@bondedhq/sdk 0.0.0-stage → 0.1.1

package/dist/vault.js

@@ -0,0 +1,326 @@
+import { breachTypeFromCode, mandateModuleAbi, mandateVaultAbi, parseEpisodeEnv, } from "@bondedhq/shared";
+import { createPublicClient, createWalletClient, custom, erc20Abi, getAddress, http, isAddressEqual, } from "viem";
+import { simulateCalls } from "viem/actions";
+import { demoRouter, erc20Call, normaliseAction, } from "./actions.js";
+import { breachReason, readExecuteOutcome, toDryRunResult, } from "./breaches.js";
+import { BlockedByMandateError, BondedError, VaultFrozenError } from "./errors.js";
+import { vaultRevertError } from "./revert.js";
+/**
+ * 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 class BondedVault {
+    address;
+    publicClient;
+    walletClient;
+    router;
+    identity;
+    constructor(config) {
+        this.address = getAddress(config.vault);
+        // Without an rpcUrl, a wallet built here sends through the given public client's RPC.
+        const transport = config.rpcUrl || !config.publicClient ? http(config.rpcUrl) : custom(config.publicClient);
+        if (config.publicClient)
+            this.publicClient = config.publicClient;
+        else if (config.chain)
+            this.publicClient = createPublicClient({ chain: config.chain, transport });
+        else
+            throw new BondedError("CONFIG", "BondedVault needs a publicClient or a chain");
+        if (config.walletClient) {
+            if (!config.walletClient.account)
+                throw new BondedError("CONFIG", "the walletClient needs an account (the agent key)");
+            this.walletClient = config.walletClient;
+        }
+        else if (config.account) {
+            const chain = config.chain ?? this.publicClient.chain;
+            if (!chain)
+                throw new BondedError("CONFIG", "BondedVault needs a chain to send transactions");
+            this.walletClient = createWalletClient({ account: config.account, chain, transport });
+        }
+        this.router = typeof config.router === "string" ? demoRouter(config.router) : config.router;
+    }
+    /** The address that sends this vault's actions, if it can send. */
+    get agentAddress() {
+        return this.walletClient?.account.address;
+    }
+    async status() {
+        const read = (functionName) => this.publicClient.readContract({ address: this.address, abi: mandateVaultAbi, functionName });
+        const [frozen, mode, breachCount, agent, guardian, mandateHash, agentId, freezeOnBreach] = await Promise.all([
+            read("frozen"),
+            read("mode"),
+            read("breachCount"),
+            read("agent"),
+            read("guardian"),
+            read("mandateHash"),
+            read("agentId"),
+            read("freezeOnBreach"),
+        ]);
+        const { kind, holder } = await this.identify();
+        return {
+            kind,
+            holder,
+            frozen,
+            mode: mode === 1 ? "enforce" : "monitor",
+            breachCount,
+            agent,
+            guardian,
+            mandateHash,
+            agentId,
+            freezeOnBreach,
+        };
+    }
+    /**
+     * 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() {
+        this.identity ??= this.publicClient
+            .readContract({ address: this.address, abi: mandateModuleAbi, functionName: "account" })
+            .then((account) => ({ kind: "module", holder: account }), (error) => {
+            // A vault has no `account()`: the call reverts. Anything else (network) is an error.
+            if (!isMissingFunction(error)) {
+                this.identity = undefined;
+                throw error;
+            }
+            return { kind: "vault", holder: this.address };
+        });
+        return this.identity;
+    }
+    /** The vault's breach log, oldest first (from `fromId`, default 0). */
+    async breaches(fromId = 0n) {
+        const count = await this.publicClient.readContract({
+            address: this.address,
+            abi: mandateVaultAbi,
+            functionName: "breachCount",
+        });
+        const ids = [];
+        for (let id = fromId; id < count; id++)
+            ids.push(id);
+        return Promise.all(ids.map(async (id) => {
+            const b = await this.publicClient.readContract({
+                address: this.address,
+                abi: mandateVaultAbi,
+                functionName: "getBreach",
+                args: [id],
+            });
+            const type = breachTypeFromCode(b.breachType);
+            return {
+                id,
+                type,
+                reason: breachReason(type),
+                target: b.target,
+                selector: b.selector,
+                lossUsd6: b.lossUsd6,
+                blocked: b.blocked,
+            };
+        }));
+    }
+    swap(params) {
+        return this.execute({ type: "swap", ...params });
+    }
+    transfer(params) {
+        return this.execute({ type: "transfer", ...params });
+    }
+    approve(params) {
+        return this.execute({ type: "approve", ...params });
+    }
+    call(params) {
+        return this.execute({ type: "call", ...params });
+    }
+    /**
+     * 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.
+     */
+    async execute(action) {
+        refuseProductionVaultWhileRated(this, "execute");
+        const wallet = this.requireWallet();
+        const calls = await this.plan(action);
+        const result = { hashes: [], breaches: [] };
+        for (const [i, call] of calls.entries()) {
+            let hash;
+            try {
+                hash = await wallet.writeContract({
+                    address: this.address,
+                    abi: mandateVaultAbi,
+                    functionName: "execute",
+                    args: [call.target, call.data],
+                    account: wallet.account,
+                    chain: wallet.chain,
+                });
+            }
+            catch (error) {
+                throw vaultRevertError(error, {
+                    vault: this.address,
+                    target: call.target,
+                    signer: this.agentAddress,
+                });
+            }
+            const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+            if (receipt.status !== "success")
+                throw new BondedError("REVERTED", `execute reverted on chain (transaction ${hash})`);
+            const outcome = readExecuteOutcome(this.address, receipt.logs);
+            result.hashes.push(hash);
+            result.breaches.push(...outcome.breaches);
+            if (!outcome.executed) {
+                const blocked = outcome.breaches.find((b) => b.blocked);
+                if (blocked)
+                    throw new BlockedByMandateError(blocked, hash);
+                throw new VaultFrozenError(this.address, outcome.breaches[0], hash);
+            }
+            // A breach froze the vault partway through: the rest of the action can't be sent.
+            if (outcome.froze && i < calls.length - 1)
+                throw new VaultFrozenError(this.address, outcome.breaches[0], hash);
+        }
+        return result;
+    }
+    /**
+     * 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`.
+     */
+    async dryRun(action) {
+        const calls = await this.plan(action);
+        const from = this.agentAddress ??
+            (await this.publicClient.readContract({
+                address: this.address,
+                abi: mandateVaultAbi,
+                functionName: "agent",
+            }));
+        let simulation;
+        try {
+            // The action from this package's viem, so a caller's older client works too.
+            simulation = await simulateCalls(this.publicClient, {
+                account: from,
+                calls: calls.map((call) => ({
+                    to: this.address,
+                    abi: mandateVaultAbi,
+                    functionName: "execute",
+                    args: [call.target, call.data],
+                })),
+            });
+        }
+        catch (error) {
+            if (isUnsupported(error))
+                throw new BondedError("DRY_RUN_UNSUPPORTED", "this RPC doesn't support eth_simulateV1, which dry runs need; use an RPC that does", { cause: error });
+            throw error;
+        }
+        const merged = { executed: true, breaches: [], froze: false };
+        for (const [i, result] of simulation.results.entries()) {
+            if (result.status === "failure") {
+                // An earlier step's breach froze the vault: the prediction is that breach.
+                if (merged.froze)
+                    return toDryRunResult({ ...merged, executed: false });
+                throw vaultRevertError(result.error, {
+                    vault: this.address,
+                    target: calls[i].target,
+                    signer: from,
+                });
+            }
+            const outcome = readExecuteOutcome(this.address, result.logs ?? []);
+            merged.breaches.push(...outcome.breaches);
+            merged.froze ||= outcome.froze;
+            if (!outcome.executed)
+                return toDryRunResult({ ...merged, executed: false });
+        }
+        return toDryRunResult(merged);
+    }
+    /** The `execute` calls an action takes, in order. A swap approves the router first if needed. */
+    async plan(action) {
+        const a = normaliseAction(action);
+        switch (a.type) {
+            case "transfer":
+                return [erc20Call("transfer", a.token, a.to, a.amount)];
+            case "approve":
+                return [erc20Call("approve", a.token, a.spender, a.amount)];
+            case "call":
+                if (isAddressEqual(a.target, this.address))
+                    throw new BondedError("INVALID_ACTION", "the vault can't call itself");
+                return [{ target: a.target, data: a.data }];
+            case "swap": {
+                const router = this.router;
+                if (!router)
+                    throw new BondedError("CONFIG", "set `router` to swap (an allowed target of the mandate), or use call()");
+                if (a.minOut !== undefined && router.quote) {
+                    const quoted = await router.quote(this.publicClient, a);
+                    if (quoted < a.minOut)
+                        throw new BondedError("BELOW_MIN_OUT", `the router quotes ${quoted} for this swap, below minOut ${a.minOut}; nothing was sent`);
+                }
+                // A module's tokens are its account's: the account approves and receives.
+                const { holder } = await this.identify();
+                const allowance = await this.publicClient.readContract({
+                    address: a.tokenIn,
+                    abi: erc20Abi,
+                    functionName: "allowance",
+                    args: [holder, router.address],
+                });
+                const swap = {
+                    target: router.address,
+                    data: router.encodeSwap({ ...a, minOut: a.minOut ?? 0n, recipient: holder }),
+                };
+                return allowance >= a.amountIn
+                    ? [swap]
+                    : [erc20Call("approve", a.tokenIn, router.address, a.amountIn), swap];
+            }
+        }
+    }
+    requireWallet() {
+        if (!this.walletClient)
+            throw new BondedError("READ_ONLY", "this BondedVault has no agent key: pass `account` or `walletClient` to send actions");
+        return this.walletClient;
+    }
+}
+/**
+ * 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 function isRatedProcess(env = typeof process === "undefined" ? {} : process.env) {
+    return Boolean(env.BONDED_EPISODE_ID?.trim()) || parseEpisodeEnv(env).ok;
+}
+/**
+ * Vaults built from the production variables (`bondedVaultFromEnv`). A process that is being rated
+ * never sends from one, whatever put those variables back in its environment (a `.env` file
+ * reloaded with `node --env-file` or dotenv, say).
+ */
+const productionVaults = new WeakSet();
+/** Marks `vault` as the production vault (internal: `bondedVaultFromEnv` calls it). */
+export function markProductionVault(vault) {
+    productionVaults.add(vault);
+    return vault;
+}
+/** Throws `BondedError` (`RATED_PRODUCTION_VAULT`) when `vault` is the production vault and this process is rated. */
+export function refuseProductionVaultWhileRated(vault, what) {
+    if (productionVaults.has(vault) && isRatedProcess())
+        throw ratedProductionVaultError(what);
+}
+export function ratedProductionVaultError(what) {
+    return new BondedError("RATED_PRODUCTION_VAULT", `${what}: this process is running a Bonded episode, so the production vault (BONDED_VAULT_ADDRESS, BONDED_AGENT_KEY) is never used. Trade through the episode's tools while rated. If those variables came from a .env file, that is why they are set; nothing was sent.`);
+}
+/** A call to a function the contract doesn't have: it reverts, or returns nothing. */
+function isMissingFunction(error) {
+    for (let e = error, depth = 0; e instanceof Error && depth < 20; e = e.cause, depth++)
+        if (e.name === "ContractFunctionRevertedError" ||
+            e.name === "ContractFunctionZeroDataError" ||
+            e.name === "ExecutionRevertedError")
+            return true;
+    return false;
+}
+function isUnsupported(error) {
+    for (let e = error, depth = 0; e instanceof Error && depth < 20; e = e.cause, depth++) {
+        if (e.code === -32601)
+            return true;
+        if (/method not found|does not exist|is not available|not supported/i.test(e.message))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=vault.js.map

package/package.json

@@ -1,6 +1,137 @@
 {
   "name": "@bondedhq/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Trade through a Bonded Mandate Vault and get rated by the Bonded Arena from any TypeScript agent: a typed vault client with dry runs, Sentinel checks and a mandate builder; the Arena episode's tools for LangChain, the Vercel AI SDK, ElizaOS and Coinbase AgentKit; and an Agent URL handler.",
+  "license": "MIT",
+  "keywords": [
+    "bonded",
+    "ai-agents",
+    "mandate-vault",
+    "mcp",
+    "langchain",
+    "langgraph",
+    "vercel-ai-sdk",
+    "agentkit",
+    "solana-agent-kit",
+    "elizaos",
+    "viem"
+  ],
+  "homepage": "https://github.com/ddboy19912/bonded/tree/main/packages/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/ddboy19912/bonded/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ddboy19912/bonded.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "bonded-mcp-config": "./dist/mcp-config-cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
+    "./agent-url": {
+      "types": "./dist/agent-url.d.ts",
+      "import": "./dist/agent-url.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.js"
+    },
+    "./ai-sdk": {
+      "types": "./dist/ai-sdk.d.ts",
+      "import": "./dist/ai-sdk.js"
+    },
+    "./agentkit": {
+      "types": "./dist/agentkit.d.ts",
+      "import": "./dist/agentkit.js"
+    },
+    "./solana-agent-kit": {
+      "types": "./dist/solana-agent-kit.d.ts",
+      "import": "./dist/solana-agent-kit.js"
+    },
+    "./eliza": {
+      "types": "./dist/eliza.d.ts",
+      "import": "./dist/eliza.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "viem": "^2.56.9",
+    "zod": "^4.6.5",
+    "@bondedhq/shared": "^0.1.1"
+  },
+  "devDependencies": {
+    "@coinbase/agentkit": "0.10.4",
+    "@elizaos/core": "1.7.2",
+    "@langchain/core": "1.2.12",
+    "@solana/spl-token": "0.4.15",
+    "@solana/web3.js": "^1.98.4",
+    "ai": "7.0.114",
+    "solana-agent-kit": "2.0.10",
+    "@bondedhq/solana": "0.1.1",
+    "@bonded/sandbox": "0.1.0"
+  },
+  "peerDependencies": {
+    "@coinbase/agentkit": "^0.10.4",
+    "@elizaos/core": "^1.7.2",
+    "@langchain/core": "^1.0.0",
+    "@solana/web3.js": "^1.98.4",
+    "ai": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "solana-agent-kit": "^2.0.10",
+    "@bondedhq/solana": "^0.1.1"
+  },
+  "peerDependenciesMeta": {
+    "@bondedhq/solana": {
+      "optional": true
+    },
+    "@coinbase/agentkit": {
+      "optional": true
+    },
+    "@elizaos/core": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    },
+    "@solana/web3.js": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "solana-agent-kit": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.eliza.json",
+    "lint": "eslint src test",
+    "test": "vitest run"
+  }
 }