Configuration

Relevant Source Files

.env.example config/environment.ts

This document covers the comprehensive configuration system for the SN106 Bittensor subnet validator. It explains how environment variables are loaded, validated, and transformed into typed configuration objects used throughout the application. The configuration system supports multi-chain operations, performance tuning, and validator-specific settings.

For information about Docker deployment configuration, see Docker Deployment. For validator operation procedures, see For Validators.

Configuration System Architecture

The SN106 configuration system follows a layered approach where environment variables are loaded, validated, and transformed into strongly-typed configuration objects.

graph TD
    ENV_FILE[".env file"] --> DOTENV["dotenv.config()"]
    ENV_VARS["Process Environment Variables"] --> DOTENV
    DOTENV --> ENV_OBJ["ENV Object<br/>Raw Environment Values"]
    
    ENV_OBJ --> VALIDATION["validateEnvironment()<br/>Required Variable Check"]
    VALIDATION --> WARNINGS["Console Warnings<br/>Missing Variables"]
    
    ENV_OBJ --> CONFIG_OBJ["CONFIG Object<br/>Typed Configuration"]
    CONFIG_OBJ --> CHAIN_CONFIG["Multi-Chain Configuration<br/>SOLANA/ETHEREUM/BASE"]
    CONFIG_OBJ --> PERF_CONFIG["Performance Configuration<br/>Retries/Timeouts/Batching"]
    CONFIG_OBJ --> VALIDATOR_CONFIG["Validator Configuration<br/>EMA/Intervals/Hotkeys"]
    CONFIG_OBJ --> BITTENSOR_CONFIG["Bittensor Configuration<br/>WebSocket/Networks"]
    
    CHAIN_CONFIG --> GET_ENABLED["getEnabledChains()<br/>Runtime Chain Filtering"]
    CHAIN_CONFIG --> IS_ENABLED["isChainEnabled()<br/>Chain Status Check"]
    
    style ENV_FILE fill:#e1f5fe
    style CONFIG_OBJ fill:#fff3e0
    style VALIDATION fill:#ffebee

Configuration Flow

The configuration system processes settings in this sequence: environment variables are loaded via dotenv, transformed through the ENV object, validated for required fields, and structured into the typed CONFIG object with computed values and helper methods.

Sources: config/environment.ts:1-169 , .env.example:1-15

Environment Variable Categories

The configuration system organizes environment variables into logical categories, each serving specific operational aspects of the validator.

graph LR
    subgraph "Core Validator Settings"
        INTERVAL["VALIDATOR_INTERVAL_MINUTES<br/>Execution Frequency"]
        HOTKEY["VALIDATOR_HOTKEY_URI<br/>Identity Management"]
        EMA_CONFIG["USE_EMA/EMA_ALPHA<br/>Weight Smoothing"]
    end
    
    subgraph "Multi-Chain Configuration"
        ENABLED["ENABLED_CHAINS<br/>Chain Selection"]
        SOLANA_RPC["SOLANA_RPC_ENDPOINT<br/>Solana Connection"]
        ETH_RPC["ETHEREUM_RPC_URL<br/>Ethereum Connection"]
        BASE_RPC["BASE_RPC_URL<br/>Base Connection"]
    end
    
    subgraph "Smart Contract Addresses"
        SN106_SOL["SN106_SVM_PROGRAM_ID<br/>Solana Program"]
        RAYDIUM["RAYDIUM_CLMM_PROGRAM_ID<br/>Raydium Integration"]
        UNISWAP_FACTORY["UNISWAP_V3_FACTORY_ADDRESS<br/>Uniswap V3 Factory"]
        MULTICALL["ETH_MULTICALL_ADDRESS<br/>Ethereum Multicall"]
    end
    
    subgraph "Network Configuration"
        SUBTENSOR["SUBTENSOR_WS_URL<br/>Subtensor Connection"]
        BITTENSOR["BITTENSOR_WS_ENDPOINT<br/>Bittensor Network"]
        NETUID["NETUID<br/>Subnet Identifier"]
    end
    
    subgraph "Performance Tuning"
        RETRIES["MAX_RETRIES<br/>Failure Handling"]
        TIMEOUTS["RPC_TIMEOUT_MS<br/>Connection Limits"]
        BATCHING["POSITION_BATCH_SIZE<br/>Data Processing"]
        CACHE_TTL["HOTKEYS_CACHE_TTL_MS<br/>Cache Duration"]
    end

Variable Organization

Environment variables are logically grouped to simplify configuration management. Each category addresses specific operational requirements: validator behavior, blockchain connections, smart contract interactions, network endpoints, and performance optimization.

Sources: config/environment.ts:12-69 , .env.example:1-15

Configuration Loading and Type Safety

The configuration system implements a two-layer approach with raw environment variable access and typed configuration objects.

Environment Variable Layer (ENV)

Category	Variables	Purpose
Validator	VALIDATOR_INTERVAL_MINUTES, USE_EMA, EMA_ALPHA, EMA_EPSILON	Core validator operation parameters
Chain Selection	ENABLED_CHAINS, MINER_HOTKEYS	Multi-chain and miner management
Solana	SOLANA_RPC_ENDPOINT, SN106_SVM_PROGRAM_ID, RAYDIUM_CLMM_PROGRAM_ID	Solana blockchain configuration
Ethereum	ETHEREUM_RPC_URL, ETH_SN106_CONTRACT_ADDRESS, UNISWAP_V3_*	Ethereum DeFi integration
Base	BASE_RPC_URL, BASE_SN106_CONTRACT_ADDRESS, BASE_UNISWAP_V3_*	Base layer 2 configuration
Bittensor	SUBTENSOR_WS_URL, BITTENSOR_WS_ENDPOINT, VALIDATOR_HOTKEY_URI, NETUID	Bittensor network settings
Performance	MAX_RETRIES, RPC_TIMEOUT_MS, POSITION_BATCH_SIZE, HOTKEY_BATCH_SIZE	Operational optimization

Typed Configuration Layer (CONFIG)

The CONFIG object transforms raw environment variables into strongly-typed, validated configuration with computed values and helper methods:

// Chain management with runtime filtering
getEnabledChains(): SupportedChain[]
isChainEnabled(chain: SupportedChain): boolean

// Typed blockchain configurations
SOLANA: { RPC_ENDPOINT, PROGRAM_ID: PublicKey, CLMM_PROGRAM_ID: PublicKey }
ETHEREUM: { RPC_URL, SN106_CONTRACT_ADDRESS, UNISWAP_V3_* }
BASE: { RPC_URL, SN106_CONTRACT_ADDRESS, UNISWAP_V3_* }

Sources: config/environment.ts:12-149

Multi-Chain Configuration Management

The SN106 system is designed for multi-chain operation with current Solana support and planned Ethereum/Base integration.

Chain Filtering System

graph TD
    ENABLED_CHAINS_ENV["ENABLED_CHAINS Environment Variable<br/>'SOLANA,ETHEREUM,BASE'"] --> PARSE_CHAINS["chainsEnv.toUpperCase()<br/>String Processing"]
    
    PARSE_CHAINS --> ALL_CHAINS["allChains: SupportedChain[]<br/>['solana']"]
    ALL_CHAINS --> GET_ENABLED["getEnabledChains()<br/>Returns Active Chains"]
    
    GET_ENABLED --> SOLANA_ACTIVE["Solana: Always Active<br/>Current Implementation"]
    GET_ENABLED --> ETH_PLANNED["Ethereum: Planned<br/>Future Support"]
    GET_ENABLED --> BASE_PLANNED["Base: Planned<br/>Future Support"]
    
    CHAIN_CHECK["isChainEnabled(chain)<br/>Runtime Chain Validation"] --> GET_ENABLED
    
    subgraph "Current Implementation"
        SOLANA_ONLY["Only 'solana' supported<br/>Returns ['solana']"]
    end
    
    style SOLANA_ACTIVE fill:#c8e6c9
    style ETH_PLANNED fill:#ffebee
    style BASE_PLANNED fill:#ffebee

Chain Configuration Status

Currently, only Solana is fully implemented and active. The configuration system is structured to support Ethereum and Base chains, with placeholder configurations ready for future activation.

Chain-Specific Configuration

Chain	RPC Configuration	Smart Contracts	Status
Solana	SOLANA_RPC_ENDPOINT (devnet default)	SN106_SVM_PROGRAM_ID, RAYDIUM_CLMM_PROGRAM_ID	✅ Active
Ethereum	ETHEREUM_RPC_URL	ETH_SN106_CONTRACT_ADDRESS, Uniswap V3 contracts	🔄 Planned
Base	BASE_RPC_URL (mainnet default)	BASE_SN106_CONTRACT_ADDRESS, Uniswap V3 contracts	🔄 Planned

Sources: config/environment.ts:87-96 , config/environment.ts:100-122

Validator Configuration

The validator configuration manages the core operational parameters that control how the SN106 validator executes its duties.

Execution and Weight Management

Setting	Environment Variable	Default	Purpose
Execution Interval	VALIDATOR_INTERVAL_MINUTES	20	Frequency of validator execution cycles
EMA Usage	USE_EMA	true	Enable exponential moving average for weight smoothing
EMA Alpha	EMA_ALPHA	0.3	Smoothing factor for weight updates
EMA Epsilon	EMA_EPSILON	1e-6	Minimum threshold for weight changes

Identity and Network Settings

graph LR
    HOTKEY_URI["VALIDATOR_HOTKEY_URI<br/>Validator Identity"] --> BACKWARD_COMPAT["Backward Compatibility<br/>VALIDATOR_HOTKEY_MNEMONIC"]
    
    HOTKEY_URI --> FORMATS["Supported Formats<br/>Mnemonic/Private Key/URI"]
    
    SUBTENSOR_WS["SUBTENSOR_WS_URL<br/>Subtensor Connection"] --> WEIGHT_SUBMISSION["Weight Submission<br/>setWeightsOnSubtensor"]
    
    NETUID_CONFIG["NETUID<br/>Subnet Identifier"] --> SUBNET_TARGET["Default: 106<br/>SN106 Subnet"]
    
    BITTENSOR_WS["BITTENSOR_WS_ENDPOINT<br/>Bittensor Network"] --> HOTKEY_RESOLUTION["Hotkey Resolution<br/>UID Mapping"]

Validator Identity Management

The VALIDATOR_HOTKEY_URI supports multiple identity formats (mnemonic, private key, URI) and maintains backward compatibility with the legacy VALIDATOR_HOTKEY_MNEMONIC variable.

Sources: config/environment.ts:14-18 , config/environment.ts:44-51 , config/environment.ts:77-84

Performance and Operational Tuning

The configuration system provides extensive performance tuning options for handling network latency, batch processing, and error recovery.

Retry and Timeout Configuration

Setting	Environment Variable	Default	Purpose
Max Retries	MAX_RETRIES	3	Maximum retry attempts for failed operations
Base Delay	RETRY_BASE_DELAY_MS	1000ms	Base delay for exponential backoff
Initial Delay	INITIAL_RETRY_DELAY_MS	500ms	Initial retry delay
Max Delay	MAX_RETRY_DELAY_MS	5000ms	Maximum retry delay cap
RPC Timeout	RPC_TIMEOUT_MS	30000ms	RPC call timeout limit

Batch Processing Configuration

graph TD
    POSITION_BATCH["POSITION_BATCH_SIZE<br/>Default: 100"] --> POSITION_PROCESSING["NFT Position Data<br/>Batch Processing"]
    
    HOTKEY_BATCH["HOTKEY_BATCH_SIZE<br/>Default: 8"] --> HOTKEY_RESOLUTION["Hotkey to UID<br/>Batch Resolution"]
    
    MAX_CONCURRENT["MAX_CONCURRENT_BATCHES<br/>Default: 3"] --> CONCURRENCY_CONTROL["Batch Concurrency<br/>Resource Management"]
    
    BATCH_DELAY["BATCH_DELAY_MS<br/>Default: 50ms"] --> RATE_LIMITING["Inter-batch Delay<br/>Rate Limiting"]
    
    CACHE_TTL["HOTKEYS_CACHE_TTL_MS<br/>Default: 5 minutes"] --> CACHE_MANAGEMENT["Hotkey Cache<br/>TTL Management"]
    
    subgraph "Performance Impact"
        POSITION_PROCESSING --> MEMORY_USAGE["Memory Usage<br/>Large Batches = More RAM"]
        HOTKEY_RESOLUTION --> API_LOAD["API Load<br/>Smaller Batches = More Calls"]
        CONCURRENCY_CONTROL --> RESOURCE_USAGE["Resource Usage<br/>Network/CPU Balance"]
    end

Batch Processing Strategy

The batch configuration balances memory usage, API call frequency, and processing speed. Larger position batches reduce API calls but increase memory usage, while smaller hotkey batches distribute API load more evenly.

Sources: config/environment.ts:58-68 , config/environment.ts:138-148

Environment Validation

The configuration system includes validation to ensure required settings are present and provides informative warnings for missing variables.

Validation Process

graph TD
    VALIDATE_ENV["validateEnvironment()<br/>Function Call"] --> REQUIRED_CHECK["Required Variables<br/>['SOLANA_RPC_ENDPOINT', 'SN106_SVM_PROGRAM_ID']"]
    
    REQUIRED_CHECK --> FILTER_MISSING["missing.filter()<br/>Find Missing Variables"]
    
    FILTER_MISSING --> HAS_MISSING{"Missing Variables?"}
    
    HAS_MISSING -->|Yes| CONSOLE_WARN["console.warn()<br/>Warning Messages"]
    HAS_MISSING -->|No| VALIDATION_PASS["Validation Passed<br/>All Required Present"]
    
    CONSOLE_WARN --> DEFAULT_VALUES["Using Default Values<br/>Graceful Degradation"]
    
    AUTO_VALIDATION["Automatic Validation<br/>On Module Import"] --> VALIDATE_ENV
    
    style CONSOLE_WARN fill:#fff3e0
    style VALIDATION_PASS fill:#c8e6c9

Validation Strategy

The validation system focuses on critical variables required for core functionality. Missing variables trigger warnings but don’t prevent startup, allowing the system to use defaults and continue operating in degraded mode.

Required vs Optional Variables

• Required: SOLANA_RPC_ENDPOINT, SN106_SVM_PROGRAM_ID
• Optional with Defaults: Most configuration variables have sensible defaults
• Validator-Specific: VALIDATOR_HOTKEY_URI (required only for validators)

Sources: config/environment.ts:154-169