QSBitcoin for Developers

Implementation Overview

QSBitcoin is a quantum-safe fork of Bitcoin Core v28.0 that adds NIST-standardized post-quantum signatures via a soft fork. The implementation is under active development with core features operational on testnet/regtest.

Key Architecture Components

• Signature Abstraction Layer: ISignatureScheme interface for algorithm independence
• Unified Opcodes: OP_CHECKSIG_EX (0xb3) and OP_CHECKSIGVERIFY_EX (0xb4)
• Quantum Key Classes: CQuantumKey and CQuantumPubKey (non-copyable, move-only)
• Soft Fork Flag: SCRIPT_VERIFY_QUANTUM_SIGS (bit 21)
• BIP9 Deployment: DEPLOYMENT_QUANTUM_SIGS (bit 3)

Source Code & Documentation

• Repository: github.com/qsbitcoin/qsbitcoin
• Technical Spec: See Specification page or Spec.md in the repository
• License: MIT (open source)
• Base: Bitcoin Core v28.0

RPC Interface

QSBitcoin extends Bitcoin Core's RPC interface with quantum-specific commands:

Extended Commands

# Generate quantum address
getnewaddress "label" "bech32" "ml-dsa|slh-dsa"

# Estimate fees for quantum transactions
estimatesmartfee conf_target "ECONOMICAL" "ml-dsa|slh-dsa"

# Sign message with any algorithm
signmessage "address" "message"

# Verify quantum signatures
verifymessage "address" "signature" "message"

New Quantum Commands

# Get quantum wallet information
getquantuminfo
# Returns:
{
  "enabled": true,
  "algorithms": ["ml-dsa", "slh-dsa"],
  "address_count": {
    "ml-dsa": 5,
    "slh-dsa": 2
  },
  "activation_status": "active"
}

# Estimate transaction fee
estimatetxfee conf_target "ml-dsa|slh-dsa"

Implementation Guide

To create a compatible quantum-safe Bitcoin implementation:

1. Implement Signature Interface

class ISignatureScheme {
    virtual bool Sign(const uint256& hash, vector& sig) = 0;
    virtual bool Verify(const uint256& hash, const vector& sig) = 0;
    virtual size_t GetPublicKeySize() = 0;
    virtual size_t GetPrivateKeySize() = 0;
    virtual size_t GetSignatureSize() = 0;
};

2. Script Interpreter Modifications

• Add quantum opcode handlers in script/interpreter.cpp
• Implement EvalChecksigQuantum() function
• Extract algorithm_id from signature (first byte)
• Bypass 520-byte push limit when SCRIPT_VERIFY_QUANTUM_SIGS is set

3. Consensus Rules

• Add SCRIPT_VERIFY_QUANTUM_SIGS flag to mandatory flags after activation
• Implement soft fork activation via BIP9
• Set transaction limits: 1MB max weight, 10 signatures max
• Apply weight factors: 3x for ML-DSA, 2x for SLH-DSA

4. Wallet Integration

• Implement quantum descriptor: qpkh(quantum_key, algorithm)
• Extend SigningProvider with quantum key methods
• Add quantum key storage (non-HD, no derivation)
• Update RPC commands for quantum operations

Critical Implementation Notes

Key Differences from Bitcoin

• Non-copyable keys: Quantum keys use move-only semantics
• No HD derivation: Each quantum address needs fresh entropy
• Large signatures: ML-DSA ~3.3KB, SLH-DSA ~35KB
• Variable weights: Different weight factors per algorithm
• Unified opcodes: Algorithm determined from signature data

Common Pitfalls to Avoid

• Witness corruption: Multiple SPKMs can corrupt witness - store/restore on failure
• Push size limits: Must bypass MAX_SCRIPT_ELEMENT_SIZE for quantum data
• RNG configuration: Use Bitcoin Core's GetStrongRandBytes() for all quantum keys
• Algorithm detection: Auto-detect by public key size (1952 bytes = ML-DSA, 48 bytes = SLH-DSA)

Testing Your Implementation

Essential test cases for quantum-safe implementations:

Unit Tests

1. Generate quantum addresses and verify bech32 encoding
2. Create and sign quantum transactions
3. Verify cross-compatibility with reference implementation
4. Test soft fork activation on regtest
5. Validate fee calculations with discounts
6. Test witness script execution with quantum opcodes

Integration Tests

# Run quantum-specific tests
./build/bin/test_bitcoin -t "*quantum*"

# Test on regtest network
bitcoind -regtest -fallbackfee=0.00001
bitcoin-cli -regtest getnewaddress "" "bech32" "ml-dsa"
bitcoin-cli -regtest generatetoaddress 101 "address"

# Functional tests
build/test/functional/test_runner.py wallet_quantum.py

Contributing to QSBitcoin

We welcome contributions to the reference implementation:

• Code Review: Review pull requests on GitHub
• Testing: Test edge cases and report issues
• Documentation: Improve technical docs and examples
• Optimization: Help optimize quantum signature verification
• Tools: Build analysis tools and block explorers

See the Development page for contribution guidelines.