go-crypto-wallet

Appearance

Bitcoin (BTC) Technical Reference ​

This document provides a comprehensive technical reference for Bitcoin implementation in the go-crypto-wallet system. It covers specifications, protocol details, and links to official documentation to help AI agents and developers understand Bitcoin's architecture and implement features correctly.

Documentation Structure ​

This directory is organized into the following categories:

File / DirectoryDescriptionAudience
architecture.mdWallet architecture — wallet roles, use case boundary map, Keygen vs Sign signingDevelopers
overview/Fundamental technical references and Bitcoin basicsAll
operations/Wallet operation guides and transaction flowsOperators
keygen/Key generation design and improvementsDevelopers
psbt/PSBT implementation and usage guidesAll
descriptor/Output Descriptor implementationDevelopers
taproot/Taproot (BIP341/BIP86) guidesAll
musig2/MuSig2 multisignature implementationAll
testing/Test procedures and verificationDevelopers
archive/Outdated documentation (reference only)-

Quick Start ​

For Operators ​

  1. Start with operations/wallet-flow.md for wallet setup and transaction flows
  2. Review operations/e2e-transaction-patterns.md for transaction types
  3. See psbt/user-guide.md for offline signing workflows

For Developers ​

  1. Read architecture.md for the wallet boundary map and use case assignments
  2. Read overview/technical-reference.md for Bitcoin protocol fundamentals
  3. Review feature-specific architecture docs: descriptor/architecture.md, musig2/architecture.md
  4. Check psbt/developer-guide.md for PSBT implementation details

Table of Contents ​

  1. Overview
  2. Core Specifications
  3. Address Types & Key Derivation
  4. Transaction Architecture
  5. Signing Mechanisms
  6. Multisig & MuSig2
  7. PSBT (Partially Signed Bitcoin Transactions)
  8. Network & Consensus
  9. Fee Management
  10. Wallet Implementation
  11. RPC & API Reference
  12. Security Considerations
  13. Testing Resources
  14. Official References
  15. Project Documentation

Overview ​

What is Bitcoin? ​

Bitcoin is a decentralized digital currency that operates on a peer-to-peer network without central authority. It uses a UTXO (Unspent Transaction Output) model for tracking ownership and proof-of-work consensus for block validation.

Key Characteristics (2026) ​

PropertyValue
Launch DateJanuary 3, 2009
Block Time~10 minutes
Block Size1-4 MB (with SegWit)
Total Supply21,000,000 BTC
Current Block Reward3.125 BTC (post-2024 halving)
Next Halving~2028 (Block 1,050,000)
Consensus AlgorithmSHA-256 Proof of Work
Cryptographic Curvesecp256k1
Signature AlgorithmsECDSA (legacy), Schnorr (Taproot)

Protocol Upgrades Timeline ​

YearUpgradeKey Features
2017SegWit (BIP141)Transaction malleability fix, increased capacity
2021Taproot (BIP340/341)Schnorr signatures, MAST, privacy improvements
2023BIP327 MuSig2Standardized multi-signature aggregation
2024+OP_CAT (Proposed)Enhanced scripting capabilities

Core Specifications ​

Cryptographic Primitives ​

Elliptic Curve (secp256k1) ​

Bitcoin uses the secp256k1 elliptic curve for all cryptographic operations:

Curve Parameters:
- p = 2^256 - 2^32 - 977
- a = 0
- b = 7
- G = (0x79BE667E..., 0x483ADA77...)
- n = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFE BAAEDCE6AF48A03BBFD25E8CD0364141

Reference:

Hash Functions ​

FunctionUsage
SHA-256Block hashing, TXID calculation, PoW
RIPEMD-160Address generation (hash160 = RIPEMD160(SHA256(x)))
HASH160SHA256 + RIPEMD160 for pubkey hashing
HASH256Double SHA256 for transaction/block hashing
Tagged HashesBIP340 Schnorr signatures (SHA256 with tag)

Data Encoding ​

FormatUsageReference
Base58CheckLegacy addresses (P2PKH, P2SH)Base58Check
Bech32Native SegWit addresses (P2WPKH, P2WSH)BIP173
Bech32mTaproot addresses (P2TR)BIP350
WIFPrivate key encodingWallet Import Format
HexRaw transaction dataStandard hexadecimal

Address Types & Key Derivation ​

Address Types Supported ​

TypeBIPPrefix (Mainnet)Prefix (Testnet)Description
P2PKHBIP441m/nLegacy Pay-to-Public-Key-Hash
P2SHBIP1632Pay-to-Script-Hash
P2SH-P2WPKHBIP4932SegWit wrapped in P2SH
P2WPKHBIP84bc1qtb1qNative SegWit
P2WSHBIP141bc1qtb1qSegWit Script Hash
P2TRBIP86bc1ptb1pTaproot (recommended)

See overview/address-types.md for detailed comparison.

HD Wallet Derivation Paths ​

StandardPathAddress Type
BIP44m/44'/0'/account'/change/indexP2PKH (Legacy)
BIP49m/49'/0'/account'/change/indexP2SH-P2WPKH
BIP84m/84'/0'/account'/change/indexP2WPKH (Native SegWit)
BIP86m/86'/0'/account'/change/indexP2TR (Taproot)

Coin Types:

  • 0' = Bitcoin Mainnet
  • 1' = Bitcoin Testnet/Signet

References:

ScriptPubKey Formats ​

P2PKH:      OP_DUP OP_HASH160 <20-byte pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
P2SH:       OP_HASH160 <20-byte scriptHash> OP_EQUAL
P2WPKH:     0x00 <20-byte pubKeyHash>
P2WSH:      0x00 <32-byte witnessScriptHash>
P2TR:       0x51 <32-byte x-only pubKey>

Transaction Architecture ​

UTXO Model ​

Bitcoin uses the Unspent Transaction Output (UTXO) model:

UTXO = {
    txid:      32-byte transaction hash
    vout:      output index (uint32)
    value:     satoshi amount (int64)
    scriptPubKey: locking script
}

Key Concepts:

  • Each transaction consumes UTXOs (inputs) and creates new UTXOs (outputs)
  • Total inputs must equal outputs + transaction fee
  • UTXOs can only be spent once (double-spend protection)

Transaction Weight & Virtual Size ​

SegWit introduced weight units for fee calculation:

Weight = (Non-witness data × 4) + Witness data
Virtual Size (vBytes) = Weight ÷ 4

Fee = Virtual Size × Fee Rate (sat/vB)

Typical Sizes:

Transaction TypeWeightvBytesFee @ 10 sat/vB
P2PKH (1-in, 2-out)~680~170~1,700 sats
P2WPKH (1-in, 2-out)~440~110~1,100 sats
P2TR (1-in, 2-out)~396~99~990 sats
2-of-3 Multisig (P2WSH)~1,100~275~2,750 sats
2-of-3 MuSig2 (P2TR)~560~140~1,400 sats

Reference:

Signing Mechanisms ​

ECDSA Signatures (Legacy/SegWit) ​

Used for P2PKH, P2SH, P2WPKH, and P2WSH transactions.

Sighash Types:

TypeValueDescription
SIGHASH_ALL0x01Sign all inputs and outputs (default)
SIGHASH_NONE0x02Sign all inputs, no outputs
SIGHASH_SINGLE0x03Sign all inputs, matching output only
SIGHASH_ANYONECANPAY0x80Modifier: sign only current input

Schnorr Signatures (Taproot) ​

Used for P2TR transactions. Introduced with Taproot (BIP340).

Advantages:

  • Fixed 64-byte size (vs variable ECDSA)
  • Linear: enables signature aggregation (MuSig2)
  • Provably secure under standard assumptions
  • Batch verification is faster

See taproot/user-guide.md for details.

Multisig & MuSig2 ​

Traditional Multisig (P2SH/P2WSH) ​

M-of-N Redeem Script:

<M> <PubKey1> <PubKey2> ... <PubKeyN> <N> OP_CHECKMULTISIG

MuSig2 (Schnorr Signature Aggregation) ​

MuSig2 enables N-of-N multisig that appears as single-sig on-chain.

Benefits:

  • 30-50% smaller transactions
  • Maximum privacy (looks like single-sig)
  • Lower fees
  • No on-chain multisig indicator

Critical Security: NONCE MANAGEMENT

  • NEVER reuse nonces - reusing leaks private key
  • Generate fresh nonces for every transaction
  • Delete nonces after signing

See musig2/ for detailed documentation.

PSBT (Partially Signed Bitcoin Transactions) ​

PSBT (BIP174) is the standard format for offline/multi-party signing workflows.

PSBT Workflow ​

1. Creator (Watch Wallet - Online)
   └── Create unsigned PSBT with UTXO data

2. Updater (Optional)
   └── Add metadata (derivation paths, etc.)

3. Signer(s) (Offline Wallets)
   └── Add partial signatures

4. Combiner (Optional)
   └── Combine multiple PSBTs

5. Finalizer (Watch Wallet)
   └── Create final scriptSig/witness

6. Extractor
   └── Extract broadcastable transaction

See psbt/ for detailed documentation.

Network & Consensus ​

Networks ​

NetworkPurposePortRPC PortMagic Bytes
MainnetProduction833383320xF9BEB4D9
Testnet3Public testing18333183320x0B110907
SignetControlled testing38333383320x0A03CF40
RegtestLocal development18444184430xFABFB5DA

Confirmation Guidelines ​

ConfirmationsRisk LevelTypical Use Case
0 (unconfirmed)HighVery small amounts, trusted parties
1MediumSmall retail transactions
3LowMost commerce
6Very LowLarge transactions
100+NoneCoinbase maturity

Fee Management ​

Fee Estimation ​

Bitcoin Core provides fee estimation via RPC:

bash
# Estimate fee for confirmation in N blocks
bitcoin-cli estimatesmartfee <conf_target> [estimate_mode]

# Modes: UNSET, ECONOMICAL, CONSERVATIVE

Fee Rate Sources ​

SourceEndpoint/Method
Bitcoin Coreestimatesmartfee RPC
Mempool.spacehttps://mempool.space/api/v1/fees/recommended
Blockstreamhttps://blockstream.info/api/fee-estimates

Fee Optimization Strategies ​

  1. SegWit/Taproot - Use native SegWit or Taproot for smaller transactions
  2. UTXO Consolidation - Consolidate UTXOs during low-fee periods
  3. Batching - Combine multiple payments in single transaction
  4. RBF - Use Replace-by-Fee for fee bumping if needed

Wallet Implementation ​

Wallet Types in This System ​

WalletRoleNetwork
WatchCreate transactions, broadcast, monitorOnline
KeygenGenerate keys, first signatureOffline (air-gapped)
SignAdditional signatures (multisig)Offline (air-gapped)

Account Types ​

AccountPurposeMultisig
clientCustomer deposit addressesNo
depositAggregate client fundsNo
paymentOutgoing paymentsYes (2-of-3 or 3-of-3)
storedCold storageYes

For the common 3-wallet transaction flow (chain-agnostic), see docs/transaction-flow.md. For BTC-specific procedures and Mermaid diagrams, see operations/wallet-flow.md.

RPC & API Reference ​

Bitcoin Core RPC ​

Essential Commands:

CommandDescription
getblockchaininfoNetwork and sync status
getbalanceWallet balance
listunspentList UTXOs
createrawtransactionCreate raw transaction
signrawtransactionwithkeySign with provided keys
sendrawtransactionBroadcast transaction
gettransactionGet transaction details
walletprocesspsbtProcess PSBT
finalizepsbtFinalize PSBT
decodepsbtDecode/analyze PSBT

Reference:

Go Libraries ​

LibraryPurposeRepository
btcdFull node implementationgithub.com/btcsuite/btcd
btcutilAddress/transaction utilitiesgithub.com/btcsuite/btcd/btcutil
btcecsecp256k1 cryptographygithub.com/btcsuite/btcd/btcec
psbtPSBT implementationgithub.com/btcsuite/btcd/btcutil/psbt
txscriptScript parsing/buildinggithub.com/btcsuite/btcd/txscript

Security Considerations ​

Private Key Security ​

  • NEVER log or expose private keys
  • Use air-gapped systems for key generation and signing
  • Implement proper entropy for key generation
  • Use hardware security modules (HSMs) for production

Transaction Security ​

  • Verify all transaction details before signing
  • Implement multi-signature for high-value accounts
  • Use PSBT for offline signing workflows
  • Validate change addresses

Nonce Security (MuSig2) ​

  • CRITICAL: Never reuse nonces in MuSig2
  • Generate cryptographically secure random nonces
  • Delete nonces immediately after signing

See musig2/security.md for details.

Testing Resources ​

Testnet Faucets ​

NetworkFaucet URL
Testnet3testnet-faucet.com
Signetsignetfaucet.com
Signet (Alt)alt.signetfaucet.com

Block Explorers ​

NetworkExplorer
Mainnetmempool.space
Mainnetblockstream.info
Testnet3mempool.space/testnet
Signetmempool.space/signet
Signetexplorer.bc-2.jp

Development Tools ​

ToolPurpose
Bitcoin CoreFull node reference implementation
btcdebBitcoin script debugger
Sparrow WalletDesktop wallet with PSBT support
ElectrumLightweight wallet

Official References ​

Bitcoin Improvement Proposals (BIPs) ​

Key Management & Addresses ​

BIPTitleStatus
BIP32HD WalletsFinal
BIP39Mnemonic SeedFinal
BIP44Multi-Account HDFinal
BIP49P2SH-P2WPKH DerivationFinal
BIP84Native SegWit DerivationFinal
BIP86Taproot DerivationFinal

SegWit & Taproot ​

BIPTitleStatus
BIP141SegWit ConsensusFinal
BIP143SegWit Signature VerificationFinal
BIP173Bech32 AddressesFinal
BIP340Schnorr SignaturesFinal
BIP341TaprootFinal
BIP342TapscriptFinal
BIP350Bech32m AddressesFinal

PSBT & Transactions ​

BIPTitleStatus
BIP174PSBTFinal
BIP370PSBT Version 2Draft
BIP371Taproot PSBT FieldsDraft
BIP125Replace-by-FeeFinal

Multisig ​

BIPTitleStatus
BIP11M-of-N StandardFinal
BIP16P2SHFinal
BIP327MuSig2Draft

Official Documentation ​

Academic Papers ​

Project Documentation ​

By Category ​

CategoryDocuments
Overviewtechnical-reference.md, address-types.md
Operationswallet-flow.md, e2e-transaction-patterns.md, wallet-flow-improvements-2025.md
Key Generationimprovements-2025.md, interface-design.md
PSBTuser-guide.md, developer-guide.md, implementation.md
Descriptoruser-guide.md, architecture.md, api.md
Taprootuser-guide.md, testing.md
MuSig2user-guide.md, architecture.md, security.md
Testingpattern3-verification.md
ResourceLocation
E2E Test Scriptsscripts/operation/btc/e2e/
Project Testing Standardsdocs/guidelines/testing.md
Security Standardsdocs/guidelines/security.md

Version Information ​

ComponentMinimum VersionRecommended
Bitcoin Corev22.0 (Taproot)v26.0+
btcdv0.24.0Latest
Go1.251.25+

Document Version: 3.0 Last Updated: 2026-01-16 Maintainer: go-crypto-wallet team