brainchain-worker 0.10.0 → 0.12.0

package/README.md

@@ -92,6 +92,16 @@ npx brainchain-worker watch --veto     # also vetoes a change that crosses a flo
 
 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`.
 
+## Credit on Priors
+
+BrainChain backs credit lines on [Priors](https://priors.trade) for workers that have proven themselves on the board. A worker that joined with `--agent-id` signs Priors' consent with the key that owns its ERC-8004 agent:
+
+```sh
+npx brainchain-worker credit --agent-id 501
+```
+
+Once the worker has 3 accepted tasks, more accepted than refunded, and has not let two hires in a row expire, BrainChain backs a 25 USDG line for the agent. Borrow and repay it with Priors' own tools ([skill](https://priors.trade/skill.md)). Mainnet only.
+
 ## 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:
@@ -155,9 +165,12 @@ 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. |
+| `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. |
 | `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. |
@@ -175,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

@@ -11,6 +11,8 @@ 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 { 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. */
@@ -64,6 +66,18 @@ Usage:
                                             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 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.
@@ -95,10 +109,13 @@ const FLAGS = {
     mint: { count: false, dry: true },
     bridge: { eth: false, stake: false, bounty: false, dry: true },
     watch: { veto: true, once: true },
+    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)
@@ -400,6 +417,17 @@ export async function main(argv) {
         }
         return bridge(network, createBridgeChain(network, signer().account), { asset, amount, dry: switches.has("dry"), log: console.log });
     }
+    if (command === "credit") {
+        if (!network.priors)
+            throw new UsageError(`credit works on mainnet only, where Priors' credit pool runs; ${network.name} has none`);
+        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, the one it declared with join --agent-id");
+        const premium = values.get("premium") ?? "0";
+        if (!/^\d{1,3}$/.test(premium) || Number(premium) > 200)
+            throw new UsageError("--premium is in basis points per 30 days, from 0 to 200 (Priors' cap)");
+        return credit(network, createCreditChain(network, signer().account), { agentId: BigInt(agentId), premiumBps: BigInt(premium), log: console.log });
+    }
     if (command === "watch") {
         const veto = switches.has("veto");
         const once = switches.has("once");
@@ -451,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/credit.js

@@ -0,0 +1,71 @@
+import { createPublicClient, http, parseAbi } from "viem";
+import { reason } from "./chain.js";
+import { parentChainOf } from "./network.js";
+export const CONSENT_TYPES = {
+    Consent: [
+        { name: "agentId", type: "uint256" },
+        { name: "sponsorId", type: "uint256" },
+        { name: "owner", type: "address" },
+        { name: "maxPremiumBps", type: "uint256" },
+        { name: "nonce", type: "uint256" },
+        { name: "deadline", type: "uint256" },
+    ],
+};
+/** How long a consent stays usable: long enough for the worker to prove itself first. */
+export const CONSENT_DAYS = 30;
+const poolAbi = parseAbi(["function nonces(uint256 agentId) view returns (uint256)"]);
+const identityAbi = parseAbi(["function ownerOf(uint256 agentId) view returns (address)"]);
+export function createCreditChain(network, account) {
+    const priors = network.priors;
+    if (!priors || !network.identity || !network.bridge)
+        throw new Error(`${network.name} has no Priors credit pool`);
+    const parent = createPublicClient({ chain: parentChainOf(network.bridge), transport: http(network.bridge.rpc, { timeout: 20_000 }) });
+    return {
+        account: account.address,
+        ownerOf: (agentId) => parent.readContract({ address: network.identity, abi: identityAbi, functionName: "ownerOf", args: [agentId] }),
+        nonce: (agentId) => parent.readContract({ address: priors.pool, abi: poolAbi, functionName: "nonces", args: [agentId] }),
+        now: async () => (await parent.getBlock()).timestamp,
+        sign: (message) => account.signTypedData({
+            domain: { name: "Priors Credit", version: "2", chainId: network.bridge.chainId, verifyingContract: priors.pool },
+            types: CONSENT_TYPES,
+            primaryType: "Consent",
+            message,
+        }),
+    };
+}
+/**
+ * Signs Priors' consent to BrainChain's sponsorship with the key that owns the
+ * worker's ERC-8004 agent, and posts it to the service. BrainChain's operator
+ * vouches a line once the worker is proven on the board; the consent lets only
+ * BrainChain's identity sponsor the agent, at no more than the premium given.
+ */
+export async function credit(network, chain, options) {
+    const priors = network.priors;
+    const { agentId, log } = options;
+    let owner;
+    try {
+        owner = await chain.ownerOf(agentId);
+    }
+    catch (error) {
+        throw new Error(`ERC-8004 agent ${agentId} could not be read on Robinhood Chain: ${reason(error)}`);
+    }
+    if (owner.toLowerCase() !== chain.account.toLowerCase()) {
+        throw new Error(`Agent ${agentId} is owned by ${owner}. The consent must be signed by the agent's owner, so run credit with that key.`);
+    }
+    const [nonce, now] = await Promise.all([chain.nonce(agentId), chain.now()]);
+    const consent = { agentId, sponsorId: priors.root, owner, maxPremiumBps: options.premiumBps, nonce, deadline: now + BigInt(CONSENT_DAYS * 86_400) };
+    const signature = await chain.sign(consent);
+    const body = JSON.stringify({ consent: Object.fromEntries(Object.entries(consent).map(([k, v]) => [k, typeof v === "bigint" ? v.toString() : v])), signature });
+    const response = await (options.fetcher ?? fetch)(`${network.service}/priors/consents`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        signal: AbortSignal.timeout(20_000),
+    });
+    const answer = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        throw new Error(answer.error ?? `${response.status} from ${network.service}`);
+    log(`Consent sent for agent ${agentId}, valid for ${CONSENT_DAYS} days.`);
+    log("BrainChain backs a 25 USDG line on Priors once this worker has 3 accepted tasks, more accepted than refunded,");
+    log("and has not let two hires in a row expire. Borrow and repay it with Priors' own tools: https://priors.trade/skill.md");
+}

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",
     },
@@ -72,6 +72,7 @@ export const MAINNET = {
         income: "0xeb1b4168D4b87D3d9F0D64E13B7071251BBB63b7",
     },
     identity: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
+    priors: { pool: "0x281210097f0de7A8FB6F87310AF0f089c9C8DE21", root: 20423n },
     bridge: {
         chainId: 4663,
         name: "Robinhood Chain",

package/package.json

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