Bitcoin Commons Developer SDK

Governance infrastructure and composition framework for Bitcoin implementations.

For verified system status: See SYSTEM_STATUS.md in the BTCDecoded organization repository.

Provides the institutional layer for Bitcoin governance, offering reusable governance primitives and a composition framework for building alternative Bitcoin implementations.

Architecture Position

Tier 5 of the 6-tier Bitcoin Commons architecture (BLVM technology stack):

1. blvm-spec (Orange Paper - mathematical foundation)
2. blvm-consensus (pure math implementation)
3. blvm-protocol (Bitcoin abstraction)
4. blvm-node (full node implementation)
5. blvm-sdk (composition + governance libraries)
6. blvm-commons (governance enforcement)

Core Components

Governance Primitives

Cryptographic key management for governance operations
Signature creation and verification using Bitcoin-compatible standards
Multisig threshold logic for collective decision making
Nested multisig support for team-based governance
Message formats for releases, module approvals, and budget decisions

CLI Tools

blvm-keygen - Generate governance keypairs
blvm-sign - Sign governance messages
blvm-verify - Verify signatures and multisig thresholds
blvm-compose - Declarative node composition from modules
blvm-sign-binary - Sign binary files
blvm-verify-binary - Verify binary file signatures
blvm-aggregate-signatures - Aggregate multiple signatures

Composition Framework

Declarative node composition from modules
Module registry and lifecycle management
Economic integration through merge mining

Quick Start

As a Library

use blvm_sdk::governance::{
    GovernanceKeypair, GovernanceMessage, Multisig
};

// Generate a keypair
let keypair = GovernanceKeypair::generate()?;

// Create a message to sign
let message = GovernanceMessage::Release {
    version: "v1.0.0".to_string(),
    commit_hash: "abc123".to_string(),
};

// Sign the message
let signature = keypair.sign(&message.to_signing_bytes())?;

// Verify with multisig
let multisig = Multisig::new(6, 7, maintainer_keys)?;
let valid = multisig.verify(&message.to_signing_bytes(), &[signature])?;

CLI Usage

# Generate a keypair
blvm-keygen --output alice.key --format pem

# Sign a release
blvm-sign release \
  --version v1.0.0 \
  --commit abc123 \
  --key alice.key \
  --output signature.txt

# Verify signatures
blvm-verify release \
  --version v1.0.0 \
  --commit abc123 \
  --signatures sig1.txt,sig2.txt,sig3.txt,sig4.txt,sig5.txt,sig6.txt \
  --threshold 6-of-7 \
  --pubkeys keys.json

Features

Governance Primitives: Cryptographic key management and signature verification
CLI Tools: blvm-keygen, blvm-sign, blvm-verify, blvm-compose, blvm-sign-binary, blvm-verify-binary, blvm-aggregate-signatures
Multisig Support: Threshold logic for collective decision making
Bitcoin-Compatible: Uses Bitcoin message signing standards
Composition Framework: Declarative node composition from modules

Design Principles

Governance Crypto is Reusable: Clean library API for external consumers
No GitHub Logic: SDK is pure cryptography + composition, not enforcement
Bitcoin-Compatible: Use Bitcoin message signing standards
Test Everything: Governance crypto needs 100% test coverage
Document for Consumers: Teams building integrations on top of governance crypto and composition are the audience for this SDK.

What This Is NOT

NOT a general-purpose Bitcoin library
NOT the GitHub enforcement engine (that is blvm-commons)
NOT handling wallet keys or user funds
NOT competing with rust-bitcoin or BDK

Security

See SECURITY.md for security policies and BTCDecoded Security Policy for organization-wide guidelines.

crates.io

The published crate is blvm-sdk on crates.io. In the monorepo, Cargo.toml uses a path to blvm-node and blvm-sdk-macros. For published versions only:

[dependencies]
blvm-sdk = ">=0.1, <1"

Use [patch.crates-io] in .cargo/config.toml if you need to override with local sibling paths.

Contributing

See CONTRIBUTING.md and the BTCDecoded Contribution Guide.

License

MIT License - see LICENSE file for details.

blvm-sdk 0.1.7