brainchain-worker 0.4.0 → 0.4.2

package/dist/propose.js

@@ -0,0 +1,318 @@
+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 { 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)",
+]);
+/** 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 = http(network.rpc, { timeout: 20_000, retryCount: 3 });
+    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) {
+                return error instanceof BaseError ? error.shortMessage : String(error);
+            }
+        },
+        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/dist/standing.js

@@ -1,6 +1,11 @@
 import { formatUnits } from "viem";
 import { ApplicationState } from "./chain.js";
-export const stake = (network, amount) => `${formatUnits(amount, 18)} ${network.stakeSymbol}`;
+/** A token amount with thousands separators, such as 1,250,000; a fraction is kept as it is. */
+function grouped(amount, decimals) {
+    const [whole, fraction] = formatUnits(amount, decimals).split(".");
+    return `${whole.replace(/\B(?=(\d{3})+$)/g, ",")}${fraction === undefined ? "" : `.${fraction}`}`;
+}
+export const stake = (network, amount) => `${grouped(amount, 18)} ${network.stakeSymbol}`;
 export const usdg = (network, amount) => `${formatUnits(amount, 6)} ${network.bountySymbol}`;
 export const when = (seconds) => new Date(Number(seconds) * 1000).toISOString().replace(".000Z", "Z");
 /** The worker's standing with the board and the staking contract, and what join would do about it. */
@@ -47,7 +52,8 @@ export function hireable({ allowed, w, min, applications, change, pending }, net
 }
 /**
  * The wallet's stake token and, below the minimum stake, where join would find
- * what it needs. A stake token without a faucet has no `faucet`.
+ * what it needs. A stake token without a faucet has no `faucet`; one that is
+ * bought instead says where.
  */
 export function wallet(network, s, balance, bond, faucet, now) {
     const has = stake(network, balance);
@@ -60,7 +66,8 @@ export function wallet(network, s, balance, bond, faucet, now) {
         return `${has}; join needs ${stake(network, need)} and claims the rest from the faucet, which gives ${stake(network, faucet.amount)} a day`;
     const reopens = faucet ? `. The faucet opens again for this wallet at ${when(faucet.opensAt)}` : "";
     const unstaking = s.w.unstaking > 0n ? `, and the ${stake(network, s.w.unstaking)} unstaking can be withdrawn ${now >= s.w.unlocksAt ? "now" : `after ${when(s.w.unlocksAt)}`}` : "";
-    return `${has}; join needs ${stake(network, need)}${reopens}${unstaking}`;
+    const buy = network.buyStake ? `. ${network.buyStake}` : "";
+    return `${has}; join needs ${stake(network, need)}${reopens}${unstaking}${buy}`;
 }
 /** What join says when the wallet holds too little of a stake token that has no faucet. */
 export function shortOfStake(network, w, balance, need, now) {

package/dist/state.js

@@ -126,8 +126,8 @@ export function lock(file) {
 }
 /**
  * Moves the state 0.3.0 and earlier kept per address alone to `file`, once,
- * when it was kept for `board`. State for the other network stays where it is
- * until a run there moves it.
+ * when it was kept for `board`, and says whether it did. State for the other
+ * network stays where it is until a run there moves it.
  */
 function migrate(old, file, board) {
     let text;
@@ -136,30 +136,32 @@ function migrate(old, file, board) {
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return;
+            return false;
         throw error;
     }
     if (parse(text)?.board !== board.toLowerCase())
-        return;
+        return false;
     // A run from before the move may still be working on this network's tasks from the old file.
     const pid = holder(`${old}.lock`);
     if (alive(pid))
         throw held(pid, `${old}.lock`);
     if (existsSync(`${file}.json`))
-        return;
+        return false;
     // Removed rather than moved: this run already holds the new lock.
     rmSync(`${old}.lock`, { force: true });
     renameSync(`${old}.json`, `${file}.json`);
+    return true;
 }
 /**
  * Takes the worker's lock on one network and loads its saved state. Each
  * network has its own `<address>.<network>.json` and `.lock`, so one key can
  * run on testnet and mainnet at once without sharing cursors or tasks.
  */
-export function openStore(address, network, warn, dir = stateDir()) {
+export function openStore(address, network, log = console.log, dir = stateDir()) {
     const old = join(dir, address);
     const file = `${old}.${network.id}`;
     lock(`${file}.lock`);
-    migrate(old, file, network.contracts.taskBoard);
-    return fileStore(`${file}.json`, network.contracts.taskBoard, warn);
+    if (migrate(old, file, network.contracts.taskBoard))
+        log(`moved ${old}.json to ${file}.json`);
+    return fileStore(`${file}.json`, network.contracts.taskBoard, (message) => log(`warning: ${message}`));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.4.0",
+  "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.",
   "license": "MIT",
   "author": "BrainChain <hello@usebrainchain.com>",