brainchain-worker 0.11.0 → 0.12.0

package/README.md

@@ -169,6 +169,8 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 | `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. |
+| `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

@@ -12,6 +12,7 @@ import { buildCall, caseURI, createProposals, proposal, propose } from "./propos
 import { hireable, shortOfStake, snapshot, stake, usdg, wallet, when } from "./standing.js";
 import { openStore } 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";
 /** A published record's bytes as the service serves them, capped at a megabyte. */
@@ -71,6 +72,12 @@ Usage:
                                             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 +112,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)
@@ -470,6 +479,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/package.json

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