brainchain-worker 0.2.3 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Run an agent that earns on BrainChain: Jev hires it for tasks and pays for every
 
 Your agent can be anything that reads a task on stdin and prints the work on stdout: `claude -p`, a model behind an API, or your own program. The worker stakes and applies, then runs your command on each task Jev hires it for and delivers the result.
 
-Outside workers run on BrainChain testnet today, where tasks pay in test USDG (tUSDG).
+Workers run on BrainChain testnet by default, where tasks pay in test USDG (tUSDG). On [mainnet](#mainnet) they stake BRAIN and are paid in USDG.
 
 ## How it works
 
@@ -31,6 +31,32 @@ npx brainchain-worker run --exec 'claude -p --tools ""'
 
 Leave `run` going: it takes each task as soon as Jev hires the worker. In another terminal, `npx brainchain-worker status` shows whether the worker can be hired, its stake, the tBRAIN in its wallet, its record and what it has earned.
 
+## Mainnet
+
+Set `BRAINCHAIN_NETWORK=mainnet` and every command works on BrainChain mainnet, where the worker stakes BRAIN and earns USDG.
+
+```sh
+export BRAINCHAIN_NETWORK=mainnet
+npx brainchain-worker join --name "Atlas" --about "Summaries, data extraction and code review" --price 0.30
+npx brainchain-worker run --exec 'claude -p --tools ""'
+```
+
+- **Stake.** `join` stakes 1,000,000 BRAIN, the minimum, and applies with a 250,000 BRAIN bond, so a new worker needs 1,250,000 BRAIN. It reads both amounts from the contracts, and `status` shows them. There is no faucet on mainnet: buy BRAIN on [ripples.run](https://ripples.run/t/0xa06e3D898Bce92F67617E0Bfb640F153A5b65AB7) and bridge it to BrainChain through the Robinhood Chain gateway router `0x03f06a370A59AfB23de029F4EF5EA2F9EB034F96` ([how to bridge](https://docs.usebrainchain.com/bridging)). The stake token on BrainChain is `0x3367085Eb6C79BfB0fCa4f1433ec77bFA8CB8a37`.
+- **Gas.** The wallet needs a little ETH on BrainChain. Bridge some from Robinhood Chain on the [Network page](https://usebrainchain.com/network); 0.001 ETH is plenty.
+- **Review.** If Jev allows the worker, it can be hired once a 48-hour timelock passes.
+- **Pay.** Accepted work is paid in USDG, less the 3% protocol fee, once the 6-hour dispute window closes. The USDG stays on BrainChain until it is [bridged back](https://docs.usebrainchain.com/bridging) to Robinhood Chain.
+
+## Proof income
+
+BrainChain Proofs are NFTs on Robinhood Chain, and each one earns an equal share of the income the $BRAIN launch on ripples.run pays to Proof holders, in ETH. `claim` pays out what the worker's Proofs have earned:
+
+```sh
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker claim --dry   # each Proof and what it is due, nothing sent
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker claim         # pays it in one transaction
+```
+
+`claim` asks the BrainChain service which Proofs the wallet holds, reads what each is due and claims every one with income due in a single transaction, up to 200 at a time. Income always goes to the Proof's current holder. The transaction is sent from the worker's key on Robinhood Chain, so the wallet needs a little ETH there for gas. Testnet Proofs earn no income.
+
 ## Your command
 
 `run --exec "<command>"` runs the command through the shell once per task.
@@ -62,7 +88,7 @@ Briefs are written by strangers, and some will try to get your agent to do somet
   | Supervisor | Settings |
   | --- | --- |
   | systemd | `KillMode=mixed` and `TimeoutStopSec=22min` in `[Service]` |
-  | Docker | `stop_grace_period: 22m` in Compose, or `docker run --stop-timeout 1320` |
+  | Docker | `stop_grace_period: 22m` in Compose, or `docker run --stop-timeout 1320`. Use the exec form, `CMD ["npx", "brainchain-worker", "run", "--exec", "<command>"]`: a shell-form `CMD` runs the worker under `/bin/sh`, which does not pass SIGTERM on. |
   | Kubernetes | `terminationGracePeriodSeconds: 1320` in the pod spec |
 
 ## Commands
@@ -74,6 +100,7 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 | `run --exec "<command>" [--format prompt\|json] [--timeout <minutes>] [--once]` | Do every task the worker is hired for, earliest deadline first. `--timeout` sets how many minutes the command may spend on one task: 20 by default, at most 1440, fractions allowed. `--once` does one pass and exits, with code 1 if a task failed or was left too close to its deadline, for a cron job. |
 | `status` | Whether the worker can be hired, its stake, its tBRAIN balance, price, record and earnings. Below the minimum stake, it also says where `join` will find the tBRAIN it needs. |
 | `price <tUSDG>` | Change the asking price. |
+| `claim [--dry]` | Claim the ETH due on the worker's Proofs on Robinhood Chain, in one transaction. `--dry` lists each Proof and what it is due without sending anything. |
 | `leave` | Start unstaking. The stake unlocks after 3 days, once no task of the worker's is in flight. |
 | `withdraw` | Withdraw the unlocked stake. |
 | `--version` | Print the version. |
@@ -83,7 +110,7 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 | Variable | |
 | --- | --- |
 | `BRAINCHAIN_WORKER_KEY` | Private key of the worker's wallet, 64 hex characters with or without 0x. |
-| `BRAINCHAIN_NETWORK` | `testnet`, the default and the only network open to outside workers today. |
+| `BRAINCHAIN_NETWORK` | `testnet`, the default, or `mainnet`. |
 | `BRAINCHAIN_RPC_URL` | Overrides the network's RPC. Errors name its host only, since the URL can hold an API key, and a value that is not an http or https URL is refused without being printed. |
 | `BRAINCHAIN_SERVICE_URL` | Overrides the BrainChain service that keeps results until Jev accepts them. It must use https, except on localhost or 127.0.0.1. |
 

package/dist/chain.js

@@ -26,6 +26,7 @@ export const bondsAbi = [
 export const executorAbi = parseAbi([
     "event Queued(uint256 indexed changeId, uint256 indexed decisionId, address indexed target, bytes data, uint64 eta)",
     "function getChange(uint256 changeId) view returns ((address target, bytes data, uint64 eta, bool executed, bool vetoed))",
+    "function timelock() view returns (uint64)",
 ]);
 /** Mirrors TaskBoard.Status. */
 export const Status = { Open: 1, Hired: 2, Submitted: 3, Graded: 4, Disputed: 5, Paid: 6, Refunded: 7 };
@@ -82,17 +83,29 @@ function unquote(text) {
         return text;
     }
 }
-/** The parts of a URL long enough to be an API key: the path, the query and each of their segments. */
+/** The Basic credentials viem sends for a URL's user and password, which a server that echoes requests answers with. */
+function basicAuth(username, password) {
+    if (!username)
+        return [];
+    try {
+        return [btoa(`${decodeURIComponent(username)}:${decodeURIComponent(password)}`)];
+    }
+    catch {
+        return [];
+    }
+}
+/** The parts of a URL long enough to be an API key: its credentials, the path, the query and each of their segments. */
 function secretParts(url) {
     if (!URL.canParse(url))
         return [];
-    const { pathname, search } = new URL(url);
-    return [pathname + search, pathname, search, ...`${pathname}${search}`.split(/[/?&=]/)].filter((part) => part.length >= 8);
+    const { pathname, search, username, password } = new URL(url);
+    const path = pathname + search;
+    return [...basicAuth(username, password), username, password, path, pathname, search, ...path.split(/[/?&=]/)].filter((part) => part.length >= 8);
 }
 /**
- * One short line of an answer, without the RPC URL's path or query: an answer
- * can echo the path, which can hold an API key, and a web page is far longer
- * than one line.
+ * One short line of an answer, without the RPC URL's credentials, path or
+ * query: an answer can echo them, and they can hold an API key. A web page is
+ * far longer than one line.
  */
 function excerpt(details, url) {
     let line = unquote(details);
@@ -104,12 +117,41 @@ function excerpt(details, url) {
         .trim();
     return line.length > 160 ? `${line.slice(0, 159)}…` : line;
 }
+/** A 2xx answer in JSON that is no JSON-RPC reply, such as a REST API's. */
+class NotRpcError extends Error {
+    excerpt;
+    /** One short line of the answer, without the URL's secrets. */
+    constructor(excerpt) {
+        super("The answer is not a JSON-RPC reply");
+        this.excerpt = excerpt;
+    }
+}
+const isReply = (value) => typeof value === "object" && value !== null && ("result" in value || ("error" in value && typeof value.error === "object" && value.error !== null));
+/** viem reads an answer without a result as an empty one, and fails later on whatever needed it, such as "Block could not be found." */
+async function checkReply(response, url) {
+    if (!response.ok)
+        return;
+    const text = await response.clone().text();
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        // viem names an answer that is not JSON itself.
+        return;
+    }
+    // The excerpt is cut here, where the URL still holds the credentials viem leaves out of its errors.
+    if (!(Array.isArray(value) ? value.every(isReply) : isReply(value)))
+        throw new NotRpcError(excerpt(text, url));
+}
 /** A request that failed, named by the RPC's host and the status it answered with. */
 function requestFailure(request) {
     const host = hostOf(request.url);
     // viem passes on a 2xx answer that does not parse as JSON as the parser's error.
     if (request.cause instanceof SyntaxError)
         return `${host} answered, but not as an RPC`;
+    if (request.cause instanceof NotRpcError)
+        return `${host} answered, but not as an RPC (${request.cause.excerpt})`;
     const details = request.details ? excerpt(request.details, request.url) : "";
     const status = request instanceof TimeoutError ? undefined : request.status;
     if (status === undefined)
@@ -146,7 +188,7 @@ export async function unhealthy(service, fetcher = fetch) {
 }
 export function createChain(network, account, store = memoryStore()) {
     const chain = chainOf(network);
-    const transport = http(network.rpc, { timeout: 20_000, retryCount: 3 });
+    const transport = http(network.rpc, { timeout: 20_000, retryCount: 3, onFetchResponse: (response) => checkReply(response, network.rpc) });
     // BrainChain mines a block per transaction, so receipts are polled every second.
     const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
     const wallet = createWalletClient({ account, chain, transport });
@@ -260,6 +302,8 @@ export function createChain(network, account, store = memoryStore()) {
         held: () => client.readContract({ address: staking, abi: workerStakingAbi, functionName: "held", args: [account.address] }),
         allowed: () => client.readContract({ ...board, functionName: "workerAllowed", args: [account.address] }),
         bond: () => client.readContract({ address: bonds, abi: bondsAbi, functionName: "bond" }),
+        /** Seconds between Jev allowing a worker and the worker being hireable. */
+        timelock: () => client.readContract({ address: executor, abi: executorAbi, functionName: "timelock" }),
         async approve(token, spender, amount) {
             const current = await client.readContract({ address: token, abi: erc20Abi, functionName: "allowance", args: [account.address, spender] });
             if (current >= amount)

package/dist/claim.js

@@ -0,0 +1,99 @@
+import { createPublicClient, createWalletClient, defineChain, formatEther, http, parseAbi, parseEventLogs } from "viem";
+import { RECEIPT_MS } from "./chain.js";
+export const proofsIncomeAbi = parseAbi([
+    "function due(uint256 tokenId) view returns (uint256)",
+    "function claimMany(uint256[] tokenIds)",
+    "function claim(uint256 tokenId)",
+    "function proofs() view returns (address)",
+    "event Claimed(uint256 indexed tokenId, address indexed to, uint256 amount)",
+]);
+/** The most Proofs one claim pays for, which keeps the transaction far inside a block. */
+export const MAX_CLAIM = 200;
+const MULTICALL3 = "0xcA11bde05977b3631167028862bE2a173976CA11";
+export function createIncome(proofs, income, account) {
+    const chain = defineChain({
+        id: proofs.chainId,
+        name: proofs.name,
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpcUrls: { default: { http: [proofs.rpc] } },
+        contracts: { multicall3: { address: MULTICALL3 } },
+    });
+    const transport = http(proofs.rpc, { timeout: 20_000, retryCount: 3 });
+    const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
+    const wallet = createWalletClient({ account, chain, transport });
+    const router = { address: income, abi: proofsIncomeAbi };
+    return {
+        account: account.address,
+        due: (ids) => client.multicall({ contracts: ids.map((id) => ({ ...router, functionName: "due", args: [id] })), allowFailure: false }),
+        ethBalance: () => client.getBalance({ address: account.address }),
+        async claimMany(ids) {
+            const tx = await wallet.writeContract({ ...router, functionName: "claimMany", args: [ids] });
+            const receipt = await client.waitForTransactionReceipt({ hash: tx, timeout: RECEIPT_MS });
+            if (receipt.status !== "success")
+                throw new Error(`The claim ${tx} reverted`);
+            // A claim pays whoever holds the Proof when it lands, so a piece sold since the service listed it pays its buyer.
+            const paid = parseEventLogs({ abi: proofsIncomeAbi, eventName: "Claimed", args: { to: account.address }, logs: receipt.logs })
+                .filter((log) => log.address.toLowerCase() === income.toLowerCase())
+                .reduce((sum, log) => sum + log.args.amount, 0n);
+            return { tx, paid };
+        },
+    };
+}
+/** The Proofs the service says `owner` holds, by token id. */
+export async function ownedProofs(network, owner, fetcher = fetch) {
+    const host = new URL(network.service).host;
+    const response = await fetcher(`${network.service}/proofs/${network.chainId}/owned/${owner}`, { signal: AbortSignal.timeout(15_000) }).catch(() => {
+        throw new Error(`Could not reach the BrainChain service at ${host}`);
+    });
+    if (!response.ok) {
+        await response.body?.cancel();
+        if (response.status === 404)
+            throw new Error(`The BrainChain service at ${host} does not list Proofs by holder yet. Try claim again later.`);
+        throw new Error(`The BrainChain service at ${host} answered ${response.status} when asked for the worker's Proofs`);
+    }
+    const tokens = (await response.json().catch(() => undefined))?.tokens;
+    if (!Array.isArray(tokens) || !tokens.every((id) => typeof id === "string" && /^\d{1,78}$/.test(id))) {
+        throw new Error(`The BrainChain service at ${host} listed the worker's Proofs in a form claim cannot read`);
+    }
+    return [...new Set(tokens.map((id) => BigInt(id)))].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+const proofCount = (n) => `${n} Proof${n === 1 ? "" : "s"}`;
+function table(ids, dues) {
+    const width = Math.max("Proof".length, ...ids.map((id) => id.toString().length));
+    const row = (left, right) => `  ${left.padEnd(width)}  ${right}`;
+    const total = dues.reduce((sum, due) => sum + due, 0n);
+    return [row("Proof", "Due (ETH)"), ...ids.map((id, i) => row(id.toString(), formatEther(dues[i]))), row("Total", formatEther(total))].join("\n");
+}
+/**
+ * Pays the income due on the worker's Proofs with one claimMany from its key.
+ * `connect` is only called where Proofs earn income, so testnet needs no key.
+ */
+export async function claim(network, connect, options) {
+    const { log } = options;
+    const { income, name } = network.proofs;
+    if (income === undefined) {
+        return log(`Proofs on ${network.name} earn no income, so there is nothing to claim. Mainnet Proofs are claimed with BRAINCHAIN_NETWORK=mainnet.`);
+    }
+    const chain = connect(income);
+    const ids = await ownedProofs(network, chain.account, options.fetcher);
+    if (ids.length === 0)
+        return log(`The BrainChain service lists no Proofs held by ${chain.account} on ${name}, so there is nothing to claim.`);
+    const dues = await chain.due(ids);
+    log(table(ids, dues));
+    const owed = ids.map((id, i) => ({ id, due: dues[i] })).filter((proof) => proof.due > 0n);
+    if (owed.length === 0)
+        return log(`Nothing is due on the worker's ${proofCount(ids.length)} yet.`);
+    // A paid Proof is due nothing until the next distribution, so the next run claims what this one leaves.
+    const batch = owed.slice(0, MAX_CLAIM);
+    const amount = batch.reduce((sum, proof) => sum + proof.due, 0n);
+    const left = owed.length - batch.length;
+    const rest = left > 0 ? ` ${left} more Proof${left === 1 ? " has" : "s have"} income due: run claim again.` : "";
+    if (options.dry)
+        return log(`Dry run, nothing sent: claim would pay ${formatEther(amount)} ETH for ${proofCount(batch.length)}.${rest}`);
+    if ((await chain.ethBalance()) === 0n) {
+        throw new Error(`${chain.account} has no ETH on ${name} to pay gas for the claim. Send it a little ETH on ${name} and run claim again.`);
+    }
+    log(`Claiming ${formatEther(amount)} ETH for ${proofCount(batch.length)} on ${name}...`);
+    const { tx, paid } = await chain.claimMany(batch.map((proof) => proof.id));
+    log(`Paid ${formatEther(paid)} ETH to ${chain.account} (${tx}).${rest}`);
+}

package/dist/index.js

@@ -4,8 +4,9 @@ import { join as joinPath } from "node:path";
 import { formatEther, parseUnits } from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 import { createChain, faucetReopens, reason, unhealthy } from "./chain.js";
+import { claim, createIncome } from "./claim.js";
 import { resolveNetwork } from "./network.js";
-import { hireable, snapshot, stake, usdg, wallet, when } from "./standing.js";
+import { hireable, shortOfStake, snapshot, stake, usdg, wallet, when } from "./standing.js";
 import { fileStore, lock, stateDir } from "./state.js";
 import { createWork, shellCommand, stopLeftover, stopper } from "./work.js";
 const { version } = createRequire(import.meta.url)("../package.json");
@@ -15,22 +16,24 @@ Earn on BrainChain by doing tasks: stake, apply, and let Jev hire your agent.
 
 Usage:
   brainchain-worker new-key                 Print a fresh private key and its address.
-  brainchain-worker join --name <name> --about <text> [--price <tUSDG>]
+  brainchain-worker join --name <name> --about <text> [--price <USDG>]
                                             Stake the minimum and apply to take tasks. The name is at
                                             most 60 characters, the description at most 500.
   brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once]
                                             Do every task Jev hires you for: the command reads the
                                             task on stdin and prints the deliverable on stdout, within
                                             --timeout minutes (20 by default, at most 1440).
-  brainchain-worker status                  Stake, tBRAIN balance, application, record and earnings.
-  brainchain-worker price <tUSDG>           Change your asking price per task.
+  brainchain-worker status                  Stake, wallet, application, record and earnings.
+  brainchain-worker price <USDG>            Change your asking price per task.
+  brainchain-worker claim [--dry]           Claim the ETH due on the worker's Proofs, on Robinhood Chain.
+                                            --dry lists what is due and sends nothing.
   brainchain-worker leave                   Start unstaking (3-day cooldown).
   brainchain-worker withdraw                Withdraw stake once the cooldown has passed.
   brainchain-worker --version               Print the version.
 
 Environment:
   BRAINCHAIN_WORKER_KEY   Private key of the worker's wallet, 64 hex characters with or without 0x.
-  BRAINCHAIN_NETWORK      testnet (the default, and the only network open to outside workers today).
+  BRAINCHAIN_NETWORK      testnet (the default) or mainnet.
   BRAINCHAIN_RPC_URL      Overrides the network's RPC.
   BRAINCHAIN_SERVICE_URL  Overrides the BrainChain service that keeps results: https, or http on
                           localhost or 127.0.0.1.
@@ -51,6 +54,7 @@ const FLAGS = {
     price: {},
     leave: {},
     withdraw: {},
+    claim: { dry: true },
 };
 const POSITIONAL = { price: 1 };
 function parse(command, args) {
@@ -108,8 +112,7 @@ function price(value) {
 }
 const RUN = '`npx brainchain-worker run --exec "<command>"`';
 function noGas(chain, network) {
-    return new Error(`${chain.account} has no ETH on ${network.name} for gas. Get Robinhood Chain testnet ETH from https://faucet.testnet.chain.robinhood.com ` +
-        `and bridge some at ${network.explorer}; 0.001 ETH is plenty.`);
+    return new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas}; 0.001 ETH is plenty.`);
 }
 async function needGas(chain, network) {
     if ((await chain.ethBalance()) === 0n)
@@ -132,9 +135,11 @@ async function join(chain, network, values) {
     const { allowed, w, change, pending, open, applying, toStake } = await snapshot(chain);
     // A worker that has staked keeps its price unless --price changes it.
     const asking = requested ?? (w.registered ? w.price : price(DEFAULT_PRICE));
-    const [bond, balance] = await Promise.all([chain.bond(), chain.stakeBalance()]);
+    const [bond, balance, timelock] = await Promise.all([chain.bond(), chain.stakeBalance(), chain.timelock()]);
     const need = toStake + (applying ? bond : 0n);
     if (balance < need) {
+        if (network.buyStake)
+            throw new Error(shortOfStake(network, w, balance, need, await chain.now()));
         const [faucet, now] = await Promise.all([chain.faucet(), chain.now()]);
         const closed = (opensAt) => {
             const withdraw = now >= w.unlocksAt ? "run withdraw now" : `run withdraw after ${when(w.unlocksAt)}`;
@@ -175,7 +180,7 @@ async function join(chain, network, values) {
     await chain.approve(network.contracts.stakeToken, network.contracts.bonds, bond);
     const profile = Buffer.from(JSON.stringify({ name, about })).toString("base64");
     await chain.apply(`data:application/json;base64,${profile}`);
-    console.log("\nApplied. Jev usually decides within a few minutes. If it allows the worker, it can be hired once a 2-hour timelock passes.\n" +
+    console.log(`\nApplied. Jev usually decides within a few minutes. If it allows the worker, it can be hired once a ${Number(timelock) / 3600}-hour timelock passes.\n` +
         `Start ${RUN} now so it takes its first task as soon as it is hired, and follow\n` +
         "the application with `npx brainchain-worker status`. New workers are offered house tasks first, which BrainChain pays for.");
 }
@@ -189,7 +194,7 @@ async function status(chain, network) {
         chain.stakeBalance(),
         chain.bond(),
         // A stake token without a faucet, as on mainnet, leaves out what the faucet would give.
-        chain.faucet().catch(() => undefined),
+        network.buyStake ? undefined : chain.faucet().catch(() => undefined),
         chain.now(),
     ]);
     const { w, min } = s;
@@ -219,7 +224,7 @@ async function run(network, { key, account }, values, once) {
     lock(`${file}.lock`);
     const store = fileStore(`${file}.json`, network.contracts.taskBoard, (message) => log(`warning: ${message}`));
     // The lock rules out a live run, so a command still in the state was left by one that died.
-    stopLeftover(store, log);
+    await stopLeftover(store, log);
     const chain = createChain(network, account, store);
     const command = shellCommand(exec);
     // An idle stop keeps the exit code of a task that failed earlier in a --once pass.
@@ -238,10 +243,19 @@ async function run(network, { key, account }, values, once) {
     });
     for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
         process.on(signal, stop.signal);
-    const gas = await chain.ethBalance().catch((error) => {
+    let gas;
+    try {
+        gas = await chain.ethBalance();
+    }
+    catch (error) {
+        // The rest of a single pass reads the same RPC, so it would only fail the same way twice more.
+        if (once) {
+            log(`could not read the chain: ${reason(error)}`);
+            process.exitCode = 1;
+            return;
+        }
         log(`could not read the wallet's ETH balance: ${reason(error)}`);
-        return undefined;
-    });
+    }
     if (gas === 0n)
         throw noGas(chain, network);
     const [line, sick] = await Promise.all([
@@ -252,8 +266,12 @@ async function run(network, { key, account }, values, once) {
     if (sick)
         log(`warning: ${sick}`);
     if (once) {
-        const result = await work.round();
-        if (result.hired === 0 && result.delivered === 0)
+        const result = await work.round().catch((error) => {
+            log(`round failed: ${reason(error)}`);
+            process.exitCode = 1;
+            return undefined;
+        });
+        if (result?.hired === 0 && result.delivered === 0)
             log("no task is hired to this worker right now");
         return;
     }
@@ -282,6 +300,9 @@ async function main(argv) {
     }
     const { positional, values, switches } = parse(command, rest);
     const network = resolveNetwork(process.env);
+    if (command === "claim") {
+        return claim(network, (income) => createIncome(network.proofs, income, signer().account), { dry: switches.has("dry"), log: console.log });
+    }
     const worker = signer();
     if (command === "run")
         return run(network, worker, values, switches.has("once"));
@@ -293,7 +314,7 @@ async function main(argv) {
             return status(chain, network);
         case "price": {
             if (positional[0] === undefined)
-                throw new UsageError("Usage: brainchain-worker price <tUSDG>, such as price 0.25");
+                throw new UsageError(`Usage: brainchain-worker price <${network.bountySymbol}>, such as price 0.25`);
             const asking = price(positional[0]);
             if (!(await chain.stake()).registered)
                 throw new Error("This worker has not staked yet. Run join, which sets the price too.");

package/dist/network.js

@@ -1,5 +1,5 @@
-import { defineChain } from "viem";
-/** BrainChain testnet, release 3.1.0. Mainnet has no open staking yet. */
+import { defineChain, zeroAddress } from "viem";
+/** BrainChain testnet, release 3.1.0. */
 export const TESTNET = {
     name: "BrainChain testnet",
     chainId: 274630,
@@ -9,6 +9,8 @@ export const TESTNET = {
     explorer: "https://usebrainchain.com/testnet",
     stakeSymbol: "tBRAIN",
     bountySymbol: "tUSDG",
+    gas: "Get Robinhood Chain testnet ETH from https://faucet.testnet.chain.robinhood.com and bridge some at https://usebrainchain.com/testnet",
+    proofs: { chainId: 46630, name: "Robinhood Chain testnet", rpc: "https://rpc.testnet.chain.robinhood.com" },
     contracts: {
         taskBoard: "0xC74564F100e70F95346A6e399ebf1Ce14309C8B6",
         staking: "0xbdC08799D865DA79FE44a469de1FeaE84bb45059",
@@ -18,16 +20,49 @@ export const TESTNET = {
         bountyToken: "0xC4ec72794bF3Ce9ba1DE4B38085464c2eb0cDCf2",
     },
 };
-export function resolveNetwork(env) {
+// The 3.3.0 set. Its DecisionExecutor is new too, and applications are read from its events.
+export const MAINNET_TASK_BOARD = "0x72C890AA996bF7efcA88e3F5063B626560215160";
+export const MAINNET_WORKER_STAKING = "0x0fb02559e704549794EdF3FBBBe91DB88bB849ee";
+export const MAINNET_PROPOSAL_BONDS = "0x3806b71D46cd74d0Ac4BBC34577f311A0Fd06D14";
+export const MAINNET_DECISION_EXECUTOR = "0xA03614B09Dcc3813eD665a1693123f2a4f2C2483";
+const BRAIN = "0x3367085Eb6C79BfB0fCa4f1433ec77bFA8CB8a37";
+/** BrainChain mainnet, release 3.3.0. */
+export const MAINNET = {
+    name: "BrainChain",
+    chainId: 274663,
+    rpc: "https://rpc.usebrainchain.com",
+    service: "https://brain.usebrainchain.com",
+    fromBlock: 425n,
+    explorer: "https://usebrainchain.com",
+    stakeSymbol: "BRAIN",
+    bountySymbol: "USDG",
+    gas: "Bridge some from Robinhood Chain at https://usebrainchain.com/network",
+    buyStake: "Buy BRAIN on ripples.run (https://ripples.run/t/0xa06e3D898Bce92F67617E0Bfb640F153A5b65AB7) and bridge it to BrainChain through the " +
+        "Robinhood Chain gateway router 0x03f06a370A59AfB23de029F4EF5EA2F9EB034F96 (docs: https://docs.usebrainchain.com/bridging); " +
+        `the stake token on BrainChain is ${BRAIN}.`,
+    proofs: { chainId: 4663, name: "Robinhood Chain", rpc: "https://rpc.mainnet.chain.robinhood.com", income: "0xeb1b4168D4b87D3d9F0D64E13B7071251BBB63b7" },
+    contracts: {
+        taskBoard: MAINNET_TASK_BOARD,
+        staking: MAINNET_WORKER_STAKING,
+        bonds: MAINNET_PROPOSAL_BONDS,
+        executor: MAINNET_DECISION_EXECUTOR,
+        stakeToken: BRAIN,
+        bountyToken: "0x8eBFEce96c0AeF7Fd23425D846a302a552c8c451",
+    },
+};
+export function resolveNetwork(env, mainnet = MAINNET) {
     const name = (env.BRAINCHAIN_NETWORK?.trim() || "testnet").toLowerCase();
-    if (name === "mainnet")
-        throw new Error("Outside workers run on BrainChain testnet for now. Unset BRAINCHAIN_NETWORK or set it to testnet.");
-    if (name !== "testnet")
-        throw new Error(`BRAINCHAIN_NETWORK must be testnet, not "${env.BRAINCHAIN_NETWORK}"`);
+    if (name !== "testnet" && name !== "mainnet")
+        throw new Error(`BRAINCHAIN_NETWORK must be testnet or mainnet, not "${env.BRAINCHAIN_NETWORK}"`);
+    const { taskBoard, staking, bonds, executor } = mainnet.contracts;
+    // A set not yet deployed is left at the zero address, and the worker must never send to it.
+    if (name === "mainnet" && [taskBoard, staking, bonds, executor].includes(zeroAddress)) {
+        throw new Error("BrainChain mainnet is not open to outside workers yet. Unset BRAINCHAIN_NETWORK to work on testnet.");
+    }
     // Blank counts as unset, as for BRAINCHAIN_NETWORK.
     const rpc = env.BRAINCHAIN_RPC_URL?.trim();
     const service = env.BRAINCHAIN_SERVICE_URL?.trim();
-    return { ...TESTNET, ...(rpc ? { rpc: rpcURL(rpc) } : {}), ...(service ? { service: serviceURL(service) } : {}) };
+    return { ...(name === "mainnet" ? mainnet : TESTNET), ...(rpc ? { rpc: rpcURL(rpc) } : {}), ...(service ? { service: serviceURL(service) } : {}) };
 }
 /** The value is never echoed: an RPC URL can hold an API key, and a mistyped one still does. */
 function rpcURL(value) {

package/dist/standing.js

@@ -62,3 +62,9 @@ export function wallet(network, s, balance, bond, faucet, now) {
     const unstaking = s.w.unstaking > 0n ? `, and the ${stake(network, s.w.unstaking)} unstaking can be withdrawn ${now >= s.w.unlocksAt ? "now" : `after ${when(s.w.unlocksAt)}`}` : "";
     return `${has}; join needs ${stake(network, need)}${reopens}${unstaking}`;
 }
+/** What join says when the wallet holds too little of a stake token that has no faucet. */
+export function shortOfStake(network, w, balance, need, now) {
+    const withdraw = now >= w.unlocksAt ? "now" : `after ${when(w.unlocksAt)}`;
+    const unstaking = w.unstaking > 0n ? ` Or run withdraw ${withdraw} and join with the ${stake(network, w.unstaking)} it returns.` : "";
+    return `The wallet holds ${stake(network, balance)} of the ${stake(network, need)} join needs. ${network.buyStake}${unstaking}`;
+}

package/dist/state.js

@@ -6,10 +6,35 @@ const empty = (board) => ({ board: board.toLowerCase(), tasks: {}, done: [] });
 export function memoryStore(board = "") {
     return { state: empty(board), save: () => undefined };
 }
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+const isHash = (value) => typeof value === "string" && /^0x[0-9a-fA-F]{64}$/.test(value);
+const isIds = (value) => Array.isArray(value) && value.every((id) => typeof id === "string" && /^\d+$/.test(id));
+function isTask(value) {
+    if (!isObject(value) || !isCount(value.failures) || !isCount(value.nextAt))
+        return false;
+    if (value.result !== undefined && typeof value.result !== "string")
+        return false;
+    if (value.tx !== undefined && !isHash(value.tx))
+        return false;
+    return value.stored === undefined || (isObject(value.stored) && typeof value.stored.uri === "string" && isHash(value.stored.hash));
+}
+/** Whether a parsed file is a state this worker can go on from; any other shape fails every round that reads it. */
+function isState(value) {
+    if (!isObject(value) || typeof value.board !== "string" || !isObject(value.tasks) || !isIds(value.done))
+        return false;
+    if (!Object.values(value.tasks).every(isTask))
+        return false;
+    const { hired, command } = value;
+    if (hired !== undefined && !(isObject(hired) && isCount(hired.block) && isIds(hired.tasks)))
+        return false;
+    // Group 0 is this process's own and -1 is every process, so only a real command's group is signalled.
+    return command === undefined || (isObject(command) && isCount(command.pgid) && command.pgid > 1 && isCount(command.startedAt));
+}
 function parse(text) {
     try {
         const value = JSON.parse(text);
-        return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+        return isState(value) ? value : undefined;
     }
     catch {
         return undefined;
@@ -28,12 +53,12 @@ export function fileStore(file, board, warn = console.warn) {
     }
     const saved = text === undefined ? undefined : parse(text);
     if (saved?.board === state.board)
-        state = { ...state, ...saved, tasks: saved.tasks ?? {}, done: saved.done ?? [] };
+        state = saved;
     if (text !== undefined && saved === undefined) {
         // Refusing to start would turn one bad file into a crash loop under a supervisor.
         const aside = `${file}.corrupt-${new Date().toISOString().replace(/\.\d+Z$/, "Z").replace(/[-:]/g, "")}`;
         renameSync(file, aside);
-        warn(`${file} was not valid JSON, so it was moved to ${aside} and this run starts with no saved work`);
+        warn(`${file} could not be read as saved worker state, so it was moved to ${aside} and this run starts with no saved work`);
     }
     return {
         state,

package/dist/work.js

@@ -79,32 +79,72 @@ function signalGroup(pid, signal) {
             throw error;
     }
 }
+/** One field of `ps` for a process, or undefined when it is gone or ps cannot tell. */
+function ps(pid, field) {
+    const result = spawnSync("ps", ["-o", `${field}=`, "-p", String(pid)], { encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
 /** When a process started, in ms since the epoch, or undefined when it is gone or ps cannot tell. */
 function startTime(pid) {
-    const ps = spawnSync("ps", ["-o", "etime=", "-p", String(pid)], { encoding: "utf8" });
-    const elapsed = /^\s*(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)\s*$/.exec(ps.stdout ?? "");
-    if (ps.status !== 0 || !elapsed)
+    const elapsed = /^(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)$/.exec(ps(pid, "etime") ?? "");
+    if (!elapsed)
         return undefined;
     const [days, hours, minutes, seconds] = elapsed.slice(1).map((part) => Number(part ?? 0));
     return Date.now() - (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
 }
+function exists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Whether a process group still has a process this user can signal. */
+function groupAlive(pgid) {
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a group lives on without its leader, as when the shell exits while
+ * what it started runs on. Its id is not reused while the group lives, so only
+ * this run's own group could match after a reuse, and ps rules that out.
+ */
+function orphaned(pgid) {
+    if (exists(pgid) || !groupAlive(pgid))
+        return false;
+    const own = ps(process.pid, "pgid");
+    return own !== undefined && own !== String(pgid);
+}
 /**
  * Stops the command an earlier run left running when it died, such as on
- * SIGKILL, so a restart never works on the same task twice at once.
+ * SIGKILL, so a restart never works on the same task twice at once. It gets
+ * SIGTERM first and SIGKILL `graceMs` later.
  */
-export function stopLeftover(store, log) {
+export async function stopLeftover(store, log, graceMs = 3_000) {
     const left = store.state.command;
     if (left === undefined)
         return;
     delete store.state.command;
     store.save();
+    const { pgid } = left;
     // A pid is not reused while its process lives, so a live process with it that started when the command did is the command.
     // Its command line proves nothing: the shell execs a simple command, so it shows the program's arguments, not --exec.
-    const started = startTime(left.pgid);
-    if (started === undefined || Math.abs(started - left.startedAt) > 5_000)
+    const started = startTime(pgid);
+    if (started === undefined ? !orphaned(pgid) : Math.abs(started - left.startedAt) > 5_000)
         return;
-    signalGroup(left.pgid, "SIGKILL");
-    log(`stopped the command an earlier run left running (process group ${left.pgid})`);
+    signalGroup(pgid, "SIGTERM");
+    for (const end = Date.now() + graceMs; Date.now() < end && groupAlive(pgid);)
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    if (groupAlive(pgid))
+        signalGroup(pgid, "SIGKILL");
+    log(`stopped the command an earlier run left running (process group ${pgid})`);
 }
 /**
  * Runs a shell command with the input on stdin and takes its stdout as the
@@ -206,13 +246,14 @@ export function stopper(options) {
                 return options.exit(129);
             }
             const now = Date.now();
-            if (last?.signal === signal && now - last.at < ECHO_MS)
+            const previous = last;
+            if (previous?.signal === signal && now - previous.at < ECHO_MS)
                 return;
             last = { signal, at: now };
             const name = signal === "SIGINT" ? "Ctrl-C" : signal;
             if (stopping) {
                 options.kill();
-                options.log(`${name} again: stopping now`);
+                options.log(`${name}${previous?.signal === signal ? " again" : ""}: stopping now`);
                 return options.exit(signal === "SIGINT" ? 130 : 143);
             }
             if (!options.busy()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Earn on BrainChain: stake, apply, and do the tasks Jev hires your agent for, with any command that reads a task and prints the work.",
   "license": "MIT",
   "author": "BrainChain <hello@usebrainchain.com>",