Skip to Content
Developers APIDaemon Configuration

Daemon Configuration

The TOS Network daemon (tos-daemon) is the core component that connects your node to the network. This guide covers comprehensive configuration options, performance tuning, and operational best practices.

Configuration File Structure

The daemon uses a TOML configuration file typically located at:

  • Linux/macOS: ~/.tos/daemon.toml
  • Windows: %APPDATA%\TOS\daemon.toml
  • Docker: /data/daemon.toml
# TOS Network Daemon Configuration
# Don't Trust, Verify it - Configure your node for maximum security
 
[network]
# Network configuration
network_id = "mainnet"  # mainnet, testnet, or devnet
bind_address = "0.0.0.0:2080"
max_peers = 50
seed_nodes = [
    "seed1.tos.network:2080",
    "seed2.tos.network:2080",
    "seed3.tos.network:2080"
]
 
[rpc]
# JSON-RPC API configuration
enable = true
bind_address = "127.0.0.1:8080"
cors_origins = ["http://localhost:3000"]
max_connections = 100
rate_limit = 1000  # requests per minute
 
[storage]
# Database and storage configuration
data_dir = "~/.tos/data"
cache_size = 1024  # MB
sync_mode = "full"  # full, fast, or light
pruning_enabled = false
max_log_files = 10
 
[mining]
# AI-Mining configuration
enable = false
miner_address = "tos1your-mining-address..."
ai_threads = 4
gpu_enabled = true
energy_threshold = 100
 
[privacy]
# Privacy and encryption settings
homomorphic_encryption = true
zero_knowledge_proofs = true
mixnet_enabled = true
tor_proxy = ""  # Optional Tor proxy for enhanced privacy
 
[logging]
# Logging configuration
level = "info"  # trace, debug, info, warn, error
file_path = "~/.tos/logs/daemon.log"
max_file_size = "100MB"
max_files = 5
console_output = true

Network Configuration

Basic Network Settings

Configure your node’s network participation:

[network]
# Choose your network
network_id = "mainnet"  # Production network
# network_id = "testnet"  # Testing network
# network_id = "devnet"   # Development network
 
# Binding configuration
bind_address = "0.0.0.0:2080"  # Listen on all interfaces
public_address = "your-public-ip:2080"  # Optional: specify public IP
 
# Peer management
max_peers = 50
target_peers = 25
min_peers = 5
peer_timeout = 30  # seconds

Advanced Network Tuning

For high-performance nodes:

[network.advanced]
# Connection optimization
tcp_nodelay = true
tcp_keepalive = true
buffer_size = 65536
max_message_size = 16777216  # 16MB
 
# Bandwidth management
max_upload_rate = 0    # 0 = unlimited
max_download_rate = 0  # 0 = unlimited
connection_pool_size = 100
 
# Network discovery
enable_mdns = true
enable_upnp = true
bootstrap_timeout = 30

RPC API Configuration

Basic RPC Setup

[rpc]
enable = true
bind_address = "127.0.0.1:8080"  # Local access only
# bind_address = "0.0.0.0:8080"  # Warning: Allows external access
 
# Security settings
require_auth = false  # Set to true for production
username = "tosuser"
password = "secure-password-here"
 
# CORS configuration
cors_origins = [
    "http://localhost:3000",
    "https://wallet.tos.network"
]

RPC Performance Tuning

[rpc.performance]
max_connections = 100
max_request_size = 1048576  # 1MB
max_response_size = 10485760  # 10MB
request_timeout = 30
keep_alive_timeout = 60
 
# Rate limiting
rate_limit = 1000  # requests per minute per IP
burst_limit = 100  # burst allowance
 
# Caching
enable_cache = true
cache_ttl = 60  # seconds
max_cache_entries = 10000

Storage and Database

Storage Configuration

[storage]
# Data directory (ensure sufficient space)
data_dir = "~/.tos/data"
temp_dir = "~/.tos/temp"
 
# Database settings
db_backend = "rocksdb"  # rocksdb or leveldb
cache_size = 1024  # MB
write_buffer_size = 64  # MB
max_open_files = 1000
 
# Synchronization
sync_mode = "full"  # full, fast, or light
batch_size = 1000
flush_interval = 5  # seconds

Pruning and Archival

[storage.pruning]
# Pruning configuration (saves disk space)
pruning_enabled = false
keep_blocks = 1000000  # Keep last 1M blocks
pruning_interval = 100  # Prune every 100 blocks
 
# Archive settings
archive_mode = false
archive_compression = true
archive_path = "~/.tos/archive"

AI-Mining Configuration

Basic Mining Setup

[mining]
enable = true
miner_address = "tos1your-verified-mining-address..."
 
# Mining threads
cpu_threads = 4  # Adjust based on your CPU
gpu_enabled = true
gpu_devices = [0, 1]  # GPU device indices
 
# AI-Mining parameters
ai_model_cache = 2048  # MB
ai_batch_size = 32
difficulty_target = "auto"

Advanced Mining Options

[mining.advanced]
# Performance tuning
memory_pool_size = 512  # MB
work_queue_size = 100
submission_timeout = 30
 
# Energy management
energy_threshold = 100
energy_regeneration_rate = 1.0
use_energy_optimization = true
 
# Mining strategy
prefer_high_fee_transactions = true
min_transaction_fee = 0.001
max_block_size = 2097152  # 2MB

Privacy and Security

Encryption Settings

[privacy]
# Core privacy features
homomorphic_encryption = true
zero_knowledge_proofs = true
ring_signatures = true
 
# Network privacy
mixnet_enabled = true
mixnet_hops = 3
tor_proxy = "127.0.0.1:9050"  # Optional Tor integration
 
# Transaction privacy
default_privacy_level = "high"  # low, medium, high, maximum
stealth_addresses = true
confidential_amounts = true

Security Hardening

[security]
# Access control
whitelist_enabled = false
whitelist_ips = ["127.0.0.1", "192.168.1.0/24"]
blacklist_ips = []
 
# SSL/TLS configuration
tls_enabled = false
tls_cert_path = "/path/to/cert.pem"
tls_key_path = "/path/to/key.pem"
 
# Security features
dos_protection = true
rate_limiting = true
fail_ban_enabled = true
max_failed_attempts = 5
ban_duration = 3600  # seconds

Logging and Monitoring

Logging Configuration

[logging]
# Log levels: trace, debug, info, warn, error
level = "info"
file_path = "~/.tos/logs/daemon.log"
 
# File rotation
max_file_size = "100MB"
max_files = 5
compress_rotated = true
 
# Output targets
console_output = true
syslog_enabled = false
json_format = false
 
# Component-specific logging
[logging.components]
network = "debug"
mining = "info"
rpc = "warn"
storage = "info"

Metrics and Monitoring

[metrics]
enable = true
bind_address = "127.0.0.1:9090"
path = "/metrics"
 
# Prometheus integration
prometheus_enabled = true
collection_interval = 30  # seconds
 
# Custom metrics
track_peer_metrics = true
track_mining_metrics = true
track_transaction_metrics = true

Environment-Specific Configurations

Production Configuration

# Production-ready configuration
[network]
network_id = "mainnet"
max_peers = 100
target_peers = 50
 
[rpc]
bind_address = "127.0.0.1:8080"  # Local only
require_auth = true
rate_limit = 500
 
[storage]
sync_mode = "full"
cache_size = 4096
pruning_enabled = true
 
[logging]
level = "warn"
console_output = false

Development Configuration

# Development-friendly configuration
[network]
network_id = "devnet"
max_peers = 10
 
[rpc]
bind_address = "0.0.0.0:8080"
require_auth = false
cors_origins = ["*"]
 
[storage]
sync_mode = "fast"
cache_size = 512
 
[logging]
level = "debug"
console_output = true

Configuration Management

Command Line Options

Override configuration file settings:

# Basic daemon startup
tos-daemon
 
# Custom configuration file
tos-daemon --config /path/to/custom.toml
 
# Override specific settings
tos-daemon --network testnet --rpc-port 8081
 
# Mining configuration
tos-daemon --enable-mining --miner-address tos1...
 
# Debug mode
tos-daemon --log-level debug --console-output

Environment Variables

Use environment variables for sensitive configuration:

# Network configuration
export TOS_NETWORK_ID=mainnet
export TOS_BIND_ADDRESS=0.0.0.0:2080
 
# RPC configuration
export TOS_RPC_USERNAME=admin
export TOS_RPC_PASSWORD=secure-password
 
# Mining configuration
export TOS_MINER_ADDRESS=tos1your-address...
export TOS_MINING_THREADS=8
 
# Start daemon with environment variables
tos-daemon

Configuration Validation

Validate your configuration:

# Check configuration syntax
tos-daemon --check-config
 
# Validate and show effective configuration
tos-daemon --show-config
 
# Test network connectivity
tos-daemon --test-network

Performance Optimization

Hardware Recommendations

Minimum Requirements:

  • CPU: 4+ cores
  • RAM: 8GB
  • Storage: 100GB SSD
  • Network: 10 Mbps

Recommended Configuration:

  • CPU: 8+ cores (modern processor)
  • RAM: 16-32GB
  • Storage: 500GB+ NVMe SSD
  • Network: 100+ Mbps

Optimization Tips

# High-performance configuration
[storage]
cache_size = 8192  # Use more RAM for caching
write_buffer_size = 128
max_open_files = 2000
 
[network]
max_peers = 100
buffer_size = 131072  # 128KB buffers
 
[rpc]
max_connections = 200
enable_cache = true
cache_ttl = 120

Troubleshooting

Common Configuration Issues

  • Port Binding Errors 
    # Check if port is in use
netstat -tulpn | grep :2080
 
# Use alternative port
tos-daemon --port 2081

  1. Permission Issues

    # Fix data directory permissions
chmod 750 ~/.tos
chown $USER ~/.tos -R

  2. Network Connectivity

    # Test connectivity to seed nodes
tos-daemon --test-network
 
# Check firewall settings
sudo ufw allow 2080

Configuration Validation

# Validate configuration file
tos-daemon --validate-config ~/.tos/daemon.toml
 
# Show effective configuration
tos-daemon --dump-config
 
# Test configuration without starting
tos-daemon --dry-run

Security Best Practices

  • Access Control
    • Use authentication for RPC access
    • Restrict RPC to localhost in production
    • Implement IP whitelisting for sensitive operations

  1. Network Security

    • Use firewall rules to limit access
    • Consider VPN for remote management
    • Enable TLS for external access

  2. Data Protection

    • Regular backups of wallet and configuration
    • Secure storage of private keys
    • Monitor logs for suspicious activity

  3. Regular Updates

    • Keep daemon software updated
    • Monitor security advisories
    • Test configuration changes in development

Docker Configuration

For containerized deployments:

# docker-compose.yml
version: '3.8'
services:
  tos-daemon:
    image: tosnetwork/tos-node:latest
    ports:
      - "2080:2080"
      - "8080:8080"
    volumes:
      - ./daemon.toml:/data/daemon.toml:ro
      - tos-data:/data
    environment:
      - TOS_CONFIG_FILE=/data/daemon.toml
    restart: unless-stopped

Common Use Cases

Home Node Setup

For personal use with moderate resources:

[network]
network_id = "mainnet"
bind_address = "0.0.0.0:2080"
max_peers = 25
 
[storage]
sync_mode = "fast"
cache_size = 1024
pruning_enabled = true
max_db_size = "100GB"
 
[rpc]
enable = true
bind_address = "127.0.0.1:8080"
cors_origins = ["http://localhost:3000"]
 
[mining]
enable = false  # Enable only if you want to mine

Validator Node Setup

For running a validator with maximum reliability:

[network]
network_id = "mainnet"
bind_address = "0.0.0.0:2080"
max_peers = 100
persistent_peers = [
    "validator1.tos.network:2080",
    "validator2.tos.network:2080"
]
 
[storage]
sync_mode = "full"
cache_size = 4096
pruning_enabled = false
backup_enabled = true
backup_interval = 3600  # Hourly backups
 
[consensus]
validator_mode = true
validator_key_file = "~/.tos/validator_key.json"
double_sign_check = true
 
[security]
rate_limiting = true
max_connections_per_ip = 5

Development/Testing Setup

For local development and testing:

[network]
network_id = "devnet"
bind_address = "127.0.0.1:2080"
max_peers = 10
 
[storage]
data_dir = "./devnet_data"
cache_size = 256
reset_on_start = true  # Fresh state each restart
 
[rpc]
enable = true
bind_address = "0.0.0.0:8080"
cors_origins = ["*"]  # Allow all origins for development
 
[logging]
level = "debug"
console_output = true
 
[mining]
enable = true
instant_mining = true  # Mine blocks instantly for testing

High-Performance Archive Node

For serving historical data and analytics:

[network]
network_id = "mainnet"
bind_address = "0.0.0.0:2080"
max_peers = 200
 
[storage]
sync_mode = "archive"
cache_size = 16384  # 16GB cache
max_open_files = 5000
compression_enabled = true
 
[rpc]
enable = true
bind_address = "0.0.0.0:8080"
max_connections = 500
historical_queries = true
bulk_query_limit = 10000
 
[performance]
sync_threads = 8
verification_threads = 16

Advanced Troubleshooting

Sync Issues

Problem: Daemon stuck at specific block height

# Check sync status
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"get_sync_info","id":1}' \
  http://localhost:8080/json_rpc
 
# Check peer connectivity
tos_daemon peer-info
 
# Force resync from specific height
tos_daemon resync --from-height 1000000
 
# Clear corrupted data and restart
tos_daemon reset-chain --confirm

Problem: Slow synchronization

# Increase peer connections
# In config.toml: max_peers = 100
 
# Use snapshot for faster sync
curl -L https://snapshots.tos.network/latest/mainnet.tar.gz | tar -xz -C ~/.tos/data/
 
# Increase cache size
# In config.toml: cache_size = 4096
 
# Check network bandwidth
speedtest-cli

Memory and Performance Issues

Problem: High memory usage

# Monitor memory usage
top -p $(pgrep tos_daemon)
 
# Reduce cache size
# In config.toml: cache_size = 512
 
# Enable pruning
# In config.toml: pruning_enabled = true
 
# Check for memory leaks
valgrind --tool=memcheck tos_daemon start

Problem: CPU usage too high

# Monitor CPU usage
htop
 
# Reduce thread count
# In config.toml: max_threads = 4
 
# Lower priority for background tasks
# In config.toml: background_priority = "low"
 
# Check for inefficient queries
tail -f ~/.tos/logs/daemon.log | grep "slow_query"

Network Connectivity Issues

Problem: Cannot connect to peers

# Check network connectivity
ping seed1.tos.network
 
# Test port accessibility
telnet seed1.tos.network 2080
 
# Check NAT/firewall settings
sudo netstat -tulpn | grep 2080
 
# Enable UPnP for automatic port forwarding
# In config.toml: upnp_enabled = true
 
# Manually add peers
tos_daemon add-peer 192.168.1.100:2080

Problem: Frequent peer disconnections

# Check bandwidth limits
# In config.toml: max_bandwidth_per_peer = "10MB"
 
# Adjust timeout settings
# In config.toml: peer_timeout = 60
 
# Monitor connection quality
tos_daemon connection-stats
 
# Check for ISP restrictions
traceroute seed1.tos.network

AI-Mining Issues

Problem: AI-Mining not earning rewards

# Check mining status
tos_daemon mining-status
 
# Verify TOS Energy balance
tos_daemon balance --energy
 
# Check AI computation logs
grep "ai_mining" ~/.tos/logs/daemon.log
 
# Test AI computation capability
tos_daemon test-ai-mining
 
# Verify miner address
tos_daemon verify-address tos1your-address...

Problem: GPU not detected for AI-Mining

# Check GPU availability
nvidia-smi  # For NVIDIA GPUs
rocm-smi    # For AMD GPUs
 
# Enable GPU in config
# In config.toml: gpu_enabled = true
 
# Set GPU device ID
# In config.toml: gpu_device = 0
 
# Check OpenCL support
clinfo
 
# Install GPU drivers if needed
# NVIDIA: sudo apt install nvidia-driver-535
# AMD: sudo apt install rocm-opencl-runtime

RPC API Issues

Problem: RPC requests timing out

# Increase timeout settings
# In config.toml: request_timeout = 60
 
# Check RPC connection limits
# In config.toml: max_connections = 200
 
# Monitor RPC performance
curl -w "%{time_total}" -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"get_info","id":1}' \
  http://localhost:8080/json_rpc
 
# Enable RPC caching
# In config.toml: enable_cache = true

Problem: CORS errors in web applications

# Configure CORS origins
# In config.toml: cors_origins = ["https://yourapp.com", "http://localhost:3000"]
 
# Allow all origins (development only)
# In config.toml: cors_origins = ["*"]
 
# Check browser console for specific errors
# Add these headers for debugging
# In config.toml: additional_headers = { "Access-Control-Allow-Headers" = "*" }

Database and Storage Issues

Problem: Database corruption

# Check database integrity
tos_daemon verify-database
 
# Repair database
tos_daemon repair-database --backup-first
 
# Restore from backup
tos_daemon restore-backup --file ~/.tos/backups/latest.tar.gz
 
# Reset database (will resync)
tos_daemon reset-database --confirm

Problem: Disk space running low

# Check disk usage
du -sh ~/.tos/
 
# Enable log rotation
# In config.toml: max_log_files = 5, max_log_size = "100MB"
 
# Enable pruning
# In config.toml: pruning_enabled = true
 
# Archive old data
tos_daemon archive-old-data --before-height 1000000
 
# Move data directory to larger disk
tos_daemon migrate-data --new-path /mnt/large-disk/tos-data

Health Monitoring

Basic Health Checks

# Check overall daemon health
tos_daemon health-check
 
# Monitor block production
tos_daemon block-stats --last 100
 
# Check transaction pool
tos_daemon mempool-info
 
# Monitor peer connections
tos_daemon peer-stats

Setting Up Monitoring

Create a monitoring script:

#!/bin/bash
# tos-monitor.sh
 
DAEMON_HOST="localhost:8080"
LOG_FILE="/var/log/tos-monitor.log"
 
check_daemon() {
    response=$(curl -s -X POST -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","method":"get_info","id":1}' \
        http://$DAEMON_HOST/json_rpc)
 
    if echo "$response" | grep -q '"result"'; then
        echo "$(date): Daemon is healthy" >> $LOG_FILE
    else
        echo "$(date): Daemon health check failed" >> $LOG_FILE
        # Send alert notification
        # curl -X POST "https://hooks.slack.com/..." -d "{"text": "TOS daemon down!"}"
    fi
}
 
check_sync() {
    sync_info=$(curl -s -X POST -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","method":"get_sync_info","id":1}' \
        http://$DAEMON_HOST/json_rpc)
 
    # Parse and check sync status
    # Alert if falling behind
}
 
# Run checks
check_daemon
check_sync

Performance Metrics

Monitor key performance indicators:

# Block processing time
tos_daemon metrics --block-processing
 
# Transaction throughput
tos_daemon metrics --tx-throughput
 
# Memory usage over time
tos_daemon metrics --memory --duration 24h
 
# Network bandwidth usage
tos_daemon metrics --network --duration 1h

Migration and Upgrades

Upgrading Daemon Version

# Backup current state
tos_daemon backup --output ~/.tos/backups/pre-upgrade-$(date +%Y%m%d).tar.gz
 
# Stop daemon gracefully
tos_daemon stop --graceful
 
# Download new version
curl -L https://github.com/tos-network/tos/releases/latest/download/tos_daemon -o tos_daemon_new
 
# Replace binary
sudo mv tos_daemon_new /usr/local/bin/tos_daemon
sudo chmod +x /usr/local/bin/tos_daemon
 
# Start with new version
tos_daemon start
 
# Verify upgrade
tos_daemon version

Migrating Between Servers

# On old server - backup everything
tos_daemon backup --full --output tos-full-backup.tar.gz
 
# Transfer to new server
scp tos-full-backup.tar.gz user@newserver:~/
 
# On new server - restore
tos_daemon restore --input tos-full-backup.tar.gz
 
# Update configuration for new environment
# Edit ~/.tos/config.toml as needed
 
# Start daemon
tos_daemon start

Getting Support

Collecting Debug Information

When reporting issues, collect comprehensive debug information:

# Generate debug report
tos_daemon debug-report --output debug-$(date +%Y%m%d).tar.gz
 
# This includes:
# - Configuration files
# - Recent logs
# - System information
# - Network connectivity tests
# - Performance metrics

Community Resources

This comprehensive configuration guide ensures your TOS Network node operates securely, efficiently, and in alignment with the network’s “Don’t Trust, Verify it” principle. Whether you’re running a simple home node or a high-performance validator, these configurations and troubleshooting steps will help you maintain optimal performance.

Last updated on
Stratum ProtocolSDK Documentation