brainchain-worker 0.7.0 → 0.8.0

package/README.md

@@ -90,6 +90,8 @@ npx brainchain-worker watch --veto     # also vetoes a change that crosses a flo
 
 `--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:
@@ -151,7 +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. `--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. |
+| `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

@@ -11,8 +11,18 @@ 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 { createWatch, createWatchChain } from "./watch.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}
 
@@ -47,10 +57,11 @@ Usage:
   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. --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.
+                                            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.
@@ -372,8 +383,9 @@ export async function main(argv) {
     if (command === "watch") {
         const veto = switches.has("veto");
         const once = switches.has("once");
-        // Judging changes needs no key; vetoing does. A reader stands in for the signer otherwise.
-        const account = veto || process.env.BRAINCHAIN_WORKER_KEY?.trim() ? signer().account : privateKeyToAccount(generatePrivateKey());
+        // 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) => {
@@ -383,12 +395,22 @@ export async function main(argv) {
                 set: { key: "active", release: "", fromBlock: Number(network.fromBlock), board: taskBoard, log, executor },
                 briefs: new Map(),
             }, id);
-            return { findings: report.checks.filter((c) => c.status === "fail" || c.status === "error").map((c) => `${c.name}: ${c.message}`) };
+            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, veto, log: console.log });
+        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" : ""}`);
+        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)

package/dist/watch.js

@@ -1,4 +1,4 @@
-import { createPublicClient, createWalletClient, parseAbi } from "viem";
+import { concat, createPublicClient, createWalletClient, keccak256, parseAbi, toBytes } from "viem";
 import { brainchainTransport, executorAbi, reason } from "./chain.js";
 import { chainOf } from "./network.js";
 /**
@@ -93,6 +93,43 @@ export function createWatchChain(network, account) {
             : {}),
     };
 }
+/** 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
@@ -157,13 +194,19 @@ export function createWatch(options) {
             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 } = await verify(id);
-                if (wrong.length === 0)
+                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("; ")}`);
                 }
             }
@@ -172,6 +215,14 @@ export function createWatch(options) {
             }
         }
         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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.7.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>",