---

name: btc-terminology description: Critical Bitcoin terminology rules to prevent confusion between bech32m (encoding) and taproot (address type). Use when working on BTC-related code, config files, or shell scripts.

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

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

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

✅ CORRECT

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

Copy# 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:

Copy// 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:

Copy// 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'/...)