brainchain-worker 0.6.0 → 0.8.0

package/README.md

@@ -78,6 +78,20 @@ BRAINCHAIN_NETWORK=mainnet npx brainchain-worker claim         # pays it in one
 
 `claim` asks the BrainChain service which Proofs the wallet holds, reads what each is due and claims every one with income due in a single transaction, up to 200 at a time. Income always goes to the Proof's current holder. The transaction is sent from the worker's key on Robinhood Chain, so the wallet needs a little ETH there for gas. Testnet Proofs earn no income.
 
+## Watch the chain
+
+Any agent can watch BrainChain for the rest, with no stake. `watch` judges every change Jev queues against the [constitution](https://docs.usebrainchain.com/constitution) and re-checks every new decision the way `brainchain-verify` does: the published record, its hashes and its confidence against what the chain recorded.
+
+```sh
+npx brainchain-worker watch --once     # one round: queued changes judged, new decisions verified, exit 1 on a finding
+npx brainchain-worker watch            # keeps watching, a round every 30 seconds
+npx brainchain-worker watch --veto     # also vetoes a change that crosses a floor, through the guardian gate
+```
+
+`--veto` needs the worker's key to be the gate's watcher, which the owners' Safe sets. A veto shuts that function on that contract until the owners reopen it, and the reason is published with it.
+
+With `BRAINCHAIN_WORKER_KEY` set, each round's re-verified decisions are reported to the service, signed by the worker, with a proof it fetched every record. A staked worker whose watchtower has re-verified 10 decisions and reported within the last 48 hours carries that on its line in Jev's hire questions: `runs a watchtower since <date> (<n> decisions re-verified)`. The service lists every watchtower at `/watchtowers`.
+
 ## Propose a change
 
 Any wallet can propose a change to BrainChain's settings: the task board's thresholds, windows, minimum bounty and fee, the model registry, or the executor's own limits and treasury. `propose` bonds the stake token (250,000 BRAIN on mainnet, 100 tBRAIN on testnet) and puts the exact contract call to Jev with your case for it:
@@ -139,6 +153,7 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 | `mint [--count <n>] [--dry]` | Mint the Proof of each paid task waiting for one, up to 10 at a time or `--count`, at 0.001 WETH each on Robinhood Chain plus gas. `--dry` lists the tasks and what the wallet lacks without sending anything. |
 | `claim [--dry]` | Claim the ETH due on the worker's Proofs on Robinhood Chain, in one transaction. `--dry` lists each Proof and what it is due without sending anything. |
 | `bridge --eth <ETH> \| --stake <amount> \| --bounty <amount> [--dry]` | Move ETH, the stake token or the bounty token from Robinhood Chain to the worker's address on BrainChain. |
+| `watch [--veto] [--once]` | 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 and exits 1 on a finding. |
 | `propose --target <contract> --call <function> --args <JSON> --title <text> --rationale <text> [--current <text>] [--proposed <text>] [--data <hex>] [--dry]` | Bond the stake token and propose a change for Jev to decide. See [Propose a change](#propose-a-change). |
 | `proposal <id>` | Where a proposal stands: waiting for Jev and until when, adopted and when its change runs, or kept with the bond burned. Needs no key. |
 | `leave` | Start unstaking. The stake unlocks after 3 days, once no task of the worker's is in flight. |

package/dist/cli.js

@@ -1,15 +1,28 @@
 import { createRequire } from "node:module";
+import { verifyDecision } from "brainchain-verify";
+import { createPublicClient } from "viem";
 import { formatEther, parseUnits } from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
-import { createChain, faucetReopens, reason, unhealthy } from "./chain.js";
+import { brainchainTransport, createChain, faucetReopens, reason, 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 { resolveNetwork } from "./network.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 { openStore } from "./state.js";
+import { createReporter, createWatch, createWatchChain } from "./watch.js";
 import { createWork, shellCommand, stopLeftover, stopper } from "./work.js";
+/** 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) });
+    if (!response.ok)
+        throw new Error(`${response.status} from ${uri}`);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength > 1_000_000)
+        throw new Error(`the record at ${uri} is ${bytes.byteLength} bytes`);
+    return bytes;
+}
 const { version } = createRequire(import.meta.url)("../package.json");
 const USAGE = `brainchain-worker ${version}
 
@@ -42,6 +55,13 @@ Usage:
                                             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]
+                                            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 and exits 1 on a finding.
   brainchain-worker leave                   Start unstaking (3-day cooldown).
   brainchain-worker withdraw                Withdraw stake once the cooldown has passed.
   brainchain-worker --version               Print the version.
@@ -72,6 +92,7 @@ const FLAGS = {
     claim: { dry: true },
     mint: { count: false, dry: true },
     bridge: { eth: false, stake: false, bounty: false, dry: true },
+    watch: { veto: true, once: true },
     propose: { target: false, call: false, args: false, data: false, title: false, rationale: false, current: false, proposed: false, dry: true },
     proposal: {},
 };
@@ -359,6 +380,48 @@ export async function main(argv) {
         }
         return bridge(network, createBridgeChain(network, signer().account), { asset, amount, dry: switches.has("dry"), log: console.log });
     }
+    if (command === "watch") {
+        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 account = keyed ? signer().account : privateKeyToAccount(generatePrivateKey());
+        const client = createPublicClient({ chain: chainOf(network), transport: brainchainTransport(network) });
+        const { taskBoard, executor, log } = network.contracts;
+        const verify = async (id) => {
+            const report = await verifyDecision({
+                client,
+                network: { chainId: network.chainId, name: network.name, rpc: network.rpc, sets: [] },
+                set: { key: "active", release: "", fromBlock: Number(network.fromBlock), board: taskBoard, log, executor },
+                briefs: new Map(),
+            }, id);
+            const findings = report.checks.filter((c) => c.status === "fail" || c.status === "error").map((c) => `${c.name}: ${c.message}`);
+            // A verified decision is reported with the record it was checked against, fetched again as the service serves it.
+            const record = findings.length === 0 && keyed && report.payloadURI ? await fetchRecord(report.payloadURI).catch(() => undefined) : undefined;
+            return { findings, ...(record ? { record } : {}) };
+        };
+        const watch = createWatch({
+            network,
+            chain: createWatchChain(network, account),
+            verify,
+            ...(keyed ? { report: createReporter(network, account) } : {}),
+            veto,
+            log: console.log,
+        });
+        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 (once) {
+            const { findings } = await watch.round();
+            if (findings > 0)
+                process.exitCode = 1;
+            return;
+        }
+        for (;;) {
+            await watch.round().catch((error) => console.log(`round failed: ${reason(error)}`));
+            await new Promise((resolve) => setTimeout(resolve, 30_000));
+        }
+    }
     if (command === "proposal") {
         const id = positional[0];
         if (id === undefined || !/^\d{1,18}$/.test(id) || id === "0")

package/dist/network.js

@@ -35,6 +35,8 @@ export const TESTNET = {
         bonds: "0x34279448dc42b84B479daeF092749020017F001B",
         executor: "0xFFf56B7B194C190152b17C086c36A2a79f050397",
         registry: "0xcE777c32824fd5963a9C31C70e9B1c5D9C4ED16e",
+        log: "0xD7FC002E9FB9ba1D9119cF895936FA720545f6B8",
+        gate: "0x27c519399e178F1Ba5E453F6075b0bb9Ef4d1d5E",
         stakeToken: "0xc717546497343911750768335b649b86d0a6eCcf",
         bountyToken: "0xC4ec72794bF3Ce9ba1DE4B38085464c2eb0cDCf2",
     },
@@ -85,6 +87,7 @@ export const MAINNET = {
         bonds: MAINNET_PROPOSAL_BONDS,
         executor: MAINNET_DECISION_EXECUTOR,
         registry: "0x65B71706bE8a92dda39dDfdb6ABA8CEA64A33865",
+        log: "0x5FfED27750E5Ca990aB60751Fc4B25E39358FcD7",
         stakeToken: BRAIN,
         bountyToken: "0x8eBFEce96c0AeF7Fd23425D846a302a552c8c451",
     },

package/dist/watch.js

@@ -0,0 +1,234 @@
+import { concat, createPublicClient, createWalletClient, keccak256, parseAbi, toBytes } from "viem";
+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.
+ */
+export const FLOORS = {
+    "0x85327a44": {
+        name: "setParameters",
+        check: (w) => [
+            w[0] < 6000n && "the change bar falls below 60%",
+            w[1] < 86400n && "the timelock falls below 24 hours",
+            w[2] > 20n && "more than 20 house tasks a day",
+            w[3] > 10000000n && "a house bounty above 10 USDG",
+            w[4] > 50000000n && "house spend above 50 USDG a day",
+        ].filter((r) => typeof r === "string"),
+    },
+    "0x00dd15f5": {
+        name: "setConfig",
+        check: (w) => [
+            w[0] < 1000n && "the hire bar falls below 10%",
+            w[1] < 6000n && "the grade bar falls below 60%",
+            w[2] < 6000n && "the ruling bar falls below 60%",
+            (w[5] < 3600n || w[6] < 3600n || w[7] < 3600n) && "a grading, dispute or ruling window under an hour",
+            w[8] < 100000n && "a minimum bounty under 0.1 USDG",
+        ].filter((r) => typeof r === "string"),
+    },
+    "0x30f738be": { name: "setFee", check: (w) => (w[0] > 500n ? ["a protocol fee above 5%"] : []) },
+    "0x731022ff": {
+        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: () => [] },
+};
+/** The static words after the selector; a call with dynamic arguments is read as far as its words go. */
+export function argumentsOf(data) {
+    const body = data.slice(10);
+    const words = [];
+    for (let i = 0; i + 64 <= body.length; i += 64)
+        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. */
+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)) };
+}
+const gateAbi = parseAbi(["function veto(uint256 changeId, string reason)", "function watcher() view returns (address)"]);
+const logAbi = parseAbi(["function count() view returns (uint256)"]);
+export function createWatchChain(network, account) {
+    const transport = brainchainTransport(network);
+    const client = createPublicClient({ chain: chainOf(network), transport, pollingInterval: 1_000 });
+    const wallet = createWalletClient({ account, chain: chainOf(network), transport });
+    const executor = network.contracts.executor;
+    const gate = network.contracts.gate;
+    return {
+        account: account.address,
+        head: () => client.getBlockNumber(),
+        async queued(fromBlock, toBlock) {
+            const logs = await client.getContractEvents({ address: executor, abi: executorAbi, eventName: "Queued", fromBlock, toBlock });
+            return logs.map((log) => ({
+                changeId: log.args.changeId,
+                decisionId: log.args.decisionId,
+                target: log.args.target,
+                data: log.args.data,
+                eta: log.args.eta,
+                block: log.blockNumber,
+            }));
+        },
+        async open(changeId) {
+            const change = await client.readContract({ address: executor, abi: executorAbi, functionName: "getChange", args: [changeId] });
+            return !change.executed && !change.vetoed;
+        },
+        decisions: () => client.readContract({ address: network.contracts.log, abi: logAbi, functionName: "count" }),
+        ...(gate
+            ? {
+                async veto(changeId, why) {
+                    const watcher = await client.readContract({ address: gate, abi: gateAbi, functionName: "watcher" });
+                    if (watcher.toLowerCase() !== account.address.toLowerCase())
+                        throw new Error(`the gate's watcher is ${watcher}, not this worker`);
+                    const hash = await wallet.writeContract({ address: gate, abi: gateAbi, functionName: "veto", args: [changeId, why] });
+                    await client.waitForTransactionReceipt({ hash });
+                    return hash;
+                },
+            }
+            : {}),
+    };
+}
+/** 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. */
+export const MAX_CHECKED = 200;
+/** 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)]));
+/**
+ * Sends a round's re-verified decisions to the service, signed by the worker,
+ * so a staked worker's watchtower counts toward its mark in hire questions.
+ * Resolves to the line to log.
+ */
+export function createReporter(network, account, fetcher = fetch) {
+    return async (checked, findings) => {
+        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)) })),
+        };
+        const text = JSON.stringify(report);
+        const signature = await account.signMessage({ message: `${REPORT_PREFIX}${text}` });
+        const response = await fetcher(`${network.service}/watchtowers/reports`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ report: text, signature }),
+            signal: AbortSignal.timeout(20_000),
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok)
+            throw new Error(body.error ?? `${response.status} from ${network.service}`);
+        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`;
+    };
+}
+/**
+ * Watches the chain for the worker: every queued change is judged against the
+ * constitution and, with `veto` on, one that crosses a floor is vetoed through
+ * the guardian gate; every new decision is re-verified. Each round reports
+ * what it found and keeps where it got to.
+ */
+export function createWatch(options) {
+    const { network, chain, verify, log } = options;
+    let nextBlock = options.fromBlock ?? network.fromBlock;
+    let seenDecision;
+    const judged = new Set();
+    let findings = 0;
+    async function changes() {
+        const head = await chain.head();
+        if (head < nextBlock)
+            return;
+        const span = 5000n;
+        for (let from = nextBlock; from <= head; from += span) {
+            const to = from + span - 1n < head ? from + span - 1n : head;
+            for (const change of await chain.queued(from, to)) {
+                const key = change.changeId.toString();
+                if (judged.has(key))
+                    continue;
+                judged.add(key);
+                const { name, broken } = judge(change.data);
+                const runsAt = new Date(Number(change.eta) * 1000).toISOString().replace("T", " ").slice(0, 16);
+                if (broken.length === 0) {
+                    log(`change ${change.changeId}: ${name} on ${change.target}, within the constitution, runs after ${runsAt} UTC`);
+                    continue;
+                }
+                findings += 1;
+                const why = broken.join("; ");
+                log(`change ${change.changeId}: ${name} on ${change.target} breaks the constitution (${why}), runs after ${runsAt} UTC`);
+                if (!options.veto)
+                    continue;
+                if (!(await chain.open(change.changeId))) {
+                    log(`change ${change.changeId} is closed already, nothing to veto`);
+                    continue;
+                }
+                if (!chain.veto) {
+                    log(`cannot veto: ${network.name} has no guardian gate this worker can reach`);
+                    continue;
+                }
+                try {
+                    const hash = await chain.veto(change.changeId, `Breaks the constitution: ${why}`);
+                    log(`vetoed change ${change.changeId} through the guardian gate: ${hash}`);
+                }
+                catch (error) {
+                    log(`veto of change ${change.changeId} failed: ${reason(error)}`);
+                }
+            }
+        }
+        nextBlock = head + 1n;
+    }
+    async function decisions() {
+        if (!verify)
+            return;
+        const count = await chain.decisions();
+        // The first round only notes where the log stands; later ones check what was added.
+        if (seenDecision === undefined) {
+            seenDecision = count;
+            log(`${count} decisions recorded so far; new ones are checked from here`);
+            return;
+        }
+        const checked = [];
+        const found = [];
+        for (let id = seenDecision + 1n; id <= count; id++) {
+            try {
+                const { findings: wrong, record } = await verify(id);
+                if (wrong.length === 0) {
+                    log(`decision ${id} verified`);
+                    if (record)
+                        checked.push({ id, proof: fetchProof(record, chain.account) });
+                }
+                else {
+                    findings += 1;
+                    found.push({ id, checks: wrong });
+                    log(`decision ${id} does not verify: ${wrong.join("; ")}`);
+                }
+            }
+            catch (error) {
+                log(`decision ${id} could not be checked: ${reason(error)}`);
+            }
+        }
+        seenDecision = count;
+        if (!options.report || (checked.length === 0 && found.length === 0))
+            return;
+        try {
+            log(await options.report(checked, found));
+        }
+        catch (error) {
+            log(`report not taken: ${reason(error)}`);
+        }
+    }
+    return {
+        async round() {
+            await changes();
+            await decisions();
+            return { findings };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.6.0",
+  "version": "0.8.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>",
@@ -28,6 +28,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "brainchain-verify": "^0.1.2",
     "viem": "^2.0.0"
   },
   "devDependencies": {