DUST Registration CLI

CLI tool to register a Midnight DUST address from a Cardano wallet.

Prerequisites

• Node.js v24+
• A Blockfrost API key (blockfrost.io)

Setup

cd cli
npm install

Environment Variables

Variable	Required	Description
NETWORK	Yes	Cardano network: Preview, Preprod, or Mainnet
BLOCKFROST_API_KEY	Yes	Blockfrost project ID for the selected network

Create a .env file or export directly:

export NETWORK=Preview
export BLOCKFROST_API_KEY=previewXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Commands

Create a new Cardano wallet

node src/index.ts create-cardano-wallet --name my-wallet

Generates a 24-word mnemonic and derives the wallet address.

Import an existing Cardano wallet

node src/index.ts import-cardano-wallet --name my-wallet --mnemonic "word1 word2 ... word24"

Create a Midnight wallet

node src/index.ts create-midnight-wallet --name my-midnight

Generates a random seed and derives the DUST address.

List wallets

# List all wallets
node src/index.ts list-wallets

# Show first 10 CIP-1852 payment addresses for a specific wallet
node src/index.ts list-wallets --cardano-wallet my-wallet --n 10

# Show staking addresses instead
node src/index.ts list-wallets --cardano-wallet my-wallet --n 10 --stake

--n controls how many account indices to derive (default: 10).

Find UTxOs

# Single account (default: account 0)
node src/index.ts find-utxos --wallet my-wallet

# Query first 3 accounts with per-account breakdown
node src/index.ts find-utxos --wallet my-wallet --n 3

Queries Blockfrost for UTxOs including cNIGHT tokens. With --n, shows balances per account and a grand total.

Build registration transaction

# Using a stored Midnight wallet
node src/index.ts build-tx --cardano-wallet my-wallet --midnight-wallet my-midnight --account 0

# Using a DUST address directly
node src/index.ts build-tx --cardano-wallet my-wallet --dust-address dust1abc123... --account 0

Builds an unsigned transaction that mints a DUST NFT and creates the registration datum on-chain. --account selects the CIP-1852 account index, which determines the payment address and stake key used.

The DUST address can be provided in two ways (mutually exclusive):

• --midnight-wallet <name> — loads the DUST address from a stored Midnight wallet
• --dust-address <address> — accepts a bech32m dust1... address directly

Sign transaction

node src/index.ts sign-tx --wallet my-wallet --tx-file ~/.dust-cli/temp/unsigned-tx-xxx.json --account 0

The --account must match the account used during build-tx. A mismatch is rejected with an error.

Submit transaction

node src/index.ts submit-tx --tx-file ~/.dust-cli/temp/signed-tx-xxx.json --account 0 --poll

The --account must match the account used during build-tx/sign-tx. The --poll flag waits for on-chain confirmation.

Check registration status

node src/index.ts check-registration --wallet my-wallet --account 0

Queries the Midnight indexer for the DUST registration status of the staking address derived from the given account. Shows registration state, DUST address, NIGHT balance, generation rate, and current capacity.

Wallet Storage

Wallet files are stored in ~/.dust-cli/:

~/.dust-cli/
  cardano-wallets/   # Cardano wallet JSON files (contain mnemonics)
  midnight-wallets/  # Midnight wallet JSON files (contain seeds)
  temp/              # Unsigned/signed transaction files

Build transaction

Transaction structure

The CLI builds the exact same transaction as the dApp's buildRegistrationTransaction in src/lib/dustTransactionsUtils.ts, using Lucid Evolution:

1. Inputs — all cNIGHT UTxOs from the wallet are collected as explicit inputs (token rotation)
2. Mint — 1 DUST NFT minted via the cnight_generates_dust PlutusV3 minting policy with a Create redeemer (constructor 0)
3. Output — sent to the validator address with an inline DustMappingDatum containing:

• c_wallet: VerificationKey([stakeKeyHash]) — the wallet's stake key hash (28 bytes)
• dust_address: the Midnight DUST address bytes (SCALE-encoded BLS scalar, 33 bytes)

4. Required signers — both the payment address and the stake/reward address
5. Output value — 1,586,080 lovelace + 1 DUST NFT

Contract data (hardcoded, extracted from dApp)

Item	Source
Script CBOR (PlutusV3)	src/config/contract_blueprint.ts — identical bytecode for testnet and mainnet
DustMappingDatum type	`{ c_wallet: VerificationKey([stakeKeyHash])
DustAction redeemer	Create (constructor 0) / Burn (constructor 1)
Policy ID	Hash of the PlutusV3 script
Validator address	Derived from the script via addressFromValidator
LOVELACE_FOR_REGISTRATION	1,586,080 lovelace

cNIGHT token identifiers per network

Network	Policy ID	Encoded Name
Preview	d2dbff622e509dda256fedbd31ef6e9fd98ed49ad91d5c0e07f68af1	4e49474854 ("NIGHT")
Preprod	d2dbff622e509dda256fedbd31ef6e9fd98ed49ad91d5c0e07f68af1	4e49474854 ("NIGHT")
Mainnet	0691b2fecca1ac4f53cb6dfb00b7013e561d1f34403b957cbb5af1fa	4e49474854 ("NIGHT")