brainchain-worker 0.18.3 → 0.19.0

package/dist/solana.js

@@ -1,21 +1,43 @@
 // `fund --from-solana`: an agent that lives on Solana funds its BrainChain worker in one command. Relay turns its USDC
 // on Solana into ETH (and, with --stake, BRAIN) for the worker's wallet on Robinhood Chain in about a second, signed by
-// the agent's Solana key; `bridge` then moves gas and stake on to BrainChain. A little ETH stays on Robinhood Chain for
-// the worker's own transactions there, such as an exit to Solana.
+// the agent's Solana key; `bridge` then moves on to BrainChain what this run brought. A little ETH stays on Robinhood
+// Chain for the worker's own transactions there.
 import { readFileSync } from "node:fs";
 import bs58 from "bs58";
-import { Connection, Keypair, PublicKey, TransactionInstruction, TransactionMessage, VersionedTransaction } from "@solana/web3.js";
-import { formatUnits, parseUnits } from "viem";
-import { checkReturn, NATIVE, relayQuote, SOLANA_CHAIN_ID, SOLANA_USDC, waitForRelay } from "./relay.js";
+import { Connection, Keypair, PublicKey, SendTransactionError, TransactionInstruction, TransactionMessage, VersionedTransaction } from "@solana/web3.js";
+import { formatEther, formatUnits, parseUnits } from "viem";
+import { reason } from "./chain.js";
+import { expandHome } from "./key.js";
+import { checkReturn, MAX_LOSS, MAX_STAKE_LOSS, NATIVE, RELAY_API, RelayError, relayQuote, SOLANA_CHAIN_ID, SOLANA_USDC, waitForRelay } from "./relay.js";
 export const SOLANA_RPC = "https://api.mainnet-beta.solana.com";
 /** USDC turned into ETH for gas, unless --gas-usdc says otherwise. */
 export const DEFAULT_GAS_USDC = "2";
 /** ETH left on Robinhood Chain when the rest goes to BrainChain: enough for a token deposit and a few transactions there. */
 export const PARENT_ETH_KEEP = 300000000000000n;
+/** How often a balance is read after Relay reports a move settled, and how far apart: the chain's RPC can lag Relay's word. */
+const ARRIVAL_READS = 10;
+const ARRIVAL_WAIT_MS = 3_000;
+/** Relay's depository program, the instruction that deposits a token into it, and the accounts it keeps. */
+export const RELAY_DEPOSITORY = "99vQwtBwYtrqqD9YSXbdum3KBdxPAVxYTaQ3cfnJSrN2";
+const DEPOSIT_TOKEN = "0b9c60da27a3b413";
+export const DEPOSITORY_STATE = "Dodg2HifwU8rmaVVyMyUZDGTRbqAJTyVYxXPwcbNpBKc";
+export const DEPOSITORY_VAULT = "7uTT8Xi5RWXzy7h9XL244GRgEycDYDhLjr3ZyNdXi8pZ";
+export const DEPOSITORY_VAULT_USDC = "4nvJ5zWdVspxJiNZzB127U6amPH98SFFkBx2JZrAduia";
+export const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+export const ASSOCIATED_TOKEN_PROGRAM = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+/** A wallet's associated token account for USDC. */
+export function usdcAccount(owner) {
+    const seeds = [new PublicKey(owner).toBuffer(), new PublicKey(TOKEN_PROGRAM).toBuffer(), new PublicKey(SOLANA_USDC).toBuffer()];
+    return PublicKey.findProgramAddressSync(seeds, new PublicKey(ASSOCIATED_TOKEN_PROGRAM))[0].toBase58();
+}
 /** The Solana key from BRAINCHAIN_SOLANA_KEY (base58) or BRAINCHAIN_SOLANA_KEY_FILE (a Solana CLI keypair file). */
 export function solanaKeypair(env = process.env) {
     const file = env.BRAINCHAIN_SOLANA_KEY_FILE?.trim();
-    const raw = file ? readFileSync(file, "utf8").trim() : env.BRAINCHAIN_SOLANA_KEY?.trim();
+    const inline = env.BRAINCHAIN_SOLANA_KEY?.trim();
+    if (file && inline)
+        throw new Error("Set BRAINCHAIN_SOLANA_KEY or BRAINCHAIN_SOLANA_KEY_FILE, not both");
+    const raw = file ? readKeyFile(file) : inline;
     if (!raw)
         throw new Error("Set BRAINCHAIN_SOLANA_KEY to the Solana wallet's secret key (base58), or BRAINCHAIN_SOLANA_KEY_FILE to its keypair file");
     try {
@@ -26,15 +48,70 @@ export function solanaKeypair(env = process.env) {
         throw new Error("The Solana key must be a 64-byte secret key, in base58 or as a keypair file's JSON array");
     }
 }
-/** How a USDC amount splits between gas and stake. */
+function readKeyFile(path) {
+    const file = expandHome(path);
+    try {
+        return readFileSync(file, "utf8").trim();
+    }
+    catch (error) {
+        throw new Error(`BRAINCHAIN_SOLANA_KEY_FILE names ${file}, which could not be read (${error.code ?? "unknown error"})`);
+    }
+}
+/** How a USDC amount splits between gas and stake. Without --stake, what gas does not take stays on Solana. */
 export function split(usdc, gasUsdc, stake) {
     if (!stake)
-        return { gas: usdc, stake: 0n };
+        return { gas: usdc < gasUsdc ? usdc : gasUsdc, stake: 0n };
     if (usdc <= gasUsdc)
         throw new Error(`With --stake the amount must be more than the ${formatUnits(gasUsdc, 6)} USDC kept for gas`);
     return { gas: gasUsdc, stake: usdc - gasUsdc };
 }
-/** Sends Relay's Solana deposit: its instructions, compiled against its lookup tables, signed by the agent's key. */
+/**
+ * What is wrong with a quote's Solana side, or undefined when it is the one
+ * thing this command signs: one deposit into Relay's depository, of the USDC
+ * asked for, from this wallet's own token account, paying the worker on the
+ * parent chain. Every field a real quote carries is checked, so anything else
+ * Relay's API answers is refused.
+ */
+export function depositProblem(quote, want) {
+    try {
+        return readDeposit(quote, want);
+    }
+    catch {
+        return "it is in a form this command cannot read";
+    }
+}
+function readDeposit(quote, want) {
+    const [step, ...others] = quote.steps;
+    if (step === undefined || others.length > 0 || step.id !== "deposit" || step.items?.length !== 1)
+        return "it is not one deposit";
+    const { instructions } = step.items[0].data;
+    if (!Array.isArray(instructions) || instructions.length !== 1)
+        return `it carries ${Array.isArray(instructions) ? instructions.length : "no"} instructions where a deposit has one`;
+    const { programId, data, keys } = instructions[0];
+    if (programId !== RELAY_DEPOSITORY)
+        return `it calls the program ${programId}, not Relay's depository`;
+    const bytes = Buffer.from(String(data).replace(/^0x/, ""), "hex");
+    if (bytes.length !== 48 || bytes.subarray(0, 8).toString("hex") !== DEPOSIT_TOKEN)
+        return "it calls Relay's depository for something other than a token deposit";
+    const amount = bytes.readBigUInt64LE(8);
+    if (amount !== want.amount)
+        return `it deposits ${formatUnits(amount, 6)} USDC, not the ${formatUnits(want.amount, 6)} asked for`;
+    const accounts = [DEPOSITORY_STATE, want.owner, want.owner, DEPOSITORY_VAULT, SOLANA_USDC, usdcAccount(want.owner), DEPOSITORY_VAULT_USDC, TOKEN_PROGRAM, ASSOCIATED_TOKEN_PROGRAM, SYSTEM_PROGRAM];
+    if (!Array.isArray(keys) || keys.length !== accounts.length)
+        return `it names ${Array.isArray(keys) ? keys.length : "no"} accounts where a deposit names ${accounts.length}`;
+    const wrong = accounts.findIndex((account, i) => keys[i].pubkey !== account);
+    if (wrong >= 0)
+        return `its account ${wrong} is ${keys[wrong].pubkey}, not ${accounts[wrong]}`;
+    if (keys.some((key, i) => key.isSigner !== (i === 1)))
+        return "it asks another account to sign";
+    if (quote.recipient?.toLowerCase() !== want.recipient.toLowerCase())
+        return `it pays ${quote.recipient ?? "no named recipient"}, not ${want.recipient}`;
+    if (quote.outCurrency?.toLowerCase() !== want.currency.toLowerCase() || quote.outChainId !== want.chainId)
+        return "it does not pay the currency asked for on Robinhood Chain";
+    return undefined;
+}
+const notConfirmed = (signature, why) => new Error(`the Solana transaction ${signature} could not be confirmed (${reason(why)}). Check it before running fund again: if it landed, its USDC left the wallet, and another run moves USDC again.`);
+/** Sends Relay's Solana deposit: its instructions, compiled against its lookup tables, signed by the agent's key. Each failure says whether the USDC moved. */
 export async function sendSvmStep(connection, keypair, item) {
     const instructions = item.instructions.map((i) => new TransactionInstruction({
         programId: new PublicKey(i.programId),
@@ -51,12 +128,31 @@ export async function sendSvmStep(connection, keypair, item) {
     const message = new TransactionMessage({ payerKey: keypair.publicKey, recentBlockhash: blockhash, instructions }).compileToV0Message(tables);
     const transaction = new VersionedTransaction(message);
     transaction.sign([keypair]);
-    const signature = await connection.sendTransaction(transaction, { maxRetries: 3 });
-    const confirmed = await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, "confirmed");
+    // A signed transaction's first signature is its id, known whether or not the send comes back.
+    const signature = bs58.encode(transaction.signatures[0]);
+    try {
+        await connection.sendTransaction(transaction, { maxRetries: 3 });
+    }
+    catch (error) {
+        if (error instanceof SendTransactionError)
+            throw new Error(`Solana refused the deposit, so its USDC did not move: ${error.message.split("\n")[0]}`);
+        throw notConfirmed(signature, error);
+    }
+    const confirmed = await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, "confirmed").catch((error) => {
+        throw notConfirmed(signature, error);
+    });
     if (confirmed.value.err)
-        throw new Error(`the Solana transaction failed: ${JSON.stringify(confirmed.value.err)}`);
+        throw new Error(`the Solana transaction ${signature} failed, so its USDC did not move: ${JSON.stringify(confirmed.value.err)}`);
     return signature;
 }
+/** What to say about a deposit Relay has not filled, or undefined once it has. Only `refund` says the USDC is back; `failure` is usually not final, and `pending` is a wait that ran out. */
+export function unsettled(status, requestId, signature, owner) {
+    if (status === "success")
+        return undefined;
+    if (status === "refund")
+        return `Relay reports a refund for request ${requestId}: the USDC of Solana transaction ${signature} goes back to ${owner}. Check the wallet before running fund again.`;
+    return `Relay has not settled request ${requestId} (it reports "${status}"). The USDC left the wallet in Solana transaction ${signature}. Check ${RELAY_API}/intents/status/v2?requestId=${requestId} before running fund again: another run moves USDC again.`;
+}
 export function createSolanaFunding(keypair, parentChainId, rpc = SOLANA_RPC) {
     const connection = new Connection(rpc, "confirmed");
     const owner = keypair.publicKey.toBase58();
@@ -71,38 +167,50 @@ export function createSolanaFunding(keypair, parentChainId, rpc = SOLANA_RPC) {
         },
         async preview(currency, amount, recipient) {
             const quote = await relayQuote({ user: owner, recipient, originChainId: SOLANA_CHAIN_ID, destinationChainId: parentChainId, originCurrency: SOLANA_USDC, destinationCurrency: currency, amount });
-            checkReturn(quote);
+            checkReturn(quote, currency === NATIVE ? MAX_LOSS : MAX_STAKE_LOSS);
+            const problem = depositProblem(quote, { owner, amount, recipient, currency, chainId: parentChainId });
+            if (problem)
+                throw new RelayError(`Relay's quote was refused before signing: ${problem}. Nothing was sent.`);
             return quote;
         },
-        async move(currency, amount, recipient) {
-            const quote = await this.preview(currency, amount, recipient);
-            let signature = "";
-            for (const step of quote.steps)
-                for (const item of step.items)
-                    signature = await sendSvmStep(connection, keypair, item.data);
-            const status = await waitForRelay(quote.requestId);
-            if (status !== "success")
-                throw new Error(`Relay reports "${status}" for request ${quote.requestId}; a refund comes back to the Solana wallet`);
-            return { quote, signature };
+        async send(quote) {
+            const signature = await sendSvmStep(connection, keypair, quote.steps[0].items[0].data);
+            const problem = unsettled(await waitForRelay(quote.requestId), quote.requestId, signature, owner);
+            if (problem)
+                throw new Error(problem);
+            return signature;
         },
     };
 }
 /** The least SOL the wallet needs to pay Solana's fees for the deposits. */
 export const MIN_LAMPORTS = 2000000n;
+/** What a move added to a balance, no more than was quoted, so a deposit from elsewhere stays out of it. */
+async function arrival(read, before, quoted, sleep) {
+    let held = await read();
+    for (let tries = 1; held <= before && tries < ARRIVAL_READS; tries++) {
+        await sleep(ARRIVAL_WAIT_MS);
+        held = await read();
+    }
+    const rise = held > before ? held - before : 0n;
+    return { held, brought: rise < quoted ? rise : quoted };
+}
 export async function fundFromSolana(options) {
     const { funding, log } = options;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const usdc = parseUnits(options.usdc, 6);
     const gasUsdc = parseUnits(options.gasUsdc ?? DEFAULT_GAS_USDC, 6);
     const parts = split(usdc, gasUsdc, options.stake);
     if (options.stake && !options.stakeToken)
         throw new Error("This network's stake token is not on the parent chain");
+    const spends = parts.gas + parts.stake;
     const [held, lamports] = await Promise.all([funding.usdcBalance(), funding.solBalance()]);
-    if (held < usdc)
-        throw new Error(`The Solana wallet ${funding.owner} holds ${formatUnits(held, 6)} USDC, less than ${options.usdc}`);
+    if (held < spends)
+        throw new Error(`The Solana wallet ${funding.owner} holds ${formatUnits(held, 6)} USDC, less than ${formatUnits(spends, 6)}`);
     if (lamports < MIN_LAMPORTS)
         throw new Error(`The Solana wallet ${funding.owner} needs about 0.002 SOL for Solana's fees; it holds ${formatUnits(lamports, 9)}`);
-    log(`From ${funding.owner} on Solana: ${formatUnits(parts.gas, 6)} USDC to ETH for gas${parts.stake ? ` and ${formatUnits(parts.stake, 6)} USDC to the stake token` : ""}, for ${options.worker}.`);
-    // Both legs are priced before either moves, so a refused stake leg never leaves the gas leg spent alone.
+    const stays = usdc > spends ? ` The other ${formatUnits(usdc - spends, 6)} USDC stays on Solana.` : "";
+    log(`From ${funding.owner} on Solana: ${formatUnits(parts.gas, 6)} USDC to ETH for gas${parts.stake ? ` and ${formatUnits(parts.stake, 6)} USDC to the stake token` : ""}, for ${options.worker}.${stays}`);
+    // Both legs are priced and checked before either moves, and those same quotes are signed, so a refused leg never leaves the other spent alone.
     const gasQuote = await funding.preview(NATIVE, parts.gas, options.worker);
     const stakeQuote = parts.stake ? await funding.preview(options.stakeToken, parts.stake, options.worker) : undefined;
     log(`Relay quotes ${gasQuote.outFormatted} ETH${stakeQuote ? ` and ${stakeQuote.outFormatted} of the stake token` : ""}.`);
@@ -110,15 +218,48 @@ export async function fundFromSolana(options) {
         log("Dry run, nothing sent.");
         return;
     }
-    const gas = await funding.move(NATIVE, parts.gas, options.worker);
-    log(`ETH arrived on the parent chain: ${gas.quote.outFormatted} ETH (Solana ${gas.signature}).`);
-    if (parts.stake) {
-        const stake = await funding.move(options.stakeToken, parts.stake, options.worker);
-        log(`Stake token arrived on the parent chain: ${stake.quote.outFormatted} (Solana ${stake.signature}).`);
+    // Read before anything moves: only what this run adds goes on to BrainChain, never what the wallet already held.
+    const readStake = () => (stakeQuote ? options.parentStake() : Promise.resolve(0n));
+    const [ethBefore, stakeBefore] = await Promise.all([options.parentEth(), readStake()]).catch((error) => {
+        throw new Error(`Could not read the worker's balances on Robinhood Chain, so what this run brings could not be told from what it holds: ${reason(error).replace(/\.$/, "")}. Nothing was sent.`);
+    });
+    const onParent = new Map();
+    try {
+        const gas = await funding.send(gasQuote);
+        onParent.set("eth", `${gasQuote.outFormatted} ETH`);
+        log(`ETH arrived on Robinhood Chain: ${gasQuote.outFormatted} ETH (Solana ${gas}).`);
+        if (stakeQuote) {
+            const stake = await funding.send(stakeQuote);
+            onParent.set("stake", `${stakeQuote.outFormatted} of the stake token`);
+            log(`Stake token arrived on Robinhood Chain: ${stakeQuote.outFormatted} (Solana ${stake}).`);
+        }
+        const eth = await arrival(options.parentEth, ethBefore, gasQuote.outAmount, sleep);
+        const stake = stakeQuote ? await arrival(options.parentStake, stakeBefore, stakeQuote.outAmount, sleep) : undefined;
+        if (eth.brought === 0n || stake?.brought === 0n) {
+            const holds = `${formatEther(eth.held)} ETH${stake ? ` and ${formatEther(stake.held)} of the stake token` : ""}`;
+            const had = `${formatEther(ethBefore)} ETH${stake ? ` and ${formatEther(stakeBefore)}` : ""}`;
+            throw new Error(`Relay reports the move settled, but the wallet on Robinhood Chain shows no increase, so what this run brought cannot be told from what it held. It holds ${holds}, and held ${had} before. Nothing was bridged.`);
+        }
+        // The stake goes first: its deposit pays for its arrival in ETH on the parent chain, out of what the ETH bridge would take.
+        if (stake) {
+            await options.bridgeOn("stake", stake.brought);
+            onParent.delete("stake");
+        }
+        const left = await options.parentEth();
+        const spent = eth.held > left ? eth.held - left : 0n;
+        const ours = eth.brought > spent ? eth.brought - spent : 0n;
+        const room = left > PARENT_ETH_KEEP ? left - PARENT_ETH_KEEP : 0n;
+        const onward = ours < room ? ours : room;
+        if (onward === 0n)
+            log("Not enough ETH to send on to BrainChain beyond what stays for gas on Robinhood Chain.");
+        else
+            await options.bridgeOn("eth", onward);
+    }
+    catch (error) {
+        const moved = [...onParent.values()].join(" and ");
+        if (!moved)
+            throw new Error(reason(error));
+        throw new Error(`${reason(error).replace(/\.?$/, ".")} This run already brought ${moved} to ${options.worker} on Robinhood Chain; \`brainchain-worker bridge\` moves that on to BrainChain, and running fund again moves more USDC.`);
     }
-    // The stake goes first: its deposit pays for its arrival in ETH on the parent chain, which the ETH bridge would take.
-    if (parts.stake)
-        await options.bridgeOn("stake");
-    await options.bridgeOn("eth");
     log("Done. `brainchain-worker status` shows the balances on BrainChain once the deposits arrive, in about a minute.");
 }

package/dist/state.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { copyFileSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join } from "node:path";
 import { startTime } from "./proc.js";
@@ -82,6 +82,19 @@ export function fileStore(file, board, warn = console.warn) {
     const saved = text === undefined ? undefined : parse(text);
     if (saved?.board === state.board)
         state = saved;
+    else if (saved) {
+        // Task ids restart with each board, so none of this can carry over, but it must not vanish in silence.
+        const left = [
+            [Object.keys(saved.tasks).length, "tasks with results"],
+            [saved.hired?.tasks.length ?? 0, "hired tasks"],
+            [Object.keys(saved.proofs ?? {}).length, "tasks waiting to settle or mint"],
+        ].flatMap(([count, what]) => (count ? [`${count} ${what}`] : []));
+        if (left.length > 0) {
+            const aside = `${file}.${saved.board}`;
+            copyFileSync(file, aside);
+            warn(`${file} holds work for the task board ${saved.board}, not this one: ${left.join(", ")}. This run starts without it, and a copy is at ${aside}.`);
+        }
+    }
     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, "")}`;

package/dist/watch.js

@@ -2,9 +2,11 @@ import { concat, createPublicClient, createWalletClient, keccak256, parseAbi, to
 import { brainchainTransport, executorAbi, reason } from "./chain.js";
 import { chainOf } from "./network.js";
 /**
- * The constitution's floors, by the function a change calls. A change that
- * crosses one is what the guardian's veto is for. Values in the units the
- * contracts take: basis points, seconds, and USDG in 6 decimals.
+ * The calls the constitution's monitor knows, by the function a change calls.
+ * A change that crosses a floor is what the guardian's veto is for, and any
+ * other call counts as crossing one. Three known calls have no floor, and say
+ * what they do instead. Values in the units the contracts take: basis points,
+ * seconds, and USDG in 6 decimals.
  */
 export const FLOORS = {
     "0x85327a44": {
@@ -32,9 +34,9 @@ export const FLOORS = {
         name: "setModel",
         check: (w) => [w[1] === 0n && "a house model with no account", w[2] > 5000000n && "a house model priced above 5 USDG"].filter((r) => typeof r === "string"),
     },
-    "0x16c38b3c": { name: "setPaused", check: () => [] },
-    "0x1f1e4d9f": { name: "setWorkerAllowed", check: () => [] },
-    "0xa9059cbb": { name: "transfer", check: () => [] },
+    "0x16c38b3c": { name: "setPaused", check: () => [], does: "pauses or resumes new posts" },
+    "0x1f1e4d9f": { name: "setWorkerAllowed", check: () => [], does: "allows or removes a worker" },
+    "0xa9059cbb": { name: "transfer", check: () => [], does: "moves house treasury funds" },
 };
 /** The static words after the selector; a call with dynamic arguments is read as far as its words go. */
 export function argumentsOf(data) {
@@ -44,13 +46,13 @@ export function argumentsOf(data) {
         words.push(BigInt(`0x${body.slice(i, i + 64)}`));
     return words;
 }
-/** What a queued change does to the constitution: nothing, or the floors it crosses. */
+/** What a queued change does to the constitution: nothing, the floors it crosses, or, for a known call with no floor, what it does. */
 export function judge(data) {
     const selector = data.slice(0, 10).toLowerCase();
     const floor = FLOORS[selector];
     if (!floor)
-        return { name: selector, broken: ["a call the constitution does not list"] };
-    return { name: floor.name, broken: floor.check(argumentsOf(data)) };
+        return { name: selector, broken: ["a call the monitor does not know, which counts as breaking a floor"] };
+    return { name: floor.name, broken: floor.check(argumentsOf(data)), ...(floor.does ? { does: floor.does } : {}) };
 }
 const gateAbi = parseAbi(["function veto(uint256 changeId, string reason)", "function watcher() view returns (address)"]);
 const logAbi = parseAbi(["function count() view returns (uint256)"]);
@@ -108,10 +110,53 @@ export async function requireWatcher(chain, log) {
         throw new Error(`This key cannot veto: the gate's watcher is ${watcher}, not ${chain.account}. Set BRAINCHAIN_WORKER_KEY to the watcher's key, or run watch without --veto.`);
     }
 }
+/** How long after a decision was recorded a record that cannot be read may hold a round's place. */
+export const UNREADABLE_MS = 86_400_000;
+/**
+ * A record that cannot be read stops the round and holds its place, so a host's
+ * outage costs no check. Only for a day from the decision's block time: one dead
+ * address would otherwise blind a watcher to every decision after it, so past
+ * that it is a finding, reported once, and the round moves on.
+ */
+function unreadable(why, recordedAt, now) {
+    if (recordedAt === undefined || !(now - Date.parse(recordedAt) >= UNREADABLE_MS))
+        throw new Error(why);
+    return { findings: [`the record could not be read a day or more after it was recorded: ${why}`] };
+}
+/**
+ * What one decision's checks come to. A check that failed is a finding, whatever
+ * else could not be read. A check that could not run says nothing about the
+ * decision, so it follows the rule for an unreadable record. A record served
+ * without its work leaves its hash checks unrun, which is neither a finding nor a
+ * verified decision: `withheld` names them. With `refetch`, a verified decision
+ * comes with the record's bytes as served, for the report, and a failure to fetch
+ * them follows the same rule.
+ */
+export async function outcome(report, options = {}) {
+    const now = options.now ?? Date.now();
+    const said = (status) => report.checks.filter((c) => c.status === status).map((c) => `${c.name}: ${c.message}`);
+    const findings = said("fail");
+    if (findings.length > 0)
+        return { findings };
+    const unread = said("error");
+    if (unread.length > 0)
+        return unreadable(unread.join("; "), report.recordedAt, now);
+    if (report.withheld)
+        return { findings, withheld: report.checks.filter((c) => c.status === "skip" && c.name.endsWith("-hash")).map((c) => c.name) };
+    if (!options.refetch || !report.payloadURI)
+        return { findings };
+    try {
+        return { findings, record: await options.refetch(report.payloadURI) };
+    }
+    catch (error) {
+        return unreadable(reason(error), report.recordedAt, now);
+    }
+}
 /** The service's prefix on a report; the worker signs the prefix and the report's JSON text. */
 export const REPORT_PREFIX = "BrainChain watchtower report\n";
-/** A report lists at most this many decisions checked. */
+/** A report lists at most this many decisions checked and this many findings; a longer round sends several. */
 export const MAX_CHECKED = 200;
+export const MAX_FINDINGS = 50;
 /** The proof a record was fetched: the hash of its bytes followed by the worker's address, which nothing on chain gives away. */
 export const fetchProof = (bytes, worker) => keccak256(concat([bytes, toBytes(worker)]));
 /** The service answered and will not take this report, so sending it again would not help. */
@@ -123,14 +168,17 @@ export class ReportRefused extends Error {
  * Resolves to the line to log.
  */
 export function createReporter(network, account, fetcher = fetch) {
-    return async (checked, findings) => {
+    // The service takes a report only if it was signed later than the last it took, by the second.
+    let lastAt = 0;
+    async function send(checked, findings) {
+        lastAt = Math.max(Math.floor(Date.now() / 1000), lastAt + 1);
         const report = {
             worker: account.address,
             chainId: network.chainId,
             log: network.contracts.log,
-            at: Math.floor(Date.now() / 1000),
-            checked: checked.slice(0, MAX_CHECKED).map((c) => ({ id: Number(c.id), proof: c.proof })),
-            findings: findings.slice(0, 50).map((f) => ({ id: Number(f.id), checks: f.checks.slice(0, 20).map((c) => c.slice(0, 400)) })),
+            at: lastAt,
+            checked: checked.map((c) => ({ id: Number(c.id), proof: c.proof })),
+            findings: findings.map((f) => ({ id: Number(f.id), checks: f.checks.slice(0, 20).map((c) => c.slice(0, 400)) })),
         };
         const text = JSON.stringify(report);
         const signature = await account.signMessage({ message: `${REPORT_PREFIX}${text}` });
@@ -148,6 +196,13 @@ export function createReporter(network, account, fetcher = fetch) {
         return body.mark
             ? `reported to ${network.name}: ${body.checked} decisions re-verified in all, watchtower mark since ${body.mark.since}`
             : `reported to ${network.name}: ${body.checked} of the ${body.markAfter} re-verified decisions that earn the watchtower mark`;
+    }
+    return async (checked, findings) => {
+        let line = await send(checked.slice(0, MAX_CHECKED), findings.slice(0, MAX_FINDINGS));
+        for (let i = 1; MAX_CHECKED * i < checked.length || MAX_FINDINGS * i < findings.length; i++) {
+            line = await send(checked.slice(MAX_CHECKED * i, MAX_CHECKED * (i + 1)), findings.slice(MAX_FINDINGS * i, MAX_FINDINGS * (i + 1)));
+        }
+        return line;
     };
 }
 /**
@@ -176,7 +231,7 @@ export function createWatch(options) {
                 const key = change.changeId.toString();
                 if (judged.has(key))
                     continue;
-                const { name, broken } = judge(change.data);
+                const { name, broken, does } = judge(change.data);
                 // A failed read leaves the change unjudged and the block range unread, so the next round comes back to it.
                 const open = await chain.open(change.changeId);
                 judged.add(key);
@@ -185,9 +240,9 @@ export function createWatch(options) {
                     log(`change ${change.changeId}: ${name} on ${change.target}${broken.length > 0 ? ` broke the constitution (${why})` : ""}; closed, it has run or was vetoed`);
                     continue;
                 }
-                const runsAt = new Date(Number(change.eta) * 1000).toISOString().replace("T", " ").slice(0, 16);
+                const runsAt = new Date(Number(change.eta) * 1000).toISOString().replace("T", " ").slice(0, 19);
                 if (broken.length === 0) {
-                    log(`change ${change.changeId}: ${name} on ${change.target}, within the constitution, runs after ${runsAt} UTC`);
+                    log(`change ${change.changeId}: ${name} on ${change.target}${does ? ` ${does}, which no floor covers` : ", within the constitution"}, runs after ${runsAt} UTC`);
                     continue;
                 }
                 findings += 1;
@@ -239,8 +294,11 @@ export function createWatch(options) {
         let reached = seenDecision;
         for (let id = seenDecision + 1n; id <= count; id++) {
             try {
-                const { findings: wrong, record } = await verify(id);
-                if (wrong.length === 0) {
+                const { findings: wrong, record, withheld } = await verify(id);
+                if (withheld) {
+                    log(`decision ${id} withheld: its record is served without the work, so ${withheld.join(" and ")} did not run; the checks that ran agree with the chain`);
+                }
+                else if (wrong.length === 0) {
                     log(`decision ${id} verified`);
                     if (record)
                         checked.push({ id, proof: fetchProof(record, chain.account) });
@@ -266,11 +324,10 @@ export function createWatch(options) {
             }
             catch (error) {
                 log(`report not taken: ${reason(error)}`);
-                // Only an answer from the service settles a report; these decisions are checked and sent again otherwise.
-                if (!(error instanceof ReportRefused)) {
-                    incomplete = true;
+                incomplete = true;
+                // Only an answer from the service settles a report: a refusal would only repeat, and these decisions are checked and sent again otherwise.
+                if (!(error instanceof ReportRefused))
                     reached = seenDecision;
-                }
             }
         }
         seenDecision = reached;

package/dist/work.js

@@ -36,6 +36,16 @@ export const printable = (text) => stripAnsi(text)
     .replace(/[\t\n\r]+/g, " ")
     .replace(/[\x00-\x1f\x7f-\x9f]/g, "")
     .replace(new RegExp(HIDDEN.source, "g"), "");
+/** The longest title the log quotes. */
+const LOGGED_TITLE = 80;
+/**
+ * A title from a stranger as the log shows it: one line, cut short and JSON-quoted,
+ * so it cannot close its quotes and pass for the worker's own words.
+ */
+export function loggedTitle(title) {
+    const characters = [...printable(title)];
+    return JSON.stringify(characters.length > LOGGED_TITLE ? `${characters.slice(0, LOGGED_TITLE - 1).join("")}…` : characters.join(""));
+}
 export function parseBrief(text) {
     let value;
     try {
@@ -437,7 +447,7 @@ export function createWork(options) {
                         // A stop asked for while the brief downloaded or the balance was read starts no command.
                         if (options.stopping?.())
                             continue;
-                        log(`task ${task.id}: working on "${brief.title}"`);
+                        log(`task ${task.id}: working on ${loggedTitle(brief.title)}`);
                         const input = options.format === "json" ? JSON.stringify(taskInput(task, brief)) : taskPrompt(task, brief);
                         const timeoutMs = Math.min(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, Number(task.deadline - MARGIN_SEC - now) * 1000);
                         const output = stripAnsi(await command.run(input, { BRAINCHAIN_TASK_ID: key }, timeoutMs, remember).finally(forget)).trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "Earn on BrainChain and propose changes to it: stake, apply, do the tasks Jev hires your agent for, and bond BRAIN to put a change to Jev.",
   "license": "MIT",
   "author": "BrainChain <hello@usebrainchain.com>",