Protocol Overview

Ryvo decouples payment execution from settlement. Participants make many payments first through signed cumulative commitments, and settle them later on-chain. Each wallet registers once as a participant and keeps the same participant_id for the life of the deployment. Participants deposit allowlisted tokens into protocol balances. When one participant pays another, they create one permanent one-way payment channel for that token. The payer may optionally lock funds to that channel if the relationship needs guaranteed payment capacity.

​

On-chain objects

The current architecture uses global singletons plus bucketed participant and channel state: Full field-level layouts are on the Account layouts reference.

​

Signed messages

Ryvo uses two signed message formats:

• ryvo-cmt-v5 - the unilateral cumulative commitment for one channel
• Ryvo-round - the cooperative clearing-round body for several participants

Both messages embed the deployment-scoped message_domain, so a signature for one environment does not verify on another. Full byte-level layouts are on the Message formats reference.

​

Settlement paths

Those two messages feed three settlement instructions: All three settle into the same shared vault and the same participant balances.

​

End-to-end flow

In the common case, an integration goes through these steps:

1. Register the payer and payee as participants.
2. Deposit an allowlisted token.
3. Create a one-way payment channel.
4. Optionally lock funds to that channel for guaranteed capacity.
5. Sign cumulative commitments off-chain as usage grows.
6. Settle the newest valid state later.

Your first payment walks through each step with working code.

​

What stays off-chain

Ryvo keeps signed payment updates off-chain until settlement. Most integrations store:

• the latest signed ryvo-cmt-v5 per channel
• usage or metering state
• bundle assembly logic
• cooperative round construction logic

Only the newest valid state needs to reach the chain.

​

Why Ryvo uses permanent identities and persistent lanes

Ryvo intentionally uses stable identities and permanent channels. The tradeoff is more long-lived on-chain state, but the protocol becomes much easier to work with:

• participant_id values do not recycle.
• Off-chain services can index users without worrying about identity reuse.
• Channels do not close and reopen, so there is no reopened-channel replay surface.
• Replay protection is simpler.
• Payment channels stay stable for clients and operators.

For the rationale, see Design principles.

​

Choosing a settlement mode

• Use direct settlement when one payer and one payee need the smallest possible surface and each lane can settle on its own.
• Use bundle settlement when one payee collects signed commitments from many payers in the same token and wants one transaction instead of many.
• Use cooperative clearing when several parties are willing to co-sign one shared round so many lanes can be advanced in one transaction.

See Settlement modes for the tradeoffs side by side.

​

Current deployment

See Deployment for environment-specific chain IDs and timelocks.

​

Where to go next