Build

TypeScript SDK

The SDK in sdk/src is what the plugin and tests use: program clients and addresses, the allowance math, money parsing, receipts and proofs that match the programs byte for byte, the settlement chain and CPI events.

Not published to npm yet. Import from sdk/src in this repository. It builds on @coral-xyz/anchor 0.32, @solana/web3.js 1.x and @solana/spl-token.

Example: verify a payment

The "verified checkmark" for a paid tool call: read the payment's Spent event, find its receipt in the published batch, and check the proof on chain.

import { BN } from "@coral-xyz/anchor";
import { allowanceProgram, receiptsProgram, cpiEventsOf, batchFromFile, proveReceipt } from "./sdk/src";

const spent = (await cpiEventsOf(connection, allowanceProgram(provider), paymentSignature))
  .find((e) => e.name.toLowerCase() === "spent");
const memo = Buffer.from(spent.data.memo);              // = the payment receipt's leaf

const batch = batchFromFile(batchFile);                  // rejects a file that doesn't match its root
const index = batch.leaves.findIndex((leaf) => leaf.equals(memo));
const proof = proveReceipt(batch, batchFile.batchIndex, index);

await receiptsProgram(provider).methods
  .verifyReceipt(new BN(proof.batchIndex), [...memo], index, proof.proof.map((p) => [...p]))
  .accountsPartial({ log: receiptLogAddress })
  .simulate();                                            // free; throws InvalidProof if forged

Programs and addresses

ExportDescription
ALLOWANCE_PROGRAM_ID, RECEIPTS_PROGRAM_ID, SETTLEMENT_PROGRAM_IDProgram ids from the bundled IDLs
allowanceProgram(provider, id?), receiptsProgram(…), settlementProgram(…)Typed Anchor clients
agentIdFor(runtimeAgentId)The 32-byte agent_id: sha256("neuron:" + id)
allowancePda(owner, agentId)["allowance", owner, agent_id]
payeePda(allowance, payee), requestPda(allowance, id)Allowlist entry and spend request addresses
vaultAddress(mint, allowance)The allowance's vault (its ATA)
receiptLogPda(owner, agentId)["receipts", owner, agent_id]
rollupStatePda(chainId)["rollup", chain_id u64 LE]

Allowance math and money

ExportDescription
remainingAllowance(a, nowSec)What the assistant can still spend now. Mirrors the program's period roll; the program stays authoritative.
periodLabel(seconds)"this week's", "today's", … for messages
toBaseUnits("0.02", 6)Exact decimal string to base units (bigint); rejects extra precision
formatAmount(20000n, 6)"$0.02", with no floating point

Receipts and proofs

ExportDescription
ModelCallReceipt, ToolCallReceipt, PaymentReceiptReceipt shapes (version 1)
canonicalJson(value)Deterministic JSON (sorted keys, no whitespace; RFC 8785 for plain data)
saltedHashJson(salt, value), newSalt()Private commitment: HMAC-SHA256 keyed by a random per-receipt salt
hashJson(value)Plain sha256 of canonical JSON, for public values
receiptLeaf(receipt)sha256(0x00 ‖ canonicalJson(receipt))
buildBatch(receipts)Leaves, root, time range, dataHash and the exact file bytes
merkleRoot, merkleProof, verifyMerkleProofTree helpers; odd nodes are promoted, as in the program
proveReceipt(batch, batchIndex, i), checkReceiptProof(p)Everything needed to check one receipt
publishableBatch(file), batchFromFile(file)The bytes to publish (sha256 = data_hash), and rebuilding a batch from a file
nextChain, replayChain(batches, genesis), receiptsGenesisChain(…)The receipt log's hash chain, from its genesis value

Settlement

ExportDescription
nextSettlementChain(prev, checkpoint)Fold one checkpoint into the chain
rewindSettlementChain(prev, checkpoint)Fold an admin rewind into the chain
replaySettlementChain(records)Replay CheckpointPosted and Rewound ({ rewind: true }) events; must equal RollupState.chain

Events

cpiEventsOf(connection, program, signature) decodes events a program emitted with Anchor's emit_cpi!, from the transaction's inner instructions. neuron_allowance uses CPI events because logs are capped per transaction and could be padded to hide a spend. Only successful transactions and inner instructions addressed to the program itself are read.