Node Operations

Operational guide for running and maintaining a BLVM node.

Operations runbook

Starting the Node

Basic Startup

# Regtest mode (default, safe for development)
blvm

# Testnet mode
blvm --network testnet

# Mainnet: first sync: see First Node Setup (IBD example config), not bare mainnet
# blvm --network mainnet

With Configuration

blvm --config blvm.toml

Starting from a Bitcoin Core datadir

Use when Core is fully synced and you want the same tip without full IBD.

# Recommended: auto-migrate on start → ~/.bitcoin/blvm/
blvm start --network mainnet --data-dir ~/.bitcoin

On first start BLVM detects the Core layout, migrates once into <datadir>/blvm/, then opens the BLVM store. Block files are not copied by default: BLVM keeps reading bodies from Core blocks/ (~700 GB stays in one place). Only the UTXO set and indexes are converted into BLVM format (~15-30 GB under blvm/).

# Optional: explicit migrate with verify, then start the BLVM store
blvm migrate core --source ~/.bitcoin --destination ~/.bitcoin/blvm \
 --network mainnet --verify
blvm start --network mainnet --data-dir ~/.bitcoin/blvm

What gets migrated

After a successful migrate you may delete Core chainstate/ (~12 GB) if you will not run bitcoind on that datadir again.

Flags and settings

Requires the rocksdb Cargo feature (blvm default features; omitted from portable Windows/aarch64 release builds). Config and ENV details: Bitcoin Core drop-in, Storage Backends.

Verify: --verify on blvm migrate core; regtest test core_drop_in (fixture: blvm-node/scripts/gen-core-regtest-fixture.sh); mainnet smoke: blvm-node/scripts/core-drop-in-mainnet-smoke.sh.

Node Lifecycle

The node follows a lifecycle with multiple states and transitions.

Sync state machine

State descriptions:

State transitions are managed by the SyncStateMachine (Initial → Headers → Blocks → Synced). Progress weighting in UI/logs uses ~30% at headers complete and ~60% at blocks complete before full sync.

Initial sync checklist

When starting for the first time, the node will:

1. Initialize Components: Storage, network, RPC, modules
2. Connect to P2P Network: Discover peers via DNS seeds or persistent peers
3. Download Headers: Request and validate block headers
4. Download Blocks: Request and validate blocks
5. Build UTXO Set: Construct UTXO set from validated blocks
6. Sync to Current Height: Continue until caught up with network

Running State

Once synced, the node maintains:

• Peer Connections: Active P2P connections
• Block Validation: Validates and relays new blocks (via blvm-consensus)
• Transaction Processing: Validates and relays transactions
• Chain State Updates: Updates chain tip and height
• RPC Requests: Serves JSON-RPC API requests
• Health Monitoring: Periodic health checks

Health States

The node tracks health status for each component:

• Healthy: Component operating normally
• Degraded: Component functional but with issues
• Unhealthy: Component not functioning correctly
• Down: Component not responding

Error Recovery

The node implements graceful error recovery:

• Network Errors: Automatic reconnection with exponential backoff
• Storage Errors: Timeout protection, graceful degradation
• Validation Errors: Logged and reported, node continues operation
• Disk Space: Periodic checks with warnings

Monitoring

Health Checks

# CLI health check (uses JSON-RPC getblockchaininfo on the configured RPC address)
blvm health
# Mainnet node:
blvm --network mainnet --rpc-addr 127.0.0.1:8332 health

# HTTP health on the RPC port (GET: same port as JSON-RPC)
curl -s http://127.0.0.1:8332/health # mainnet: quick status
curl -s http://127.0.0.1:18332/health # testnet
curl -s http://127.0.0.1:18443/health # regtest
curl -s http://127.0.0.1:18443/health/live # liveness (same body as /health)
curl -s http://127.0.0.1:18443/health/ready # readiness (healthy only)
curl -s http://127.0.0.1:18443/health/detailed # full gethealth JSON

# Prometheus metrics (GET /metrics: requires auth when [rpc_auth] is enabled)
curl -s http://127.0.0.1:8332/metrics

# JSON-RPC node health extension (blvm-node; not Bitcoin Core): use your RPC port
curl -X POST http://127.0.0.1:18443 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc": "2.0", "method": "gethealth", "params": [], "id": 1}'

# JSON-RPC metrics extension (blvm-node; not Bitcoin Core)
curl -X POST http://127.0.0.1:18443 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc": "2.0", "method": "getmetrics", "params": [], "id": 1}'

# JSON-RPC blockchain info
curl -X POST http://127.0.0.1:8332 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc": "2.0", "method": "getblockchaininfo", "params": [], "id": 1}'

Logging

The node uses structured logging. Set log level via environment variable:

# Set log level
RUST_LOG=info blvm

# Debug mode
RUST_LOG=debug blvm

# Trace all operations
RUST_LOG=trace blvm

Maintenance

Database Maintenance

The node automatically maintains block storage, UTXO set, chain indexes, and transaction indexes.

Backup

Regular backups recommended:

# Backup data directory
tar -czf blvm-backup-$(date +%Y%m%d).tar.gz /var/lib/blvm

Updates

When updating the node:

1. Stop the node gracefully
2. Backup data directory
3. Download new binary from GitHub Releases
4. Replace old binary with new one
5. Restart node

Troubleshooting

See Troubleshooting for detailed solutions to common issues.

Source

• sync.rs
• mod.rs
• health.rs

See Also

• Node Configuration - Configuration options
• Node Overview - Node architecture and features
• RPC API Reference - Complete RPC API documentation
• Troubleshooting - Common issues and solutions
• Performance Optimizations - Performance tuning