@arcnow/mcp 0.1.1 → 0.2.0

package/README.md

@@ -22,8 +22,48 @@ npx -y @arcnow/mcp                  # read-only. The default, and the useful par
 npx -y @arcnow/mcp --allow-writes   # can spend, if ARCNOW_PRIVATE_KEY is in the environment.
 ```
 
-Or tell an MCP client to. Claude Desktop, Cursor, Claude Code and the like all
-take this shape in their MCP server configuration:
+Every client below runs that same command with `ARCNOW_MCP_NETWORK` set. The
+examples say `arc-mainnet`, where [arcnow.io](https://arcnow.io) is live — Arc
+mainnet, chain 5042. `arc-testnet` is the rehearsal network: the same contracts
+at other addresses, with test funds. With the variable unset the server starts
+on `arc-testnet`, so nobody is pointed at real money by omission.
+
+**Write mode, in every client:** add `--allow-writes` to the arguments and put
+the signing key **in a file** the server reads through `ARCNOW_PRIVATE_KEY_FILE`
+— never the key itself in a client config, which gets committed and
+screenshotted. Read-only needs no key at all. **On `arc-mainnet` every write is
+real money**: the spend caps below are what bounds a mistake, and the server
+says so at startup and in every session. Every variable is in
+[Configuration](#configuration); [`examples/`](examples) has both shapes — the
+writes-enabled one on `arc-testnet`, as a rehearsal.
+
+### Claude Code
+
+```sh
+claude mcp add --env ARCNOW_MCP_NETWORK=arc-mainnet --scope user arcnow -- npx -y @arcnow/mcp
+```
+
+`--scope` is `local` (this project, you only; the default), `project` (checked
+into `.mcp.json` at the project root, shared with the team) or `user` (every
+project). The project-file form:
+
+```json
+{
+  "mcpServers": {
+    "arcnow": {
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json` — macOS
+`~/Library/Application Support/Claude/claude_desktop_config.json`, Windows
+`%APPDATA%\Claude\claude_desktop_config.json`:
 
 ```json
 {
@@ -31,17 +71,89 @@ take this shape in their MCP server configuration:
     "arcnow": {
       "command": "npx",
       "args": ["-y", "@arcnow/mcp"],
-      "env": { "ARCNOW_MCP_NETWORK": "arc-testnet" }
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
     }
   }
 }
 ```
 
-A writes-enabled client adds `"--allow-writes"` to `args` and puts the key
-**in a file**, never in the config: see [`examples/`](examples) for both shapes
-and [Configuration](#configuration) for every variable. To run from source
-instead, clone
-[arcnow-io/arcnow-io-mcp](https://github.com/arcnow-io/arcnow-io-mcp), then
+### Codex
+
+`~/.codex/config.toml` (or `.codex/config.toml` in a project):
+
+```toml
+[mcp_servers.arcnow]
+command = "npx"
+args = ["-y", "@arcnow/mcp"]
+
+[mcp_servers.arcnow.env]
+ARCNOW_MCP_NETWORK = "arc-mainnet"
+```
+
+Or from the CLI: `codex mcp add arcnow --env ARCNOW_MCP_NETWORK=arc-mainnet -- npx -y @arcnow/mcp`.
+
+### Cursor
+
+`.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for every project):
+
+```json
+{
+  "mcpServers": {
+    "arcnow": {
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
+```
+
+### VS Code (Copilot agent mode)
+
+`.vscode/mcp.json` — note the key is `servers`, not `mcpServers`:
+
+```json
+{
+  "servers": {
+    "arcnow": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
+```
+
+For write mode, VS Code's `inputs` can prompt for the key-file path instead of
+writing it into the file; see its MCP documentation for the `${input:…}` form.
+
+### Gemini CLI
+
+`~/.gemini/settings.json` (or `.gemini/settings.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "arcnow": {
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
+```
+
+Or `gemini mcp add -e ARCNOW_MCP_NETWORK=arc-mainnet arcnow npx -y @arcnow/mcp`.
+
+### Windsurf, Cline
+
+Both take the generic `mcpServers` JSON above — the same `command`, `args` and
+`env` — in their MCP settings file.
+
+### From source
+
+Clone [arcnow-io/arcnow-io-mcp](https://github.com/arcnow-io/arcnow-io-mcp), then
 `npm ci && npm run build && node dist/index.js`; the SDK comes from npm.
 
 ---
@@ -97,13 +209,13 @@ Nine read tools, always published. Six write tools, published only on opt-in.
 | tool | what it answers |
 | --- | --- |
 | `arcnow_network` | Which chain, which contracts, which graduation venues, whether a v4 router is configured for graduated tokens, **and which mode this server is in**. The first call of any session that might trade. |
-| `arcnow_quote_tokens` | The quote tokens a launch may use — native USDC and the ERC-20s the quote registry allowlists, such as EURC — each with its symbol, name, decimals, address, whether it is native, its launch fee in its own units, whether the registry accepts it now, and **this server's spend cap for it**. At most three `eth_call`s. On a chain with no quote registry (the 2.x contracts Arc testnet ran until the multi-quote reset), it says so, shows the error, and lists the network's own quote-token metadata with nothing known to be accepted. |
+| `arcnow_quote_tokens` | The quote tokens a launch may use — native USDC and the ERC-20s the quote registry allowlists, such as EURC — each with its symbol, name, decimals, address, whether it is native, its launch fee in its own units (zero on both networks: launching is free, and the figure is read from the registry rather than assumed), whether the registry accepts it now, and **this server's spend cap for it**. At most three `eth_call`s. On a chain with no quote registry, it says so, shows the error, and lists the network's own quote-token metadata with nothing known to be accepted. |
 | `arcnow_list_tokens` | Recent launches, newest first, from the launchpad's `Launched` log, back to the block it was deployed in. Reports the block window it actually covered — see [the SDK gap](#what-made-a-clean-surface-awkward). |
-| `arcnow_token` | One token in full: metadata, **its quote token** (address, symbol, decimals, native or ERC-20), its curve's parameters (`r0Wad`, `y0Wad`), curve state, price, progress, and **where it trades now** — its curve, its v4 pool (with the router, whether it reaches the pool, the PoolManager, the pool's LP fee and what the fee hook holds accrued), or nowhere. Takes a token *or* a curve address. |
-| `arcnow_quote_buy` | What an amount of the token's quote (`quoteIn`) would buy, wherever the token trades. On a curve: tokens out, the 1% fee and exactly who receives it, the average fill price, minimum-out floors at four tolerances. In a pool: a quote that says it is a pool quote, with arcnow.io's 1% and the pool's own LP fee apart, the average fill against the pool's spot price, and the price impact. |
+| `arcnow_token` | One token in full: metadata, **its quote token** (address, symbol, decimals, native or ERC-20), its curve's parameters (`r0Wad`, `y0Wad`), curve state, price, progress, and **where it trades now** — its curve, its v4 pool (with the router, whether it reaches the pool, the PoolManager, what a trade there costs — the hook's 0.80% and the pool's 0.20% LP fee, read off the pool — how the hook splits its part, and what it holds accrued), or nowhere. Takes a token *or* a curve address. |
+| `arcnow_quote_buy` | What an amount of the token's quote (`quoteIn`) would buy, wherever the token trades. On a curve: tokens out, the 1% fee split four ways — creator, platform, referrer, protocol — with exactly who receives each share, the average fill price, minimum-out floors at four tolerances. In a pool: a quote that says it is a pool quote, with the fee hook's 0.80% and the pool's own 0.20% LP fee apart (1.00% in all, both read off the pool), the hook's three-way split, the average fill against the pool's spot price, and the price impact. |
 | `arcnow_quote_sell` | The same for a sell — plus, on a curve, that selling needs no approval, ever, and in a pool, that it does, and how much the holder has approved already. |
-| `arcnow_quote_launch` | What a launch in a given `quote` (native USDC by default, or an ERC-20 by symbol or address) would cost before anything is spent, split into the flat fee and the initial buy's own trade fee, with the predicted token and curve addresses. |
-| `arcnow_platform` | A platform's fee split, its default migrator and its curve template — every share printed both as bps of the fee and as a percentage of a trade. |
+| `arcnow_quote_launch` | What a launch in a given `quote` (native USDC by default, or an ERC-20 by symbol or address) would cost before anything is spent: the launch fee the registry reports (zero — launching is free), the initial buy and its own trade fee, with the predicted token and curve addresses. |
+| `arcnow_platform` | A platform's four-way fee split, its default migrator and its curve template — every share printed both as bps of the fee and as a percentage of a trade. |
 | `arcnow_list_platforms` | The registry's actual enumeration. Complete, unlike the token list. |
 
 The read tools are the valuable part. An assistant that can answer *what is this
@@ -118,13 +230,16 @@ mistake that costs money:
   reports an *average fill price* next to the spot price, and the tool
   descriptions tell the model to quote rather than multiply.
 - **A share of the fee is not a share of the trade.** 3000 bps of the fee is
-  0.30% of a trade. Both are printed, every time.
+  0.30% of a trade. Both are printed, every time. The fee has **four parties** —
+  creator, platform, referrer, protocol; arcnow.io's own split is 3000 / 3500 /
+  1000 / 2500 — and no developer share: no tool takes a `developer`.
 - **Graduated and migrated are different states.** A curve can have stopped
   trading permanently while its pool was never created, and then the token
   trades *nowhere*. That is reported as its own thing, with the rescue named.
 - **A pool quote is not a curve quote.** It says so, and it names two charges,
-  not one: arcnow.io's 1%, taken in the pool's quote by the fee hook, and the pool's own
-  Uniswap LP fee on top.
+  not one: the fee hook's **0.80%**, taken in the pool's quote and split creator /
+  platform / protocol, and the pool's own **0.20%** Uniswap LP fee — 1.00% in all,
+  the same as the curve charged. Both rates are read off the pool, never assumed.
 
 ### Write
 
@@ -163,8 +278,8 @@ set a boolean — but does make the assertion explicit in the transcript.
    Zero means "fill me at any price", which on a public mempool is a donation,
    so it has to be typed rather than omitted.
 5. **Nothing that does not apply.** A curve trade pays the sender and has no
-   `recipient`; a pool swap has no `referrer` or `developer` and cannot graduate
-   anything, so `gasLimit` guards nothing there. Each is **refused** on the
+   `recipient`; a pool swap has no `referrer` and cannot graduate anything, so
+   `gasLimit` guards nothing there. Each is **refused** on the
    venue it does not exist on, before anything is quoted or sent — never
    silently dropped. The SDK refuses the same things; this server says so first.
 6. **The report.** Each tool states the exact cost and the exact effect, and
@@ -202,15 +317,21 @@ four tools work across that line. Three states, told apart out loud:
 | state | quote | buy / sell |
 | --- | --- | --- |
 | on its curve | a curve quote, as before | through the curve; `recipient` refused |
-| graduated **and** migrated | a pool quote, labelled as one | through arcnow.io's router; `gasLimit`, `referrer`, `developer` refused |
+| graduated **and** migrated | a pool quote, labelled as one | through arcnow.io's router; `gasLimit`, `referrer` refused |
 | graduated, **not** migrated | refused: tradeable nowhere until `migrate()` | refused, naming `arcnow_migrate` |
 
 **What a pool quote contains.** The SDK prices a pool trade by simulating the
 real swap through the router, so the figures are the real fill with two charges
-inside them. The quote takes them back out and names each: arcnow.io's 1%, which
-the fee hook takes in the pool's quote, and the pool's own LP fee — the pool key's `fee`, in
-hundredths of a bip — which Uniswap charges on top. It shows the average fill
-price, the pool's spot price, and the price impact between them. The SDK has no
+inside them. The quote takes them back out and names each: the fee hook's 0.80%,
+which it takes in the pool's quote and splits creator 5000 / platform 1875 /
+protocol 3125 bps (a pool swap has no referrer), and the pool's own 0.20% LP fee
+— the pool key's `fee`, in hundredths of a bip — which Uniswap charges and the
+pool's liquidity keeps. 1.00% in all, the same as the curve. Every rate comes
+from the SDK's `Pool.fees()`, which reads the hook's `feeBps()` and
+`feeConfigOf()` and the key; this server holds no fee constant, so a pool whose
+key carries another LP fee is reported at the fee it carries. It shows the
+average fill price, the pool's spot price, and the price impact between them.
+The SDK has no
 reader for a pool's price, so the spot price is the SDK's own quote of a
 probe buy with both fees taken out — 0.000001 of an 18-decimal quote, or 10,000 raw
 units of a smaller one (0.01 EURC), so the fees' raw-unit rounding stays below one
@@ -253,32 +374,35 @@ decoded contract error or revert *failed on-chain*. `RpcFailure` *could not
 reach the chain*: the public endpoint rate-limits, and that says nothing about
 the token.
 
-### One curve
+### One curve, on two networks
 
 arcnow.io has one bonding curve — the constant-product curve,
-`arcnow/bonding-curve@3.x.x`, priced in a quote token, with parameters `r0Wad`
+`arcnow/bonding-curve@4.x.x`, priced in a quote token, with parameters `r0Wad`
 (the virtual quote reserve at launch, in WAD) and `y0Wad` (the virtual token
 reserve at launch) — launched through one contract stack, and a fee hook,
-`arcnow/arc-now-fee-hook@3.x.x`, that
-accrues each fee as a PoolManager claim and pays it out at the start of a later
-swap.
+`arcnow/arc-now-fee-hook@4.x.x`, that takes its 0.80% in the pool, accrues each
+fee as a PoolManager claim and pays it out at the start of a later swap. The same
+build is live on Arc mainnet (`arc-mainnet`) and Arc testnet (`arc-testnet`), at
+different addresses; a token address from one means nothing on the other, and
+the server's instructions say which network a session is on.
 
 - **Nothing a tool prints names a curve kind or a stack.** There is one of
   each. `arcnow_token` prints the curve's own parameters, and a pool trade
   reports the fees it paid out from earlier trades (`FeesDistributed`) apart
   from the trader's fill.
 - **Any other version is refused by name, and never priced.** A curve or a
-  platform of another version — the 2.x contracts Arc testnet ran until the
-  multi-quote reset and the retired linear curve, `@1.x.x`, included —
-  is the SDK's `UnknownCurveVersion`, naming the version, before any quote or
-  send. A fee hook of another version is `UnknownHookVersion`, and its accrual
-  is not read.
+  platform of another version — the retired multi-quote stack, `@3.x.x`, which
+  carried a developer share and whose data was wiped; the `@2.x.x` contracts
+  before it; the retired linear curve, `@1.x.x` — is the SDK's
+  `UnknownCurveVersion`, naming the version, before any quote or send. A fee hook
+  of another version — the `@3.x.x` hook that charged 1% in the pool included —
+  is `UnknownHookVersion`, and neither its accrual nor its rates are read.
 - **An address that is not a curve is refused by name.** The SDK's
   `AddressIsNotACurve` for an arcnow.io token's address is followed to its curve;
   for anything else — an ordinary ERC-20, an account, nothing at all — it is the
   refusal, saying the address is not an arcnow.io token either.
 - **`arcnow_list_tokens` reads the one launchpad**, back to the block its stack
-  was deployed in (61,911,405 on Arc testnet).
+  was deployed in (21,179,866 on Arc mainnet, 62,386,232 on Arc testnet).
 
 ---
 
@@ -290,7 +414,7 @@ where an operator's decisions belong. See
 
 | variable | default | what it does |
 | --- | --- | --- |
-| `ARCNOW_MCP_NETWORK` | `arc-testnet` | The network preset. `arc-mainnet` is **refused at startup, by name** — arcnow.io is not deployed to one, and this server will not invent an address. |
+| `ARCNOW_MCP_NETWORK` | `arc-testnet` | The network preset: `arc-mainnet` (Arc mainnet, chain 5042, where arcnow.io is live — **real money**) or `arc-testnet` (the rehearsal, chain 5042002). Both come from the SDK's `networks.json`; a name it does not know refuses to start, naming the two it does. The default is the rehearsal on purpose. |
 | `ARCNOW_MCP_NETWORK_FILE` | unset | A path to a JSON document in the SDK's `CustomNetwork` shape, for a deployment no preset names — a local anvil stack, or a stack deployed onto a fork. **Mutually exclusive with a preset name.** See [below](#a-network-the-sdk-has-no-preset-for). |
 | `ARCNOW_RPC_URL` | the preset's endpoint | Override the endpoint. Redacted of credentials before it is ever printed. |
 | `ARCNOW_MCP_ALLOW_WRITES` | unset | `1` enables the write tools. `--allow-writes` does the same. |
@@ -313,7 +437,9 @@ in EURC. So every quote token has its own cap, in its own units:
 - `ARCNOW_MCP_MAX_SPEND_USDC` caps native USDC, and defaults to `100`.
 - `ARCNOW_MCP_MAX_SPEND_<SYMBOL>` caps each other quote — `ARCNOW_MCP_MAX_SPEND_EURC=50`
   is 50 EURC. The symbol is upper-cased; a character that is not a letter or a
-  digit is written `_`.
+  digit is written `_`. The cap is matched to the network's own token by
+  address: on `arc-mainnet` that is EURC at `0xbEf5f6d5…`, on `arc-testnet` at
+  `0x89b50855…`, each read from the preset.
 
 It fails closed, four ways:
 
@@ -330,8 +456,8 @@ It fails closed, four ways:
 - **Two quote tokens of the network sharing a symbol refuses to start** it: one
   variable cannot mean two caps.
 
-What counts: a launch spends its `totalCost` — the launch fee plus the initial
-buy, in the launch's quote; a buy spends its `quoteIn`. For an ERC-20 quote the
+What counts: a launch spends its `totalCost` — the initial buy plus any launch
+fee (zero on both networks), in the launch's quote; a buy spends its `quoteIn`. For an ERC-20 quote the
 SDK approves exactly that spend, so the same check covers the approve. The
 caller's own `maxTotalCost` is read in the same quote. The startup banner,
 `arcnow_network` and `arcnow_quote_tokens` show every cap, and
@@ -341,7 +467,7 @@ caller's own `maxTotalCost` is read in the same quote. The startup banner,
 ### A network the SDK has no preset for
 
 `ARCNOW_MCP_NETWORK_FILE=/path/to/network.json` points the server at a
-deployment by its addresses — a local anvil stack, or the 3.x stack this
+deployment by its addresses — a local anvil stack, or the stack this
 repository's fork proof deploys onto a fork of Arc testnet:
 
 ```json
@@ -393,7 +519,7 @@ token. Gas is always native USDC, whatever a token's quote.
 `@arcnow/sdk` is published to npm from
 [arcnow-io/arcnow-io-sdk](https://github.com/arcnow-io/arcnow-io-sdk), one tagged
 release per version, and this server depends on it at an **exact version** —
-`"@arcnow/sdk": "0.1.3"`, never `^0.1.3`. The tool descriptions promise what one
+`"@arcnow/sdk": "0.2.0"`, never `^0.2.0`. The tool descriptions promise what one
 known SDK does; a range would let `npm install` move the code under them with no
 commit here saying so. Moving the pin is a pull request.
 
@@ -402,10 +528,10 @@ commit here saying so. Moving the pin is a pull request.
 ```json
 "sdk": {
   "package": "@arcnow/sdk",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "integrity": "sha512-…",
   "public_repo": "arcnow-io/arcnow-io-sdk",
-  "tag": "v0.1.3",
+  "tag": "v0.2.0",
   "why": ["what this server uses from that SDK, in prose"]
 }
 ```
@@ -417,214 +543,56 @@ surface**: every module, the generated ABIs that encode every call, the
 published this file hashed its sources file by file and the gate recompiled its
 `dist/`; the integrity replaces all of that.)
 
-`scripts/check-pins.sh` (run straight after the install by `scripts/preflight.sh`)
-enforces four things:
-
-1. `package.json` depends on the SDK at **exactly** `sdk.version`. A range, a
-   `file:` path or another number fails, by name.
-2. `package-lock.json`'s entry for it carries that version, resolves to the npm
-   registry, and its `integrity` **is** `sdk.integrity` — the link between the
-   version and the bytes; npm refuses to install a tarball that does not hash to
-   it.
-3. `node_modules/@arcnow/sdk/package.json` is that version — what the server
-   actually compiles against and imports.
-4. The registry has that version and serves it with that `dist.integrity`, so
-   the pinned bytes are the published bytes. This needs the network: unreachable
-   is a **warning** (a laptop on a train is not a broken pin) unless
-   `ARCNOW_REQUIRE_REGISTRY=1`, which CI sets; a 404 is always a failure.
-
-Together: the manifest asks for one version, the lockfile binds it to one
-tarball, `node_modules` holds it, and the registry says those are the bytes it
-serves under that number. `test/unit/check-pins.test.ts` builds real roots with
-a fake `npm` on `PATH` and breaks each link on purpose — a range, a path, a
-foreign tarball, a stale install, a version the registry never had, a registry
-that cannot be reached.
-
-Moving the pin is a commit of its own: `npm install @arcnow/sdk@X.Y.Z
---save-exact`, `npm ci`, `scripts/check-pins.sh --record` — which records the
-version, the lockfile's integrity and the tag, and refuses a range or a version
-the registry does not have — update `sdk.why`, run preflight, and say what
-changed in the SDK surface and what it meant for the tools. A tool description
-that still promises what an older SDK did is a model quoting a wrong price.
+Before every release the maintainers verify that the manifest, the lockfile, the
+installed package and the registry all name that one tarball; moving the pin is a
+pull request that reads the SDK's changelog and re-reads every tool description.
 
 ---
 
-## Running the gates
+## Testing
 
 ```bash
-./scripts/preflight.sh              # install, pins, lint, typecheck, build, tests, fork proof
-./scripts/preflight.sh --no-install
-./scripts/preflight.sh --no-chain   # everything but the fork proof
-./scripts/check-pins.sh             # just the pin
-npm test                            # just the unit suite — no chain, no container, no key
-npm run test:fork                   # just the fork proof — needs Docker
+npm test     # the unit suite: no chain, no container, no key
 ```
 
-`.github/workflows/ci.yml` is `workflow_dispatch:` only, the same decision every
-repository in this org has made. **`scripts/preflight.sh` is the gate**; the
-workflow is a transcription of it, kept because a clean-checkout run is the one
-thing a local run cannot prove.
-
-Everything but the fork proof needs nothing beyond `npm ci`: the SDK comes from
-npm. The fork proof is the maintainers' **private infrastructure**: it starts one
-container, an anvil fork of Arc testnet from the Foundry image `pins.json` pins,
-labelled `io.arcnow.mcp.test`, and deploys arcnow.io's 3.x multi-quote contracts
-onto it with the private `arcnow-io/sdk` checkout's `scripts/fork-deploy-stack.sh`
-(`ARCNOW_SDK_DIR`, default `../sdk`). Arc testnet now runs a 3.x stack of its own,
-deployed on 2026-09-15, but the fork is taken at a pinned, already-cached block
-from before that, where the live contracts are the 2.x ones the SDK refuses — and
-a proof that deploys its own stack does not depend on what happens to be live
-anyway. That also needs `ARCNOW_CONTRACTS_DIR`, a checkout
-of arcnow-io/contracts at the commit that SDK checkout's `pins.json` names, and
-forge at the release it names. Its harness —
-copied from `arcnow-io/sdk`'s, not imported, because that repository's tests are
-not part of the pinned surface — removes it on every exit path, sweeps only its
-own label, and touches nothing else on a shared daemon.
-
-### What the tests prove
+It runs against a fake chain that does exactly what each test says, and proves
+what can be proved offline:
 
 - **A key is never an argument.** Every published schema is walked for
-  credential-shaped field names and for descriptions that ask for one; every
-  schema is asserted strict; and passing `privateKey` or `mnemonic` anyway is
-  asserted to be refused, named, answered with "rotate it", and to leave the
-  port untouched.
-- **A write refuses without the opt-in.** Every write tool, called on a
-  read-only server, is asserted to error, to name `--allow-writes` and
-  `ARCNOW_PRIVATE_KEY`, to tell the model not to ask a user for a key — and,
-  the assertion that carries the weight, **to have sent nothing**.
-- **Both spend ceilings stop a transaction rather than annotate one**, on a
-  curve and in a pool alike, **per quote token**: a USDC-only configuration
-  refuses a EURC buy and launch; an EURC cap allows up to it and refuses a raw
-  unit above; a typo'd cap variable refuses to start; a USDC cap does not apply
-  to EURC or the reverse; a quote the network does not list is refused.
-- **Every amount is labelled with its own quote** — native, a 6-decimal and an
-  18-decimal ERC-20 — a pool's quote is the SDK's in either currency order, an
-  input with more decimals than its quote is refused, and an ERC-20 spend's
-  approve is reported whether it was sent or not.
-- **The gas trap is handled**, for a buy and for a launch whose initial buy
-  graduates the curve.
-- **The venues are told apart.** A migrated token is quoted and traded in its
-  pool through `client.trade`; a stranded one is refused everywhere with
-  `arcnow_migrate` named; a curve-only parameter in a pool and a pool-only one
-  on a curve are refused with nothing sent.
-- **The sell approval is gated and disclosed.** Never sent without
-  `approveRouter: true`, never for more than the amount sold, not sent when the
-  allowance already covers the sale, reported in full, and still reported when
-  the sell after it fails.
-- **The reports say true things.** Fees broken out, a pool's two charges apart,
-  an absent referrer's share named as going to the platform, the average fill
-  price distinguished from the spot price, graduated distinguished from
-  migrated, an undecodable pool revert explained cautiously rather than bare.
-- **The pin gate fails when it should.** See above.
-- **The wire works.** A real MCP client against a real MCP server over an
-  in-memory transport, and — in the fork proof — over stdio against the built
-  server.
-- **Against the 3.x contracts deployed onto a fork of Arc testnet**
-  (`test/fork/mcp.fork.test.ts`), the built server — started with
-  `ARCNOW_MCP_NETWORK_FILE` naming the deployed stack — driven by a real MCP
-  client lists the quote tokens from the deployed registry in at most three
-  `eth_call`s with each one's cap, launches a native USDC
-  token on the launchpad, reads it
-  back with its quote token, `r0Wad` and `y0Wad`, buys it on its curve,
-  watches an impersonated Arc account graduate it, then quotes, buys and sells it
-  in its Uniswap v4 pool through the live router — and sells a second token back
-  to its curve — and launches a token in EURC, with its exact approve and exactly
-  the total pulled, buys it in EURC, and has a buy above the 50 EURC cap refused
-  with nothing sent. Every figure is checked against the chain with viem, not through
-  the server: every quote equals its fill, to the wei; exactly the amount and
-  the gas left the signer; the sell's approval is one `Approval` log to the
-  router for exactly the amount sold, used up by the sale; the recipient is paid
-  exactly what the report says; a swap's fee payout matches the hook's
-  `FeesDistributed` log; the refusals leave the signer's nonce where it was; and
-  the USDC ERC-20 predeploy comes back as `AddressIsNotACurve`. The server's RPC
-  goes through a counting proxy, and the per-call request counts are printed.
-- **One curve, and nothing else priced.** Against the fake, whose version
-  checks are the SDK's own `assertCurveVersion` and `assertPlatformVersion`: no
-  report names a curve kind or a stack, an `@1` curve, platform or fee hook is
-  refused by name with nothing quoted or sent, and the launch scan reads the one
-  launchpad from its deployment block.
-
-### What they do not prove
-
-- **Not Arc's own execution semantics.** A fork re-executes locally with
-  anvil's EVM and disagrees with Arc about blocklisted transfers, EIP-1153, the
-  EIP-7708 system emitter and burn-to-zero without saying so.
-- **Not a EURC pool against a chain.** The fork proof launches a EURC token,
-  buys it on its curve with the exact approve, and holds the 50 EURC cap; a
-  EURC token's pool is unit-tested against the fake.
-- **Not every path against a chain.** The fork proof covers a launch, curve
-  trades, graduation and pool trades. A
-  migration through `arcnow_migrate`, a graduating buy through `arcnow_buy` (the
-  proof graduates its token through the SDK, so that nothing credits the
-  server's signer), a token that graduated but never migrated — there is none on
-  Arc testnet to fork — and a curve, platform or hook whose version the SDK
-  refuses are
-  unit-tested here against the fake, and proved against a chain, where they are
-  at all, by the SDK's own fork suite. If you change how a tool calls the SDK,
-  run the SDK's preflight too.
-- **Not that the tool descriptions are true.** Those are prose, read by a model
-  deciding whether to spend somebody's money. When the pin moves, that is a
-  person's job.
-- **Not that a model behaves.** Every guard in this server is a bound on
-  damage, not a guarantee of judgement.
-
----
-
-## What made a clean surface awkward
-
-Five things, all worth fixing upstream rather than here — and one of them now is.
-
-**The SDK cannot enumerate tokens.** There is no `recentLaunches()` anywhere in
-`@arcnow/sdk`, and its `networks.json` explains why a preset cannot carry one: a
-token and its curve come from the `Launched` log, one pair per launch, and there
-are as many as there have been launches. But "show me the recent tokens" is the
-first thing anybody asks an assistant, so `arcnow_list_tokens` reads that log
-directly — with the SDK's own pinned ABI, through the SDK's own configured
-client, at the SDK's own launchpad address, adding nothing but the scan. It is
-the only place in this repository that talks to the chain outside an SDK method,
-and it is in `src/sdk-port.ts` with a comment saying so. A
-`launchpad.recentLaunches()` belongs in the SDK, where the forked-chain suite
-could test it against a real chain; here it is tested against a fake.
-
-Because the scan is a bounded walk backwards from the tip rather than an index,
-`arcnow_list_tokens` reports the block window it covered and says plainly when
-it stopped on its budget with history unread. An assistant must not conclude a
-token does not exist from a tool that only ever saw a window.
-
-**The SDK's handles are classes with private fields.** `Curve`, `Token`,
-`Launchpad` and `PlatformRegistry` are nominally typed, so nothing can be
-assigned to them — a test cannot construct a stand-in, and there is no seam to
-substitute one. That is why `src/sdk-port.ts` exists: a set of interfaces the
-SDK's handles already satisfy, wrapping nothing and computing nothing, so that a
-fake can drive every tool through the states that matter and are hardest to
-reach on a real chain (a buy that graduates, a curve that graduated and never
-migrated, a cost that moved between the quote and the order). If the SDK exposed
-interfaces alongside its classes, that file would be a re-export.
-
-**The SDK has no reader for a pool's price.** A pool quote is the real fill, but
-"how far is that from the pool's price" needs the pool's price, and there is no
-`slot0`/`sqrtPriceX96` read anywhere in `@arcnow/sdk`. Reading the PoolManager's
-storage here would be the second, unpinned copy of chain code this server exists
-not to have. So the spot price is the SDK's own quote of a tiny probe buy with
-both fees taken out — accurate to far below the printed digits, one extra
-`eth_call`, and labelled as what it is. A `pool.spotPrice()` belongs in the SDK.
-The pool's LP fee is likewise not in a quote; it is read from `pool.key()`.
-
-**Fixed upstream: a revert inside the pool.** A revert from inside the fee hook,
-or a failed transfer out of the PoolManager, arrives wrapped in Uniswap v4's
-`WrappedError`. It used to surface as a bare `UnknownRevert`. Since sdk#7 the SDK
-unwraps it and names the failed transfer (`NativeTransferFailed` /
-`ERC20TransferFailed`), so this server only shows what the SDK decoded.
-
-**A pool sell quote needs a real holder.** The SDK overrides the router
-allowance for a sell simulation but deliberately not the balance, so
-`arcnow_quote_sell` on a pool needs `holder` on a read-only server. That is the
-right call, and it is why that argument exists.
-
-Nothing else got in the way. In particular, the SDK's four amount types, its
-refusal to default a slippage floor, its explicit `gasLimit`, its
-`migratedInThisTransaction` flag and its by-selector error decoding are each the
-reason a corresponding class of mistake is not reachable from here.
+  credential-shaped field names and asserted strict; passing `privateKey` or
+  `mnemonic` anyway is refused, named, answered with "rotate it", and sends
+  nothing.
+- **A write refuses without the opt-in**, names `--allow-writes` and
+  `ARCNOW_PRIVATE_KEY`, and has sent nothing.
+- **Both spend ceilings stop a transaction**, on a curve and in a pool, per
+  quote token, on either preset — mainnet's EURC is capped by its mainnet
+  address; a typo'd cap variable refuses to start; a USDC cap does not apply
+  to EURC or the reverse.
+- **Every amount is labelled with its own quote**, an input with more decimals
+  than its quote is refused, and an ERC-20 approve is reported whether it was
+  sent or not.
+- **The gas trap is handled**, the venues are told apart (a stranded token is
+  refused everywhere with `arcnow_migrate` named), the sell approval is never
+  sent without `approveRouter: true` and never for more than the amount sold,
+  and the reports say true things: a curve fee broken out four ways, a pool's
+  0.80% and 0.20% read off the pool and never assumed, a free launch printed
+  from the registry's zero, average fill price apart from spot, graduated apart
+  from migrated.
+- **Both presets resolve** to the SDK's live deployments, `arc-mainnet` says it
+  is real money, and nothing of one network's addresses appears in a report
+  about the other.
+- **The wire works**: a real MCP client against a real MCP server over an
+  in-memory transport.
+
+What the unit suite cannot prove — that the built server, driven by a real MCP
+client over stdio, lists the quote tokens, launches, buys and sells a token on its
+curve and in its Uniswap v4 pool, and launches and buys a token priced in EURC
+under the EURC cap, against arcnow.io's real contracts, every quote equal to its
+fill to the wei — the maintainers prove before every release, on an anvil fork of
+Arc testnet with those contracts deployed onto it. A fork re-executes with anvil's
+EVM, so Arc's own execution semantics are outside even that; and no test can
+prove that a tool description is true or that a model behaves — every guard here
+is a bound on damage, not a guarantee of judgement.
 
 ---
 

package/dist/config.d.ts

@@ -57,7 +57,15 @@
  * the network sharing a symbol is a startup error, because their two caps would
  * be one variable.
  *
- * # A network the SDK has no preset for
+ * # Two presets, and a network the SDK has no preset for
+ *
+ * `ARCNOW_MCP_NETWORK` is `arc-mainnet` — Arc mainnet, chain 5042, where
+ * arcnow.io is live and every write spends real money — or `arc-testnet`, the
+ * rehearsal network at chain 5042002, which runs the same contracts at other
+ * addresses. Both resolve through the SDK's `resolveNetwork`, which is the only
+ * source of an address in this server. The default is `arc-testnet`: a server
+ * started with no network named should not be pointed at real money by
+ * omission.
  *
  * `ARCNOW_MCP_NETWORK_FILE` names a JSON document in the SDK's `CustomNetwork`
  * shape — `rpcUrl`, `chainId`, `contracts`, and optionally `quoteTokens` and
@@ -176,9 +184,10 @@ export declare const DEFAULTS: {
     readonly network: "arc-testnet";
     /**
      * 100 USDC a call. Low enough that a prompt-injected "buy everything" is a
-     * bounded accident and not a bounded-by-your-balance one; high enough that
-     * the shipped 2 USDC launch fee plus a real first buy fits under it. An
-     * operator who means to spend more says so once, at startup, on purpose.
+     * bounded accident and not a bounded-by-your-balance one; high enough that a
+     * real first buy fits under it (launching itself is free on arcnow.io's
+     * networks). An operator who means to spend more says so once, at startup, on
+     * purpose — and on arc-mainnet every one of these is real money.
      *
      * Native USDC only. Every other quote has NO default: spending it is refused
      * until the operator names a cap for it.