brainchain-worker 0.4.1 → 0.5.0

package/README.md

@@ -70,6 +70,21 @@ BRAINCHAIN_NETWORK=mainnet npx brainchain-worker claim         # pays it in one
 
 `claim` asks the BrainChain service which Proofs the wallet holds, reads what each is due and claims every one with income due in a single transaction, up to 200 at a time. Income always goes to the Proof's current holder. The transaction is sent from the worker's key on Robinhood Chain, so the wallet needs a little ETH there for gas. Testnet Proofs earn no income.
 
+## 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:
+
+```sh
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker propose --target board --call setFee \
+  --args '[200, "0xdFeFbdBF680568e8DC44abbbd657c0701964cC8c"]' \
+  --title "Lower the fee to 2%" --rationale "Why the change is better, in up to 1,500 characters." --dry
+```
+
+- **The call.** `--target` is `board`, `executor` or `registry`, `--call` the function and `--args` its arguments as a JSON array, with a struct as an object that names every field. `--data` takes raw calldata instead. The board takes `setConfig`, `setFee`, `setPaused` and `setWorkerAllowed`; the executor `setParameters` and `transfer`; the registry `setModel`.
+- **The case.** Jev reads `--title` (up to 120 characters) and `--rationale` (up to 1,500), and `--current` and `--proposed` (up to 300 each) if given. `--proposed` defaults to the call itself.
+- **Checks first.** Before any bond moves, `propose` runs the call as the executor would and refuses it if it would revert, if the guardian vetoed it before, or if it is a call the executor never makes, such as `setGuardian`. `--dry` stops after the checks.
+- **Outcome.** Jev decides within 7 days. If it adopts the change with at least the change threshold's confidence (60% on mainnet), the bond comes back and the call runs after the timelock: 48 hours on mainnet, 2 on testnet. Otherwise the bond is burned. `proposal <id>` shows where a proposal stands.
+
 ## Your command
 
 `run --exec "<command>"` runs the command through the shell once per task.
@@ -115,6 +130,8 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 | `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. |
+| `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. |
 | `withdraw` | Withdraw the unlocked stake. |
 | `--version` | Print the version. |

package/dist/chain.js

@@ -186,9 +186,11 @@ export async function unhealthy(service, fetcher = fetch) {
         return `the BrainChain service at ${host} reports it is behind (503); results still upload, and grading may be late`;
     return `the BrainChain service at ${host} answered its health check with ${response.status}; results are uploaded there, so delivery can fail until it recovers`;
 }
+/** 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) });
 export function createChain(network, account, store = memoryStore()) {
     const chain = chainOf(network);
-    const transport = http(network.rpc, { timeout: 20_000, retryCount: 3, onFetchResponse: (response) => checkReply(response, network.rpc) });
+    const transport = brainchainTransport(network);
     // BrainChain mines a block per transaction, so receipts are polled every second.
     const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
     const wallet = createWalletClient({ account, chain, transport });

package/dist/claim.js

@@ -1,6 +1,6 @@
-import { createPublicClient, createWalletClient, formatEther, http, parseAbi, parseEventLogs } from "viem";
+import { createPublicClient, createWalletClient, formatEther, parseAbi, parseEventLogs } from "viem";
 import { RECEIPT_MS } from "./chain.js";
-import { proofsChainOf } from "./network.js";
+import { proofsChainOf, proofsTransport } from "./network.js";
 export const proofsIncomeAbi = parseAbi([
     "function due(uint256 tokenId) view returns (uint256)",
     "function claimMany(uint256[] tokenIds)",
@@ -12,7 +12,7 @@ export const proofsIncomeAbi = parseAbi([
 export const MAX_CLAIM = 200;
 export function createIncome(proofs, income, account) {
     const chain = proofsChainOf(proofs);
-    const transport = http(proofs.rpc, { timeout: 20_000, retryCount: 3 });
+    const transport = proofsTransport(proofs);
     const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
     const wallet = createWalletClient({ account, chain, transport });
     const router = { address: income, abi: proofsIncomeAbi };

package/dist/cli.js

@@ -5,6 +5,7 @@ import { createChain, faucetReopens, reason, unhealthy } from "./chain.js";
 import { claim, createIncome } from "./claim.js";
 import { createProofMinter, createProofsChain, MAX_MINT, mint } from "./mint.js";
 import { 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 { createWork, shellCommand, stopLeftover, stopper } from "./work.js";
@@ -30,6 +31,12 @@ Usage:
                                             --count, at 0.001 WETH each on Robinhood Chain. --dry sends nothing.
   brainchain-worker claim [--dry]           Claim the ETH due on the worker's Proofs, on Robinhood Chain.
                                             --dry lists what is due and sends nothing.
+  brainchain-worker propose --target board|executor|registry --call <function> --args '<JSON array>'
+                            --title <text> --rationale <text> [--current <text>] [--proposed <text>] [--dry]
+                                            Bond the stake token and propose a change to BrainChain for Jev to
+                                            decide. --data <hex> gives the call as raw calldata instead of
+                                            --call and --args. --dry checks the call and sends nothing.
+  brainchain-worker proposal <id>           Where a proposal stands: waiting, adopted and when it runs, or kept.
   brainchain-worker leave                   Start unstaking (3-day cooldown).
   brainchain-worker withdraw                Withdraw stake once the cooldown has passed.
   brainchain-worker --version               Print the version.
@@ -59,8 +66,10 @@ const FLAGS = {
     withdraw: {},
     claim: { dry: true },
     mint: { count: false, dry: true },
+    propose: { target: false, call: false, args: false, data: false, title: false, rationale: false, current: false, proposed: false, dry: true },
+    proposal: {},
 };
-const POSITIONAL = { price: 1 };
+const POSITIONAL = { price: 1, proposal: 1 };
 export function parse(command, args) {
     const known = FLAGS[command];
     if (known === undefined)
@@ -332,7 +341,27 @@ export async function main(argv) {
         }
         return mint(network, createProofsChain(network.proofs, signer().account), { count: count === undefined ? undefined : Number(count), dry: switches.has("dry"), log: console.log });
     }
+    if (command === "proposal") {
+        const id = positional[0];
+        if (id === undefined || !/^\d{1,18}$/.test(id) || id === "0")
+            throw new UsageError("Usage: brainchain-worker proposal <id>, such as proposal 2");
+        // Reading a proposal needs no key, so any address stands in for the signer.
+        const reader = process.env.BRAINCHAIN_WORKER_KEY?.trim() ? signer().account : privateKeyToAccount(generatePrivateKey());
+        return proposal(network, createProposals(network, reader), BigInt(id), console.log);
+    }
     const worker = signer();
+    if (command === "propose") {
+        if (!values.has("target"))
+            throw new UsageError("--target is required: board, executor or registry");
+        const call = buildCall(network, worker.account.address, {
+            target: values.get("target"),
+            call: values.get("call"),
+            args: values.get("args"),
+            data: values.get("data"),
+        });
+        const uri = caseURI(call, { title: values.get("title") ?? "", rationale: values.get("rationale") ?? "", current: values.get("current"), proposed: values.get("proposed") });
+        return propose(network, createProposals(network, worker.account), call, uri, { dry: switches.has("dry"), log: console.log });
+    }
     if (command === "run")
         return run(network, worker, values, switches.has("once"), !switches.has("no-mint"));
     const chain = createChain(network, worker.account);

package/dist/mint.js

@@ -1,6 +1,6 @@
-import { createPublicClient, createWalletClient, formatEther, http, parseAbi, parseEventLogs, zeroAddress, } from "viem";
+import { createPublicClient, createWalletClient, formatEther, parseAbi, parseEventLogs, zeroAddress, } from "viem";
 import { reason, RECEIPT_MS } from "./chain.js";
-import { proofsChainOf } from "./network.js";
+import { proofsChainOf, proofsTransport } from "./network.js";
 import { when } from "./standing.js";
 export const collectionAbi = parseAbi([
     "function PRICE_QUOTE() view returns (uint256)",
@@ -38,7 +38,7 @@ export function mintedToken(logs, collection, to) {
 }
 export function createProofsChain(proofs, account) {
     const chain = proofsChainOf(proofs);
-    const transport = http(proofs.rpc, { timeout: 20_000, retryCount: 3 });
+    const transport = proofsTransport(proofs);
     const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
     const wallet = createWalletClient({ account, chain, transport });
     const weth = { address: proofs.weth, abi: wethAbi };

package/dist/network.js

@@ -1,4 +1,4 @@
-import { defineChain, zeroAddress } from "viem";
+import { defineChain, fallback, http, zeroAddress } from "viem";
 /** BrainChain testnet, release 3.1.0. */
 export const TESTNET = {
     id: "testnet",
@@ -15,6 +15,7 @@ export const TESTNET = {
         chainId: 46630,
         name: "Robinhood Chain testnet",
         rpc: "https://rpc.testnet.chain.robinhood.com",
+        rpcFallbacks: ["https://robinhood-sepolia-rpc.publicnode.com", "https://robinhood-testnet.drpc.org"],
         collection: "0x324B52EE2182641ec29652076ab541bc9F9907d2",
         weth: "0x1F852eF3Afa13156b807204d838BbB46B4b452eb",
         faucet: true,
@@ -25,6 +26,7 @@ export const TESTNET = {
         staking: "0xbdC08799D865DA79FE44a469de1FeaE84bb45059",
         bonds: "0x574060D1A7CA8f3786d2D14fe1A782cc4638CB1e",
         executor: "0x420484B139001ED5B1DA330e689Cc2f4814001Fb",
+        registry: "0x297AA5fb95Ef9785Da6DC0cA00121060606e2C63",
         stakeToken: "0xc717546497343911750768335b649b86d0a6eCcf",
         bountyToken: "0xC4ec72794bF3Ce9ba1DE4B38085464c2eb0cDCf2",
     },
@@ -54,6 +56,7 @@ export const MAINNET = {
         chainId: 4663,
         name: "Robinhood Chain",
         rpc: "https://rpc.mainnet.chain.robinhood.com",
+        rpcFallbacks: ["https://rpc-robinhood.globalstake.io", "https://robinhood.api.pocket.network"],
         collection: "0xE6E6B7DBF1a66dFB25c6F6A87a916B3186113169",
         weth: "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73",
         gas: "Send it a little ETH there for gas",
@@ -64,6 +67,7 @@ export const MAINNET = {
         staking: MAINNET_WORKER_STAKING,
         bonds: MAINNET_PROPOSAL_BONDS,
         executor: MAINNET_DECISION_EXECUTOR,
+        registry: "0x65B71706bE8a92dda39dDfdb6ABA8CEA64A33865",
         stakeToken: BRAIN,
         bountyToken: "0x8eBFEce96c0AeF7Fd23425D846a302a552c8c451",
     },
@@ -112,7 +116,12 @@ export function proofsChainOf(proofs) {
         id: proofs.chainId,
         name: proofs.name,
         nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
-        rpcUrls: { default: { http: [proofs.rpc] } },
+        rpcUrls: { default: { http: [proofs.rpc, ...(proofs.rpcFallbacks ?? [])] } },
         contracts: { multicall3: { address: MULTICALL3 } },
     });
 }
+/** The Proofs chain's RPCs in order; the next answers when one fails to, a revert being an answer. */
+export function proofsTransport(proofs) {
+    const urls = [proofs.rpc, ...(proofs.rpcFallbacks ?? [])];
+    return fallback(urls.map((url) => http(url, { timeout: 20_000, retryCount: urls.length > 1 ? 1 : 3 })), { rank: false, retryCount: 0 });
+}

package/dist/propose.js

@@ -0,0 +1,336 @@
+import { BaseError, createPublicClient, createWalletClient, decodeErrorResult, decodeFunctionData, encodeAbiParameters, encodeFunctionData, ExecutionRevertedError, getAddress, isAddress, isHex, keccak256, parseAbi, parseEventLogs, size, } from "viem";
+import { erc20Errors } from "./abi.js";
+import { bondsAbi, brainchainTransport, erc20Abi, executorAbi, RECEIPT_MS } from "./chain.js";
+import { chainOf } from "./network.js";
+import { stake, when } from "./standing.js";
+/** Every call the executor can be asked to make, by the contract it calls. */
+export const GOVERNED = {
+    board: parseAbi([
+        "struct Config { uint16 hireThresholdBps; uint16 gradeThresholdBps; uint16 ruleThresholdBps; uint64 minDuration; uint64 maxDuration; uint64 gradeWindow; uint64 disputeWindow; uint64 ruleWindow; uint128 minBounty; }",
+        "function setConfig(Config config)",
+        "function setFee(uint16 feeBps, address feeRouter)",
+        "function setPaused(bool paused)",
+        "function setWorkerAllowed(address account, bool allowed)",
+    ]),
+    executor: parseAbi([
+        "function setParameters(uint16 changeThresholdBps, uint64 timelock, uint32 houseTasksPerDay, uint128 maxHouseBounty, uint128 houseSpendPerDay)",
+        "function transfer(address to, uint256 amount)",
+    ]),
+    registry: parseAbi(["function setModel(bytes32 id, address account, uint128 price, bool active)"]),
+};
+const TARGETS = Object.keys(GOVERNED);
+/** What the brain reads from a proposal's URI, cut to the lengths it keeps. */
+export const LIMITS = { title: 120, rationale: 1_500, current: 300, proposed: 300 };
+const proposalsAbi = parseAbi([
+    "event Expired(uint256 indexed id)",
+    "function decideWithin() view returns (uint64)",
+]);
+const executorReadsAbi = parseAbi([
+    "function vetoedCall(bytes32) view returns (bool)",
+    "function changeThresholdBps() view returns (uint16)",
+]);
+// The reverts a governed call can hit, so a rehearsal names the rule it broke.
+const callErrorsAbi = [
+    ...parseAbi(["error BadConfig()", "error BadFee()", "error ZeroAddress()", "error NotOwner()", "error NotSelf()", "error NotGuardian()"]),
+    ...erc20Errors,
+];
+/** Mirrors ProposalBonds.State. */
+const State = { None: 0, Open: 1, Returned: 2, Burned: 3 };
+export class ProposalError extends Error {
+}
+function functions(target) {
+    return GOVERNED[target].filter((item) => item.type === "function").map((item) => item.name);
+}
+/** A JSON value as the ABI parameter it is passed for: integers become bigints, tuples objects. */
+export function coerce(param, value) {
+    const name = param.name ?? param.type;
+    const fail = (expected) => new ProposalError(`${name} must be ${expected}, not ${JSON.stringify(value)}`);
+    if (/^u?int\d*$/.test(param.type)) {
+        const signed = param.type.startsWith("int");
+        if (typeof value === "number" && Number.isSafeInteger(value))
+            return BigInt(value);
+        if (typeof value === "string" && (signed ? /^-?\d+$/ : /^\d+$/).test(value))
+            return BigInt(value);
+        throw fail(`a whole number${signed ? "" : " from 0"}, as a JSON number or a string of digits`);
+    }
+    if (param.type === "bool") {
+        if (typeof value === "boolean")
+            return value;
+        throw fail("true or false");
+    }
+    if (param.type === "address") {
+        if (typeof value === "string" && isAddress(value, { strict: false }))
+            return getAddress(value);
+        throw fail("an address");
+    }
+    const bytes = /^bytes(\d+)$/.exec(param.type);
+    if (bytes) {
+        if (typeof value === "string" && isHex(value) && size(value) === Number(bytes[1]))
+            return value.toLowerCase();
+        throw fail(`${bytes[1]} bytes of hex`);
+    }
+    if (param.type === "tuple" && "components" in param) {
+        const parts = param.components;
+        if (Array.isArray(value) && value.length === parts.length) {
+            return Object.fromEntries(parts.map((part, i) => [part.name, coerce(part, value[i])]));
+        }
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            const given = value;
+            const extra = Object.keys(given).filter((key) => !parts.some((part) => part.name === key));
+            if (extra.length > 0)
+                throw new ProposalError(`${name} has no field ${extra[0]}; its fields are ${parts.map((p) => p.name).join(", ")}`);
+            return Object.fromEntries(parts.map((part) => {
+                if (!(part.name in given))
+                    throw new ProposalError(`${name} is missing ${part.name}; give every field: ${parts.map((p) => p.name).join(", ")}`);
+                return [part.name, coerce(part, given[part.name])];
+            }));
+        }
+        throw fail(`an object with ${parts.map((p) => p.name).join(", ")}`);
+    }
+    throw fail(param.type);
+}
+const show = (value) => {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (Array.isArray(value))
+        return `(${value.map(show).join(", ")})`;
+    if (typeof value === "object" && value !== null)
+        return `{${Object.entries(value).map(([k, v]) => `${k}: ${show(v)}`).join(", ")}}`;
+    return String(value);
+};
+function resolveTarget(network, target) {
+    const addresses = { board: network.contracts.taskBoard, executor: network.contracts.executor, registry: network.contracts.registry };
+    const named = TARGETS.find((t) => t === target || addresses[t].toLowerCase() === target.toLowerCase());
+    if (!named)
+        throw new ProposalError(`--target is board, executor or registry, not "${target}"`);
+    return { target: named, address: addresses[named] };
+}
+/**
+ * The call a proposal asks the executor to make, from --call and --args or
+ * from raw --data, refused here when the executor would refuse it anyway.
+ */
+export function buildCall(network, proposer, input) {
+    const { target, address } = resolveTarget(network, input.target);
+    const abi = GOVERNED[target];
+    const offered = `The ${target} takes ${functions(target).join(", ")}`;
+    let data;
+    if (input.data !== undefined) {
+        if (input.call !== undefined || input.args !== undefined)
+            throw new ProposalError("Give either --data or --call with --args, not both");
+        if (!isHex(input.data) || input.data.length < 10)
+            throw new ProposalError("--data must be the call's hex calldata, starting 0x");
+        data = input.data.toLowerCase();
+    }
+    else {
+        if (!input.call)
+            throw new ProposalError(`--call is required: the function to call. ${offered}.`);
+        const fn = abi.find((item) => item.type === "function" && item.name === input.call);
+        if (!fn || fn.type !== "function")
+            throw new ProposalError(`${offered}, not ${input.call}. setGuardian and setOwner are never queued.`);
+        let args;
+        try {
+            args = JSON.parse(input.args ?? "[]");
+        }
+        catch {
+            throw new ProposalError(`--args must be a JSON array, such as '[300, "0x…"]'`);
+        }
+        if (!Array.isArray(args) || args.length !== fn.inputs.length) {
+            throw new ProposalError(`${fn.name} takes ${fn.inputs.length} argument${fn.inputs.length === 1 ? "" : "s"} (${fn.inputs.map((p) => p.name).join(", ")}), given as a JSON array in --args`);
+        }
+        data = encodeFunctionData({ abi, functionName: fn.name, args: fn.inputs.map((param, i) => coerce(param, args[i])) });
+    }
+    let decoded;
+    try {
+        decoded = decodeFunctionData({ abi, data });
+    }
+    catch {
+        throw new ProposalError(`${offered}; the selector ${data.slice(0, 10)} is none of them`);
+    }
+    if (encodeFunctionData({ abi, functionName: decoded.functionName, args: decoded.args }).toLowerCase() !== data) {
+        throw new ProposalError("--data has bytes beyond the call's arguments");
+    }
+    const args = decoded.args ?? [];
+    if (target === "board" && decoded.functionName === "setWorkerAllowed" && args[1] === true && String(args[0]).toLowerCase() === proposer.toLowerCase()) {
+        throw new ProposalError("Allowing your own wallet to work is an application: run join, which stakes and applies in one go");
+    }
+    return { target, address, data, text: `${decoded.functionName}(${args.map(show).join(", ")})` };
+}
+/** The proposal's URI: base64 JSON the brain shows Jev as the proposer's case. */
+export function caseURI(call, input) {
+    const title = input.title.trim();
+    const rationale = input.rationale.trim();
+    if (!title)
+        throw new ProposalError(`--title is required, up to ${LIMITS.title} characters`);
+    if (!rationale)
+        throw new ProposalError(`--rationale is required: why the change is better, up to ${LIMITS.rationale} characters. Jev reads it to decide.`);
+    const body = { title, rationale, current: input.current?.trim() ?? "", proposed: input.proposed?.trim() || call.text };
+    for (const key of Object.keys(LIMITS)) {
+        if (body[key].length > LIMITS[key])
+            throw new ProposalError(`--${key} is at most ${LIMITS[key]} characters`);
+    }
+    return `data:application/json;base64,${Buffer.from(JSON.stringify(body)).toString("base64")}`;
+}
+const LOG_RANGE = 50000n;
+export function createProposals(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 { bonds, executor, stakeToken } = network.contracts;
+    const proposals = { address: bonds, abi: [...bondsAbi, ...proposalsAbi] };
+    async function scan(fetch) {
+        const to = await client.getBlockNumber();
+        const all = [];
+        for (let start = network.fromBlock; start <= to; start += LOG_RANGE) {
+            all.push(...(await fetch(start, start + LOG_RANGE - 1n < to ? start + LOG_RANGE - 1n : to)));
+        }
+        return all;
+    }
+    async function send(request) {
+        const hash = await wallet.writeContract(request);
+        const receipt = await client.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+        if (receipt.status !== "success")
+            throw new Error(`Transaction ${hash} reverted`);
+        return receipt;
+    }
+    return {
+        account: account.address,
+        now: async () => (await client.getBlock()).timestamp,
+        ethBalance: () => client.getBalance({ address: account.address }),
+        stakeBalance: () => client.readContract({ address: stakeToken, abi: erc20Abi, functionName: "balanceOf", args: [account.address] }),
+        bond: () => client.readContract({ ...proposals, functionName: "bond" }),
+        decideWithin: () => client.readContract({ ...proposals, functionName: "decideWithin" }),
+        changeThresholdBps: async () => BigInt(await client.readContract({ address: executor, abi: executorReadsAbi, functionName: "changeThresholdBps" })),
+        timelock: () => client.readContract({ address: executor, abi: executorAbi, functionName: "timelock" }),
+        vetoed: (call) => client.readContract({
+            address: executor,
+            abi: executorReadsAbi,
+            functionName: "vetoedCall",
+            args: [keccak256(encodeAbiParameters([{ type: "address" }, { type: "bytes" }], [call.address, call.data]))],
+        }),
+        async rehearse(call) {
+            try {
+                await client.call({ account: executor, to: call.address, data: call.data });
+                return undefined;
+            }
+            catch (error) {
+                // Only a revert says the call would fail; an RPC that cannot be reached is a failure of its own.
+                const reverted = error instanceof BaseError ? error.walk((e) => e instanceof ExecutionRevertedError) : null;
+                if (!(error instanceof BaseError) || !reverted)
+                    throw error;
+                const raw = error.walk((e) => typeof e.data === "string");
+                try {
+                    if (raw?.data)
+                        return `${decodeErrorResult({ abi: callErrorsAbi, data: raw.data }).errorName}, the contract's check on these values`;
+                }
+                catch {
+                    // Not one of the contracts' own errors; the node's message says more.
+                }
+                return error.shortMessage;
+            }
+        },
+        async propose(call, uri, bond) {
+            const allowance = await client.readContract({ address: stakeToken, abi: erc20Abi, functionName: "allowance", args: [account.address, bonds] });
+            if (allowance < bond)
+                await send({ address: stakeToken, abi: erc20Abi, functionName: "approve", args: [bonds, bond] });
+            const receipt = await send({ ...proposals, functionName: "propose", args: [call.address, call.data, uri] });
+            const [log] = parseEventLogs({ abi: bondsAbi, eventName: "Proposed", logs: receipt.logs }).filter((l) => l.address.toLowerCase() === bonds.toLowerCase());
+            if (!log)
+                throw new Error(`The proposal landed in ${receipt.transactionHash} but logged no id`);
+            return { id: log.args.id, tx: receipt.transactionHash };
+        },
+        async get(id) {
+            const p = await client.readContract({ ...proposals, functionName: "get", args: [id] });
+            return { id, proposer: p.proposer, bond: p.bond, createdAt: p.createdAt, state: p.state };
+        },
+        async outcome(id) {
+            const [settled, expired] = await Promise.all([
+                scan((fromBlock, toBlock) => client.getContractEvents({ ...proposals, eventName: "Settled", args: { id }, fromBlock, toBlock })),
+                scan((fromBlock, toBlock) => client.getContractEvents({ ...proposals, eventName: "Expired", args: { id }, fromBlock, toBlock })),
+            ]);
+            if (settled[0])
+                return { decisionId: settled[0].args.decisionId, adopted: settled[0].args.adopted };
+            return expired[0] ? "expired" : undefined;
+        },
+        async queued(decisionId) {
+            const [log] = await scan((fromBlock, toBlock) => client.getContractEvents({ address: executor, abi: executorAbi, eventName: "Queued", args: { decisionId }, fromBlock, toBlock }));
+            if (!log)
+                return undefined;
+            const change = await client.readContract({ address: executor, abi: executorAbi, functionName: "getChange", args: [log.args.changeId] });
+            return { changeId: log.args.changeId, eta: change.eta, executed: change.executed, vetoed: change.vetoed };
+        },
+    };
+}
+const hours = (seconds) => `${Number(seconds) / 3600} hours`;
+const days = (seconds) => `${Number(seconds) / 86_400} days`;
+const percent = (bps) => `${Number(bps) / 100}%`;
+export async function propose(network, chain, call, uri, options) {
+    const { log } = options;
+    const [bond, balance, gas, within, threshold, timelock, vetoed, revert] = await Promise.all([
+        chain.bond(),
+        chain.stakeBalance(),
+        chain.ethBalance(),
+        chain.decideWithin(),
+        chain.changeThresholdBps(),
+        chain.timelock(),
+        chain.vetoed(call),
+        chain.rehearse(call),
+    ]);
+    if (vetoed)
+        throw new ProposalError(`The guardian vetoed ${call.text} on the ${call.target} before, so the executor never queues it again`);
+    if (revert)
+        throw new ProposalError(`${call.text} would fail if the executor made it now (${revert}), so the bond would be burned for nothing`);
+    log(`Proposal on ${network.name}
+  Call      ${call.text} on the ${call.target} (${call.address})
+  Data      ${call.data}
+  Bond      ${stake(network, bond)}, returned if Jev adopts the change with at least ${percent(threshold)} confidence, burned otherwise
+  Decision  within ${days(within)}; an adopted change runs ${hours(timelock)} later`);
+    if (options.dry) {
+        log("Dry run, nothing sent.");
+        return;
+    }
+    if (balance < bond) {
+        const buy = network.buyStake ? ` ${network.buyStake}` : "";
+        throw new Error(`The wallet holds ${stake(network, balance)} of the ${stake(network, bond)} bond.${buy}`);
+    }
+    if (gas === 0n)
+        throw new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas}; 0.001 ETH is plenty.`);
+    log(`Bonding ${stake(network, bond)} and proposing...`);
+    const { id, tx } = await chain.propose(call, uri, bond);
+    log(`Proposal ${id} is waiting for Jev (${tx}). Follow it with \`npx brainchain-worker proposal ${id}\`.`);
+}
+export async function proposal(network, chain, id, log) {
+    const p = await chain.get(id);
+    if (p.state === State.None)
+        throw new ProposalError(`There is no proposal ${id} on ${network.name}`);
+    const head = `Proposal ${id} by ${p.proposer}, bond ${stake(network, p.bond)}`;
+    if (p.state === State.Open) {
+        const [within, now] = await Promise.all([chain.decideWithin(), chain.now()]);
+        const closes = p.createdAt + within;
+        const after = now > closes ? `its window closed at ${when(closes)}, so anyone can return the bond with expire` : `Jev decides by ${when(closes)}`;
+        log(`${head}\n  Waiting for Jev: ${after}.`);
+        return;
+    }
+    const outcome = await chain.outcome(id);
+    if (outcome === "expired") {
+        log(`${head}\n  Not decided in its window; the bond was returned.`);
+        return;
+    }
+    if (outcome === undefined) {
+        log(`${head}\n  ${p.state === State.Returned ? "Settled, bond returned" : "Settled, bond burned"}.`);
+        return;
+    }
+    if (!outcome.adopted) {
+        log(`${head}\n  Jev kept the current setting (decision ${outcome.decisionId}); the bond was burned.`);
+        return;
+    }
+    const change = await chain.queued(outcome.decisionId);
+    const state = !change
+        ? "not queued yet"
+        : change.executed
+            ? `change ${change.changeId} has run`
+            : change.vetoed
+                ? `change ${change.changeId} was vetoed by the guardian`
+                : `change ${change.changeId} runs from ${when(change.eta)}`;
+    log(`${head}\n  Jev adopted it (decision ${outcome.decisionId}) and the bond was returned; ${state}.`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "brainchain-worker",
-  "version": "0.4.1",
-  "description": "Earn on BrainChain: stake, apply, and do the tasks Jev hires your agent for, with any command that reads a task and prints the work.",
+  "version": "0.5.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>",
   "homepage": "https://docs.usebrainchain.com/run-a-worker",