Node

SnowBlossomNode is the full node: it maintains peer links, downloads and validates every block of the shards it follows, keeps the UTXO trie and the optional indexes, and answers wallets, miners, pools and explorers over gRPC. It holds no funds - only identity keys for TLS and the trust network - so it can safely live on a different machine than the wallet.

Configuration reference

Keys read by the node (all overridable with snowblossom_<key> environment variables, see Configuration):

Example: public mainnet node with indexes

network=snowblossom
log_config_file=configs/logging.properties
db_type=rocksdb
db_path=node_db/mainnet
addr_index=true
tx_index=true
service_port=2338
tls_service_port=2348
tls_key_path=node_db/tls_mainnet
trustnet_key_path=node_db/trustnet

Requirements

• 64-bit JVM, Java 17+ recommended. The Bazel target pins -Xms4g -Xmx4g; when running the jar yourself use at least -Xmx4g. RocksDB uses native memory on top, so plan 6–8 GB for the node.
• Disk: an indexed mainnet database is ~100 GB (2026) and grows with the chain; nothing is pruned. SSD strongly recommended - validation, the UTXO trie and address-history lookups are random-access heavy. The one-time summary rebuild of the 2.0 upgrade needed extra space until compaction ran.
• Network: inbound on the service ports for other peers (optional but good for the network), outbound to peers, DNS seeds, ipv4-lookup.snowblossom.org/ipv6-lookup.snowblossom.org (own IP discovery) and timecheck.snowblossom.org (clock check).
• Clock: NTP. Blocks more than 45 s in the future are rejected; a warning is logged when the clock is off by more than 5 s.

Start-up and what happens inside

1. Registers BouncyCastle, loads the config, requires db_type, logs “Starting SnowBlossomNode version …”.
2. Loads network parameters and the shard interest set (“Shard interest set: […]”).
3. Opens the database - a shutdown hook flushes RocksDB cleanly (“RocksDB flush started/completed”), so stop the node with SIGTERM, not SIGKILL, and give it time.
4. Loads the peerage (persisted peer list + seeds), transaction broadcaster, forge, UTXO importer, mempools and maintenance thread.
5. Opens a BlockIngestor per shard with a stored head (“Loaded chain tip: shard 0 height …”), recomputing summaries if their version is old (“Reindexing …”).
6. Binds the ports (“Ports: [2338] [2348]”), tries UPnP, starts the gRPC services.
7. Starts peering, the clock watcher and the broadcaster; then “SnowBlossomNode started”.

Threads

Database layout

All maps share one RocksDB with prefixed keys:

Because the summary is written last, after the block, its transactions and the UTXO nodes, a crash can at worst leave orphaned nodes, never a half-applied block.

Monitoring sync and health

• Log lines: “Got first tip from a remote peer”, “Requesting block: …”, “New block: Shard 0 Height H … (tx:N sz:B)”, “New chain tip: Shard 0 Height H hash” followed by “The activated field is 9 (hippo). This block was age ago” - the age tells you how far behind you are.
• SnowBlossomClient client.conf nodestatus prints the NodeStatus JSON: head height per shard, connected_peers (should approach peer_count), estimated_nodes, mem_pool_size, peer version histogram. Compare the height with the explorer.
• Miners and pools get “We are not yet synced, refusing to send block template” until the node is within 10 blocks of the best header it has seen.
• Peers on the wrong network are dropped silently (visible at FINE level: “Peer has wrong name”).

Deployment

systemd

[Unit]
Description=Snowblossom node
After=network.target

[Service]
User=snowblossom
WorkingDirectory=/var/snowblossom
ExecStart=/usr/bin/java -Xmx4g -jar /var/snowblossom/SnowBlossomNode_deploy.jar configs/node.conf
Restart=on-failure
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target

(example/systemd/ in the repository has the original units; they run a node.sh wrapper and have no Restart=.) Logs: journalctl -u snowblossom-node -f plus the rotating files in logs/.

Docker

docker run -d --restart always --name snowblossom.node --network host \
  -v snownode:/data \
  -e snowblossom_addr_index=true -e snowblossom_tx_index=true \
  snowblossom/node:latest
docker logs -f snowblossom.node
docker container stop -t 90 snowblossom.node      # let RocksDB flush

Testnet: add -e snowblossom_network=testnet -e snowblossom_service_port=2339 -e snowblossom_tls_service_port=2349. The images keep everything under /data; SNOWBLOSSOM_JAVA_OPTIONS passes JVM flags.

Reverse proxies and firewalls

Expose 2338/2348 directly. The seed operators also listen on 80/443 for users behind restrictive firewalls; that works because gRPC over HTTP/2 is just TCP - but a proxy that terminates TLS with its own certificate breaks the identity check for grpc+tls:// clients. Web explorers run on their own HTTP port and are the thing to put behind Apache or nginx.

Upgrading

• Stop the node cleanly, replace the jar, start. The database format has been stable since 1.6; summaries with an old summary_version are recomputed at start automatically.
• 2.0.0 rebuilt the summary table on first start (up to an hour, heavy IO, temporary extra disk until compaction). Nodes had to be upgraded by block 211,600 (May 2022).
• 2.2.0 added the post-quantum signatures (mandatory by block 358,700, March 2025), trust-network signed peer info, GetPeerList, TLS for pool miners.
• Turning on addr_index/tx_index later means deleting db_path and resyncing.
• Older milestones: 1.6.0 moved the indexes into the hashed trie (minutes of reindexing); 1.0.8 changed the default DB location; 1.7.0 changed the template protocol so MrPlow needs a node ≥ 1.7.

Troubleshooting