Skip to main content
Agon currently uses two signed message types:
  1. agon-cmt-v5 — unilateral cumulative commitment for one payment channel.
  2. agon-round-v4 — cooperative clearing-round message signed by multiple participants.
Both are verified on-chain by the Ed25519 native program. The protocol inspects the preceding Ed25519 instruction and cross-checks the signed bytes against the data passed to settle_individual, settle_commitment_bundle, or settle_clearing_round.

​
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(
    "agon-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.

​
agon-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
authorized_settlerPubkeyOptional delegated submitter (present iff flag bit set)

​
Flags

BitMeaning
0x01authorized_settler field is present

​
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.
  • If the flag bit is set, the appended authorized_settler key is the only non-payee address allowed to submit this commitment on-chain.
  • Operator or coordinator compensation is not embedded in agon-cmt-v5. If a flow needs to pay an operator, that payment is expressed as its own ordinary channel commitment.

​
agon-round-v4

The cooperative clearing-round message. Used by settle_clearing_round.

​
Layout

FieldTypeMeaning
kindu8 = 0x02Clearing-round message
versionu8 = 0x04V4 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. Every participant listed in the roster must provide a valid Ed25519 signature over the same body. The program verifies every signature, then applies only the net residual balance changes after the implied payments have cancelled each other out. See Clearing rounds for a worked example and the settlement semantics.

​
Which message to use

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

​
See also