Layer-Tier Governance Model

Overview

Bitcoin Commons implements dual-dimensional governance combining Layers (repository architecture) and Tiers (action classification). When both apply, the system uses the most restrictive wins rule, taking the highest signature requirement and longest review period.

PR action tiers (1–5) are defined in governance action-tiers.yml with narrative in docs/ACTION_TIERS.md. Emergency classes use emergency-tiers.yml only.

Layer System

The layer system maps repository architecture to governance requirements:

Layer	Repository	Purpose	Signatures	Review Period
1	blvm-spec	Constitutional	6-of-7	180 days
2	blvm-consensus	Constitutional	6-of-7	180 days
3	blvm-protocol	Implementation	4-of-5	90 days
4	blvm-node / blvm	Application	3-of-5	60 days
5	blvm-sdk	Extension	2-of-3	14 days

Note: For consensus rule changes, Layer 1–2 require 365 days review period.

Tier System

The tier system classifies changes by action type:

Tier	Type	Signatures	Review Period
1	Routine Maintenance	3-of-5	7 days
2	Feature Changes	4-of-5	30 days
3	Consensus-Adjacent	5-of-5	90 days
4	Emergency Actions	4-of-5	0 days
5	Governance Changes	5-of-5	180 days

Tier 5 special process (wider maintainer pool and emergency keyholders) is documented in governance GOVERNANCE.md, not in action-tiers.yml.

Combination Rules

When both Layer and Tier requirements apply, the system takes the most restrictive (highest) requirements:

Layer	Tier	Final Signatures	Final Review	Source
1	1	6-of-7	180 days	Layer 1
1	2	6-of-7	180 days	Layer 1
1	3	6-of-7	180 days	Layer 1
1	4	6-of-7	180 days	Layer 1
1	5	6-of-7	180 days	Layer 1
2	1	6-of-7	180 days	Layer 2
2	2	6-of-7	180 days	Layer 2
2	3	6-of-7	180 days	Layer 2
2	4	6-of-7	180 days	Layer 2
2	5	6-of-7	180 days	Layer 2
3	1	4-of-5	90 days	Layer 3
3	2	4-of-5	90 days	Layer 3
3	3	5-of-5	90 days	Tier 3
3	4	4-of-5	90 days	Layer 3
3	5	5-of-5	180 days	Tier 5
4	1	3-of-5	60 days	Layer 4
4	2	4-of-5	60 days	Combined Layer 4 + Tier 2
4	3	5-of-5	90 days	Tier 3
4	4	4-of-5	60 days	Combined Layer 4 + Tier 4
4	5	5-of-5	180 days	Tier 5
5	1	3-of-5	14 days	Combined Layer 5 + Tier 1
5	2	4-of-5	30 days	Tier 2
5	3	5-of-5	90 days	Tier 3
5	4	4-of-5	14 days	Combined Layer 5 + Tier 4
5	5	5-of-5	180 days	Tier 5

Examples

Example	Layer	Tier	Result	Source
Bug fix in blvm-protocol	3 (4-of-5, 90d)	1 (3-of-5, 7d)	4-of-5, 90d	Layer 3
New feature in blvm-sdk	5 (2-of-3, 14d)	2 (4-of-5, 30d)	4-of-5, 30d	Tier 2
Consensus change in blvm-spec	1 (6-of-7, 180d)	3 (5-of-5, 90d)	6-of-7, 180d	Layer 1
Emergency fix in blvm-node	4 (3-of-5, 60d)	4 (4-of-5, 0d)	4-of-5, 60d	Combined Layer 4 + Tier 4

Implementation

Code: threshold.rs

#![allow(unused)]
fn main() {
pub fn get_combined_requirements(layer: i32, tier: u32) -> (usize, usize, i64) {
    let (layer_sigs_req, layer_sigs_total) = Self::get_threshold_for_layer(layer);
    let layer_review = Self::get_review_period_for_layer(layer, false);
    let (tier_sigs_req, tier_sigs_total) = Self::get_tier_threshold(tier);
    let tier_review = Self::get_tier_review_period(tier);
    // Take most restrictive
    (layer_sigs_req.max(tier_sigs_req), layer_sigs_total.max(tier_sigs_total), layer_review.max(tier_review))
}
}

Test: cd blvm-commons && cargo test threshold

Published tables above are derived from the same max-rule at book build time (mdbook-governance-vars). Merge enforcement in blvm-commons still uses hardcoded values in threshold.rs until that code loads YAML (see plan backlog).

Configuration

config/repository-layers.yml - Layer definitions
config/action-tiers.yml - Tier definitions (docs/ACTION_TIERS.md)
config/emergency-tiers.yml - Emergency classes (separate from action tiers)
config/tier-classification-rules.yml - PR classification

BLVM Documentation