Skip to main content
Version: v1

Wallet SDK v2.0.0 release notes

For the complete documentation index, see llms.txt
  • Version: v2.0.0
  • Date: 2026-11-05
  • Environment: Mainnet, Preview

High-level summary​

Wallet SDK 2.0.0 is the major release for the ledger 9 network upgrade. Wallet SDK 1.x can't transact on Mainnet after the upgrade, so every Mainnet wallet and DApp needs 2.0.0 and indexer 4.4.101.

Wallet SDK 2 runs ledger 8 before the upgrade and ledger 9 from it, so balances, coins, and history carry across the switch. Preview was reset on 6 November 2026 as a new chain that runs ledger 9, so wallets on Preview also need 2.0.0 and a fresh sync. Preprod stays on ledger 8 until a later upgrade. For Preprod, keep using wallet SDK 1.2.0.

Audience​

This release is relevant for developers who:

  • Build or maintain a wallet for Mainnet or Preview
  • Use the wallet SDK in a DApp, a backend service, or tests on Mainnet or Preview

What changed (Summary of updates)​

  • Runs @midnightntwrk/ledger-v8 below the chain's forks.v9 and @midnightntwrk/ledger-v9 from it. The default fork version is 2000000, the value a 2.x node reports. FacadeState.protocol reports Crossing while the wallets catch up and Settled once they're on one ledger.
  • Tags each transaction with its protocol version and refuses a mismatch with ProtocolVersionMismatchError.
  • Fails a transaction if the chain changes version while it proves the transaction, and releases the coins it reserved.
  • Adds configuration for the upgrade and for proving:
    • forks: { v9 } sets the protocol version from which the wallets read ledger 9. Leave it out to use the default.
    • provers: { v8?, v9 } names a proving backend per ledger version, each { kind: 'server', url } or { kind: 'wasm' }. Or set one proof server for both with provingServerUrl.
  • FacadeState.isSynced and waitForSyncedState() also wait until the indexer's reported tip is checked against a node's finalized head, and keep waiting while the indexer is behind or on another network.
  • Adds ./ledger/v8 and ./ledger/v9 subpaths for applications that build their own transactions.
  • Every Midnight package the SDK depends on installs from the public npm registry, without credentials.

Breaking changes or required actions​

The @midnightntwrk/wallet-sdk-facade 5.0.0 release notes carry the full migration guide.

  • Start wallets and the facade from seeds or from each ledger version's keys. For example, facade.start(WalletSeeds.fromMasterSeed(masterSeed)) replaces facade.start(shieldedSecretKeys, dustSecretKey).
  • Methods that build transactions, such as transferTransaction, initSwap, and the balance*Transaction methods, no longer take a secretKeys argument.
  • Transactions are WalletTransaction handles that carry the protocol version they were built for. If you build your own transactions, import the ledger from ./ledger/v8 or ./ledger/v9 and seal them with WalletTransaction.adopt.
  • Signers are asynchronous (SignSegment), and keys and signatures are tagged { tag, value } objects.
  • FacadeState.lifecycle and facade.transactionLifecycleService replace FacadeState.pending and the pending-transactions service.
  • Roles.Metadata is now Roles.EcdsaUnshielded.
  • ledger-v8 now comes from @midnightntwrk/ledger-v8. If your application builds ledger 8 objects and passes them to the wallet, import them from @midnightntwrk/ledger-v8 too. The wallet doesn't accept objects from @midnight-ntwrk/ledger-v8.
  • Package versions move together: wallet-sdk 2.0.0 uses wallet-sdk-facade 5.0.0, wallet-sdk-shielded 4.0.0, wallet-sdk-unshielded-wallet 4.0.0, and wallet-sdk-dust-wallet 5.0.0.

DUST after the upgrade​

The upgrade resets DUST state once, at the switch to ledger 9. NIGHT balances are untouched.

On Mainnet, every DUST registration is backed by cNIGHT. The network replays these registrations automatically after the switch, straight to their full DUST cap, so Mainnet users don't need to do anything. While the replay runs, transactions that users submit wait in the transaction pool and are included once it ends. On a recent Mainnet snapshot, the replay takes about 48 blocks, under five minutes. It ends with a DustReapplyCompleted event.

Wallets show the replayed DUST only on wallet SDK 2.0.0 with indexer 4.4.101, which reports DUST capacity correctly.

Preview has no replay. It was reset as a new chain, so the old DUST registrations are gone. On Preview, request tNIGHT from the faucet again and register it for DUST again.

The protocol token bridge from cNIGHT to mNIGHT ships with ledger 9 but stays off until governance enables it, and its rollout will be announced separately. The replay covers cNIGHT-backed registrations only, and Mainnet holds no mNIGHT at the upgrade. NIGHT bridged to mNIGHT later needs its own DUST registration with registerNightUtxosForDustGeneration.

Fee floor​

Ledger 9 introduces an explicit fee floor, min_block_price, set by the ledger parameters. It takes effect from the first block after the upgrade, so fees rise slightly. If your wallet or DApp estimates fees itself, update the estimate to respect the floor before the upgrade.

Known issues​

The 2.0.0 release notes list no known issues. For network known issues that affect wallets after the upgrade, such as fees paid with a single DUST spend, see the ledger 9 upgrade page.