Node Configuration

This guide covers all configuration options available for Ubu-Block nodes. Configuration is managed through TOML files that specify database connections, network settings, and peer relationships.

Configuration File Format

Ubu-Block uses TOML configuration files. Create a config.toml file in your node directory:

main_db = "sqlite://data/blockchain.db"
private_db = "sqlite://data/private.db"
http_addr = "127.0.0.1:9091"
node_addr = "127.0.0.1:9090"

[peers]
node1 = "127.0.0.1:9093"
node2 = "127.0.0.1:9095"

Configuration Structure

The configuration is defined in crates/types/src/config.rs:7-15:

pub struct Config {
    pub mode: Option<Mode>,
    pub main_db: String,
    pub private_db: String,
    pub peer_config: Option<P2PConfig>,
    pub peers: Option<HashMap<String, String>>,
    pub http_addr: Option<String>,
    pub node_addr: Option<String>,
}

Core Options

Database Configuration

`main_db`

main_db

string

required

Connection string for the main blockchain database. Stores blocks, transactions, and electoral data.

Example:

main_db = "sqlite://data/blockchain.db"

Supported formats:

SQLite: sqlite://path/to/database.db
In-memory SQLite: sqlite::memory:
Relative paths: sqlite://../../data/blockchain.db
Absolute paths: sqlite:///home/user/data/blockchain.db

`private_db`

private_db

string

required

Connection string for the private database. Stores node-specific data not shared with the network.

Example:

private_db = "sqlite://data/private.db"

Network Configuration

`node_addr`

node_addr

string

Address and port for the P2P network interface. Used for blockchain protocol communications.

Example:

node_addr = "127.0.0.1:9090"

Default: Not set (required for submission nodes) Format: IP:PORT

Use 127.0.0.1 for localhost only
Use 0.0.0.0 to listen on all interfaces
Port range: 1024-65535 (avoid privileged ports)

`http_addr`

http_addr

string

Address and port for the HTTP API server. Used for REST API endpoints.

Example:

http_addr = "127.0.0.1:9091"

Default: Not set (required for submission nodes) Format: IP:PORT

Peer Configuration

`peers`

peers

object

Map of peer names to addresses. The node will attempt to connect to all listed peers on startup.

Example:

[peers]
bootstrap = "127.0.0.1:9090"
node2 = "192.168.1.100:9090"
node3 = "10.0.0.50:9090"

Notes:

Peer names (keys) are arbitrary identifiers
Values must be valid socket addresses
Connections are established asynchronously
Failed connections are logged but don’t stop startup

P2P Protocol Configuration

`peer_config`

peer_config

P2PConfig

Advanced P2P network settings. Uses defaults if not specified.

The P2P configuration is defined in crates/types/src/p2p.rs:94-112:

[peer_config]
max_peers = 50
ping_interval_secs = 30
connection_timeout_secs = 10
sync_batch_size = 100
max_message_size = 10485760

Options:

Option	Type	Default	Description
`max_peers`	integer	50	Maximum number of peer connections
`ping_interval_secs`	integer	30	Seconds between keep-alive pings
`connection_timeout_secs`	integer	10	Connection timeout in seconds
`sync_batch_size`	integer	100	Number of blocks per sync batch
`max_message_size`	integer	10485760	Maximum message size in bytes (10MB)

Configuration Examples

Single Submission Node

main_db = "sqlite://data/blockchain.db"
private_db = "sqlite://data/private.db"
http_addr = "127.0.0.1:9091"
node_addr = "127.0.0.1:9090"

Submission Node with Peers

main_db = "sqlite://data/blockchain.db"
private_db = "sqlite://data/private.db"
http_addr = "127.0.0.1:9091"
node_addr = "127.0.0.1:9090"

[peers]
bootstrap = "127.0.0.1:9093"
node2 = "127.0.0.1:9095"

Production Configuration

main_db = "sqlite:///var/lib/ubu-block/blockchain.db"
private_db = "sqlite:///var/lib/ubu-block/private.db"
http_addr = "0.0.0.0:9091"
node_addr = "0.0.0.0:9090"

[peers]
peer1 = "node1.ubublock.network:9090"
peer2 = "node2.ubublock.network:9090"
peer3 = "node3.ubublock.network:9090"

[peer_config]
max_peers = 100
ping_interval_secs = 60
connection_timeout_secs = 30
sync_batch_size = 500
max_message_size = 52428800

Development Multi-Node Setup

config1.toml:

main_db = "sqlite://data/blockchain1.db"
private_db = "sqlite://data/private1.db"
http_addr = "127.0.0.1:9091"
node_addr = "127.0.0.1:9090"

config2.toml:

main_db = "sqlite://data/blockchain2.db"
private_db = "sqlite://data/private2.db"
http_addr = "127.0.0.1:9092"
node_addr = "127.0.0.1:9093"

[peers]
default = "127.0.0.1:9090"

config3.toml:

main_db = "sqlite://data/blockchain3.db"
private_db = "sqlite://data/private3.db"
http_addr = "127.0.0.1:9094"
node_addr = "127.0.0.1:9095"

[peers]
node1 = "127.0.0.1:9090"
node2 = "127.0.0.1:9093"

Loading Configuration

Configuration files are loaded at startup using the --config flag:

cargo run --release -- --config config.toml

From nodes/submission/src/main.rs:23-28:

let cli = Cli::parse();

let config: Config = toml::from_str(
    &std::fs::read_to_string(cli.config.as_path())
        .expect("Failed to read config file"),
).expect("Failed to parse config file");

Environment Variables

While most configuration is in TOML files, some settings use environment variables:

`RUST_LOG`

Controls logging verbosity:

# Error only
RUST_LOG=error cargo run -- --config config.toml

# Info level (recommended)
RUST_LOG=info cargo run -- --config config.toml

# Debug (verbose)
RUST_LOG=debug cargo run -- --config config.toml

# Trace (very verbose)
RUST_LOG=trace cargo run -- --config config.toml

Module-specific logging:

# Only blockchain module
RUST_LOG=blockchain=debug cargo run -- --config config.toml

# Multiple modules
RUST_LOG=blockchain=debug,p2p=info cargo run -- --config config.toml

Configuration Validation

The node validates configuration on startup:

Required fields:

main_db - Always required
private_db - Always required
node_addr - Required for submission nodes
http_addr - Required for submission nodes

Common validation errors:

Invalid database URL format
Port already in use
Invalid IP address format
Unreachable peer addresses
File permission issues

Security Best Practices

Database Security

Use absolute paths for production databases
Set appropriate file permissions (600 for database files)
Regular database backups
Separate main and private databases
Use encrypted storage for sensitive data

Network Security

Bind to 127.0.0.1 for local-only access
Use firewall rules to restrict P2P ports
Keep HTTP API on internal network only
Use reverse proxy for external access
Enable TLS for production deployments

Peer Security

Only connect to trusted peers
Verify peer certificates (when implemented)
Monitor peer connection logs
Set reasonable max_peers limit
Use peer allowlists for production

Troubleshooting

Configuration File Not Found

Error: Failed to read config file: No such file or directory

Solution: Verify the path is correct relative to your current directory:

ls -la config.toml
cargo run -- --config ./config.toml

Invalid TOML Syntax

Error: Failed to parse config file

Solution: Validate TOML syntax:

Check for missing quotes around strings
Verify table headers use [section] format
Ensure key-value pairs use = separator
Use a TOML validator online

Port Already in Use

Error: Address already in use (os error 98)

Solution: Change ports in config or stop the conflicting process:

# Find process using port
lsof -i :9090

# Kill process
kill <PID>

# Or change port in config.toml
node_addr = "127.0.0.1:9099"

Database Connection Failed

Error: Failed to connect to database

Solution:

Ensure the directory exists: mkdir -p data
Check file permissions
Verify SQLite is installed
Use absolute paths for production

Next Steps

Observer Node

Run an observer node

Submission Node

Run a submission node

Verification Node

Learn about verification

Get Started

Core Concepts

Node Operations

Usage Guides

Security

Node Configuration

Configuration File Format

Configuration Structure

Core Options

Database Configuration

`main_db`

`private_db`

Network Configuration

`node_addr`

`http_addr`

Peer Configuration

`peers`

P2P Protocol Configuration

`peer_config`

Configuration Examples

Single Submission Node

Submission Node with Peers

Production Configuration

Development Multi-Node Setup

Loading Configuration

Environment Variables

`RUST_LOG`

Configuration Validation

Security Best Practices

Troubleshooting

Configuration File Not Found

Invalid TOML Syntax

Port Already in Use

Database Connection Failed

Next Steps

Observer Node

Submission Node

Verification Node

Build docs developers (and LLMs) love

Get Started

Core Concepts

Node Operations

Usage Guides

Security

​Configuration File Format

​Configuration Structure

​Core Options

​Database Configuration

​main_db

​private_db

​Network Configuration

​node_addr

​http_addr

​Peer Configuration

​peers

​P2P Protocol Configuration

​peer_config

​Configuration Examples

​Single Submission Node

​Submission Node with Peers

​Production Configuration

​Development Multi-Node Setup

​Loading Configuration

​Environment Variables

​RUST_LOG

​Configuration Validation

​Security Best Practices

​Troubleshooting

​Configuration File Not Found

​Invalid TOML Syntax

​Port Already in Use

​Database Connection Failed

​Next Steps

Observer Node

Submission Node

Verification Node

Build docs developers (and LLMs) love

Configuration File Format

Configuration Structure

Core Options

Database Configuration

`main_db`

`private_db`

Network Configuration

`node_addr`

`http_addr`

Peer Configuration

`peers`

P2P Protocol Configuration

`peer_config`

Configuration Examples

Single Submission Node

Submission Node with Peers

Production Configuration

Development Multi-Node Setup

Loading Configuration

Environment Variables

`RUST_LOG`

Configuration Validation

Security Best Practices

Troubleshooting

Configuration File Not Found

Invalid TOML Syntax

Port Already in Use

Database Connection Failed

Next Steps