brainchain-mcp 0.6.1 → 0.7.0

package/README.md

@@ -16,7 +16,7 @@ Read the key without echoing it or leaving it in your shell history, then add th
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo
-claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.6.1
+claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.7.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -27,7 +27,7 @@ unset BRAINCHAIN_PAYER_KEY
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.6.1"],
+      "args": ["-y", "brainchain-mcp@0.7.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${BRAINCHAIN_PAYER_KEY}" }
     }
   }
@@ -45,7 +45,7 @@ Or add the server to a project's `.cursor/mcp.json` (`~/.cursor/mcp.json` for ev
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.6.1"],
+      "args": ["-y", "brainchain-mcp@0.7.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${env:BRAINCHAIN_PAYER_KEY}" }
     }
   }
@@ -63,7 +63,7 @@ Add the server to the client's `mcpServers` configuration. For Claude Desktop th
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.6.1"],
+      "args": ["-y", "brainchain-mcp@0.7.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "0xYOUR_KEY" }
     }
   }
@@ -82,7 +82,7 @@ These clients keep the key in that file as plain text.
     "brainchain": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.6.1"],
+      "args": ["-y", "brainchain-mcp@0.7.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
     }
   },
@@ -100,10 +100,10 @@ Save the key in a file only your account can read, then point the server at it:
 mkdir -p ~/.brainchain
 (umask 077; printf 'Key: ' && read -rs key && echo && printf '%s\n' "$key" > ~/.brainchain/payer.key)
 chmod 600 ~/.brainchain/payer.key
-openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.6.1"],"env":{"BRAINCHAIN_PAYER_KEY_FILE":"~/.brainchain/payer.key"}}'
+openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.7.0"],"env":{"BRAINCHAIN_PAYER_KEY_FILE":"~/.brainchain/payer.key"}}'
 ```
 
-The config holds only the path, and the key never enters OpenClaw's environment, which the agent's shell inherits. A key saved in `skills.entries.brainchain.apiKey` does not reach the server. `BRAINCHAIN_PAYER_KEY_FILE=~/.brainchain/payer.key npx -y brainchain-mcp@0.6.1 wallet` checks the file and prints the wallet it holds and its balance. [`examples/openclaw/brainchain`](examples/openclaw/brainchain) is an OpenClaw skill that tells the agent when to hand work to BrainChain, how to write the brief and levels, and checks the wallet before it pays.
+The config holds only the path, and the key never enters OpenClaw's environment, which the agent's shell inherits. A key saved in `skills.entries.brainchain.apiKey` does not reach the server. `BRAINCHAIN_PAYER_KEY_FILE=~/.brainchain/payer.key npx -y brainchain-mcp@0.7.0 wallet` checks the file and prints the wallet it holds and its balance. [`examples/openclaw/brainchain`](examples/openclaw/brainchain) is an OpenClaw skill that tells the agent when to hand work to BrainChain, how to write the brief and levels, and checks the wallet before it pays.
 
 Each setup above pays in USDG on Robinhood Chain. To pay in USDC on Base instead, add `BRAINCHAIN_PAY_ON=base` to the server's environment (`-e BRAINCHAIN_PAY_ON=base` in Claude Code).
 
@@ -117,7 +117,7 @@ Each brief is posted on BrainChain and each result is served at a public link. K
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
-npx -y brainchain-mcp@0.6.1 approve
+npx -y brainchain-mcp@0.7.0 approve
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -136,6 +136,8 @@ An agent with a shell on the same account can read whatever that account can, in
 | `brainchain_post_task` | Pays for a task and returns an order id, the price paid and a `statusUrl`. Takes a one-line `title` of up to 120 characters, a `brief` of up to 32,000 characters and two or three different quality `levels` of up to 200 characters each, best first. The whole task can be at most 64,000 bytes as JSON, so a brief in Chinese, Japanese or Korean fits about 21,000 characters. An emoji counts as two characters. With three levels the work is paid at the second level or better; with two, only at the first. Models cannot browse, so put every fact they need in the brief. |
 | `brainchain_get_task` | Takes the `order` id and returns the payment (`network`, `paymentTx`), the order's `state` and the task's status on BrainChain (`task.status`, which appears shortly after the order reads `posted`), whether Jev accepted the work, the result text once it did, and the refund transaction if it did not. `done` says when to stop asking and `retryAfterSeconds` when to ask again. A rejected task stays not done until the refund is sent, so `next` gives the verdict first and `retryAfterSeconds` runs to the close of the dispute window. |
 | `brainchain_stock_premiums` | Takes nothing and returns what tokenized US stocks cost on Robinhood Chain against their Chainlink price right now: pool price, Chainlink price, premium in percent and the feed's age for NVDA, SPY, AAPL, TSLA, GOOGL, META and MSFT. Free, no key, read from the chain. The same board is at [usebrainchain.com/premium](https://usebrainchain.com/premium). |
+| `brainchain_bond_task` | For a wallet that also works on BrainChain. Takes a `task` id and an `amount` in USDG and locks it on [Shipped](https://shipped.bond) behind that task: if the task is paid and its Proof is minted, the bond comes back less Shipped's 1% fee; if the task is not paid by its deadline, it goes to the agent that paid for the task, which the bond names. Jev reads the bond when it hires. At least the task's bounty and 2 USDG, at most `BRAINCHAIN_MAX_BOND_UNITS`, counted against the budget and the daily limit like a post; never on a task this wallet posted or paid for. The wallet needs the USDG and a little ETH on Robinhood Chain. Mainnet only, once BrainChain's ProofIndex is live; until then the tool says so. See [Bond a task](https://docs.usebrainchain.com/bond-a-task). |
+| `brainchain_bond_status` | Takes the `task` id and returns where this wallet's bonds on it stand: open, marked, delivered or missed, with the next step. A delivered bond is collected with the worker CLI's `bond claim`. |
 
 Results usually arrive within minutes. A post reply with `possiblyCharged` means the payment was signed but the desk never confirmed the order, because the connection dropped or the desk returned an unexpected status. The payment may have gone through, so read the order with `brainchain_get_task` rather than posting again. While the server keeps running, an identical post within 15 minutes returns the first order, marked `duplicate`, instead of paying twice.
 
@@ -158,12 +160,13 @@ Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/
 | `BRAINCHAIN_NETWORK` | `mainnet` | `testnet` switches every setting to BrainChain testnet. |
 | `BRAINCHAIN_PAY_ON` | `robinhood` | `base` pays in USDC on Base (Base Sepolia on testnet) instead of USDG on Robinhood Chain. |
 | `BRAINCHAIN_MAX_PRICE_UNITS` | `1000000` | Maximum paid per task, in base units (6 decimals, so 1000000 is 1 USDG). |
+| `BRAINCHAIN_MAX_BOND_UNITS` | `10000000` | Maximum locked in one delivery bond with `brainchain_bond_task`, in base units. Bonds also draw on the budget and the daily limit. |
 | `BRAINCHAIN_BUDGET_UNITS` | `10000000` | Maximum paid in total while the server runs, in base units (10000000 is 10 USDG). |
 | `BRAINCHAIN_DAILY_UNITS` | no limit | Maximum the wallet pays per UTC day, in base units. The running total is kept on disk, so restarting the server does not reset it. A payment signed just before a crash stays counted until 00:00 UTC, even if it was never taken. |
 | `BRAINCHAIN_STATE_DIR` | `~/.brainchain` | Where the daily total is kept, one file per network and wallet: absolute or starting with `~/`. |
 | `BRAINCHAIN_DESK_URL`, `BRAINCHAIN_PAY_TO`, `BRAINCHAIN_PAYMENT_NETWORK`, `BRAINCHAIN_PAYMENT_ASSET`, `BRAINCHAIN_PAYMENT_RPC` | network preset | Override a single setting. A custom desk needs its own `BRAINCHAIN_PAY_TO`, and an https URL unless it is on localhost or 127.0.0.1. |
 
-If a setting is invalid, the server says so once on stderr when it starts, and both tools return the error. A key it cannot use is reported the same way, except that `brainchain_get_task` needs no key and keeps working, and so is a `BRAINCHAIN_STATE_DIR` that cannot hold the daily limit's record when `BRAINCHAIN_DAILY_UNITS` is set. `npx -y brainchain-mcp@0.6.1 wallet` checks the settings and the key, and prints the wallet that pays, what it holds and, for USDG, what Permit2 may spend. `--help` lists the commands and variables, and `--version` prints the version.
+If a setting is invalid, the server says so once on stderr when it starts, and both tools return the error. A key it cannot use is reported the same way, except that `brainchain_get_task` needs no key and keeps working, and so is a `BRAINCHAIN_STATE_DIR` that cannot hold the daily limit's record when `BRAINCHAIN_DAILY_UNITS` is set. `npx -y brainchain-mcp@0.7.0 wallet` checks the settings and the key, and prints the wallet that pays, what it holds and, for USDG, what Permit2 may spend. `--help` lists the commands and variables, and `--version` prints the version.
 
 ## Try it on testnet
 
@@ -171,7 +174,7 @@ Set `BRAINCHAIN_NETWORK=testnet` in the server's environment. Test tokens have n
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo
-claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.6.1
+claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.7.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -190,7 +193,7 @@ unset BRAINCHAIN_PAYER_KEY
 
    ```bash
    printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
-   BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.6.1 approve
+   BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.7.0 approve
    unset BRAINCHAIN_PAYER_KEY
    ```
 

package/dist/bonds.js

@@ -0,0 +1,212 @@
+// Delivery bonds from this server's wallet: USDG locked on Shipped behind a
+// BrainChain task, released by the task's Proof and paid to the poster when
+// the task is not paid by its deadline. A bond draws on the same budget and
+// daily limit as a post, and never passes BRAINCHAIN_MAX_BOND_UNITS.
+import { createPublicClient, createWalletClient, defineChain, formatEther, http, isAddress, parseAbi, parseEventLogs } from "viem";
+import { formatUnits } from "./config.js";
+import { limitReached } from "./payments.js";
+import { BOND_LEAD_SEC, BPS, bondTerms, CHECK_CONFIRM_SEC, CHECK_HOLD_SEC, DeedStatus, FEE_BPS, MIN_BOND, shippedAbi, taskBoardAbi, taskOfCheck, TaskStatus } from "./shipped.js";
+const erc20 = parseAbi([
+    "function balanceOf(address owner) view returns (uint256)",
+    "function allowance(address owner, address spender) view returns (uint256)",
+    "function approve(address spender, uint256 amount) returns (bool)",
+]);
+/** Gas the transactions take, measured on a fork of Robinhood Chain, with room. */
+const GAS = { approve: 60000n, create: 1100000n };
+const DEED_BATCH = 200;
+const DEED_SCAN = 5_000;
+export function createBondChain(bonds, account, desk, fetchImpl = fetch) {
+    const brainchain = createPublicClient({
+        chain: defineChain({ id: bonds.brainchain.chainId, name: "BrainChain", nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 }, rpcUrls: { default: { http: [bonds.brainchain.rpc] } } }),
+        transport: http(bonds.brainchain.rpc, { retryCount: 2, timeout: 15_000 }),
+    });
+    const chain = defineChain({
+        id: 4663,
+        name: bonds.chain,
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpcUrls: { default: { http: [bonds.rpc] } },
+        contracts: { multicall3: { address: "0xcA11bde05977b3631167028862bE2a173976CA11" } },
+    });
+    const transport = http(bonds.rpc, { retryCount: 2, timeout: 15_000 });
+    const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
+    const wallet = createWalletClient({ account, chain, transport });
+    const registry = { address: bonds.registry, abi: shippedAbi };
+    const token = { address: bonds.usdg, abi: erc20 };
+    async function send(request) {
+        const hash = await wallet.writeContract(request);
+        const receipt = await client.waitForTransactionReceipt({ hash, timeout: 90_000 });
+        if (receipt.status !== "success")
+            throw new Error(`Transaction ${hash} reverted.`);
+        return { hash, receipt };
+    }
+    return {
+        account: account.address,
+        async task(id) {
+            const t = await brainchain.readContract({ address: bonds.brainchain.board, abi: taskBoardAbi, functionName: "get", args: [id] });
+            return t.status === 0 ? undefined : { poster: t.poster, bounty: t.bounty, deadline: t.deadline, status: t.status, model: t.model };
+        },
+        now: async () => (await client.getBlock()).timestamp,
+        usdgBalance: () => client.readContract({ ...token, functionName: "balanceOf", args: [account.address] }),
+        ethBalance: () => client.getBalance({ address: account.address }),
+        gasPrice: () => client.getGasPrice(),
+        allowance: () => client.readContract({ ...token, functionName: "allowance", args: [account.address, bonds.registry] }),
+        async approve(amount) {
+            return (await send({ ...token, functionName: "approve", args: [bonds.registry, amount] })).hash;
+        },
+        async create(terms, amount) {
+            const { hash, receipt } = await send({ ...registry, functionName: "create", args: [terms, amount] });
+            const created = parseEventLogs({ abi: shippedAbi, eventName: "DeedCreated", args: { creator: account.address }, logs: receipt.logs }).find((log) => log.address.toLowerCase() === bonds.registry.toLowerCase());
+            if (!created)
+                throw new Error(`The bond ${hash} created no deed for ${account.address}.`);
+            return { deed: created.args.deedId, tx: hash };
+        },
+        async bondsOn(task) {
+            if (!bonds.proofIndex)
+                return [];
+            const count = Number(await client.readContract({ ...registry, functionName: "deedCount" }));
+            const floor = Math.max(0, count - DEED_SCAN);
+            const mine = [];
+            for (let to = count; to > floor; to -= DEED_BATCH) {
+                const ids = Array.from({ length: Math.min(DEED_BATCH, to - floor) }, (_, i) => BigInt(to - i));
+                const cores = await client.multicall({ contracts: ids.map((id) => ({ ...registry, functionName: "core", args: [id] })), allowFailure: false });
+                ids.forEach((id, i) => {
+                    if (cores[i][0].toLowerCase() === account.address.toLowerCase())
+                        mine.push(id);
+                });
+            }
+            if (mine.length === 0)
+                return [];
+            const deeds = await client.multicall({ contracts: mine.map((id) => ({ ...registry, functionName: "getDeed", args: [id] })), allowFailure: false });
+            return mine.flatMap((deed, i) => {
+                const d = deeds[i];
+                if (d.terms.check.toLowerCase() !== bonds.check.toLowerCase() || taskOfCheck(d.terms.checkData, bonds.proofIndex, bonds.brainchain.board) !== task)
+                    return [];
+                return [{ deed, amount: d.balance, deadline: d.terms.deadline, status: d.status, remainderBps: d.remainderBps, checkMetAt: d.checkMetAt, settledAt: d.settledAt, refundTo: d.terms.refundTo }];
+            });
+        },
+        proofOf: (task) => client.readContract({ address: bonds.proofIndex, abi: parseAbi(["function proofOf(address board, uint256 taskId) view returns (uint256)"]), functionName: "proofOf", args: [bonds.brainchain.board, task] }),
+        async payerOf(task) {
+            let response;
+            try {
+                response = await fetchImpl(`${desk}/bonds/refund-to/${task}`, { signal: AbortSignal.timeout(15_000) });
+            }
+            catch (error) {
+                throw new Error(`Could not reach the desk at ${desk} to ask who paid for task ${task} (${error instanceof Error ? error.message.split("\n")[0] : String(error)}). Nothing was bonded.`);
+            }
+            if (!response.ok)
+                throw new Error(`The desk at ${desk} answered ${response.status} when asked who paid for task ${task}. Nothing was bonded.`);
+            const { refundTo } = (await response.json().catch(() => undefined)) ?? {};
+            if (refundTo === null || refundTo === undefined)
+                return undefined;
+            if (typeof refundTo !== "string" || !isAddress(refundTo))
+                throw new Error(`The desk at ${desk} named the payer of task ${task} in a form this server cannot read. Nothing was bonded.`);
+            return refundTo;
+        },
+    };
+}
+const iso = (seconds) => new Date(Number(seconds) * 1000).toISOString();
+const fee = (amount) => (amount * FEE_BPS) / BPS;
+/** Why bonds cannot be placed on this network right now, for the tool's description and its answers. */
+export function bondsClosed(config) {
+    if (!config.bonds)
+        return `Delivery bonds run on Robinhood Chain against Shipped's registry, which ${config.name === "testnet" ? "BrainChain testnet" : "this network"} has no counterpart of. They are open with BRAINCHAIN_NETWORK=mainnet.`;
+    if (!config.bonds.proofIndex)
+        return "Delivery bonds are not open yet: BrainChain's ProofIndex on Robinhood Chain, which a bond's check reads, is not deployed. A later release of brainchain-mcp names it.";
+    return undefined;
+}
+export function createBonds(options) {
+    const { config, limits } = options;
+    let chain;
+    const connected = () => {
+        const closed = bondsClosed(config);
+        if (closed)
+            throw new Error(closed);
+        return (chain ??= (options.connect ?? createBondChain)(config.bonds, options.signer(), config.desk, options.fetch ?? fetch));
+    };
+    function state(b, indexed, now) {
+        if (b.status === DeedStatus.Settled) {
+            return b.remainderBps === Number(BPS)
+                ? { state: "delivered", settledAt: iso(b.settledAt), back: `${formatUnits(b.amount - fee(b.amount))} USDG`, next: "The bond less Shipped's 1% fee is owed to this wallet on the registry; the worker CLI's `bond claim` collects it." }
+                : { state: "missed", settledAt: iso(b.settledAt), paidTo: b.refundTo, next: "The task was not paid by the deadline, so the bond went to the poster." };
+        }
+        if (b.checkMetAt > 0n)
+            return { state: "marked", markedAt: iso(b.checkMetAt), next: `BrainChain confirms the check after ${iso(b.checkMetAt + CHECK_HOLD_SEC)}, and the bond settles as delivered.` };
+        if (now > b.deadline)
+            return { state: "lapsed", next: `No Proof was recorded by the deadline. The bond settles to the poster ${b.refundTo} after ${iso(b.deadline + CHECK_HOLD_SEC + CHECK_CONFIRM_SEC)}.` };
+        return { state: "open", next: indexed ? "The Proof is in the index; BrainChain marks the check shortly." : "Waiting for the task to be paid and its Proof recorded." };
+    }
+    return {
+        async bond(task, amount) {
+            const c = connected();
+            const t = await c.task(task);
+            if (!t)
+                throw new Error(`There is no task ${task} on BrainChain. Nothing was bonded.`);
+            if (t.poster.toLowerCase() === c.account.toLowerCase())
+                throw new Error(`Task ${task} was posted by this wallet. A bond guarantees delivery to someone else; it earns no standing on a task the same wallet posted. Nothing was bonded.`);
+            const hiredHere = t.status === TaskStatus.Hired && t.model.toLowerCase().endsWith(c.account.slice(2).toLowerCase());
+            if (t.status !== TaskStatus.Open && !hiredHere)
+                throw new Error(`Task ${task} is not open and not hired to this wallet, so there is nothing to bond. Nothing was bonded.`);
+            const now = await c.now();
+            if (t.deadline <= now)
+                throw new Error(`Task ${task}'s deadline, ${iso(t.deadline)}, has passed. Nothing was bonded.`);
+            if (amount < t.bounty)
+                throw new Error(`The bond must be at least the task's bounty, ${formatUnits(t.bounty)} USDG; ${formatUnits(amount)} USDG is under it. Nothing was bonded.`);
+            if (amount < MIN_BOND)
+                throw new Error(`The bond must be at least ${formatUnits(MIN_BOND)} USDG: under that, Shipped's fee and the gas take too much of it. Nothing was bonded.`);
+            if (amount > config.maxBond)
+                throw new Error(`This server bonds at most ${formatUnits(config.maxBond)} USDG on one task. Raise BRAINCHAIN_MAX_BOND_UNITS and restart the server to allow more. Nothing was bonded.`);
+            const existing = (await c.bondsOn(task)).find((b) => b.status !== DeedStatus.Settled);
+            if (existing)
+                throw new Error(`This wallet already has bond No. ${existing.deed} open on task ${task}. Nothing was bonded.`);
+            // A task paid through the desk has the desk as its poster on the board; the bond pays the agent that paid.
+            const payer = await c.payerOf(task);
+            if (payer?.toLowerCase() === c.account.toLowerCase())
+                throw new Error(`Task ${task} was paid for by this wallet. A bond guarantees delivery to someone else; it earns no standing on a task the same wallet paid for. Nothing was bonded.`);
+            const refundTo = payer ?? t.poster;
+            const hold = await limits.take(amount);
+            if (typeof hold === "string")
+                throw new Error(await limitReached(config, limits, hold, "signed payments and bonds for"));
+            try {
+                const [balance, allowance, gasPrice, eth] = await Promise.all([c.usdgBalance(), c.allowance(), c.gasPrice(), c.ethBalance()]);
+                const approves = allowance < amount;
+                const gas = (GAS.create + (approves ? GAS.approve : 0n)) * gasPrice;
+                if (balance < amount)
+                    throw new Error(`${c.account} holds ${formatUnits(balance)} USDG on ${config.bonds.chain}, under the ${formatUnits(amount)} USDG to bond. Nothing was bonded.`);
+                if (eth < gas)
+                    throw new Error(`${c.account} holds ${formatEther(eth)} ETH on ${config.bonds.chain}, under the ${formatEther(gas)} ETH the approval and the bond need. Nothing was bonded.`);
+                const terms = bondTerms({ check: config.bonds.check, proofIndex: config.bonds.proofIndex, usdg: config.bonds.usdg }, { id: task, refundTo, paidThroughDesk: payer !== undefined, deadline: t.deadline }, { address: config.bonds.brainchain.board, chainId: config.bonds.brainchain.chainId });
+                if (approves)
+                    await c.approve(amount);
+                const { deed, tx } = await c.create(terms, amount);
+                return {
+                    bond: deed.toString(),
+                    tx,
+                    task: task.toString(),
+                    amount: `${formatUnits(amount)} USDG`,
+                    deadline: iso(terms.deadline),
+                    delivered: `${formatUnits(amount - fee(amount))} USDG back after Shipped's 1% fee, once the task is paid and its Proof recorded`,
+                    missed: `${formatUnits(amount)} USDG to ${refundTo}, ${payer ? "the agent that paid for the task" : "the poster"}, if no Proof is recorded by the deadline`,
+                    next: "Jev reads the bond when it hires. Follow it with brainchain_bond_status.",
+                };
+            }
+            catch (error) {
+                await limits.give(hold);
+                throw error;
+            }
+        },
+        async status(task) {
+            const c = connected();
+            const bonds = await c.bondsOn(task);
+            if (bonds.length === 0)
+                return { task: task.toString(), wallet: c.account, bonds: [] };
+            const [now, indexed] = await Promise.all([c.now(), c.proofOf(task)]);
+            return {
+                task: task.toString(),
+                wallet: c.account,
+                proofIndexed: indexed > 0n,
+                bonds: bonds.map((b) => ({ bond: b.deed.toString(), amount: `${formatUnits(b.amount)} USDG`, deadline: iso(b.deadline), ...state(b, indexed > 0n, now) })),
+            };
+        },
+    };
+}
+export { BOND_LEAD_SEC };

package/dist/config.js

@@ -44,6 +44,17 @@ const PRESETS = {
         },
     },
 };
+const BONDS = {
+    mainnet: {
+        registry: "0xD5Da523ee49CB7Fe855B0C6fa38707190A9D531F",
+        check: "0x2e7C4F0F2e6079C3B5F7Cd2440308234CBDc537D",
+        usdg: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+        rpc: "https://rpc.mainnet.chain.robinhood.com",
+        chain: "Robinhood Chain",
+        brainchain: { rpc: "https://rpc.usebrainchain.com", chainId: 274663, board: "0x8385bb4b8990411CcdD8e851B2676da1A4C1f3C4" },
+    },
+    testnet: undefined,
+};
 /** USDG, USDC and their test versions all use 6 decimals. */
 export const DECIMALS = 6;
 /** A payment authorization may stay valid for at most this long. */
@@ -56,6 +67,7 @@ export const MAX_TIMEOUT_SECONDS = 600;
 export const REPOST_AFTER_MINUTES = 15;
 const DEFAULT_MAX_PRICE = 1000000n;
 const DEFAULT_BUDGET = 10000000n;
+const DEFAULT_MAX_BOND = 10000000n;
 export function formatUnits(units) {
     const whole = units / 10n ** BigInt(DECIMALS);
     const fraction = (units % 10n ** BigInt(DECIMALS)).toString().padStart(DECIMALS, "0").replace(/0+$/, "");
@@ -127,6 +139,8 @@ export function resolveConfig(env) {
     const daily = envString(env, "BRAINCHAIN_DAILY_UNITS") === undefined ? undefined : envUnits(env, "BRAINCHAIN_DAILY_UNITS", 0n);
     if (daily !== undefined && daily < maxPrice)
         throw new Error("BRAINCHAIN_DAILY_UNITS must be at least BRAINCHAIN_MAX_PRICE_UNITS.");
+    const maxBond = envUnits(env, "BRAINCHAIN_MAX_BOND_UNITS", DEFAULT_MAX_BOND);
+    const bonds = BONDS[name];
     return {
         name,
         payOn,
@@ -143,6 +157,8 @@ export function resolveConfig(env) {
         budget,
         ...(daily !== undefined ? { daily } : {}),
         stateDir: envDirectory(env, "BRAINCHAIN_STATE_DIR", join(homedir(), ".brainchain")),
+        maxBond,
+        ...(bonds ? { bonds } : {}),
         terms: {
             cost: maxPrice === DEFAULT_MAX_PRICE ? `1 ${preset.token}` : `at most ${formatUnits(maxPrice)} ${preset.token}`,
             chain: preset.chain,

package/dist/index.js

@@ -8,7 +8,8 @@ import { approvalFailure, approveCommand, chainClients, createServer, erc20, pay
 const { version } = createRequire(import.meta.url)("../package.json");
 const USAGE = `brainchain-mcp ${version}
 
-MCP server that pays for tasks on BrainChain, reads their graded results, and reads what stock tokens cost on Robinhood Chain.
+MCP server that pays for tasks on BrainChain, reads their graded results, bonds tasks the wallet will deliver as a worker,
+and reads what stock tokens cost on Robinhood Chain.
 
 Usage:
   brainchain-mcp                 Start the server on stdio (what MCP clients run).
@@ -28,6 +29,8 @@ Environment:
   BRAINCHAIN_MAX_PRICE_UNITS  Maximum paid per task, in base units (default 1000000 = 1 USDG or USDC).
   BRAINCHAIN_BUDGET_UNITS     Maximum paid in total while the server runs (default 10000000 = 10 USDG or USDC).
   BRAINCHAIN_DAILY_UNITS      Maximum the wallet pays per UTC day, on either chain, kept across restarts (default: no daily limit).
+  BRAINCHAIN_MAX_BOND_UNITS   Maximum locked in one delivery bond on Shipped (default 10000000 = 10 USDG); bonds also draw on
+                              the budget and the daily limit.
   BRAINCHAIN_STATE_DIR        Where the daily limit's record is kept (default ~/.brainchain). Absolute or starting with ~/.
   BRAINCHAIN_DESK_URL, BRAINCHAIN_PAY_TO, BRAINCHAIN_PAYMENT_NETWORK, BRAINCHAIN_PAYMENT_ASSET, BRAINCHAIN_PAYMENT_RPC
                               Advanced overrides of the network preset.

package/dist/limits.js

@@ -0,0 +1,44 @@
+// What this server may spend from its wallet: the budget for the run, counted
+// before the first await so parallel calls cannot overshoot it, and the daily
+// limit kept on disk. Posts and bonds draw on the same two.
+import { join } from "node:path";
+import { dailyLedger } from "./daily.js";
+export function createLimits(config, account) {
+    let spent = 0n;
+    let ledger;
+    // Kept per network and wallet, so a testnet wallet never spends from the mainnet limit, and one
+    // limit holds whichever chain the wallet pays on: USDG and USDC count in the same units.
+    const daily = () => config.daily === undefined
+        ? undefined
+        : (ledger ??= dailyLedger(join(config.stateDir, `spend-${config.name}-${account().address.toLowerCase()}.json`), config.daily));
+    return {
+        spent: () => spent,
+        async take(amount) {
+            if (spent + amount > config.budget)
+                return "budget";
+            spent += amount;
+            const today = daily();
+            if (!today)
+                return { amount };
+            let reservation;
+            try {
+                reservation = await today.reserve(amount);
+            }
+            catch (error) {
+                spent -= amount;
+                throw error;
+            }
+            if (!reservation) {
+                spent -= amount;
+                return "daily limit";
+            }
+            return { amount, reservation };
+        },
+        async give(hold) {
+            spent -= hold.amount;
+            if (hold.reservation)
+                await daily().release(hold.reservation);
+        },
+        spentToday: async () => daily()?.spentToday().catch(() => undefined),
+    };
+}

package/dist/payments.js

@@ -1,12 +1,20 @@
 import { ExactEvmScheme } from "@x402/evm/exact/client";
 import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
-import { join } from "node:path";
 import { keccak256, toBytes } from "viem";
 import { formatUnits, MAX_TIMEOUT_SECONDS, REPOST_AFTER_MINUTES } from "./config.js";
-import { dailyLedger } from "./daily.js";
+import { createLimits } from "./limits.js";
 const BUDGET_REASON = "budget";
 const DAILY_REASON = "daily limit";
 const RESULT_LIMIT = 20_000;
+/** What a refused budget or daily limit tells a person, for a post and for a bond alike. */
+export async function limitReached(config, limits, which, verb = "signed payments for") {
+    if (which === "budget") {
+        return `This server has already ${verb} ${formatUnits(limits.spent())} of its ${formatUnits(config.budget)} ${config.token} budget. The budget resets when the server restarts; raise BRAINCHAIN_BUDGET_UNITS to allow more per run. Nothing was charged.`;
+    }
+    const today = await limits.spentToday();
+    // One limit covers both chains, so it is named without a token.
+    return `This wallet has already ${verb} ${today === undefined ? "most" : formatUnits(today)} of its daily limit of ${formatUnits(config.daily)}, counting USDG and USDC together. The limit resets at 00:00 UTC; raise BRAINCHAIN_DAILY_UNITS to allow more. Nothing was charged.`;
+}
 /** Same serialization the desk hashes into an order id: sorted keys, no whitespace. */
 export function canonicalStringify(value) {
     if (value === null || typeof value !== "object")
@@ -49,14 +57,8 @@ async function jsonObject(response) {
 export function createDesk(options) {
     const { config, signer, approveCommand } = options;
     const fetchImpl = options.fetch ?? fetch;
-    let spent = 0n;
     const account = () => (typeof signer === "function" ? signer() : signer);
-    let ledger;
-    // Kept per network and wallet, so a testnet wallet never spends from the mainnet limit, and one
-    // limit holds whichever chain the wallet pays on: USDG and USDC count in the same units.
-    const daily = () => config.daily === undefined
-        ? undefined
-        : (ledger ??= dailyLedger(join(config.stateDir, `spend-${config.name}-${account().address.toLowerCase()}.json`), config.daily));
+    const limits = options.limits ?? createLimits(config, account);
     const endpoint = `${config.desk}/x402/tasks`;
     const recent = new Map();
     /** When this process paid, or may have paid, for each order; the desk can take minutes to know one. */
@@ -84,14 +86,10 @@ export function createDesk(options) {
     /** Turns an x402 client error, raised before anything was signed, into a step a person or model can act on. */
     async function explainUnsigned(error) {
         const message = firstLine(error);
-        if (message.includes(`Payment creation aborted: ${BUDGET_REASON}`)) {
-            return `This server has already signed payments for ${formatUnits(spent)} of its ${formatUnits(config.budget)} ${config.token} budget. The budget resets when the server restarts; raise BRAINCHAIN_BUDGET_UNITS to allow more per run. Nothing was charged.`;
-        }
-        if (message.includes(`Payment creation aborted: ${DAILY_REASON}`)) {
-            const today = await daily().spentToday().catch(() => undefined);
-            // One limit covers both chains, so it is named without a token.
-            return `This wallet has already signed payments for ${today === undefined ? "most" : formatUnits(today)} of its daily limit of ${formatUnits(config.daily)}, counting USDG and USDC together. The limit resets at 00:00 UTC; raise BRAINCHAIN_DAILY_UNITS to allow more. Nothing was charged.`;
-        }
+        if (message.includes(`Payment creation aborted: ${BUDGET_REASON}`))
+            return await limitReached(config, limits, "budget");
+        if (message.includes(`Payment creation aborted: ${DAILY_REASON}`))
+            return await limitReached(config, limits, "daily limit");
         if (/rejected by spendControls/.test(message)) {
             const price = await quotedPrice();
             if (price !== undefined && price > config.maxPrice) {
@@ -174,16 +172,13 @@ export function createDesk(options) {
     }
     async function pay(task) {
         let signed;
-        let amount = 0n;
-        let reservation;
+        let hold;
         const unreserve = async () => {
-            spent -= amount;
-            amount = 0n;
-            if (reservation)
-                await daily().release(reservation);
-            reservation = undefined;
+            if (hold)
+                await limits.give(hold);
+            hold = undefined;
         };
-        const receipt = (order) => ({ order, price: `${formatUnits(amount)} ${config.token}`, statusUrl: `${endpoint}/${order}` });
+        const receipt = (order) => ({ order, price: `${formatUnits(hold?.amount ?? 0n)} ${config.token}`, statusUrl: `${endpoint}/${order}` });
         const client = x402Client.fromConfig({
             schemes: [{ network: config.network, client: new ExactEvmScheme(account()) }],
             spendControls: { allowedAssets: [{ network: config.network, asset: config.asset, maxAmountPerPayment: config.maxPrice.toString() }] },
@@ -198,25 +193,10 @@ export function createDesk(options) {
         // signed, so parallel calls cannot overshoot either. The budget is counted before
         // the first await, so no other call can pass the check in between.
         client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
-            const price = BigInt(selectedRequirements.amount);
-            if (spent + price > config.budget)
-                return { abort: true, reason: BUDGET_REASON };
-            spent += price;
-            amount = price;
-            let today;
-            try {
-                today = daily();
-                if (today)
-                    reservation = await today.reserve(price);
-            }
-            catch (error) {
-                await unreserve();
-                throw error;
-            }
-            if (today && !reservation) {
-                await unreserve();
-                return { abort: true, reason: DAILY_REASON };
-            }
+            const taken = await limits.take(BigInt(selectedRequirements.amount));
+            if (typeof taken === "string")
+                return { abort: true, reason: taken };
+            hold = taken;
         });
         client.onAfterPaymentCreation(async ({ paymentPayload }) => {
             signed = paymentPayload;
@@ -321,7 +301,7 @@ export function createDesk(options) {
         }
         return { ...view, ...guidance(view, config) };
     }
-    return { post, get, spent: () => spent };
+    return { post, get, spent: () => limits.spent() };
 }
 /** What the order means for the caller, and when to look again. Every state and status pair is in payments.test.ts. */
 export function guidance(view, config, now = Date.now()) {

package/dist/server.js

@@ -4,11 +4,13 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { createPublicClient, defineChain, formatEther, http, maxUint256, parseAbi } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
+import { bondsClosed, createBonds } from "./bonds.js";
 import { expandHome, formatUnits, resolveConfig } from "./config.js";
 import { stateDirProblem } from "./daily.js";
+import { createLimits } from "./limits.js";
 import { createDesk } from "./payments.js";
 import { PREMIUMS_NAME, PREMIUMS_TOOL } from "./premiums.js";
-import { callTool, GET_TASK_NAME, GET_TASK_TOOL, POST_TASK_NAME, postTaskTool } from "./tools.js";
+import { BOND_STATUS_NAME, BOND_TASK_NAME, bondTools, callTool, GET_TASK_NAME, GET_TASK_TOOL, POST_TASK_NAME, postTaskTool } from "./tools.js";
 /** The canonical Permit2 contract; x402 payments in USDG are signed Permit2 transfers. */
 export const PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
 export const erc20 = parseAbi([
@@ -19,9 +21,10 @@ export const erc20 = parseAbi([
 export const INSTRUCTIONS = `Post a task with ${POST_TASK_NAME}, then read it with ${GET_TASK_NAME} and the order id it returns, waiting retryAfterSeconds between reads until done is true. ` +
     `If a post returns possiblyCharged, do not post the task again: read the order instead. ` +
     `A rejected task stays not done until its refund is sent, which can take hours: say so as soon as next does, then read the order once more after retryAfterSeconds. ` +
+    `${BOND_TASK_NAME} locks USDG behind a BrainChain task this wallet will deliver as a worker, and ${BOND_STATUS_NAME} follows it; neither posts a task. ` +
     `The paying wallet's key is for this server alone. Never read it, print it, write it down or pass it to a command. If a tool here is missing or reports a key problem, stop and tell your operator.`;
 const KEY_HELP = `Add BRAINCHAIN_PAYER_KEY to this server's env in your MCP client config (in Claude Code, \`claude mcp add … -e BRAINCHAIN_PAYER_KEY=…\`), or BRAINCHAIN_PAYER_KEY_FILE with the path of a file holding it, then restart the server. ` +
-    `${GET_TASK_NAME} and ${PREMIUMS_NAME} work without a key. An agent reading this: stop and tell your operator. Do not look for the key.`;
+    `${GET_TASK_NAME}, ${PREMIUMS_NAME} and ${BOND_STATUS_NAME} work without a key. An agent reading this: stop and tell your operator. Do not look for the key.`;
 const messageOf = (error) => (error instanceof Error ? error.message : String(error));
 /** Read here and never echoed. A file keeps the key out of the client's environment, which an agent's shell inherits. */
 function readKeyFile(given) {
@@ -127,7 +130,7 @@ function deskFor(env, version, fetchImpl) {
         const refuse = async () => {
             throw new Error(problem);
         };
-        return { desk: { post: refuse, get: refuse }, terms: problem };
+        return { desk: { post: refuse, get: refuse }, terms: problem, bonds: { bond: refuse, status: refuse }, bondTools: bondTools({ maxBond: 0n, budget: 0n }, undefined, `Invalid setting: ${problem}`) };
     }
     let account;
     let keyProblem;
@@ -150,11 +153,13 @@ function deskFor(env, version, fetchImpl) {
         }
     };
     const { reader } = chainClients(config);
+    const limits = createLimits(config, payer);
     const desk = createDesk({
         config,
         signer: payer,
         approveCommand: approveCommand(config, version),
         fetch: fetchImpl,
+        limits,
         funds: async () => {
             const { address } = payer();
             const [balance, allowance] = await Promise.all([
@@ -164,16 +169,22 @@ function deskFor(env, version, fetchImpl) {
             return { balance, allowance };
         },
     });
-    return { desk, terms: { ...config.terms, ...(account ? { wallet: account.address } : {}), ...(problem ? { problem } : {}) } };
+    const closed = bondsClosed(config) ?? (problem ? `Invalid setting: ${problem}` : undefined);
+    return {
+        desk,
+        terms: { ...config.terms, ...(account ? { wallet: account.address } : {}), ...(problem ? { problem } : {}) },
+        bonds: createBonds({ config, signer: payer, limits }),
+        bondTools: bondTools(config, account?.address, closed),
+    };
 }
 export function createServer(env, version, options = {}) {
-    const { desk, terms } = deskFor(env, version, options.fetch);
+    const { desk, terms, bonds, bondTools: bondToolList } = deskFor(env, version, options.fetch);
     const problem = typeof terms === "string" ? terms : terms.problem;
     if (problem)
         (options.log ?? console.error)(`brainchain-mcp has an invalid setting: ${problem}`);
-    const tools = [postTaskTool(terms), GET_TASK_TOOL, PREMIUMS_TOOL];
+    const tools = [postTaskTool(terms), GET_TASK_TOOL, PREMIUMS_TOOL, ...bondToolList];
     const server = new Server({ name: "brainchain", title: "BrainChain", version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
-    server.setRequestHandler(CallToolRequestSchema, (request) => callTool(desk, request.params.name, request.params.arguments));
+    server.setRequestHandler(CallToolRequestSchema, (request) => callTool(desk, request.params.name, request.params.arguments, undefined, bonds));
     return server;
 }

package/dist/shipped.js

@@ -0,0 +1,80 @@
+// Shipped's registry on Robinhood Chain and the terms of a BrainChain delivery
+// bond on it: a deed with no judge, decided by Shipped's on-chain check reading
+// BrainChain's ProofIndex, proofOf(task) >= 1, with the task's poster as the
+// refund side.
+import { decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, parseAbi } from "viem";
+export const proofIndexAbi = parseAbi(["function proofOf(address board, uint256 taskId) view returns (uint256)"]);
+const TERMS = "(string title, string milestone, address project, uint8 projectKind, address asset, uint64 deadline, address verifier, address backupVerifier, address appealPanel, address check, bytes checkData, address refundTo, uint16 defaultRemainderBps, uint16 refundCapBps, bool allowPartial, uint32 verifierGrace, uint32 backupGrace, uint32 appealWindow, uint32 panelWindow, uint128 appealBond, uint128 verifierFee, address[] refundExcluded)";
+export const shippedAbi = parseAbi([
+    `function create(${TERMS} t, uint256 deposit) returns (uint256 deedId)`,
+    "function withdraw(address asset) returns (uint256)",
+    "function owed(address account, address asset) view returns (uint256)",
+    "function deedCount() view returns (uint256)",
+    "function core(uint256 deedId) view returns (address creator, uint8 status, address asset, uint64 deadline)",
+    `function getDeed(uint256 deedId) view returns ((address creator, uint8 status, uint8 ruling, uint16 remainderBps, uint16 feeBps, bool overturned, uint64 createdAt, uint64 ruledAt, uint64 appealedAt, uint64 settledAt, uint64 checkMetAt, uint64 windowEnd, address ruledBy, address appellant, uint256 balance, ${TERMS} terms))`,
+    `event DeedCreated(uint256 indexed deedId, address indexed creator, address indexed project, ${TERMS} terms, uint256 deposit, uint16 feeBps)`,
+]);
+export const taskBoardAbi = parseAbi([
+    "function get(uint256 id) view returns ((address poster, uint128 bounty, uint64 deadline, uint8 status, bool accepted, bool disputed, bool disputedByModel, bytes32 model, bytes32 briefHash, bytes32 resultHash, string briefURI, string resultURI, uint64 submittedAt, uint64 gradedAt, uint64 disputedAt, uint16 gradeThresholdBps, uint16 ruleThresholdBps, uint16 feeBps))",
+]);
+/** ShippedDeeds.Status and Ruling, as the contract declares them. */
+export const DeedStatus = { None: 0, Open: 1, Ruled: 2, Appealed: 3, Settled: 4 };
+export const Ruling = { None: 0, Accepted: 1, Rejected: 2, Partial: 3, Invalid: 4, Conceded: 5, Default: 6, CheckMet: 7 };
+/** TaskBoard.Status. */
+export const TaskStatus = { Open: 1, Hired: 2 };
+export const BPS = 10000n;
+export const FEE_BPS = 100n;
+/** The bond's deadline is the task's plus this. */
+export const BOND_LEAD_SEC = 48n * 3600n;
+export const CHECK_HOLD_SEC = 3600n;
+export const CHECK_CONFIRM_SEC = 86400n;
+/** Under this the fee and the gas take too much of the bond. */
+export const MIN_BOND = 2000000n;
+const ZERO = "0x0000000000000000000000000000000000000000";
+const checkDataTypes = [{ type: "address" }, { type: "bytes" }, { type: "uint8" }, { type: "uint256" }];
+/** Task ids restart with each board, so the board is part of the key. */
+export function encodeCheckData(proofIndex, board, task) {
+    return encodeAbiParameters(checkDataTypes, [proofIndex, encodeFunctionData({ abi: proofIndexAbi, functionName: "proofOf", args: [board, task] }), 0, 1n]);
+}
+/** The task a bond's check reads on `proofIndex` for `board`, or undefined for any other check. */
+export function taskOfCheck(data, proofIndex, board) {
+    try {
+        const [target, call, op, threshold] = decodeAbiParameters(checkDataTypes, data);
+        if (target.toLowerCase() !== proofIndex.toLowerCase() || op !== 0 || threshold !== 1n)
+            return undefined;
+        const { functionName, args } = decodeFunctionData({ abi: proofIndexAbi, data: call });
+        return functionName === "proofOf" && args[0].toLowerCase() === board.toLowerCase() ? args[1] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The refund side is the agent that paid for the task: the poster on the board, or the payer the desk recorded. */
+export function bondTerms(config, task, board) {
+    return {
+        title: `BrainChain task #${task.id}`,
+        milestone: `The Proof NFT for BrainChain task #${task.id} (task board ${board.address} on BrainChain, chain ${board.chainId}) is recorded in BrainChain's ProofIndex at ${config.proofIndex} on Robinhood Chain, ` +
+            `read as proofOf(${board.address}, ${task.id}) >= 1. BrainChain records the Proof once the task is paid and the Proof is minted. ` +
+            `If no Proof is recorded by the deadline, the bond is paid to ${task.refundTo}, ${task.paidThroughDesk ? "the agent that paid BrainChain's desk for the task" : "the task's poster"}.`,
+        project: ZERO,
+        projectKind: 0,
+        asset: config.usdg,
+        deadline: task.deadline + BOND_LEAD_SEC,
+        verifier: ZERO,
+        backupVerifier: ZERO,
+        appealPanel: ZERO,
+        check: config.check,
+        checkData: encodeCheckData(config.proofIndex, board.address, task.id),
+        refundTo: task.refundTo,
+        defaultRemainderBps: 0,
+        refundCapBps: 0,
+        allowPartial: false,
+        verifierGrace: 0,
+        backupGrace: 0,
+        appealWindow: 0,
+        panelWindow: 0,
+        appealBond: 0n,
+        verifierFee: 0n,
+        refundExcluded: [],
+    };
+}

package/dist/tools.js

@@ -1,10 +1,48 @@
-import { REPOST_AFTER_MINUTES } from "./config.js";
+import { formatUnits, REPOST_AFTER_MINUTES } from "./config.js";
 import { canonicalStringify } from "./payments.js";
 import { PREMIUMS_NAME, readPremiums } from "./premiums.js";
+import { MIN_BOND } from "./shipped.js";
 export const POST_TASK_NAME = "brainchain_post_task";
 /** The desk's cap on a task as it goes on chain: title, brief, levels and pass level as JSON. */
 export const MAX_TASK_BYTES = 64_000;
 export const GET_TASK_NAME = "brainchain_get_task";
+export const BOND_TASK_NAME = "brainchain_bond_task";
+export const BOND_STATUS_NAME = "brainchain_bond_status";
+const TASK_ID = { type: "string", pattern: "^[1-9][0-9]{0,17}$", description: "The task's id on BrainChain's task board." };
+const BOND_TASK_INPUT = {
+    type: "object",
+    properties: {
+        task: TASK_ID,
+        amount: { type: "string", pattern: "^[0-9]{1,9}(\\.[0-9]{1,6})?$", description: "USDG to lock, such as \"5\" or \"2.5\": at least the task's bounty and at least 2 USDG." },
+    },
+    required: ["task", "amount"],
+    additionalProperties: false,
+};
+const BOND_STATUS_INPUT = { type: "object", properties: { task: TASK_ID }, required: ["task"], additionalProperties: false };
+/** The bond tools, worded for the network and the wallet this server holds; `closed` says why no bond can be placed. */
+export function bondTools(config, wallet, closed) {
+    const where = wallet ? `this server's wallet ${wallet}` : "this server's wallet";
+    return [
+        {
+            name: BOND_TASK_NAME,
+            title: "Bond a BrainChain task on Shipped",
+            description: (closed ? `${closed} Until then this tool only returns that error. ` : "") +
+                `Lock USDG on Shipped behind a BrainChain task from ${where}, as the worker that will deliver it. ` +
+                `If the task is paid and its Proof is minted, the bond comes back less Shipped's 1% fee; if the task is not paid by its deadline, the bond goes to the task's poster. ` +
+                `Jev reads the bond when it hires. The amount is at least the task's bounty and ${formatUnits(MIN_BOND)} USDG, at most ${formatUnits(config.maxBond)} USDG per task, and counts against this server's budget and daily limit like a post. ` +
+                `The wallet needs the USDG and a little ETH on Robinhood Chain. Never bond a task this wallet posted. Returns the bond number; follow it with ${BOND_STATUS_NAME}.`,
+            inputSchema: BOND_TASK_INPUT,
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+        },
+        {
+            name: BOND_STATUS_NAME,
+            title: "Read this wallet's bond on a BrainChain task",
+            description: `${closed ? `${closed} ` : ""}Where ${where}'s bonds on a task stand: open, marked (the Proof is recorded and the check waits out its hour), delivered (the bond less 1% is owed to the wallet) or missed (paid to the poster), with the next step.`,
+            inputSchema: BOND_STATUS_INPUT,
+            annotations: { readOnlyHint: true, openWorldHint: true },
+        },
+    ];
+}
 const POST_TASK_INPUT = {
     type: "object",
     properties: {
@@ -128,9 +166,24 @@ function orderReply(view) {
         result.content.push({ type: "text", text: resultText });
     return result;
 }
-export async function callTool(desk, name, args, premiums = readPremiums) {
+export async function callTool(desk, name, args, premiums = readPremiums, bonds) {
     const input = (args ?? {});
     try {
+        if (name === BOND_TASK_NAME || name === BOND_STATUS_NAME) {
+            if (!bonds)
+                return reply({ error: "This server has no bond tools." }, true);
+            refuseUnknownFields(input, name === BOND_TASK_NAME ? BOND_TASK_INPUT : BOND_STATUS_INPUT);
+            const task = text("task", input.task);
+            if (!/^[1-9]\d{0,17}$/.test(task))
+                throw new Error("task must be the task's id on BrainChain, a whole number above zero.");
+            if (name === BOND_STATUS_NAME)
+                return reply(await bonds.status(BigInt(task)));
+            const amount = text("amount", input.amount);
+            if (!/^\d{1,9}(\.\d{1,6})?$/.test(amount) || Number(amount) <= 0)
+                throw new Error("amount is in USDG, above zero with at most 6 decimals, such as \"5\".");
+            const [whole, fraction = ""] = amount.split(".");
+            return reply(await bonds.bond(BigInt(task), BigInt(whole + fraction.padEnd(6, "0"))));
+        }
         if (name === POST_TASK_NAME) {
             refuseUnknownFields(input, POST_TASK_INPUT);
             return reply(await desk.post(checkBrief(input)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-mcp",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "MCP server for BrainChain: let your agent hire a frontier model for a task and pay in USDG on Robinhood Chain or USDC on Base, only for work that meets the quality bar you set.",
   "mcpName": "com.usebrainchain/brainchain",
   "license": "MIT",