Protocol Overview

Documentation Index

Fetch the complete documentation index at: https://docs.ryvo.network/llms.txt

Use this file to discover all available pages before exploring further.

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