@bondedhq/sdk 0.0.0-stage → 0.1.1

package/dist/vault-tools.js

@@ -0,0 +1,335 @@
+import { EVM_CHAINS, evmChainById, mandateVaultAbi } from "@bondedhq/shared";
+import { defineChain, erc20Abi, formatUnits, getAddress, isAddress, isHex, parseUnits, } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { z } from "zod";
+import { BondedError } from "./errors.js";
+import { GuardedVault, } from "./guarded.js";
+import { BondedVault, isRatedProcess, markProductionVault, ratedProductionVaultError, refuseProductionVaultWhileRated, } from "./vault.js";
+/** The tools' names: the same as the Arena episode's write tools, plus `vault_status`. */
+export const BONDED_VAULT_TOOLS = ["swap", "transfer", "approve", "vault_status"];
+const amount = z
+    .union([z.string(), z.number()])
+    .transform(String)
+    .pipe(z.string().regex(/^\d+(\.\d+)?$/, "a decimal amount in whole tokens, e.g. 250 or 12.5"));
+const ARGS = {
+    swap: z.object({
+        tokenIn: z.string(),
+        tokenOut: z.string(),
+        amountIn: amount,
+        minOut: amount.optional(),
+    }),
+    transfer: z.object({ token: z.string(), to: z.string(), amount }),
+    approve: z.object({ token: z.string(), spender: z.string(), amount }),
+    vault_status: z.object({}),
+};
+const decimal = { type: "string", description: "A decimal amount in whole tokens, e.g. 250" };
+const token = { type: "string", description: "A token symbol (e.g. tUSDG) or address" };
+const SCHEMAS = {
+    swap: {
+        type: "object",
+        properties: {
+            tokenIn: { ...token, description: "The token to sell: a symbol or address" },
+            tokenOut: { ...token, description: "The token to buy: a symbol or address" },
+            amountIn: { ...decimal, description: "How much tokenIn to sell, in whole tokens" },
+            minOut: { ...decimal, description: "Optional: the least tokenOut to accept" },
+        },
+        required: ["tokenIn", "tokenOut", "amountIn"],
+        additionalProperties: false,
+    },
+    transfer: {
+        type: "object",
+        properties: {
+            token,
+            to: { type: "string", description: "The recipient's 0x address" },
+            amount: decimal,
+        },
+        required: ["token", "to", "amount"],
+        additionalProperties: false,
+    },
+    approve: {
+        type: "object",
+        properties: {
+            token,
+            spender: { type: "string", description: "The 0x address allowed to spend" },
+            amount: { ...decimal, description: "The most it may spend, in whole tokens; 0 revokes" },
+        },
+        required: ["token", "spender", "amount"],
+        additionalProperties: false,
+    },
+    vault_status: { type: "object", properties: {}, additionalProperties: false },
+};
+const DESCRIPTIONS = {
+    swap: "Swap one token for another with the funds in the agent's Bonded Mandate Vault. Every trade is checked against the agent's mandate.",
+    transfer: "Send tokens from the agent's Bonded Mandate Vault to an address. Only the mandate's destinations are allowed.",
+    approve: "Let an address spend tokens from the agent's Bonded Mandate Vault. Only the mandate's contracts are allowed.",
+    vault_status: "The agent's Bonded Mandate Vault: its mode, whether it is frozen, breaches recorded, and its token balances.",
+};
+/**
+ * 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 function bondedVaultTools(options) {
+    // While rated, the production vault's tools are refused outright: use the episode's tools.
+    refuseProductionVaultWhileRated(options.vault, "bondedVaultTools");
+    const guard = options.guard ?? true;
+    const tokens = tokenBook(options);
+    // Sentinel sees symbols and whole units: the configured tokens, else the mandate's.
+    let guarded;
+    const guardedVault = async () => {
+        const s = options.sentinel;
+        guarded ??= new GuardedVault(options.vault, s ? { sentinel: { ...s, tokens: s.tokens ?? (await tokens.list()) } } : {});
+        return guarded;
+    };
+    const send = async (action, given) => {
+        if (!guard && !options.sentinel)
+            return options.vault.execute(action);
+        const context = given ?? (options.sentinel && options.context ? await options.context() : {});
+        return (await guardedVault()).execute(action, context);
+    };
+    const run = async (name, raw, context, call) => {
+        const write = async (action, given) => (call.confirmed = await send(action, given));
+        const parsed = ARGS[name].safeParse(raw);
+        if (!parsed.success)
+            throw new BondedError("INVALID_ACTION", `${name}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "arguments"} ${i.message}`).join(", ")}`);
+        const args = parsed.data;
+        switch (name) {
+            case "swap": {
+                const tokenIn = await tokens.resolve(args.tokenIn);
+                const tokenOut = await tokens.resolve(args.tokenOut);
+                const { holder } = await options.vault.identify();
+                const before = await balance(options.vault, tokenOut.address, holder);
+                const result = await write({
+                    type: "swap",
+                    tokenIn: tokenIn.address,
+                    tokenOut: tokenOut.address,
+                    amountIn: parseUnits(args.amountIn, tokenIn.decimals),
+                    ...(args.minOut ? { minOut: parseUnits(args.minOut, tokenOut.decimals) } : {}),
+                }, context);
+                // The trade is confirmed: reading what it bought is best-effort. Failing here would hide
+                // the transactions and invite the model to trade again.
+                const after = await balance(options.vault, tokenOut.address, holder).catch(() => undefined);
+                return outcome(result, {
+                    sold: `${args.amountIn} ${tokenIn.symbol}`,
+                    received: after === undefined
+                        ? null
+                        : `${formatUnits(after - before, tokenOut.decimals)} ${tokenOut.symbol}`,
+                }, after === undefined ? BALANCE_UNREAD : undefined);
+            }
+            case "transfer": {
+                const t = await tokens.resolve(args.token);
+                const to = address("to", args.to);
+                const result = await write({
+                    type: "transfer",
+                    token: t.address,
+                    to,
+                    amount: parseUnits(args.amount, t.decimals),
+                }, context);
+                return outcome(result, { sent: `${args.amount} ${t.symbol}`, to });
+            }
+            case "approve": {
+                const t = await tokens.resolve(args.token);
+                const spender = address("spender", args.spender);
+                const result = await write({
+                    type: "approve",
+                    token: t.address,
+                    spender,
+                    amount: parseUnits(args.amount, t.decimals),
+                }, context);
+                return outcome(result, { approved: `${args.amount} ${t.symbol}`, spender });
+            }
+            case "vault_status": {
+                const status = await options.vault.status();
+                const known = await tokens.list();
+                const balances = Object.fromEntries(await Promise.all(known.map(async (t) => [
+                    t.symbol,
+                    formatUnits(await balance(options.vault, t.address, status.holder), t.decimals),
+                ])));
+                return {
+                    vault: options.vault.address,
+                    kind: status.kind,
+                    holder: status.holder,
+                    mode: status.mode,
+                    frozen: status.frozen,
+                    breachCount: status.breachCount.toString(),
+                    balances,
+                };
+            }
+        }
+    };
+    return BONDED_VAULT_TOOLS.map((name) => ({
+        name,
+        description: DESCRIPTIONS[name],
+        inputSchema: SCHEMAS[name],
+        call: async (args = {}, context) => {
+            const call = {};
+            try {
+                refuseProductionVaultWhileRated(options.vault, name);
+                const output = await run(name, args, context, call);
+                return { ok: true, output, text: JSON.stringify(output) };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                // Anything that fails after the write confirmed is a read: report the write, never a
+                // failure the model would retry (a second trade).
+                if (call.confirmed) {
+                    const output = outcome(call.confirmed, {}, `The ${name} is confirmed (see transactions), but reading its result failed (${message}). Don't repeat it: check vault_status.`);
+                    return { ok: true, output, text: JSON.stringify(output) };
+                }
+                return { ok: false, error: message, text: message };
+            }
+        },
+    }));
+}
+const BALANCE_UNREAD = "Trade confirmed (see transactions); couldn't read the new balance, so what it received is unknown. Don't repeat the trade: check vault_status.";
+/**
+ * A write's result as the model reads it: what moved, the transactions, and any breach the vault
+ * recorded or anything the tool couldn't read afterwards.
+ */
+function outcome(result, moved, unread) {
+    const warnings = [
+        ...(result.breaches.length
+            ? [
+                "The vault ran this action but recorded a breach of the mandate. The vault may have frozen the agent.",
+            ]
+            : []),
+        ...(unread ? [unread] : []),
+    ];
+    return {
+        ...moved,
+        transactions: result.hashes,
+        ...(result.breaches.length ? { breaches: result.breaches.map(breachView) } : {}),
+        ...(warnings.length ? { warning: warnings.join(" ") } : {}),
+    };
+}
+function breachView(b) {
+    return { id: b.id.toString(), type: b.type, reason: b.reason, blocked: b.blocked };
+}
+function address(field, value) {
+    if (!isAddress(value, { strict: false }))
+        throw new BondedError("INVALID_ACTION", `${field} must be a 0x address, not "${value}"`);
+    return getAddress(value);
+}
+function balance(vault, token, holder) {
+    return vault.publicClient.readContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: "balanceOf",
+        args: [holder],
+    });
+}
+/**
+ * The tokens the model can name: the configured ones, else the mandate's assets read from the
+ * vault once. An unknown address is looked up on chain.
+ */
+function tokenBook(options) {
+    let known;
+    const list = () => {
+        if (options.tokens)
+            return Promise.resolve(options.tokens);
+        known ??= readMandateTokens(options.vault).catch(() => {
+            known = undefined;
+            return [];
+        });
+        return known;
+    };
+    const resolve = async (value) => {
+        const tokens = await list();
+        const found = tokens.find((t) => t.symbol.toLowerCase() === value.toLowerCase() ||
+            t.address.toLowerCase() === value.toLowerCase());
+        if (found)
+            return found;
+        if (!isAddress(value, { strict: false }))
+            throw new BondedError("INVALID_ACTION", `unknown token "${value}"; use one of ${tokens.map((t) => t.symbol).join(", ") || "the mandate's tokens"} or a token address`);
+        return tokenInfo(options.vault, getAddress(value));
+    };
+    return { list, resolve };
+}
+async function readMandateTokens(vault) {
+    const assets = await vault.publicClient.readContract({
+        address: vault.address,
+        abi: mandateVaultAbi,
+        functionName: "getAssets",
+    });
+    return Promise.all(assets.map((a) => tokenInfo(vault, a)));
+}
+async function tokenInfo(vault, address) {
+    const read = (functionName) => vault.publicClient.readContract({ address, abi: erc20Abi, functionName });
+    const [symbol, decimals] = await Promise.all([
+        read("symbol").catch(() => address),
+        read("decimals"),
+    ]);
+    return { symbol, address, decimals };
+}
+/**
+ * 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 function bondedVaultFromEnv(env = typeof process === "undefined" ? {} : process.env) {
+    const vault = env.BONDED_VAULT_ADDRESS?.trim();
+    // A rated process never builds the production vault, even when its variables are back (a
+    // .env file reloaded with `node --env-file` or dotenv): undefined, as if they weren't set.
+    if (isRatedProcess(env) || isRatedProcess()) {
+        if (vault || env.BONDED_AGENT_KEY?.trim())
+            warnRatedOnce();
+        return undefined;
+    }
+    if (!vault)
+        return undefined;
+    const problems = [];
+    if (!isAddress(vault, { strict: false }))
+        problems.push("BONDED_VAULT_ADDRESS isn't an address");
+    const key = env.BONDED_AGENT_KEY?.trim();
+    if (!key)
+        problems.push("BONDED_AGENT_KEY (the vault's agent key) isn't set");
+    else if (!isHex(key) || key.length !== 66)
+        problems.push("BONDED_AGENT_KEY must be a 0x-prefixed 32-byte private key");
+    const chainId = Number(env.BONDED_VAULT_CHAIN_ID?.trim() || EVM_CHAINS.robinhoodTestnet.chainId);
+    if (!Number.isSafeInteger(chainId) || chainId <= 0)
+        problems.push("BONDED_VAULT_CHAIN_ID must be a chain id");
+    const known = evmChainById(chainId);
+    const rpcUrl = env.BONDED_VAULT_RPC_URL?.trim() || known?.rpcUrl;
+    if (!rpcUrl)
+        problems.push(`BONDED_VAULT_RPC_URL isn't set (no default RPC for chain ${chainId})`);
+    const router = env.BONDED_ROUTER_ADDRESS?.trim();
+    if (router && !isAddress(router, { strict: false }))
+        problems.push("BONDED_ROUTER_ADDRESS isn't an address");
+    if (problems.length)
+        throw new BondedError("CONFIG", problems.join("; "));
+    const built = new BondedVault({
+        vault: vault,
+        chain: defineChain({
+            id: chainId,
+            name: known?.name ?? `Chain ${chainId}`,
+            nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+            rpcUrls: { default: { http: [rpcUrl] } },
+        }),
+        rpcUrl: rpcUrl,
+        account: privateKeyToAccount(key),
+        ...(router ? { router: router } : {}),
+    });
+    return markProductionVault(built);
+}
+let warnedRated = false;
+function warnRatedOnce() {
+    if (warnedRated)
+        return;
+    warnedRated = true;
+    console.warn(`[bonded] ${ratedProductionVaultError("bondedVaultFromEnv").message}`);
+}
+//# sourceMappingURL=vault-tools.js.map

package/dist/vault.d.ts

@@ -0,0 +1,116 @@
+import { type Account, type Address, type Chain, type Hex, type PublicClient, type Transport, type WalletClient } from "viem";
+import { type ApproveParams, type CallParams, type SwapParams, type SwapRouter, type TransferParams, type VaultAction, type VaultCall } from "./actions.js";
+import { type DryRunResult, type VaultBreach } from "./breaches.js";
+import { BondedError } from "./errors.js";
+export interface BondedVaultConfig {
+    /**
+     * The Mandate Vault's address, or a MandateModule's (the mandate on an ERC-7579 smart
+     * account). The SDK tells them apart on chain.
+     */
+    vault: Address;
+    /** Reads the chain. Built from `chain` (and `rpcUrl`) when left out. */
+    publicClient?: PublicClient<Transport, Chain | undefined>;
+    /** Sends as the vault's agent key. Built from `account` (and `chain`, `rpcUrl`) when left out. */
+    walletClient?: WalletClient<Transport, Chain | undefined, Account>;
+    /** The vault's agent key. Without it (or a wallet client) the vault is read-only. */
+    account?: Account;
+    chain?: Chain;
+    /** RPC URL. Defaults to the public client's, or the chain's own. */
+    rpcUrl?: string;
+    /**
+     * Where `swap` trades: an allowed target of the mandate. An address means Bonded's testnet
+     * market (`DemoRouter`); pass a `SwapRouter` for any other venue.
+     */
+    router?: Address | SwapRouter;
+}
+/** What the vault (or module) is and whether it will act. */
+export interface VaultStatus {
+    /** A Mandate Vault holds the funds itself; a MandateModule guards a smart account's. */
+    kind: "vault" | "module";
+    /** Where the funds are: the vault itself, or the module's smart account. */
+    holder: Address;
+    /** The agent can't act until the guardian unfreezes the vault. */
+    frozen: boolean;
+    /** Monitor lets breaches through and records them; Enforce blocks and records them. */
+    mode: "monitor" | "enforce";
+    breachCount: bigint;
+    /** The key that can call `execute`. */
+    agent: Address;
+    /** Can freeze, unfreeze and rotate the agent key. */
+    guardian: Address;
+    mandateHash: Hex;
+    agentId: bigint;
+    freezeOnBreach: boolean;
+}
+/** What a write did. Monitor mode lets breaches through: check `breaches`. */
+export interface ActionResult {
+    /** One transaction per `execute` sent (a swap may need an approval first). */
+    hashes: Hex[];
+    /** Breaches the vault recorded while running the action. Empty when it kept to the mandate. */
+    breaches: VaultBreach[];
+}
+/**
+ * A Mandate Vault, from the agent's side. Every write is `MandateVault.execute(target, data)`
+ * sent from the agent key, so the vault checks it against the mandate and records any breach.
+ *
+ * ```ts
+ * const vault = new BondedVault({ vault, chain, account: privateKeyToAccount(agentKey) });
+ * const check = await vault.dryRun({ type: "transfer", token, to, amount });
+ * if (check.ok) await vault.transfer({ token, to, amount });
+ * ```
+ */
+export declare class BondedVault {
+    readonly address: Address;
+    readonly publicClient: PublicClient<Transport, Chain | undefined>;
+    readonly walletClient: WalletClient<Transport, Chain | undefined, Account> | undefined;
+    private readonly router;
+    private identity;
+    constructor(config: BondedVaultConfig);
+    /** The address that sends this vault's actions, if it can send. */
+    get agentAddress(): Address | undefined;
+    status(): Promise<VaultStatus>;
+    /**
+     * Whether this is a Mandate Vault or a MandateModule, and where its funds are (the vault
+     * itself, or the module's account). Read once from the chain: a module has `account()`.
+     */
+    identify(): Promise<{
+        kind: "vault" | "module";
+        holder: Address;
+    }>;
+    /** The vault's breach log, oldest first (from `fromId`, default 0). */
+    breaches(fromId?: bigint): Promise<VaultBreach[]>;
+    swap(params: SwapParams): Promise<ActionResult>;
+    transfer(params: TransferParams): Promise<ActionResult>;
+    approve(params: ApproveParams): Promise<ActionResult>;
+    call(params: CallParams): Promise<ActionResult>;
+    /**
+     * Sends an action through the vault and waits for it. Resolves when the vault ran it (in
+     * Monitor mode possibly with breaches recorded: see `breaches`). Throws `BlockedByMandateError`
+     * when Enforce mode stopped it, `VaultFrozenError` when the vault is or became frozen,
+     * `NotAgentError` for the wrong key and `CallRevertedError` when the call itself failed.
+     */
+    execute(action: VaultAction): Promise<ActionResult>;
+    /**
+     * What the vault would do with `action` right now: simulates `execute` from the agent key
+     * against the chain's current state (`eth_simulateV1`) and reads the vault's own events, so
+     * the verdict is the contract's, never a copy of its rules. Nothing is sent.
+     *
+     * Throws what sending would throw before the vault judges anything: `VaultFrozenError`,
+     * `NotAgentError`, `CallRevertedError`.
+     */
+    dryRun(action: VaultAction): Promise<DryRunResult>;
+    /** The `execute` calls an action takes, in order. A swap approves the router first if needed. */
+    plan(action: VaultAction): Promise<VaultCall[]>;
+    private requireWallet;
+}
+/**
+ * Whether this process is being rated: the runner set a Bonded episode's variables. Fails closed:
+ * a `BONDED_EPISODE_ID` alone counts, even when the rest of the episode's variables are malformed.
+ */
+export declare function isRatedProcess(env?: Record<string, string | undefined>): boolean;
+/** Marks `vault` as the production vault (internal: `bondedVaultFromEnv` calls it). */
+export declare function markProductionVault(vault: BondedVault): BondedVault;
+/** Throws `BondedError` (`RATED_PRODUCTION_VAULT`) when `vault` is the production vault and this process is rated. */
+export declare function refuseProductionVaultWhileRated(vault: BondedVault, what: string): void;
+export declare function ratedProductionVaultError(what: string): BondedError;
+//# sourceMappingURL=vault.d.ts.map