@blockula/mcp 0.5.1 → 1.0.2

package/README.md

@@ -3,11 +3,11 @@
 🧛 MCP server that lets any coding agent use **Blockula**, a post-quantum blockchain. Agents can hold a wallet, send FANG, claim `.boo` names, stake, vote on proposals, look things up in plain English, and start or summon chains.
 
 ```bash
-claude mcp add blockula -- npx -y @blockula/mcp                      # the public testnet
-claude mcp add blockula -- npx -y @blockula/mcp --network local      # a `blockula dev` chain on this machine
+claude mcp add blockula -- npx -y @blockula/mcp                                   # a `blockula dev` chain on this machine
+claude mcp add blockula -e BLOCKULA_RPC=https://<your node> -- npx -y @blockula/mcp   # a chain you launched (`blockula summon`)
 ```
 
-With no configuration it connects to the public testnet at `https://blockula-testnet.fly.dev`. Call `status` to see which network and chain you're on.
+With no configuration it connects to a `blockula dev` node on this machine (`http://localhost:7070`). The public testnet (`blockula-testnet-2`) was retired in November 2026 and has no public node, so nothing public is built in: for any other chain, set `BLOCKULA_RPC` to a node of it. Call `status` to see which network and chain you're on.
 
 To run an exact release, name it: `npx -y @blockula/mcp@0.5.0` (the first release on npm, for the protocol v1 testnet `blockula-testnet-2`). Each release pins its whole dependency tree (exact versions plus a published `npm-shrinkwrap.json`), so what runs next to the agent's key is what CI tested.
 
@@ -15,10 +15,10 @@ To run an exact release, name it: `npx -y @blockula/mcp@0.5.0` (the first releas
 
 The network is chosen by the user, once, in the MCP's configuration, and nothing changes it while the server runs: it never switches to whatever answers on `localhost:7070`, and no tool can point it somewhere else.
 
-- `--network` (or `BLOCKULA_NETWORK`): `testnet` (default), `mainnet`, `local` (`http://localhost:7070`) or `custom`.
-- `BLOCKULA_RPC` picks the node: required for `custom`, and for `mainnet` until public mainnet RPCs are built in. Plain `http://` only on this machine or a private network.
-- Every network pins a chain id (`blockula-1` for mainnet, `blockula-testnet-2` for the testnet, with the `tboo` address prefix), and a genesis hash where one is known (`KNOWN_GENESIS` in `src/network.ts`: a release pins a launched chain's). `BLOCKULA_CHAIN_ID` and `BLOCKULA_GENESIS_HASH` pin them for any node. Whatever isn't pinned is pinned from the first status the node reports and remembered in `~/.blockula/known-chains.json` (except for local dev chains, which `--reset` replaces).
-- A node reporting another chain id, genesis hash or address prefix is refused, before anything is signed, at startup or mid-session. If a network was relaunched on purpose under the same chain id, the user removes its entry from `known-chains.json` or sets `BLOCKULA_GENESIS_HASH`. (A relaunch takes a new chain id, as the testnet's did: an entry remembered for the old `blockula-testnet` isn't held against `blockula-testnet-2`.)
+- `--network` (or `BLOCKULA_NETWORK`): `local` (default, `http://localhost:7070`), `testnet` or `custom`.
+- `BLOCKULA_RPC` picks the node: required for `testnet` (its public node was retired: without one the MCP refuses to start and says so) and `custom`. Plain `http://` only on this machine or a private network, and no query or fragment. A node written two ways (`Node.Example`, `:443`, a trailing `/.`) is one node: it's never its own witness.
+- The testnet pins its chain id (`blockula-testnet-2`, with the `tboo` address prefix), and every network pins a genesis hash where one is known (`KNOWN_GENESIS` in `src/network.ts`: a release pins a launched chain's). `BLOCKULA_CHAIN_ID` and `BLOCKULA_GENESIS_HASH` pin them for any node. Whatever isn't pinned is pinned from the first status the node reports and remembered in `~/.blockula/known-chains.json` (except for local dev chains, which `--reset` replaces).
+- A node reporting another chain id, genesis hash or address prefix is refused, before anything is signed, at startup or mid-session. So is one whose chain id isn't 1 to 64 letters, digits, `-`, `_` or `.` (the chain id names files and ledger entries here) or whose genesis hash isn't 64 hex characters. If a network was relaunched on purpose under the same chain id, the user removes its entry from `known-chains.json` or sets `BLOCKULA_GENESIS_HASH`. (A relaunch takes a new chain id, as the testnet's did: an entry remembered for the old `blockula-testnet` isn't held against `blockula-testnet-2`.) A node that says it's on `blockula-1` is refused too, unless the user set `BLOCKULA_CHAIN_ID=blockula-1`: it's never pinned on first use, so a configuration that didn't name that chain can't land there.
 
 `start_dev_node` starts a local chain, but the MCP only uses it when it was configured with `--network local`.
 
@@ -32,25 +32,64 @@ The network is chosen by the user, once, in the MCP's configuration, and nothing
 | Staking | `stake`, `unstake`, `withdraw_stake`, `my_stake` |
 | Governance | `list_proposals`, `vote` |
 | Hunts and contributions | `list_hunts`, `link_github`, `fund_hunt`, `contribution_pool`, `submit_contribution`, `my_contributions` |
+| Programs (read only) | `program_show`, `program_view`, `program_code` (and `lookup` of a program address or code hash) |
 | Running chains | `install_node`, `start_dev_node`, `summon_chain` |
 
-**Getting paid for code:** once a PR to a pool repo merges, `submit_contribution` claims it for the user's account (the PR's author must be their linked GitHub handle). If you act through a session key, the user first registers it as a Familiar. Validators check GitHub, a human jury scores it, and rewards vest to the user. `my_contributions` tracks it. The bond counts toward `BLOCKULA_MAX_SEND` / `BLOCKULA_MAX_DAILY`. Testnet FANG, Hunts and Soul have no monetary value and come with no promise of any mainnet allocation.
+Tools carry a title and annotations: the reads are `readOnlyHint`, and everything that signs is `destructiveHint` and `openWorldHint`. To skip the prompt for reads only, allow them by name in Claude Code's `.claude/settings.json`, and leave the tools that move FANG to ask every time:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__blockula__status", "mcp__blockula__tx_status", "mcp__blockula__wallet_info",
+      "mcp__blockula__check_name", "mcp__blockula__lookup", "mcp__blockula__latest_blocks",
+      "mcp__blockula__my_stake", "mcp__blockula__list_proposals", "mcp__blockula__list_hunts",
+      "mcp__blockula__contribution_pool", "mcp__blockula__my_contributions",
+      "mcp__blockula__program_show", "mcp__blockula__program_view", "mcp__blockula__program_code"
+    ]
+  }
+}
+```
+
+Never allow `mcp__blockula__*`: that lets every send through without asking.
+
+**Getting paid for code:** a Hunt's creator awards its bounty after the PR merges, to the account linked to the PR author's GitHub (`link_github`, which needs an owner key: through a session key, the user links GitHub in their wallet). Once a PR to a pool repo merges, `submit_contribution` claims it for the user's account. It checks the GitHub link first and refuses one that doesn't verify (`force: true` overrides), since validators would refute the claim. The bond is returned unless validators refute the claim or the jury marks it spam. If you act through a session key, the user first registers it as a Familiar. Validators check GitHub, a human jury scores it, and rewards vest to the user. `my_contributions` tracks it. The bond counts toward `BLOCKULA_MAX_SEND` / `BLOCKULA_MAX_DAILY`. FANG, Hunts and Soul have no value, on any chain.
 
 **Spending a user's money safely:**
-1. `create_wallet`, then `use_account` with the user's account address (`boo1…`: the web wallet's Devices & agents → Give an agent a budget shows it, with the name as a label). A name works on test chains; on mainnet an unproven name answers `needs_confirmation` with the address it resolved to, for the user to compare with the one their wallet shows. Until the user has authorized the key it answers with a `grant_code`: this key's signed consent to joining that one account (no secret in it). Hand it to the user. A key id alone can't be added (AddKey needs the key's consent, so nobody can pad the key's account list).
-2. The user pastes it in the Blockula web wallet at https://blockula-wallet.vercel.app (Devices & agents → Give an agent a budget) and picks a limit and an expiry. The chain enforces both.
+1. `create_wallet`, then `use_account` with the user's account address (`boo1…`: the web wallet's Devices & agents → Give an agent a budget shows it, with the name as a label). A name works on any chain but `blockula-1`; there an unproven name answers `needs_confirmation` with the address it resolved to, for the user to compare with the one their wallet shows. Until the user has authorized the key it answers with a `grant_code`: this key's signed consent to joining that one account (no secret in it). Hand it to the user. A key id alone can't be added (AddKey needs the key's consent, so nobody can pad the key's account list).
+2. The user pastes it in the Blockula web wallet (Devices & agents → Give an agent a budget) and picks a limit and an expiry. The chain enforces both.
 3. `use_account` with the same address again, then `send`.
 
+`use_account` returns a `check_code` (the wallet shows the same code for the key) and, on a chain with a public wallet built in, the wallet's address (none is, since the public testnet was retired). An address with no account gets no grant code: it can't add a key until it has FANG. The account the agent acts for is kept per chain: a testnet account doesn't follow the agent to another network.
+
+**What can be spent.** `wallet_info` (and `use_account`) say what the account can move now (`transferable`), what's `locked` and until when, the session key's allowance this window and when it resets, the caps, and `spendable_now`: the smallest of them, with the one that binds. What the chain would refuse by the node's own answers is refused before anything is signed, sent or counted: a session key signing anything but a transfer (or a Familiar's claim), more than its allowance left, a payment past what the account can move, or a key that isn't on the account. A lying node can only cause such a refusal, never a spend.
+
+**What a payment costs.** Paying an address with no account yet burns the account creation fee (0.1 FANG today) on top. `send` reports it as `account_opening_fee_burned`, and `total_cost` is the amount, the fee charged and that burn.
+
 Session keys can only send transfers: staking, voting and name renewals need an owner key (the agent's own account, or one the user made it an owner of). Staking and voting lock FANG for weeks, so ask the user first.
 
-**Spending caps.** `BLOCKULA_MAX_SEND` bounds what one call moves and `BLOCKULA_MAX_DAILY` what leaves the account per UTC day through this MCP. Every FANG-moving tool counts: `send` (with the fee and, for a new account, the opening fee), `stake`, `fund_hunt`, `register_name` and `renew_name` (their price, computed from the chain's parameters and never below the node's quote; a node that doesn't report one is refused), `submit_contribution` (the bond), and every tx's fee. A spend is reserved before the tx is sent, under the tx's (account, nonce) slot. Only the unused part of a final tx's max fee comes back. Everything else stays counted: a tx that failed in a block (its fee was charged), one the node dropped unrun, one that is pending or unknown, and even one the node refused, since a lying node can answer "refused" and relay the signed tx anyway. A refused tx stops being counted twice when the MCP signs its next tx with the same nonce (at most one tx per slot can execute). A tx that isn't final within `BLOCKULA_TX_WAIT_MS` comes back as `"status": "pending"` (or `"dropped"`, `"unknown"`) with its `tx_id`: it was submitted and still counts, so check `tx_status` instead of sending it again. `tx_status` keeps the distinction: `"failed"` ran in a block (final, its fee was charged), `"dropped"` was dropped from that node's mempool unrun (nothing charged, but another node may still include it until its `valid_until`, which comes from what this MCP signed: `agent-txs.json`), and a tx this MCP signed that the node can't show (pruned, never held) is read against the account's nonce: `"nonce_used"` (a tx with that nonce ran, this one or one that took its nonce: it can never execute again, and may already have gone through), `"expired"` (the nonce was still unused past `valid_until`: it never ran; proven with `BLOCKULA_WITNESSES`, else the node's word), otherwise `"unknown"` (in flight until `valid_until`). With witnesses only the nonce is proven: which tx used it is the node's word. A tx signed on another network (every network shares `agent-txs.json`, and each record names its chain) is `"other_chain"`: ask that network. By default `BLOCKULA_MAX_DAILY` is `BLOCKULA_MAX_SEND` plus 1 FANG for fees, so one full-size call fits in a day. The chain itself enforces a session key's limit; these caps are the MCP's own (`wallet_info` shows today's total).
+**Spending caps.** `BLOCKULA_MAX_SEND` bounds what one call moves and `BLOCKULA_MAX_DAILY` what leaves the account per UTC day on each chain through this MCP. Every FANG-moving tool counts: `send` (with the fee and, for a new account, the opening fee), `stake`, `fund_hunt`, `register_name` and `renew_name` (their price, computed from the chain's parameters and never below the node's quote; a node that doesn't report one is refused), `submit_contribution` (the bond), and every tx's fee. A spend is reserved before the tx is sent, under the tx's (chain, account, nonce) slot. Only the unused part of a final tx's max fee comes back. Everything else stays counted: a tx that failed in a block (its fee was charged), one the node dropped unrun, one that is pending or unknown, and even one the node refused, since a lying node can answer "refused" and relay the signed tx anyway. A refused tx stops being counted twice when the MCP signs its next tx with the same nonce (at most one tx per slot can execute). The ledger keeps a total per chain (`agent-spend.json`, still readable by 0.5.1: its `spent` is every chain's total, and spend it can't place on a chain counts toward each). Building, signing and submitting take one tx at a time per account, in this process and across sessions sharing `BLOCKULA_HOME`, so parallel calls don't collide on a nonce. A tx that isn't final within `BLOCKULA_TX_WAIT_MS` comes back as `"status": "pending"` (or `"dropped"`, `"unknown"`) with its `tx_id`: it was submitted and still counts, so check `tx_status` instead of sending it again. `tx_status` keeps the distinction: `"failed"` ran in a block (final, its fee was charged), `"dropped"` was dropped from that node's mempool unrun (nothing charged, but another node may still include it until its `valid_until`, which comes from what this MCP signed: `agent-txs.json`), and a tx this MCP signed that the node can't show (pruned, never held) is read against the account's nonce: `"nonce_used"` (a tx with that nonce ran, this one or one that took its nonce: it can never execute again, and may already have gone through), `"expired"` (the nonce was still unused past `valid_until`: it never ran; proven with `BLOCKULA_WITNESSES`, else the node's word), otherwise `"unknown"` (in flight until `valid_until`). With witnesses only the nonce is proven: which tx used it is the node's word. A tx signed on another network (every network shares `agent-txs.json`, and each record names its chain) is `"other_chain"`: ask that network. By default `BLOCKULA_MAX_DAILY` is `BLOCKULA_MAX_SEND` plus 1 FANG for fees, so one full-size call fits in a day. The chain itself enforces a session key's limit; these caps are the MCP's own (`wallet_info` shows today's total).
 
-**Names in signatures.** `send`, `stake`, `unstake` and `use_account` take `.boo` names. With `BLOCKULA_WITNESSES` (comma-separated URLs of other nodes of the same chain, held to the same pins), each name is proven against them before it's signed, so a lying node can't redirect it, and a tx's height may not be ahead of the lowest of their heads (each must answer). Every tx's height is also checked against the chain's genesis clock (its start time and block time: built in for a known genesis, else read from the node's `/api/genesis` the first time and remembered with the genesis hash in `known-chains.json`): a node reporting a height the chain can't have reached by this machine's clock gets nothing signed. Without witnesses, `send` signs the name itself: the chain pays whoever owns it when the tx runs, so a lying node can't point it at another account now (the result says `recipient_signed_as` and what the node says the owner is now, unproven), but it could hold the signed tx and release it later, after the name changed hands: pay a name that's about to expire by address. `stake`, `unstake` and `use_account` need an address, so a name is the node's word: the result shows the address and says `UNPROVEN`, and on mainnet (any node on `blockula-1`, whatever the configuration calls the network) nothing is signed until the user confirms the address (the tool answers `needs_confirmation` with the address; call it again with the address). `use_account` checks the account's own key list, not `/api/key`. A partial `unstake` signs the amount, and the chain converts it to pool shares at its own price when the tx runs, so no node's report of the stake decides how much unbonds; `all` signs every share the node reports (a lie there can only unbond less, or fail on chain).
+**What the caps protect.** The MCP's caps protect against mistakes. (The daily one is per chain: a key used on two chains has that budget on each.) They don't protect against a compromised agent: the agent's own shell can read its key file and rewrite the ledger. What protects the user's FANG from a compromised agent is the session key's limit, which the chain enforces. So spend through a session key (`use_account`), with a small limit and a near expiry, and keep the agent's own account nearly empty.
+
+**Names in signatures.** `send`, `stake`, `unstake` and `use_account` take `.boo` names. With witnesses (`BLOCKULA_WITNESSES`: comma-separated URLs of other nodes of the same chain, held to the same pins; `status` lists them), each name is proven against them before it's signed, so a lying node can't redirect it, and a tx's height may not be ahead of the lowest of their heads (each must answer). Every tx's height is also checked against the chain's genesis clock (its start time and block time: built in for a known genesis, else read from the node's `/api/genesis` the first time and remembered with the genesis hash in `known-chains.json`): a node reporting a height the chain can't have reached by this machine's clock gets nothing signed. Without witnesses, `send` signs the name itself: the chain pays whoever owns it when the tx runs, so a lying node can't point it at another account now (the result says `recipient_signed_as` and what the node says the owner is now, unproven), but it could hold the signed tx and release it later, after the name changed hands: pay a name that's about to expire by address. `stake`, `unstake` and `use_account` need an address, so a name is the node's word: the result shows the address and says `UNPROVEN`, and on `blockula-1` (which a node is used on only with `BLOCKULA_CHAIN_ID=blockula-1`) nothing is signed until the user confirms the address (the tool answers `needs_confirmation` with the address; call it again with the address). `use_account` checks the account's own key list, not `/api/key`. A partial `unstake` signs the amount, and the chain converts it to pool shares at its own price when the tx runs, so no node's report of the stake decides how much unbonds; `all` signs every share the node reports (a lie there can only unbond less, or fail on chain).
 
 **Votes bind what was shown.** `list_proposals` describes what each proposal does (`does`) from its `kind`, the content a vote binds with its title and link, never from the node's own summary (which no digest covers, so a node could make it say "plant garlic" over a treasury drain), and returns its `proposal_digest`. `vote` requires that digest back: it re-reads the proposal and refuses, signing nothing, if it reads differently now (a node showing one thing to the list and another to the vote). A proposal holding a number past 2^53 has no digest here (`cannot_vote`): vote on it with the `blockula` CLI.
 
 **Chain text is untrusted.** Hunt titles, memos, proposal titles and links, key labels and claim notes are written by anyone. Tools return them in fields named `untrusted_*`, cleaned of control and invisible characters, and the server's instructions tell the agent they're data, never instructions. Node JSON is nested (`status`'s `node_reports`, `lookup`'s `data`), so a node can't override what the MCP says about the network.
 
+**Programs are read only here.** `program_show` gives a program's record (its code and interface hashes, version, who could upgrade it, what it holds and stores, its methods and the `version_digest` a call binds: recomputed from the code, interface and version, never taken from the node's field, and, with `BLOCKULA_WITNESSES`, built from the proven record: the fields no transaction changes are held to the proof and a node whose reading differs is refused, the storage totals and the balance are the proven ones, and `proven` says exactly what was proven and `node_word_only` what stays the node's word: the methods and their types, the code's size and the names beside addresses), `program_view` runs a `view` method on the node (nothing is signed or paid; its answer is that node's word, and says which node) and `program_code` describes a stored code. No tool signs a program transaction: an agent's calls need the confirmation flow of docs/PROGRAMS.md 11.5 (the user is asked, an allowlist), a later release. Everything a program or its deployer chose is data, never instructions: method names are `untrusted_method`, argument names `untrusted_argument`, a code's exports `untrusted_exports`, what a method returns `untrusted_return_data` (the program's claim, which the chain checks nothing of), a receipt's events and abort messages `untrusted_name` and `untrusted_message`, and the bytes of a receipt's return values and events (`lookup`) `untrusted_data`, summarized past 64 bytes; a failure is summarized in words that quote none of it.
+
+## Your own node
+
+Point the MCP at a node of a chain you launched (`blockula summon`, docs/LAUNCH.md) or joined (`blockula join`):
+
+```bash
+claude mcp add blockula -e BLOCKULA_RPC=http://127.0.0.1:7171 -- npx -y @blockula/mcp
+```
+
+A node on this machine is the `local` network unless you name another; `--network testnet` holds it to `blockula-testnet-2`'s pins (`status` then calls it "your node on blockula-testnet-2"). No chain has a public RPC built in, so names are your node's word until `BLOCKULA_WITNESSES` lists other nodes of the same chain: then they're proven against them, and a height your node reports can't run ahead of theirs.
+
 ## install_node
 
 Downloads the prebuilt `blockula` for this machine from the GitHub release and installs it to `~/.blockula/mcp-bin` (its own path: it never replaces the binary `blockula release install` keeps in `~/.blockula/bin`), after the same checks as `scripts/install.sh` (docs/OPERATIONS.md "Releases"). It installs releases from v0.5.0 on: earlier releases' `checksums.txt` names no tag, so nothing binds them to the version asked for, and it refuses them. (Validators install with `blockula release install` instead, which checks against a pinned release key id.)
@@ -66,19 +105,21 @@ The checks add up: each refuses a release it fails. The result lists what was ve
 
 | Env | Default | |
 |---|---|---|
-| `BLOCKULA_NETWORK` | `testnet` | `mainnet`, `testnet`, `local` or `custom` (same as `--network`) |
-| `BLOCKULA_RPC` | the network's public RPC | node URL |
-| `BLOCKULA_CHAIN_ID` / `BLOCKULA_GENESIS_HASH` | the network's pins | the chain the node must be on |
-| `BLOCKULA_HOME` | `~/.blockula` | the agent key (mode 600), the spending ledger and `known-chains.json` |
+| `BLOCKULA_NETWORK` | `local` | `local`, `testnet` or `custom` (same as `--network`) |
+| `BLOCKULA_RPC` | `http://localhost:7070` for `local`; required for `testnet` and `custom` | node URL (no query or fragment) |
+| `BLOCKULA_CHAIN_ID` / `BLOCKULA_GENESIS_HASH` | the network's pins | the chain the node must be on. A node that says it's on `blockula-1` is used only with `BLOCKULA_CHAIN_ID=blockula-1` |
+| `BLOCKULA_HOME` | `~/.blockula` | what the MCP keeps, each file mode 600 but the log: `agent-wallet.json` (the agent key and the account it acts for on each chain), `agent-spend.json` (the spending ledger), `agent-txs.json` (the txs it signed, for `tx_status`), `known-chains.json`, `nonces/` (per account: the last nonce signed, and a `.lock` file while a tx is built and sent, which the session holding it keeps touching; one left by a dead session, or untouched for two minutes, is taken over, or delete it), `grant-<chain id>-<address>.txt` (the grant code `use_account` hands out, one per account that hasn't authorized the key yet), and `dev-node.log` (`start_dev_node`'s log) |
 | `BLOCKULA_MAX_SEND` | `100` | max FANG one call moves: sent, staked, escrowed, paid for a name, bonded (and per vote) |
-| `BLOCKULA_MAX_DAILY` | `BLOCKULA_MAX_SEND` + 1 | max FANG leaving the account per UTC day across all calls, fees and pending, dropped or refused txs included (persisted in `BLOCKULA_HOME`) |
-| `BLOCKULA_WITNESSES` | none | other nodes of the same chain (comma-separated https URLs): names that get signed are proven against them |
+| `BLOCKULA_MAX_DAILY` | `BLOCKULA_MAX_SEND` + 1 | max FANG leaving the account per UTC day on this chain across all calls, fees and pending, dropped or refused txs included (persisted in `BLOCKULA_HOME`) |
+| `BLOCKULA_WITNESSES` | none | other nodes of the same chain (comma-separated https URLs): names that get signed are proven against them. `none` opts out |
 | `BLOCKULA_TIMEOUT_MS` | `15000` | how long one request to the node may take (at most 2147483647) |
 | `BLOCKULA_TX_WAIT_MS` | `15000` | how long a tx tool waits for finality before answering `pending` |
 | `BLOCKULA_BIN` | of `~/.blockula/bin/blockula` (`blockula release install`, checked against the pinned key) and `~/.blockula/mcp-bin/blockula` (`install_node`), the one whose `--version` is this MCP's, the first if both or neither are; else `blockula` | node binary used by `start_dev_node` / `summon_chain` (they say which ran, and when it isn't this MCP's version) |
 | `BLOCKULA_REQUIRE_VERIFY` | unset | `1`: `install_node` refuses a release it can only checksum, and with a release key id requires provenance too |
 | `BLOCKULA_RELEASE_KEY_ID` | built in after the key ceremony | release signing key id to trust (must agree with the built-in one and the pin) |
 
-`npm test -w @blockula/mcp` checks the network rules, the pins, the release checks and the dependency pins offline, and runs the built server against a fake node (`test/spend.ts`: the spending caps with pending, refused (and a node that refuses but relays), failed, dropped and final txs, name prices, untrusted text, timeouts, unproven names).
+A bad value in any of them (a cap that isn't an amount, a duration out of range) doesn't stop the server: every tool answers with the configuration error.
+
+`npm test -w @blockula/mcp` checks the network rules, the pins, the release checks and the dependency pins offline, and runs the built server against fake nodes (`test/spend.ts`: the spending caps with pending, refused (and a node that refuses but relays), failed, dropped and final txs, name prices, untrusted text, timeouts, unproven names; `test/agent.ts`: the caps, accounts and ledgers per chain and 0.5.1's files, costs, what can be spent, the refusals before signing, nonces under parallel calls and two sessions, your own node's witnesses, a chain without a faucet).
 
 ⚠️ Early and unaudited: test chains only.

package/dist/accounts.d.ts

@@ -0,0 +1,44 @@
+/** A key file as it's stored. Unknown fields are kept as they are. */
+export type WalletFile = {
+    address: string;
+    key_id: string;
+    /** The account `use_account` chose, per chain (`<chain_id> <genesis_hash>`). */
+    accounts?: Record<string, string>;
+    /** 0.5.1's one account for every network: moved into `accounts` by `actingFor`. */
+    account?: string;
+    [field: string]: unknown;
+};
+/** The key file's 32-byte secret (hex). */
+export declare function secretOf(f: WalletFile): string;
+/** A new key file's contents. */
+export declare function newWalletFile(address: string, keyId: string, secretHex: string): WalletFile;
+export declare function readWalletFile(file: string): WalletFile | null;
+/** Writes the whole file (a temporary file beside it, then a rename), readable by this user only. */
+export declare function writeWalletFile(file: string, f: WalletFile): void;
+/**
+ * Writes a new key file, only if there's none yet (a link, which fails if the file exists): two
+ * sessions creating a wallet at once can't replace each other's key. The loser reads the winner's.
+ */
+export declare function createWalletFile(file: string, f: WalletFile): void;
+/** Who the agent acts for on one chain. */
+export interface ActingFor {
+    /** The account chosen with use_account on this chain; undefined: the key's own address. */
+    account?: string;
+    /** A 0.5.1 account that belongs to another chain (another prefix): not used here. */
+    ignored?: string;
+    /** The file changed (a 0.5.1 account moved to this chain): write it back. */
+    changed: boolean;
+}
+/** The account the agent acts for on the chain `chain` (`<chain_id> <genesis_hash>`) whose addresses start with `prefix`1. */
+export declare function actingFor(f: WalletFile, chain: string, prefix: string): ActingFor;
+/** Sets (or, with undefined, clears) the account the agent acts for on `chain`. */
+export declare function setActingFor(f: WalletFile, chain: string, account: string | undefined): void;
+/** What wallet_info says about an ignored 0.5.1 account. */
+export declare function ignoredNote(account: string, prefix: string): string;
+/**
+ * The web wallet's "Give an agent a budget", by chain id (where the user pastes a grant code), for
+ * chains with a public wallet: none since the public testnet was retired.
+ */
+export declare const WALLET_URLS: Record<string, string>;
+/** The short code the web wallet shows for a key (web/lib/format.ts `keyCode`), for the user to compare. */
+export declare const checkCode: (keyId: string) => string;

package/dist/accounts.js

@@ -0,0 +1,118 @@
+// The agent's key file (`agent-wallet.json`) and the account it acts for, per chain (AGENT-2).
+//
+// - The account `use_account` chose is kept per chain (`accounts`, keyed `<chain_id> <genesis_hash>`).
+//   0.5.1 kept one `account` for every network, so a testnet `tboo1…` account followed the agent to
+//   other chains. It moves to the first chain whose prefix it matches; on any other chain it's
+//   ignored (wallet_info says so) and left in place for its own chain.
+// - The file is written whole (a temporary file, then a rename) with mode 600, and keeps every
+//   field it was read with, so rewriting it can't lose the key.
+import { linkSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { isAddress } from "@blockula/sdk";
+/** The key file's secret field (written by 0.5.1 and every release since). */
+const SECRET = "seed";
+/** The key file's 32-byte secret (hex). */
+export function secretOf(f) {
+    const v = f[SECRET];
+    if (typeof v !== "string" || !/^[0-9a-f]{64}$/i.test(v))
+        throw new Error("the agent's key file has no valid key; restore it from a backup, or move it aside and call create_wallet");
+    return v;
+}
+/** A new key file's contents. */
+export function newWalletFile(address, keyId, secretHex) {
+    return { address, key_id: keyId, [SECRET]: secretHex };
+}
+export function readWalletFile(file) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+    let f;
+    try {
+        f = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${file} is unreadable (it holds the agent's key): fix it, or restore it from a backup`);
+    }
+    if (!f || typeof f !== "object" || Array.isArray(f))
+        throw new Error(`${file} is malformed (it holds the agent's key): fix it, or restore it from a backup`);
+    return f;
+}
+/** Writes the whole file (a temporary file beside it, then a rename), readable by this user only. */
+export function writeWalletFile(file, f) {
+    secretOf(f); // never write a file without its key
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(f, null, 2), { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+/**
+ * Writes a new key file, only if there's none yet (a link, which fails if the file exists): two
+ * sessions creating a wallet at once can't replace each other's key. The loser reads the winner's.
+ */
+export function createWalletFile(file, f) {
+    secretOf(f);
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.new`;
+    try {
+        writeFileSync(tmp, JSON.stringify(f, null, 2), { mode: 0o600 });
+        linkSync(tmp, file);
+    }
+    catch (e) {
+        if (e.code !== "EEXIST")
+            throw e;
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+/** The account the agent acts for on the chain `chain` (`<chain_id> <genesis_hash>`) whose addresses start with `prefix`1. */
+export function actingFor(f, chain, prefix) {
+    const chosen = f.accounts?.[chain];
+    if (chosen !== undefined) {
+        const legacy = typeof f.account === "string" && !isAddress(f.account, prefix) ? { ignored: f.account } : {};
+        return isAddress(chosen, prefix) ? { account: chosen, changed: false, ...legacy } : { ignored: chosen, changed: false };
+    }
+    if (typeof f.account !== "string" || f.account === "")
+        return { changed: false };
+    if (!isAddress(f.account, prefix))
+        return { ignored: f.account, changed: false };
+    // 0.5.1's account matches this chain's prefix: it's this chain's from now on.
+    f.accounts = { ...(f.accounts ?? {}), [chain]: f.account };
+    delete f.account;
+    return { account: f.accounts[chain], changed: true };
+}
+/** Sets (or, with undefined, clears) the account the agent acts for on `chain`. */
+export function setActingFor(f, chain, account) {
+    const accounts = { ...(f.accounts ?? {}) };
+    if (account === undefined)
+        delete accounts[chain];
+    else
+        accounts[chain] = account;
+    f.accounts = accounts;
+}
+/** What wallet_info says about an ignored 0.5.1 account. */
+export function ignoredNote(account, prefix) {
+    const other = account.startsWith("tboo1") ? "a testnet's" : account.startsWith("boo1") ? "a boo1… chain's" : "another chain's";
+    return `This agent used to act for ${account}, ${other} account, which isn't an address on this chain (its addresses start with ${prefix}1). Here it acts for its own key until use_account is called with this chain's account.`;
+}
+/**
+ * The web wallet's "Give an agent a budget", by chain id (where the user pastes a grant code), for
+ * chains with a public wallet: none since the public testnet was retired.
+ */
+export const WALLET_URLS = {};
+/** The short code the web wallet shows for a key (web/lib/format.ts `keyCode`), for the user to compare. */
+export const checkCode = (keyId) => {
+    const k = keyId.toUpperCase();
+    return `${k.slice(0, 4)}-${k.slice(4, 8)}-${k.slice(-4)}`;
+};

package/dist/budget.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The default per-call cap; the daily cap is it plus DAILY_FEE_ALLOWANCE (review-fix-clients-3).
+ * The caps guard against mistakes. A compromised agent can read its own key file, so only the
+ * session key's on-chain limit protects the user's FANG from one.
+ */
+export declare const DEFAULT_MAX_SEND = "100";
+/** Fees count toward the daily cap: by default it's the per-call cap plus this, so one full-size call fits. */
+export declare const DAILY_FEE_ALLOWANCE = "1";
+/** The spending caps in force. */
+export interface Caps {
+    maxSend: bigint;
+    maxDaily: bigint;
+    /** How a refusal names them. */
+    sendText: string;
+    dailyText: string;
+}
+/** The caps from the environment. Throws on a bad value. */
+export declare function capsFrom(e: Record<string, string | undefined>): Caps;
+/** A duration in milliseconds from the environment: whole and within a timer's range. */
+export declare function msFrom(e: Record<string, string | undefined>, name: string, fallback: number): number;
+/**
+ * The configuration error in these variables, if any: every cap and duration is parsed once at
+ * startup, inside a try, and the server reports the error through every tool (as it does a bad
+ * network) instead of exiting.
+ */
+export declare function configError(e: Record<string, string | undefined>): Error | null;
+/** An amount the agent passes: FANG with up to 9 decimals; a trailing " FANG" is allowed (AGENT-14). */
+export declare function amountArg(s: string, what?: string): bigint;
+/** About how long `blocks` blocks take at the chain's block time, e.g. "about 23 h". */
+export declare function aboutBlocks(blocks: number, blockTimeMs?: number): string;
+/** A drops amount the node reports (a digit string, or a safe whole number), or undefined. */
+export declare const dropsOf: (v: unknown) => bigint | undefined;
+/** A key on an account, as `/api/account` lists it. */
+export interface KeyEntry {
+    key_id?: unknown;
+    label?: unknown;
+    role?: {
+        type?: unknown;
+        limit?: unknown;
+        period_blocks?: unknown;
+        expires_at?: unknown;
+    };
+    spent_this_period?: unknown;
+    window_start?: unknown;
+}
+/** A session key's allowance as of the block a tx can run in first. */
+export interface Allowance {
+    limit: bigint;
+    /** Spent in the window that block falls in (0 once the window restarts). */
+    spent: bigint;
+    left: bigint;
+    periodBlocks: number;
+    /** When the window restarts, if anything's spent in it. */
+    resetsAt?: number;
+    expiresAt: number;
+    expired: boolean;
+}
+/** The node's session-key rule (node/src/chain.rs `admit`): spent + amount + charge ≤ limit, the window restarting `period_blocks` after it began. */
+export declare function allowanceOf(key: KeyEntry | undefined, height: number): Allowance | null;
+/** The key with this id on an account (`/api/account`'s `keys`), or undefined when it isn't there; null when the node doesn't list keys. */
+export declare function keyOn(account: {
+    keys?: unknown;
+} | null | undefined, keyId: string): KeyEntry | undefined | null;
+/** Everything the checks before signing need: reads the MCP makes anyway, and the tx's cost. */
+export interface Preflight {
+    /** `/api/account` for the account the tx acts for (null: the node didn't answer). */
+    account: any;
+    keyId: string;
+    actingFor: string;
+    action: string;
+    /**
+     * FANG the action takes out of what the account can move: sent, a name's price, escrowed, a
+     * bond. Not a stake (locked FANG can be staked) or a vote (it locks, it doesn't spend).
+     */
+    outflow: bigint;
+    /** What opening the recipient's account burns on top. */
+    opening: bigint;
+    /** The tx's fee (what it can be charged at most). */
+    fee: bigint;
+    /** The first block the tx can run in (the node's height + 1). */
+    height: number;
+    blockTimeMs?: number;
+}
+/**
+ * Throws when the chain would refuse the tx for something the node's reads already show (AGENT-6).
+ * A field the node doesn't report isn't checked: the chain still is.
+ */
+export declare function preflight(p: Preflight): void;
+/**
+ * What can be spent now, before fees, and what limits it: the account's transferable FANG, the
+ * session key's allowance left this window, the MCP's daily cap left and its per-call cap.
+ */
+export declare function spendableNow(o: {
+    transferable?: bigint;
+    allowance?: Allowance | null;
+    height: number;
+    blockTimeMs?: number;
+    dailyLeft: bigint;
+    caps: Caps;
+}): {
+    amount: bigint;
+    limitedBy: string;
+    limits: string[];
+};

package/dist/budget.js

@@ -0,0 +1,169 @@
+// What the agent may spend, and the checks made before anything is signed.
+//
+// - Caps (AGENT-19, AGENT-15): BLOCKULA_MAX_SEND per call and BLOCKULA_MAX_DAILY per UTC day.
+//   Unset, they're 100 and 101 FANG. A bad value is a configuration error every tool reports,
+//   never a crash at startup.
+// - Refusals before signing (AGENT-6): a session key signing what it can't, or more than its
+//   allowance left; a payment past what the account can move; a key that isn't on the account.
+//   They read what the node reports (the account, its keys, the fee), so a lying node can only
+//   cause a refusal here, never a spend: whatever passes is still checked by the chain, and still
+//   reserved against the caps (spend.ts).
+// - What can be spent now (AGENT-7): the smallest of what the account can move, the session key's
+//   allowance left this window, and the MCP's caps, with the one that binds.
+import { checkTimeoutMs, formatFang, parseFang } from "@blockula/sdk";
+/**
+ * The default per-call cap; the daily cap is it plus DAILY_FEE_ALLOWANCE (review-fix-clients-3).
+ * The caps guard against mistakes. A compromised agent can read its own key file, so only the
+ * session key's on-chain limit protects the user's FANG from one.
+ */
+export const DEFAULT_MAX_SEND = "100";
+/** Fees count toward the daily cap: by default it's the per-call cap plus this, so one full-size call fits. */
+export const DAILY_FEE_ALLOWANCE = "1";
+const env = (e, name) => {
+    const v = e[name]?.trim();
+    return v === undefined || v === "" ? undefined : v;
+};
+const fangEnv = (name, v) => {
+    try {
+        return parseFang(v);
+    }
+    catch {
+        throw new Error(`${name} must be an amount of FANG with up to 9 decimals, like "10" (got "${v.slice(0, 40)}")`);
+    }
+};
+/** The caps from the environment. Throws on a bad value. */
+export function capsFrom(e) {
+    const send = env(e, "BLOCKULA_MAX_SEND");
+    const daily = env(e, "BLOCKULA_MAX_DAILY");
+    const maxSend = fangEnv("BLOCKULA_MAX_SEND", send ?? DEFAULT_MAX_SEND);
+    const maxDaily = daily !== undefined ? fangEnv("BLOCKULA_MAX_DAILY", daily) : maxSend + parseFang(DAILY_FEE_ALLOWANCE);
+    const sendText = send !== undefined ? `BLOCKULA_MAX_SEND=${send} FANG` : `BLOCKULA_MAX_SEND, by default ${formatFang(maxSend)}`;
+    const dailyText = daily !== undefined ? `BLOCKULA_MAX_DAILY=${daily} FANG` : `BLOCKULA_MAX_DAILY, by default BLOCKULA_MAX_SEND + ${DAILY_FEE_ALLOWANCE} FANG for fees = ${formatFang(maxDaily)}`;
+    return { maxSend, maxDaily, sendText, dailyText };
+}
+/** A duration in milliseconds from the environment: whole and within a timer's range. */
+export function msFrom(e, name, fallback) {
+    const v = env(e, name);
+    if (v === undefined)
+        return fallback;
+    if (!/^\d+$/.test(v))
+        throw new Error(`${name} must be a positive number of milliseconds`);
+    return checkTimeoutMs(Number(v), name);
+}
+/**
+ * The configuration error in these variables, if any: every cap and duration is parsed once at
+ * startup, inside a try, and the server reports the error through every tool (as it does a bad
+ * network) instead of exiting.
+ */
+export function configError(e) {
+    try {
+        capsFrom(e);
+        msFrom(e, "BLOCKULA_TIMEOUT_MS", 15_000);
+        msFrom(e, "BLOCKULA_TX_WAIT_MS", 15_000);
+        return null;
+    }
+    catch (err) {
+        return err;
+    }
+}
+/** An amount the agent passes: FANG with up to 9 decimals; a trailing " FANG" is allowed (AGENT-14). */
+export function amountArg(s, what = "amount") {
+    const v = s.trim().replace(/\s*FANG$/i, "");
+    try {
+        return parseFang(v);
+    }
+    catch {
+        throw new Error(`${what} must be a number in FANG with up to 9 decimals, like "1.5" (got "${s.slice(0, 40)}")`);
+    }
+}
+/** About how long `blocks` blocks take at the chain's block time, e.g. "about 23 h". */
+export function aboutBlocks(blocks, blockTimeMs = 1000) {
+    const s = Math.max(0, blocks) * (blockTimeMs / 1000);
+    if (s < 90)
+        return `about ${Math.round(s)} s`;
+    if (s < 5400)
+        return `about ${Math.round(s / 60)} min`;
+    if (s < 172_800)
+        return `about ${Math.round(s / 3600)} h`;
+    return `about ${Math.round(s / 86_400)} days`;
+}
+/** A drops amount the node reports (a digit string, or a safe whole number), or undefined. */
+export const dropsOf = (v) => (typeof v === "string" && /^\d+$/.test(v) ? BigInt(v) : typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? BigInt(v) : undefined);
+const digits = dropsOf;
+const whole = (v) => (Number.isSafeInteger(v) && v >= 0 ? v : undefined);
+/** The node's session-key rule (node/src/chain.rs `admit`): spent + amount + charge ≤ limit, the window restarting `period_blocks` after it began. */
+export function allowanceOf(key, height) {
+    if (key?.role?.type !== "session")
+        return null;
+    const limit = digits(key.role.limit);
+    const periodBlocks = whole(key.role.period_blocks);
+    const expiresAt = whole(key.role.expires_at);
+    if (limit === undefined || periodBlocks === undefined || expiresAt === undefined)
+        return null;
+    const windowStart = whole(key.window_start) ?? 0;
+    const restarts = height >= windowStart + periodBlocks;
+    const spent = restarts ? 0n : (digits(key.spent_this_period) ?? 0n);
+    return { limit, spent, left: limit > spent ? limit - spent : 0n, periodBlocks, ...(spent > 0n ? { resetsAt: windowStart + periodBlocks } : {}), expiresAt, expired: height > expiresAt };
+}
+/** The key with this id on an account (`/api/account`'s `keys`), or undefined when it isn't there; null when the node doesn't list keys. */
+export function keyOn(account, keyId) {
+    if (!account || !Array.isArray(account.keys))
+        return null;
+    return account.keys.find((k) => k?.key_id === keyId);
+}
+const REFUSED = "Refused before signing: nothing was signed or sent, and nothing counts toward today's limit.";
+/**
+ * Throws when the chain would refuse the tx for something the node's reads already show (AGENT-6).
+ * A field the node doesn't report isn't checked: the chain still is.
+ */
+export function preflight(p) {
+    const short = (a) => (a.length > 20 ? `${a.slice(0, 12)}…${a.slice(-6)}` : a);
+    const key = keyOn(p.account, p.keyId);
+    if (key === undefined) {
+        throw new Error(`${REFUSED} This agent's key (${checkCodeOf(p.keyId)}) isn't on ${p.actingFor}: it was removed, or never added. Call use_account with the account to get a new grant code for the user, or use_account "self" to act for the key's own address.`);
+    }
+    const allowance = allowanceOf(key ?? undefined, p.height);
+    if (key && allowance) {
+        if (allowance.expired)
+            throw new Error(`${REFUSED} This agent's session key on ${short(p.actingFor)} expired at block ${allowance.expiresAt}. Ask the user for a new budget: call use_account with the account for a new grant code.`);
+        const familiar = Array.isArray(p.account?.familiars) && p.account.familiars.some((f) => f?.key_id === p.keyId);
+        const allowed = p.action === "transfer" || (p.action === "submit_claim" && familiar);
+        if (!allowed) {
+            const what = p.action === "submit_claim"
+                ? "Only a session key the user registered as a Familiar can claim contributions: ask them to register it in their wallet (Programs → Accounts → Register a Familiar)."
+                : p.action === "link_github"
+                    ? "Linking GitHub needs an owner key: ask the user to link GitHub in their wallet."
+                    : "Ask the user to do it in their wallet, with an owner key.";
+            throw new Error(`${REFUSED} This agent acts for ${short(p.actingFor)} through a session key, and session keys can only send transfers (and claims, for registered Familiars). ${what}`);
+        }
+        // A transfer counts what it sends and what opening the recipient burns; a claim its bond; both the fee.
+        const need = p.outflow + p.opening + p.fee;
+        if (need > allowance.left) {
+            const resets = allowance.resetsAt !== undefined ? ` It resets at block ${allowance.resetsAt} (${aboutBlocks(allowance.resetsAt - p.height, p.blockTimeMs)}).` : "";
+            throw new Error(`${REFUSED} This needs ${formatFang(need)} with the fee${p.opening > 0n ? ` and the account-opening burn (${formatFang(p.opening)})` : ""}, but the session key has ${formatFang(allowance.left)} of its ${formatFang(allowance.limit)} allowance left this window.${resets} Send less, or ask the user to raise the limit.`);
+        }
+    }
+    const transferable = digits(p.account?.transferable);
+    if (p.outflow > 0n && transferable !== undefined && p.outflow + p.opening + p.fee > transferable) {
+        const locked = digits(p.account?.locked) ?? 0n;
+        throw new Error(`${REFUSED} This needs ${formatFang(p.outflow + p.opening + p.fee)} with the fee${p.opening > 0n ? ` and the account-opening burn (${formatFang(p.opening)})` : ""}, but ${short(p.actingFor)} can move ${formatFang(transferable)} now${locked > 0n ? ` (${formatFang(locked)} more is locked: wallet_info shows until when)` : ""}.`);
+    }
+}
+const checkCodeOf = (keyId) => (typeof keyId === "string" && keyId.length >= 12 ? `${keyId.slice(0, 4).toUpperCase()}-${keyId.slice(4, 8).toUpperCase()}-${keyId.slice(-4).toUpperCase()}` : keyId);
+/**
+ * What can be spent now, before fees, and what limits it: the account's transferable FANG, the
+ * session key's allowance left this window, the MCP's daily cap left and its per-call cap.
+ */
+export function spendableNow(o) {
+    const limits = [];
+    if (o.transferable !== undefined)
+        limits.push({ amount: o.transferable, why: `the account can move ${formatFang(o.transferable)} now` });
+    if (o.allowance) {
+        const resets = o.allowance.resetsAt !== undefined ? ` until block ${o.allowance.resetsAt} (${aboutBlocks(o.allowance.resetsAt - o.height, o.blockTimeMs)})` : "";
+        limits.push({ amount: o.allowance.expired ? 0n : o.allowance.left, why: o.allowance.expired ? `the session key expired at block ${o.allowance.expiresAt}` : `the session key has ${formatFang(o.allowance.left)} of ${formatFang(o.allowance.limit)} left${resets}` });
+    }
+    limits.push({ amount: o.dailyLeft, why: `this MCP's daily cap has ${formatFang(o.dailyLeft)} of ${formatFang(o.caps.maxDaily)} left today (UTC)` });
+    limits.push({ amount: o.caps.maxSend, why: `this MCP's per-call cap is ${formatFang(o.caps.maxSend)}` });
+    const binding = limits.reduce((a, b) => (b.amount < a.amount ? b : a));
+    return { amount: binding.amount, limitedBy: binding.why, limits: limits.map((l) => l.why) };
+}