QSBitcoin Technical Specification
This document outlines all technical differences between QSBitcoin and standard Bitcoin Core v28.0. QSBitcoin adds quantum-safe signatures via a soft fork while maintaining full backward compatibility.
Table of Contents
1. Overview of Changes
QSBitcoin is a soft fork of Bitcoin Core that adds post-quantum cryptographic signatures. Here's what's new:
Key Differences from Bitcoin:
- New Signature Algorithms: ML-DSA-65 and SLH-DSA-192f (NIST-standardized)
- Unified Opcodes: OP_CHECKSIG_EX and OP_CHECKSIGVERIFY_EX
- Large Signatures: Up to 35KB (vs 71 bytes for ECDSA)
- No HD Derivation: Quantum keys cannot be derived from a seed
- Variable Weight Factors: 3x for ML-DSA, 2x for SLH-DSA
- Fee Structure: Standard fees based on transaction size
| Component | Bitcoin Core | QSBitcoin | Change Type |
|---|---|---|---|
| Signature Algorithms | ECDSA, Schnorr | ECDSA, Schnorr, ML-DSA-65, SLH-DSA-192f | Addition |
| Script Opcodes | Standard opcodes | + OP_CHECKSIG_EX, OP_CHECKSIGVERIFY_EX | Addition |
| Max Signature Size | ~71 bytes | 50,000 bytes | Modification |
| Transaction Weight | Fixed 4x witness | Variable: 4x ECDSA, 3x ML-DSA, 2x SLH-DSA | Modification |
| Script Flags | Standard flags | + SCRIPT_VERIFY_QUANTUM_SIGS (bit 21) | Addition |
2. New Cryptographic Primitives
2.1 Signature Algorithms
ML-DSA-65 (Module-Lattice Digital Signature Algorithm)
- Algorithm ID: 0x02
- Public Key Size: 1,952 bytes
- Private Key Size: 4,032 bytes
- Signature Size: ~3,309 bytes
- Security Level: NIST Level 3
- Use Case: Standard transactions (99% of cases)
- Fee Structure: Standard fees based on size
SLH-DSA-192f (Stateless Hash-Based Digital Signature Algorithm)
- Algorithm ID: 0x03
- Public Key Size: 48 bytes
- Private Key Size: 96 bytes
- Signature Size: ~35,664 bytes
- Security Level: NIST Level 3
- Use Case: High-value cold storage
- Fee Structure: Standard fees based on size
2.2 Key Differences from Bitcoin Keys
| Property | Bitcoin (ECDSA) | QSBitcoin (Quantum) |
|---|---|---|
| Key Derivation | BIP32 HD derivation supported | No derivation - each key needs fresh entropy |
| Key Copyability | Keys are copyable | Non-copyable, move-only semantics |
| Memory Management | Standard memory handling | Secure erasure required |
| RNG Source | GetStrongRandBytes() | Same, via liboqs callback |
// Quantum key classes (simplified)
class CQuantumKey {
uint8_t algorithm_id; // 0x02 (ML-DSA) or 0x03 (SLH-DSA)
vector<uint8_t> key_data; // Private key material
// Non-copyable, move-only semantics
};
class CQuantumPubKey {
uint8_t algorithm_id;
vector<uint8_t> key_data; // Public key material
};
3. New Opcodes
Unified Opcode Design
QSBitcoin uses just 2 new opcodes that support all quantum algorithms. The algorithm is identified by the first byte of the signature data, not the opcode itself.
| Opcode | Hex Value | Previous Use | New Function |
|---|---|---|---|
| OP_CHECKSIG_EX | 0xb3 | OP_NOP4 | Extended checksig for quantum signatures |
| OP_CHECKSIGVERIFY_EX | 0xb4 | OP_NOP5 | Extended checksig and verify for quantum signatures |
3.1 Signature Format
// Quantum signature format in witness data
[algorithm_id:1 byte][signature_data][sighash_type:1 byte]
// Example for ML-DSA signature
0x02 [3309 bytes of signature] 0x01
// Example for SLH-DSA signature
0x03 [35664 bytes of signature] 0x01
3.2 Witness Script Format
// All quantum addresses use P2WSH with this witness script:
<pubkey> OP_CHECKSIG_EX
// The algorithm is NOT stored in the witness script
// It's determined from the signature during verification
4. Consensus Rule Changes
4.1 Soft Fork Activation
| Parameter | Value |
|---|---|
| Deployment Name | DEPLOYMENT_QUANTUM_SIGS |
| BIP9 Bit | 3 |
| Script Flag | SCRIPT_VERIFY_QUANTUM_SIGS (bit 21) |
| Mainnet Status | NEVER_ACTIVE (awaiting parameters) |
| Testnet/Regtest Status | ALWAYS_ACTIVE |
4.2 Transaction Limits
| Limit | Bitcoin Core | QSBitcoin |
|---|---|---|
| MAX_STANDARD_TX_WEIGHT | 400,000 | 400,000 (unchanged) |
| MAX_STANDARD_TX_WEIGHT_QUANTUM | N/A | 1,000,000 (1MB) |
| MAX_SCRIPT_ELEMENT_SIZE | 520 bytes | Bypassed for quantum when flag active |
| MAX_STANDARD_QUANTUM_SIGS | N/A | 10 per transaction |
| MAX_STANDARD_QUANTUM_SIG_SIZE | N/A | 50,000 bytes |
4.3 Weight Calculation
Important: Variable Weight Factors
Unlike Bitcoin which uses a fixed 4x weight factor for all witness data, QSBitcoin uses variable factors based on actual validation costs.
// Weight calculation formula
if (is_quantum_signature):
if (algorithm == ML_DSA):
weight = base_size + (witness_size * 3) // 25% discount
elif (algorithm == SLH_DSA):
weight = base_size + (witness_size * 2) // 50% discount
else:
weight = base_size + (witness_size * 4) // Standard Bitcoin
5. Transaction Format Changes
5.1 Input Structure
Quantum signatures in transaction inputs follow a specific format:
| Field | Size | Description |
|---|---|---|
| Algorithm ID | 1 byte | 0x02 for ML-DSA, 0x03 for SLH-DSA |
| Signature Data | Variable | ~3.3KB for ML-DSA, ~35KB for SLH-DSA |
| Sighash Type | 1 byte | Standard Bitcoin sighash types |
5.2 Fee Structure
// Fee calculation for quantum transactions
// Fees are based purely on transaction size
// Quantum signatures are larger, so fees are proportionally higher
fee = calculate_standard_fee(tx_size)
// Example sizes:
// ECDSA signature: ~71 bytes
// ML-DSA signature: ~3,309 bytes
// SLH-DSA signature: ~35,664 bytes
6. Address Format
No Special Address Format
Quantum addresses use standard P2WSH (Pay-to-Witness-Script-Hash) format. They are indistinguishable from regular P2WSH addresses, preserving privacy.
| Network | Address Prefix | Length | Example |
|---|---|---|---|
| Mainnet | bc1q | 62 characters | bc1q... |
| Testnet | tb1q | 62 characters | tb1q... |
| Regtest | bcrt1q | 64 characters | bcrt1q... |
Address Generation Process
1. Generate quantum key pair (ML-DSA or SLH-DSA)
2. Create witness script: <pubkey> OP_CHECKSIG_EX
3. Hash witness script with SHA256
4. Encode as bech32 P2WSH address
7. Wallet Changes
7.1 Descriptor Support
QSBitcoin adds a new descriptor type for quantum addresses:
// Quantum descriptor format
qpkh(<quantum_key>, <algorithm>)
// Examples:
qpkh(0x02abcd..., ml-dsa) // ML-DSA address
qpkh(0x03ef01..., slh-dsa) // SLH-DSA address
7.2 Key Storage
| Property | ECDSA Keys | Quantum Keys |
|---|---|---|
| Storage Location | Wallet database | Wallet database (descriptor-based) |
| HD Support | Yes (BIP32) | No - each key is independent |
| Backup Method | Seed phrase | Individual key backup required |
| Encryption | Wallet passphrase | Same wallet passphrase |
8. RPC Interface Changes
8.1 Modified Commands
| Command | New Parameters | Description |
|---|---|---|
| getnewaddress | algorithm: "ml-dsa"|"slh-dsa" | Generate quantum-safe address |
| getrawchangeaddress | algorithm: "ml-dsa"|"slh-dsa" | Get quantum change address |
| estimatesmartfee | signature_type: "ecdsa"|"ml-dsa"|"slh-dsa" | Estimate fees for quantum tx |
8.2 New 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 with quantum signatures
estimatetxfee conf_target "ml-dsa|slh-dsa"
9. Network Protocol
Minimal Protocol Changes
QSBitcoin requires minimal network protocol changes due to its soft fork design. Non-upgraded nodes see quantum transactions as valid.
| Aspect | Change Required | Description |
|---|---|---|
| P2P Messages | No | Existing messages handle larger transactions |
| Service Flags | Optional | NODE_QUANTUM (1 << 24) for future use |
| Version Handshake | No | Soft fork compatible |
| Block Propagation | No | Standard block relay works |
10. Migration Path
10.1 User Migration
For Users
- Update to QSBitcoin-compatible wallet
- Generate new quantum address:
getnewaddress "" "bech32" "ml-dsa" - Transfer funds from ECDSA to quantum address
- Enjoy quantum-safe protection
For Services
- Update Bitcoin Core to QSBitcoin
- No changes needed for receiving
- Update fee estimation for quantum transactions
- Optionally generate quantum addresses
10.2 Timeline
| Phase | Status | Description |
|---|---|---|
| 1. Development | 🚧 In Progress | Core implementation with ongoing development |
| 2. Testnet | ✅ Active | Fully operational on testnet/regtest |
| 3. Mainnet Activation | ⏳ Pending | Awaiting community consensus |
| 4. Adoption | Future | Gradual user migration |
Full Technical Documentation
For the complete technical specification including implementation details, test vectors, and code examples, see the official Spec.md in the QSBitcoin repository.