> ## 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.

# Message Formats

> The exact signed message formats used by the current Ryvo protocol.

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](/reference/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

| Field              | Type          | Meaning                               |
| ------------------ | ------------- | ------------------------------------- |
| `kind`             | `u8` = `0x01` | Unilateral commitment message         |
| `version`          | `u8` = `0x05` | Current unilateral wire format        |
| `message_domain`   | `[u8; 16]`    | Deployment-scoped replay boundary     |
| `flags`            | `u8`          | Optional-field presence bits          |
| `payer_id`         | compact `u64` | Channel payer participant ID          |
| `payee_id`         | compact `u64` | Channel payee participant ID          |
| `token_id`         | `u16` (LE)    | Allowlisted settlement token          |
| `committed_amount` | compact `u64` | New 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

| Field                    | Type          | Meaning                                          |
| ------------------------ | ------------- | ------------------------------------------------ |
| `kind`                   | `u8` = `0x02` | Clearing-round message                           |
| `version`                | `u8` = `0x05` | Current clearing-round wire format               |
| `message_domain`         | `[u8; 16]`    | Deployment-scoped replay boundary                |
| `token_id`               | `u16` (LE)    | Token shared by the entire round                 |
| `participant_count`      | `u8`          | Number of signed participants in the roster      |
| *per participant block:* |               |                                                  |
| `participant_id`         | compact `u64` | Participant who owns this block                  |
| `entry_count`            | `u8`          | Number of outgoing channel targets in this block |
| *per entry:*             |               |                                                  |
| `payee_ref`              | `u8`          | Index of the payee inside the signed roster      |
| `target_cumulative`      | compact `u64` | New 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](/settlement-modes/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

* [Direct settlement](/settlement-modes/direct-settlement)
* [Bundle settlement](/settlement-modes/bundle-settlement)
* [Clearing rounds](/settlement-modes/clearing-rounds)
* [Commitments](/core-concepts/commitments)