brainchain-worker 0.12.2 → 0.13.0

package/dist/cli.js

@@ -1,20 +1,21 @@
 import { createRequire } from "node:module";
 import { verifyDecision } from "brainchain-verify";
-import { createPublicClient } from "viem";
-import { formatEther, parseUnits } from "viem";
+import { createPublicClient, http } from "viem";
+import { parseUnits } from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
-import { brainchainTransport, createChain, faucetReopens, reason, unhealthy } from "./chain.js";
+import { brainchainTransport, createChain, faucetReopens, reason, requireChainId, unhealthy } from "./chain.js";
 import { assetOf, bridge, createBridgeChain } from "./bridge.js";
 import { claim, createIncome } from "./claim.js";
 import { createProofMinter, createProofsChain, MAX_MINT, mint } from "./mint.js";
 import { chainOf, resolveNetwork } from "./network.js";
 import { buildCall, caseURI, createProposals, proposal, propose } from "./propose.js";
-import { hireable, shortOfStake, snapshot, stake, usdg, wallet, when } from "./standing.js";
+import { ethNeeded, gasLine, hireable, joinLimits, shortOfGas, shortOfStake, snapshot, stake, usdg, wallet, when } from "./standing.js";
 import { openStore, readWatched, writeWatched } from "./state.js";
+import { clearKeyFromEnvironment, keyConfigured, keyText, writeKeyFile } from "./key.js";
 import { createCreditChain, credit } from "./credit.js";
 import { appeal, createDisputeChain, dispute } from "./dispute.js";
-import { createReporter, createWatch, createWatchChain } from "./watch.js";
-import { createWork, firstProgram, programFound, shellCommand, stopLeftover, stopper } from "./work.js";
+import { createReporter, createWatch, createWatchChain, requireWatcher } from "./watch.js";
+import { createWork, firstProgram, npxUnderSupervisor, programFound, shellCommand, stopLeftover, stopper, watchStarter } from "./work.js";
 /** How many of the latest decisions a first watch --once checks. */
 const FIRST_RUN_DECISIONS = 10n;
 /** A published record's bytes as the service serves them, capped at a megabyte. */
@@ -28,71 +29,81 @@ async function fetchRecord(uri) {
     return bytes;
 }
 const { version } = createRequire(import.meta.url)("../package.json");
-const USAGE = `brainchain-worker ${version}
-
-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 <USDG>] [--agent-id <id>]
+/** Each command's lines in the usage text, in the order the text lists them. */
+const COMMAND_USAGE = {
+    "new-key": `  brainchain-worker new-key [--file <path>] Print a fresh private key and its address. --file writes the key
+                                            to a new file only you can read and prints only the address.`,
+    join: `  brainchain-worker join --name <name> --about <text> [--price <USDG>] [--agent-id <id>]
                                             Stake the minimum and apply to take tasks. The name is at
                                             most 60 characters, the description at most 500. --agent-id
                                             (mainnet) names the worker's ERC-8004 agent on Robinhood Chain,
-                                            so its BrainChain record is written to that identity.
-  brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once] [--no-mint]
+                                            so its BrainChain record is written to that identity.`,
+    run: `  brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once] [--no-mint]
                                             Do every task Jev hires the worker for: the command reads the
                                             task on stdin and prints the deliverable on stdout, within
                                             --timeout minutes (20 by default, at most 1440). The worker
-                                            mints the Proof of each task it is paid for, unless --no-mint.
-  brainchain-worker status                  Stake, wallet, application, record and earnings.
-  brainchain-worker price <USDG>            Change your asking price per task.
-  brainchain-worker mint [--count <n>] [--dry]
+                                            mints the Proof of each task it is paid for, unless --no-mint.`,
+    status: `  brainchain-worker status                  Stake, wallet, application, record and earnings.`,
+    price: `  brainchain-worker price <USDG>            Change your asking price per task.`,
+    mint: `  brainchain-worker mint [--count <n>] [--dry]
                                             Mint a Proof for each paid task waiting for one, up to 10 or
-                                            --count, at 0.001 WETH each on Robinhood Chain. --dry sends nothing.
-  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 bridge --eth <ETH> | --stake <amount> | --bounty <amount> [--dry]
+                                            --count, at 0.001 WETH each on Robinhood Chain. --dry sends nothing.`,
+    claim: `  brainchain-worker claim [--dry]           Claim the ETH due on the worker's Proofs, on Robinhood Chain.
+                                            --dry lists what is due and sends nothing.`,
+    bridge: `  brainchain-worker bridge --eth <ETH> | --stake <amount> | --bounty <amount> [--dry]
                                             Move ETH for gas, the stake token or the bounty token from Robinhood
                                             Chain to the worker's address on BrainChain; it arrives in about a
-                                            minute. --dry checks the balances and sends nothing.
-  brainchain-worker propose --target board|executor|registry --call <function> --args '<JSON array>'
+                                            minute. --eth works on both networks, the tokens on mainnet. --dry
+                                            checks the balances and sends nothing.`,
+    propose: `  brainchain-worker propose --target board|executor|registry --call <function> --args '<JSON array>'
                             --title <text> --rationale <text> [--current <text>] [--proposed <text>] [--dry]
                                             Bond the stake token and propose a change to BrainChain for Jev to
                                             decide. --data <hex> gives the call as raw calldata instead of
-                                            --call and --args. --dry checks the call and sends nothing.
-  brainchain-worker proposal <id>           Where a proposal stands: waiting, adopted and when it runs, or kept.
-  brainchain-worker watch [--veto] [--once]
+                                            --call and --args. --dry checks the call and sends nothing.`,
+    proposal: `  brainchain-worker proposal <id>           Where a proposal stands: waiting, adopted and when it runs, or kept.`,
+    watch: `  brainchain-worker watch [--veto] [--once]
                                             Watch the chain: judge every queued change against the constitution
                                             and re-verify every new decision, reporting what disagrees. With the
                                             worker's key set, each round is reported to the service toward the
                                             worker's watchtower mark. --veto vetoes a change that crosses a floor
                                             through the guardian gate, when the worker's key is the gate's
                                             watcher. --once reads one round, checks the decisions added since
-                                            the last --once (the latest 10 on the first) and exits 1 on a finding.
-  brainchain-worker credit --agent-id <id> [--premium <bps>]
+                                            the last --once (the latest 10 on the first) and exits 1 on a finding
+                                            or a decision it could not check.`,
+    credit: `  brainchain-worker credit --agent-id <id> [--premium <bps>]
                                             Ask BrainChain to back a credit line for the worker's ERC-8004 agent
                                             on Priors (priors.trade): signs Priors' consent with the agent owner's
                                             key and sends it. The line opens once the worker is proven on the
                                             board. --premium is the most the sponsor may charge per 30 days, in
-                                            basis points (default 0, at most 200). Mainnet only.
-  brainchain-worker dispute <task>          Dispute the grade on a task the worker delivered, within the dispute
-                                            window. Jev rules on it; a confident ruling decides.
-  brainchain-worker appeal <task>           Appeal the ruling on a task, when it went against the worker, within the
+                                            basis points (default 0, at most 200). Mainnet only.`,
+    dispute: `  brainchain-worker dispute <task>          Dispute the grade on a task the worker delivered, within the dispute
+                                            window. Jev rules on it; a confident ruling decides.`,
+    appeal: `  brainchain-worker appeal <task>           Appeal the ruling on a task, when it went against the worker, within the
                                             appeal window, with the bond the task's terms fix (a quarter of the
                                             bounty). Jev rules again; the bond comes back unless Jev confidently
-                                            rules the same way. Testnet only for now.
-  brainchain-worker leave                   Start unstaking (3-day cooldown).
-  brainchain-worker withdraw                Withdraw stake once the cooldown has passed.
+                                            rules the same way. Testnet only for now.`,
+    leave: `  brainchain-worker leave                   Start unstaking (3-day cooldown).`,
+    withdraw: `  brainchain-worker withdraw                Withdraw stake once the cooldown has passed.`,
+};
+const USAGE = `brainchain-worker ${version}
+
+Earn on BrainChain by doing tasks: stake, apply, and let Jev hire your agent.
+
+Usage:
+${Object.values(COMMAND_USAGE).join("\n")}
   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_WORKER_KEY_FILE
+                          A file that holds the key, used instead, so no process's environment holds it.
   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.
 
 The command sees the worker's environment without any BRAINCHAIN_ variable, plus BRAINCHAIN_TASK_ID.
+It runs as your user, so it can reach what your user can: see "Your command" in the README.
 Unfinished work is kept in ~/.config/brainchain-worker/<address>.<network>.json across restarts,
 and one run at a time works for each address on each network.
 
@@ -102,6 +113,7 @@ export class UsageError extends Error {
 }
 /** The flags each command takes; `true` marks a switch, which takes no value. */
 const FLAGS = {
+    "new-key": { file: false },
     join: { name: false, about: false, price: false, "agent-id": false },
     run: { exec: false, format: false, timeout: false, once: true, "no-mint": true },
     status: {},
@@ -119,8 +131,10 @@ const FLAGS = {
     appeal: {},
 };
 const POSITIONAL = { price: 1, proposal: 1, dispute: 1, appeal: 1 };
+/** A command's flags; a name from argv can match what every object inherits, such as constructor. */
+const flagsOf = (command) => (Object.hasOwn(FLAGS, command) ? FLAGS[command] : undefined);
 export function parse(command, args) {
-    const known = FLAGS[command];
+    const known = flagsOf(command);
     if (known === undefined)
         throw new UsageError(`Unknown command "${command}" (see brainchain-worker --help)`);
     const positional = [];
@@ -133,7 +147,7 @@ export function parse(command, args) {
             continue;
         }
         const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
-        const isSwitch = known[name];
+        const isSwitch = Object.hasOwn(known, name) ? known[name] : undefined;
         if (isSwitch === undefined)
             throw new UsageError(`The ${command} command has no --${name} flag (see brainchain-worker --help)`);
         if (isSwitch) {
@@ -151,19 +165,39 @@ export function parse(command, args) {
         throw new UsageError(`Unexpected "${positional.at(-1)}" (see brainchain-worker --help)`);
     return { positional, values, switches };
 }
+/**
+ * Whether the arguments ask for help as a flag of their own. It reads them as
+ * parse does: `--about -h` is a description, and a flag's value never starts
+ * with --, so `--about --help` still asks.
+ */
+export function asksHelp(command, args) {
+    const known = flagsOf(command) ?? {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            return true;
+        if (arg.startsWith("--") && !arg.includes("=") && Object.hasOwn(known, arg.slice(2)) && known[arg.slice(2)] === false && !args[i + 1]?.startsWith("--"))
+            i++;
+    }
+    return false;
+}
+/** One command's usage lines, or the whole text for anything else. A name from argv can match what every object inherits, such as constructor. */
+export function usage(command) {
+    return command !== undefined && Object.hasOwn(COMMAND_USAGE, command) ? `Usage:\n${COMMAND_USAGE[command]}` : USAGE;
+}
 function signer() {
-    const raw = process.env.BRAINCHAIN_WORKER_KEY?.trim();
+    const raw = keyText()?.trim();
     if (!raw)
-        throw new Error("Set BRAINCHAIN_WORKER_KEY to the worker's private key. `npx brainchain-worker new-key` makes one.");
+        throw new Error("Set BRAINCHAIN_WORKER_KEY to the worker's private key, or BRAINCHAIN_WORKER_KEY_FILE to a file that holds it. `npx brainchain-worker new-key` makes one.");
     const hex = raw.startsWith("0x") ? raw.slice(2) : raw;
     if (!/^[0-9a-fA-F]{64}$/.test(hex))
-        throw new Error("BRAINCHAIN_WORKER_KEY must be 64 hex characters, with or without 0x");
+        throw new Error("The worker's key must be 64 hex characters, with or without 0x");
     const key = `0x${hex.toLowerCase()}`;
     try {
         return { key, account: privateKeyToAccount(key) };
     }
     catch {
-        throw new Error("BRAINCHAIN_WORKER_KEY is not a valid private key. `npx brainchain-worker new-key` makes one.");
+        throw new Error("The worker's key is not a valid private key. `npx brainchain-worker new-key` makes one.");
     }
 }
 const DEFAULT_PRICE = "0.20";
@@ -175,8 +209,9 @@ function price(value) {
     return parseUnits(value, 6);
 }
 const RUN = '`npx brainchain-worker run --exec "<command>"`';
+const KEEP_RUNNING = "https://github.com/usebrainchain/brainchain-worker#keep-it-running";
 function noGas(chain, network) {
-    return new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas}; 0.001 ETH is plenty.`);
+    return new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas}.`);
 }
 async function needGas(chain, network) {
     if ((await chain.ethBalance()) === 0n)
@@ -201,11 +236,8 @@ export async function join(chain, network, values) {
         throw new UsageError("--agent-id works on mainnet only, where BrainChain writes each worker's record to its ERC-8004 identity");
     }
     const requested = values.has("price") ? price(values.get("price")) : undefined;
-    const gas = await chain.ethBalance();
-    // The faucet covers the stake where there is one, so gas is all a new worker can lack there.
-    if (gas === 0n && !network.buyStake)
-        throw noGas(chain, network);
-    const { allowed, w, change, pending, open, applying, toStake } = await snapshot(chain);
+    const standing = await snapshot(chain);
+    const { allowed, w, change, pending, open, applying, toStake } = standing;
     // The agent id travels in the application, and Jev keeps the profile it decided on.
     if (agentId !== undefined) {
         if (allowed || (change && pending) || open) {
@@ -220,15 +252,19 @@ export async function join(chain, network, values) {
     }
     // 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, timelock] = await Promise.all([chain.bond(), chain.stakeBalance(), chain.timelock()]);
+    const [gas, gasPrice, bond, balance, timelock] = await Promise.all([chain.ethBalance(), chain.gasPrice(), chain.bond(), chain.stakeBalance(), chain.timelock()]);
     const need = toStake + (applying ? bond : 0n);
+    const claims = balance < need && !network.buyStake;
+    // Checked before anything is sent: a wallet that runs out partway leaves the stake placed and the application unsent.
+    const gasNeed = ethNeeded(joinLimits(standing, claims, toStake === 0n && w.price !== asking), gasPrice);
+    const lacksGas = gas < gasNeed ? `${chain.account} holds ${shortOfGas(network, gas, gasNeed, "join")}` : undefined;
     if (balance < need && network.buyStake) {
         const short = shortOfStake(network, w, balance, need, await chain.now());
         // Both needs at once, so a new worker does not bridge ETH only to learn it needs the stake token too.
-        throw new Error(gas === 0n ? `${noGas(chain, network).message}\n${short}` : short);
+        throw new Error(lacksGas ? `${lacksGas}\n${short}` : short);
     }
-    if (gas === 0n)
-        throw noGas(chain, network);
+    if (lacksGas)
+        throw new Error(lacksGas);
     if (balance < need) {
         const [faucet, now] = await Promise.all([chain.faucet(), chain.now()]);
         const closed = (opensAt) => {
@@ -275,8 +311,9 @@ export async function join(chain, network, values) {
         "the application with `npx brainchain-worker status`. New workers are offered house tasks first, which BrainChain pays for.");
 }
 async function status(chain, network) {
-    const [gas, s, held, record, bountyBalance, stakeBalance, bond, faucet, now] = await Promise.all([
+    const [gas, gasPrice, s, held, record, bountyBalance, stakeBalance, bond, faucet, now] = await Promise.all([
         chain.ethBalance(),
+        chain.gasPrice(),
         snapshot(chain),
         chain.held(),
         chain.record(),
@@ -296,7 +333,7 @@ async function status(chain, network) {
   Price     ${w.registered ? `${usdg(network, w.price)} per task` : "not set until you join"}
   Record    ${record.accepted} accepted, ${record.refunded} refunded, ${record.inFlight} in flight${held > 0 ? " (stake held until they settle)" : ""}
   Earned    ${usdg(network, record.earned)} after fees; wallet holds ${usdg(network, bountyBalance)}
-  Gas       ${formatEther(gas)} ETH`);
+  Gas       ${gasLine(network, s, gas, gasPrice, !network.buyStake && stakeBalance < s.toStake + (s.applying ? bond : 0n))}`);
 }
 async function run(network, { key, account }, values, once, mints) {
     const exec = values.get("exec");
@@ -310,6 +347,7 @@ async function run(network, { key, account }, values, once, mints) {
         throw new UsageError("--timeout is the most minutes the command may spend on one task: more than 0, at most 1440, and 20 by default");
     }
     const log = (message) => console.log(`${new Date().toISOString().slice(0, 19)}Z ${message}`);
+    clearKeyFromEnvironment(key, log);
     const program = firstProgram(exec);
     if (program && !programFound(program))
         log(`warning: the shell cannot find ${program}, so --exec will fail when the worker is hired`);
@@ -336,6 +374,14 @@ async function run(network, { key, account }, values, once, mints) {
     });
     for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
         process.on(signal, stop.signal);
+    if (process.env.npm_execpath !== undefined) {
+        watchStarter(() => {
+            log("npx, which started this run, is gone, so this counts as a stop");
+            stop.signal("SIGTERM");
+        });
+        if (npxUnderSupervisor())
+            log(`warning: a supervisor's stop reaches npx and ends this run with its task. For a stop that lets the task finish, install the package and start the brainchain-worker binary: ${KEEP_RUNNING}`);
+    }
     let gas;
     try {
         gas = await chain.ethBalance();
@@ -384,10 +430,20 @@ async function run(network, { key, account }, values, once, mints) {
     await minting;
     log("stopped");
 }
+/** What watch says at start. Without a key it names no address: the one its reads go through is a throwaway. */
+export function watching(network, address, veto) {
+    if (address === undefined)
+        return `watching ${network.name} (read-only, no key)`;
+    return `watching ${network.name} as ${address}${veto ? ", vetoing through the guardian gate" : ""}, reporting rounds to the service`;
+}
 export async function main(argv) {
     const [command, ...rest] = argv;
-    if (command === undefined || command === "help" || argv.includes("--help") || argv.includes("-h")) {
-        console.log(USAGE);
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+        console.log(usage(rest[0]));
+        return;
+    }
+    if (asksHelp(command, rest)) {
+        console.log(usage(command));
         return;
     }
     if (command === "--version" || command === "-v") {
@@ -395,12 +451,22 @@ export async function main(argv) {
         return;
     }
     if (command === "new-key") {
+        const file = parse(command, rest).values.get("file");
         const fresh = generatePrivateKey();
-        console.log(`BRAINCHAIN_WORKER_KEY=${fresh}\naddress ${privateKeyToAccount(fresh).address}\nKeep the key secret; it controls the stake and the earnings.`);
+        const { address } = privateKeyToAccount(fresh);
+        if (file === undefined) {
+            console.log(`BRAINCHAIN_WORKER_KEY=${fresh}\naddress ${address}\nKeep the key secret; it controls the stake and the earnings.`);
+            return;
+        }
+        writeKeyFile(file, fresh);
+        console.log(`BRAINCHAIN_WORKER_KEY_FILE=${file}\naddress ${address}\nKeep the file secret; it controls the stake and the earnings.`);
         return;
     }
     const { positional, values, switches } = parse(command, rest);
     const network = resolveNetwork(process.env);
+    if (process.env.BRAINCHAIN_RPC_URL?.trim()) {
+        await requireChainId(network, () => createPublicClient({ transport: http(network.rpc, { timeout: 10_000, retryCount: 0 }) }).getChainId());
+    }
     if (command === "claim") {
         return claim(network, (income) => createIncome(network.proofs, income, signer().account), { dry: switches.has("dry"), log: console.log });
     }
@@ -438,7 +504,7 @@ export async function main(argv) {
         const veto = switches.has("veto");
         const once = switches.has("once");
         // Judging changes needs no key; vetoing and reporting do. A reader stands in for the signer otherwise.
-        const keyed = veto || Boolean(process.env.BRAINCHAIN_WORKER_KEY?.trim());
+        const keyed = veto || keyConfigured();
         const account = keyed ? signer().account : privateKeyToAccount(generatePrivateKey());
         const client = createPublicClient({ chain: chainOf(network), transport: brainchainTransport(network) });
         const { taskBoard, executor, log } = network.contracts;
@@ -454,9 +520,10 @@ export async function main(argv) {
             const record = findings.length === 0 && keyed && report.payloadURI ? await fetchRecord(report.payloadURI).catch(() => undefined) : undefined;
             return { findings, ...(record ? { record } : {}) };
         };
+        const chain = createWatchChain(network, account);
         const watch = createWatch({
             network,
-            chain: createWatchChain(network, account),
+            chain,
             verify,
             ...(keyed ? { report: createReporter(network, account) } : {}),
             veto,
@@ -466,10 +533,12 @@ export async function main(argv) {
         });
         if (veto && !network.contracts.gate)
             throw new UsageError(`${network.name} has no guardian gate yet, so there is nothing to veto through`);
-        console.log(`watching ${network.name} as ${account.address}${veto ? ", vetoing through the guardian gate" : ""}${keyed ? ", reporting rounds to the service" : ""}`);
+        if (veto)
+            await requireWatcher(chain, console.log);
+        console.log(watching(network, keyed ? account.address : undefined, veto));
         if (once) {
-            const { findings } = await watch.round();
-            if (findings > 0)
+            const { findings, incomplete } = await watch.round();
+            if (findings > 0 || incomplete)
                 process.exitCode = 1;
             return;
         }
@@ -483,7 +552,7 @@ export async function main(argv) {
         if (id === undefined || !/^\d{1,18}$/.test(id) || id === "0")
             throw new UsageError("Usage: brainchain-worker proposal <id>, such as proposal 2");
         // Reading a proposal needs no key, so any address stands in for the signer.
-        const reader = process.env.BRAINCHAIN_WORKER_KEY?.trim() ? signer().account : privateKeyToAccount(generatePrivateKey());
+        const reader = keyConfigured() ? signer().account : privateKeyToAccount(generatePrivateKey());
         return proposal(network, createProposals(network, reader), BigInt(id), console.log);
     }
     const worker = signer();
@@ -517,8 +586,11 @@ export async function main(argv) {
             if (positional[0] === undefined)
                 throw new UsageError("Usage: brainchain-worker price <USDG>, such as price 0.25");
             const asking = price(positional[0]);
-            if (!(await chain.stake()).registered)
+            const w = await chain.stake();
+            if (!w.registered)
                 throw new Error("This worker has not staked yet. Run join, which sets the price too.");
+            if (w.price === asking)
+                return console.log(`The price is already ${usdg(network, asking)} per task.`);
             await needGas(chain, network);
             await chain.setPrice(asking);
             console.log(`Price set to ${usdg(network, asking)} per task.`);

package/dist/dispute.js

@@ -2,8 +2,7 @@ import { createPublicClient, createWalletClient, formatUnits, parseAbi } from "v
 import { brainchainTransport, erc20Abi, RECEIPT_MS, Status } from "./chain.js";
 import { chainOf } from "./network.js";
 /** TaskBoard statuses from set 3.5.0 on: a ruling that waits out its appeal window, and one under appeal. */
-export const Ruled = 8;
-export const Appealed = 9;
+export const { Ruled, Appealed } = Status;
 const boardAbi = 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, uint64 submittedAt, uint64 gradedAt, uint64 disputedAt, uint64 postedAt, address payee, address feeRecipient, uint16 feeBps, uint16 hireThresholdBps, uint16 gradeThresholdBps, uint16 ruleThresholdBps, uint64 gradeWindow, uint64 disputeWindow, uint64 ruleWindow))",
     "function appealOf(uint256 id) view returns ((uint64 window, uint16 bondBps, uint64 ruledAt, bool pays, bool confident, address appellant, uint128 bond, uint64 appealedAt))",

package/dist/key.js

@@ -0,0 +1,92 @@
+import { randomBytes } from "node:crypto";
+import { accessSync, constants, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { stateDir } from "./state.js";
+/** Names the file a run passes its key through when it restarts itself without the key in its environment. */
+const HANDOFF = "BRAINCHAIN_WORKER_KEY_HANDOFF";
+const HANDOFF_NAME = /^brainchain-worker-key-[0-9a-f]{32}$/;
+const expandHome = (path) => (path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path);
+/** Whether the environment names a key, without reading it: a key file can be a pipe, which reads only once. */
+export const keyConfigured = (env = process.env) => Boolean(env[HANDOFF] || env.BRAINCHAIN_WORKER_KEY?.trim() || env.BRAINCHAIN_WORKER_KEY_FILE?.trim());
+function fromFile(path, warn) {
+    const file = expandHome(path);
+    let text;
+    try {
+        const stat = statSync(file);
+        if (stat.isFile() && (stat.mode & 0o077) !== 0)
+            warn(`warning: other users can read ${file}; run chmod 600 on it`);
+        text = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new Error(`BRAINCHAIN_WORKER_KEY_FILE names ${file}, which could not be read (${error.code ?? "unknown error"})`);
+    }
+    // The file holds the key alone, or the line new-key prints.
+    return /^\s*(?:BRAINCHAIN_WORKER_KEY=)?(\S+)\s*$/m.exec(text)?.[1] ?? "";
+}
+/** The text of the worker's key, from wherever the environment says it is; undefined when it names none. */
+export function keyText(env = process.env, warn = console.warn) {
+    const handoff = env[HANDOFF];
+    if (handoff !== undefined) {
+        delete env[HANDOFF];
+        if (!HANDOFF_NAME.test(basename(handoff)))
+            throw new Error(`${HANDOFF} is for the worker's own use; unset it`);
+        const text = readFileSync(handoff, "utf8");
+        rmSync(handoff, { force: true });
+        return text;
+    }
+    const inline = env.BRAINCHAIN_WORKER_KEY?.trim();
+    const file = env.BRAINCHAIN_WORKER_KEY_FILE?.trim();
+    if (inline && file)
+        throw new Error("Set BRAINCHAIN_WORKER_KEY or BRAINCHAIN_WORKER_KEY_FILE, not both");
+    return file ? fromFile(file, warn) : inline || undefined;
+}
+/** Writes a new key to a file only its owner can read; an existing file is left alone, since it may hold a wallet's only key. */
+export function writeKeyFile(path, key) {
+    const file = expandHome(path);
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    try {
+        writeFileSync(file, `${key}\n`, { flag: "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error(`${file} already exists, and new-key never replaces a key`);
+        throw error;
+    }
+}
+/** Memory rather than disk where the system offers it. The file lives for the milliseconds a restart takes. */
+function handoffDir() {
+    try {
+        accessSync("/dev/shm", constants.W_OK);
+        return "/dev/shm";
+    }
+    catch {
+        mkdirSync(stateDir(), { recursive: true, mode: 0o700 });
+        return stateDir();
+    }
+}
+/**
+ * Restarts this process in place without BRAINCHAIN_WORKER_KEY in its
+ * environment. Deleting the variable would not do: `ps eww` and /proc read the
+ * block the process started with, and a command run by `run` can reach both.
+ * The pid, the output and the supervisor's view all stay as they were. Returns
+ * when there is nothing to clear, or when it could not be cleared.
+ */
+export function clearKeyFromEnvironment(key, warn, env = process.env, execve = process.execve) {
+    if (env.BRAINCHAIN_WORKER_KEY === undefined)
+        return;
+    if (typeof execve !== "function")
+        return warn(`warning: Node.js ${process.version} cannot clear the key from this process's environment; Node.js 22.15 or later can`);
+    const { BRAINCHAIN_WORKER_KEY: _, ...rest } = env;
+    let file;
+    try {
+        file = join(handoffDir(), `brainchain-worker-key-${randomBytes(16).toString("hex")}`);
+        writeFileSync(file, key, { flag: "wx", mode: 0o600 });
+        execve(process.execPath, [process.execPath, ...process.execArgv, process.argv[1], ...process.argv.slice(2)], { ...rest, [HANDOFF]: file });
+    }
+    catch (error) {
+        if (file !== undefined)
+            rmSync(file, { force: true });
+        warn(`warning: could not clear the key from this process's environment (${error.message})`);
+    }
+}

package/dist/network.js

@@ -1,5 +1,5 @@
 import { defineChain, fallback, http, zeroAddress } from "viem";
-/** BrainChain testnet, release 3.4.0. */
+/** BrainChain testnet, release 3.5.0. */
 export const TESTNET = {
     id: "testnet",
     name: "BrainChain testnet",
@@ -10,7 +10,7 @@ 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",
+    gas: "Get Robinhood Chain testnet ETH from https://faucet.testnet.chain.robinhood.com, then move it here with `npx brainchain-worker bridge --eth 0.001`",
     proofs: {
         chainId: 46630,
         name: "Robinhood Chain testnet",
@@ -58,7 +58,7 @@ export const MAINNET = {
     explorer: "https://usebrainchain.com",
     stakeSymbol: "BRAIN",
     bountySymbol: "USDG",
-    gas: "Bridge some from Robinhood Chain at https://usebrainchain.com/network",
+    gas: "Send this address ETH on Robinhood Chain, then move it here with `npx brainchain-worker bridge --eth 0.001`",
     buyStake: "Buy BRAIN on Robinhood Chain at ripples.run (https://ripples.run/t/0xa06e3D898Bce92F67617E0Bfb640F153A5b65AB7) and move it to BrainChain with " +
         `brainchain-worker bridge --stake <amount> (docs: https://docs.usebrainchain.com/bridging); the stake token on BrainChain is ${BRAIN}.`,
     proofs: {

package/dist/propose.js

@@ -303,7 +303,7 @@ export async function propose(network, chain, call, uri, options) {
         throw new Error(`The wallet holds ${stake(network, balance)} of the ${stake(network, bond)} bond.${buy}`);
     }
     if (gas === 0n)
-        throw new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas}; 0.001 ETH is plenty.`);
+        throw new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas}.`);
     log(`Bonding ${stake(network, bond)} and proposing...`);
     const { id, tx } = await chain.propose(call, uri, bond);
     log(`Proposal ${id} is waiting for Jev (${tx}). Follow it with \`npx brainchain-worker proposal ${id}\`.`);

package/dist/standing.js

@@ -1,4 +1,4 @@
-import { formatUnits } from "viem";
+import { formatEther, formatUnits } from "viem";
 import { ApplicationState } from "./chain.js";
 /** A token amount with thousands separators, such as 1,250,000; a fraction is kept as it is. */
 function grouped(amount, decimals) {
@@ -26,6 +26,39 @@ export async function snapshot(chain) {
         toStake: w.staked >= min ? 0n : min - w.staked,
     };
 }
+/** The highest gas limit seen for each transaction join can send, across testnet and mainnet. */
+const GAS = { faucet: 76000n, approve: 50000n, stake: 120000n, setPrice: 31000n, apply: 240000n };
+/** The highest gas limit seen for delivering a result. */
+const SUBMIT_GAS = 104000n;
+/**
+ * The ETH a wallet must hold for transactions with these gas limits to go
+ * through in order. Each pays the going price, but the RPC refuses one the
+ * wallet could not cover at 2.4 times it, the fee cap it fills in.
+ */
+export function ethNeeded(limits, gasPrice) {
+    let spent = 0n;
+    let need = 0n;
+    for (const limit of limits) {
+        const covered = spent + (limit * gasPrice * 24n) / 10n;
+        if (covered > need)
+            need = covered;
+        spent += limit * gasPrice;
+    }
+    return need;
+}
+/** The gas limits of what join would send for this worker, in order. */
+export function joinLimits(s, claims, reprices) {
+    return [
+        ...(claims ? [GAS.faucet] : []),
+        ...(s.toStake > 0n ? [GAS.approve, GAS.stake] : reprices ? [GAS.setPrice] : []),
+        ...(s.applying ? [GAS.approve, GAS.apply] : []),
+    ];
+}
+/** An amount of ETH rounded up to two significant figures. */
+export function aboutEth(wei) {
+    const unit = 10n ** BigInt(Math.max(wei.toString().length - 2, 0));
+    return formatEther(((wei + unit - 1n) / unit) * unit);
+}
 /** Why the worker can or cannot be hired right now, in one line for `run` or for `status`, which shows the rest itself. */
 export function hireable({ allowed, w, min, applications, change, pending }, network, from) {
     if (allowed) {
@@ -34,8 +67,11 @@ export function hireable({ allowed, w, min, applications, change, pending }, net
         return `no: your stake is below the minimum of ${stake(network, min)}. Run join to stake again${from === "run" ? "; status shows what it needs" : ""}.`;
     }
     // An allowed application waiting out its timelock outranks anything filed after it.
-    if (change && pending)
-        return `no: Jev allowed this worker; it can be hired after ${when(change.eta)}`;
+    if (change && pending) {
+        const due = BigInt(Math.floor(Date.now() / 1000)) >= change.eta;
+        const allowed = `no: Jev allowed this worker; ${due ? `the change that allows it was due at ${when(change.eta)} and has not run yet` : `it can be hired after ${when(change.eta)}`}`;
+        return w.staked >= min ? allowed : `${allowed}. Its stake is below the minimum of ${stake(network, min)}, so run join to stake again first.`;
+    }
     const last = applications.at(-1);
     if (last === undefined)
         return "no: run `npx brainchain-worker join` to apply";
@@ -69,6 +105,14 @@ export function wallet(network, s, balance, bond, faucet, now) {
     const buy = network.buyStake ? `. ${network.buyStake}` : "";
     return `${has}; join needs ${stake(network, need)}${reopens}${unstaking}${buy}`;
 }
+/** What a wallet short of gas holds and needs, for join's refusal and for `status`. */
+export const shortOfGas = (network, gas, need, purpose) => `${formatEther(gas)} ETH on ${network.name}; ${purpose} needs about ${aboutEth(need)} ETH for gas. ${network.gas}.`;
+/** The wallet's ETH, and what more join or the next delivery needs, since a send the wallet cannot cover fails partway through. */
+export function gasLine(network, s, gas, gasPrice, claims) {
+    const limits = joinLimits(s, claims, false);
+    const need = ethNeeded(limits.length > 0 ? limits : [SUBMIT_GAS], gasPrice);
+    return gas >= need ? `${formatEther(gas)} ETH` : shortOfGas(network, gas, need, limits.length > 0 ? "join" : "delivering a result");
+}
 /** 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)}`;