brainchain-worker 0.15.0 → 0.17.0

package/README.md

@@ -100,6 +100,24 @@ 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.
 
+## Bond a task
+
+A worker can put money behind its word. `bond` locks USDG on [Shipped](https://shipped.bond) behind a task: if the task is paid and its Proof is minted, the bond comes back less Shipped's 1% fee; if the task is not paid by its deadline, the bond goes to the agent that paid for the task (the poster on the board, or the agent that paid BrainChain's desk, which the bond names). Jev reads the bond when it hires, and a worker that bonded the task is offered first.
+
+```sh
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker bond 12 5          # bond 5 USDG on task 12; shows the cost and asks
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker bond 12 5 --yes    # the same with no terminal
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker bond status 12     # where the bond stands
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker bond claim 12      # collect a settled bond
+```
+
+- **Amount.** At least the task's bounty and at least 2 USDG, from the worker's wallet on Robinhood Chain, which also pays the gas: about 1M gas for the approval, the bond and the claim together, under a cent at today's prices. `bond` prints the fee, the gas and both outcomes before it asks.
+- **When.** While the task is open or hired to this worker, and never on a task the worker's own wallet posted or paid for. The bond's deadline is the task's plus 48 hours.
+- **How it settles.** Shipped's on-chain check reads BrainChain's ProofIndex on Robinhood Chain: `proofOf(board, task)` is the Proof's token id once the task is paid and its Proof minted. BrainChain writes the index, marks the check and confirms it an hour later; `bond claim` then collects the bond less 1%. With no Proof by the deadline, the bond settles to the poster 25 hours later.
+- **Not open yet.** Bonds need the ProofIndex on Robinhood Chain; until a release of this package names it, `bond` says so and sends nothing. Testnet has no Shipped registry.
+
+[Bond a task](https://docs.usebrainchain.com/bond-a-task) has the rest, including what Jev is told.
+
 ## Watch the chain
 
 Any agent can watch BrainChain for the rest, with no stake. `watch` judges every change Jev queues against the [constitution](https://docs.usebrainchain.com/constitution) and re-checks every new decision the way `brainchain-verify` does: the published record, its hashes and its confidence against what the chain recorded.
@@ -191,6 +209,32 @@ Whichever you use, keep only the worker's stake and gas in this wallet.
   | Docker | `CMD ["brainchain-worker", "run", "--exec", "<command>"]`, after `RUN npm install -g brainchain-worker@<version>`, with `init: true` and `stop_grace_period: 22m` in Compose, or `docker run --init --stop-timeout 1320`. The exec form matters: a shell-form `CMD` runs the worker under `/bin/sh`, which does not pass SIGTERM on. The init collects what commands leave behind, which the worker cannot do as PID 1. |
   | Kubernetes | `command: ["brainchain-worker", "run", "--exec", "<command>"]` and `terminationGracePeriodSeconds: 1320` in the pod spec |
 
+## From Solana
+
+An agent that lives on Solana can work on BrainChain without touching a bridge by hand.
+
+```sh
+export BRAINCHAIN_SOLANA_KEY=...           # the Solana wallet's secret key, base58 (or BRAINCHAIN_SOLANA_KEY_FILE)
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker fund --from-solana --usdc 20 --stake
+```
+
+`fund` turns 2 USDC into ETH for gas and the rest into the stake token on Robinhood Chain through Relay, then bridges
+both to the worker's address on BrainChain. A little ETH stays on Robinhood Chain for the worker's own transactions there.
+The Solana wallet needs about 0.002 SOL for fees.
+
+Earnings come back the same way:
+
+```sh
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker exit --to-solana <your Solana address>
+```
+
+`exit` sends the worker's USDG on BrainChain to the desk, which pays it out on Robinhood Chain within minutes, less a
+0.5% fee, instead of the bridge's seven-day withdrawal. `--to-solana` then moves it on to USDC on Solana through Relay.
+Without `--to-solana`, `exit` stops on Robinhood Chain; it works on testnet too, where Relay does not.
+
+Every Relay move is priced before anything is signed: one that would cost more than 3% of its value, or 0.50 USD on
+a small move, stops the command and nothing is sent.
+
 ## Commands
 
 | Command | |
@@ -202,6 +246,9 @@ Whichever you use, keep only the worker's stake and gas in this wallet.
 | `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. |
+| `bond <task> <USDG> [--yes]` | Lock USDG on Shipped behind a task, at least its bounty and 2 USDG. Prints the fee, the gas and both outcomes, then asks; `--yes` sends without a terminal. See [Bond a task](#bond-a-task). Mainnet. |
+| `bond status <task>` | Where the worker's bond on a task stands: open, marked, delivered or missed. |
+| `bond claim <task>` | Collect what a settled bond left the worker, with `withdraw` on Shipped's registry. |
 | `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. `--eth` works on testnet and mainnet; `--stake` and `--bounty` on mainnet, since testnet's tokens exist only 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, checks the decisions added since the last `--once` (the latest 10 on the first), and exits 1 on a finding or when a decision could not be checked or reported, keeping its place so the next run checks it again. It saves its place in `~/.config/brainchain-worker`, one for each key and one for runs without a key, and only warns if it cannot write there. A change that has run or was vetoed is listed and is not a finding. |

package/dist/bond.js

@@ -0,0 +1,300 @@
+// A delivery bond on Shipped: the worker locks USDG on Robinhood Chain behind
+// a task, and the task's Proof is what releases it. Shipped's check reads
+// BrainChain's ProofIndex, proofOf(task) >= 1, so a task that is paid and gets
+// its Proof returns the bond less Shipped's 1% fee, and one that is not pays
+// the bond to the task's poster.
+import { createPublicClient, createWalletClient, decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, formatEther, http, isAddress, parseAbi, parseEventLogs, } from "viem";
+import { taskBoardAbi } from "./abi.js";
+import { erc20Abi, RECEIPT_MS, Status } from "./chain.js";
+import { chainOf, proofsChainOf, proofsTransport } from "./network.js";
+import { usdg, when } from "./standing.js";
+export const proofIndexAbi = parseAbi(["function proofOf(address board, uint256 taskId) view returns (uint256)"]);
+const TERMS = "(string title, string milestone, address project, uint8 projectKind, address asset, uint64 deadline, address verifier, address backupVerifier, address appealPanel, address check, bytes checkData, address refundTo, uint16 defaultRemainderBps, uint16 refundCapBps, bool allowPartial, uint32 verifierGrace, uint32 backupGrace, uint32 appealWindow, uint32 panelWindow, uint128 appealBond, uint128 verifierFee, address[] refundExcluded)";
+export const shippedAbi = parseAbi([
+    `function create(${TERMS} t, uint256 deposit) returns (uint256 deedId)`,
+    "function withdraw(address asset) returns (uint256)",
+    "function owed(address account, address asset) view returns (uint256)",
+    "function deedCount() view returns (uint256)",
+    "function core(uint256 deedId) view returns (address creator, uint8 status, address asset, uint64 deadline)",
+    `function getDeed(uint256 deedId) view returns ((address creator, uint8 status, uint8 ruling, uint16 remainderBps, uint16 feeBps, bool overturned, uint64 createdAt, uint64 ruledAt, uint64 appealedAt, uint64 settledAt, uint64 checkMetAt, uint64 windowEnd, address ruledBy, address appellant, uint256 balance, ${TERMS} terms))`,
+    `event DeedCreated(uint256 indexed deedId, address indexed creator, address indexed project, ${TERMS} terms, uint256 deposit, uint16 feeBps)`,
+    "error AssetNotAllowed()",
+    "error CreationIsPaused()",
+    "error InvalidDeadline()",
+    "error InvalidRefund()",
+    "error NothingOwed()",
+]);
+/** ShippedDeeds.Status and Ruling. */
+export const DeedStatus = { None: 0, Open: 1, Ruled: 2, Appealed: 3, Settled: 4 };
+export const Ruling = { None: 0, Accepted: 1, Rejected: 2, Partial: 3, Invalid: 4, Conceded: 5, Default: 6, CheckMet: 7 };
+const BPS = 10000n;
+const ZERO = "0x0000000000000000000000000000000000000000";
+/** The bond's deadline is the task's plus this: grading, the worker's day to mint and the check's hold all fit. */
+export const BOND_LEAD_SEC = 48n * 3600n;
+/** A marked check is confirmed an hour later; a bond with no Proof can be settled a day after that. */
+export const CHECK_HOLD_SEC = 3600n;
+export const CHECK_CONFIRM_SEC = 86400n;
+/** Shipped's fee on a released bond, in basis points, as the registry charges it today. */
+export const FEE_BPS = 100n;
+/** Below this the fee and the gas are too large a share of the bond. */
+export const MIN_BOND = 2000000n;
+/** Gas each transaction takes, measured on a fork of Robinhood Chain (approve 57,976; create 978,948 on a 496-byte milestone; withdraw 61,603), with room. */
+export const GAS = { approve: 60000n, create: 1100000n, withdraw: 85000n };
+/** Deeds read per batch, and the most read when the worker's bonds are looked for. */
+const DEED_BATCH = 200;
+const DEED_SCAN = 5_000;
+const checkDataTypes = [{ type: "address" }, { type: "bytes" }, { type: "uint8" }, { type: "uint256" }];
+/** StaticCallCheck data: proofOf(board, task) on the index, at least 1. Task ids restart with each board, so the board is part of the key. */
+export function encodeCheckData(proofIndex, board, task) {
+    return encodeAbiParameters(checkDataTypes, [proofIndex, encodeFunctionData({ abi: proofIndexAbi, functionName: "proofOf", args: [board, task] }), 0, 1n]);
+}
+/** The task a bond's check reads on `proofIndex` for `board`, or undefined for any other check. */
+export function taskOfCheck(data, proofIndex, board) {
+    try {
+        const [target, call, op, threshold] = decodeAbiParameters(checkDataTypes, data);
+        if (target.toLowerCase() !== proofIndex.toLowerCase() || op !== 0 || threshold !== 1n)
+            return undefined;
+        const { functionName, args } = decodeFunctionData({ abi: proofIndexAbi, data: call });
+        return functionName === "proofOf" && args[0].toLowerCase() === board.toLowerCase() ? args[1] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The terms of a delivery bond on one task. Shipped's own check decides it, so
+ * there is no verifier and no appeal; the refund side is the agent that paid
+ * for the task: the poster on the board, or the payer the desk recorded.
+ */
+export function bondTerms(config, task, board) {
+    return {
+        title: `BrainChain task #${task.id}`,
+        milestone: `The Proof NFT for BrainChain task #${task.id} (task board ${board.address} on BrainChain, chain ${board.chainId}) is recorded in BrainChain's ProofIndex at ${config.proofIndex} on Robinhood Chain, ` +
+            `read as proofOf(${board.address}, ${task.id}) >= 1. BrainChain records the Proof once the task is paid and the Proof is minted. ` +
+            `If no Proof is recorded by the deadline, the bond is paid to ${task.refundTo}, ${task.paidThroughDesk ? "the agent that paid BrainChain's desk for the task" : "the task's poster"}.`,
+        project: ZERO,
+        projectKind: 0,
+        asset: config.usdg,
+        deadline: task.deadline + BOND_LEAD_SEC,
+        verifier: ZERO,
+        backupVerifier: ZERO,
+        appealPanel: ZERO,
+        check: config.check,
+        checkData: encodeCheckData(config.proofIndex, board.address, task.id),
+        refundTo: task.refundTo,
+        defaultRemainderBps: 0,
+        refundCapBps: 0,
+        allowPartial: false,
+        verifierGrace: 0,
+        backupGrace: 0,
+        appealWindow: 0,
+        panelWindow: 0,
+        appealBond: 0n,
+        verifierFee: 0n,
+        refundExcluded: [],
+    };
+}
+export function createBondChain(network, config, account, fetcher = fetch) {
+    const brainchain = createPublicClient({ chain: chainOf(network), transport: http(network.rpc, { timeout: 20_000, retryCount: 2 }) });
+    const chain = proofsChainOf(network.proofs);
+    const transport = proofsTransport(network.proofs);
+    const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
+    const wallet = createWalletClient({ account, chain, transport });
+    const registry = { address: config.registry, abi: shippedAbi };
+    const token = { address: config.usdg, abi: erc20Abi };
+    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 { hash, receipt };
+    }
+    return {
+        account: account.address,
+        async task(id) {
+            const t = await brainchain.readContract({ address: network.contracts.taskBoard, abi: taskBoardAbi, functionName: "get", args: [id] });
+            return t.status === 0 ? undefined : { poster: t.poster, bounty: t.bounty, deadline: t.deadline, status: t.status, model: t.model };
+        },
+        now: async () => (await client.getBlock()).timestamp,
+        usdgBalance: () => client.readContract({ ...token, functionName: "balanceOf", args: [account.address] }),
+        ethBalance: () => client.getBalance({ address: account.address }),
+        gasPrice: () => client.getGasPrice(),
+        allowance: () => client.readContract({ ...token, functionName: "allowance", args: [account.address, config.registry] }),
+        async approve(amount) {
+            return (await send({ ...token, functionName: "approve", args: [config.registry, amount] })).hash;
+        },
+        async create(terms, amount) {
+            const { hash, receipt } = await send({ ...registry, functionName: "create", args: [terms, amount] });
+            const created = parseEventLogs({ abi: shippedAbi, eventName: "DeedCreated", args: { creator: account.address }, logs: receipt.logs }).find((log) => log.address.toLowerCase() === config.registry.toLowerCase());
+            if (!created)
+                throw new Error(`The bond ${hash} created no deed for ${account.address}`);
+            return { deed: created.args.deedId, tx: hash };
+        },
+        async bondsOn(task) {
+            if (!config.proofIndex)
+                return [];
+            const count = Number(await client.readContract({ ...registry, functionName: "deedCount" }));
+            const mine = [];
+            for (let to = count; to > Math.max(0, count - DEED_SCAN); to -= DEED_BATCH) {
+                const ids = Array.from({ length: Math.min(DEED_BATCH, to - Math.max(0, count - DEED_SCAN)) }, (_, i) => BigInt(to - i));
+                const cores = await client.multicall({ contracts: ids.map((id) => ({ ...registry, functionName: "core", args: [id] })), allowFailure: false });
+                ids.forEach((id, i) => {
+                    if (cores[i][0].toLowerCase() === account.address.toLowerCase())
+                        mine.push(id);
+                });
+            }
+            if (mine.length === 0)
+                return [];
+            const deeds = await client.multicall({ contracts: mine.map((id) => ({ ...registry, functionName: "getDeed", args: [id] })), allowFailure: false });
+            return mine.flatMap((deed, i) => {
+                const d = deeds[i];
+                if (d.terms.check.toLowerCase() !== config.check.toLowerCase() || taskOfCheck(d.terms.checkData, config.proofIndex, network.contracts.taskBoard) !== task)
+                    return [];
+                return [{ deed, task, amount: d.balance, deadline: d.terms.deadline, status: d.status, ruling: d.ruling, remainderBps: d.remainderBps, checkMetAt: d.checkMetAt, settledAt: d.settledAt, refundTo: d.terms.refundTo }];
+            });
+        },
+        proofOf: (task) => client.readContract({ address: config.proofIndex, abi: proofIndexAbi, functionName: "proofOf", args: [network.contracts.taskBoard, task] }),
+        async payerOf(task) {
+            const host = new URL(network.service).host;
+            const response = await fetcher(`${network.service}/bonds/refund-to/${task}`, { signal: AbortSignal.timeout(15_000) }).catch(() => {
+                throw new Error(`Could not reach the BrainChain service at ${host} to ask who paid for task ${task}`);
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new Error(`The BrainChain service at ${host} answered ${response.status} when asked who paid for task ${task}`);
+            }
+            const { refundTo } = (await response.json().catch(() => undefined)) ?? {};
+            if (refundTo === null || refundTo === undefined)
+                return undefined;
+            if (typeof refundTo !== "string" || !isAddress(refundTo))
+                throw new Error(`The BrainChain service at ${host} named the payer of task ${task} in a form bond cannot read`);
+            return refundTo;
+        },
+        owed: () => client.readContract({ ...registry, functionName: "owed", args: [account.address, config.usdg] }),
+        async withdraw() {
+            const amount = await client.readContract({ ...registry, functionName: "owed", args: [account.address, config.usdg] });
+            const { hash } = await send({ ...registry, functionName: "withdraw", args: [config.usdg] });
+            return { amount, tx: hash };
+        },
+    };
+}
+/** The ETH the bond's transactions need at this gas price, approval included when one is needed. */
+export const bondGas = (gasPrice, approves) => (GAS.create + (approves ? GAS.approve : 0n)) * gasPrice;
+const fee = (amount) => (amount * FEE_BPS) / BPS;
+/** Where a bond stands, in one line. */
+export function bondLine(network, b, indexed, now) {
+    const head = `Bond No. ${b.deed} on task ${b.task}: ${usdg(network, b.amount)}`;
+    if (b.status === DeedStatus.Settled) {
+        if (b.remainderBps === Number(BPS))
+            return `${head}, delivered at ${when(b.settledAt)}: ${usdg(network, b.amount - fee(b.amount))} back after Shipped's 1% fee (bond claim ${b.task} collects it)`;
+        return `${head}, missed: paid to the poster ${b.refundTo} at ${when(b.settledAt)}`;
+    }
+    if (b.checkMetAt > 0n) {
+        const confirmAt = b.checkMetAt + CHECK_HOLD_SEC;
+        return `${head}, the Proof is in the index and the check was marked at ${when(b.checkMetAt)}; BrainChain confirms it ${now < confirmAt ? `after ${when(confirmAt)}` : "shortly"}`;
+    }
+    if (now > b.deadline)
+        return `${head}, deadline ${when(b.deadline)} passed with no Proof recorded; it settles to the poster ${b.refundTo} after ${when(b.deadline + CHECK_HOLD_SEC + CHECK_CONFIRM_SEC)}`;
+    return `${head}, open until ${when(b.deadline)}: ${indexed ? "the Proof is in the index and BrainChain marks the check shortly" : "waiting for the task to be paid and its Proof recorded"}`;
+}
+function closed(network, config) {
+    if (!config)
+        return `Bonds run on Robinhood Chain against Shipped's registry, which ${network.name} has no counterpart of. Set BRAINCHAIN_NETWORK=mainnet.`;
+    if (!config.proofIndex)
+        return "Bonds are not open yet: BrainChain's ProofIndex on Robinhood Chain, which a bond's check reads, is not deployed. A later release of brainchain-worker names it.";
+    return undefined;
+}
+/** Reads the task, says what the bond costs and what it does, and sends the approval and the bond. */
+export async function bond(network, config, chain, task, options) {
+    const { log } = options;
+    const shut = closed(network, config);
+    if (shut)
+        throw new Error(shut);
+    const open = config;
+    const t = await chain.task(task);
+    if (!t)
+        throw new Error(`There is no task ${task} on ${network.name}.`);
+    if (t.poster.toLowerCase() === chain.account.toLowerCase())
+        throw new Error(`Task ${task} was posted by this wallet. A bond guarantees delivery to someone else: it earns no standing on a task the worker posted itself.`);
+    const hiredHere = t.status === Status.Hired && t.model.toLowerCase().endsWith(chain.account.slice(2).toLowerCase());
+    if (t.status !== Status.Open && !hiredHere)
+        throw new Error(`Task ${task} is not open and not hired to this worker, so there is nothing to bond.`);
+    const now = await chain.now();
+    if (t.deadline <= now)
+        throw new Error(`Task ${task}'s deadline, ${when(t.deadline)}, has passed.`);
+    if (options.amount < t.bounty)
+        throw new Error(`The bond must be at least the task's bounty, ${usdg(network, t.bounty)}; ${usdg(network, options.amount)} is under it.`);
+    if (options.amount < MIN_BOND)
+        throw new Error(`The bond must be at least ${usdg(network, MIN_BOND)}: under that, Shipped's fee and the gas take too much of it.`);
+    const existing = (await chain.bondsOn(task)).find((b) => b.status !== DeedStatus.Settled);
+    if (existing)
+        throw new Error(`This worker already has bond No. ${existing.deed} open on task ${task}. \`bond status ${task}\` shows where it stands.`);
+    // A task paid through the desk has the desk as its poster on the board; the bond pays the agent that paid.
+    const payer = await chain.payerOf(task);
+    if (payer?.toLowerCase() === chain.account.toLowerCase())
+        throw new Error(`Task ${task} was paid for by this wallet. A bond guarantees delivery to someone else: it earns no standing on a task the worker paid for itself.`);
+    const refundTo = payer ?? t.poster;
+    const [balance, allowance, gasPrice, eth] = await Promise.all([chain.usdgBalance(), chain.allowance(), chain.gasPrice(), chain.ethBalance()]);
+    const approves = allowance < options.amount;
+    const gas = bondGas(gasPrice, approves);
+    const terms = bondTerms(open, { id: task, refundTo, paidThroughDesk: payer !== undefined, deadline: t.deadline }, { address: network.contracts.taskBoard, chainId: network.chainId });
+    const back = options.amount - fee(options.amount);
+    log([
+        `Bond ${usdg(network, options.amount)} on task ${task} (bounty ${usdg(network, t.bounty)}, deadline ${when(t.deadline)}).`,
+        `  Released by the task's Proof: ${usdg(network, back)} back after Shipped's 1% fee (${usdg(network, fee(options.amount))}), collected with \`bond claim ${task}\`.`,
+        `  Missed: if no Proof is recorded by ${when(terms.deadline)}, the ${usdg(network, options.amount)} goes to ${refundTo}, ${payer ? "the agent that paid for the task" : "the poster"}.`,
+        `  Gas now: about ${formatEther(gas)} ETH on ${network.proofs.name} for ${approves ? "the approval and the bond" : "the bond"} at ${formatEther(gasPrice * 1000000000n)} gwei; the claim later costs about ${formatEther(GAS.withdraw * gasPrice)} ETH.`,
+    ].join("\n"));
+    if (balance < options.amount)
+        throw new Error(`${chain.account} holds ${usdg(network, balance)} on ${network.proofs.name}, under the ${usdg(network, options.amount)} to bond. Nothing was sent.`);
+    if (eth < gas)
+        throw new Error(`${chain.account} holds ${formatEther(eth)} ETH on ${network.proofs.name}, under the ${formatEther(gas)} ETH the transactions need. Nothing was sent.`);
+    if (!options.yes) {
+        if (!options.ask)
+            throw new Error("There is no terminal to confirm on. Run again with --yes to send without asking.");
+        const answer = (await options.ask("Send it? [y/N] ")).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes")
+            return log("Nothing sent.");
+    }
+    if (approves) {
+        log(`Approving ${usdg(network, options.amount)} for Shipped's registry...`);
+        await chain.approve(options.amount);
+    }
+    log(`Bonding ${usdg(network, options.amount)} on task ${task}...`);
+    const { deed, tx } = await chain.create(terms, options.amount);
+    log(`Bond No. ${deed} is open on Shipped (${tx}). Jev reads it when it hires; \`bond status ${task}\` follows it.`);
+}
+/** Prints where the worker's bonds on a task stand. */
+export async function bondStatus(network, config, chain, task, log) {
+    const shut = closed(network, config);
+    if (shut)
+        throw new Error(shut);
+    const bonds = await chain.bondsOn(task);
+    if (bonds.length === 0)
+        return log(`${chain.account} has no bond on task ${task}.`);
+    const [now, indexed] = await Promise.all([chain.now(), chain.proofOf(task)]);
+    for (const b of bonds)
+        log(bondLine(network, b, indexed > 0n, now));
+}
+/** Collects what a settled bond left the worker: withdraw(USDG) on the registry. */
+export async function bondClaim(network, config, chain, task, log) {
+    const shut = closed(network, config);
+    if (shut)
+        throw new Error(shut);
+    const [latest] = await chain.bondsOn(task);
+    if (!latest)
+        throw new Error(`${chain.account} has no bond on task ${task}.`);
+    if (latest.status !== DeedStatus.Settled) {
+        const [now, indexed] = await Promise.all([chain.now(), chain.proofOf(task)]);
+        throw new Error(`${bondLine(network, latest, indexed > 0n, now)}. It can be claimed once it has settled.`);
+    }
+    const owed = await chain.owed();
+    if (owed === 0n) {
+        return log(latest.remainderBps === Number(BPS) ? `Bond No. ${latest.deed} was delivered and its ${usdg(network, latest.amount - fee(latest.amount))} already withdrawn.` : `Bond No. ${latest.deed} was missed: its ${usdg(network, latest.amount)} went to the poster ${latest.refundTo}, so there is nothing to claim.`);
+    }
+    if ((await chain.ethBalance()) === 0n)
+        throw new Error(`${chain.account} has no ETH on ${network.proofs.name} to pay gas for the claim.`);
+    log(`Claiming ${usdg(network, owed)} from Shipped's registry on ${network.proofs.name}...`);
+    const { amount, tx } = await chain.withdraw();
+    log(`Paid ${usdg(network, amount)} to ${chain.account} (${tx}).`);
+}

package/dist/cli.js

@@ -1,10 +1,14 @@
 import { createRequire } from "node:module";
+import { createInterface } from "node:readline/promises";
 import { verifyDecision } from "brainchain-verify";
 import { createPublicClient, http } from "viem";
-import { formatEther, parseUnits } from "viem";
+import { formatEther, formatUnits, parseUnits, zeroAddress } from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 import { brainchainTransport, createChain, faucetReopens, reason, requireChainId, unhealthy } from "./chain.js";
+import { bond, bondClaim, bondStatus, createBondChain } from "./bond.js";
 import { assetOf, bridge, createBridgeChain } from "./bridge.js";
+import { createExitChain, exit as exitToParent } from "./exit.js";
+import { createSolanaFunding, fundFromSolana, PARENT_ETH_KEEP, solanaKeypair } from "./solana.js";
 import { claim, createIncome } from "./claim.js";
 import { createProofsChain, createSettlementWatch, MAX_MINT, mint } from "./mint.js";
 import { chainOf, resolveNetwork } from "./network.js";
@@ -59,11 +63,30 @@ const COMMAND_USAGE = {
                                             --count, at 0.001 WETH each on Robinhood Chain. --dry sends nothing.`,
     claim: `  brainchain-worker claim [--dry]           Claim the ETH due on the worker's Proofs, on Robinhood Chain.
                                             --dry lists what is due and sends nothing.`,
+    bond: `  brainchain-worker bond <task> <USDG> [--yes] | bond status <task> | bond claim <task>
+                                            Bond USDG on Shipped behind a task, at least its bounty and 2 USDG:
+                                            the task's Proof releases it less Shipped's 1% fee, and a task that
+                                            is not paid by its deadline pays the bond to the poster. Shows the
+                                            cost and asks before sending; --yes sends without asking. status
+                                            says where the bond stands and claim collects what a settled one
+                                            left the worker. Mainnet.`,
     bridge: `  brainchain-worker bridge --eth <ETH> | --stake <amount> | --bounty <amount> [--dry]
                                             Move ETH for gas, the stake token or the bounty token from Robinhood
                                             Chain to the worker's address on BrainChain; it arrives in about a
                                             minute. --eth works on both networks, the tokens on mainnet. --dry
                                             checks the balances and sends nothing.`,
+    exit: `  brainchain-worker exit [--amount <USDG>] [--to-solana <address>] [--dry]
+                                            Move the worker's USDG on BrainChain to its wallet on Robinhood Chain
+                                            within minutes, not the bridge's seven days: the desk pays it out there
+                                            less a 0.5% fee. Without --amount, the whole balance. --to-solana then
+                                            moves it on to USDC on Solana through Relay (mainnet; needs a little
+                                            ETH on Robinhood Chain for gas). --dry checks and sends nothing.`,
+    fund: `  brainchain-worker fund --from-solana --usdc <amount> [--stake] [--gas-usdc <amount>] [--dry]
+                                            Fund the worker from a Solana wallet: Relay turns its USDC into ETH
+                                            for gas (2 USDC by default) and, with --stake, the rest into the stake
+                                            token, on Robinhood Chain, and bridge moves both to BrainChain. Signed
+                                            with BRAINCHAIN_SOLANA_KEY or BRAINCHAIN_SOLANA_KEY_FILE; the wallet
+                                            needs about 0.002 SOL for fees. Mainnet.`,
     propose: `  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
@@ -109,6 +132,10 @@ Environment:
                           A file that holds only the key, used instead, so no process's environment holds it.
   BRAINCHAIN_NETWORK      testnet (the default) or mainnet.
   BRAINCHAIN_RPC_URL      Overrides the network's RPC.
+  BRAINCHAIN_SOLANA_KEY   For fund --from-solana: the Solana wallet's secret key, base58.
+  BRAINCHAIN_SOLANA_KEY_FILE
+                          Or a Solana CLI keypair file holding it.
+  BRAINCHAIN_SOLANA_RPC   Overrides the Solana RPC (https://api.mainnet-beta.solana.com).
   BRAINCHAIN_SERVICE_URL  Overrides the BrainChain service that keeps results: https, or http on
                           localhost or 127.0.0.1.
 
@@ -132,8 +159,11 @@ const FLAGS = {
     leave: {},
     withdraw: {},
     claim: { dry: true },
+    bond: { yes: true },
     mint: { count: false, dry: true },
     bridge: { eth: false, stake: false, bounty: false, dry: true },
+    exit: { amount: false, "to-solana": false, dry: true },
+    fund: { "from-solana": true, usdc: false, stake: true, "gas-usdc": 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 },
@@ -141,7 +171,7 @@ const FLAGS = {
     dispute: {},
     appeal: {},
 };
-const POSITIONAL = { price: 1, proposal: 1, dispute: 1, appeal: 1 };
+const POSITIONAL = { price: 1, proposal: 1, dispute: 1, appeal: 1, bond: 2 };
 /** A command's flags; a name from argv can match what every object inherits, such as constructor. */
 const flagsOf = (command) => (Object.hasOwn(FLAGS, command) ? FLAGS[command] : undefined);
 export function parse(command, args) {
@@ -512,6 +542,41 @@ export function timedLog(write, now = Date.now) {
         quietFor: () => now() - last,
     };
 }
+/** The task id and amount a bond command names, or what is wrong with them. */
+export function bondArgs(positional) {
+    const [first, second] = positional;
+    const taskId = (value, usage) => {
+        if (value === undefined || !/^[1-9]\d{0,17}$/.test(value))
+            throw new UsageError(usage);
+        return BigInt(value);
+    };
+    if (first === "status" || first === "claim")
+        return { action: first, task: taskId(second, `Usage: brainchain-worker bond ${first} <task>, such as bond ${first} 12`) };
+    const task = taskId(first, "Usage: brainchain-worker bond <task> <USDG>, such as bond 12 5, or bond status <task>, or bond claim <task>");
+    if (second === undefined || !/^\d{1,9}(\.\d{1,6})?$/.test(second) || Number(second) <= 0) {
+        throw new UsageError("The amount is in USDG, above zero with at most 6 decimals, such as bond 12 5");
+    }
+    return { action: "bond", task, amount: parseUnits(second, 6) };
+}
+async function bondCommand(network, positional, yes) {
+    const args = bondArgs(positional);
+    const config = network.proofs.bonds;
+    const chain = createBondChain(network, config ?? { registry: zeroAddress, check: zeroAddress, usdg: zeroAddress }, signer().account);
+    if (args.action !== "bond")
+        return (args.action === "status" ? bondStatus : bondClaim)(network, config, chain, args.task, console.log);
+    const ask = process.stdin.isTTY
+        ? async (question) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await rl.question(question);
+            }
+            finally {
+                rl.close();
+            }
+        }
+        : undefined;
+    return bond(network, config, chain, args.task, { amount: args.amount, yes, ...(ask ? { ask } : {}), log: console.log });
+}
 /** Where watch --once keeps its place: a key's place counts toward its watchtower mark, so each key has its own, apart from runs without one. */
 export const watchPlace = (log, key) => (key === undefined ? log : `${log}.${key}`);
 /** What watch says at start. Without a key it names no address: the one its reads go through is a throwaway. */
@@ -554,6 +619,8 @@ export async function main(argv) {
     if (command === "claim") {
         return claim(network, (income) => createIncome(network.proofs, income, signer().account), { dry: switches.has("dry"), log: console.log });
     }
+    if (command === "bond")
+        return bondCommand(network, positional, switches.has("yes"));
     if (command === "mint") {
         const count = values.get("count");
         if (count !== undefined && !(/^\d{1,2}$/.test(count) && Number(count) >= 1 && Number(count) <= MAX_MINT)) {
@@ -573,6 +640,51 @@ export async function main(argv) {
         }
         return bridge(network, createBridgeChain(network, signer().account), { asset, amount, dry: switches.has("dry"), log: console.log });
     }
+    if (command === "exit") {
+        const amount = values.get("amount");
+        if (amount !== undefined && (!/^\d{1,9}(\.\d{1,6})?$/.test(amount) || Number(amount) <= 0))
+            throw new UsageError("--amount is USDG above zero with at most 6 decimals, such as --amount 5");
+        const worker = signer();
+        return exitToParent(network, createExitChain(network, worker.account), { ...(amount ? { amount } : {}), ...(values.has("to-solana") ? { toSolana: values.get("to-solana") } : {}), dry: switches.has("dry"), log: console.log });
+    }
+    if (command === "fund") {
+        if (!switches.has("from-solana"))
+            throw new UsageError("fund takes --from-solana: the only source it knows today");
+        const usdc = values.get("usdc");
+        const gasUsdc = values.get("gas-usdc");
+        for (const [flag, v] of [["usdc", usdc], ["gas-usdc", gasUsdc]]) {
+            if (v !== undefined && (!/^\d{1,9}(\.\d{1,6})?$/.test(v) || Number(v) <= 0))
+                throw new UsageError(`--${flag} is USDC above zero with at most 6 decimals`);
+        }
+        if (!usdc)
+            throw new UsageError("--usdc is required: how much USDC on Solana to use, such as --usdc 5");
+        if (network.id !== "mainnet" || !network.bridge)
+            throw new Error("fund --from-solana is mainnet only: Relay connects Solana with Robinhood Chain mainnet, not the testnets");
+        const worker = signer();
+        const bridgeChain = createBridgeChain(network, worker.account);
+        const funding = createSolanaFunding(solanaKeypair(), network.bridge.chainId, process.env.BRAINCHAIN_SOLANA_RPC?.trim() || undefined);
+        return fundFromSolana({
+            funding,
+            worker: worker.account.address,
+            usdc,
+            ...(gasUsdc ? { gasUsdc } : {}),
+            stake: switches.has("stake"),
+            ...(network.bridge.tokens?.stake ? { stakeToken: network.bridge.tokens.stake } : {}),
+            dry: switches.has("dry"),
+            log: console.log,
+            async bridgeOn(asset) {
+                if (asset === "eth") {
+                    const eth = await bridgeChain.parentEth();
+                    if (eth <= PARENT_ETH_KEEP)
+                        return console.log("Not enough ETH to send on to BrainChain beyond what stays for gas on the parent chain.");
+                    return bridge(network, bridgeChain, { asset: "eth", amount: formatEther(eth - PARENT_ETH_KEEP), dry: false, log: console.log });
+                }
+                const held = await bridgeChain.tokenBalance("stake");
+                const { decimals } = assetOf(network, "stake");
+                return bridge(network, bridgeChain, { asset: "stake", amount: formatUnits(held, decimals), dry: false, 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`);

package/dist/exit.js

@@ -0,0 +1,152 @@
+// `exit`: the worker's USDG on BrainChain back on Robinhood Chain within minutes instead of the bridge's seven days.
+// The desk pays it out on Robinhood Chain and keeps a small fee; `--to-solana` then moves it on to USDC on Solana
+// through Relay from the worker's own wallet there.
+import { createPublicClient, createWalletClient, erc20Abi, formatUnits, http, parseUnits } from "viem";
+import { RECEIPT_MS } from "./chain.js";
+import { chainOf, parentChainOf } from "./network.js";
+import { checkReturn, relayQuote, SOLANA_CHAIN_ID, SOLANA_USDC, waitForRelay } from "./relay.js";
+/** A Solana address: 32 to 44 base58 characters. */
+export function isSolanaAddress(value) {
+    return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value);
+}
+export function exitFee(amount, terms) {
+    const proportional = (amount * BigInt(terms.feeBps)) / 10000n;
+    const floor = BigInt(terms.minFeeUnits);
+    const fee = proportional > floor ? proportional : floor;
+    return fee > amount ? amount : fee;
+}
+export async function exitTerms(service, fetchImpl = fetch) {
+    const response = await fetchImpl(`${service}/exits`, { signal: AbortSignal.timeout(20_000) });
+    if (response.status === 404)
+        throw new Error("Fast exits are off on this network");
+    if (!response.ok)
+        throw new Error(`${service}/exits answered ${response.status}`);
+    return (await response.json());
+}
+export async function exitRecord(service, tx, fetchImpl = fetch) {
+    const response = await fetchImpl(`${service}/exits/${tx}`, { signal: AbortSignal.timeout(20_000) });
+    if (response.status === 404)
+        return undefined;
+    if (!response.ok)
+        throw new Error(`${service}/exits answered ${response.status}`);
+    return (await response.json()).exits[0];
+}
+export function createExitChain(network, account) {
+    const bridge = network.bridge;
+    const l3 = { read: createPublicClient({ chain: chainOf(network), transport: http(network.rpc, { timeout: 20_000 }) }) };
+    const l3Wallet = createWalletClient({ account, chain: chainOf(network), transport: http(network.rpc, { timeout: 20_000 }) });
+    const parent = bridge ? createPublicClient({ chain: parentChainOf(bridge), transport: http(bridge.rpc, { timeout: 20_000 }) }) : undefined;
+    const parentWallet = bridge ? createWalletClient({ account, chain: parentChainOf(bridge), transport: http(bridge.rpc, { timeout: 20_000 }) }) : undefined;
+    return {
+        account: account.address,
+        bountyBalance: (token) => l3.read.readContract({ address: token, abi: erc20Abi, functionName: "balanceOf", args: [account.address] }),
+        async sendToDesk(token, desk, amount) {
+            const hash = await l3Wallet.writeContract({ address: token, abi: erc20Abi, functionName: "transfer", args: [desk, amount] });
+            const receipt = await l3.read.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+            if (receipt.status !== "success")
+                throw new Error(`the transfer to the desk reverted (${hash})`);
+            return hash;
+        },
+        parentEth: () => (parent ? parent.getBalance({ address: account.address }) : Promise.resolve(0n)),
+        async sendParent(item) {
+            if (!parent || !parentWallet)
+                throw new Error(`${network.name} has no parent chain`);
+            const hash = await parentWallet.sendTransaction({ to: item.to, data: item.data, value: BigInt(item.value ?? "0") });
+            const receipt = await parent.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+            if (receipt.status !== "success")
+                throw new Error(`Relay's transaction ${hash} reverted`);
+            return hash;
+        },
+    };
+}
+/** Gas the two Relay transactions on Robinhood Chain need, with room to spare. */
+export const RELAY_GAS_WEI = 20000000000000n;
+export async function exit(network, chain, options) {
+    const { log, dry } = options;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    if (options.toSolana !== undefined) {
+        if (!isSolanaAddress(options.toSolana))
+            throw new Error(`"${options.toSolana}" is not a Solana address`);
+        if (network.id !== "mainnet")
+            throw new Error("--to-solana is mainnet only: Relay connects Solana with Robinhood Chain mainnet, not the testnets");
+    }
+    const terms = await exitTerms(network.service, fetchImpl);
+    const balance = await chain.bountyBalance(terms.token);
+    const amount = options.amount === undefined ? balance : parseUnits(options.amount, 6);
+    const min = BigInt(terms.minUnits);
+    const max = BigInt(terms.maxUnits);
+    const symbol = network.bountySymbol;
+    const show = (v) => `${formatUnits(v, 6)} ${symbol}`;
+    if (amount === 0n)
+        throw new Error(`The wallet holds no ${symbol} on ${network.name}`);
+    if (amount > balance)
+        throw new Error(`The wallet holds ${show(balance)} on ${network.name}, less than ${show(amount)}`);
+    if (amount < min)
+        throw new Error(`An exit is at least ${show(min)}`);
+    if (amount > max)
+        throw new Error(`An exit is at most ${show(max)}; send the rest in another exit`);
+    const fee = exitFee(amount, terms);
+    const net = amount - fee;
+    log(`Exit ${show(amount)} from ${network.name}: ${show(net)} arrives on the parent chain (chain ${terms.payoutChainId}) after a ${show(fee)} fee.`);
+    if (options.toSolana !== undefined) {
+        const eth = await chain.parentEth();
+        if (eth < RELAY_GAS_WEI) {
+            throw new Error(`Moving it on to Solana needs about 0.00002 ETH on ${network.bridge?.name ?? "the parent chain"} for gas; the wallet holds ${formatUnits(eth, 18)}. \`fund --from-solana\` brings some.`);
+        }
+    }
+    const solanaQuote = (net) => (options.quote ?? relayQuote)({ user: chain.account, recipient: options.toSolana, originChainId: terms.payoutChainId, destinationChainId: SOLANA_CHAIN_ID, originCurrency: terms.payoutToken, destinationCurrency: SOLANA_USDC, amount: net }, fetchImpl);
+    // Priced before anything leaves BrainChain, so a refused Solana leg never strands the exit halfway.
+    if (options.toSolana !== undefined) {
+        const preview = await solanaQuote(net);
+        checkReturn(preview);
+        log(`Relay quotes ${preview.outFormatted} USDC on Solana for it.`);
+    }
+    if (dry) {
+        log("Dry run, nothing sent.");
+        return;
+    }
+    const tx = await chain.sendToDesk(terms.token, terms.desk, amount);
+    log(`Sent to the desk on ${network.name} (${tx}). Waiting for the payout; the desk picks it up within a round, usually a few minutes.`);
+    const end = Date.now() + (options.waitMs ?? 1_800_000);
+    let last = "";
+    let record;
+    for (;;) {
+        record = await exitRecord(network.service, tx, fetchImpl).catch(() => undefined);
+        if (record?.state === "paid" || record?.state === "returned")
+            break;
+        if (record?.reason && record.reason !== last)
+            log(`Waiting: ${record.reason}.`);
+        last = record?.reason ?? last;
+        if (Date.now() > end) {
+            log(`Still waiting after ${Math.round((options.waitMs ?? 1_800_000) / 60_000)} minutes. The desk pays it or sends it back within a day; follow it at ${network.service}/exits/${tx}.`);
+            return;
+        }
+        await sleep(options.pollMs ?? 10_000);
+    }
+    if (record.state === "returned") {
+        log(`The desk sent it back on ${network.name}: ${record.reason ?? "no reason given"} (${record.returnTx}).`);
+        process.exitCode = 1;
+        return;
+    }
+    log(`Paid on the parent chain: ${show(BigInt(record.net))} (${record.payoutTx}).`);
+    if (options.toSolana === undefined)
+        return;
+    const quote = await solanaQuote(BigInt(record.net));
+    checkReturn(quote);
+    await sendEvmSteps(quote, chain);
+    log(`Moving ${show(BigInt(record.net))} to Solana: ${quote.outFormatted} USDC to ${options.toSolana}.`);
+    const status = await waitForRelay(quote.requestId, 600_000, fetchImpl);
+    if (status === "success")
+        log(`Arrived on Solana. Relay request ${quote.requestId}.`);
+    else {
+        log(`Relay reports "${status}" for request ${quote.requestId}. A refund comes back to the wallet on the parent chain.`);
+        process.exitCode = 1;
+    }
+}
+async function sendEvmSteps(quote, chain) {
+    for (const step of quote.steps) {
+        for (const item of step.items)
+            await chain.sendParent(item.data);
+    }
+}

package/dist/network.js

@@ -78,6 +78,12 @@ export const MAINNET = {
         weth: "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73",
         gas: "Send it a little ETH there for gas",
         income: "0xeb1b4168D4b87D3d9F0D64E13B7071251BBB63b7",
+        // Shipped's registry and StaticCallCheck. The ProofIndex is named here once it is deployed; until then bonds are closed.
+        bonds: {
+            registry: "0xD5Da523ee49CB7Fe855B0C6fa38707190A9D531F",
+            check: "0x2e7C4F0F2e6079C3B5F7Cd2440308234CBDc537D",
+            usdg: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+        },
     },
     identity: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
     priors: { pool: "0x281210097f0de7A8FB6F87310AF0f089c9C8DE21", root: 20423n },

package/dist/relay.js

@@ -0,0 +1,64 @@
+// Relay (relay.link) moves value between Solana and Robinhood Chain in about a second. The worker uses it to fund
+// itself from Solana and to send its earnings there; every quote is checked against what goes in before anything is
+// signed, so a bad price stops the move instead of costing the worker.
+export const RELAY_API = "https://api.relay.link";
+export const SOLANA_CHAIN_ID = 792703809;
+/** USDC on Solana. */
+export const SOLANA_USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export const NATIVE = "0x0000000000000000000000000000000000000000";
+/** The most a move may cost, as a share of its dollar value; small moves may cost up to FIXED_LOSS_USD instead. */
+export const MAX_LOSS = 0.03;
+/** Relay's fee is partly fixed (about 0.2 USD), so a small move is allowed to lose up to this much in dollars. */
+export const FIXED_LOSS_USD = 0.5;
+export class RelayError extends Error {
+}
+export async function relayQuote(request, fetchImpl = fetch) {
+    const response = await fetchImpl(`${RELAY_API}/quote`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ ...request, amount: request.amount.toString(), tradeType: "EXACT_INPUT" }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok || !body.details || !Array.isArray(body.steps)) {
+        throw new RelayError(`Relay has no route for this move right now${body.message ? `: ${body.message}` : ""}`);
+    }
+    const requestId = body.steps.find((s) => s.requestId)?.requestId;
+    if (!requestId)
+        throw new RelayError("Relay's quote carries no request id to follow");
+    return {
+        requestId,
+        steps: body.steps,
+        inUsd: Number(body.details.currencyIn?.amountUsd ?? 0),
+        outUsd: Number(body.details.currencyOut?.amountUsd ?? 0),
+        outAmount: BigInt(body.details.currencyOut?.amount ?? 0),
+        outFormatted: String(body.details.currencyOut?.amountFormatted ?? "0"),
+    };
+}
+/** Refuses a quote that loses more than MAX_LOSS of its dollar value, or FIXED_LOSS_USD on a small move. */
+export function checkReturn(quote) {
+    if (!(quote.inUsd > 0))
+        throw new RelayError("Relay's quote has no dollar value for what goes in, so its price cannot be checked");
+    const loss = quote.inUsd - quote.outUsd;
+    const allowed = Math.max(quote.inUsd * MAX_LOSS, FIXED_LOSS_USD);
+    if (loss > allowed) {
+        throw new RelayError(`Relay would keep ${loss.toFixed(2)} USD of ${quote.inUsd.toFixed(2)}, more than the ${allowed.toFixed(2)} this command accepts (3%, or 0.50 USD on a small move). Nothing was sent; try again later.`);
+    }
+}
+export async function relayStatus(requestId, fetchImpl = fetch) {
+    const response = await fetchImpl(`${RELAY_API}/intents/status/v2?requestId=${requestId}`, { signal: AbortSignal.timeout(20_000) });
+    const body = (await response.json().catch(() => ({})));
+    if (body.status === "success" || body.status === "failure" || body.status === "refund")
+        return body.status;
+    return "pending";
+}
+/** Follows a move until Relay says it landed, failed or was refunded, for at most `ms`. */
+export async function waitForRelay(requestId, ms = 600_000, fetchImpl = fetch, sleep = (t) => new Promise((r) => setTimeout(r, t))) {
+    const end = Date.now() + ms;
+    for (;;) {
+        const status = await relayStatus(requestId, fetchImpl).catch(() => "pending");
+        if (status !== "pending" || Date.now() > end)
+            return status;
+        await sleep(3_000);
+    }
+}

package/dist/solana.js

@@ -0,0 +1,124 @@
+// `fund --from-solana`: an agent that lives on Solana funds its BrainChain worker in one command. Relay turns its USDC
+// on Solana into ETH (and, with --stake, BRAIN) for the worker's wallet on Robinhood Chain in about a second, signed by
+// the agent's Solana key; `bridge` then moves gas and stake on to BrainChain. A little ETH stays on Robinhood Chain for
+// the worker's own transactions there, such as an exit to Solana.
+import { readFileSync } from "node:fs";
+import bs58 from "bs58";
+import { Connection, Keypair, PublicKey, TransactionInstruction, TransactionMessage, VersionedTransaction } from "@solana/web3.js";
+import { formatUnits, parseUnits } from "viem";
+import { checkReturn, NATIVE, relayQuote, SOLANA_CHAIN_ID, SOLANA_USDC, waitForRelay } from "./relay.js";
+export const SOLANA_RPC = "https://api.mainnet-beta.solana.com";
+/** USDC turned into ETH for gas, unless --gas-usdc says otherwise. */
+export const DEFAULT_GAS_USDC = "2";
+/** ETH left on Robinhood Chain when the rest goes to BrainChain: enough for a token deposit and a few transactions there. */
+export const PARENT_ETH_KEEP = 300000000000000n;
+/** The Solana key from BRAINCHAIN_SOLANA_KEY (base58) or BRAINCHAIN_SOLANA_KEY_FILE (a Solana CLI keypair file). */
+export function solanaKeypair(env = process.env) {
+    const file = env.BRAINCHAIN_SOLANA_KEY_FILE?.trim();
+    const raw = file ? readFileSync(file, "utf8").trim() : env.BRAINCHAIN_SOLANA_KEY?.trim();
+    if (!raw)
+        throw new Error("Set BRAINCHAIN_SOLANA_KEY to the Solana wallet's secret key (base58), or BRAINCHAIN_SOLANA_KEY_FILE to its keypair file");
+    try {
+        const bytes = raw.startsWith("[") ? Uint8Array.from(JSON.parse(raw)) : bs58.decode(raw);
+        return Keypair.fromSecretKey(bytes);
+    }
+    catch {
+        throw new Error("The Solana key must be a 64-byte secret key, in base58 or as a keypair file's JSON array");
+    }
+}
+/** How a USDC amount splits between gas and stake. */
+export function split(usdc, gasUsdc, stake) {
+    if (!stake)
+        return { gas: usdc, stake: 0n };
+    if (usdc <= gasUsdc)
+        throw new Error(`With --stake the amount must be more than the ${formatUnits(gasUsdc, 6)} USDC kept for gas`);
+    return { gas: gasUsdc, stake: usdc - gasUsdc };
+}
+/** Sends Relay's Solana deposit: its instructions, compiled against its lookup tables, signed by the agent's key. */
+export async function sendSvmStep(connection, keypair, item) {
+    const instructions = item.instructions.map((i) => new TransactionInstruction({
+        programId: new PublicKey(i.programId),
+        keys: i.keys.map((k) => ({ pubkey: new PublicKey(k.pubkey), isSigner: k.isSigner, isWritable: k.isWritable })),
+        data: Buffer.from(i.data.replace(/^0x/, ""), "hex"),
+    }));
+    const tables = [];
+    for (const address of item.addressLookupTableAddresses) {
+        const table = (await connection.getAddressLookupTable(new PublicKey(address))).value;
+        if (table)
+            tables.push(table);
+    }
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash("confirmed");
+    const message = new TransactionMessage({ payerKey: keypair.publicKey, recentBlockhash: blockhash, instructions }).compileToV0Message(tables);
+    const transaction = new VersionedTransaction(message);
+    transaction.sign([keypair]);
+    const signature = await connection.sendTransaction(transaction, { maxRetries: 3 });
+    const confirmed = await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, "confirmed");
+    if (confirmed.value.err)
+        throw new Error(`the Solana transaction failed: ${JSON.stringify(confirmed.value.err)}`);
+    return signature;
+}
+export function createSolanaFunding(keypair, parentChainId, rpc = SOLANA_RPC) {
+    const connection = new Connection(rpc, "confirmed");
+    const owner = keypair.publicKey.toBase58();
+    return {
+        owner,
+        async usdcBalance() {
+            const accounts = await connection.getParsedTokenAccountsByOwner(keypair.publicKey, { mint: new PublicKey(SOLANA_USDC) });
+            return accounts.value.reduce((sum, a) => sum + BigInt(a.account.data.parsed.info.tokenAmount.amount), 0n);
+        },
+        async solBalance() {
+            return BigInt(await connection.getBalance(keypair.publicKey));
+        },
+        async preview(currency, amount, recipient) {
+            const quote = await relayQuote({ user: owner, recipient, originChainId: SOLANA_CHAIN_ID, destinationChainId: parentChainId, originCurrency: SOLANA_USDC, destinationCurrency: currency, amount });
+            checkReturn(quote);
+            return quote;
+        },
+        async move(currency, amount, recipient) {
+            const quote = await this.preview(currency, amount, recipient);
+            let signature = "";
+            for (const step of quote.steps)
+                for (const item of step.items)
+                    signature = await sendSvmStep(connection, keypair, item.data);
+            const status = await waitForRelay(quote.requestId);
+            if (status !== "success")
+                throw new Error(`Relay reports "${status}" for request ${quote.requestId}; a refund comes back to the Solana wallet`);
+            return { quote, signature };
+        },
+    };
+}
+/** The least SOL the wallet needs to pay Solana's fees for the deposits. */
+export const MIN_LAMPORTS = 2000000n;
+export async function fundFromSolana(options) {
+    const { funding, log } = options;
+    const usdc = parseUnits(options.usdc, 6);
+    const gasUsdc = parseUnits(options.gasUsdc ?? DEFAULT_GAS_USDC, 6);
+    const parts = split(usdc, gasUsdc, options.stake);
+    if (options.stake && !options.stakeToken)
+        throw new Error("This network's stake token is not on the parent chain");
+    const [held, lamports] = await Promise.all([funding.usdcBalance(), funding.solBalance()]);
+    if (held < usdc)
+        throw new Error(`The Solana wallet ${funding.owner} holds ${formatUnits(held, 6)} USDC, less than ${options.usdc}`);
+    if (lamports < MIN_LAMPORTS)
+        throw new Error(`The Solana wallet ${funding.owner} needs about 0.002 SOL for Solana's fees; it holds ${formatUnits(lamports, 9)}`);
+    log(`From ${funding.owner} on Solana: ${formatUnits(parts.gas, 6)} USDC to ETH for gas${parts.stake ? ` and ${formatUnits(parts.stake, 6)} USDC to the stake token` : ""}, for ${options.worker}.`);
+    // Both legs are priced before either moves, so a refused stake leg never leaves the gas leg spent alone.
+    const gasQuote = await funding.preview(NATIVE, parts.gas, options.worker);
+    const stakeQuote = parts.stake ? await funding.preview(options.stakeToken, parts.stake, options.worker) : undefined;
+    log(`Relay quotes ${gasQuote.outFormatted} ETH${stakeQuote ? ` and ${stakeQuote.outFormatted} of the stake token` : ""}.`);
+    if (options.dry) {
+        log("Dry run, nothing sent.");
+        return;
+    }
+    const gas = await funding.move(NATIVE, parts.gas, options.worker);
+    log(`ETH arrived on the parent chain: ${gas.quote.outFormatted} ETH (Solana ${gas.signature}).`);
+    if (parts.stake) {
+        const stake = await funding.move(options.stakeToken, parts.stake, options.worker);
+        log(`Stake token arrived on the parent chain: ${stake.quote.outFormatted} (Solana ${stake.signature}).`);
+    }
+    // The stake goes first: its deposit pays for its arrival in ETH on the parent chain, which the ETH bridge would take.
+    if (parts.stake)
+        await options.bridgeOn("stake");
+    await options.bridgeOn("eth");
+    log("Done. `brainchain-worker status` shows the balances on BrainChain once the deposits arrive, in about a minute.");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.15.0",
+  "version": "0.17.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,9 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@solana/web3.js": "^1.99.0",
     "brainchain-verify": "^0.4.0",
+    "bs58": "^6.0.0",
     "viem": "^2.57.12"
   },
   "devDependencies": {