brainchain-worker 0.13.1 → 0.15.0

package/dist/cli.js

@@ -1,23 +1,29 @@
 import { createRequire } from "node:module";
 import { verifyDecision } from "brainchain-verify";
 import { createPublicClient, http } from "viem";
-import { parseUnits } from "viem";
+import { formatEther, parseUnits } from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 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 { createProofsChain, createSettlementWatch, MAX_MINT, mint } from "./mint.js";
 import { chainOf, resolveNetwork } from "./network.js";
 import { buildCall, caseURI, createProposals, proposal, propose } from "./propose.js";
-import { ethNeeded, gasLine, hireable, joinLimits, shortOfGas, shortOfStake, snapshot, stake, usdg, wallet, when } from "./standing.js";
+import { deliveries, deliveriesLeft, ethNeeded, flightLine, gasHelp, 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, requireWatcher } from "./watch.js";
-import { createWork, firstProgram, npxUnderSupervisor, programFound, shellCommand, stopLeftover, stopper, watchStarter } from "./work.js";
+import { createWork, firstProgram, npxUnderSupervisor, programFound, shellCommand, stopLeftover, stopper, unseen, watchStarter } from "./work.js";
 /** How many of the latest decisions a first watch --once checks. */
 const FIRST_RUN_DECISIONS = 10n;
+/** How long an idle run goes without a line before it says it is still waiting. */
+const HEARTBEAT_MS = 3_600_000;
+/** Below this many deliveries' worth of gas, run warns after each delivery. */
+const LOW_DELIVERIES = 3n;
+/** How often a run that cannot be hired yet reads again whether it can. */
+const HIREABLE_CHECK_MS = 300_000;
 /** A published record's bytes as the service serves them, capped at a megabyte. */
 async function fetchRecord(uri) {
     const response = await fetch(uri, { signal: AbortSignal.timeout(20_000) });
@@ -32,18 +38,21 @@ const { version } = createRequire(import.meta.url)("../package.json");
 /** 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.`,
+                                            to a new file only you can read and prints the file's path in
+                                            place of the key.`,
     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.`,
-    run: `  brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once] [--no-mint]
+    run: `  brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once] [--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.`,
-    status: `  brainchain-worker status                  Stake, wallet, application, record and earnings.`,
+                                            --timeout minutes (20 by default, at most 1440). It logs how
+                                            each task settles. --mint also mints the Proof of each task it is
+                                            paid for.`,
+    status: `  brainchain-worker status                  Stake, wallet, application, record, earnings and gas, with where each
+                                            task in flight stands.`,
     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
@@ -80,8 +89,9 @@ const COMMAND_USAGE = {
                                             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.`,
+                                            bounty), claimed from the test USDG faucet when the wallet holds less.
+                                            Jev rules again; the bond comes back unless Jev confidently 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.`,
 };
@@ -115,7 +125,8 @@ export class UsageError extends Error {
 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 },
+    // --no-mint is still accepted from before minting became opt-in; it changes nothing.
+    run: { exec: false, format: false, timeout: false, once: true, mint: true, "no-mint": true },
     status: {},
     price: {},
     leave: {},
@@ -189,7 +200,7 @@ function signer() {
     const raw = keyText()?.trim();
     if (!raw)
         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;
+    const hex = raw.replace(/^0x/i, "");
     if (!/^[0-9a-fA-F]{64}$/.test(hex))
         throw new Error("The worker's key must be 64 hex characters, with or without 0x");
     const key = `0x${hex.toLowerCase()}`;
@@ -210,12 +221,12 @@ function price(value) {
 }
 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(chain.account)}.`);
+async function noGas(chain, network) {
+    return new Error(`${chain.account} has no ETH on ${network.name} for gas. ${gasHelp(network, chain.account, 0n, await chain.sent())}.`);
 }
 async function needGas(chain, network) {
     if ((await chain.ethBalance()) === 0n)
-        throw noGas(chain, network);
+        throw await noGas(chain, network);
 }
 export async function join(chain, network, values) {
     const name = values.get("name")?.trim() ?? "";
@@ -224,11 +235,19 @@ export async function join(chain, network, values) {
         throw new UsageError("--name is required, up to 60 characters");
     if (name.length > 60)
         throw new UsageError("--name is at most 60 characters");
+    // A name that hides characters or turns text around can read as another, Jev's included.
+    const nameHides = unseen(name);
+    if (nameHides)
+        throw new UsageError(`--name must be one line with no invisible or direction-changing characters, and it holds ${nameHides}`);
     if (!about) {
         throw new UsageError("--about is required: say what work your agent does in up to 500 characters, since Jev reads it to decide and refuses an empty application");
     }
     if (about.length > 500)
         throw new UsageError("--about is at most 500 characters");
+    // A description may run over several lines.
+    const aboutHides = unseen(about.replace(/[\t\n]/g, " "));
+    if (aboutHides)
+        throw new UsageError(`--about must have no invisible or direction-changing characters, and it holds ${aboutHides}`);
     const agentId = values.get("agent-id");
     if (agentId !== undefined && !/^(0|[1-9]\d{0,14})$/.test(agentId))
         throw new UsageError("--agent-id is the worker's ERC-8004 agent id, a whole number");
@@ -252,12 +271,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 [gas, gasPrice, bond, balance, timelock] = await Promise.all([chain.ethBalance(), chain.gasPrice(), chain.bond(), chain.stakeBalance(), chain.timelock()]);
+    const [gas, gasPrice, bond, balance, timelock, sent] = await Promise.all([
+        chain.ethBalance(),
+        chain.gasPrice(),
+        chain.bond(),
+        chain.stakeBalance(),
+        chain.timelock(),
+        chain.sent(),
+    ]);
     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, chain.account, gas, gasNeed, "join")}` : undefined;
+    const lacksGas = gas < gasNeed ? `${chain.account} holds ${shortOfGas(network, chain.account, gas, sent, 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.
@@ -311,9 +337,10 @@ 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, gasPrice, s, held, record, bountyBalance, stakeBalance, bond, faucet, now] = await Promise.all([
+    const [gas, gasPrice, sent, s, held, record, bountyBalance, stakeBalance, bond, faucet, now] = await Promise.all([
         chain.ethBalance(),
         chain.gasPrice(),
+        chain.sent(),
         snapshot(chain),
         chain.held(),
         chain.record(),
@@ -331,9 +358,9 @@ async function status(chain, network) {
   Stake     ${stake(network, w.staked)} (minimum ${stake(network, min)})${unstaking}
   Wallet    ${wallet(network, s, stakeBalance, bond, faucet, now)}
   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)" : ""}
+  Record    ${record.paid} paid, ${record.refunded} refunded, ${record.inFlight.length} in flight${held > 0 ? " (stake held until they settle)" : ""}${record.inFlight.map((f) => `\n            ${flightLine(f)}`).join("")}
   Earned    ${usdg(network, record.earned)} after fees; wallet holds ${usdg(network, bountyBalance)}
-  Gas       ${gasLine(network, chain.account, s, gas, gasPrice, !network.buyStake && stakeBalance < s.toStake + (s.applying ? bond : 0n))}`);
+  Gas       ${gasLine(network, chain.account, s, gas, gasPrice, !network.buyStake && stakeBalance < s.toStake + (s.applying ? bond : 0n), sent)}`);
 }
 async function run(network, { key, account }, values, once, mints) {
     const exec = values.get("exec");
@@ -346,7 +373,7 @@ async function run(network, { key, account }, values, once, mints) {
     if (!/^\d{1,4}(\.\d+)?$/.test(minutes) || Number(minutes) <= 0 || Number(minutes) > 1440) {
         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}`);
+    const { log, quietFor } = timedLog((line) => console.log(line));
     clearKeyFromEnvironment(key, log);
     const program = firstProgram(exec);
     if (program && !programFound(program))
@@ -355,7 +382,7 @@ async function run(network, { key, account }, values, once, mints) {
     // The lock rules out a live run, so a command still in the state was left by one that died.
     await stopLeftover(store, log);
     const chain = createChain(network, account, store);
-    const proofs = createProofMinter({ network, chain: createProofsChain(network.proofs, account), settled: chain.settled, store, log, enabled: mints });
+    const settlements = createSettlementWatch({ network, chain: createProofsChain(network.proofs, account), settlement: chain.settlement, store, log, mints });
     const command = shellCommand(exec);
     // An idle stop keeps the exit code of a task that failed earlier in a --once pass.
     const stop = stopper({ busy: () => work.busy(), kill: command.kill, log, exit: (code) => process.exit(code || process.exitCode) });
@@ -370,8 +397,23 @@ async function run(network, { key, account }, values, once, mints) {
         stopping: stop.stopping,
         // A cron job sees a failed task as a failed run.
         failed: once ? () => void (process.exitCode = 1) : undefined,
-        delivered: proofs.track,
+        delivered(task) {
+            settlements.track(task);
+            void lowGas();
+        },
+        gasHelp: async () => gasHelp(network, account.address, 0n, await chain.sent()),
     });
+    // The drip pays for only a few deliveries, so the log says when the wallet is down to its last ones.
+    const lowGas = async () => {
+        const [gas, price, sent] = await Promise.all([chain.ethBalance(), chain.gasPrice(), chain.sent()]).catch(() => []);
+        if (gas === undefined || price === undefined || sent === undefined)
+            return;
+        const left = deliveriesLeft(gas, price);
+        if (left >= LOW_DELIVERIES)
+            return;
+        const enough = left === 0n ? "not enough for another delivery" : `enough for about ${left} more ${left === 1n ? "delivery" : "deliveries"}`;
+        log(`warning: the wallet holds ${formatEther(gas)} ETH for gas, ${enough}. ${gasHelp(network, account.address, gas, sent)}.`);
+    };
     for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
         process.on(signal, stop.signal);
     if (process.env.npm_execpath !== undefined) {
@@ -396,12 +438,14 @@ async function run(network, { key, account }, values, once, mints) {
         log(`could not read the wallet's ETH balance: ${reason(error)}`);
     }
     if (gas === 0n)
-        throw noGas(chain, network);
-    const [line, sick] = await Promise.all([
+        throw await noGas(chain, network);
+    const held = gas;
+    const [line, sick, left] = await Promise.all([
         snapshot(chain).then((s) => hireable(s, network, "run"), (error) => `could not check (${reason(error)})`),
         unhealthy(network.service),
+        held === undefined ? undefined : chain.gasPrice().then((price) => deliveriesLeft(held, price), () => undefined),
     ]);
-    log(`worker ${chain.account} on ${network.name}; hireable: ${line}`);
+    log(`worker ${chain.account} on ${network.name}; hireable: ${line}${left === undefined ? "" : `; gas for ${deliveries(left)}`}`);
     if (sick)
         log(`warning: ${sick}`);
     if (once) {
@@ -412,24 +456,64 @@ async function run(network, { key, account }, values, once, mints) {
         });
         if (result?.hired === 0 && result.delivered === 0)
             log("no task is hired to this worker right now");
-        await proofs.round().catch((error) => log(`proofs round failed: ${reason(error)}`));
+        await settlements.round().catch((error) => log(`settlement round failed: ${reason(error)}`));
         return;
     }
     log("waiting for tasks (Ctrl-C to stop)");
     // Minting waits on receipts from another chain, so it runs beside the work, one round at a time.
     let minting;
+    const hireChange = hireWatch(line, () => snapshot(chain).then((s) => hireable(s, network, "run"), () => undefined));
     while (!stop.stopping()) {
         await work.round().catch((error) => log(`round failed: ${reason(error)}`));
-        minting ??= proofs
+        minting ??= settlements
             .round()
-            .catch((error) => log(`proofs round failed: ${reason(error)}`))
+            .catch((error) => log(`settlement round failed: ${reason(error)}`))
             .finally(() => (minting = undefined));
+        const changed = stop.stopping() ? undefined : await hireChange();
+        if (changed !== undefined)
+            log(`hireable: ${changed}`);
+        if (quietFor() >= HEARTBEAT_MS && !work.busy() && !stop.stopping()) {
+            log(`still waiting for tasks; hireable: ${await snapshot(chain).then((s) => hireable(s, network, "run"), (error) => `could not check (${reason(error)})`)}`);
+        }
         for (let i = 0; i < 15 && !stop.stopping(); i++)
             await new Promise((resolve) => setTimeout(resolve, 1_000));
     }
     await minting;
     log("stopped");
 }
+/**
+ * Reads again, every few minutes until the worker can be hired, whether it can,
+ * and returns the new answer when it changed. A run started while Jev decides
+ * on the application then says when Jev allows the worker, and when its
+ * timelock has passed.
+ */
+export function hireWatch(first, check, everyMs = HIREABLE_CHECK_MS, now = Date.now) {
+    let last = first;
+    let checkedAt = now();
+    return async () => {
+        if (last === "yes" || now() - checkedAt < everyMs)
+            return undefined;
+        checkedAt = now();
+        const line = await check();
+        if (line === undefined || line === last)
+            return undefined;
+        last = line;
+        return line;
+    };
+}
+/** Run's log, with each line's time, and how long it has been quiet, so an idle run can say it is still there. */
+export function timedLog(write, now = Date.now) {
+    let last = now();
+    return {
+        log(message) {
+            last = now();
+            write(`${new Date(last).toISOString().slice(0, 19)}Z ${message}`);
+        },
+        quietFor: () => now() - last,
+    };
+}
+/** Where watch --once keeps its place: a key's place counts toward its watchtower mark, so each key has its own, apart from runs without one. */
+export const watchPlace = (log, key) => (key === undefined ? log : `${log}.${key}`);
 /** 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)
@@ -508,6 +592,7 @@ export async function main(argv) {
         const account = keyed ? signer().account : privateKeyToAccount(generatePrivateKey());
         const client = createPublicClient({ chain: chainOf(network), transport: brainchainTransport(network) });
         const { taskBoard, executor, log } = network.contracts;
+        const place = watchPlace(log, keyed ? account.address : undefined);
         const verify = async (id) => {
             const report = await verifyDecision({
                 client,
@@ -529,7 +614,7 @@ export async function main(argv) {
             veto,
             log: console.log,
             // Each run of --once is a new process, so it keeps its place on disk; a first run checks the latest few.
-            ...(once ? { seenDecision: readWatched(log), recent: FIRST_RUN_DECISIONS, saw: (count) => writeWatched(log, count) } : {}),
+            ...(once ? { seenDecision: readWatched(place), recent: FIRST_RUN_DECISIONS, saw: (count) => writeWatched(place, count) } : {}),
         });
         if (veto && !network.contracts.gate)
             throw new UsageError(`${network.name} has no guardian gate yet, so there is nothing to veto through`);
@@ -575,7 +660,7 @@ export async function main(argv) {
         return propose(network, createProposals(network, worker.account), call, uri, { dry: switches.has("dry"), log: console.log });
     }
     if (command === "run")
-        return run(network, worker, values, switches.has("once"), !switches.has("no-mint"));
+        return run(network, worker, values, switches.has("once"), switches.has("mint"));
     const chain = createChain(network, worker.account);
     switch (command) {
         case "join":

package/dist/dispute.js

@@ -1,15 +1,33 @@
-import { createPublicClient, createWalletClient, formatUnits, parseAbi } from "viem";
-import { brainchainTransport, erc20Abi, RECEIPT_MS, Status } from "./chain.js";
+import { createPublicClient, createWalletClient, encodeFunctionData, formatUnits, parseAbi } from "viem";
+import { erc20Errors, transferErrors } from "./abi.js";
+import { appealAbi, brainchainTransport, erc20Abi, explainRevert, faucetReopens, reason, RECEIPT_MS, Status } from "./chain.js";
 import { chainOf } from "./network.js";
+import { ethNeeded, GAS, shortOfGas } from "./standing.js";
 /** TaskBoard statuses from set 3.5.0 on: a ruling that waits out its appeal window, and one under appeal. */
 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))",
-    "function appealBond(uint256 id) view returns (uint128)",
-    "function dispute(uint256 id)",
-    "function appeal(uint256 id)",
-]);
+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 appealBond(uint256 id) view returns (uint128)",
+        "function dispute(uint256 id)",
+        "function appeal(uint256 id)",
+        "error BadStatus()",
+        "error TooLate()",
+        "error NotDisputant()",
+        "error NotAppellant()",
+        "error TransferMismatch()",
+    ]),
+    ...appealAbi,
+    ...erc20Errors,
+    ...transferErrors,
+];
+/** The highest gas limit seen for the bond's approval. */
+const APPROVE_GAS = 50000n;
+/**
+ * The appeal was estimated at 112,355 gas, yet the RPC refused it to a wallet
+ * that held 2.8 times that at the going price, so it is counted high.
+ */
+const APPEAL_GAS = 140000n;
 export function createDisputeChain(network, account) {
     const chain = chainOf(network);
     const transport = brainchainTransport(network);
@@ -18,7 +36,9 @@ export function createDisputeChain(network, account) {
     const board = { address: network.contracts.taskBoard, abi: boardAbi };
     const token = { address: network.contracts.bountyToken, abi: erc20Abi };
     async function send(functionName, id) {
-        const hash = await wallet.writeContract({ ...board, functionName, args: [id] });
+        const hash = await wallet.writeContract({ ...board, functionName, args: [id] }).catch(async (error) => {
+            throw await explainRevert(error, () => client.call({ account: account.address, to: board.address, data: encodeFunctionData({ abi: boardAbi, functionName, args: [id] }) }));
+        });
         const receipt = await client.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
         if (receipt.status !== "success")
             throw new Error(`Transaction ${hash} reverted`);
@@ -35,14 +55,34 @@ export function createDisputeChain(network, account) {
         appealOf: (id) => client.readContract({ ...board, functionName: "appealOf", args: [id] }),
         appealBond: (id) => client.readContract({ ...board, functionName: "appealBond", args: [id] }),
         bountyBalance: () => client.readContract({ ...token, functionName: "balanceOf", args: [account.address] }),
+        async bountyFaucet() {
+            const [amount, interval, last] = await Promise.all([
+                client.readContract({ ...token, functionName: "FAUCET_AMOUNT" }),
+                client.readContract({ ...token, functionName: "FAUCET_INTERVAL" }),
+                client.readContract({ ...token, functionName: "lastClaim", args: [account.address] }),
+            ]);
+            return { amount, opensAt: last === 0n ? 0n : last + interval };
+        },
+        async claimBounty() {
+            const hash = await wallet.writeContract({ ...token, functionName: "faucet" });
+            const receipt = await client.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+            if (receipt.status !== "success")
+                throw new Error(`The faucet claim ${hash} reverted`);
+            return hash;
+        },
+        ethBalance: () => client.getBalance({ address: account.address }),
+        sent: () => client.getTransactionCount({ address: account.address }),
+        gasPrice: () => client.getGasPrice(),
+        allowance: () => client.readContract({ ...token, functionName: "allowance", args: [account.address, board.address] }),
         async approveBounty(amount) {
             const current = await client.readContract({ ...token, functionName: "allowance", args: [account.address, board.address] });
             if (current >= amount)
-                return;
+                return undefined;
             const hash = await wallet.writeContract({ ...token, functionName: "approve", args: [board.address, amount] });
             const receipt = await client.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
             if (receipt.status !== "success")
                 throw new Error(`Approval ${hash} reverted`);
+            return hash;
         },
         dispute: (id) => send("dispute", id),
         appeal: (id) => send("appeal", id),
@@ -86,12 +126,48 @@ export async function appeal(network, chain, id, log) {
     const closes = terms.ruledAt + terms.window;
     if (now > closes)
         throw new Error(`The appeal window for task ${id} closed at ${at(closes)}.`);
-    const [bond, balance] = await Promise.all([chain.appealBond(id), chain.bountyBalance()]);
+    const [bond, balance, eth, gasPrice, allowance, sent] = await Promise.all([
+        chain.appealBond(id),
+        chain.bountyBalance(),
+        chain.ethBalance(),
+        chain.gasPrice(),
+        chain.allowance(),
+        chain.sent(),
+    ]);
     const amount = `${formatUnits(bond, 6)} ${network.bountySymbol}`;
-    if (balance < bond)
-        throw new Error(`The appeal bond is ${amount}, and the worker holds ${formatUnits(balance, 6)}. Bridge more with \`npx brainchain-worker bridge --bounty <amount>\`.`);
-    await chain.approveBounty(bond);
-    const tx = await chain.appeal(id);
+    const holds = `The appeal bond is ${amount}, and this wallet holds ${formatUnits(balance, 6)}.`;
+    // Test USDG comes from its faucet, as tBRAIN does for join; only mainnet's USDG is bridged in.
+    const claims = balance < bond && network.bountyFaucet === true;
+    if (balance < bond && !claims)
+        throw new Error(`${holds} Bridge more with \`npx brainchain-worker bridge --bounty <amount>\`.`);
+    const closed = (opensAt) => new Error(`${holds} The ${network.bountySymbol} faucet allows one claim a day, and this wallet can claim again at ${at(opensAt)}` +
+        (opensAt > closes ? `, after the appeal window closes at ${at(closes)}.` : `. Run appeal again then, before the appeal window closes at ${at(closes)}.`));
+    if (claims) {
+        const faucet = await chain.bountyFaucet();
+        if (now < faucet.opensAt)
+            throw closed(faucet.opensAt);
+        if (balance + faucet.amount < bond)
+            throw new Error(`${holds} The faucet's ${formatUnits(faucet.amount, 6)} ${network.bountySymbol} a day would not make up the rest.`);
+    }
+    // Checked for every transaction before any is sent: an approval alone spends gas and leaves the bond approved.
+    const need = ethNeeded([...(claims ? [GAS.faucet] : []), ...(allowance < bond ? [APPROVE_GAS] : []), APPEAL_GAS], gasPrice);
+    if (eth < need)
+        throw new Error(`${chain.account} holds ${shortOfGas(network, chain.account, eth, sent, need, "the appeal")} Nothing was sent.`);
+    if (claims) {
+        log(`Claiming ${network.bountySymbol} from the testnet faucet for the bond...`);
+        const claim = await chain.claimBounty().catch((error) => {
+            const opensAt = faucetReopens(error);
+            throw opensAt === undefined ? error : closed(opensAt);
+        });
+        log(`Claimed: ${claim}`);
+    }
+    const approval = await chain.approveBounty(bond);
+    const tx = await chain.appeal(id).catch((error) => {
+        if (approval === undefined)
+            throw error;
+        throw new Error(`The board was approved to take the ${amount} bond (${approval}), and then the appeal failed: ${reason(error)}. ` +
+            `The approval stands, so running appeal again before ${at(closes)} sends only the appeal.`);
+    });
     log(`Appealed the ruling on task ${id} with a ${amount} bond: ${tx}`);
     log(`Jev rules again within ${task.ruleWindow / 3600n} hours. The bond comes back unless Jev confidently rules the same way.`);
 }

package/dist/key.js

@@ -13,7 +13,7 @@ export const keyConfigured = (env = process.env) => Boolean(env[HANDOFF] || env.
 function keyFileProblem(text) {
     if (text === "")
         return "is empty";
-    if (/^(0x)?[0-9a-fA-F]{64}$/.test(text))
+    if (/^(0x)?[0-9a-f]{64}$/i.test(text))
         return undefined;
     if (/[\r\n]/.test(text))
         return "holds more than one line";
@@ -21,7 +21,7 @@ function keyFileProblem(text) {
         return "holds a line in the form NAME=value";
     if (/^["'`]|["'`]$/.test(text))
         return "holds the key in quotes";
-    const hex = text.startsWith("0x") ? text.slice(2) : text;
+    const hex = text.replace(/^0x/i, "");
     if (/^[0-9a-fA-F]+$/.test(hex))
         return `holds ${hex.length} hex characters where a key has 64`;
     return "holds characters that are not hex digits";