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.

@ryvonetwork/sdk is the official TypeScript SDK for the Ryvo Protocol. It wraps the live Anchor program into a small set of typed helpers so you can integrate the protocol without hand-rolling IDLs, PDAs, or message encoders. The SDK is developed in the open at Ryvonetwork/ryvo-protocol-sdk.

​
What is inside

The package exposes five composable layers:
LayerWhat it gives you
RyvoClientA thin, typed wrapper around the Anchor program with one method per instruction.
PDA helpersDeterministic derivations for every account the program uses (global-config, token-registry, participant, vault-token-account, channel-v2).
Message buildersryvo-cmt-v5 commitment and clearing-round message encoders, plus signing helpers.
Account helpersConvenience readers for participant token balances and for computing the next commitment amount from a channel.
Constants & IDLRYVO_PROTOCOL_PROGRAM_ID, RYVO_CHAIN_IDS, seed strings, and the generated Anchor IDL.
The SDK depends on @coral-xyz/anchor, @solana/web3.js, and @noble/curves, all standard in the Solana TypeScript ecosystem. It has no hidden RPC behavior: every call you make goes through the AnchorProvider you construct it with.

​
Install

npm install @ryvonetwork/sdk @coral-xyz/anchor @solana/web3.js
Requirements:
  • Node.js >= 18
  • An Anchor-compatible AnchorProvider (browser wallet adapter, backend keypair, test ledger, etc.)
The package is ESM-only ("type": "module"). In CommonJS codebases, use a dynamic import() or switch to ESM.

​
Quick start

import * as anchor from "@coral-xyz/anchor";
import { RyvoClient } from "@ryvonetwork/sdk";

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

const client = new RyvoClient({ provider });

const owner = provider.wallet.publicKey;
const participantPda = client.participantAddress(owner);
const participant = await client.fetchParticipant(owner);

console.log("Participant ID:", participant.participantId);
By default, RyvoClient uses the live program ID baked into the IDL (3UyUFeNsUYPpM6hMRf7H8wg3MKEXQ82rqnsXhZrUwgSD on devnet). To target a different deployment, pass a programId override: 
import { PublicKey } from "@solana/web3.js";

const client = new RyvoClient({
  provider,
  programId: new PublicKey("<your program id>"),
});

​
Sign a commitment and settle

The following snippet is the full direct-settlement flow, compressed. See Recipes for the expanded version with participant setup, deposits, and channel creation. 
import {
  RyvoClient,
  createCommitmentMessage,
  createEd25519Instruction,
  deriveMessageDomain,
  RYVO_CHAIN_IDS,
} from "@ryvonetwork/sdk";

const client = new RyvoClient({ provider });
const messageDomain = deriveMessageDomain(client.programId, RYVO_CHAIN_IDS.devnet);

const message = createCommitmentMessage({
  messageDomain,
  payerId: payer.participantId,
  payeeId: payee.participantId,
  tokenId: 2,
  committedAmount: 1_000_000n, // micro-USDC
});

const ed25519Ix = createEd25519Instruction(payerKeypair, message);

await client
  .settleIndividual({
    payerAccount: client.participantAddress(payerKeypair.publicKey),
    payeeAccount: client.participantAddress(payeeKeypair.publicKey),
    channelState: client.channelAddress(
      payer.participantId,
      payee.participantId,
      2,
    ),
    submitter: payeeKeypair.publicKey,
  })
  .preInstructions([ed25519Ix])
  .signers([payeeKeypair])
  .rpc();
Two things are worth noting:
  1. The commitment is signed off-chain by the payer. The payee is the one who submits it on-chain.
  2. createEd25519Instruction must be added to the same transaction as settleIndividual; Ryvo verifies it through the instructions sysvar.

​
Versioning

The SDK is on the 0.2.x line while the protocol surface stabilises. Breaking changes are signalled in the npm changelog and tracked against the program’s IDL. The package ships the generated IDL and TypeScript program type, so upgrading the SDK is always aligned with a protocol upgrade.

​
Agentic tooling

If you are building agent workflows, pair the SDK with the agentic toolchain:
  • protocol CLI for state inspection and unsigned action prep
  • protocol MCP for tool-calling integrations
  • gateway CLI and MCP for route discovery and payment flows
  • reusable skills for Codex-style agent workflows
See Agentic tools for package names, defaults, and workflow guidance.

​
Where to go next

RyvoClient

Every instruction the SDK can build, initialize, deposit, lock, settle, withdraw.

PDAs & constants

Derive every account the program uses, deterministically and off-chain.

Messages

Build ryvo-cmt-v5 and cooperative-round messages.

Recipes

End-to-end flows: register, fund, sign, settle, withdraw.

Agentic tools

Protocol CLI, MCP, skills, and LLM text built on the SDK.