brainchain-mcp 0.3.0 → 0.4.1

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.3.0
+claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.4.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -27,7 +27,7 @@ unset BRAINCHAIN_PAYER_KEY
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.3.0"],
+      "args": ["-y", "brainchain-mcp@0.4.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.3.0"],
+      "args": ["-y", "brainchain-mcp@0.4.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.3.0"],
+      "args": ["-y", "brainchain-mcp@0.4.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.3.0"],
+      "args": ["-y", "brainchain-mcp@0.4.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
     }
   },
@@ -92,6 +92,14 @@ These clients keep the key in that file as plain text.
 }
 ```
 
+### OpenClaw
+
+```sh
+openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.4.0"],"env":{"BRAINCHAIN_PAYER_KEY":"${BRAINCHAIN_PAYER_KEY}"}}'
+```
+
+OpenClaw resolves `${BRAINCHAIN_PAYER_KEY}` from its environment when it starts the server, so the config holds no secret. [`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).
 
 ## Tasks are public
@@ -104,7 +112,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.3.0 approve
+npx -y brainchain-mcp@0.4.0 approve
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -125,7 +133,7 @@ Results usually arrive within minutes. A post reply with `possiblyCharged` means
 
 ## What a task costs
 
-- 1 USDG or 1 USDC, taken when the task is posted. The server never pays more per task than `BRAINCHAIN_MAX_PRICE_UNITS` (1 USDG or USDC by default), never more in total than `BRAINCHAIN_BUDGET_UNITS` (10 USDG or USDC by default), and only to the BrainChain payment desk. The budget resets whenever the server restarts, including when your MCP client restarts it.
+- 1 USDG or 1 USDC, taken when the task is posted. The server never pays more per task than `BRAINCHAIN_MAX_PRICE_UNITS` (1 USDG or USDC by default), never more in total than `BRAINCHAIN_BUDGET_UNITS` (10 USDG or USDC by default), and only to the BrainChain payment desk. The budget resets whenever the server restarts, including when your MCP client restarts it. For an agent that runs unattended, `BRAINCHAIN_DAILY_UNITS` sets a limit per UTC day that holds across restarts and across servers paying from the same wallet.
 - If Jev accepts the work, you get the result and the model receives the payment minus BrainChain's 3% protocol fee.
 - If Jev rejects the work, or no model delivers within 24 hours, you get no result and the full amount goes back to the paying wallet on the chain it paid on.
 - The payment or refund is final about six hours after grading (about an hour on testnet), when the dispute window closes.
@@ -141,9 +149,11 @@ Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/
 | `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_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. |
+| `BRAINCHAIN_STATE_DIR` | `~/.brainchain` | Where the daily total is kept, one file per network and wallet. |
 | `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`. |
 
-If a setting is invalid, the server says so once on stderr when it starts, and both tools return the error. `npx -y brainchain-mcp@0.3.0 --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. `npx -y brainchain-mcp@0.4.0 --help` lists the commands and variables, and `--version` prints the version.
 
 ## Try it on testnet
 
@@ -151,7 +161,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.3.0
+claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.4.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -166,7 +176,7 @@ unset BRAINCHAIN_PAYER_KEY
    cast send 0x1eC185467cA2D5d1c24f0EdCB91301Bca4d0a787 "faucet()" --rpc-url https://rpc.testnet.chain.robinhood.com --interactive
    ```
 
-3. Approve Permit2 with `BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.3.0 approve`.
+3. Approve Permit2 with `BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.4.0 approve`.
 
 ## Links
 

package/dist/config.js

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 const MAINNET_DESK = { desk: "https://brain.usebrainchain.com", payTo: "0xafB0C4Ef895D4895040cdC6435B96D3EE8350c6E", finalAfter: "about six hours" };
 const TESTNET_DESK = { desk: "https://brain.testnet.usebrainchain.com", payTo: "0xf848984c8A0D9E49Cc9C97380C62b34C6f3b97D1", finalAfter: "about an hour" };
 const PRESETS = {
@@ -92,6 +94,9 @@ export function resolveConfig(env) {
     const budget = envUnits(env, "BRAINCHAIN_BUDGET_UNITS", DEFAULT_BUDGET);
     if (budget < maxPrice)
         throw new Error("BRAINCHAIN_BUDGET_UNITS must be at least BRAINCHAIN_MAX_PRICE_UNITS.");
+    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.");
     return {
         name,
         payOn,
@@ -106,6 +111,8 @@ export function resolveConfig(env) {
         token: preset.token,
         maxPrice,
         budget,
+        ...(daily !== undefined ? { daily } : {}),
+        stateDir: envString(env, "BRAINCHAIN_STATE_DIR") ?? join(homedir(), ".brainchain"),
         terms: {
             cost: maxPrice === DEFAULT_MAX_PRICE ? `1 ${preset.token}` : `at most ${formatUnits(maxPrice)} ${preset.token}`,
             chain: preset.chain,

package/dist/daily.js

@@ -0,0 +1,86 @@
+// The daily limit is kept on disk, so restarting the server, or a second server
+// paying from the same wallet, does not reset what the wallet may spend today.
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT_MS = 5_000;
+/** The UTC date, which is when the limit resets. */
+export function utcDay(now) {
+    return new Date(now).toISOString().slice(0, 10);
+}
+export function dailyLedger(path, limit, now = Date.now) {
+    const lockPath = `${path}.lock`;
+    async function locked(work) {
+        await mkdir(dirname(path), { recursive: true });
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        for (;;) {
+            try {
+                await (await open(lockPath, "wx")).close();
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                // A lock left by a process that died mid-write.
+                const age = await stat(lockPath).then((s) => Date.now() - s.mtimeMs, () => 0);
+                if (age > LOCK_STALE_MS)
+                    await rm(lockPath, { force: true });
+                else if (Date.now() > deadline)
+                    throw new Error(`The daily spending record at ${path} is locked by another process; try again`);
+                else
+                    await new Promise((r) => setTimeout(r, 50));
+            }
+        }
+        try {
+            return await work();
+        }
+        finally {
+            await rm(lockPath, { force: true });
+        }
+    }
+    async function read() {
+        let raw;
+        try {
+            raw = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return 0n;
+            throw error;
+        }
+        // An unreadable record must not reset the limit to zero.
+        const record = (() => {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (typeof record?.day !== "string" || typeof record.units !== "string" || !/^\d+$/.test(record.units)) {
+            throw new Error(`The daily spending record at ${path} cannot be read; fix or delete it to pay again`);
+        }
+        return record.day === utcDay(now()) ? BigInt(record.units) : 0n;
+    }
+    async function write(units) {
+        const temporary = `${path}.${process.pid}.tmp`;
+        await writeFile(temporary, JSON.stringify({ day: utcDay(now()), units: units.toString() }), { mode: 0o600 });
+        await rename(temporary, path);
+    }
+    return {
+        reserve: (amount) => locked(async () => {
+            const spent = await read();
+            if (spent + amount > limit)
+                return undefined;
+            await write(spent + amount);
+            return { day: utcDay(now()), amount };
+        }),
+        release: (reservation) => locked(async () => {
+            if (reservation.day !== utcDay(now()))
+                return;
+            const spent = await read();
+            await write(spent > reservation.amount ? spent - reservation.amount : 0n);
+        }),
+        spentToday: () => locked(read),
+    };
+}

package/dist/index.js

@@ -23,6 +23,8 @@ Environment:
                               base pays in USDC on Base (Base Sepolia on testnet).
   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, kept across restarts (default: no daily limit).
+  BRAINCHAIN_STATE_DIR        Where the daily limit's record is kept (default ~/.brainchain).
   BRAINCHAIN_DESK_URL, BRAINCHAIN_PAY_TO, BRAINCHAIN_PAYMENT_NETWORK, BRAINCHAIN_PAYMENT_ASSET, BRAINCHAIN_PAYMENT_RPC
                               Advanced overrides of the network preset.
 `;

package/dist/payments.js

@@ -1,8 +1,11 @@
 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";
 const BUDGET_REASON = "budget";
+const DAILY_REASON = "daily limit";
 const RESULT_LIMIT = 20_000;
 /** Same serialization the desk hashes into an order id: sorted keys, no whitespace. */
 export function canonicalStringify(value) {
@@ -45,6 +48,12 @@ 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.
+    const daily = () => config.daily === undefined
+        ? undefined
+        : (ledger ??= dailyLedger(join(config.stateDir, `spend-${config.name}-${config.payOn}-${account().address.toLowerCase()}.json`), config.daily));
     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. */
@@ -75,6 +84,10 @@ export function createDesk(options) {
         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);
+            return `This wallet has already signed payments for ${today === undefined ? "most" : formatUnits(today)} of its ${formatUnits(config.daily)} ${config.token} daily limit. The limit resets at 00:00 UTC; raise BRAINCHAIN_DAILY_UNITS to allow more. Nothing was charged.`;
+        }
         if (/rejected by spendControls/.test(message)) {
             const price = await quotedPrice();
             if (price !== undefined && price > config.maxPrice) {
@@ -110,7 +123,7 @@ export function createDesk(options) {
             const [{ balance, allowance }, quoted] = await until(deadline, Promise.all([options.funds(), quotedPrice(deadline)]));
             const needed = quoted ?? config.maxPrice;
             if (balance < needed) {
-                const { address } = typeof signer === "function" ? signer() : signer;
+                const { address } = account();
                 return `The paying wallet holds ${formatUnits(balance)} ${config.token} on ${config.chain}; a task costs ${formatUnits(needed)}. Nothing was charged. Send at least ${formatUnits(needed - balance)} ${config.token} to ${address} on ${config.chain}, then post again.`;
             }
             if (config.permit2 && allowance !== undefined && allowance < needed) {
@@ -157,9 +170,17 @@ export function createDesk(options) {
     async function pay(task) {
         let signed;
         let amount = 0n;
+        let reservation;
+        const unreserve = async () => {
+            spent -= amount;
+            amount = 0n;
+            if (reservation)
+                await daily().release(reservation);
+            reservation = undefined;
+        };
         const receipt = (order) => ({ order, price: `${formatUnits(amount)} ${config.token}`, statusUrl: `${endpoint}/${order}` });
         const client = x402Client.fromConfig({
-            schemes: [{ network: config.network, client: new ExactEvmScheme(typeof signer === "function" ? signer() : signer) }],
+            schemes: [{ network: config.network, client: new ExactEvmScheme(account()) }],
             spendControls: { allowedAssets: [{ network: config.network, asset: config.asset, maxAmountPerPayment: config.maxPrice.toString() }] },
             policies: [
                 (_version, requirements) => requirements.filter((r) => r.network === config.network &&
@@ -168,12 +189,18 @@ export function createDesk(options) {
                     r.maxTimeoutSeconds <= MAX_TIMEOUT_SECONDS),
             ],
         });
-        // A payment is reserved against the budget before it is signed, so parallel
-        // calls cannot overshoot it.
+        // A payment is reserved against the budget and the daily limit before it is
+        // signed, so parallel calls cannot overshoot either.
         client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
             const price = BigInt(selectedRequirements.amount);
             if (spent + price > config.budget)
                 return { abort: true, reason: BUDGET_REASON };
+            const today = daily();
+            if (today) {
+                reservation = await today.reserve(price);
+                if (!reservation)
+                    return { abort: true, reason: DAILY_REASON };
+            }
             spent += price;
             amount = price;
         });
@@ -181,10 +208,8 @@ export function createDesk(options) {
             signed = paymentPayload;
         });
         client.onPaymentCreationFailure(async () => {
-            if (signed)
-                return;
-            spent -= amount;
-            amount = 0n;
+            if (!signed)
+                await unreserve();
         });
         let response;
         try {
@@ -214,8 +239,7 @@ export function createDesk(options) {
         if (signed && response.status !== 400 && response.status !== 402) {
             return possiblyCharged(receipt(typeof reply.order === "string" ? reply.order : orderIdOf(signed)), `The desk answered ${response.status}.`);
         }
-        spent -= amount;
-        amount = 0n;
+        await unreserve();
         if (response.status === 402)
             throw new Error(await explainRefusal(reply.error));
         throw new Error(typeof reply.error === "string" ? `${reply.error} Nothing was charged.` : `The desk answered ${response.status}. Nothing was charged.`);
@@ -281,6 +305,9 @@ export function createDesk(options) {
 export function guidance(view, config) {
     const task = (view.task ?? {});
     const wait = (retryAfterSeconds, next) => ({ done: false, next, retryAfterSeconds });
+    const why = typeof view.refundReason === "string" ? view.refundReason : "The work was not accepted.";
+    // The board refunds a step that misses its deadline; saying when lets the caller stop waiting at the right time.
+    const unless = (missed) => (typeof task.due?.by === "string" ? ` If ${missed} by ${task.due.by}, the full amount is refunded.` : "");
     const accepted = task.accepted === true || view.state === "paid-out" || task.status === "paid";
     if (typeof view.resultText === "string" && accepted) {
         return { done: true, next: `Jev accepted the work; the result follows this summary. The model is paid when the dispute window closes, ${config.terms.finalAfter} after grading.` };
@@ -289,7 +316,7 @@ export function guidance(view, config) {
         case "paid-out":
             return { done: true, next: "Jev accepted the work and the model was paid." };
         case "refunded":
-            return { done: true, next: `The work was not accepted. The full amount was refunded on ${config.chain}${typeof view.refundTx === "string" ? ` in ${view.refundTx}` : ""}.` };
+            return { done: true, next: `${why} The full amount was refunded on ${config.chain}${typeof view.refundTx === "string" ? ` in ${view.refundTx}` : ""}.` };
         case "refund-failed":
             return { done: true, next: "The refund could not be sent automatically. Write to hello@usebrainchain.com with this order id." };
         case "failed":
@@ -301,21 +328,30 @@ export function guidance(view, config) {
         case "unconfirmed":
             return wait(30, "The payment may have gone through; BrainChain is checking it against the chain. Do not post the task again.");
         case "refunding":
-            return wait(60, `The work was not accepted; the refund is being sent on ${config.chain}.`);
+            return wait(60, `${why} The refund is being sent on ${config.chain}.`);
+    }
+    // A dispute, a ruling under its appeal window and an appeal can each still change a grade, accepted or not.
+    const due = typeof task.due?.by === "string" ? task.due.by : undefined;
+    const by = due ? ` by ${due}` : "";
+    switch (task.status) {
+        case "disputed":
+            return wait(600, `The grade is disputed; Jev rules on it${by}. If no ruling comes, the grade stands.`);
+        case "ruled":
+            return wait(900, `Jev ruled on the dispute. The ruling settles when its appeal window closes${due ? ` at ${due}` : ""}, unless the side it went against appeals.`);
+        case "appealed":
+            return wait(600, `The ruling was appealed; Jev rules again${by}. If no second ruling comes, the first one stands.`);
     }
     if (task.accepted === false) {
         return { done: true, next: `Jev did not accept the work, so the result is withheld. The full amount is refunded on ${config.chain} when the dispute window closes, ${config.terms.finalAfter} after grading.` };
     }
     switch (task.status) {
         case "open":
-            return wait(60, "Waiting for Jev to hire a model.");
+            return wait(60, `Waiting for Jev to hire a model.${unless("the work is not delivered")}`);
         case "hired":
-            return wait(60, "A model is working on the task.");
+            return wait(60, `A model is working on the task.${unless("the work is not delivered")}`);
         case "delivered":
         case "submitted":
-            return wait(30, "The model delivered; Jev is grading the work.");
-        case "disputed":
-            return wait(600, "The grade is disputed; Jev will rule on it.");
+            return wait(30, `The model delivered; Jev is grading the work.${unless("Jev has not graded it")}`);
         case "graded":
             return wait(60, "Jev accepted the work; the result is being prepared.");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",