Skip to content

Security: BTCDecoded/blvm-node

Security

SECURITY.md

Security Boundaries and Threat Model

This document covers repo-specific security boundaries. See the BTCDecoded Security Policy for organization-wide policy.

Overview

This document defines the security boundaries, threat model, and limitations of the BTCDecoded blvm-node implementation. This is critical for understanding what this node can and cannot do safely.

Operators: deployment exposure classes (RPC / P2P / modules) and required vs recommended vs unsupported combinations are summarized in the BLVM book — Deployment posture — and in RPC transport × authentication.

Security Boundaries

What blvm-node Handles

  • Consensus validation (delegated to blvm-consensus via blvm-protocol)
  • Network protocol (P2P message parsing, peer management)
  • Storage layer (block storage, UTXO set, chain state)
  • RPC interface (JSON-RPC 2.0 API)
  • Module orchestration (loading, IPC, lifecycle management)
  • Mempool management
  • Mining coordination

What blvm-node NEVER Handles

  • Consensus rule validation (delegated to blvm-consensus)
  • Protocol variant selection (delegated to blvm-protocol)
  • Private key management (no wallet functionality)
  • Cryptographic key generation (delegated to blvm-sdk or modules)
  • Governance enforcement (delegated to blvm-commons)

Security Boundaries (Detailed)

✅ IN SCOPE - What This Node Handles

  1. Consensus Validation

    • Block validation using blvm-consensus
    • Transaction validation and script execution
    • Proof of work verification
    • Economic rule enforcement (supply limits, fees)

  2. Network Protocol

    • Bitcoin P2P protocol message parsing
    • Peer connection management
    • Block and transaction relay
    • Network message validation

  3. Storage Layer

    • Block storage and indexing
    • UTXO set management
    • Chain state tracking
    • Transaction indexing

  4. RPC Interface

    • JSON-RPC 2.0 compliant API
    • Blockchain data queries
    • Network status reporting
    • Mining coordination

❌ OUT OF SCOPE - What This Node NEVER Handles

  1. Private Key Management

    • NO private key storage
    • NO private key generation
    • NO wallet functionality
    • NO signing operations

  2. Wallet Operations

    • NO address generation
    • NO transaction creation
    • NO UTXO selection
    • NO change calculation

  3. Mining Operations

    • NO actual mining (proof of work)
    • NO block template generation
    • NO nonce searching
    • NO mining pool coordination

Threat Model

Current Deployment (Pre-Production Testing)

Environment: Trusted network only Timeline: 6-12 months testing phase Threats: Limited to development and testing scenarios

Threats NOT Applicable (Trusted Network)

  • Eclipse attacks
  • Sybil attacks
  • Network partitioning attacks
  • Malicious peer injection

Threats That Apply

  • Code vulnerabilities in consensus validation
  • Memory corruption in parsing
  • Integer overflow in calculations
  • Resource exhaustion (DoS)
  • Supply chain attacks on dependencies

Future Mainnet Deployment

Environment: Public Bitcoin network Timeline: After security audit and hardening Threats: Full Bitcoin network threat model

Additional Threats for Mainnet

  • Eclipse attacks — malicious peers isolate node
  • Sybil attacks — fake peer identities
  • Network partitioning — routing attacks
  • Resource exhaustion — memory/CPU DoS
  • Protocol manipulation — malformed messages

Security Limitations

Current Implementation Limitations

  1. Storage Layer

    • ✅ RocksDB is included in default features (performance path for mainnet-scale IBD)
    • ✅ redb available as --features redb (pure Rust; no default C++ rocksdb)
    • ⚠️ sled available behind --features sled (not recommended for production mainnet)
    • ✅ Database abstraction allows switching backends (database_backend config)
    • ⚠️ No advanced indexing (sufficient for current use case)

  2. Network Layer

    • ✅ Peer management implemented
    • ✅ Rate limiting implemented (token bucket, per-IP connection limits)
    • ✅ DoS protection implemented (connection rate limiting, message queue limits, auto-ban, resource monitoring)

  3. RPC Interface

    • ✅ Authentication implemented (token-based and certificate-based, configurable)
    • ✅ Rate limiting implemented (per-user, per-IP when auth disabled, batch-aware)
    • ✅ IP rate limiting when auth disabled (rate-limit-only mode)
    • ✅ Quinn RPC auth and rate limiting (same model as HTTP RPC)
    • ✅ Batch RPC rate limiting (consumes min(batch_len, 10) tokens)
    • ✅ Connection rate limiting (per-IP per minute for RPC and REST)
    • ✅ REST vault/pool/congestion: oversized body returns 413
    • ✅ Input validation and sanitization
    • ✅ Access control via authentication
    • ⚠️ Certificate auth (S-001): When using certificate-based RPC auth, the RPC endpoint must be behind TLS termination (e.g. nginx, Caddy) that sets the x-client-cert-fingerprint header from the validated client certificate. Without this, the header is spoofable—any client can forge it. If RPC is not behind such TLS, use token-based auth only or disable cert auth.

  4. Consensus Layer

    • Signature verification now uses real transaction hashes ✅
    • All consensus-critical dependencies pinned ✅
    • Proper Bitcoin hashing implemented ✅
    • Network protocol validation added ✅

Security Hardening Roadmap

Phase 1: Pre-Production (Current)

  • Fix signature verification with real transaction hashes
  • Implement proper Bitcoin double SHA256 hashing
  • Pin all dependencies to exact versions
  • Add network protocol input validation
  • Add storage bounds checking
  • Add comprehensive test vectors

Phase 2: Production Readiness

  • Add redb as optional pure-Rust storage backend; RocksDB remains default feature set for performance
  • Add DoS protection mechanisms (connection rate limiting, auto-ban, resource monitoring)
  • Add RPC authentication (token-based and certificate-based)
  • Implement rate limiting (per-user RPC rate limiting, network message rate limiting)
  • Add comprehensive fuzzing (protocol parsing, compact blocks, enhanced edge cases)
  • Add eclipse attack prevention (IP diversity tracking, limits connections from same IP range)
  • Add storage bounds checking (prevents overflow, warns when approaching limits)

Phase 2.5: RPC Security Hardening (Complete)

  • Rate limiting when auth disabled
  • Quinn RPC auth and rate limiting
  • Batch RPC rate limiting
  • RPC connection rate limiting
  • REST vault/pool/congestion error handling (413 for oversized body)

Phase 3: Mainnet Hardening

  • Professional security audit (external, requires security firm)
  • Formal verification of critical paths (property tests for node invariants added)
  • Advanced peer management (connection quality tracking, peer selection, reliability scoring)
  • Performance optimization (performance profiler infrastructure added)
  • Monitoring and alerting (metrics collection, health checks, RPC endpoints)

Usage Guidelines

Safe Usage Patterns

  1. Validation Only

    • Use for block and transaction validation
    • Query blockchain state
    • Monitor network health
    • Educational purposes

  2. Development and Testing

    • Integration testing
    • Consensus rule validation
    • Protocol development
    • Research and analysis

Unsafe Usage Patterns

  1. Never Use For

    • Storing private keys
    • Creating transactions
    • Mining operations
    • Production mainnet without hardening

  2. Security Warnings

    • Never expose RPC to untrusted/public networks without authentication. The node warns at startup when bound to a non-loopback address without auth (rpc_auth.required = false); heed the warning.
    • Do not use for financial operations
    • Do not rely on for consensus without audit
    • Do not use sled storage for production

Dependencies Security

Consensus-Critical Dependencies (Exact Versions)

  • secp256k1 = "=0.28.2" - ECDSA cryptography
  • sha2 = "=0.10.9" - SHA256 hashing
  • ripemd = "=0.1.3" - RIPEMD160 hashing
  • bitcoin_hashes = "=0.11.0" - Bitcoin-specific hashing

Non-Consensus Dependencies (Exact Versions)

  • serde = "=1.0.193" - Serialization
  • anyhow = "=1.0.93" - Error handling
  • thiserror = "=1.0.69" - Error types

Reporting Security Issues

Responsible Disclosure

If you discover a security vulnerability:

  1. DO NOT create public issues
  2. DO NOT discuss publicly
  3. DO report privately to: security@thebitcoincommons.org
  4. DO provide detailed reproduction steps
  5. DO allow reasonable time for fixes

Security Response Process

  1. Acknowledgment within 48 hours
  2. Assessment within 7 days
  3. Fix development within 30 days
  4. Public disclosure after fix deployment

Compliance and Standards

Bitcoin Protocol Compliance

  • Implements Bitcoin consensus rules
  • Interoperates with common chain data and RPC conventions where implemented
  • Follows BIP specifications
  • Maintains protocol compatibility

Security Standards

  • Follows Rust security best practices
  • Implements defense in depth
  • Uses secure coding patterns
  • Maintains audit trail

Conclusion

This blvm-node implementation provides a solid foundation for Bitcoin consensus validation but is NOT suitable for production mainnet use without significant hardening. It is designed for:

  • Educational purposes
  • Development and testing
  • Consensus rule validation
  • Research and analysis

For production use, additional security hardening, professional audit, and mainnet-specific protections are required.

Last Updated: April 2026
Version: 0.1.0
Status: Pre-Production Testing

There aren't any published security advisories