Documentation

Run. Mine. Build.

Everything you need to run a Dilithium node, mine DLT, or build with CUDA-accelerated GPU mining.

Wallet Nodes CPU Mining GPU Mining Pool Mining CLI Reference API

Overview

Dilithium ships as a set of standalone binaries. Download the ones you need for your platform from GitHub Releases and make them executable.

Binary	Purpose	Requires Node?
dilithium	Full node — validates blocks, relays transactions, serves the API	Is the node
dilithium-cli	Wallet management, send transactions, check balances	Connects to a node API
dilithium-miner	CPU miner with multi-threading	Embeds one automatically
dilithium-gpu-miner	Rust+CUDA GPU miner (recommended for GPU mining)	Connects to a node
dilithium-cpu-gpu-miner	Go hybrid CPU/GPU miner (pre-built runs CPU, build with CUDA for GPU)	Embeds one automatically

Make binaries executable (macOS / Linux)

$chmod +x dilithium*

Create a Wallet

Generate a quantum-safe CRYSTALS-Dilithium keypair with a 24-word recovery phrase. Your address is derived from the public key and used to receive mining rewards and DLT transfers.

Create a new wallet (generates 24-word recovery phrase)

$./dilithium-cli init

Restore a wallet from recovery phrase

$./dilithium-cli wallet restore

View your address

$./dilithium-cli address

Check your balance

$./dilithium-cli balance

Important: When you create a wallet, a 24-word recovery phrase is displayed once. Write it down and store it safely — it is the only way to restore your wallet. You can optionally set a passphrase to encrypt the private key on disk.

Desktop wallet: The dilithium-wallet GUI app provides the same seed phrase creation and restore flow with a graphical interface.

PWA wallet: A progressive web app is also available at wallet.dilithiumcoin.com — use it from any browser to create wallets, check balances, and send DLT without installing anything.

Running a Node

Nodes form the backbone of the Dilithium network. They validate transactions, relay blocks, and serve the REST API. You can run a standalone node or let a miner start an embedded one automatically.

Standalone Node

Run a full node to support the network. It connects to seed nodes automatically and syncs the blockchain.

Start a node

$./dilithium --port 1701 --api-port 8001

Start a node with auto-mining

$./dilithium --port 1701 --api-port 8001 --auto-mine --miner YOUR_ADDRESS

Connect to a specific peer

$./dilithium --port 1701 --api-port 8001 --connect 192.168.1.10:1701

Embedded Node (via Miner)

Both dilithium-miner and dilithium-cpu-gpu-miner automatically start an embedded node when you don't specify --node. Just place the dilithium binary in the same directory as the miner.

$./dilithium-miner --miner YOUR_ADDRESS

External Node

Point any miner at an existing node's API. Useful when you want to run the node and miner separately, or mine against a remote node.

Miner connecting to local node

$./dilithium-miner --node http://localhost:8001 --miner YOUR_ADDRESS

GPU miner connecting to remote node

$./dilithium-gpu-miner --node http://your-node:8001 --address YOUR_ADDRESS

Node Flags

Flag	Default	Description
--port	1701	P2P port for peer connections
--api-port	8001	HTTP API port
--connect	—	Peer address to connect to (e.g., 192.168.1.10:1701)
--auto-mine	false	Mine blocks automatically
--miner	—	Wallet address for mining rewards
--data-dir	—	Data directory path
--no-seeds	false	Don't connect to seed nodes (for local testing)

CPU Mining

The standard miner uses multi-threaded SHA-256 proof-of-work on your CPU. It automatically starts an embedded node unless you point it at an existing one.

Quick Start

Solo mine (embedded node, auto-detect wallet)

$./dilithium-miner --miner YOUR_ADDRESS

Multi-threaded (use 8 CPU threads)

$./dilithium-miner --miner YOUR_ADDRESS --threads 8

Mine against an existing node

$./dilithium-miner --node http://localhost:8001 --miner YOUR_ADDRESS --no-node

Miner Flags

Flag	Default	Description
--miner	—	Wallet address for mining rewards
--node	(embedded)	Node API URL
--no-node	false	Disable embedded node (requires --node)
--threads	1	Number of mining threads
--wallet	~/.dilithium/wallet	Wallet directory for auto-detection

GPU Mining

GPU mining uses NVIDIA CUDA for massively parallel SHA-256 hashing — up to 100x faster than CPU mining. The Rust+CUDA miner is recommended for maximum performance.

Rust+CUDA Miner (Recommended)

The dilithium-gpu-miner is a dedicated Rust+CUDA GPU miner for maximum hashrate. Requires Rust and the CUDA Toolkit.

Build from source

$cd cmd/dilithium-gpu-miner && cargo build --release

Run

$./dilithium-gpu-miner --address YOUR_ADDRESS --node http://localhost:8001

Select GPU device and batch size

$./dilithium-gpu-miner --address YOUR_ADDRESS --device 0 --batch-size 134217728

Alternative: Go CPU/GPU Hybrid Miner

The dilithium-cpu-gpu-miner runs in optimized CPU mode out of the box. For GPU acceleration, copy cmd/dilithium-cpu-gpu-miner/ to your GPU machine and build with CUDA.

CPU mode (pre-built binary)

$./dilithium-cpu-gpu-miner --address YOUR_ADDRESS

Build with CUDA

$cd cmd/dilithium-cpu-gpu-miner && make gpu SM=86

Run with GPU acceleration

$./dilithium-cpu-gpu-miner --gpu --address YOUR_ADDRESS

CUDA SM Architecture

Set SM= to match your GPU generation. Find yours with: nvidia-smi --query-gpu=compute_cap --format=csv

SM	Generation	Example GPUs
75	Turing	RTX 2060, 2070, 2080
80	Ampere	A100, RTX 3090 (desktop)
86	Ampere	RTX 3060, 3070, 3080 (laptop)
89	Ada Lovelace	RTX 4060, 4070, 4080, 4090
90	Hopper	H100, H200

Performance

Hardware	Mode	Hashrate
Apple M4 (10 threads)	CPU	~180 MH/s
Intel i7 (8 threads)	CPU	~80 MH/s
RTX 3080	GPU	~1,400 MH/s
RTX 4090	GPU	~5,000 MH/s

Run ./dilithium-cpu-gpu-miner --benchmark to measure your CPU hardware.

CPU/GPU Miner Flags

Flag	Default	Description
--address	auto-detect	Mining reward address
--wallet	~/.dilithium/wallet	Wallet directory for auto-detection
--node	(embedded)	Node API URL
--no-node	false	Disable embedded node (requires --node)
--peer	—	Seed peer for embedded node
--threads	all CPUs	CPU mining thread count
--gpu	false	Enable NVIDIA GPU mining (requires CUDA build)
--device	0	GPU device ID
--batch-size	67108864	Nonces per GPU kernel launch
--pool	—	Pool address (host:port)
--benchmark	false	Run hashrate benchmark and exit

Troubleshooting: “GPU mining not available” means the binary was built without CUDA — rebuild with make gpu. “No kernel image available” means SM architecture mismatch — rebuild with the correct SM= value.

Pool Mining

Pool mining combines hashpower from multiple miners for more consistent rewards. Supported by both the CPU miner and GPU miner.

Connect to a Pool

CPU pool mining

$./dilithium-cpu-gpu-miner --pool pool.example.com:3333 --address YOUR_ADDRESS

GPU pool mining

$./dilithium-cpu-gpu-miner --pool pool.example.com:3333 --address YOUR_ADDRESS --gpu

CLI Reference

The dilithium-cli tool manages wallets and submits transactions.

Command	Description
dilithium-cli init	Create a new wallet with 24-word recovery phrase
dilithium-cli wallet restore	Restore wallet from a recovery phrase
dilithium-cli wallet info	Display wallet details
dilithium-cli wallet export	Export wallet private key
dilithium-cli address	Show your wallet address
dilithium-cli balance	Check wallet balance
dilithium-cli send --to <addr> --amount N	Send DLT to an address
dilithium-cli send --to <addr> --amount N --fee F	Send DLT with a custom fee (min: 0.0001 DLT)
dilithium-cli tx sign [flags]	Sign a transaction
dilithium-cli status	Show node status
dilithium-cli peers	List connected peers
dilithium-cli mempool	View pending transactions

REST API

Every node exposes an HTTP API for querying the blockchain, submitting transactions, and managing peers.

Method	Endpoint	Description
GET	/status	Node status, height, difficulty, hashrate
GET	/chain	Full blockchain (paginated with ?limit=N&page=P)
GET	/stats	Explorer statistics: height, difficulty, hashrate, supply, mempool, peers
GET	/block?index=N	Single block details by index
GET	/explorer/address?addr=ADDR	Address balance, transaction history
GET	/peers	Connected peers
GET	/mempool	Pending transactions
POST	/transaction	Submit a signed transaction (supports optional fee field)
POST	/mine?miner=ADDR	Manually mine a block
POST	/add-peer?address=IP:PORT	Connect to a peer

Check node status

$curl http://localhost:8001/status

Explorer stats (hashrate, supply, etc.)

$curl http://localhost:8001/stats

Look up an address

$curl http://localhost:8001/explorer/address?addr=YOUR_ADDRESS

Get a specific block

$curl http://localhost:8001/block?index=100

Send with fee

$./dilithium-cli send --to <address> --amount 10 --fee 0.0001

View mempool

$curl http://localhost:8001/mempool