@kuiralabs/midnight-wallet

Wallets for the Midnight CLI packages: mn's passphrase and sealed wallet files, seeds and addresses, balances, NIGHT transfers and airdrops, Dust registration, and swap offers. Wallet files live under the state root your host gives, never in ~/.midnight unless that is the root you give.

Install

npm install @kuiralabs/midnight-cli-core @kuiralabs/midnight-wallet @kuiralabs/midnight-engine-rc

Install with npm 11 or older (npm 12 no longer reads a package's shrinkwrap): the engine ships an npm-shrinkwrap.json that pins its SDK set, and npm 11 honours it. A program that runs the SDK installs the engine, @kuiralabs/midnight-engine-rc, for every network. How a program sets up its process for the SDK (the rejection guard, the heap, Ctrl-C, ending) is in core's README.

Entry points

| Import | What it holds | |---|---| | @kuiralabs/midnight-wallet | The functions below, the wallet protector type, and the errors they throw | | @kuiralabs/midnight-wallet/commands | wallet, generate, info, balance, address, genesis-address, airdrop, transfer, dust and cache as one registry entry (walletCommands), swap as another (swapCommands), the wallet's codes (walletCodes) |

Every export and its signature is in api-report.md.

What you call

• createWallet, listWallets, setActiveWallet, unlockWallet, walletAddress: wallet files under your state root.
• readWalletBalance, readAddressBalance: balances, as bigints in each token's smallest unit.
• transferNight, airdropNight: send NIGHT, shielded or not; transferNight to one recipient or to several in one transaction (recipients, at most MAX_TRANSFER_RECIPIENTS), airdropNight on a local network.
• registerDust, readDustStatus, exportDustSnapshot: Dust for fees.
• makeSwapOffer, inspectSwapOffer, takeSwapOffer, cancelSwapOffer, listSwapOffers: swap offers, each paid through a payer you pass.
• establishPassphrase, unlockPassphrase, checkPassphrase: mn's passphrase, asked through your host's prompter or read from MN_PASSPHRASE.

Codes

Each error carries a code, and classifyError(err, registry) gives its code and exit code by that code alone, never by its message. These are the codes this package owns; the rest come from core and the packages below it, each listed in its README.

| Code | Exit | What went wrong | What to do | |------|------|-----------------|------------| | WALLET_NOT_FOUND | 3 | Named wallet doesn't exist on disk. | midnight_wallet_list() — user may have removed it. | | WALLET_ADDRESS_MISMATCH | 2 | A wallet file's saved addresses are not the ones its seed derives: the file was edited or mixed with another wallet's. Nothing was sent. | Don't retry. Ask the user to restore the wallet file from a backup, or the wallet from its mnemonic (midnight wallet generate <name> --mnemonic "..." --force, at their terminal). | | OFFER_TAKEN | 2 | A swap offer's coins are already spent: it was taken, or its maker cancelled it, first (also when the node refuses a take or a cancel for that). | Don't retry. Taking: ask the maker for a new offer. Cancelling: nothing is left to do; mn's record of the offer is closed. |

Mounting its commands

The commands are definitions your program mounts in its own command line, with your state root, settings and notices (core's README explains each part). Its commands name codes the packages it builds on own, so the registry holds their entries too, as mn's does; a registry missing one is refused when it is built. Built on core's example, this one adds the wallet's commands. swap pays through a payer: add swapCommands and pass payer: servePayer from @kuiralabs/midnight-connect in the run:

import { homedir } from 'node:os';
import { join } from 'node:path';
import { classifyError, createHost, createPackageRegistry, parseArgs, runCommand, settingsFromEnvironment, UsageError } from '@kuiralabs/midnight-cli-core';
import { coreCommands } from '@kuiralabs/midnight-cli-core/commands';
import { chainCommands } from '@kuiralabs/midnight-chain/commands';
import { walletCommands } from '@kuiralabs/midnight-wallet/commands';
import { createRcEngine } from '@kuiralabs/midnight-engine-rc';

const registry = createPackageRegistry([coreCommands, chainCommands, walletCommands], []);
const host = createHost({
  paths: { stateRoot: join(homedir(), '.my-app'), home: homedir() },
  settings: () => settingsFromEnvironment(process.env),
  notice: (line) => console.error(line),
  engineLoader: async (_set, host) => createRcEngine(host),
});
const output = { result: (data) => console.log(JSON.stringify(data)), stdout: (text) => process.stdout.write(text), stderr: (text) => process.stderr.write(text) };

const args = parseArgs(process.argv.slice(2));
try {
  const definition = registry.find(args.command ?? '');
  if (definition === undefined) throw new UsageError(`Unknown command: ${args.command}`);
  const outcome = await runCommand(definition, args, { host, output });
  process.exitCode = outcome?.exitCode ?? 0;
} catch (err) {
  const { errorCode, exitCode } = classifyError(err, registry);
  console.error(`${errorCode}: ${err.message}`);
  process.exitCode = exitCode;
}

MN_PASSPHRASE=… node my-cli.mjs wallet generate alice writes ~/.my-app/wallets/alice.json; node my-cli.mjs wallet info bob for a wallet that doesn't exist ends with WALLET_NOT_FOUND and exit code 3. A test in mn runs the block above as it is written.