brainchain-worker 0.4.2 → 0.5.1

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/network.js

@@ -1,12 +1,12 @@
 import { defineChain, fallback, http, zeroAddress } from "viem";
-/** BrainChain testnet, release 3.1.0. */
+/** BrainChain testnet, release 3.4.0. */
 export const TESTNET = {
     id: "testnet",
     name: "BrainChain testnet",
     chainId: 274630,
     rpc: "https://rpc.testnet.usebrainchain.com",
     service: "https://brain.testnet.usebrainchain.com",
-    fromBlock: 898n,
+    fromBlock: 1793n,
     explorer: "https://usebrainchain.com/testnet",
     stakeSymbol: "tBRAIN",
     bountySymbol: "tUSDG",
@@ -22,11 +22,11 @@ export const TESTNET = {
         gas: "Get Robinhood Chain testnet ETH for gas at https://faucet.testnet.chain.robinhood.com",
     },
     contracts: {
-        taskBoard: "0xC74564F100e70F95346A6e399ebf1Ce14309C8B6",
-        staking: "0xbdC08799D865DA79FE44a469de1FeaE84bb45059",
-        bonds: "0x574060D1A7CA8f3786d2D14fe1A782cc4638CB1e",
-        executor: "0x420484B139001ED5B1DA330e689Cc2f4814001Fb",
-        registry: "0x297AA5fb95Ef9785Da6DC0cA00121060606e2C63",
+        taskBoard: "0x0beA77333E26a257983fCc59B8D857730b5B1D2B",
+        staking: "0x09468dE253517bD5d91b92115cce45798F300Cf0",
+        bonds: "0x34279448dc42b84B479daeF092749020017F001B",
+        executor: "0xFFf56B7B194C190152b17C086c36A2a79f050397",
+        registry: "0xcE777c32824fd5963a9C31C70e9B1c5D9C4ED16e",
         stakeToken: "0xc717546497343911750768335b649b86d0a6eCcf",
         bountyToken: "0xC4ec72794bF3Ce9ba1DE4B38085464c2eb0cDCf2",
     },

package/dist/propose.js

@@ -1,5 +1,6 @@
-import { BaseError, createPublicClient, createWalletClient, decodeFunctionData, encodeAbiParameters, encodeFunctionData, getAddress, http, isAddress, isHex, keccak256, parseAbi, parseEventLogs, size, } from "viem";
-import { bondsAbi, erc20Abi, executorAbi, RECEIPT_MS } from "./chain.js";
+import { BaseError, createPublicClient, createWalletClient, decodeErrorResult, decodeFunctionData, encodeAbiParameters, encodeFunctionData, ExecutionRevertedError, getAddress, isAddress, isHex, keccak256, parseAbi, parseEventLogs, size, slice, } 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. */
@@ -25,9 +26,15 @@ const proposalsAbi = parseAbi([
     "function decideWithin() view returns (uint64)",
 ]);
 const executorReadsAbi = parseAbi([
+    "function vetoed(address target, bytes4 selector) view returns (bool)",
     "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 {
@@ -167,7 +174,7 @@ export function caseURI(call, input) {
 const LOG_RANGE = 50000n;
 export function createProposals(network, account) {
     const chain = chainOf(network);
-    const transport = http(network.rpc, { timeout: 20_000, retryCount: 3 });
+    const transport = brainchainTransport(network);
     const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
     const wallet = createWalletClient({ account, chain, transport });
     const { bonds, executor, stakeToken } = network.contracts;
@@ -196,19 +203,39 @@ export function createProposals(network, account) {
         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]))],
-        }),
+        // A set 3.4.0 executor shuts a function (target and selector) until the admin reopens it; earlier ones block the exact call.
+        vetoed: async (call) => {
+            try {
+                return await client.readContract({ address: executor, abi: executorReadsAbi, functionName: "vetoed", args: [call.address, slice(call.data, 0, 4)] });
+            }
+            catch {
+                return 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) {
-                return error instanceof BaseError ? error.shortMessage : String(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) {
@@ -259,7 +286,7 @@ export async function propose(network, chain, call, uri, options) {
         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`);
+        throw new ProposalError(`The guardian vetoed ${call.text} on the ${call.target}, so the executor does not queue it until the admin reopens that function`);
     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}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "brainchain-worker",
-  "version": "0.4.2",
-  "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.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>",
   "homepage": "https://docs.usebrainchain.com/run-a-worker",