web3-tools-mcp 2.0.2 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,187 @@
 
 Notable changes per release. Dates are release dates; unreleased work sits at the top.
 
+## [3.1.0] — 2026-10-01
+
+Mostly fixes, several of them for security — worth taking on any hosted server.
+
+From this release `web3-wallet-relay` shares the server's version number, jumping from 2.0.0
+to 3.1.0. The two speak one protocol that carries no version of its own, so the package
+version is what matches them: a relay hosted on its own runs at the version of the server
+pointing at it. `web3-tools-mcp` still pins it exactly.
+
+### Added
+
+- A host's `Login` can name the `credential` it checks, binding every code and token issued
+  under it so that rotating the secret revokes them, and its `page()` is told which client
+  is asking and where the code will go.
+
+### Changed
+
+- `trace_transaction`'s `traceType` is `trace`, `prestate` or `stateDiff`. `vmTrace` is gone:
+  it ran the prestate tracer under another name, and `stateDiff` asked for a tracer no node
+  has. Traces too large for an agent's context are cut short and say so.
+- `get_logs` returns at most 1,000 logs, with `truncated` and the `nextBlock` to continue
+  from. `toBlock` is inclusive on both paths, a list in `eventArgs` is an OR filter, and an
+  invalid `address` is an error rather than a filter silently dropped.
+- `get_balance`, `read_contract` and `batch_resolve_ens_names` take at most 25 items.
+- ENS tools take `mainnet`, `linea` or `base` — the chains that have a resolver — and the
+  no-op `universalResolver` parameter is gone.
+- `render.yaml` is a single service: the relay runs inside the MCP server, as on Fly.
+- Keeping OAuth state in Upstash needs per-field hash expiry (`HEXPIRE`, Redis ≥ 7.4), so
+  expired tokens no longer pile up. The file store prunes them on write.
+
+### Fixed
+
+- `send_erc20_token` no longer assumes 18 decimals. It reads them on-chain and refuses a
+  `decimals` that disagrees; a token whose decimals cannot be read needs them passed.
+- `write_contract` takes numeric arguments only as safe integers — pass a large uint or int
+  as a string — and coerces string arguments to their ABI types, as `read_contract` does.
+- `sign_message` sends the browser the message hex-encoded, as the phone gets it, so both
+  sign the same bytes. The phone signs on a chain its session approved, not mainnet.
+- Phone signing on `localhost` is refused up front: the phone has no route to that node. Use
+  the browser.
+- The signing preview names each labelled address as `Name (0x…)`, shows token amounts with
+  the token's address, and gives an amount whose decimals are unknown as the raw integer,
+  marked so, rather than assuming 18. Its summary includes `to`.
+- `get_logs` over Hypersync no longer drops the last block, reports a response cut short
+  by the server, or scans from genesis when `fromBlock` is omitted.
+- `get_error_signature` hashes tuple parameters correctly.
+- `get_gas_price` shows sub-gwei L2 prices instead of "0.00", and costs in the chain's own
+  native token.
+- An invalid, expired or replayed OAuth code or refresh token answers `invalid_grant`, not a
+  500, so connectors re-authorise instead of retrying.
+- Etherscan errors say why ("Invalid API Key", rate limit) rather than "NOTOK".
+- `npx web3-wallet-relay` starts the relay.
+
+### Security
+
+- The provider API key no longer appears in tool output.
+- `get_ens_avatar` returns the raw avatar record rather than fetching it server-side.
+- Requests carry `expiresAt`, and the signing page cancels an approval that arrives after
+  the request timed out or was disconnected. A request that failed any way but an explicit
+  rejection now reports `outcome_unknown` — it may still have been broadcast — instead of
+  `rejected_or_failed`, so an agent checks before retrying rather than paying twice.
+- The signing page is hardened against script injection and framing, with a strict CSP.
+- OAuth refresh tokens expire, and rotating `MCP_TOKEN` revokes every token issued under
+  it — existing tokens predate the binding, so single-token deployments re-authorise once.
+  The login page names the client and where it redirects, and cannot be framed.
+  `MCP_TRUST_PROXY` lets rate limiting see client addresses behind a proxy.
+- The hosted signer link is no longer written to the logs.
+
+## [3.0.0] — 2026-09-26
+
+The theme is multi-tenancy: one server can now carry several people without their wallets
+meeting. Nothing turns that on by itself — a server still authenticates its deployment
+rather than a person, so everyone on it remains the same user until something issues
+distinct identities.
+
+`web3-wallet-relay` goes to 2.0.0 alongside, and `web3-tools-mcp` pins it exactly: the
+handshake changed, so a mismatched pair cannot pair at all.
+
+### Changed
+
+- **Tracing uses a node that is already running, instead of starting one.** Each trace used
+  to spawn an Anvil fork and kill it afterwards, which on a shared server is unbounded child
+  processes. It now talks to `ANVIL_RPC_URL`, defaulting to `127.0.0.1:8545` — any node
+  exposing `debug_traceCall` will do, and a provider whose RPC can trace is still preferred.
+
+  Anvil serves no block below its own fork height, so replaying an older transaction means
+  re-forking the node there, which clears whatever state it held. That only happens with
+  `ANVIL_ALLOW_RESET=1`; without it the trace fails and says so. The node is returned to
+  head afterwards rather than left pinned to an old block.
+
+  Re-forking reads state from the chain's configured RPC, so tracing an old transaction
+  needs one with archive access — a provider key or a `CUSTOM_RPC`. The hard-coded archive
+  endpoint for Arbitrum is gone.
+
+### Added
+
+- **Several phone wallets can be paired at once** — a hot wallet and a hardware one, say.
+  `pair_phone_wallet` used to report that one was already paired and stop; it now pairs, and
+  says which wallets the new one joins. `wallet_status` lists them all, and the signing
+  tools take `account` to choose between them, as does `disconnect_phone_wallet` — which
+  still clears everything when no account is named. With one wallet paired nothing changes,
+  and omitting `account` uses the most recently paired.
+- **`simulate_bundle`** runs several transactions in order in one block, each on the state
+  the last left — approve then swap, deposit then borrow. Offered with an Alchemy key.
+- **Signing requests outlive their call.** One not approved in time comes back with a
+  `requestId`, and `check_signing_request` collects it instead of a second prompt landing in
+  the wallet. A phone request returns as soon as the wallet has it, and both signers wait
+  for the receipt, reporting mined, reverted or still pending. The signing page shows every
+  request waiting, approvable in any order.
+- A host assembling its own server can mount routes, hand a pairing made under a
+  placeholder to the address it proved, and draw the pairing QR as SVG (`qrSvg`).
+- The server declares an icon, so a connector list shows more than a letter.
+- `pair_phone_wallet` warns when the same wallet app is already paired, and reports a
+  pairing the wallet ended itself.
+
+### Fixed
+
+- An ERC-721 `Transfer` reads as a token id, not as an ERC-20 transfer of nothing.
+
+### Security
+
+- **Signing is scoped to whoever asked for it.** Every tool call now carries the identity it
+  is acting for, and both signers are keyed by it: a wallet page reaches only the person it
+  belongs to, and a phone session is matched by a binding recorded when it was approved.
+  Sessions were previously picked as "the most recently paired", so on a server with more
+  than one user a signing request could be sent to somebody else's phone — and
+  `disconnect_phone_wallet` ended everybody's sessions. Phones paired before this keep
+  working on a single-user server.
+
+- **Relay tokens name the room they admit you to**, signed by the relay's secret, so the
+  server can mint a pair per person and the relay needs no record of who exists. Naming a
+  room without the signature is refused.
+
+- **The relay bounds what one room can take.** A frame over 512KB is refused, rather than
+  the 100MB the WebSocket library would otherwise accept, and a room holds at most 16
+  connections. Neither is reachable in normal use — contract creation calldata tops out
+  near 98KB of hex, and a person needs a wallet tab or two plus a requester per editor
+  session — but without them one connection could exhaust the process for everybody else.
+
+- **`localhost` is not a chain a hosted server will accept.** It resolves to the machine
+  running the server, so on a shared deployment it was a way to aim requests at whatever
+  that host had listening on its own loopback. Self-hosted runs are unaffected.
+
+  The same switch keeps a hosted server from probing its own loopback for a tracing node
+  and from opening a browser on itself. The CLI flips it with `MCP_HTTP_PORT`; a host that
+  assembles its own server from the library sets `MCP_HOSTED=1` before importing it, and
+  `startHttpServer` refuses to run without one of the two.
+
+- **The relay drops a frame it cannot use instead of dying on it.** A peer that had
+  authenticated could send `null` — valid JSON, not an object — and take the relay down,
+  along with the MCP server it is embedded in when hosted. Tokens are also compared in
+  constant time.
+
+- **A request signs from the account it named.** With a session exposing several
+  addresses, `account` chose the session but the transaction was still sent from its first
+  address. Concurrent pairings on one server no longer overwrite each other's ownership
+  record, and a hosted server closes a person's idle relay socket after ten minutes
+  instead of holding one open per person forever.
+
+- **The signing page and the MCP server now hold different tokens.** One token granted both
+  roles, and a relay client may either answer transaction proposals (the page) or make them
+  (the server). The page's token is the exposed one — it rides in a URL you open, keep in
+  history and show on screen — so anyone who saw it could push proposals at your wallet.
+  The page's token is derived from the server's and grants the signing role only; the
+  server's never reaches a browser.
+
+  **Re-open the signing page from the link the server prints.** Pairing URLs issued before
+  this carry a token the relay no longer accepts for signing.
+
+- **The signing page no longer takes the transaction's value from the preview.** The preview
+  travels with the request and is forwarded untouched, so a hostile requester could state
+  one amount while the calldata did another. The value is now read from the transaction
+  itself, and the calldata is shown even when a decoded view is available, so a claim that
+  disagrees with the bytes is visible on the same screen.
+
+- **A relay can serve several people without their wallets meeting.** Connections resolve to
+  a room, and a transaction only ever reaches a page in the same one. Previously the relay
+  offered each transaction to whichever page was first in its pool, broadcast the first
+  signer's address to every requester, and let any page answer a request by its id. A
+  self-hosted relay keeps one room and behaves exactly as before.
+
 ## [2.0.2] — 2026-09-22
 
 ### Fixed
@@ -80,7 +261,7 @@ sign it.
   `call_contract_write` is now `write_contract` — the old pair gave no hint which one
   spent gas. The names now match viem's, and a saved prompt naming the old ones will need
   updating.
-- Every supported chain now lives in one table ([mcp/src/chains.ts](mcp/src/chains.ts)). Adding a
+- Every supported chain now lives in one table ([mcp/src/chains.ts](https://github.com/hajnalben/web3-tools-mcp/blob/main/mcp/src/chains.ts)). Adding a
   chain is a single entry; the tool schemas, RPC selection, explorer links, Hypersync
   routing and `--help` all derive from it.
 - Tool errors surface the underlying failure rather than a re-wrapped message that hid it.

package/README.md

@@ -4,13 +4,13 @@
 
 **Your agent proposes the transaction. You approve it — in your own wallet, on your phone.** 📱
 
-30 MCP tools for reading any EVM network and signing transactions in *your own* wallet.
+32 MCP tools for reading any EVM network and signing transactions in *your own* wallet.
 Every transaction is decoded, named and simulated before you approve it.
 
 [![npm](https://img.shields.io/npm/v/web3-tools-mcp?color=%233856d6&label=npm)](https://www.npmjs.com/package/web3-tools-mcp)
 [![downloads](https://img.shields.io/npm/dm/web3-tools-mcp?color=%233856d6)](https://www.npmjs.com/package/web3-tools-mcp)
 [![node](https://img.shields.io/node/v/web3-tools-mcp?color=%233856d6)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/web3-tools-mcp?color=%233856d6)](LICENSE)
+[![license](https://img.shields.io/npm/l/web3-tools-mcp?color=%233856d6)](https://github.com/hajnalben/web3-tools-mcp/blob/main/LICENSE)
 
 </div>
 
@@ -22,7 +22,7 @@ One entry in that client's MCP config:
 ```
 
 Each app keeps that config somewhere different —
-[the file paths are below ↓](#-setup). You need Node.js ≥ 20; `npx` fetches the rest.
+[the file paths are below ↓](#-setup). You need Node.js ≥ 20.19; `npx` fetches the rest.
 
 **ChatGPT, Grok** and **claude.ai** cannot launch anything locally — they only reach a URL.
 [Host it once ↓](#-hosting) and add it as a connector, and there is nothing running on your
@@ -91,7 +91,7 @@ npx web3-tools-mcp --walletconnect-project-id YOUR_PROJECT_ID
 | 💾 | **It sticks.** The session is stored on disk (or in Redis when hosted), so it survives restarts and redeploys. Pair once, not once a day |
 | ✍️ | **You choose each time.** Every signing tool takes a required `signWith`, so the agent asks whether this one goes to your phone or the browser. A paired phone never quietly claims a request |
 | 🧾 | **You still see the decode.** The full preview comes back in the tool response — your wallet shows its own summary, so read ours before you approve theirs |
-| 🔌 | **Drop it any time.** `disconnect_phone_wallet` clears every session and pairing |
+| 🔌 | **Drop it any time.** `disconnect_phone_wallet` drops the wallet you name by `account`, or every session and pairing when you name none |
 
 Works with **MetaMask · Rabby · Trust · Coinbase Wallet** — anything speaking WalletConnect v2.
 
@@ -123,28 +123,36 @@ returns the page URL any time you want to open it yourself.
 ## 🧰 Tools
 
 <details>
-<summary><b>30 tools</b> — reads, writes, ENS, logs, tracing</summary>
+<summary><b>32 tools</b> — reads, writes, ENS, logs, tracing</summary>
 
 ### ✍️ Transactions & signing
 | Tool | |
 | --- | --- |
-| `write_contract` | Send a transaction calling a state-changing function, via your wallet |
+| `write_contract` | Send a transaction calling a state-changing function, via your wallet. Pass large integers as strings |
 | `send_native_token` | Send ETH or a native token |
-| `send_erc20_token` | Send an ERC-20 |
-| `sign_message` | Sign a message |
-| `wallet_status` | Which signer is connected — phone or browser |
+| `send_erc20_token` | Send an ERC-20, with decimals read on-chain — a `decimals` you pass must agree |
+| `sign_message` | Sign a message — the same bytes on either signer |
+| `check_signing_request` | Collect a request still awaiting approval, by its `requestId` |
+| `wallet_status` | Every signer and whether it is ready — phone wallets and the browser page |
 | `pair_phone_wallet` | Pair a phone over WalletConnect, returns a QR |
-| `disconnect_phone_wallet` | Drop every WalletConnect session and pairing |
+| `disconnect_phone_wallet` | Drop one paired wallet by `account`, or every session and pairing |
 
 The four signing tools take a required `signWith` of `phone` or `browser`. There is no
 default on purpose — the agent has to ask you, so a request never lands on a device you are
-not holding.
+not holding. On `localhost` only the browser can sign; a phone has no route to your node.
+With several phones paired, the optional `account` picks one by address;
+omitted, the most recently paired is used.
+
+A request not approved within the call comes back with a `requestId` instead of hanging,
+and `check_signing_request` collects it — asking again would put a second prompt in front
+of your wallet.
 
 ### 📜 Contracts
 | Tool | |
 | --- | --- |
-| `read_contract` | Read state via view/pure functions — batched, no wallet, no gas |
+| `read_contract` | Read state via view/pure functions — batched (up to 25 calls), no wallet, no gas |
 | `simulate_contract` | Simulate without broadcasting, with gas |
+| `simulate_bundle` | Simulate several transactions in order, each on the state the last left — approve → swap. Needs `ALCHEMY_API_KEY` |
 | `get_contract_abi` | ABI, with proxy detection and verification status |
 | `get_contract_source_code` | Verified source, proxies included |
 | `get_contract_source_file` | One file out of the cached source |
@@ -157,14 +165,20 @@ not holding.
 ### ⛓️ Chain data
 | Tool | |
 | --- | --- |
-| `get_balance` | Native or ERC-20 balances — batched |
-| `get_logs` | Query and decode events, with Hypersync fallback |
+| `get_balance` | Native or ERC-20 balances — batched, up to 25 queries |
+| `get_logs` | Query and decode events; Hypersync when the RPC refuses the range. At most 1,000 logs — past that it returns `truncated` and the `nextBlock` to continue from. A list in `eventArgs` matches any of its values |
 | `get_block_info` | Block data |
 | `get_storage_at` | Storage slots, with type decoding |
 | `get_gas_price` | Current gas — legacy and EIP-1559 |
 | `estimate_gas` | Gas for any transaction |
-| `trace_transaction` | Call tree, VM trace, state diff |
-| `debug_call` | Trace a call without broadcasting, falling back to a local anvil fork |
+| `trace_transaction` | Call tree, prestate or state diff |
+| `debug_call` | Trace a call without broadcasting, through a node at `ANVIL_RPC_URL` |
+
+Tracing prefers an RPC that exposes `debug_*`, and otherwise uses a node you already run at
+`ANVIL_RPC_URL` (default `127.0.0.1:8545`, e.g. `anvil --fork-url …`) — nothing is started
+for you. Replaying a transaction older than the fork re-forks that node, clearing its state,
+so it happens only with `ANVIL_ALLOW_RESET=1`. A hosted server has no default and traces only
+through an explicit `ANVIL_RPC_URL`.
 
 ### 🏷️ ENS
 | Tool | |
@@ -172,8 +186,10 @@ not holding.
 | `resolve_ens_name` | Name → address |
 | `reverse_resolve_ens` | Address → name |
 | `get_ens_text_record` | Text records |
-| `get_ens_avatar` | Avatar URI |
-| `batch_resolve_ens_names` | Many names at once |
+| `get_ens_avatar` | The raw avatar record — URL, data URI or NFT reference, not fetched |
+| `batch_resolve_ens_names` | Up to 25 names at once |
+
+ENS tools take `mainnet` (ENS), `linea` (Linea Names) or `base` (Basenames).
 
 </details>
 
@@ -196,7 +212,7 @@ not holding.
 | Unichain | 130 | ✅ |
 | Localhost | 1337 | ❌ |
 
-Adding one is a single entry in [`mcp/src/chains.ts`](mcp/src/chains.ts).
+Adding one is a single entry in [`mcp/src/chains.ts`](https://github.com/hajnalben/web3-tools-mcp/blob/main/mcp/src/chains.ts).
 
 </details>
 
@@ -291,7 +307,7 @@ What you lose is reach, not stability — so here is the honest version:
 | `WALLETCONNECT_PROJECT_ID` | [walletconnect](https://dashboard.walletconnect.com) | 📱 **No phone signing at all.** Browser wallet only, so a hosted instance has no way to sign |
 | `ALCHEMY_API_KEY`<br>or `INFURA_API_KEY`<br>or `CUSTOM_RPC` | [alchemy](https://alchemy.com) · [infura](https://infura.io) | **No historical state.** Public endpoints answer `403 Archive requests require a personal token`, which takes out balances, storage and calls at a past block, event ranges, and `trace_transaction` |
 | `ETHERSCAN_API_KEY` | [etherscan](https://etherscan.io/apis) | `get_contract_abi`, `get_contract_source_code` and `get_contract_source_file` refuse. Signing previews still decode — they try Sourcify first, then recover the ABI from bytecode |
-| `HYPERSYNC_API_KEY` | [envio](https://envio.dev) | Event queries fall back to plain RPC — slower, and past ranges then need one of the provider keys above |
+| `HYPERSYNC_API_KEY` | [envio](https://envio.dev) | `get_logs` asks the RPC first and falls back to Hypersync when the RPC refuses the range. Without a token that fallback is gone, so wide or past ranges depend on your provider's limits |
 
 So with nothing configured you get current balances, contract reads, gas, ENS, simulation
 and browser signing. Add `WALLETCONNECT_PROJECT_ID` for your phone and one provider key for
@@ -299,7 +315,7 @@ history, and everything above lights up.
 
 Every key has a matching flag (`--etherscan-api-key`, …), RPC selection falls back
 Alchemy → Infura → public, and `CUSTOM_RPC` overrides all of it.
-`npx web3-tools-mcp --help` lists them; [.env.example](.env.example) documents each one.
+`npx web3-tools-mcp --help` lists them; [.env.example](https://github.com/hajnalben/web3-tools-mcp/blob/main/.env.example) documents each one.
 
 ```bash
 npx web3-tools-mcp --etherscan-api-key KEY --walletconnect-project-id ID
@@ -319,26 +335,34 @@ transaction at your phone.
 <a href="https://fly.io/docs/launch/"><img src="https://img.shields.io/badge/Deploy%20on-Fly.io-8b5cf6?style=for-the-badge&logo=flydotio&logoColor=white" alt="Deploy on Fly.io" height="32"></a>
 
 **Render** reads `render.yaml`, generates `MCP_TOKEN` and asks for `WALLETCONNECT_PROJECT_ID`
-— genuinely one click.
+— one click, on a paid `starter` instance with a 1 GB disk so it stays awake and keeps the
+pairing. `MCP_PUBLIC_URL` defaults to the service's `onrender.com` address; set it only for a
+custom domain.
 
 **Fly** ships no deploy button, so it is four commands. Worth it for a personal instance:
 volumes come with any plan, so the pairing survives redeploys without paying for a disk.
 
 ```bash
-fly launch --no-deploy --copy-config
+fly launch --no-deploy --copy-config   # then set MCP_PUBLIC_URL in fly.toml to https://<app>.fly.dev
 fly volumes create data --size 1
 fly secrets set MCP_TOKEN=$(openssl rand -hex 24) WALLETCONNECT_PROJECT_ID=<id>
 fly deploy
 ```
 
+Without the right `MCP_PUBLIC_URL` the OAuth metadata and the wallet links point somewhere
+clients cannot reach. Both `fly.toml` and `render.yaml` set `MCP_TRUST_PROXY=1`, so rate
+limiting sees client addresses rather than the platform's proxy.
+
 <details>
 <summary>🐳 <b>Docker, and connecting a client</b></summary>
 
 There is a plain `Dockerfile` too, so Railway, Cloud Run or your own box work the same way:
 
 ```bash
+docker build -t web3-tools-mcp .
 docker run -p 8080:8080 \
   -e MCP_TOKEN=<long random string> \
+  -e MCP_PUBLIC_URL=https://your-host \
   -e WALLETCONNECT_PROJECT_ID=<id> \
   web3-tools-mcp
 ```
@@ -352,49 +376,54 @@ claude mcp add --transport http web3-tools https://your-host/mcp \
 
 Clients that cannot send a header — claude.ai connectors, and the browser and phone apps —
 use OAuth, which the server implements against the same credential: it shows a page asking
-for `MCP_TOKEN` and issues a token once you paste it. No identity provider, no accounts. Set
-`MCP_PUBLIC_URL` to the address clients reach you on, since OAuth metadata must advertise it.
+for `MCP_TOKEN` and issues a token once you paste it. No identity provider, no accounts.
 
 > 🔐 **`MCP_TOKEN` is mandatory** and the server refuses to start without it. Anyone who
 > reaches `/mcp` while your phone is paired can push signing prompts at it. You would still
 > approve each one, but that is a phishing surface, not a feature.
 
+| Variable | |
+| --- | --- |
+| `MCP_HTTP_PORT` | Serve over HTTP on this port instead of stdio. Also switches on the hosted guards: no `localhost` chain, no loopback tracing node |
+| `MCP_HTTP_HOST` | Bind address, default `0.0.0.0` |
+| `MCP_TOKEN` | The one credential, as a bearer header or through OAuth. Changing it revokes every OAuth token issued against the old one |
+| `MCP_PUBLIC_URL` | The address clients reach you on — advertised in OAuth metadata and used for wallet links |
+| `MCP_TRUST_PROXY` | Reverse-proxy hops to trust for client IPs in rate limiting. `1` behind Fly or Render; off by default |
+| `MCP_HOSTED` | The hosted guards without `MCP_HTTP_PORT`, for a host assembling its own server from the library |
+| `XDG_CONFIG_HOME` | Where pairings, OAuth tokens and the relay token are stored, under `web3-tools-mcp/` |
+| `UPSTASH_REDIS_REST_URL`<br>`UPSTASH_REDIS_REST_TOKEN` | Keep sessions and tokens in Redis instead. Needs per-field hash expiry (`HEXPIRE`: Upstash, or Redis ≥ 7.4) |
+| `WALLET_TOKEN` | Relay secret. Unset, a hosted server mints one per boot |
+| `WALLET_SERVER_URL` | A separately hosted relay, below |
+| `ANVIL_RPC_URL`<br>`ANVIL_ALLOW_RESET` | Tracing node, and whether it may be re-forked — see Tools |
+
 Two things decide whether the pairing survives:
 
 - ⏰ **Keep the instance awake.** Sleeping drops the WalletConnect socket, so the first
   transaction after an idle period waits for the host to wake — about a minute on a free tier.
 - 💾 **Give the session somewhere durable.** Most hosts have an ephemeral filesystem, so a
   plain file is lost on redeploy and you rescan the QR. Attach a volume and point
-  `XDG_CONFIG_HOME` at it (what `render.yaml` does), or set `UPSTASH_REDIS_REST_URL` and
-  `UPSTASH_REDIS_REST_TOKEN` ([Upstash](https://upstash.com) has a free plan).
+  `XDG_CONFIG_HOME` at it (what `render.yaml` and `fly.toml` do), or set
+  `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` ([Upstash](https://upstash.com)
+  has a free plan).
 
 Render's free Key Value instance is not an option here — no persistence, so the pairing
 disappears at its next maintenance.
 
 Both signers work on a hosted instance. The signing page is served from the same port as
 `/mcp`, so `https://your-host/#t=<relay token>` is your wallet page — no second service to
-deploy. Ask the agent for `wallet_status` to get the link; it is behind `MCP_TOKEN`, and the
-relay token is minted fresh each boot rather than stored, so the URL changes when you
-redeploy.
+deploy. Ask the agent for `wallet_status` to get the link; it is behind `MCP_TOKEN` and never written to the logs. Unless
+you set `WALLET_TOKEN`, the relay secret is minted fresh each boot rather than stored, so the
+URL changes when you redeploy.
 
 </details>
 
 <details>
 <summary>🖇️ <b>Host the signing page</b> separately</summary>
 
-The relay is its own package, [`wallet-relay/`](wallet-relay) — express, cors and ws, about
-4 MB installed against ~180 MB for the server. It runs anywhere that keeps a Node process
-alive and supports WebSockets.
-
-```bash
-WALLET_TOKEN=<long random string> \
-WALLET_PUBLIC_URL=https://wallet.example.com \
-npx web3-wallet-relay
-```
-
-Then point the server at it with `WALLET_SERVER_URL` and the same `WALLET_TOKEN`.
-`render.yaml` deploys it as-is. Anyone holding `WALLET_TOKEN` can send your browser a
-transaction to sign — treat it like a password, and always serve over HTTPS.
+The relay is its own package, [`web3-wallet-relay`](https://github.com/hajnalben/web3-tools-mcp/tree/main/wallet-relay),
+and runs anywhere that keeps a Node process alive and supports WebSockets. Its README covers
+hosting it; run it at this server's version, then point the server at it with
+`WALLET_SERVER_URL` and the same `WALLET_TOKEN`.
 
 Locally nothing changes: the server embeds the same relay.
 
@@ -416,11 +445,11 @@ npm run typecheck
 npm test
 ```
 
-Two workspaces: [`mcp/`](mcp) is this server, [`wallet-relay/`](wallet-relay) is the signing
-page. [CONTRIBUTING.md](CONTRIBUTING.md) covers running a checkout against a client, the
-layout, and how to add a chain or a tool. Releases: [CHANGELOG.md](CHANGELOG.md).
+Two workspaces: [`mcp/`](https://github.com/hajnalben/web3-tools-mcp/tree/main/mcp) is this server, [`wallet-relay/`](https://github.com/hajnalben/web3-tools-mcp/tree/main/wallet-relay) is the signing
+page. [CONTRIBUTING.md](https://github.com/hajnalben/web3-tools-mcp/blob/main/CONTRIBUTING.md) covers running a checkout against a client, the
+layout, and how to add a chain or a tool. Releases: [CHANGELOG.md](https://github.com/hajnalben/web3-tools-mcp/blob/main/CHANGELOG.md).
 
-Requires Node.js ≥ 20.
+Requires Node.js ≥ 20.19.
 
 ## 📄 License
 

package/dist/anvil.d.ts

@@ -1,22 +1,12 @@
-import { type ChildProcess } from 'node:child_process';
-import { createPublicClient } from 'viem';
-export interface AnvilInstance {
-    process: ChildProcess;
-    port: number;
-    rpcUrl: string;
-    client: ReturnType<typeof createPublicClient>;
-}
-export interface AnvilConfig {
-    forkUrl: string;
-    forkBlockNumber?: bigint;
-    port?: number;
-    chainId?: number;
-}
-export declare function isAnvilInstalled(): Promise<boolean>;
-export declare function startAnvil(config: AnvilConfig): Promise<AnvilInstance>;
-export declare function stopAnvil(instance: AnvilInstance): void;
-export declare function withAnvil<T>(config: AnvilConfig, fn: (instance: AnvilInstance) => Promise<T>): Promise<T>;
-export declare function traceTransactionWithAnvil(forkUrl: string, transactionHash: string, blockNumber: bigint, tracer?: 'callTracer' | 'prestateTracer' | 'stateDiffTracer', chainName?: string): Promise<unknown>;
+/**
+ * The node to ask for traces, or undefined when there is none.
+ *
+ * Hosted, only an explicit setting counts: defaulting to loopback would turn every trace
+ * into a request against the server's own private network.
+ */
+export declare function debugRpcUrl(): string | undefined;
+/** Whether a tracing node is reachable and actually offers the debug namespace. */
+export declare function isDebugNodeAvailable(): Promise<boolean>;
 export interface SimulateCallParams {
     to: string;
     data?: string;
@@ -24,6 +14,14 @@ export interface SimulateCallParams {
     value?: bigint;
     gas?: bigint;
 }
+/**
+ * Replay a transaction through the tracing node.
+ *
+ * Run against the block before it, so the state is what the transaction actually saw. The
+ * node needs archive access to that block; without it this fails rather than quietly
+ * tracing against the wrong state.
+ */
+export declare function traceTransactionWithAnvil(forkUrl: string, transactionHash: string, blockNumber: bigint, tracer?: 'callTracer' | 'prestateTracer' | 'stateDiffTracer'): Promise<unknown>;
 export declare function simulateCallWithTrace(forkUrl: string, params: SimulateCallParams, blockNumber?: bigint, tracer?: 'callTracer' | 'prestateTracer'): Promise<{
     result: string;
     trace: unknown;

package/dist/anvil.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anvil.d.ts","sourceRoot":"","sources":["../src/anvil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EAAE,kBAAkB,EAAQ,MAAM,MAAM,CAAA;AAG/C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,YAAY,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAA;CAC9C;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAGD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC,CAMzD;AAyBD,wBAAsB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAoF5E;AAGD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAIvD;AAGD,wBAAsB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAO/G;AAQD,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,YAAY,GAAG,gBAAgB,GAAG,iBAAgC,EAC1E,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAiDlB;AAGD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,kBAAkB,EAC1B,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,GAAE,YAAY,GAAG,gBAA+B,GACrD,OAAO,CAAC;IACT,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAC,CAmFD"}
+{"version":3,"file":"anvil.d.ts","sourceRoot":"","sources":["../src/anvil.ts"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,GAAG,SAAS,CAGhD;AAMD,mFAAmF;AACnF,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAe7D;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AA0ED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,YAAY,GAAG,gBAAgB,GAAG,iBAAgC,GACzE,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,kBAAkB,EAC1B,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,GAAE,YAAY,GAAG,gBAA+B,GACrD,OAAO,CAAC;IACT,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAC,CAiCD"}