Skip to content

Comprehensive Settings Reference

This document provides a complete reference for all Teranode configuration settings, organized by component.

Table of Contents

  1. Overview
  2. General Configuration
  3. Services

Overview

All Teranode services accept settings through a centralized Settings object that allows local and remote servers to have their own specific configuration.

For general information on how the configuration system works, see the Settings Overview.

For deployment-specific information, see:

General Configuration

Configuration Files

Settings are stored in two files:

  • settings.conf: Global settings with sensible defaults for all environments
  • settings_local.conf: Developer-specific and deployment-specific overrides (not in source control)

Configuration System

The configuration system uses a layered approach with the following priority (highest to lowest):

  1. Environment variable (exact setting key name, e.g., asset_httpListenAddress=:8090)
  2. SETTING_NAME.full_context (e.g., SETTING_NAME.docker.m — longest matching context chain wins)
  3. Progressively shorter context suffixes (e.g., SETTING_NAME.docker if SETTING_NAME.docker.m is not set)
  4. SETTING_NAME: Base setting (lowest priority)

Context resolution strips suffixes from right to left until a match is found. There is no special .base suffix — the plain key name is the final fallback.

Context Names and Suffixes

Base contexts:

Context Description
dev Local development
test Unit/integration test runs
docker Docker Compose deployments
operator Kubernetes/production deployments

Contexts support dot-notation suffixes to target specific deployment sub-configurations:

Suffix Meaning Example
.m Multi-node Docker Compose setup KAFKA_HOSTS.docker.m
.ss.teranode1 Single-service deployment, first instance KAFKA_BLOCKS.docker.ss.teranode1
.testrunner CI test runner environment DATADIR.docker.context.testrunner

Suffixes are combined with base contexts using dots, e.g., docker.m means "multi-node Docker Compose". Settings are resolved by matching the longest applicable suffix chain.

Environment Variables

Settings can be configured as environment variables using the exact setting key name (e.g., asset_httpListenAddress=:8090, blockchain_grpcAddress=localhost:8087). The environment variable name matches the key exactly as it appears in settings.conf and the settings structs. Environment variables take the highest priority and override any value in the settings files.

Services

For detailed service-specific configuration documentation, see:

  • Alert Service - BSV Blockchain alert system configuration
  • Asset Server - HTTP/WebSocket interface configuration
  • Block Assembly - Block assembly service configuration
  • Blockchain - Blockchain state management configuration
  • Block Persister - Block persistence configuration
  • Block Validation - Block validation configuration
  • Legacy - Legacy Bitcoin protocol compatibility configuration
  • P2P - Peer-to-peer networking configuration
  • Propagation - Transaction propagation configuration
  • RPC - JSON-RPC server configuration
  • Pruner - UTXO and block data pruning configuration
  • Subtree Validation - Subtree validation configuration
  • UTXO Persister - UTXO set persistence configuration
  • Validator - Transaction validation configuration
  • Coinbase - Coinbase transaction and mining reward configuration
  • Faucet - Test Bitcoin faucet service configuration