@bondedhq/sdk 0.0.0-stage → 0.1.1

package/dist/solana-agent-kit.js

@@ -0,0 +1,333 @@
+import { breachEventsFromLogs, executeInstruction, fetchVault, TOKEN_PROGRAM, vaultError, } from "@bondedhq/solana";
+import { PublicKey, SystemProgram, TransactionInstruction, TransactionMessage, VersionedTransaction, } from "@solana/web3.js";
+import { z } from "zod/v3";
+import { BondedError } from "./errors.js";
+/** An error from the Solana vault, with the breach when the vault recorded one. */
+export class SolanaVaultError extends BondedError {
+    breach;
+    signature;
+    name = "SolanaVaultError";
+    constructor(code, message, breach, signature, options) {
+        super(code, message, options);
+        this.breach = breach;
+        this.signature = signature;
+    }
+}
+/** Solana Agent Kit validates with zod 3; `zod/v3` is that API, typed at this boundary. */
+const schema = (shape) => z.object(shape);
+/** Reads and confirmations use "confirmed": a vault's state must be current to judge an action. */
+const COMMITMENT = "confirmed";
+const ATA_PROGRAM = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+const MINT_DECIMALS_OFFSET = 44;
+/** The associated token account of `owner` for `mint` (the vault, a PDA, included). */
+export function associatedTokenAddress(owner, mint) {
+    return PublicKey.findProgramAddressSync([owner.toBuffer(), TOKEN_PROGRAM.toBuffer(), mint.toBuffer()], ATA_PROGRAM)[0];
+}
+/**
+ * A Bonded vault on Solana, from the agent's side. Every action is the vault program's
+ * `execute`, signed by the agent key.
+ */
+export class SolanaBondedVault {
+    connection;
+    agent;
+    address;
+    constructor(connection, vault, agent) {
+        this.connection = connection;
+        this.agent = agent;
+        this.address = new PublicKey(vault);
+    }
+    async status() {
+        const vault = await fetchVault(this.connection, this.address, COMMITMENT);
+        if (!vault)
+            throw new BondedError("NOT_FOUND", `no Bonded vault at ${this.address.toBase58()}`);
+        return vault;
+    }
+    /**
+     * Send `amount` (base units) of `mint` from the vault to `to`'s associated token account,
+     * creating it (paid by the agent key) if it doesn't exist. Only a transfer to the vault's own
+     * account keeps to the mandate on Solana.
+     */
+    async transfer(params) {
+        const plan = await this.transferPlan(params);
+        return this.execute(plan.instruction, plan.setup);
+    }
+    /** Runs `inner` through the vault's `execute`, after any `setup` the agent key runs itself. */
+    async execute(inner, setup = [], lookupTables = []) {
+        const { transaction, blockhash, lastValidBlockHeight } = await this.build(inner, setup, lookupTables);
+        const signed = await this.agent.signTransaction(transaction);
+        let signature;
+        try {
+            signature = await this.connection.sendRawTransaction(signed.serialize(), {
+                preflightCommitment: COMMITMENT,
+            });
+        }
+        catch (error) {
+            throw this.programError(error);
+        }
+        const confirmed = await this.connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, COMMITMENT);
+        if (confirmed.value.err)
+            throw this.programError(confirmed.value.err, `transaction ${signature} failed`);
+        const tx = await this.connection.getTransaction(signature, {
+            commitment: COMMITMENT,
+            maxSupportedTransactionVersion: 0,
+        });
+        const breaches = breachEventsFromLogs(tx?.meta?.logMessages ?? []);
+        const blocked = breaches.find((b) => b.blocked);
+        if (blocked)
+            throw new SolanaVaultError("BLOCKED_BY_MANDATE", `the vault blocked this action (${blocked.type}); the attempt is recorded as breach ${blocked.breachId}`, blocked, signature);
+        return { signature, breaches };
+    }
+    /** What the vault would do with `inner`: simulates `execute` against the cluster's state. */
+    async dryRun(inner, setup = [], lookupTables = []) {
+        const { transaction } = await this.build(inner, setup, lookupTables);
+        const { value } = await this.connection.simulateTransaction(transaction, {
+            sigVerify: false,
+            replaceRecentBlockhash: true,
+            commitment: COMMITMENT,
+        });
+        if (value.err)
+            throw this.programError(value.err, "the simulation failed", value.logs);
+        const breaches = breachEventsFromLogs(value.logs ?? []);
+        return {
+            ok: breaches.length === 0,
+            blocked: breaches.some((b) => b.blocked),
+            ...(breaches[0] ? { breach: breaches[0] } : {}),
+            breaches,
+        };
+    }
+    /**
+     * The SPL `TransferChecked` the vault would sign for `transfer`, and the account creation the
+     * agent key runs first if needed. Pass both to `dryRun` to preview a transfer.
+     */
+    async transferPlan(params) {
+        const vault = await this.status();
+        const source = params.mint.equals(vault.baseMint)
+            ? vault.baseAccount
+            : associatedTokenAddress(this.address, params.mint);
+        const destination = associatedTokenAddress(params.to, params.mint);
+        const setup = (await this.connection.getAccountInfo(destination, COMMITMENT))
+            ? []
+            : [createAtaIdempotent(this.agent.publicKey, destination, params.to, params.mint)];
+        const decimals = await mintDecimals(this.connection, params.mint);
+        const data = Buffer.alloc(10);
+        data.writeUInt8(12, 0); // TransferChecked
+        data.writeBigUInt64LE(params.amount, 1);
+        data.writeUInt8(decimals, 9);
+        const instruction = new TransactionInstruction({
+            programId: TOKEN_PROGRAM,
+            data,
+            keys: [
+                { pubkey: source, isSigner: false, isWritable: true },
+                { pubkey: params.mint, isSigner: false, isWritable: false },
+                { pubkey: destination, isSigner: false, isWritable: true },
+                { pubkey: this.address, isSigner: true, isWritable: false },
+            ],
+        });
+        return { instruction, setup };
+    }
+    async build(inner, setup, lookupTables) {
+        const { blockhash, lastValidBlockHeight } = await this.connection.getLatestBlockhash(COMMITMENT);
+        const execute = executeInstruction({ address: this.address, agent: this.agent.publicKey }, inner);
+        const message = new TransactionMessage({
+            payerKey: this.agent.publicKey,
+            recentBlockhash: blockhash,
+            instructions: [...setup, execute],
+        }).compileToV0Message(lookupTables);
+        return { transaction: new VersionedTransaction(message), blockhash, lastValidBlockHeight };
+    }
+    /** Names the vault program's error when the failure is one, e.g. a frozen vault. */
+    programError(error, context, logs) {
+        const code = customErrorCode(error);
+        const named = code !== undefined ? vaultError(code) : undefined;
+        if (named)
+            return new SolanaVaultError(named.name === "Frozen"
+                ? "VAULT_FROZEN"
+                : named.name === "NotAgent"
+                    ? "NOT_AGENT"
+                    : "VAULT_ERROR", named.message, undefined, undefined, { cause: error });
+        const detail = logs?.length ? `\n${logs.join("\n")}` : "";
+        const what = error instanceof Error ? error.message : JSON.stringify(error);
+        return new BondedError("CALL_REVERTED", `${context ?? "the transaction failed"}: ${what}${detail}`, {
+            cause: error,
+        });
+    }
+}
+/** The custom program error code in a transaction error, from its JSON or its message. */
+function customErrorCode(error) {
+    const json = /"Custom":(\d+)/.exec(JSON.stringify(error) ?? "");
+    if (json)
+        return Number(json[1]);
+    const message = error instanceof Error ? error.message : "";
+    const hex = /custom program error: 0x([0-9a-f]+)/i.exec(message);
+    return hex ? parseInt(hex[1], 16) : undefined;
+}
+function createAtaIdempotent(payer, ata, owner, mint) {
+    return new TransactionInstruction({
+        programId: ATA_PROGRAM,
+        data: Buffer.from([1]), // CreateIdempotent
+        keys: [
+            { pubkey: payer, isSigner: true, isWritable: true },
+            { pubkey: ata, isSigner: false, isWritable: true },
+            { pubkey: owner, isSigner: false, isWritable: false },
+            { pubkey: mint, isSigner: false, isWritable: false },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+            { pubkey: TOKEN_PROGRAM, isSigner: false, isWritable: false },
+        ],
+    });
+}
+async function mintDecimals(connection, mint) {
+    const info = await connection.getAccountInfo(mint, COMMITMENT);
+    if (!info || !info.owner.equals(TOKEN_PROGRAM) || info.data.length <= MINT_DECIMALS_OFFSET)
+        throw new BondedError("INVALID_ACTION", `${mint.toBase58()} is not an SPL token mint`);
+    return info.data[MINT_DECIMALS_OFFSET];
+}
+/** Whole units (e.g. "12.5") to base units, refusing more decimals than the mint has. */
+function toBaseUnits(amount, decimals) {
+    const match = /^(\d+)(?:\.(\d+))?$/.exec(amount.trim());
+    if (!match || (match[2]?.length ?? 0) > decimals)
+        throw new BondedError("INVALID_ACTION", `"${amount}" is not an amount with at most ${decimals} decimals`);
+    return BigInt(match[1] + (match[2] ?? "").padEnd(decimals, "0"));
+}
+/**
+ * A Solana Agent Kit plugin whose transfer and swap go through a Bonded vault. The kit's wallet
+ * must be the vault's agent key. Methods (`agent.methods.*`) take base units; actions take whole
+ * units, as an LLM writes them.
+ */
+export function bondedVaultPlugin(options) {
+    const vaults = new WeakMap();
+    const vaultFor = (agent) => {
+        let vault = vaults.get(agent);
+        if (!vault) {
+            vault = new SolanaBondedVault(agent.connection, options.vault, agent.wallet);
+            vaults.set(agent, vault);
+        }
+        return vault;
+    };
+    const guarded = async (vault, inner, setup = [], lookupTables = []) => {
+        if (options.guard) {
+            const check = await vault.dryRun(inner, setup, lookupTables);
+            if (!check.ok)
+                throw new SolanaVaultError("PREDICTED_BREACH", `refused: the vault would record a breach (${check.breach?.type})`, check.breach);
+        }
+        return vault.execute(inner, setup, lookupTables);
+    };
+    const methods = {
+        /** The vault's account: mode, frozen, allowed programs, limit and breach log. */
+        bondedVaultStatus: (agent) => vaultFor(agent).status(),
+        bondedVaultTransfer: async (agent, params) => {
+            const vault = vaultFor(agent);
+            const plan = await vault.transferPlan(params);
+            return guarded(vault, plan.instruction, plan.setup);
+        },
+        bondedVaultSwap: async (agent, params) => {
+            if (!options.swap)
+                throw new BondedError("CONFIG", "set `swap` in bondedVaultPlugin to swap through the vault");
+            const vault = vaultFor(agent);
+            const built = await options.swap({
+                vault: vault.address,
+                inputMint: params.inputMint,
+                outputMint: params.outputMint,
+                amount: params.amount,
+                slippageBps: params.slippageBps ?? 50,
+            });
+            return guarded(vault, built.instruction, built.setup, built.lookupTables);
+        },
+        /** Any instruction with the vault as signer, through `execute`. */
+        bondedVaultExecute: (agent, instruction) => guarded(vaultFor(agent), instruction),
+    };
+    const report = (result) => ({
+        signature: result.signature,
+        breaches: result.breaches.map((b) => ({
+            ...b,
+            target: b.target.toBase58(),
+            loss: b.loss.toString(),
+        })),
+        message: result.breaches.length
+            ? `Done, but the vault recorded a breach (${result.breaches.map((b) => b.type).join(", ")}) and may have frozen the agent.`
+            : "Done within the mandate.",
+    });
+    const transferAction = {
+        name: "BONDED_VAULT_TRANSFER",
+        similes: ["send tokens from the vault", "transfer from the bonded vault"],
+        description: "Send SPL tokens from the Bonded vault that holds the agent's funds. The vault checks it against the mandate; on Solana only transfers to the vault's own accounts are allowed.",
+        examples: [
+            [
+                {
+                    input: {
+                        mint: "So11111111111111111111111111111111111111112",
+                        to: "<vault>",
+                        amount: "1.5",
+                    },
+                    output: { status: "success", signature: "5x...", breaches: [] },
+                    explanation: "Move 1.5 tokens into the vault's own token account",
+                },
+            ],
+        ],
+        schema: schema({
+            mint: z.string().describe("The token's mint address"),
+            to: z.string().describe("The owner of the receiving token account"),
+            amount: z.string().describe("Amount in whole tokens, e.g. 12.5"),
+        }),
+        handler: async (agent, input) => {
+            const mint = new PublicKey(input.mint);
+            const amount = toBaseUnits(input.amount, await mintDecimals(agent.connection, mint));
+            return report(await methods.bondedVaultTransfer(agent, {
+                mint,
+                to: new PublicKey(input.to),
+                amount,
+            }));
+        },
+    };
+    const swapAction = {
+        name: "BONDED_VAULT_SWAP",
+        similes: ["swap tokens in the vault", "trade through the bonded vault"],
+        description: "Swap tokens held by the Bonded vault. The swap runs inside the vault's execute, which checks the program and the outflow limit.",
+        examples: [],
+        schema: schema({
+            inputMint: z.string(),
+            outputMint: z.string(),
+            amount: z.string().describe("Amount of the input token in whole tokens"),
+            slippageBps: z.number().int().min(0).max(10_000).optional(),
+        }),
+        handler: async (agent, input) => {
+            const inputMint = new PublicKey(input.inputMint);
+            const amount = toBaseUnits(input.amount, await mintDecimals(agent.connection, inputMint));
+            return report(await methods.bondedVaultSwap(agent, {
+                inputMint,
+                outputMint: new PublicKey(input.outputMint),
+                amount,
+                ...(input.slippageBps !== undefined ? { slippageBps: input.slippageBps } : {}),
+            }));
+        },
+    };
+    const statusAction = {
+        name: "BONDED_VAULT_STATUS",
+        similes: ["vault status", "is the vault frozen"],
+        description: "Report the Bonded vault's state: whether it is frozen, its mode, the programs it may call, its per-call limit and its breach log.",
+        examples: [],
+        schema: schema({}),
+        handler: async (agent) => {
+            const v = await methods.bondedVaultStatus(agent);
+            return {
+                vault: v.address.toBase58(),
+                frozen: v.frozen,
+                mode: v.enforce ? "enforce" : "monitor",
+                allowedPrograms: v.allowedPrograms.map((p) => p.toBase58()),
+                maxOutflowPerCall: v.maxOutflowPerCall.toString(),
+                breaches: v.breaches.map((b) => ({
+                    id: b.id,
+                    type: b.type,
+                    blocked: b.blocked,
+                    loss: b.loss.toString(),
+                })),
+            };
+        },
+    };
+    return {
+        name: "bonded-vault",
+        methods,
+        actions: [transferAction, statusAction, ...(options.swap ? [swapAction] : [])],
+        initialize: () => { },
+    };
+}
+//# sourceMappingURL=solana-agent-kit.js.map

package/dist/vault-tools.d.ts

@@ -0,0 +1,67 @@
+import { type GuardContext, type SentinelGuardOptions, type TokenInfo } from "./guarded.js";
+import type { EpisodeToolResult, ToolInputSchema } from "./mcp.js";
+import { BondedVault } from "./vault.js";
+export interface BondedVaultToolsOptions {
+    /** The vault (or module), with the agent key to send from and a `router` for swaps. */
+    vault: BondedVault;
+    /**
+     * Tokens the model may name by symbol. Default: the mandate's own assets, read from the vault
+     * once (`getAssets()`, with each token's symbol and decimals). Any token can also be named by
+     * address.
+     */
+    tokens?: readonly TokenInfo[];
+    /**
+     * Dry-run each write first and refuse a predicted breach, so the model gets an error instead
+     * of a recorded breach. On by default: an LLM-driven agent should not knowingly breach. The
+     * vault judges either way.
+     */
+    guard?: boolean;
+    /** Also ask Sentinel before each write that passes the dry run. Advisory; off unless set. */
+    sentinel?: SentinelGuardOptions;
+    /**
+     * What the agent read before this write (emails, posts, tool output), for Sentinel. Called
+     * before each write. The AI SDK tools fill it from the conversation's tool results by default.
+     */
+    context?: () => GuardContext | Promise<GuardContext>;
+}
+/** The tools' names: the same as the Arena episode's write tools, plus `vault_status`. */
+export declare const BONDED_VAULT_TOOLS: readonly ["swap", "transfer", "approve", "vault_status"];
+export type BondedVaultToolName = (typeof BONDED_VAULT_TOOLS)[number];
+/** One vault tool, framework-neutral: wrap it for your framework, or use the helpers. */
+export interface BondedVaultTool {
+    name: BondedVaultToolName;
+    description: string;
+    inputSchema: ToolInputSchema;
+    /**
+     * Runs the tool. A failure (a refused dry run, Sentinel's advice, a blocked or reverted call,
+     * bad arguments) is returned as `{ ok: false, error }`, not thrown, so the model can react.
+     */
+    call(args?: Record<string, unknown>, context?: GuardContext): Promise<EpisodeToolResult>;
+}
+/**
+ * The vault's trading tools, framework-neutral: `swap`, `transfer`, `approve` (the same names and
+ * arguments as the Arena episode's write tools, so the agent's prompts work the same while it is
+ * rated) and `vault_status`. Every write goes through `BondedVault`, so the vault checks it
+ * against the mandate; by default each is dry-run first and refused on a predicted breach.
+ * `bondedVaultLangChainTools` and `bondedVaultAiSdkTools` wrap these for their frameworks.
+ */
+export declare function bondedVaultTools(options: BondedVaultToolsOptions): BondedVaultTool[];
+/**
+ * The production vault from the environment, or undefined when `BONDED_VAULT_ADDRESS` isn't set
+ * (so the same code runs before the agent has a vault):
+ *
+ * | Variable | Meaning |
+ * |---|---|
+ * | `BONDED_VAULT_ADDRESS` | The Mandate Vault (or MandateModule) |
+ * | `BONDED_AGENT_KEY` | The vault's agent key (0x private key), required with the address |
+ * | `BONDED_VAULT_CHAIN_ID` | Default 46630 (Robinhood Chain testnet) |
+ * | `BONDED_VAULT_RPC_URL` | Default: the chain's public RPC |
+ * | `BONDED_ROUTER_ADDRESS` | The swap venue your mandate allows (Bonded's `DemoRouter` on testnet) |
+ *
+ * These are different from the `BONDED_*` variables the runner sets for an episode, and the
+ * runner removes them from a rated agent's environment. If they come back anyway (a `.env` file
+ * reloaded with `node --env-file` or dotenv), this still returns undefined while the process is
+ * rated, and warns once: a rating never trades the production vault.
+ */
+export declare function bondedVaultFromEnv(env?: Record<string, string | undefined>): BondedVault | undefined;
+//# sourceMappingURL=vault-tools.d.ts.map