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
| Export | Description |
|---|---|
ALLOWANCE_PROGRAM_ID, RECEIPTS_PROGRAM_ID, SETTLEMENT_PROGRAM_ID | Program 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
| Export | Description |
|---|---|
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
| Export | Description |
|---|---|
ModelCallReceipt, ToolCallReceipt, PaymentReceipt | Receipt 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, verifyMerkleProof | Tree 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
| Export | Description |
|---|---|
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.