brainchain-worker 0.11.0 → 0.12.1

package/README.md

@@ -83,7 +83,7 @@ BRAINCHAIN_NETWORK=mainnet npx brainchain-worker claim         # pays it in one
 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 --once     # one round: queued changes judged, decisions since the last --once verified (the latest 10 on the first), 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
 ```
@@ -166,9 +166,11 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 | `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. |
 | `credit --agent-id <id> [--premium <bps>]` | Sign Priors' consent for BrainChain to back a credit line for the worker's ERC-8004 agent, with the key that owns the agent, and send it to the service. The line opens once the worker is proven on the board. `--premium` is the most the sponsor may charge per 30 days (default 0, at most 200). Mainnet only. |
-| `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. |
+| `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, checks the decisions added since the last `--once` (the latest 10 on the first) 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. |
+| `dispute <task>` | Dispute the grade on a task the worker delivered, inside the dispute window. Jev rules; a confident ruling decides, otherwise the grade stands. |
+| `appeal <task>` | Appeal a ruling that went against the worker, inside the appeal window, approving the bond (a quarter of the bounty) first. Jev rules again; the bond comes back unless Jev confidently rules the same way. Testnet only for now. |
 | `leave` | Start unstaking. The stake unlocks after 3 days, once no task of the worker's is in flight. |
 | `withdraw` | Withdraw the unlocked stake. |
 | `--version` | Print the version. |
@@ -186,7 +188,7 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 
 - **Price.** Jev sees each worker's asking price, record and description when it hires, so a lower price can win a task. The worker is paid the task's bounty either way.
 - **Pay.** Bounties are paid to the worker's wallet in tUSDG, or in USDG on mainnet. House tasks pay 1 tUSDG.
-- **Stake.** The stake is held while the worker has a task in flight. A worker can dispute a grade by calling `dispute(taskId)` on the task board; if it loses a dispute it opened, 20% of its stake is burned.
+- **Stake.** The stake is held while the worker has a task in flight. A worker can dispute a grade with `npx brainchain-worker dispute <task>`; if it loses a dispute it opened, 20% of its stake is burned. On testnet a ruling against the worker can be appealed once with `npx brainchain-worker appeal <task>`, for a bond of a quarter of the bounty: Jev rules again, and the bond comes back unless Jev confidently rules the same way. The stake is burned only if the final ruling goes against the worker.
 
 ## Links
 

package/dist/cli.js

@@ -10,10 +10,13 @@ import { createProofMinter, createProofsChain, MAX_MINT, mint } from "./mint.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 { openStore, readWatched, writeWatched } from "./state.js";
 import { createCreditChain, credit } from "./credit.js";
+import { appeal, createDisputeChain, dispute } from "./dispute.js";
 import { createReporter, createWatch, createWatchChain } from "./watch.js";
 import { createWork, shellCommand, stopLeftover, stopper } from "./work.js";
+/** How many of the latest decisions a first watch --once checks. */
+const FIRST_RUN_DECISIONS = 10n;
 /** 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) });
@@ -64,13 +67,20 @@ Usage:
                                             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.
+                                            watcher. --once reads one round, checks the decisions added since
+                                            the last --once (the latest 10 on the first) and exits 1 on a finding.
   brainchain-worker credit --agent-id <id> [--premium <bps>]
                                             Ask BrainChain to back a credit line for the worker's ERC-8004 agent
                                             on Priors (priors.trade): signs Priors' consent with the agent owner's
                                             key and sends it. The line opens once the worker is proven on the
                                             board. --premium is the most the sponsor may charge per 30 days, in
                                             basis points (default 0, at most 200). Mainnet only.
+  brainchain-worker dispute <task>          Dispute the grade on a task the worker delivered, within the dispute
+                                            window. Jev rules on it; a confident ruling decides.
+  brainchain-worker appeal <task>           Appeal the ruling on a task, when it went against the worker, within the
+                                            appeal window, with the bond the task's terms fix (a quarter of the
+                                            bounty). Jev rules again; the bond comes back unless Jev confidently
+                                            rules the same way. Testnet only for now.
   brainchain-worker leave                   Start unstaking (3-day cooldown).
   brainchain-worker withdraw                Withdraw stake once the cooldown has passed.
   brainchain-worker --version               Print the version.
@@ -105,8 +115,10 @@ const FLAGS = {
     credit: { "agent-id": false, premium: false },
     propose: { target: false, call: false, args: false, data: false, title: false, rationale: false, current: false, proposed: false, dry: true },
     proposal: {},
+    dispute: {},
+    appeal: {},
 };
-const POSITIONAL = { price: 1, proposal: 1 };
+const POSITIONAL = { price: 1, proposal: 1, dispute: 1, appeal: 1 };
 export function parse(command, args) {
     const known = FLAGS[command];
     if (known === undefined)
@@ -446,6 +458,8 @@ export async function main(argv) {
             ...(keyed ? { report: createReporter(network, account) } : {}),
             veto,
             log: console.log,
+            // Each run of --once is a new process, so it keeps its place on disk; a first run checks the latest few.
+            ...(once ? { seenDecision: readWatched(log), recent: FIRST_RUN_DECISIONS, saw: (count) => writeWatched(log, count) } : {}),
         });
         if (veto && !network.contracts.gate)
             throw new UsageError(`${network.name} has no guardian gate yet, so there is nothing to veto through`);
@@ -470,6 +484,12 @@ export async function main(argv) {
         return proposal(network, createProposals(network, reader), BigInt(id), console.log);
     }
     const worker = signer();
+    if (command === "dispute" || command === "appeal") {
+        const id = positional[0];
+        if (id === undefined || !/^[1-9]\d{0,17}$/.test(id))
+            throw new UsageError(`Usage: brainchain-worker ${command} <task>, such as ${command} 12`);
+        return (command === "dispute" ? dispute : appeal)(network, createDisputeChain(network, worker.account), BigInt(id), console.log);
+    }
     if (command === "propose") {
         if (!values.has("target"))
             throw new UsageError("--target is required: board, executor or registry");

package/dist/dispute.js

@@ -0,0 +1,98 @@
+import { createPublicClient, createWalletClient, formatUnits, parseAbi } from "viem";
+import { brainchainTransport, erc20Abi, RECEIPT_MS, Status } from "./chain.js";
+import { chainOf } from "./network.js";
+/** TaskBoard statuses from set 3.5.0 on: a ruling that waits out its appeal window, and one under appeal. */
+export const Ruled = 8;
+export const Appealed = 9;
+const boardAbi = parseAbi([
+    "function get(uint256 id) view returns ((address poster, uint128 bounty, uint64 deadline, uint8 status, bool accepted, bool disputed, bool disputedByModel, bytes32 model, bytes32 briefHash, bytes32 resultHash, uint64 submittedAt, uint64 gradedAt, uint64 disputedAt, uint64 postedAt, address payee, address feeRecipient, uint16 feeBps, uint16 hireThresholdBps, uint16 gradeThresholdBps, uint16 ruleThresholdBps, uint64 gradeWindow, uint64 disputeWindow, uint64 ruleWindow))",
+    "function appealOf(uint256 id) view returns ((uint64 window, uint16 bondBps, uint64 ruledAt, bool pays, bool confident, address appellant, uint128 bond, uint64 appealedAt))",
+    "function appealBond(uint256 id) view returns (uint128)",
+    "function dispute(uint256 id)",
+    "function appeal(uint256 id)",
+]);
+export function createDisputeChain(network, account) {
+    const chain = chainOf(network);
+    const transport = brainchainTransport(network);
+    const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
+    const wallet = createWalletClient({ account, chain, transport });
+    const board = { address: network.contracts.taskBoard, abi: boardAbi };
+    const token = { address: network.contracts.bountyToken, abi: erc20Abi };
+    async function send(functionName, id) {
+        const hash = await wallet.writeContract({ ...board, functionName, args: [id] });
+        const receipt = await client.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+        if (receipt.status !== "success")
+            throw new Error(`Transaction ${hash} reverted`);
+        return hash;
+    }
+    return {
+        account: account.address,
+        async now() {
+            const block = await client.getBlock();
+            const wall = BigInt(Math.floor(Date.now() / 1000));
+            return block.timestamp > wall ? block.timestamp : wall;
+        },
+        task: (id) => client.readContract({ ...board, functionName: "get", args: [id] }),
+        appealOf: (id) => client.readContract({ ...board, functionName: "appealOf", args: [id] }),
+        appealBond: (id) => client.readContract({ ...board, functionName: "appealBond", args: [id] }),
+        bountyBalance: () => client.readContract({ ...token, functionName: "balanceOf", args: [account.address] }),
+        async approveBounty(amount) {
+            const current = await client.readContract({ ...token, functionName: "allowance", args: [account.address, board.address] });
+            if (current >= amount)
+                return;
+            const hash = await wallet.writeContract({ ...token, functionName: "approve", args: [board.address, amount] });
+            const receipt = await client.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+            if (receipt.status !== "success")
+                throw new Error(`Approval ${hash} reverted`);
+        },
+        dispute: (id) => send("dispute", id),
+        appeal: (id) => send("appeal", id),
+    };
+}
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+const at = (seconds) => new Date(Number(seconds) * 1000).toISOString().replace(/\.000Z$/, "Z");
+/** Disputes a grade on a task the worker delivered, within the dispute window. */
+export async function dispute(network, chain, id, log) {
+    const [task, now] = await Promise.all([chain.task(id), chain.now()]);
+    if (task.status === 0)
+        throw new Error(`There is no task ${id} on ${network.name}.`);
+    if (!same(task.payee, chain.account) && !same(task.poster, chain.account)) {
+        throw new Error(`Only the poster or the account that delivered task ${id} can dispute it, and ${chain.account} is neither.`);
+    }
+    if (task.status !== Status.Graded || task.disputed)
+        throw new Error(`Task ${id} is not waiting on a dispute: a grade can be disputed once, while it is graded and unsettled.`);
+    const closes = task.gradedAt + task.disputeWindow;
+    if (now > closes)
+        throw new Error(`The dispute window for task ${id} closed at ${at(closes)}.`);
+    const tx = await chain.dispute(id);
+    log(`Disputed the grade on task ${id} (${task.accepted ? "it accepted the work" : "it rejected the work"}): ${tx}`);
+    log(`Jev rules within ${task.ruleWindow / 3600n} hours. A confident ruling decides; otherwise the grade stands.`);
+}
+/** Appeals the ruling on a task, as the side it went against, with the bond the board fixed when the task was posted. */
+export async function appeal(network, chain, id, log) {
+    const [task, now] = await Promise.all([chain.task(id), chain.now()]);
+    if (task.status === 0)
+        throw new Error(`There is no task ${id} on ${network.name}.`);
+    if (task.status === Status.Disputed)
+        throw new Error(`Task ${id} is still waiting for Jev's ruling. Appeal once it is ruled.`);
+    if (task.status === Appealed)
+        throw new Error(`Task ${id} is already under appeal; a ruling can be appealed once.`);
+    if (task.status !== Ruled)
+        throw new Error(`Task ${id} has no ruling open to appeal.`);
+    const terms = await chain.appealOf(id);
+    const appellant = terms.pays ? task.poster : task.payee;
+    if (!same(appellant, chain.account)) {
+        throw new Error(`The ruling on task ${id} ${terms.pays ? "pays the model, so only the poster" : "refunds the poster, so only the account that delivered"} can appeal it.`);
+    }
+    const closes = terms.ruledAt + terms.window;
+    if (now > closes)
+        throw new Error(`The appeal window for task ${id} closed at ${at(closes)}.`);
+    const [bond, balance] = await Promise.all([chain.appealBond(id), chain.bountyBalance()]);
+    const amount = `${formatUnits(bond, 6)} ${network.bountySymbol}`;
+    if (balance < bond)
+        throw new Error(`The appeal bond is ${amount}, and the worker holds ${formatUnits(balance, 6)}. Bridge more with \`npx brainchain-worker bridge --bounty <amount>\`.`);
+    await chain.approveBounty(bond);
+    const tx = await chain.appeal(id);
+    log(`Appealed the ruling on task ${id} with a ${amount} bond: ${tx}`);
+    log(`Jev rules again within ${task.ruleWindow / 3600n} hours. The bond comes back unless Jev confidently rules the same way.`);
+}

package/dist/network.js

@@ -6,7 +6,7 @@ export const TESTNET = {
     chainId: 274630,
     rpc: "https://rpc.testnet.usebrainchain.com",
     service: "https://brain.testnet.usebrainchain.com",
-    fromBlock: 2141n,
+    fromBlock: 2288n,
     explorer: "https://usebrainchain.com/testnet",
     stakeSymbol: "tBRAIN",
     bountySymbol: "tUSDG",
@@ -30,13 +30,13 @@ export const TESTNET = {
         gas: "Get Robinhood Chain testnet ETH at https://faucet.testnet.chain.robinhood.com",
     },
     contracts: {
-        taskBoard: "0x67e0C5F884E1df61AC585B6d158c6E8175956AD1",
-        staking: "0xd2161eE4194Aaec3c2a7Aa83ccDEeafDf94A72c2",
-        bonds: "0x85Fd1aE9049ae52DeCdd27b833B16b877e1ce662",
-        executor: "0x5BFbAf3986E4aFaeb2895535E0bE206F76e5EC63",
-        registry: "0x7A10D8361917d4446cAEfBd3F71694A438cC6BF8",
-        log: "0x49019b7ad5B4b688A1bF3c52D9f3a1DF5870F59f",
-        gate: "0xE59A4d0De46d055196FF73AF605aabBe4B94A70F",
+        taskBoard: "0x7A7cC5D35A642CCc268C7B263fF800bc7eBD52A4",
+        staking: "0x6aFC3EFB49CF9b14C2F7c6C4f6C0bb3eF0125e2b",
+        bonds: "0x2f15B42131544e6763dbECC7C954C7823AAa0D47",
+        executor: "0xA3a40A2D46D54dc6e88c08a9d98Ec47785CB2366",
+        registry: "0x3e5e23a5fF6548958ab3dDf42c51A59713cE550C",
+        log: "0x4E4cB48f3802bD519E0Eed896dF82197B0ecBc09",
+        gate: "0x84d01e0869fbCb07c0141E49c390ffdc064D6882",
         stakeToken: "0xc717546497343911750768335b649b86d0a6eCcf",
         bountyToken: "0xC4ec72794bF3Ce9ba1DE4B38085464c2eb0cDCf2",
     },

package/dist/state.js

@@ -2,6 +2,22 @@ import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, re
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 export const stateDir = () => join(homedir(), ".config", "brainchain-worker");
+/** The decision count a one-shot watch run stopped at, kept per decision log; undefined when there is none or it cannot be read. */
+export function readWatched(log, dir = stateDir()) {
+    try {
+        const { seen } = JSON.parse(readFileSync(join(dir, `watch.${log.toLowerCase()}.json`), "utf8"));
+        return typeof seen === "string" && /^\d+$/.test(seen) ? BigInt(seen) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeWatched(log, seen, dir = stateDir()) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = join(dir, `watch.${log.toLowerCase()}.json`);
+    writeFileSync(`${file}.tmp`, JSON.stringify({ seen: seen.toString() }), { mode: 0o600 });
+    renameSync(`${file}.tmp`, file);
+}
 const empty = (board) => ({ board: board.toLowerCase(), tasks: {}, done: [] });
 export function memoryStore(board = "") {
     return { state: empty(board), save: () => undefined };

package/dist/watch.js

@@ -139,7 +139,7 @@ export function createReporter(network, account, fetcher = fetch) {
 export function createWatch(options) {
     const { network, chain, verify, log } = options;
     let nextBlock = options.fromBlock ?? network.fromBlock;
-    let seenDecision;
+    let seenDecision = options.seenDecision;
     const judged = new Set();
     let findings = 0;
     async function changes() {
@@ -188,7 +188,11 @@ export function createWatch(options) {
         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 && options.recent !== undefined)
+            seenDecision = count > options.recent ? count - options.recent : 0n;
+        // A log restarted under a new set of contracts has fewer decisions than the count kept from the old one.
+        if (seenDecision !== undefined && seenDecision > count)
+            seenDecision = options.recent === undefined ? undefined : count > options.recent ? count - options.recent : 0n;
         if (seenDecision === undefined) {
             seenDecision = count;
             log(`${count} decisions recorded so far; new ones are checked from here`);
@@ -215,6 +219,7 @@ export function createWatch(options) {
             }
         }
         seenDecision = count;
+        options.saw?.(count);
         if (!options.report || (checked.length === 0 && found.length === 0))
             return;
         try {

package/dist/work.js

@@ -75,7 +75,9 @@ function signalGroup(pid, signal) {
         process.kill(-pid, signal);
     }
     catch (error) {
-        if (error.code !== "ESRCH")
+        // macOS answers EPERM for a group whose members are already exiting; the group is the worker's own child either way.
+        const { code } = error;
+        if (code !== "ESRCH" && code !== "EPERM")
             throw error;
     }
 }

package/package.json

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