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.

In Ryvo, a payment channel is one directional payment relationship from a payer to a payee for a specific token. In V5, channel state is stored in channel buckets. Each participant pair and token maps to a canonical lane inside a deterministic bucket.

​
Why one-way

Ryvo channels are intentionally unidirectional because the common case is unidirectional:
  • one buyer paying one API
  • one agent paying one tool
  • one service paying one provider
The payer signs a unilateral cumulative message; the payee does not need to co-sign every off-chain update. When a relationship needs to send value in both directions, the two parties open two channels, one in each direction, and can later settle both together in a cooperative round.

​
What a lane stores

FieldMeaning
settled_cumulativeHighest cumulative amount already settled
locked_balanceFunds reserved for this channel
authorized_signerKey allowed to sign unilateral payment updates
pending_unlock_amount + unlock_requested_atTimelocked unlock request
pending_authorized_signer + authorized_signer_update_requested_atTimelocked signer rotation request
Crucially, the channel does not store the latest signed message. That stays off-chain until settlement.

​
Creating a channel

The payer creates the channel and pays the account rent. The payee may also need to sign, depending on its inbound channel policy. 
await program.methods
  .createChannel(tokenId, null)
  .accounts({
    tokenRegistry,
    owner: payer.publicKey,
    payerAccount,
    payeeAccount,
    payeeOwner: payee.publicKey,
    channelState,
    systemProgram: SystemProgram.programId,
  } as any)
  .signers([payer, payee])
  .rpc();
If the payer passes null for authorized_signer, the protocol uses the payer wallet as the signing key by default.

​
Locked funds

Locked funds are optional. Use them when the payee wants guaranteed payment capacity on the channel. If funds are locked, settlement spends locked balance first and shared participant balance second. Unlocking is intentionally delayed:
  1. The payer requests an unlock (request_unlock_channel_funds).
  2. The protocol waits through the configured timelock.
  3. The payer executes the unlock (execute_unlock_channel_funds) and receives the remaining locked amount back into available_balance.
The timelock gives the payee time to settle recent commitments before the locked funds are released.

​
Channel signing key

Each channel has one signing key for unilateral commitments. By default that is the payer wallet, but the payer can choose a different key at creation time or rotate it later.
authorized_signer signs new cumulative payment amounts. It is the only signing key role on unilateral commitments.
Rotations are timelocked:
  1. request_update_channel_authorized_signer
  2. Wait through the timelock.
  3. execute_update_channel_authorized_signer
Until the rotation executes, the old signing key stays active. After it executes, only the new signing key can sign new commitments for that channel.

​
Why channels are permanent

Older designs allowed channels to close and reopen. The current protocol removed that behavior. Permanent channels make the protocol easier to work with:
  1. There is no close-and-reopen replay boundary.
  2. Payment channels stay stable for off-chain services.
  3. The protocol has fewer lifecycle rules to handle.
The tradeoff is more long-lived on-chain state. The protocol accepts that tradeoff because the simpler semantics are worth it for machine-payment integrations.

​
See also