BCH (Bitcoin Cash) Development Rules

🚨 CRITICAL: Override Pattern for BCH-Specific Logic

This is a non-negotiable architectural rule. BCH implementation uses struct embedding with method override pattern.

Architecture Overview

// internal/infrastructure/api/btc/bch/bitcoin_cash.go
type BitcoinCash struct {
    apibtcimpl.Bitcoin  // Embeds BTC implementation
}

Key Principle: BitcoinCash embeds Bitcoin, inheriting all BTC methods by default.

Rules

✅ DO: Override on BCH Side

When BCH requires different logic from BTC:

Create a new file in internal/infrastructure/api/btc/bch/
Implement the method with the same name on BitcoinCash
This "overrides" the embedded Bitcoin method

❌ DON'T: Modify BTC Side for BCH

NEVER modify internal/infrastructure/api/btc/btc/ for BCH-specific requirements
NEVER add BCH conditionals in BTC code
NEVER add BCH-specific types or logic to the BTC package

Why This Pattern?

Reason	Explanation
Separation of Concerns	BTC code remains pure and focused
Maintainability	BCH changes don't affect BTC
Clarity	BCH differences are explicit in BCH directory
Safety	BTC modifications can't accidentally break BCH

Implementation Examples

Example 1: GetAddressInfo Override

BCH has a different response structure for getaddressinfo RPC:

// internal/infrastructure/api/btc/bch/address.go
// BCH-specific response type
type GetAddressInfoResult struct {
    Address      string `json:"address"`
    ScriptPubKey string `json:"scriptPubKey"`
    Label        string `json:"label,omitempty"`  // BCH uses Label (singular)
    Labels       []struct {                       // BCH has different Labels structure
        Name    string `json:"name"`
        Purpose string `json:"purpose"`
    } `json:"labels"`
    // ... other BCH-specific fields
}

// Override GetAddressInfo for BCH
func (b *BitcoinCash) GetAddressInfo(addr string) (*dtobtc.AddressInfo, error) {
    // BCH-specific implementation
    // ...
}

Example 2: GetAccount Override

BCH requires different logic for getting account info:

// internal/infrastructure/api/btc/bch/account.go
func (b *BitcoinCash) GetAccount(addr string) (string, error) {
    // BCH calls GetAddressInfo (which is also overridden)
    res, err := b.GetAddressInfo(addr)
    if err != nil {
        return "", fmt.Errorf("fail to call btc.GetAddressInfo() in bch: %w", err)
    }
    // BCH-specific label extraction
    if len(res.Labels) == 0 {
        return "", nil
    }
    return res.Labels[0], nil
}

Example 3: Chain Parameters Override

BCH has different network magic numbers:

// internal/infrastructure/api/btc/bch/bitcoin_cash.go
const (
    MainnetMagic wire.BitcoinNet = 0xe8f3e1e3  // BCH-specific
    TestnetMagic wire.BitcoinNet = 0xf4f3e5f4  // BCH-specific
    Regtestmagic wire.BitcoinNet = 0xfabfb5da  // BCH-specific
)

func (b *BitcoinCash) initChainParams() {
    // Override chain parameters for BCH
}

BCH vs BTC: Feature Differences

Feature	BTC	BCH
SegWit	✅ Supported	❌ Not supported
Taproot	✅ Supported	❌ Not supported
Address Format	Legacy, SegWit, Taproot	Legacy, CashAddr
Network Magic	BTC values	BCH-specific values

Directory Structure

internal/infrastructure/api/btc/
├── btc/                      # BTC implementation (DO NOT modify for BCH)
│   ├── bitcoin.go            # Bitcoin struct and methods
│   ├── account.go
│   ├── address.go
│   └── ...
├── bch/                      # BCH overrides (ADD new files here)
│   ├── bitcoin_cash.go       # BitcoinCash struct (embeds Bitcoin)
│   ├── account.go            # Override: GetAccount
│   ├── address.go            # Override: GetAddressInfo
│   └── ...
└── connection.go             # Shared connection logic

Checklist for BCH Changes

When implementing BCH-specific logic:

File created in internal/infrastructure/api/btc/bch/ (NOT in btc/)
Method has same signature as the BTC method being overridden
No changes made to internal/infrastructure/api/btc/btc/
BCH-specific types defined in BCH package (if needed)
Error messages include "bch" for traceability

Common Mistakes

❌ WRONG: Adding BCH Logic to BTC

// internal/infrastructure/api/btc/btc/account.go
func (b *Bitcoin) GetAccount(addr string) (string, error) {
    if b.coinTypeCode == domainCoin.BCH {  // DON'T DO THIS!
        // BCH-specific logic
    }
    // BTC logic
}

✅ CORRECT: Override in BCH Package

// internal/infrastructure/api/btc/bch/account.go
func (b *BitcoinCash) GetAccount(addr string) (string, error) {
    // BCH-specific logic here
}

Technical Note: How Go Embedding Works

When BitcoinCash embeds Bitcoin:

All Bitcoin methods are "promoted" to BitcoinCash
If BitcoinCash defines a method with the same name, it takes precedence
The embedded Bitcoin methods can still be called via b.Bitcoin.MethodName()

// Call overridden method (uses BitcoinCash.GetAddressInfo)
info, _ := bch.GetAddressInfo(addr)

// Call embedded method directly (uses Bitcoin.GetAddressInfo)
info, _ := bch.Bitcoin.GetAddressInfo(addr)

Related Files

File	Purpose
`internal/infrastructure/api/btc/bch/bitcoin_cash.go`	BitcoinCash struct definition
`internal/infrastructure/api/btc/btc/bitcoin.go`	Bitcoin struct (embedded by BCH)
`internal/application/ports/btc/interface.go`	Bitcoiner interface

bch-development