Your First Payment

This guide shows the smallest useful Ryvo integration: one payer, one payee, one token, one payment channel, and one settled ryvo-cmt-v5 message. The examples below mirror the current protocol tests. They use raw Anchor calls so you can see the exact accounts and signatures involved.

If you don’t need that level of control, the official @ryvonetwork/sdk wraps every step on this page into one or two method calls. See the SDK Recipes for the same flow in a dozen lines.

What you will build

By the end of this guide, you will have:

Two registered participants.
One funded payer.
One open payment channel.
One signed unilateral commitment.
One successful direct settlement.

Prerequisites

Anchor workspace wired to the Ryvo program at 3UyUFeNsUYPpM6hMRf7H8wg3MKEXQ82rqnsXhZrUwgSD on devnet
Two keypairs with a small amount of SOL on devnet
One allowlisted settlement token. Gateway-channel v1 uses official devnet USDC, mint 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU; resolve its token_id from TokenRegistry or RYVO_PROTOCOL_DEVNET_USDC_TOKEN_ID.

1. Create the program client

import * as anchor from "@coral-xyz/anchor";
import { Program } from "@coral-xyz/anchor";
import { Ed25519Program, PublicKey, SystemProgram } from "@solana/web3.js";
import { RyvoProtocol } from "../target/types/ryvo_protocol";

const provider = anchor.AnchorProvider.env();
anchor.setProvider(provider);

const program = anchor.workspace.RyvoProtocol as Program<RyvoProtocol>;

2. Derive the PDAs

You will use deterministic PDA helpers throughout the protocol flow, so define these helpers once:

const findParticipantPda = (owner: PublicKey) =>
  PublicKey.findProgramAddressSync(
    [Buffer.from("participant"), owner.toBytes()],
    program.programId
  )[0];

const findTokenRegistryPda = () =>
  PublicKey.findProgramAddressSync(
    [Buffer.from("token-registry")],
    program.programId
  )[0];

const findVaultTokenAccountPda = (tokenId: number) =>
  PublicKey.findProgramAddressSync(
    [
      Buffer.from("vault-token-account"),
      new anchor.BN(tokenId).toArrayLike(Buffer, "le", 2),
    ],
    program.programId
  )[0];

const findChannelPda = (payerId: number, payeeId: number, tokenId: number) =>
  PublicKey.findProgramAddressSync(
    [
      Buffer.from("channel-v2"),
      new Uint8Array(new Uint32Array([payerId]).buffer),
      new Uint8Array(new Uint32Array([payeeId]).buffer),
      new Uint8Array(new Uint16Array([tokenId]).buffer),
    ],
    program.programId
  )[0];

The channel PDA seed order is payer_id (u32 LE) || payee_id (u32 LE) || token_id (u16 LE) under the channel-v2 prefix. If you derive in a different order, settle_* instructions will reject the account.

3. Register both wallets

Each wallet registers once and keeps the same participant_id for the life of the deployment.

await program.methods
  .initializeParticipant()
  .accounts({
    owner: alice.publicKey,
    feeRecipient,
  } as any)
  .signers([alice])
  .rpc();

await program.methods
  .initializeParticipant()
  .accounts({
    owner: bob.publicKey,
    feeRecipient,
  } as any)
  .signers([bob])
  .rpc();

const aliceParticipantPda = findParticipantPda(alice.publicKey);
const bobParticipantPda = findParticipantPda(bob.publicKey);

const aliceParticipant = await program.account.participantAccount.fetch(
  aliceParticipantPda
);
const bobParticipant = await program.account.participantAccount.fetch(
  bobParticipantPda
);

Read the assigned participant IDs:

console.log(aliceParticipant.participantId);
console.log(bobParticipant.participantId);

4. Deposit the settlement token

Ryvo only settles allowlisted tokens. Once the payer has a normal SPL token account, deposit from that account into the protocol vault:

await program.methods
  .deposit(tokenId, new anchor.BN(amount))
  .accounts({
    owner: alice.publicKey,
    participantAccount: aliceParticipantPda,
    ownerTokenAccount: aliceTokenAccount,
    vaultTokenAccount: findVaultTokenAccountPda(tokenId),
  } as any)
  .signers([alice])
  .rpc();

This moves tokens from the payer’s token account into the protocol vault and credits the payer’s available_balance.

5. Create the channel

One one-way payment channel exists for each payer_id + payee_id + token_id relationship. Channels are permanent.

const channelPda = findChannelPda(
  aliceParticipant.participantId,
  bobParticipant.participantId,
  tokenId
);

await program.methods
  .createChannel(tokenId, null)
  .accounts({
    tokenRegistry: findTokenRegistryPda(),
    owner: alice.publicKey,
    payerAccount: aliceParticipantPda,
    payeeAccount: bobParticipantPda,
    payeeOwner: bob.publicKey,
    channelState: channelPda,
    systemProgram: SystemProgram.programId,
  } as any)
  .signers([alice, bob])
  .rpc();

The payeeOwner signer is only required when the payee’s inbound-channel policy demands consent. Under Permissionless, channel creation does not require the payee to sign.

6. Optionally lock funds

Locked funds are optional. Use them when the payee wants guaranteed payment capacity on the channel.

await program.methods
  .lockChannelFunds(tokenId, new anchor.BN(1_000_000))
  .accounts({
    owner: alice.publicKey,
    payerAccount: aliceParticipantPda,
    payeeAccount: bobParticipantPda,
    channelState: channelPda,
  } as any)
  .signers([alice])
  .rpc();

Settlement spends locked balance first, then shared participant balance.

7. Build the `ryvo-cmt-v5` message

ryvo-cmt-v5 is cumulative. It does not say “pay 25 again.” It says “this channel is now authorized up to cumulative amount X.” The helper below matches the real test suite:

function encodeCompactU64(value: bigint): number[] {
  const bytes: number[] = [];
  let remaining = value;
  do {
    let byte = Number(remaining & 0x7fn);
    remaining >>= 7n;
    if (remaining > 0n) byte |= 0x80;
    bytes.push(byte);
  } while (remaining > 0n);
  return bytes;
}

function createCommitmentMessage(params: {
  payerId: number;
  payeeId: number;
  tokenId: number;
  committedAmount: anchor.BN;
  messageDomain: Buffer;
  // no delegated submitter field
}): Buffer {
  const flags = 0;

  const bodyParts = [
    Buffer.from(encodeCompactU64(BigInt(params.payerId))),
    Buffer.from(encodeCompactU64(BigInt(params.payeeId))),
    new anchor.BN(params.tokenId).toArrayLike(Buffer, "le", 2),
    Buffer.from(encodeCompactU64(BigInt(params.committedAmount.toString()))),
  ];

  return Buffer.concat([
    Buffer.from([0x01, 0x05]),
    params.messageDomain,
    Buffer.from([flags]),
    ...bodyParts,
  ]);
}

Build the first commitment:

const channel = await program.account.channelState.fetch(channelPda);

const delta = new anchor.BN(250_000);
const committedAmount = channel.settledCumulative.add(delta);

const message = createCommitmentMessage({
  payerId: channel.payerId,
  payeeId: channel.payeeId,
  tokenId,
  committedAmount,
  messageDomain,
});

8. Add the Ed25519 verification instruction

Ryvo expects the signed message to be verified by Solana’s Ed25519 program inside the same transaction:

const ed25519Ix = Ed25519Program.createInstructionWithPrivateKey({
  privateKey: alice.secretKey,
  message,
});

The signer above must match the channel’s current authorized_signer. This key signs new cumulative payment amounts for that channel. By default it is the payer wallet that created the channel; if the channel uses a different signing key, that key must sign here instead.

authorized_signer signs the payment update. Settlement submitter logic stays outside the signed commitment body.

9. Submit `settle_individual`

The payee submits the settlement transaction:

await program.methods
  .settleIndividual()
  .accounts({
    channelState: channelPda,
    payerAccount: aliceParticipantPda,
    payeeAccount: bobParticipantPda,
    submitter: bob.publicKey,
  } as any)
  .preInstructions([ed25519Ix])
  .signers([bob])
  .rpc();

The program verifies the Ed25519 instruction, parses the message, checks the message_domain, validates the canonical payer / payee / token / channel, then moves the delta between the old and new cumulative amounts.

10. Read the result

After settlement:

channel.settled_cumulative has advanced.
The payer balance has decreased by the delta.
The payee balance has increased by the same amount.
Any locked funds used by the settlement have been consumed first.

If an operator also needs to be paid, model that as a separate channel payment rather than as a fee field inside this message. See Operator payment. That is the full direct settlement flow.

Where to go next

Bundle settlement

Settle many payers’ commitments for one payee in a single transaction.

Cooperative clearing

Compress many payments across many participants into one round.

Message formats

The exact byte layout of ryvo-cmt-v5 and cooperative round messages.

Introduction

Getting Started

Core Concepts

Settlement

Security

Benchmarks

Comparisons

Examples

SDK

Reference

What you will build

Prerequisites

1. Create the program client

2. Derive the PDAs

3. Register both wallets

4. Deposit the settlement token

5. Create the channel

6. Optionally lock funds

7. Build the `ryvo-cmt-v5` message

8. Add the Ed25519 verification instruction

9. Submit `settle_individual`

10. Read the result

Where to go next

Bundle settlement

Cooperative clearing

Message formats

​What you will build

​Prerequisites

​1. Create the program client

​2. Derive the PDAs

​3. Register both wallets

​4. Deposit the settlement token

​5. Create the channel

​6. Optionally lock funds

​7. Build the ryvo-cmt-v5 message

​8. Add the Ed25519 verification instruction

​9. Submit settle_individual

​10. Read the result

​Where to go next

Bundle settlement

Cooperative clearing

Message formats

What you will build

Prerequisites

1. Create the program client

2. Derive the PDAs

3. Register both wallets

4. Deposit the settlement token

5. Create the channel

6. Optionally lock funds

7. Build the `ryvo-cmt-v5` message

8. Add the Ed25519 verification instruction

9. Submit `settle_individual`

10. Read the result

Where to go next