Configuration System

Overview

The Bitcoin Commons configuration system provides a unified, type-safe interface for all governance-controlled parameters. The system uses YAML files as the source of truth with a database-backed registry for governance-controlled changes and a comprehensive fallback chain.

Architecture

The configuration system has three core components:

1. YAML Files (Source of Truth)

YAML configuration files in the governance/config/ directory serve as the authoritative source for all configuration defaults. These files are version-controlled and human-readable.

Key Files:

• action-tiers.yml - Tier definitions and signature requirements
• repository-layers.yml - Layer definitions and requirements
• emergency-tiers.yml - Emergency tier definitions
• commons-contributor-thresholds.yml - Commons contributor thresholds
• governance-fork.yml - Governance fork configuration
• maintainers/*.yml - Maintainer configurations by layer
• repos/*.yml - Repository-specific configurations

2. ConfigRegistry (Database-Backed)

The ConfigRegistry stores all governance-controlled configuration parameters in a database, enabling governance-approved changes without modifying YAML files directly.

Features:

• Stores 87+ forkable governance variables
• Tracks change proposals and approvals
• Requires Tier 5 governance to modify
• Complete audit trail of all changes
• Automatic sync from YAML on startup

Code: config_registry.rs

3. ConfigReader (Unified Interface)

The ConfigReader provides a type-safe interface for reading configuration values with caching and fallback support.

Features:

• Type-safe accessors (get_i32(), get_f64(), get_bool(), get_string())
• In-memory caching (5-minute TTL)
• Automatic cache invalidation on changes
• Fallback chain support

Code: config_reader.rs

Fallback Chain

The system uses a four-tier fallback chain for configuration values:

1. Cache (in-memory, 5-minute TTL)
   ↓ (if not found)
2. Config Registry (database, governance-controlled)
   ↓ (if not found)
3. YAML Config (file-based, source of truth)
   ↓ (if not found)
4. Hardcoded Defaults (safety fallback)

Implementation: 76:110:blvm-commons/src/governance/config_reader.rs

Sync Mechanisms

sync_from_yaml()

On startup, the system automatically syncs YAML values into the database:

#![allow(unused)]
fn main() {
config_registry.sync_from_yaml(config_path).await?;
}

This process:

1. Loads all YAML configuration files
2. Extracts configuration values using YamlConfigLoader
3. Compares with database values
4. Updates database if no governance history exists (preserves governance-approved changes)

Code: config_registry.rs

sync_to_yaml()

When governance-approved changes are activated, the system can write changes back to YAML files. Full bidirectional sync is planned.

Code: config_registry.rs

Configuration Categories

Configuration parameters are organized into categories:

• FeatureFlags: Feature toggles (e.g., feature_governance_enforcement)
• Thresholds: Signature and veto thresholds (e.g., tier_3_signatures_required)
• TimeWindows: Review periods and time limits (e.g., tier_3_review_period_days)
• Limits: Size and count limits (e.g., max_pr_size_bytes)
• Network: Network-related parameters
• Security: Security-related parameters
• Other: Miscellaneous parameters

87+ Forkable Variables

The system manages 87+ governance-controlled configuration variables, organized into categories:

Complete Configuration Schema

Total: 87+ variables

Code: config_defaults.rs

Action Tier Thresholds (15 variables)

Code: config_defaults.rs

| signaling_tier_5_mining_percent | 50.0 | Tier 5: Mining hashpower for support (%) | | signaling_tier_5_economic_percent | 60.0 | Tier 5: Economic activity for support (%) |

Code: config_defaults.rs

Commons Contributor Thresholds (8 variables)

Code: config_defaults.rs

Governance Phase Thresholds (11 variables)

Code: config_defaults.rs

Repository Layer Thresholds (9 variables)

Code: config_defaults.rs

Complete Reference

For the complete list of all 87+ variables with descriptions and default values, see:

• YAML Source: governance/config/FORKABLE_VARIABLES.md
• Default Values: governance/config/DEFAULT_VALUES_REFERENCE.md
• Implementation: blvm-commons/src/governance/config_defaults.rs

Governance Change Workflow

Changing a configuration parameter requires Tier 5 governance approval:

1. Proposal: Create a configuration change proposal via PR
2. Review: 5-of-5 maintainer signatures required
3. Review Period: 180 days review period
4. Activation: Change activated in database via activate_change()
5. Sync: Change optionally synced back to YAML files

Code: config_registry.rs

Usage Examples

Basic Configuration Access

#![allow(unused)]
fn main() {
use crate::governance::config_reader::ConfigReader;
use crate::governance::config_registry::ConfigRegistry;
use std::sync::Arc;

// Initialize
let registry = Arc::new(ConfigRegistry::new(pool));
let yaml_loader = YamlConfigLoader::new(config_path);
let config = Arc::new(ConfigReader::with_yaml_loader(
    registry.clone(),
    Some(yaml_loader),
));

// Read a value (with fallback)
let review_period = config.get_i32("tier_3_review_period_days", 90).await?;
let veto_threshold = config.get_f64("veto_tier_3_mining_percent", 30.0).await?;
let enabled = config.get_bool("feature_governance_enforcement", false).await?;
}

Convenience Methods

#![allow(unused)]
fn main() {
// Get tier signatures
let (required, total) = config.get_tier_signatures(3).await?;

// Get Commons contributor threshold (with YAML fallback)
let threshold = config.get_commons_contributor_threshold("zaps").await?;
}

Integration with Validators

#![allow(unused)]
fn main() {
// ThresholdValidator with config support
let validator = ThresholdValidator::with_config(config.clone());

// All methods use config registry
let (req, total) = validator.get_tier_threshold(3).await?;
}

Caching Strategy

• Cache TTL: 5 minutes (configurable via cache_ttl)
• Cache Invalidation:
  • Automatic after config changes are activated
  • Manual via clear_cache() or invalidate_key()
• Cache Storage: In-memory HashMap<String, serde_json::Value>

Code: config_reader.rs

YAML Structure

YAML files use a structured format. Example from action-tiers.yml:

tiers:
  - tier: 1
    name: "Routine Maintenance"
    signatures_required: 3
    signatures_total: 5
    review_period_days: 7
  - tier: 3
    name: "Consensus-Adjacent"
    signatures_required: 5
    signatures_total: 5
    review_period_days: 90

The YamlConfigLoader extracts values from these files into a flat key-value structure for the registry.

Code: yaml_loader.rs

Initialization

On system startup:

1. Load YAML Files: System loads YAML configuration files
2. Sync to Database: sync_from_yaml() populates database from YAML
3. Initialize Defaults: initialize_governance_defaults() registers any missing configs
4. Create ConfigReader: ConfigReader created with YAML loader for fallback access

Code: main.rs

Configuration Key Reference

All configuration keys follow a naming convention:

• Tier configs: tier_{n}_{property}
• Layer configs: layer_{n}_{property}
• Veto configs: veto_tier_{n}_{type}_percent
• Commons contributor: commons_contributor_threshold_{type}

Complete Reference: See governance/config/DEFAULT_VALUES_REFERENCE.md for all keys and default values.

Benefits

1. YAML as Source of Truth: Human-readable, version-controlled defaults
2. Governance Control: Database enables governance-approved changes without YAML edits
3. Type Safety: Type-safe accessors prevent configuration errors
4. Performance: Caching reduces database queries
5. Flexibility: Fallback chain ensures system always has valid configuration
6. Audit Trail: Complete history of all configuration changes