BTC Terminology Rules

🚨 CRITICAL: Bech32m vs Taproot

This is a common source of bugs. Do NOT confuse these terms:

| Term | What It Is | Where Used | |------|------------|------------| | bech32m | Encoding format (HOW address is serialized) | Bitcoin Core RPC, shell scripts | | taproot | Address type (WHAT the address represents) | Config files, domain model |

Key Rule: bech32m ≠ taproot — They are related but NOT interchangeable.

Quick Reference Table

| Context | Correct Term | Example | |---------|--------------|---------| | Config YAML/TOML files | taproot | address_type: "taproot" | | Environment variables | taproot | WALLET_ADDRESS_TYPE="taproot" | | Bitcoin Core CLI/RPC | bech32m | bitcoin-cli getnewaddress "" bech32m | | Shell scripts (receiver addresses) | bech32m | getnewaddress "" bech32m | | Go domain code (internal/domain/address/) | taproot | AddrTypeTaproot | | Go Bitcoin Core interface (internal/domain/bitcoin/) | bech32m | AddressTypeTaproot = "bech32m" |

Common Mistakes

❌ WRONG

# Config file - DON'T use bech32m
address_type: "bech32m"  # WRONG!

# Shell script - DON'T use taproot for Bitcoin Core RPC
bitcoin-cli getnewaddress "" taproot  # WRONG!

✅ CORRECT

# Config file - Use taproot
address_type: "taproot"  # CORRECT!

# Shell script - Use bech32m for Bitcoin Core RPC
bitcoin-cli getnewaddress "" bech32m  # CORRECT!

Technical Background

Why Two Different Terms?

Taproot (BIP341) = SegWit version 1 address type (P2TR - Pay-to-Taproot)
Bech32m (BIP350) = Encoding format that fixes checksum issues in original Bech32

All Taproot addresses are encoded using bech32m, but:

User-facing config uses "taproot" (what you want)
Bitcoin Core RPC uses "bech32m" (how it's encoded)

Address Format Comparison

| Encoding | SegWit Version | Address Type | Prefix | Config Value | |----------|----------------|--------------|--------|--------------| | Base58 | N/A | P2PKH | 1... | legacy | | Base58 | N/A | P2SH | 3... | p2sh-segwit | | Bech32 | v0 | P2WPKH | bc1q... | bech32 | | Bech32m | v1 | P2TR | bc1p... | taproot |

Codebase Mapping

The project has two different type definitions:

// internal/domain/bitcoin/address_type.go
// For Bitcoin Core RPC communication
AddressTypeTaproot AddressType = "bech32m"  // Bitcoin Core uses "bech32m"

// internal/domain/address/types.go
// For user-facing configuration
AddrTypeTaproot AddrType = "taproot"  // User sees "taproot"

Conversion between these is handled by mapper functions:

// internal/infrastructure/api/btc/btc/mapper.go
// FromAddressType: "bech32m" (Bitcoin Core) → "taproot" (user-facing)
// ToAddressType:   "taproot" (user-facing) → "bech32m" (Bitcoin Core)

Verification Checklist

When working with Taproot/Bech32m code:

[ ] Config files (YAML/TOML) use address_type: "taproot"
[ ] Environment variables use WALLET_ADDRESS_TYPE="taproot"
[ ] Bitcoin Core RPC calls in shell scripts use bech32m
[ ] Shell scripts generating receiver addresses use bech32m
[ ] Go code uses correct type for the layer:
- Domain/config layer: AddrTypeTaproot (value: "taproot")
- Bitcoin Core interface: AddressTypeTaproot (value: "bech32m")

Related Files

| File | Purpose | |------|---------| | internal/domain/address/types.go | User-facing AddrType definitions | | internal/domain/bitcoin/address_type.go | Bitcoin Core AddressType definitions | | internal/infrastructure/api/btc/btc/mapper.go | Type conversion functions | | docs/crypto/btc/taproot/user-guide.md | Taproot user guide |

btc-terminology