BTC Terminology Rules

BTC Terminology Rules

🚨 CRITICAL: Bech32m vs Taproot

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

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

Quick Reference Table

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?

1. Taproot (BIP341) = SegWit version 1 address type (P2TR - Pay-to-Taproot)
2. 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

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

Related Documentation

• BIP350 - Bech32m specification
• BIP341 - Taproot specification
• BIP86 - Taproot key derivation (m/​86'/​...)