Guide for Integrators

This guide outlines the key steps and requirements for integrators, such as exchanges, who want to set up and operate a Proof-of-Stake (PoS) node for the Nimiq blockchain.

Node Types and Requirements

Available Node Types

Stores all transactions since genesis but does not permanently retain all block data. Transactions are never pruned and remain retrievable by their hash and block number.

Best for: Exchanges and services requiring full transaction history

Hardware Requirements

Component	History Node	Full Node	Light Node
Memory	16GB+ RAM	8GB+ RAM	1GB RAM
CPU	4-8 vCPUs	4-8 vCPUs	64-bit
Storage	Growing with chain	80-160GB	Minimal
Network	High-speed + SSD	High-speed + SSD	1 Mbps+
Sync Time	Increases over time	Linear growth	Few seconds

Storage Requirements

History nodes need increasing storage as the blockchain grows. Full nodes maintain a fixed window of data.

JSON-RPC Interface

Key Methods

// Get transaction details
await rpc.getTransactionByHash(txHash)
 
// Get address transactions
await rpc.getTransactionHashesByAddress(address)
 
// Get current block height
await rpc.getBlockNumber()
 
// Check node sync status
await rpc.isConsensusEstablished()
 
// Create and send transaction
await rpc.createBasicTransaction({
  from: sender,
  to: recipient,
  value: amount
})

Transaction Creation

All create*Transaction methods have equivalent send*Transaction versions for immediate broadcasting.

Node Setup Guide

Configuration File

The client.toml configuration requires these key settings:

[network]
seed_nodes = [
  "/dns4/aurora.seed.nimiq.com/tcp/443/wss",
  # ...more seed nodes...
]
 
[consensus]
network = "main-albatross"  # or "test-albatross"
sync_mode = "history"       # or "full"

Docker Setup (Recommended)

# Create data directory
mkdir ~/data
 
# Pull latest image
docker pull ghcr.io/nimiq/core-rs-albatross:latest
 
# Run container
docker run -v $(pwd)/data:/home/nimiq/.nimiq \
  -p 8443:8443 -p 8648:8648 -p 9100:9100 \
  --name nimiq-rpc --rm \
  ghcr.io/nimiq/core-rs-albatross:latest

Source Build

# Install dependencies
apt update && apt install clang cmake libssl-dev pkg-config
 
# Build client
cargo build --release --bin nimiq-client
 
# Run client
cargo run --release --bin nimiq-client

Important Properties

Network Parameters

Parameter	Value
Block Time	1 second
TPS	~700
Epoch Length	~12 hours
Tx Window	~2 hours
Finality	Next macro block

Transaction Validity

Transactions must be included within the 2-hour validity window or they become invalid.