| name | midnight-wallet:managing-test-wallets |
| description | This skill should be used when the user asks to create a test wallet, fund a wallet, get tNight from a faucet, register DUST, monitor wallet balance, transfer NIGHT or shielded tokens, derive a wallet from a seed or BIP-39 mnemonic, set up wallets for tests, watch an address for incoming funds, generate dust, fund their DApp's test fixtures, or run end-to-end test scenarios that need real wallets on the local devnet or a public testnet. |
Managing Test Wallets
SDK-driven patterns for creating, funding, and managing Midnight test
wallets. Network-aware (undeployed / preprod / preview).
Critical caveat — verify SDK is current
Every pattern here was 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.
Before using any pattern from this skill, run
midnight-wallet:sdk-regression-check (drift check). If a major
version has shifted, run the smoke test before trusting the patterns.
Scope — browser wallets are out of scope
Browser wallets (Lace and other extensions) are out of scope for this
skill. This skill teaches programmatic wallet patterns where the script
owns the keys directly. If the user is integrating their DApp with a
browser extension wallet, load midnight-dapp-dev:dapp-connector
instead. The two skills are complementary: a DApp typically uses the
extension wallet in production and uses the patterns in this skill for
development and test wallets.
When to use this skill
| Scenario | Pattern |
|---|
| Wiring wallet setup into an example DApp's startup or tests | Lift the relevant examples/*.ts block, adapt to the host project's config and pin SDK versions in its package.json |
| One-off: user asks for a funded test wallet, balance check, transfer, etc. | Write a throwaway script in /tmp/ or the project's scripts/, run with npx tsx, report results |
Read this first — three-address model
A WalletFacade owns three sub-wallets, each with its own address and
balance. Faucets and the genesis-seed airdrop fund the UNSHIELDED
address only. See references/addresses-and-tokens.md.
Decision tree
| User wants… | Reference | Example |
|---|
| Generate a brand-new wallet | wallet-creation.md | create-wallet.ts |
| Restore from BIP-39 mnemonic / hex seed | wallet-creation.md | create-wallet.ts |
| Fund on local devnet | funding.md | fund-wallet-undeployed.ts |
| Fund on preprod or preview | funding.md | fund-wallet-public-faucet.ts |
| Register DUST | dust-registration.md | register-dust.ts |
| Watch balance changes | balance-monitoring.md | monitor-wallet.ts |
| Transfer NIGHT | transfers.md | transfer-night.ts |
| Transfer shielded tokens | transfers.md | transfer-shielded.ts |
| End-to-end (create + fund + dust) | all of the above | full-test-wallet-setup.ts |
References
| Reference | Topic |
|---|
references/addresses-and-tokens.md | Three-address model |
references/wallet-creation.md | Seed sources, HD derivation, construction |
references/funding.md | Per-network funding strategy |
references/dust-registration.md | DUST mechanics + registration |
references/balance-monitoring.md | State subscription patterns |
references/transfers.md | Three transfer kinds |
references/network-config.md | DefaultConfiguration per network |
references/troubleshooting.md | Common symptoms |
Examples
| Example | Demonstrates |
|---|
examples/create-wallet.ts | Wallet construction (random, mnemonic, hex seed) |
examples/fund-wallet-undeployed.ts | Genesis-seed airdrop on local devnet |
examples/fund-wallet-public-faucet.ts | Print-and-wait pattern for testnets |
examples/register-dust.ts | DUST registration |
examples/monitor-wallet.ts | Live balance ticker |
examples/transfer-night.ts | Unshielded NIGHT transfer |
examples/transfer-shielded.ts | Shielded transfer |
examples/full-test-wallet-setup.ts | End-to-end |
Related skills
| Need | Skill |
|---|
| Wallet SDK package reference | midnight-wallet:wallet-sdk |
| SDK drift detection / smoke test | midnight-wallet:sdk-regression-check |
| Local devnet management | midnight-tooling:devnet |
| Genesis seed for local devnet | midnight-tooling:devnet#genesis-seed |
| Browser wallet (Lace) integration | midnight-dapp-dev:dapp-connector |
| DApp SDK provider wiring | midnight-dapp-dev:midnight-sdk |
| Testing wallet SDK code | midnight-cq:wallet-testing |
