sdk

@covenant-org/sdk

TypeScript SDK for the Covenant protocol on Solana. A high-level client that derives PDAs, signs, sends, and reads decoded on-chain state, plus the lower-level instruction builders (agent registration, $CVNT staking, task escrow, credit purchase, receipt anchoring), PDA derivation, account decoding, and Node + browser (wallet-adapter) signing.

Install

npm add @covenant-org/sdk @solana/web3.js

@solana/web3.js (v1) is a peer dependency, so bring your own version.

Quick start

CovenantClient is the high-level path. It derives every PDA, fills the signer as the operator, owner, or client account, resolves the $CVNT mint from the on-chain config, and runs each call build, sign, send, confirm. Reads decode on-chain state and need no signer.

import { Connection, Keypair } from '@solana/web3.js';
import { CovenantClient, keypairSigner, hash32FromText } from '@covenant-org/sdk';

const client = new CovenantClient({
  connection: new Connection('https://api.mainnet-beta.solana.com', 'confirmed'),
  signer: keypairSigner(operatorKeypair),
});

// read decoded on-chain state (no signer required)
const config = await client.getConfig();
const agent = await client.getAgent(hash32FromText('my-agent'));

// register: derives the config + agent PDAs, signs, sends, confirms, returns the signature
const signature = await client.registerAgent({
  agentKey: hash32FromText('my-agent'),
  metadataHash: hash32FromText('https://example.com/agents/my-agent.json'),
  capabilityHash: hash32FromText('research,settlement'),
});

In the browser, hand the client a wallet-adapter wallet instead of a keypair:

import { walletAdapterSigner } from '@covenant-org/sdk';
const client = new CovenantClient({ connection, signer: walletAdapterSigner(wallet) });

Deriving addresses

Each PDA has a derive*Pda helper that bakes in the program id and returns { address: PublicKey, bump }:

import { deriveConfigPda, deriveAgentPda, deriveAssociatedTokenAddress } from '@covenant-org/sdk';

const { address: config } = deriveConfigPda();
const { address: agent } = deriveAgentPda(hash32FromText('my-agent'));
const ata = deriveAssociatedTokenAddress(owner, covntMint); // token account for owner + mint

The client derives these internally; you only reach for them with the low-level builders, whose account fields are base58 strings, so unwrap a PDA with .address.toBase58().

Low-level instruction builders

Each prepare*Instruction returns a wallet-agnostic descriptor; toTransactionInstructions turns it into signable TransactionInstructions (an 8-byte Anchor discriminator plus Borsh-encoded args from the on-chain IDLs).

import { Connection, Keypair, Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
import {
  deriveAgentPda,
  deriveConfigPda,
  hash32FromText,
  prepareRegisterAgentInstruction,
  resolveSolanaNetwork,
  toTransactionInstructions,
} from '@covenant-org/sdk';

const operator = Keypair.generate();
const connection = new Connection(resolveSolanaNetwork().rpcUrl, 'confirmed');
const agentKey = hash32FromText('my-agent');

const bundle = prepareRegisterAgentInstruction({
  configAccount: deriveConfigPda().address.toBase58(),
  agentAccount: deriveAgentPda(agentKey).address.toBase58(),
  operator: operator.publicKey.toBase58(),
  agentKey,
  metadataHash: hash32FromText('https://example.com/agents/my-agent.json'),
  capabilityHash: hash32FromText('research,settlement'),
});

const tx = new Transaction().add(...toTransactionInstructions(bundle));
await sendAndConfirmTransaction(connection, tx, [operator]);

fetchAgent, fetchConfig, fetchTask, and the decode* functions read and decode state directly, without a client.

Token accounts and the CVNT mint

stake, buy_credits, create_task, and release_task move $CVNT, so each needs the mint and the owner's token account. Derive the token account with deriveAssociatedTokenAddress, and read the mint from the on-chain config (or set the COVNT_MINT env var, since resolveSolanaNetwork().covntMint is null until you do):

import {
  deriveAgentPda,
  deriveAssociatedTokenAddress,
  deriveConfigPda,
  deriveStakePositionPda,
  fetchConfig,
  hash32FromText,
  prepareStakeInstruction,
  toTransactionInstructions,
} from '@covenant-org/sdk';

const owner = operator.publicKey;
const agentKey = hash32FromText('my-agent');
const { covntMint } = (await fetchConfig(connection, deriveConfigPda().address))!;

const bundle = prepareStakeInstruction({
  configAccount: deriveConfigPda().address.toBase58(),
  agentAccount: deriveAgentPda(agentKey).address.toBase58(),
  positionAccount: deriveStakePositionPda(agentKey, owner).address.toBase58(),
  owner: owner.toBase58(),
  ownerCovntAccount: deriveAssociatedTokenAddress(owner, covntMint).toBase58(),
  stakeVault: STAKE_VAULT,
  covntMint,
  amountCovnt: '1000000000',
  lockUntil: String(Math.floor(Date.now() / 1000) + 30 * 86400),
});
const [ix] = toTransactionInstructions(bundle);

stakeVault is the program's $CVNT vault, a deployment address you configure once. CovenantClient takes the same token accounts if you prefer the high-level path.

Configuration

resolveSolanaNetwork(overrides?) resolves the cluster, RPC/WS URLs, protocol program id, and mint. Pass overrides directly, or set environment variables (a NEXT_PUBLIC_-prefixed form is read for browser builds):

Setting	Override	Env
Cluster (devnet default)	{ cluster: 'mainnet' }	COVENANT_SOLANA_CLUSTER
RPC URL	{ rpcUrl }	COVENANT_SOLANA_RPC_URL
Protocol program id	{ programId }	COVENANT_PROTOCOL_PROGRAM_ID
CVNT mint	{ covntMint }	COVNT_MINT

const mainnet = resolveSolanaNetwork({ cluster: 'mainnet' });

Surface

Area	Exports
Client	CovenantClient
Signers	keypairSigner, walletAdapterSigner
PDA derivation	deriveConfigPda, deriveAgentPda, deriveTaskPda, deriveCreditsPda, deriveStakePositionPda, deriveReceiptBatchPda, deriveAssociatedTokenAddress, the stake-program derive*Pda, SETTLEMENT_PROGRAM_ID, STAKE_PROGRAM_ID
Account reads	fetchConfig, fetchAgent, fetchTask, fetchCreditAccount, fetchStakePosition, fetchReceiptBatch, and the matching decode*
Settlement instructions	prepareRegisterAgentInstruction, prepareStakeInstruction, prepareBuyCreditsInstruction, prepareCreateTaskInstruction, prepareReleaseTaskInstruction, prepareAnchorReceiptBatchInstruction
Stake-program instructions	prepareStakeInitializeInstruction, prepareStakeCreatePositionInstruction, prepareStakeIncreaseAmountInstruction, prepareStakeClaimInstruction, prepareStakeClosePositionInstruction, plus the fee-router, pause, and authority admin builders
Transactions and serialization	buildTransaction, sendAndConfirmSignedTransaction, toTransactionInstruction, toTransactionInstructions
Addresses and hashing	isSolanaAddress, assertSolanaAddress, assertHash32, hash32FromText, toBase58, toPublicKey, ACCOUNT_SEEDS
Network	resolveSolanaNetwork, solanaExplorerHref
Tasks	TASK_STATUS_VALUES (TaskStatus, DiscoveryEventRecord, and DiscoveryStats are TypeScript types only)

Everything imports from the package root. Instruction data is encoded from the program IDLs (settlement cov9UDyp..., stake CstkpU2q...), so the wire bytes cannot drift from what the on-chain program accepts.

Stability

0.2.0, alpha. compatibility/exports.v1.json and compatibility/instructions.v1.json pin the exported surface and each instruction's account order and data keys against accidental drift. Semver support windows are not yet guaranteed, so pin an exact version.

License

Apache-2.0.