| name | midnight-wallet:wallet-sdk |
| description | This skill should be used when the user asks about the Midnight Wallet SDK packages (@midnight-ntwrk/wallet-sdk-*), how to construct a wallet with WalletFacade, HD key derivation from seeds or mnemonics, the three-wallet architecture (shielded, unshielded, dust), observing wallet state and sync progress, transaction balancing and signing, proving and submission services, connecting to infrastructure (indexer client, node client, prover client), or Bech32m address formatting. Also covers ProtocolVersion, SyncProgress, FacadeState, and the wallet runtime |
Wallet SDK Reference
Reference for the @midnight-ntwrk/wallet-sdk-* packages.
Critical caveat — verify SDK is current
Patterns in this skill were verified against the package versions pinned
in midnight-wallet:sdk-regression-check/versions.lock.json. The
Midnight Network ecosystem moves quickly, and there may be breaking
changes between SDK versions. Run midnight-wallet:sdk-regression-check
before trusting any pattern here.
Scope — browser wallets are out of scope
This skill is the package-level reference for the wallet SDK
(@midnight-ntwrk/wallet-sdk-*), used in programmatic contexts where
the script owns the keys directly. If the user is integrating their
DApp with a browser extension wallet (Lace or other), load
midnight-dapp-dev:dapp-connector instead.
Quick Start: Wallet Construction
The most common task is constructing a WalletFacade from a seed. The flow is:
Seed (64 hex chars)
→ HDWallet.fromSeed() → selectAccount(0) → selectRoles() → deriveKeysAt(0)
→ ShieldedWallet (Zswap role)
→ UnshieldedWallet (NightExternal role)
→ DustWallet (Dust role)
→ WalletFacade.init({ shielded, unshielded, dust, configuration })
Key packages involved:
| Package | What it provides |
|---|
@midnight-ntwrk/wallet-sdk-hd | HDWallet, Roles, generateRandomSeed |
@midnight-ntwrk/wallet-sdk-facade | WalletFacade — unified API |
@midnight-ntwrk/wallet-sdk-shielded | ShieldedWallet factory |
@midnight-ntwrk/wallet-sdk-unshielded-wallet | UnshieldedWallet factory, createKeystore, PublicKey |
@midnight-ntwrk/wallet-sdk-dust-wallet | DustWallet factory |
For the full construction code, see examples/basic-wallet-setup.ts.
For configuration details, see references/wallet-construction.md.
Deep Dive References
| Task | Reference |
|---|
| Look up a package name, import path, or key type | references/quick-reference.md |
| Generate keys from a seed or mnemonic | references/key-derivation.md |
| Construct and configure a WalletFacade | references/wallet-construction.md |
| Read wallet state, balances, or sync progress | references/state-and-balances.md |
| Create, balance, sign, prove, or submit a transaction | references/transactions.md |
| Connect to indexer, node, or proof server | references/infrastructure-clients.md |
| Look up the variant/runtime pattern (advanced) | references/variants-and-runtime.md |
| Choose between Promise and Effect APIs | references/effect-and-promise-apis.md |
| Customize wallet services (balancer, prover, etc.) | references/capabilities-deep-dive.md |
| Resolve runtime errors and exceptions | references/errors-and-troubleshooting.md |
Related Skills
| Need | Skill |
|---|
| DApp browser wallet integration (DApp Connector API) | midnight-dapp-dev:dapp-connector |
| DApp SDK providers (MidnightProviders, WalletProvider) | midnight-dapp-dev:midnight-sdk |
| Testing wallet SDK code | midnight-cq:wallet-testing |
| CLI wallet construction patterns | compact-cli-dev:core |
| Test wallet patterns + runnable examples | midnight-wallet:managing-test-wallets |
| SDK drift detection / smoke test | midnight-wallet:sdk-regression-check |
