Command line

nulld is one binary with subcommands: run starts a node, the wallet commands open a wallet file and talk to a running node, and a few tools cover keys and test faucets. This page lists every subcommand and flag of release v0.1.8.

Usage: nulld <COMMAND>

Commands:
  run                 Run a node
  status              Print a node's status line
  keygen              Generate a seed phrase, spending key and address
  create              Create an encrypted wallet file
  address             Show the default address of a wallet
  export-viewing-key  Print a wallet's full viewing key
  balance             Scan the chain through a node and show the balance
  send                Pay an address through a node
  consolidate         Merge available notes into larger notes
  faucet              Serve a faucet
  genesis-coinbase    Build a genesis coinbase transaction
  help                Print help for a command

Conventions

The only global flags are -h, --help and -V, --version. Every subcommand also takes --help.

  • Network. Commands that take --network accept main or test and default to main. Commands that talk to a node learn the network from its genesis block.
  • Amounts are in smallest units: 1 NULL is 100000000.
  • Secrets can come from the environment instead of the command line, so they stay out of shell history and process lists:
VariableUsed for
NULL_WALLET_PASSPHRASEthe wallet passphrase; prompted when unset (twice when creating)
NULL_SEED_PHRASEthe seed phrase for create --phrase; prompted without echo when unset
NULL_RPC_TOKENthe node token, for --rpc-token
NULL_WALLET_RPC_TOKENthe wallet daemon token, for null-wallet-rpc --token

Wallet flags

Commands that open a wallet take one of:

  • Name
    --wallet
    Type
    path
    Description

    Encrypted wallet file, created with nulld create or the desktop wallet. The passphrase is read from NULL_WALLET_PASSPHRASE or prompted.

  • Name
    --sk
    Type
    hex
    Description

    A spending key, kept in memory for this command only. The wallet scans from genesis every time. Conflicts with --wallet.

Close the desktop wallet or null-wallet-rpc before opening its wallet file: only one process can open it at a time.

Node connection flags

Commands that talk to a node take:

  • Name
    --rpc
    Type
    host:port
    Description

    The node's control socket. Default 127.0.0.1:18444.

  • Name
    --rpc-token
    Type
    string
    Description

    The node's token. Also read from NULL_RPC_TOKEN. Conflicts with --rpc-token-file.

  • Name
    --rpc-token-file
    Type
    path
    Description

    File holding the token, such as rpc.token in the node's data directory.

One of the token flags (or NULL_RPC_TOKEN) is required.

Node

nulld run

Runs a node until Ctrl-C or SIGTERM. With no flags it joins mainnet through the seed nodes, stores the chain in the default data directory and opens the control socket on 127.0.0.1:18444. See Run a node for a walk-through.

  • Name
    --network
    Type
    main | test
    Description

    Network to join. Default main.

  • Name
    --datadir
    Type
    path
    Description

    Directory for chain.redb, rpc.token and peers.dat. Defaults to <user data>/<network>/chain, the chain the desktop wallet uses.

  • Name
    --in-memory
    Type
    flag
    Description

    Keep the chain in memory only. Conflicts with --datadir.

  • Name
    --listen
    Type
    ip:port
    Description

    Accept peers on this address, for example 0.0.0.0:19000. Without it the node connects out only.

  • Name
    --advertise
    Type
    ip:port
    Description

    Public endpoint to announce, for a forwarded port behind NAT. Requires --listen; conflicts with --proxy and --i2p.

  • Name
    --connect
    Type
    host:port
    Description

    Peer to connect to. Repeatable.

  • Name
    --seed
    Type
    host:port
    Description

    Extra bootstrap peer, in addition to the network's seeds. Repeatable.

  • Name
    --proxy
    Type
    ip:port
    Description

    SOCKS5 proxy for every outbound connection, for example Tor at 127.0.0.1:9050. .onion names then work in --connect.

  • Name
    --i2p
    Type
    ip:port
    Description

    I2P SAM bridge for .i2p peers. The bare flag uses 127.0.0.1:7656.

  • Name
    --mine
    Type
    address
    Description

    Mine to this address.

  • Name
    --mining-threads
    Type
    integer
    Description

    Miner worker threads. Default 1. Ignored without --mine.

  • Name
    --rpc
    Type
    ip:port
    Description

    Control socket address. Default 127.0.0.1:18444.

  • Name
    --rpc-http
    Type
    ip:port
    Description

    Serve JSON-RPC 2.0 over HTTP here, behind the same token (Authorization: Bearer). Off by default.

  • Name
    --rpc-token
    Type
    string
    Description

    Token to demand. Also read from NULL_RPC_TOKEN. Generated when omitted. Either way it is written to rpc.token in the data directory.

  • Name
    --metrics
    Type
    ip:port
    Description

    Serve Prometheus metrics at GET /metrics. Unauthenticated; off by default.

  • Name
    --blocknotify
    Type
    command
    Description

    Shell command to run on every new main-chain tip; %s is replaced by the block hash.

  • Name
    --log-level
    Type
    debug | info | warn | error
    Description

    Log threshold. Default info.

  • Name
    --log-file
    Type
    path
    Description

    Also append log lines to this file, dated in UTC and without colors. Not rotated.

Public node

nulld run \
  --listen 0.0.0.0:19000 \
  --rpc-http 127.0.0.1:18446 \
  --metrics 127.0.0.1:9100

Over Tor

nulld run --proxy 127.0.0.1:9050 \
  --connect <hostname>.onion:19000

Local test node

nulld run --network test --in-memory \
  --listen 127.0.0.1:19000 --mine tnull1...

nulld status

Prints the node's status line from the control socket: tip height and hash, peer count, mempool size, blocks mined since start and how many of them are in the main chain, and whether it is syncing.

Takes the node connection flags.

Example

nulld status \
  --rpc-token-file ~/.local/share/null/main/chain/rpc.token

Output

ok height=6206 hash=00000fc8d37f816b... peers=8 mempool=0 mined=0 in_chain=0 syncing=false

Wallet

The wallet commands need a running node for anything that reads the chain. create, address and export-viewing-key work offline.

nulld create

Creates an encrypted wallet file. With no key flag it generates a new 24-word seed phrase, prints it once with the default address, and asks for a passphrase twice. Write the phrase down: it restores the wallet on any machine.

  • Name
    --wallet
    Type
    path
    Description

    Wallet file to create. Required.

  • Name
    --phrase
    Type
    flag
    Description

    Restore from a seed phrase, read from NULL_SEED_PHRASE or a hidden prompt.

  • Name
    --account
    Type
    integer
    Description

    Account of the seed phrase to use. Default 0. Conflicts with --sk.

  • Name
    --sk
    Type
    hex
    Description

    Import a spending key instead. Conflicts with --phrase.

  • Name
    --viewing-key
    Type
    string
    Description

    Create a watch-only wallet from a full viewing key (nullview1...). It sees deposits and spends but cannot sign. Conflicts with --sk and --phrase.

  • Name
    --network
    Type
    main | test
    Description

    Network the wallet is for. Default main.

New wallet

nulld create --wallet main.wallet

Restore

nulld create --wallet restored.wallet --phrase

Watch-only

nulld create --wallet watch.wallet \
  --viewing-key nullview1...

Output

seed_phrase: word1 word2 ... word24
write the seed phrase down; it restores this wallet on any machine
address: null1...

nulld address

Prints the wallet's default address.

Takes the wallet flags and --network (default main).

Example

nulld address --wallet main.wallet

nulld export-viewing-key

Prints the wallet's full viewing key, nullview1... on mainnet. Use it with create --viewing-key to make a watch-only wallet on another machine. The key reveals every incoming and outgoing payment of the wallet; treat it as sensitive.

Takes the wallet flags and --network (default main).

Example

nulld export-viewing-key --wallet main.wallet

nulld balance

Scans the chain through a node and prints each unspent note and the total balance. A wallet file keeps its scan state, so later runs only scan new blocks, and it rolls back by itself if the node's chain reorganized.

Takes the wallet flags and the node connection flags.

  • Name
    --light
    Type
    flag
    Description

    Scan compact blocks instead of full ones. Faster; memos are not recovered, but balance and witnesses are the same.

Example

nulld balance --wallet main.wallet \
  --rpc-token-file ~/.local/share/null/main/chain/rpc.token

Output

note at height 5120 position 10422: 970000000
scanned to height 6206, balance 970000000

nulld send

Syncs the wallet, builds and proves a payment, and submits it through the node. Proving takes a few seconds. Prints the transaction id.

Takes the wallet flags and the node connection flags.

  • Name
    --to
    Type
    address
    Description

    Recipient address. Must belong to the node's network. Required.

  • Name
    --amount
    Type
    integer
    Description

    Amount in smallest units. Required. The fee is added on top.

  • Name
    --light
    Type
    flag
    Description

    Scan compact blocks instead of full ones.

Send 1 NULL

nulld send --wallet main.wallet \
  --to null1... --amount 100000000 \
  --rpc-token-file ~/.local/share/null/main/chain/rpc.token

Output

submitted <txid>

nulld consolidate

Merges small notes, such as mining rewards, into larger notes at the wallet's main (index 0) address. Fewer, larger notes keep later payments in a small action class and so lower their fee. Each consolidation transaction combines up to sixteen inputs.

The command first prints a quote: input count, transaction count, destination address and total fee. Without --dry-run it then queues the transactions with that fee as the maximum, prints each operation's status, and fails if one failed. Run balance afterwards to see the new notes confirm; for a large wallet, repeat once they have confirmed.

Takes the wallet flags and the node connection flags. Close the desktop wallet or wallet daemon before opening its file.

  • Name
    --dry-run
    Type
    flag
    Description

    Only print the quote; send nothing.

  • Name
    --min-confirmations
    Type
    integer
    Description

    Minimum confirmations an input needs. Default 1.

  • Name
    --light
    Type
    flag
    Description

    Scan compact blocks instead of full ones.

Preview

nulld consolidate --wallet main.wallet --dry-run \
  --rpc-token-file ~/.local/share/null/main/chain/rpc.token

Consolidate

nulld consolidate --wallet main.wallet \
  --min-confirmations 10 \
  --rpc-token-file ~/.local/share/null/main/chain/rpc.token

The same operation is available in the desktop wallet and as the quoteconsolidation and consolidate methods of the wallet RPC.

Mining

Mining is part of nulld run; there is no separate mining command. The relevant flags:

FlagPurpose
--mine <address>mine to this address
--mining-threads <n>worker threads, default 1; each needs about 1.8 GB of memory on mainnet
--blocknotify <command>run a command on each new tip, for pools
--metrics <ip:port>exposes null_mining_ready and null_blocks_mined

On mainnet the node hands out no work until it has a peer and has caught up; the log says mining waits: ... and later mining resumes. See Mining for solo mining and the pool guide for pools.

nulld run --mine null1... --mining-threads 4

Tools

nulld keygen

Generates a new seed phrase and prints it with its account 0 spending key and default address, without writing a file. The output is secret; anyone with it controls the funds.

  • Name
    --network
    Type
    main | test
    Description

    Network to write the address for. Default main.

Example

nulld keygen

Output

seed_phrase: word1 word2 ... word24
spending_key: <64 hex characters>
address: null1...

nulld faucet

Serves a faucet over HTTP: GET /pay/<address> sends a fixed amount from the wallet. It pays each address at most once an hour and each client at most once every ten minutes. Put a TLS reverse proxy in front of it. Intended for test networks.

Takes the wallet flags and the node connection flags.

  • Name
    --listen
    Type
    ip:port
    Description

    Address to serve HTTP on. Default 127.0.0.1:8080.

  • Name
    --amount
    Type
    integer
    Description

    Amount per request in smallest units. Default 100000000 (1 coin).

Example

NULL_WALLET_PASSPHRASE=... nulld faucet \
  --wallet faucet.wallet \
  --rpc-token-file /var/lib/null/rpc.token \
  --listen 127.0.0.1:8080 --amount 100000000

nulld genesis-coinbase

Builds a genesis coinbase transaction paying the premine to an address and writes its bytes to a file. Only relevant when creating a new network: every run produces a new transaction and so a new genesis hash. Node operators never need it.

  • Name
    --address
    Type
    address
    Description

    Address that receives the premine. Required.

  • Name
    --out
    Type
    path
    Description

    Where to write the encoded transaction. Required.

  • Name
    --network
    Type
    main | test
    Description

    Network the coinbase is for. Default main.

Example

nulld genesis-coinbase --network test \
  --address tnull1... --out genesis.tx

Other binaries

null-wallet-rpc

The wallet daemon. It opens one wallet, syncs it from a node and serves the wallet JSON-RPC methods documented in Wallet methods. With no flags it opens the default mainnet wallet and finds the default node's token by itself.

FlagDefaultPurpose
--wallet <path><user data>/<network>/wallet.redbwallet file
--network <main or test>mainnetwork the wallet is for
--node <host:port>127.0.0.1:18444the node's control socket
--node-token <token>node token; also NULL_RPC_TOKEN
--node-token-file <path><user data>/<network>/chain/rpc.tokenfile holding the node token
--listen <ip:port>127.0.0.1:18447address for the wallet JSON-RPC
--token <token>generatedtoken the wallet JSON-RPC demands; also NULL_WALLET_RPC_TOKEN. Written to wallet-rpc.token next to the wallet file when generated
--sync-interval <seconds>2seconds between syncs from the node
--lightoffscan compact blocks: faster, no memos
--log-level <level>infodebug, info, warn or error
--log-file <path>also append log lines to this file
NULL_WALLET_PASSPHRASE=... null-wallet-rpc --wallet exchange.wallet

null-desktop

The desktop wallet, with an embedded node. It needs no flags for ordinary use; these override null.conf for one launch:

FlagPurpose
--network <main or test>network; a new installation defaults to main
--datadir <path>application data directory
--conf <path>configuration file; default null.conf in the data directory
--wallet <path>advanced override for the wallet file
--connect <host:port>bootstrap peer; repeatable
--listen <ip:port>accept peers on this address
--advertise <ip:port>public endpoint to announce behind NAT
--rpc <ip:port>combined RPC listener, loopback only; default 127.0.0.1:18448
--proxy <ip:port>SOCKS5 proxy for outbound peer connections