midnight-wallet-cli 0.5.7 → 0.5.8

package/docs/SKILL-CORE.md

@@ -0,0 +1,47 @@
+# 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.
+
+## 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" | `midnight_localnet_up()` |
+| "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`.
+
+## Slow first call on preprod and preview
+
+The first call that needs a wallet's Dust on a hosted network (dust register, transfer, contract deploy or call) reads the chain's Dust history first: about 5 minutes on `preprod`, about 30 seconds on `preview`, once per wallet and network. Later calls take seconds. Tell the user before that first call, allow it that long, and don't cancel and retry. If it takes far longer, the CLI's native Dust reader is not in use: fetch `midnight-wallet://skill/full` and read "First sync on a hosted network".
+
+## 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

@@ -15,14 +15,28 @@ Manage wallets, check balances, transfer NIGHT tokens, register dust (fee token)
 - **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. Its indexer and node are served by Blockfrost and need the user's own project id (see "Preprod needs a Blockfrost project id" below). 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.
+  - `preprod` — public testnet. Its indexer and node are served by Blockfrost and need the user's own project id (see "Preprod needs a Blockfrost project id" below). The first call that needs the wallet's Dust reads the chain's whole Dust history: about 5 minutes, once per wallet (see "First sync on a hosted network" below).
+  - `preview` — public preview testnet. No project id needed. Same first sync, about 30 seconds.
 - **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".
 
 ### Preprod needs a Blockfrost project id
 
 Midnight shut its own preprod indexer down on 2026-10-09. Blockfrost serves preprod's indexer and node now, and every request needs the user's own project id (created at https://blockfrost.io, one project per network; preprod ids start with `nightpreprod`; requests count against the user's Blockfrost plan). The user sets it once with `midnight config set blockfrost-project-id <project id>` in their own terminal, or `BLOCKFROST_PROJECT_ID` (or `MN_BLOCKFROST_PROJECT_ID`) in the MCP server's environment. It is a secret: `midnight_config_get` shows it masked, no tool result contains it, and you should never ask for it in chat or echo it. Preview and the local network need none.
 
+### First sync on a hosted network
+
+The first call that needs a wallet's Dust on `preprod` or `preview` (`midnight_dust_register`, `midnight_dust_status` of a registered wallet, `midnight_transfer`, any contract deploy or call, `mn serve`, `mn dust export`) reads the chain's whole Dust event history before it does anything else. It happens once per wallet and network; later calls resume from a cache and take seconds. A balance of an empty wallet does not trigger it.
+
+| Network | Dust events (2026-10-11) | First sync, native reader | First sync, WASM reader | Later calls |
+|---|---|---|---|---|
+| `preprod` | 1.6M | about 5 min | about 27 min (estimated) | about 6 s |
+| `preview` | 144k | about 30 s | about 2 min | about 10 s |
+
+- **Tell the user before the first such call** how long it will take, and allow the tool call that long. Don't cancel and retry: an interrupted sync resumes from its last checkpoint, so nothing is lost, but nothing is gained either.
+- **The native reader** is the `dust-sync` sidecar: an optional npm package for the platform (`@nel349/dust-sync-<os>-<arch>`; macOS arm64/x64, Linux x64/arm64 on glibc, Windows x64) that installs with the CLI and needs no setup. Without it the CLI reads with its built-in WASM reader: same result, several times slower.
+- **How to tell which reader ran** (CLI): add `--verbose`. Each sync logs `dust: native sidecar: <path>`, or `dust: native sidecar <reason>, using WASM`. On a long sync the CLI also prints one line on stderr without `--verbose`: `Native Dust reader <reason>: reading with the built-in one, several times slower on a long sync.`
+- **If the native reader is not in use**, the reason is one of: `not installed` (npm ran with `--omit=optional`, or the platform has no build), `can't start on this system` (Alpine or another musl Linux: the Linux builds need glibc), `disabled by MN_DISABLE_NATIVE_DUST=1`, or `failed` (a run error; the CLI carries on in WASM). Fixes for the user to run: reinstall without omitting optional dependencies (`npm install -g midnight-wallet-cli`), or use a glibc container image (`node:22-slim`, not `node:22-alpine`). Don't set `MN_DISABLE_NATIVE_DUST` yourself.
+
 ## Intent routing (natural language → tool)
 
 | User says | Call this tool |
@@ -90,7 +104,7 @@ 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`.
 - `"browser"` — additionally needs `port` and `build-cmd`; emits `prompt.md` instead of `actions.json`. Claude drives the UI per `prompt.md`.
 
-Run via `midnight_test_run` (CLI: `mn test run --suite <name>`). Browser strategy supports `browserMode: "vision"` (screenshots — default), `"dom"` (accessibility tree, faster, requires `chrome-devtools-mcp`), `"script"` (direct JS, fastest, requires `chrome-devtools-mcp`). Pre-flight detects missing `chrome-devtools-mcp` and orphan automation Chromes from prior crashes.
+Running a suite is a CLI command, not an MCP tool: `mn test run --suite <name>` (exit code 0 on PASS, 1 on FAIL; `--json` prints the result, `mn test results` shows the last one). Its prep steps start the localnet if it is down, fund the active wallet, register Dust and wait until there is enough of it to pay for a transaction (about a minute and a half on a new chain), then start `mn serve`. Browser strategy supports `browserMode: "vision"` (screenshots — default), `"dom"` (accessibility tree, faster, requires `chrome-devtools-mcp`), `"script"` (direct JS, fastest, requires `chrome-devtools-mcp`). Pre-flight detects missing `chrome-devtools-mcp` and orphan automation Chromes from prior crashes.
 
 ## Safety rules (non-negotiable)
 
@@ -111,10 +125,10 @@ Every MCP tool error returns `{ error: true, code: <ERROR_CODE>, message: <human
 | `INVALID_DUST_PROOF` | Chain rejected the dust spend proof as malformed (substrate "Custom error 170"). Stale commitment tree. | `midnight_cache_clear({ wallet: "<name>" })` then retry. |
 | `STALE_CACHE` | Local wallet cache disagrees with chain (e.g. localnet reset, remote testnet re-indexed). | `midnight_cache_clear({ wallet: "<name>" })` then retry. |
 | `STALE_UTXO` | UTXO was already spent on-chain (substrate "error code 115"). | Re-sync (the next call will refresh state) and retry. |
-| `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_FAILURE` | Proof server rejected or failed to generate the ZK proof. Often a stale commitment tree or unreachable proof server. | Check that the proof server is running (on localnet: `midnight_localnet_status()`); if it is, `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()`. |
+| `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. If first syncs take far longer than the times in "First sync on a hosted network", the native Dust reader is not in use: see that section. |
+| `NETWORK_ERROR` | Indexer/node/proof-server connection refused or DNS failure. | On localnet: `midnight_localnet_status()`, then `midnight_localnet_up()` if it is down. On a hosted network: retry once, then show the message to the user. |
 | `BLOCKFROST_PROJECT_ID_REQUIRED` | The network (preprod) is served by Blockfrost and no project id is set. | Ask the user to create a Midnight preprod project at https://blockfrost.io and run `midnight config set blockfrost-project-id <project id>` themselves. Never ask them to paste the id into the chat. Don't retry until they have. |
 | `BLOCKFROST_PROJECT_ID_REJECTED` | Blockfrost refused the project id (HTTP 403): mistyped, revoked, or for another network. | Ask the user to check it at blockfrost.io and set it again. Don't retry blindly. |
 | `BLOCKFROST_LIMIT_REACHED` | Blockfrost's plan limit or rate limit. | Wait and retry once; if it persists, tell the user it is their Blockfrost plan. |
@@ -128,14 +142,14 @@ 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.
+- **Integration testing against a hosted chain?** → `preprod` (needs a Blockfrost project id; first Dust sync about 5 minutes) or `preview` (no project id; about 30 seconds). Later syncs restore from cache and take seconds.
 - **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. The first call that needs the wallet's Dust reads the chain's Dust history (about 5 minutes on preprod, 30 seconds on preview, with the native reader that installs with the CLI); the CLI caches state after that so later calls take seconds. See "First sync on a hosted network".
 - 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.7",
+  "version": "0.5.8",
   "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": {
@@ -88,10 +89,10 @@
     "vitest": "^3.2.4"
   },
   "optionalDependencies": {
-    "@nel349/dust-sync-darwin-arm64": "0.5.7",
-    "@nel349/dust-sync-darwin-x64": "0.5.7",
-    "@nel349/dust-sync-linux-x64": "0.5.7",
-    "@nel349/dust-sync-linux-arm64": "0.5.7",
-    "@nel349/dust-sync-win32-x64": "0.5.7"
+    "@nel349/dust-sync-darwin-arm64": "0.5.8",
+    "@nel349/dust-sync-darwin-x64": "0.5.8",
+    "@nel349/dust-sync-linux-x64": "0.5.8",
+    "@nel349/dust-sync-linux-arm64": "0.5.8",
+    "@nel349/dust-sync-win32-x64": "0.5.8"
   }
 }