Skip to main content
Version: v1

Wallet SDK v3.0.0 release notes

For the complete documentation index, see llms.txt
  • Version: v3.0.0
  • Date: 20 March, 2026
  • Environment: Mainnet, Preprod, Preview

High-level summary​

This release focuses on accurate fee estimation and developer ergonomics. Fee calculation is now split into a context-free calculateFee and a wallet-aware estimateFee that accounts for available coins and balancing transaction cost. The SDK is updated to ledger v8. It also introduces fetchTermsAndConditions for retrieving network Terms and Conditions before initialization, and a promise-based QueryRunner for developers not using Effect.

Audience​

This release is relevant for developers who:

  • Build wallets for the Midnight Network
  • Integrate Midnight token transfers into their DApps
  • Need to manage shielded (private) and unshielded token balances
  • Implement atomic swaps between parties

What changed (Summary of updates)​

This release refines fee behavior and improves developer workflows while aligning the SDK with ledger v8. The updates below summarize API additions and security-focused handling changes across wallet implementations.

  • Fee calculation now uses two APIs: calculateFee for a transaction in isolation, and estimateFee for the fee the current wallet would pay including balancing costs.
  • Updated to ledger v8 across the SDK.
  • New WalletFacade.fetchTermsAndConditions() static method for retrieving network Terms and Conditions.
  • New QueryRunner.runPromise() utility for executing GraphQL queries as plain Promises.
  • SecretKeysResource in shielded and DUST wallets now clears keys from memory after use.
  • Shielded wallet now clears pending coins on transaction failure.
  • Improved error messages for invalid transaction submission and balancing failures.

New features​

Below is a detailed breakdown of the new features added in this release.

Terms and conditions retrieval​

This release adds static method WalletFacade.fetchTermsAndConditions(configuration), which retrieves the current Terms and Conditions (URL and SHA-256 hash) from the network indexer. You can call it before or independently of wallet initialization. It accepts any configuration that includes indexerClientConnection.indexerHttpUrl, so you can pass shared wallet configuration directly.

Promise-based query runner​

This release introduces QueryRunner.runPromise() in @midnight-ntwrk/wallet-sdk-indexer-client, which executes GraphQL queries as plain Promises without Effect boilerplate. It takes a query, variables, and server config, and returns a Promise<R>.

New features requiring configuration updates​

No configuration updates are required to access the new features in this release.

Improvements​

This release also includes quality and reliability improvements across wallet components.

  • Node client (@midnight-ntwrk/wallet-sdk-node-client) now returns clearer error messages when transaction submission fails due to an invalid transaction
  • DUST wallet reports more descriptive error messages when balancing fails
  • SecretKeysResource in shielded and DUST wallets securely clears cryptographic keys from memory after use, instead of only nullifying the reference

Deprecations​

This release does not introduce any deprecations.

Breaking changes​

This release includes several API and behavior changes that require migration.

Ledger v8​

The SDK is updated to Ledger v8 compatibility across all packages. Developers must upgrade their Ledger dependency to v8.

Dynamic fee calculation (@midnight-ntwrk/wallet-sdk-facade, @midnight-ntwrk/wallet-sdk-dust-wallet)​

The previous calculateFee method attempted to estimate total wallet fee, but could not account for wallet coin availability or balancing transaction cost. In v3.0.0, fee computation is split into two methods:

  • calculateFee: Computes fee for a transaction in isolation. It does not consider wallet coin set or balancing transaction cost.
  • estimateFee: Computes the realistic total fee the current wallet would pay, including coin availability and balancing transaction cost. This method requires secret key and wallet state, and throws InsufficientFundsError when the wallet cannot cover the fee.

Wallet facade migration:

// Before (v2.0.0) - single method
const fee = await wallet.calculateTransactionFee(tx);

// After (v3.0.0) - two methods

// Fee for the transaction only (no balancing costs, no wallet context):
const txFee = await wallet.calculateTransactionFee(tx);

// Total fee the wallet would actually pay (includes balancing tx, wallet-aware):
const totalFee = await wallet.estimateTransactionFee(tx, secretKey, {
  ttl: new Date(/* ... */), // optional
  currentTime: new Date(), // optional
});

DUST wallet API migration:

// Before - single calculateFee
const fee = await dustWallet.calculateFee(transactions);

// After
// Transaction fee only (context-free):
const txOnlyFee = await dustWallet.calculateFee(transactions);

// Total fee the wallet would pay (wallet-aware, may throw InsufficientFundsError):
const totalFee = await dustWallet.estimateFee(secretKey, transactions, ttl, currentTime);

CoinSelection type change (@midnight-ntwrk/wallet-sdk-dust-wallet)​

CoinSelection has changed from a target-based multi-coin selection function to a simpler single-coin selection function.

// Before - returned multiple coins summed to a target
type CoinSelection<T> = (coins: readonly CoinWithValue<T>[], target: bigint) => CoinWithValue<T>[];

// After - returns a single coin (smallest available) or undefined
type CoinSelection<T> = (coins: readonly CoinWithValue<T>[]) => CoinWithValue<T> | undefined;

InsufficientFundsError (@midnight-ntwrk/wallet-sdk-dust-wallet)​

This release adds a new error type thrown by estimateFee when the wallet cannot cover fee requirements. It includes message and tokenType fields.

import { InsufficientFundsError } from '@midnight-ntwrk/wallet-sdk-dust-wallet';

Known issues​

This section lists known issues with this release of the Wallet SDK.

Transaction history not implemented for shielded and DUST wallets​

The shielded and DUST wallets do not track transaction history. The shielded wallet transaction history getter throws "not yet implemented". Only the unshielded wallet maintains transaction records.

Packages​

PackageVersionDescription
@midnight-ntwrk/wallet-sdk-facade3.0.0Unified API orchestrating shielded, unshielded, and DUST wallets. Fee calculation split into calculateFee and estimateFee. Terms and Conditions retrieval added.
@midnight-ntwrk/wallet-sdk-unshielded-wallet2.1.0Manages NIGHT and other unshielded tokens. Updated to ledger v8.
@midnight-ntwrk/wallet-sdk-shielded2.1.0Manages privacy-preserving shielded tokens. Updated to ledger v8. Securely clears secret keys from memory.
@midnight-ntwrk/wallet-sdk-dust-wallet3.0.0Manages DUST for transaction fees. Dynamic fee calculation, InsufficientFundsError, and improved balancing error messages.
@midnight-ntwrk/wallet-sdk-capabilities3.2.0Shared wallet features including ProvingService, SubmissionService, and PendingTransactionsService. Updated to ledger v8.
@midnight-ntwrk/wallet-sdk-abstractions2.0.0Core interfaces and domain types. Includes shared SyncProgress and SerializedTransaction.
@midnight-ntwrk/wallet-sdk-prover-client1.2.0Interfaces with the prover service. Updated to ledger v8.
@midnight-ntwrk/wallet-sdk-indexer-client1.2.0Queries the Midnight indexer via GraphQL. Adds Terms and Conditions query, QueryRunner.runPromise(), and ledger v8 updates.
@midnight-ntwrk/wallet-sdk-address-format3.1.0Encodes and decodes Midnight addresses using Bech32m format. Updated to ledger v8.
@midnight-ntwrk/wallet-sdk-hd3.0.1Derives cryptographic keys from a seed following BIP-32/BIP-44/CIP-1852.
@midnight-ntwrk/wallet-sdk-node-client1.1.0Communicates with Midnight nodes. Improved invalid transaction error messages and ledger v8 support.
@midnight-ntwrk/wallet-sdk-utilities1.1.0Common utilities. Dev-only dependencies cleaned up and ledger v8 support added.
@midnight-ntwrk/wallet-sdk-runtime1.0.2Orchestrates wallet lifecycle and state management.

Fixed defect list​

This release includes the following defect fixes:

  • Shielded wallet now correctly clears pending coins when a transaction fails; previously, pending coins were not released on failure, which could reduce available balances until restart
  • SecretKeysResource in shielded and DUST wallets now securely clears cryptographic keys from memory after use, instead of only nullifying the reference
  • Node client returns clearer error messages when transaction submission fails due to an invalid transaction
  • DUST wallet reports more descriptive error messages when balancing fails
  • Dev-only dependencies moved out of production dependencies in @midnight-ntwrk/wallet-sdk-utilities