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.

Ryvo currently uses two signed message types:
  1. ryvo-cmt-v5 - unilateral cumulative commitment for one payment channel.
  2. Ryvo-round - cooperative clearing-round message body used by BLS-authenticated clearing rounds.
Commitment signatures are verified through Ed25519 pre-instructions. Cooperative rounds are verified through aggregate BLS signatures over one shared round body.

​
Common encoding rules

Every signed message begins with:
  1. A one-byte kind.
  2. A one-byte version.
  3. A 16-byte message_domain.

​
Message domain

message_domain is derived inside the program as: 
message_domain = SHA256(
    "ryvo-message-domain-v1"
    || program_id
    || chain_id (little-endian u16)
)[..16]
This binds every signed message to both the program deployment and the chain ID it runs on. A commitment signed for one deployment will not verify on another, even if the payer, payee, channel, and amount are all identical. See Deployment for the live program ID and chain ID.

​
Compact unsigned integers

Participant IDs and cumulative amounts use compact unsigned integer encoding in the signed body (seven data bits per byte, continuation bit in the MSB). Reference implementations typically call this helper encodeCompactU64.

​
Token ID

token_id is encoded as a little-endian u16 in both message types.

​
ryvo-cmt-v5

The unilateral cumulative commitment message. Used by:
  • settle_individual
  • settle_commitment_bundle

​
Layout

FieldTypeMeaning
kindu8 = 0x01Unilateral commitment message
versionu8 = 0x05Current unilateral wire format
message_domain[u8; 16]Deployment-scoped replay boundary
flagsu8Optional-field presence bits
payer_idcompact u64Channel payer participant ID
payee_idcompact u64Channel payee participant ID
token_idu16 (LE)Allowlisted settlement token
committed_amountcompact u64New cumulative target for the channel

​
Semantics

  • committed_amount is cumulative, not incremental. If the channel is already settled to 1_000_000 and the new message says 1_250_000, the on-chain delta is 250_000.
  • Operator or coordinator compensation is not embedded in ryvo-cmt-v5. If a flow needs to pay an operator, that payment is expressed as its own ordinary channel commitment.

​
Ryvo-round

The cooperative clearing-round message. Used by settle_clearing_round.

​
Layout

FieldTypeMeaning
kindu8 = 0x02Clearing-round message
versionu8 = 0x05Current clearing-round wire format
message_domain[u8; 16]Deployment-scoped replay boundary
token_idu16 (LE)Token shared by the entire round
participant_countu8Number of signed participants in the roster
per participant block:
participant_idcompact u64Participant who owns this block
entry_countu8Number of outgoing channel targets in this block
per entry:
payee_refu8Index of the payee inside the signed roster
target_cumulativecompact u64New cumulative target for that channel

​
Semantics

The round is organized by payer block. Each block says:
  1. Which participant is the payer.
  2. How many outgoing channel targets that payer is advancing.
  3. For each target, which signed participant in the roster is the payee.
  4. What the new cumulative amount for that channel should be.
Reusing the roster through payee_ref keeps the signed body compact, payee IDs are referenced, not repeated. Participants register BLS keys and co-sign the same logical round body off-chain. Settlement submits one aggregate BLS signature and the program advances every included channel target in one transaction. See Clearing rounds for a worked example and the settlement semantics.

​
Which message to use

  • Use ryvo-cmt-v5 when one payer is updating one channel. This includes bundled settlement, which batches many ryvo-cmt-v5 messages for one payee into one transaction.
  • Use Ryvo-round when several participants are willing to sign one shared message so many channels can be advanced in one on-chain transaction.

​
See also