Skip to main content

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.

Cooperative clearing rounds are the densest settlement path in Ryvo. Instead of each channel settling independently, a group of participants signs one shared round message. That round advances many channel targets at once and settles all included lanes in one transaction.

​
Worked example

Suppose Alice owes Bob, Bob owes Carol, and Carol owes Alice, all in the same token. If every channel settles independently, each lane needs its own settlement transaction. If all three sign one clearing round, the protocol can:
  1. Move each channel’s settled_cumulative forward.
  2. Consume lane-specific locked balances first.
  3. Apply participant-bucket balance deltas after all lane updates are known.
With concrete numbers, A -> B = 50, B -> C = 10, C -> A = 10, Ryvo advances every included channel to its new cumulative target in one transaction. The key invariant is not “skip channel advancement through netting.” The key invariant is “every included cumulative channel target moves forward exactly as signed.” This matters because channels are cumulative. Partial advancement of a signed target would leave replay surface for later settlement. Clearing rounds avoid that by advancing each included lane to its full signed target.

​
What is signed

The clearing-round body signs:
  1. the deployment message_domain
  2. one shared token_id
  3. the participant roster
  4. each participant block’s outgoing channel targets
Each block names the payer by participant_id. Each entry inside the block points to the payee by payee_ref, which is an index into the signed roster. Reusing the roster by index is what keeps cooperative rounds byte-efficient. For the exact byte layout, see Message formats.

​
What the program verifies

When settle_clearing_round runs, the program checks:
  1. The round message is present and self-contained.
  2. The aggregate BLS signature verifies against the exact same round message.
  3. The signer roster matches registered participant BLS keys.
  4. Each participant account is the canonical PDA for the participant block it represents.
  5. Each channel lane account is canonical for the payer, payee, and token.
  6. Every target cumulative amount moves forward.
  7. Every participant with a negative final position has enough balance to cover it.
Only after all these checks pass does the program write the new lane states and apply participant balance deltas.

​
What changes on-chain

A clearing round updates two kinds of state:

​
Channel state

Every included lane gets a new settled_cumulative. If that lane has locked balance, the round consumes that first.

​
Participant balances

After all lane deltas are known, the program applies participant-bucket token balance deltas in the same transaction. A ClearingRoundSettled event summarizes round totals, including gross and adjusted balance-flow fields.

​
Example round construction

const message = createClearingRoundMessage({
  tokenId: 1,
  blocks: [
    {
      participantId: aToB.channel.payerId,
      entries: [{ payeeRef: 1, targetCumulative: nextA }],
    },
    {
      participantId: bToC.channel.payerId,
      entries: [{ payeeRef: 2, targetCumulative: nextB }],
    },
    {
      participantId: cToA.channel.payerId,
      entries: [{ payeeRef: 0, targetCumulative: nextC }],
    },
  ],
});
Each roster participant signs the same round body off-chain. Settlement submits that body plus one aggregate BLS signature.

​
When to use this path

Choose cooperative clearing when:
  • Several participants are already coordinating and willing to co-sign one shared round.
  • You want to advance many channels in one transaction while preserving cumulative-lane correctness.
  • The participants are willing to block briefly on round construction in exchange for denser settlement.
V5 integrates BLS aggregation for this path. Recent observed rounds include 20 participants advancing 84 channels and 32 participants advancing 32 channels.

​
See also