midnight-wallet-cli 0.5.2 → 0.6.0-rc.0

package/docs/SKILL-CORE.md

@@ -0,0 +1,45 @@
+# midnight-wallet-cli — Agent Skill (Core)
+
+You have access to the `midnight-wallet-cli` MCP server. This is the **core** skill — intent routing and non-negotiable safety rules. Fetch `midnight-wallet://skill/full` on demand for canonical multi-step flows, error-recovery recipes, concept primers (NIGHT, DUST, shielded vs unshielded), network selection, and deeper context.
+
+**Ledger 9 only.** This build refuses a chain still on ledger 8 (preview and preprod today; those stay on `midnight-wallet-cli` 0.5.x) and refuses `midnight_localnet_up` (no published ledger-9 indexer image yet). The user runs a ledger-9 stack and points mn at it; details in `/full`.
+
+## Intent routing (natural language → tool)
+
+| User says | Call this tool |
+|---|---|
+| "Create a new wallet called alice" | `midnight_wallet_generate({ name: "alice" })` |
+| "Show my wallets" / "list wallets" | `midnight_wallet_list()` |
+| "Switch to bob" / "use wallet bob" | `midnight_wallet_use({ name: "bob" })` |
+| "What's my balance?" | `midnight_balance()` |
+| "Balance for this address 0x…" | `midnight_balance({ address: "mn_addr_..." })` |
+| "Send 100 NIGHT to alice" | `midnight_transfer({ to: "alice", amount: "100" })` — ask consent first |
+| "Send shielded" | use the shielded address directly, or pass `--shielded` via the CLI |
+| "Fund my wallet" (localnet only) | `midnight_airdrop({ amount: "1000" })` |
+| "Register dust" / "I need fees" | `midnight_dust_register()` |
+| "Am I registered for dust?" | `midnight_dust_status()` |
+| "Start localnet" / "start a local network" | Refused on this build: explain, and point the user at running a ledger-9 stack (see `/full`) |
+| "Stop localnet" | `midnight_localnet_stop()` |
+| "Show localnet logs" / "what's the indexer doing" | `midnight_localnet_logs({ tail: "200" })` |
+| "Inspect this contract" / "what circuits does this dApp expose" | `midnight_contract_inspect({ path })` |
+| "Deploy this contract" / "deploy on undeployed" | `midnight_contract_deploy({ path, wallet, network })` — two-step pending token |
+| "Call circuit X" / "submit a score" | `midnight_contract_call({ address, circuit, args })` — two-step pending token |
+| "What's the contract state?" / "read the ledger" | `midnight_contract_state({ address, path })` |
+| "Generate tests for this contract" / "scaffold a test suite" | `midnight_test_create({ path })` (default cli; pass `strategy: "browser"` + `port` + `build-cmd` for UI tests) |
+
+## Safety rules (non-negotiable)
+
+- **Read tools** (`readOnlyHint: true`) — safe to call without user consent. Examples: balance, info, list, status, address derivation.
+- **Destructive tools** (`destructiveHint: true`) — require explicit user consent before calling. Examples: transfer, airdrop, dust register, wallet generate, wallet remove, cache clear, localnet down.
+- **Open-world tools** (`openWorldHint: true`) — touch the network/chain/Docker. Can fail non-deterministically; retry is usually safe for reads, risky for writes.
+- **Never** auto-execute a fund-moving operation. Always describe amount + recipient + network first.
+- **Never** invent a mnemonic, seed, or private key. If the user needs one, call `midnight_wallet_generate`.
+- **Transfers use a two-step confirmation token.** `midnight_transfer` returns a pending token + description; you must show the description verbatim and then call `midnight_confirm_operation({ token })` only after the user explicitly says yes. Full flow in `midnight-wallet://skill/full`.
+
+## When to fetch the full skill
+
+- On any error from a tool call → fetch `midnight-wallet://skill/full`, find the recipe in "Error recovery recipes".
+- Before a multi-step flow (first session, deploying a contract, transfer with confirmation) → fetch `/full` for the canonical sequence.
+- When the user asks conceptual questions (what is dust, shielded vs unshielded, which network) → fetch `/full`.
+- For per-tool details: read the tool description in `tools/list`.
+- For CLI reference: `mn help <command>`.

package/docs/SKILL.md

@@ -2,9 +2,11 @@
 
 You have access to the `midnight-wallet-cli` MCP server. This document teaches you how to use it well. Read it once at the start of a session; use it as reference throughout.
 
+> **Ledger 9 only.** This build speaks ledger 9 only. A chain still on ledger 8 (preview and preprod today) is refused up front with an error saying so: tell the user to use `midnight-wallet-cli` 0.5.x for it, don't retry. `midnight_localnet_up` is refused too, because no published indexer image runs ledger 9 yet. The user runs a ledger-9 stack themselves; on the default ports (node 9944, indexer 8088, proof server 6300) `undeployed` reaches it with no configuration, otherwise set its URLs with `midnight_config_set` (keys `node`, `indexer-ws`, `proof-server`) or pass `--node` / `--indexer-ws` / `--proof-server` on the CLI.
+
 ## What you can do with this CLI
 
-Manage wallets, check balances, transfer NIGHT tokens, register dust (fee token), run a local Midnight network, and deploy/call/inspect Compact smart contracts — all on behalf of the user. Every CLI command is also an MCP tool.
+Manage wallets, check balances, transfer NIGHT tokens, register dust (fee token), manage a local Midnight network, act as a fee wallet for an agent's dApp transactions (`mn serve --approve-fees`), and deploy/call/inspect Compact smart contracts — all on behalf of the user. Every CLI command is also an MCP tool.
 
 ## Core concepts (teach these accurately)
 
@@ -14,9 +16,9 @@ Manage wallets, check balances, transfer NIGHT tokens, register dust (fee token)
 - **Shielded vs unshielded** — shielded addresses start `mn_shield-addr_*`; unshielded start `mn_addr_*`. A wallet has one of each per network. Sender controls the privacy: `mn transfer --shielded` sends privately.
 - **No self-shielding** — a wallet cannot move its own funds from unshielded to shielded. To get shielded NIGHT, receive a shielded transfer from a wallet that already has some (genesis wallet has 250M shielded NIGHT on localnet).
 - **Networks**
-  - `undeployed` — local Docker network via `mn localnet up`. Use this for dev iteration.
-  - `preprod` — public testnet. First-time wallet sync processes the full event history and can take significantly longer than subsequent syncs (which restore from cached wallet state). Exact time depends on wallet age, event density, network, and hardware.
-  - `preview` — public preview testnet. Same first-sync trade-off as preprod.
+  - `undeployed` — local network. Use this for dev iteration. On this build it must be a ledger-9 stack the user runs (`mn localnet up` is refused, see the note at the top).
+  - `preprod` — public testnet (ledger 8 today, so refused by this build). First-time wallet sync processes the full event history and can take significantly longer than subsequent syncs (which restore from cached wallet state). Exact time depends on wallet age, event density, network, and hardware.
+  - `preview` — public preview testnet (ledger 8 today, so refused by this build). Same first-sync trade-off as preprod.
 - **Proof server** — local HTTP service that generates ZK proofs for transactions. Default port 6300. Version must match the network's ledger version or writes fail with "Custom error 170".
 
 ## Intent routing (natural language → tool)
@@ -34,13 +36,13 @@ Manage wallets, check balances, transfer NIGHT tokens, register dust (fee token)
 | "Fund this address …" (localnet only) | `midnight_airdrop({ amount: "1000", wallet: "mn_addr_undeployed1…" })` — `wallet` accepts a name, path, or raw bech32m address |
 | "Register dust" / "I need fees" | `midnight_dust_register()` |
 | "Am I registered for dust?" | `midnight_dust_status()` |
-| "Start localnet" / "start a local network" | `midnight_localnet_up()` |
+| "Start localnet" / "start a local network" | Explain that `midnight_localnet_up()` is refused on this ledger-9 build; the user runs a ledger-9 stack and points mn at it (see the note at the top) |
 | "Stop localnet" | `midnight_localnet_stop()` |
 
 ## Canonical flows
 
 ### New user, first session (localnet)
-1. `midnight_localnet_up()` — spin up Docker network.
+1. Make sure a ledger-9 stack is running and reachable (see the note at the top); `midnight_localnet_up()` won't start one on this build.
 2. `midnight_wallet_generate({ name: "alice" })` — create wallet, set active.
 3. `midnight_airdrop({ amount: "1000" })` — fund from genesis.
 4. `midnight_dust_register()` — make wallet able to pay fees.
@@ -77,10 +79,14 @@ Use `midnight_contract_*` MCP tools (or `mn contract` CLI). Flow: `compact compi
 
 Plain strings, booleans, fractional numbers, and `null` pass through unchanged. No hex-string detection — `"1234"` stays a string.
 
-**Compatibility caveat — runtime version skew.** Contracts must be compiled with the current Compact toolchain. The CLI bundles `@midnight-ntwrk/compact-runtime` `^0.16.0`, so contracts have to target runtime `0.16.0`. Pre-compiled artifacts built for an older runtime (e.g. `0.15.0`) are rejected at deploy/call with a clear message like `CompactError: Version mismatch: compiled code expects 0.15.0`. The fix is to recompile against the current runtime — run `compact compile` (or `mn dev`, which auto-compiles on save) rather than asking the user to downgrade `mn`. `midnight_contract_inspect` shows the compiled `runtimeVersion` so you can flag the mismatch before attempting deploy.
+**Compatibility caveat — runtime version skew.** Contracts must be compiled with Compact 0.35 (language 0.27). The CLI bundles `@midnight-ntwrk/compact-runtime` `0.20.0`, so contracts have to target runtime `0.20.0`. Artifacts built for another runtime (e.g. `0.16.0`, from a ledger-8 toolchain) are rejected at deploy/call with a message like `CompactError: Version mismatch: compiled code expects 0.16.0`. The fix is to recompile with Compact 0.35 (`compact compile`) rather than asking the user to change `mn`; a contract that must stay on the ledger-8 toolchain belongs with `midnight-wallet-cli` 0.5.x. `midnight_contract_inspect` shows the compiled `runtimeVersion` so you can flag the mismatch before attempting deploy.
 
 **Stale MCP server.** Every MCP response carries `_serverVersion`. If the user upgraded `midnight-wallet-cli` but `_serverVersion` lags `mn --version`, the MCP client is talking to a long-lived stale process. Tell them to disconnect and re-add the MCP server (a /mcp reconnect alone will not respawn it).
 
+### Agent needs a fee wallet for its own dApp transactions
+
+When an agent builds and proves its own ledger-9 transaction (its own value already balanced) and only needs the Dust fee paid, the user runs `mn serve --approve-fees` (CLI only, not an MCP tool). In that mode `balanceUnsealedTransaction` / `balanceSealedTransaction` add only Dust, and are auto-approved only when the transaction spends none of the wallet's funds, has no unsigned unshielded input, needs no non-Dust value, and is not a rewards claim; otherwise they are refused with every reason listed. `submitTransaction` is auto-approved only for a transaction that server balanced that way on the same connection. Everything else still prompts the user (and is rejected without a terminal). `--approve-fees` cannot be combined with `--approve-all`. Two limits bound what an agent can cost the wallet: `--max-fee <DUST>` refuses a transaction whose total Dust fee (the agent's transaction plus the wallet's balancing) is higher (default 10 DUST; a simple contract call costs about 0.5), and `--max-pending <n>` refuses new balances while n balanced transactions wait to be submitted (default 2). Both are checked before any Dust is reserved. Each balanced transaction reserves a whole Dust coin until it is submitted and on chain (about 20 seconds on a 6-second-block localnet) or released, so a fee wallet serves as many agents at once as it has Dust coins: one per NIGHT UTXO registered for Dust generation. A request that finds none free waits for one, then fails with an error saying so. With `--json`, the line `mn serve` prints once it is listening includes the approval policy (`"approval": {"reads": "auto", "balancing": "fee-only", "writes": "fee-only", "feeLimits": {"maxFeeSpecks": "10000000000000000", "maxPending": 2}}`), so whoever started it can check what it will approve.
+
 ### User wants to scaffold tests for a contract
 Use `midnight_test_create({ path, strategy })`. Strategies:
 - `"cli"` (default) — emits `dapp.test.json` + `tests/suites/cli-default/{suite,actions,assertions}.json` with deploy → state → one call per impure circuit → state. Placeholder args; user reviews and edits before `mn test run`.
@@ -110,7 +116,11 @@ Every MCP tool error returns `{ error: true, code: <ERROR_CODE>, message: <human
 | `PROOF_FAILURE` | Proof server rejected or failed to generate the ZK proof. Often a stale commitment tree or unreachable proof server. | Check `midnight_status()`; if proof server healthy, `midnight_cache_clear({ wallet: "<name>" })` then retry. |
 | `PROOF_TIMEOUT` | ZK proof generation didn't finish within the deadline. | Retry — proofs can be slow under load. |
 | `SYNC_TIMEOUT` | Long-running wallet sync hit its deadline. Common on a hosted-network first-cold-sync. | Retry; the cache resumes from the last applied event so progress is preserved. |
-| `NETWORK_ERROR` | Indexer/node/proof-server connection refused or DNS failure. | Check `midnight_status()`; if localnet, `midnight_localnet_up()`. |
+| `NETWORK_ERROR` | Indexer/node/proof-server connection refused or DNS failure. | Check `midnight_localnet_status()` or the endpoints the user configured; on this build `midnight_localnet_up()` is refused, so ask the user to start their ledger-9 stack. |
+| `UNSUPPORTED_LEDGER` | The network is on ledger 8; this build supports ledger 9 only. | Tell the user: this network needs midnight-wallet-cli 0.5.x. Don't retry. |
+| `LOCALNET_UNAVAILABLE` | `midnight_localnet_up()` can't start a ledger-9 stack on this build. | Ask the user to start their ledger-9 stack and point mn at it (endpoint config). |
+| `LOCAL_STACK_UNREACHABLE` | No ledger-9 stack answers at the configured endpoints. | Ask the user to start their stack or fix the configured node / indexer-ws / proof-server endpoints. |
+| `AMBIGUOUS_LOCAL_STACKS` | Several local Midnight stacks are running and no endpoints are configured, so mn won't guess. | Ask the user which stack to use; they set its endpoints with `midnight config set`. Don't retry blindly. |
 | `WALLET_NOT_FOUND` | Named wallet doesn't exist on disk. | `midnight_wallet_list()` — user may have removed it. |
 | `INVALID_ARGS` | Missing/invalid argument. | Show the message to the user verbatim — it names the missing field. |
 | `TX_REJECTED` | Chain rejected the submitted transaction (catch-all when no more specific code applies). | Read the message; usually a state mismatch resolved by re-sync + retry. |
@@ -119,15 +129,15 @@ Every MCP tool error returns `{ error: true, code: <ERROR_CODE>, message: <human
 
 ## When to use which network
 
-- **Developing a contract?** → `undeployed` (localnet). No first-sync cost; everything is local.
-- **Integration testing against a hosted chain?** → `preprod`. First sync for a new wallet on this network processes full event history; subsequent syncs restore from cache and are much faster.
+- **Developing a contract?** → `undeployed` (a ledger-9 stack the user runs locally). No first-sync cost; everything is local.
+- **Integration testing against a hosted chain?** → `preprod`, once it runs ledger 9 (refused while it is on ledger 8). First sync for a new wallet on this network processes full event history; subsequent syncs restore from cache and are much faster.
 - **Demoing to users?** → `preview` (if the dApp is deployed there) or `undeployed` (if self-contained).
 - **Mainnet?** → not on this CLI yet. Don't claim it is.
 
 ## What this CLI is NOT
 
 - Not a custody service. Keys are on the user's disk (`~/.midnight/wallets/<name>.json`).
-- Not an instant-sync tool for a first-time wallet on a hosted network. First run replays the chain's event history; the CLI caches state after that so repeat runs are fast. Dust priming specifically uses a bundled native accelerator (~5× faster than the WASM fallback — set `MN_DISABLE_NATIVE_DUST=1` to force WASM), but a cold prime is still minutes, not seconds.
+- Not an instant-sync tool for a first-time wallet on a hosted network. First run replays the chain's event history; the CLI caches state after that so repeat runs are fast. On this ledger-9 build dust priming always runs in WASM (the native accelerator is built for ledger 8 and is not used), so a cold prime takes minutes, not seconds.
 - Not a contract compiler. The project's `package.json` should expose a `compact` script (Midnight convention, e.g. `"compact": "compact compile src/foo.compact src/managed/foo"`) or a `compile` script as a generic fallback. `mn dev` detects whichever is present; create-mn-app and midnight-starship templates ship with the `compact` script already wired.
 
 ## Authoritative references

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midnight-wallet-cli",
-  "version": "0.5.2",
+  "version": "0.6.0-rc.0",
   "type": "module",
   "description": "Git-style CLI wallet for the Midnight blockchain",
   "license": "Apache-2.0",
@@ -36,6 +36,7 @@
   "files": [
     "dist",
     "docs/SKILL.md",
+    "docs/SKILL-CORE.md",
     "NOTICE"
   ],
   "engines": {
@@ -53,25 +54,21 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@midnight-ntwrk/compact-runtime": "^0.16.0",
-    "@midnight-ntwrk/dapp-connector-api": "^4.0.1",
+    "@midnight-ntwrk/compact-runtime": "0.20.0",
     "@midnight-ntwrk/ledger-v8": "^8.1.0",
-    "@midnight-ntwrk/midnight-js-contracts": "^4.1.1",
-    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "^4.1.1",
-    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "^4.1.1",
-    "@midnight-ntwrk/midnight-js-level-private-state-provider": "^4.1.1",
-    "@midnight-ntwrk/midnight-js-network-id": "^4.1.1",
-    "@midnight-ntwrk/midnight-js-node-zk-config-provider": "^4.1.1",
-    "@midnight-ntwrk/midnight-js-types": "^4.1.1",
-    "@midnight-ntwrk/midnight-js-utils": "^4.1.1",
-    "@midnight-ntwrk/wallet-sdk-abstractions": "^2.0.0",
-    "@midnight-ntwrk/wallet-sdk-address-format": "^3.1.0",
-    "@midnight-ntwrk/wallet-sdk-capabilities": "^3.2.0",
-    "@midnight-ntwrk/wallet-sdk-dust-wallet": "^4.0.0",
-    "@midnight-ntwrk/wallet-sdk-facade": "^4.0.0",
-    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.1",
-    "@midnight-ntwrk/wallet-sdk-shielded": "^3.0.0",
-    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "^3.0.0",
+    "@midnight-ntwrk/midnight-js-contracts": "5.0.0-rc.1",
+    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "5.0.0-rc.1",
+    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "5.0.0-rc.1",
+    "@midnight-ntwrk/midnight-js-level-private-state-provider": "5.0.0-rc.1",
+    "@midnight-ntwrk/midnight-js-network-id": "5.0.0-rc.1",
+    "@midnight-ntwrk/midnight-js-node-zk-config-provider": "5.0.0-rc.1",
+    "@midnight-ntwrk/midnight-js-protocol": "5.0.0-rc.1",
+    "@midnight-ntwrk/midnight-js-types": "5.0.0-rc.1",
+    "@midnight-ntwrk/midnight-js-utils": "5.0.0-rc.1",
+    "@midnightntwrk/dapp-connector-api": "4.1.0-beta.1",
+    "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
+    "@midnightntwrk/onchain-runtime-v4": "4.0.0-rc.3",
+    "@midnightntwrk/wallet-sdk": "2.0.0-rc.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@scure/bip39": "^2.0.1",
     "rxjs": "^7.8.1",
@@ -83,12 +80,5 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
-  },
-  "optionalDependencies": {
-    "@nel349/dust-sync-darwin-arm64": "0.5.2",
-    "@nel349/dust-sync-darwin-x64": "0.5.2",
-    "@nel349/dust-sync-linux-x64": "0.5.2",
-    "@nel349/dust-sync-linux-arm64": "0.5.2",
-    "@nel349/dust-sync-win32-x64": "0.5.2"
   }
 }