# `wallet-sdk 2.0.1` ## Metadata - **Release type**: patch - Semver delta from `wallet-sdk 2.0.0` - **Date**: 2026-11-16 - **Sister-line note**: This release is on the 2.x line, published under the npm dist-tag `latest`. Integrators who stay on the 1.x line should pin `wallet-sdk 1.2.0` instead. - **Environment**: Mainnet, Preprod, Preview - **Released artifact(s)**: 13 npm packages under the `@midnightntwrk` scope, also mirrored under the deprecated `@midnight-ntwrk` alias scope; see **Artifacts** below - **Component class**: library/SDK - **Upgrade scope**: N/A — library - **Reset required**: N/A — library - **Governance action required**: N/A — library ## High-level summary This patch release moves the SDK to the final `@midnightntwrk/ledger-v9` 1.0.2 and proof server 9.0.2. It fixes a facade that released a submitted transaction's coins and Dust on errors raised after the transaction was in a block, transactions that needed more proofs than a proof server queues, and shielded and Dust wallets that stopped syncing or never reported synced. The in-process prover now proves ZKIR v3 circuits, and the Dust wallet exports `dustWalletProbes`. ## Audience This release is for: - **External integrators** who build wallets on Midnight, move tokens from their DApps, or manage shielded, unshielded and Dust balances. - **Shielded Technologies** engineering teams who maintain the SDK, its test harness or services built on it. ## Dependencies Hard, component-local requirements: - `@midnightntwrk/ledger-v9` is pinned to exactly `1.0.2`, where 2.0.0 accepted `^1.0.0`; `@midnightntwrk/ledger-v8` stays at `^8.1.3`. - The prover client depends on `@midnightntwrk/zkir-v3` `^3.2.1`, whose runtime is loaded only when a ZKIR v3 circuit is proved. - The SDK is tested against proof server 9.0.2 for ledger-v9, node 2.1.101 and indexer 4.4.101. **Downstream impact (cascading effects).** - ledger-v9 from 1.0.1 refuses to price a transaction that repeats a spend, so `estimateFee` and `balanceTransactions` on the V2 variant fail on such input. ([#938](https://github.com/midnightntwrk/midnight-wallet/pull/938)) ## Tested-with versions > Build pins read from the 2.0.1 tag's lockfile, compose files and test containers. Build pins, not QA-verified. | Component | Tested-with version | | -------------------------------------------------------- | ------------------- | | `@midnightntwrk/ledger-v9` | `1.0.2` | | `@midnightntwrk/ledger-v8` | `8.1.3` | | `@midnightntwrk/zkir-v2` | `2.2.0` | | `@midnightntwrk/zkir-v3` | `3.2.1` | | Indexer, `midnightntwrk/indexer-standalone` | `4.4.101` | | Node, `midnightntwrk/midnight-node` | `2.1.101` | | Proof server for ledger-v9, `midnightntwrk/proof-server` | `9.0.2` | | Proof server for ledger-v8, `midnightntwrk/proof-server` | `8.1.0` | ## Deployment information - **Upgrade scope**: N/A — library - **Reset required**: N/A — library - **Governance action required**: N/A — library - **Downtime / coordination**: N/A — library ## Artifacts - `@midnightntwrk/wallet-sdk@2.0.1` — the barrel package, re-exporting every package below except the test harness - `@midnightntwrk/wallet-sdk-facade@5.0.1` — one API over the shielded, unshielded and Dust wallets - `@midnightntwrk/wallet-sdk-shielded@4.0.1` — the shielded wallet - `@midnightntwrk/wallet-sdk-unshielded-wallet@4.0.1` — the unshielded wallet, for Night and other unshielded tokens - `@midnightntwrk/wallet-sdk-dust-wallet@5.1.0` — the Dust wallet, which pays fees - `@midnightntwrk/wallet-sdk-capabilities@4.0.1` — shared proving, balancing, validation, submission, simulation and transaction lifecycle - `@midnightntwrk/wallet-sdk-runtime@2.0.1` — runs a wallet's variants and hands over between them - `@midnightntwrk/wallet-sdk-indexer-client@2.0.1` — the indexer GraphQL client - `@midnightntwrk/wallet-sdk-node-client@2.0.1` — the node RPC client - `@midnightntwrk/wallet-sdk-prover-client@2.0.1` — the proof server client and in-process prover - `@midnightntwrk/wallet-sdk-address-format@4.0.1` — Bech32m address encoding - `@midnightntwrk/wallet-sdk-utilities@1.3.1` — shared utilities and test containers - `@midnightntwrk/wallet-sdk-testkit@1.0.1` — the end-to-end test harness `@midnightntwrk/wallet-sdk-abstractions` `3.0.0` and `@midnightntwrk/wallet-sdk-hd` `4.0.0` are unchanged and were not republished. ## What changed - The SDK runs the final `@midnightntwrk/ledger-v9` 1.0.2 and proof server 9.0.2; ledger-v9's key material is unchanged, at circuit generation 10. ([#946](https://github.com/midnightntwrk/midnight-wallet/pull/946)) - `WalletFacade.submitTransaction` keeps a submitted transaction's coins and Dust booked unless the failure proves no block holds it. ([#925](https://github.com/midnightntwrk/midnight-wallet/pull/925)) - The HTTP prover client holds at most 10 requests at a proof server at once and sends a request again when the proof server's queue is full or it answers 502, 503 or 504. ([#933](https://github.com/midnightntwrk/midnight-wallet/pull/933)) - The in-process prover proves contract circuits compiled with compactc 0.36.0 or later, which emit ZKIR v3 only. ([#928](https://github.com/midnightntwrk/midnight-wallet/pull/928)) - A Dust wallet on the projections sync keeps synchronizing when a pass hands back a coin it already applied. ([#935](https://github.com/midnightntwrk/midnight-wallet/pull/935)) - Restoring a Dust snapshot refuses one holding values the wallet cannot use, with `SnapshotRestoreError` (`invalid-shape`), on both variants. ([#936](https://github.com/midnightntwrk/midnight-wallet/pull/936)) - A shielded wallet on a chain whose zswap commitment tree is still empty reports synced. ([#927](https://github.com/midnightntwrk/midnight-wallet/pull/927)) - `dustWalletProbes(configuration)` is exported, so a composition with its own variants starts its Dust where `DustWallet` would. ([#875](https://github.com/midnightntwrk/midnight-wallet/pull/875)) - The test harness network presets point at their `shielded.tools` hosts. ([#911](https://github.com/midnightntwrk/midnight-wallet/pull/911)) - A test harness wallet lifecycle released with `persist: false` deletes the sync cache snapshots it would have saved. ([#942](https://github.com/midnightntwrk/midnight-wallet/pull/942)) ## New features ### `dustWalletProbes` **Description**: `dustWalletProbes(configuration)` returns the probes `DustWallet` asks before a fresh start, including the search for where the Dust timeline reaches `forks.v9` when `skipLedgerV8DustHistory` is set. A composition with its own variants spreads it into its configuration to start where `DustWallet` would. ### Proof server request cap and retry settings **Description**: The HTTP prover client takes `maxConcurrentRequests`, the most requests it has waiting at a proof server at once (10 by default), and `retrySchedule`, how it waits before sending a request again (1 second, doubling up to 10 seconds, for 5 minutes in all, by default). A wallet sets the cap per proof server backend, with `maxConcurrentRequests` beside `url` in `provers`, and `ServerProvingConfiguration` takes it too; `provingServerUrl` always uses the default. `HttpProverClient.create` and `HttpProverClient.layer` can now also fail with `InvalidMaxConcurrentRequestsError`, when `maxConcurrentRequests` is not a whole number of at least one. A request the proof server has not answered within 10 minutes is given up, which fails the proof. This limit is fixed and matches the proof server's default job timeout. ### Test harness `willRetry` **Description**: Passing `willRetry(context)` as `willRetry` keeps the sync cache snapshots of a failed attempt that vitest will run again, honouring the test's retry `condition`. The dust and token-transfer healthchecks pass it. ## New features requiring configuration updates None ## Improvements ### ledger-v9 1.0.2 and proof server 9.0.2 **Description**: `@midnightntwrk/ledger-v9` moves from the `^1.0.0` range to the final `1.0.2`, run with proof server 9.0.2. The test stacks move to node 2.1.101 and indexer 4.4.101. ### Test harness wallets on networks past the v9 fork **Description**: The test harness's `eventLessDustWallet` takes its probes from `dustWalletProbes`, so it honours `skipLedgerV8DustHistory` as `DustWallet` does. The remote network presets set that flag, so a new wallet on a network that crossed the v9 fork starts its Dust at the boundary instead of replaying the ledger-v8 history; the undeployed environment leaves it off. ### Test harness network presets **Description**: The `devnet` and `qanet` presets use `*..shielded.tools` hosts, which resolve to private addresses and need the VPN. The `preprod` preset moves to `indexer.preprod.shielded.tools` and `rpc.preprod.shielded.tools`, and the `preview` preset is unchanged. Any preset host can be replaced through `createRemoteEnvironment`'s `endpoints` option. ## Deprecations None ## Breaking changes None ## Known issues - [#742](https://github.com/midnightntwrk/midnight-wallet/issues/742): The shielded wallet's sync retry back-off is not capped, so after a long indexer outage the shielded sync can wait far longer than two minutes between attempts. Workaround: restart the wallet once the indexer is back. - [#743](https://github.com/midnightntwrk/midnight-wallet/issues/743): The shielded and Dust wallets are not gated by indexer liveness, and `isConnected` stays `true` while their sync is failing. `FacadeState.isSynced` and `facade.waitForSyncedState()` are gated through the unshielded wallet; a standalone shielded or Dust wallet is not. - [#781](https://github.com/midnightntwrk/midnight-wallet/issues/781): An event-synced Dust snapshot resumes from an indexer database id, so it fails on every retry after the indexer behind its endpoint renumbers its events. Workaround: restore the Dust wallet from its seed, or use the projections Dust sync, which resumes from a block height. - [#893](https://github.com/midnightntwrk/midnight-wallet/issues/893): The Dust wallet prices `feeBlocksMargin` on the proof-erased transaction, so the margin it pays falls short of the configured number of blocks. Workaround: configure a larger `feeBlocksMargin`. - [#885](https://github.com/midnightntwrk/midnight-wallet/issues/885): A sender's shielded transaction-history entry can briefly show no spent coins after a transfer, and can stay that way if the wallet stops between two sync batches. ## Links and references - **QA test coverage / test evidence**: [qa/tests/evidence/2.0.1/README.md](https://github.com/midnightntwrk/midnight-wallet/blob/467ae3bdafba21a79c53c6a6ef3b2edd556c16ec/qa/tests/evidence/2.0.1/README.md) - **PRs**: [Changes since wallet-sdk 2.0.0](https://github.com/midnightntwrk/midnight-wallet/compare/%40midnightntwrk/wallet-sdk%402.0.0...%40midnightntwrk/wallet-sdk%402.0.1) - **Engineering docs**: [Wallet SDK design](https://github.com/midnightntwrk/midnight-wallet/blob/%40midnightntwrk/wallet-sdk%402.0.1/docs/Design.md), [Wallet specification](https://github.com/midnightntwrk/midnight-wallet/blob/%40midnightntwrk/wallet-sdk%402.0.1/docs/spec/Specification.md) - **SDK docs**: [API usage examples](https://github.com/midnightntwrk/midnight-wallet/tree/%40midnightntwrk/wallet-sdk%402.0.1/packages/docs-snippets), [wallet-sdk package README](https://github.com/midnightntwrk/midnight-wallet/blob/%40midnightntwrk/wallet-sdk%402.0.1/packages/wallet-sdk/README.md) - **Known issues board**: [GitHub issues](https://github.com/midnightntwrk/midnight-wallet/issues) ## Fixed defect list The following defects were fixed in `wallet-sdk 2.0.1` since `wallet-sdk 2.0.0`. | Defect number | Description | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [#922](https://github.com/midnightntwrk/midnight-wallet/issues/922) | `submitTransaction` released every booking on any submission error, including errors raised after the transaction was already in a block, so the wallets offered spent coins and Dust until sync caught up. | | [#882](https://github.com/midnightntwrk/midnight-wallet/issues/882) | A transaction with more proofs than a proof server had room for in its queue had the proofs past that refused with `Job Queue full`, which failed the whole transaction. | | [#914](https://github.com/midnightntwrk/midnight-wallet/issues/914) | The in-process prover failed on every contract circuit compiled with compactc 0.36.0 or later, with `expected one of 'ir-source[v2-generic]' or 'ir-source[v2]', got 'ir-source[v3-generic]'`. | | [#646](https://github.com/midnightntwrk/midnight-wallet/issues/646) | A Dust wallet on the projections sync stopped synchronizing when a pass handed back a coin it had already applied. | | [#916](https://github.com/midnightntwrk/midnight-wallet/issues/916) | A Dust snapshot with an out-of-range or malformed value in a `pendingDust` entry restored, and then every sync threw while settling the entry and retried forever. | | [#924](https://github.com/midnightntwrk/midnight-wallet/issues/924) | A shielded wallet on a chain with no zswap events never connected, so `progress.isStrictlyComplete()`, and with it the facade's `isSynced`, never became true. | | — | The test harness qanet preset's indexer subscription named a host that does not serve it, so a wallet restored from a snapshot never connected. | | — | A failed test harness run left behind the sync cache snapshot of each wallet it would have saved, which the next run restored and failed on again. |