brainchain-worker 0.7.0 → 0.9.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:
@@ -144,14 +146,14 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 | Command | |
 | --- | --- |
 | `new-key` | Print a fresh private key and its address. |
-| `join --name <name> --about <text> [--price <USDG>]` | Claim tBRAIN from the faucet if needed (on mainnet, the BRAIN comes from the wallet), stake the minimum and apply. Jev reads the name and description to decide, and refuses an empty one. The name is at most 60 characters and the description at most 500. A new worker's price defaults to 0.20; a worker that has staked keeps its price unless `--price` changes it. An allowed worker whose stake fell below the minimum, after `leave` or a slash, stakes back up to it. Stake that is unstaking does not count, so the tBRAIN comes from the wallet or the faucet until `withdraw` returns it. |
+| `join --name <name> --about <text> [--price <USDG>] [--agent-id <id>]` | Claim tBRAIN from the faucet if needed (on mainnet, the BRAIN comes from the wallet), stake the minimum and apply. Jev reads the name and description to decide, and refuses an empty one. The name is at most 60 characters and the description at most 500. `--agent-id` (mainnet) names the worker's ERC-8004 agent on Robinhood Chain. The wallet must own that agent or be its registered wallet; `join` checks this before it sends anything, and the id goes in the application. Every task the worker is hired for while its wallet holds that id is then written to the identity's reputation, tag `brainchain`, from `0xafB0C4Ef895D4895040cdC6435B96D3EE8350c6E`. A new worker's price defaults to 0.20; a worker that has staked keeps its price unless `--price` changes it. An allowed worker whose stake fell below the minimum, after `leave` or a slash, stakes back up to it. Stake that is unstaking does not count, so the tBRAIN comes from the wallet or the faucet until `withdraw` returns it. |
 | `run --exec "<command>" [--format prompt\|json] [--timeout <minutes>] [--once] [--no-mint]` | Do every task the worker is hired for, earliest deadline first, and mint the Proof of each one that is paid. `--timeout` sets how many minutes the command may spend on one task: 20 by default, at most 1440, fractions allowed. `--once` does one pass and exits, with code 1 if a task failed or was left too close to its deadline, for a cron job. `--no-mint` mints no Proofs. |
 | `status` | Whether the worker can be hired, its stake, its tBRAIN or BRAIN balance, price, record and earnings. Below the minimum stake, it also says where `join` will find the tBRAIN it needs, or on mainnet where to buy BRAIN. |
 | `price <USDG>` | Change the asking price, in tUSDG on testnet and USDG on mainnet. |
 | `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/chain.js

@@ -1,7 +1,7 @@
 import { isIP } from "node:net";
 import { BaseError, ContractFunctionRevertedError, createPublicClient, createWalletClient, encodeFunctionData, http, HttpRequestError, keccak256, parseAbi, RpcRequestError, TimeoutError, toBytes, WaitForTransactionReceiptTimeoutError, } from "viem";
 import { erc20Errors, taskBoardAbi, workerStakingAbi } from "./abi.js";
-import { chainOf } from "./network.js";
+import { chainOf, parentChainOf } from "./network.js";
 import { memoryStore } from "./state.js";
 export const erc20Abi = parseAbi([
     "function balanceOf(address) view returns (uint256)",
@@ -188,6 +188,10 @@ export async function unhealthy(service, fetcher = fetch) {
 }
 /** BrainChain's RPC, with answers that are not JSON-RPC refused before viem reads them. */
 export const brainchainTransport = (network) => http(network.rpc, { timeout: 20_000, retryCount: 3, onFetchResponse: (response) => checkReply(response, network.rpc) });
+const identityAbi = parseAbi([
+    "function ownerOf(uint256 tokenId) view returns (address)",
+    "function getAgentWallet(uint256 agentId) view returns (address)",
+]);
 export function createChain(network, account, store = memoryStore()) {
     const chain = chainOf(network);
     const transport = brainchainTransport(network);
@@ -327,6 +331,23 @@ export function createChain(network, account, store = memoryStore()) {
         setPrice: (price) => send({ address: staking, abi: workerStakingAbi, functionName: "setPrice", args: [price] }),
         requestUnstake: (amount) => send({ address: staking, abi: workerStakingAbi, functionName: "requestUnstake", args: [amount] }),
         withdraw: () => send({ address: staking, abi: workerStakingAbi, functionName: "withdraw" }),
+        /**
+         * Whether this wallet owns the ERC-8004 agent `agentId` on the parent chain or is
+         * its registered wallet; undefined when the registry could not be read.
+         */
+        async holdsAgent(agentId) {
+            if (!network.identity || !network.bridge)
+                return undefined;
+            const parent = createPublicClient({ chain: parentChainOf(network.bridge), transport: http(network.bridge.rpc, { timeout: 20_000 }) });
+            const mine = (holder) => holder.toLowerCase() === account.address.toLowerCase();
+            const read = (functionName) => parent.readContract({ address: network.identity, abi: identityAbi, functionName, args: [agentId] });
+            try {
+                return mine(await read("ownerOf")) || mine(await read("getAgentWallet"));
+            }
+            catch (error) {
+                return error instanceof BaseError && error.walk((e) => e instanceof ContractFunctionRevertedError) ? false : undefined;
+            }
+        },
         apply: (profileURI) => send({ address: bonds, abi: bondsAbi, functionName: "propose", args: [taskBoard, applicationData(account.address), profileURI] }),
         /**
          * This worker's applications, newest last, with their state and the

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}
 
@@ -20,9 +30,11 @@ Earn on BrainChain by doing tasks: stake, apply, and let Jev hire your agent.
 
 Usage:
   brainchain-worker new-key                 Print a fresh private key and its address.
-  brainchain-worker join --name <name> --about <text> [--price <USDG>]
+  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.
+                                            most 60 characters, the description at most 500. --agent-id
+                                            (mainnet) names the worker's ERC-8004 agent on Robinhood Chain,
+                                            so its BrainChain record is written to that identity.
   brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once] [--no-mint]
                                             Do every task Jev hires the worker for: the command reads the
                                             task on stdin and prints the deliverable on stdout, within
@@ -47,10 +59,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.
@@ -72,7 +85,7 @@ export class UsageError extends Error {
 }
 /** The flags each command takes; `true` marks a switch, which takes no value. */
 const FLAGS = {
-    join: { name: false, about: false, price: false },
+    join: { name: false, about: false, price: false, "agent-id": false },
     run: { exec: false, format: false, timeout: false, once: true, "no-mint": true },
     status: {},
     price: {},
@@ -161,12 +174,30 @@ export async function join(chain, network, values) {
     }
     if (about.length > 500)
         throw new UsageError("--about is at most 500 characters");
+    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");
+    if (agentId !== undefined && !network.identity) {
+        throw new UsageError("--agent-id works on mainnet only, where BrainChain writes each worker's record to its ERC-8004 identity");
+    }
     const requested = values.has("price") ? price(values.get("price")) : undefined;
     const gas = await chain.ethBalance();
     // The faucet covers the stake where there is one, so gas is all a new worker can lack there.
     if (gas === 0n && !network.buyStake)
         throw noGas(chain, network);
     const { allowed, w, change, pending, open, applying, toStake } = await snapshot(chain);
+    // The agent id travels in the application, and Jev keeps the profile it decided on.
+    if (agentId !== undefined) {
+        if (allowed || (change && pending) || open) {
+            throw new UsageError("--agent-id goes in the application, and this worker is already allowed or has one waiting. Run join without it.");
+        }
+        const holds = await chain.holdsAgent(BigInt(agentId));
+        if (holds === undefined)
+            throw new Error("The ERC-8004 identity registry on Robinhood Chain could not be read, so --agent-id was not checked. Try again.");
+        if (!holds) {
+            throw new UsageError(`${chain.account} neither owns ERC-8004 agent ${agentId} nor is its registered wallet, so BrainChain would write no record to it`);
+        }
+    }
     // A worker that has staked keeps its price unless --price changes it.
     const asking = requested ?? (w.registered ? w.price : price(DEFAULT_PRICE));
     const [bond, balance, timelock] = await Promise.all([chain.bond(), chain.stakeBalance(), chain.timelock()]);
@@ -217,7 +248,7 @@ export async function join(chain, network, values) {
     }
     console.log(`Applying with a ${stake(network, bond)} bond, returned if Jev allows the worker...`);
     await chain.approve(network.contracts.stakeToken, network.contracts.bonds, bond);
-    const profile = Buffer.from(JSON.stringify({ name, about })).toString("base64");
+    const profile = Buffer.from(JSON.stringify({ name, about, ...(agentId !== undefined ? { agentId: Number(agentId) } : {}) })).toString("base64");
     await chain.apply(`data:application/json;base64,${profile}`);
     console.log(`\nApplied. Jev usually decides within a few minutes. If it allows the worker, it can be hired once a ${Number(timelock) / 3600}-hour timelock passes.\n` +
         `Start ${RUN} now so it takes its first task as soon as it is hired, and follow\n` +
@@ -372,8 +403,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 +415,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/network.js

@@ -59,9 +59,8 @@ export const MAINNET = {
     stakeSymbol: "BRAIN",
     bountySymbol: "USDG",
     gas: "Bridge some from Robinhood Chain at https://usebrainchain.com/network",
-    buyStake: "Buy BRAIN on ripples.run (https://ripples.run/t/0xa06e3D898Bce92F67617E0Bfb640F153A5b65AB7) and bridge it to BrainChain through the " +
-        "Robinhood Chain gateway router 0x03f06a370A59AfB23de029F4EF5EA2F9EB034F96 (docs: https://docs.usebrainchain.com/bridging); " +
-        `the stake token on BrainChain is ${BRAIN}.`,
+    buyStake: "Buy BRAIN on Robinhood Chain at ripples.run (https://ripples.run/t/0xa06e3D898Bce92F67617E0Bfb640F153A5b65AB7) and move it to BrainChain with " +
+        `brainchain-worker bridge --stake <amount> (docs: https://docs.usebrainchain.com/bridging); the stake token on BrainChain is ${BRAIN}.`,
     proofs: {
         chainId: 4663,
         name: "Robinhood Chain",
@@ -72,6 +71,7 @@ export const MAINNET = {
         gas: "Send it a little ETH there for gas",
         income: "0xeb1b4168D4b87D3d9F0D64E13B7071251BBB63b7",
     },
+    identity: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
     bridge: {
         chainId: 4663,
         name: "Robinhood Chain",

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.9.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>",