hiromaily 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")
- Domain/config layer:
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/chains/btc/taproot/user-guide.md |
Taproot user guide |