hacks/btcphrasechecker

Bitcoin Phrase Checker

A modular and extensible Go program that derives Bitcoin addresses from a BIP39 mnemonic phrase and provides comprehensive transaction history and balance analysis using public APIs.

Features

Core Functionality

• BIP39 Support: Validates and processes mnemonic phrases (12/24 words) with optional passphrases
• Multi-Path Derivation: Automatically derives addresses from standard Bitcoin derivation paths:
  • BIP44 (Legacy): m/44'/0'/0'/0 - P2PKH addresses (starting with 1...)
  • BIP49 (SegWit): m/49'/0'/0'/0 - P2SH-wrapped SegWit (starting with 3...)
  • BIP84 (Native SegWit): m/84'/0'/0'/0 - Bech32 addresses (starting with bc1...)
• Comprehensive Analysis: For each address, displays:
  • Current balance
  • Total received amount
  • Total sent amount
  • Transaction count
  • Derivation path

Transaction History

• Chronological Display: Shows all transactions sorted by date (YYYY-MM-DD format)
• Running Balance: Calculates and displays balance after each transaction
• Transaction Types: Identifies received, sent, and self-transfer transactions
• Detailed Statistics:
  • Total received amount and count
  • Total sent amount and count
  • Transaction confirmation status

Architecture

• Modular Design: Organized into separate packages for easy extension
  • types/: Common interfaces and data structures
  • bitcoin/: Bitcoin-specific implementation (derivation, API, analysis)
  • Ready for additional blockchain support (e.g., Ethereum)
• Testable: Comprehensive test suite with network tests using known mnemonic
• Public API Integration: Uses Blockstream.info API with built-in rate limiting

Installation

# Clone or download the project
cd btcphrasechecker

# Download dependencies
go mod download

# Build
go build -o btcphrasechecker

Usage

Basic Usage

# Check wallet with mnemonic only
./btcphrasechecker -mnemonic "your twelve or twenty four word mnemonic phrase here"

# With optional passphrase
./btcphrasechecker -mnemonic "your mnemonic phrase" -passphrase "your passphrase"

# Customize number of addresses to check (default: 20)
./btcphrasechecker -mnemonic "your mnemonic" -count 50

Example Output

Bitcoin Wallet Analysis
======================

Checking BIP44 (Legacy): m/44'/0'/0'/0 - P2PKH addresses (1...)
-----------------------------------------------------------
  1LqBGSKuX5yYUonjxT5qGfpUsXKYYWeabA
    Path:     m/44'/0'/0'/0/0
    Balance:  0.00000000 BTC
    Received: 0.01146203 BTC
    Sent:     0.01146203 BTC
    Txs:      46

Checking BIP49 (SegWit): m/49'/0'/0'/0 - P2SH-wrapped SegWit (3...)
-----------------------------------------------------------
  37VucYSaXLCAsxYyAPfbSi9eh4iEcbShgf
    Path:     m/49'/0'/0'/0/0
    Balance:  0.00000000 BTC
    Received: 0.06783787 BTC
    Sent:     0.06783787 BTC
    Txs:      22

Checking BIP84 (Native SegWit): m/84'/0'/0'/0 - Bech32 addresses (bc1...)
-----------------------------------------------------------
  bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu
    Path:     m/84'/0'/0'/0/0
    Balance:  0.00000000 BTC
    Received: 0.04021550 BTC
    Sent:     0.04021550 BTC
    Txs:      166

Fetching transaction history...

======================
Summary
======================
Total Balance:        0.00000000 BTC
Total Received:       0.16710427 BTC (94 transactions)
Total Sent:           0.16710427 BTC (91 transactions)
Total Transactions:   360
Active Addresses:     44

Active Addresses Summary:
-----------------------------------------------------------
  1LqBGSKuX5yYUonjxT5qGfpUsXKYYWeabA
    Path:     m/44'/0'/0'/0/0
    Balance:  0.00000000 BTC
    Received: 0.01146203 BTC
    Sent:     0.01146203 BTC
    Txs:      46

======================
Transaction History
======================
Date                 Type         Confirmed  Amount (BTC)    Balance (BTC)  TxID
---------------------------------------------------------------------------------------------------------------------------
2014-11-09 03:31:39  + Received   Yes          0.00130000      0.00130000  d6f136091b72cb4f...
2014-11-18 07:42:59  - Sent       Yes          0.00130000      0.00000000  f0ac3836d27b2914...
2015-02-13 04:23:20  + Received   Yes          0.00016924      0.00016924  762ff05a44abf82e...
...

Testing

The project includes a comprehensive test suite that uses the well-known test mnemonic:

abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about

Run Tests

# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run specific test
go test -v ./bitcoin -run TestDeriveAddresses

# Run with network timeout (tests make real API calls)
go test ./... -timeout 5m

Test Coverage

• Derivation Tests: Verifies correct address generation for all BIP standards
• API Tests: Tests Blockstream API integration with real network calls
• Integration Tests: End-to-end wallet analysis with the test mnemonic
• Passphrase Tests: Validates different seeds from different passphrases
• Known Address Tests: Validates against known good addresses

Project Structure

btcphrasechecker/
├── main.go                  # Main entry point and CLI handling
├── main_test.go             # Integration tests
├── go.mod                   # Go module dependencies
├── README.md                # This file
│
├── types/
│   └── types.go            # Common types and interfaces
│
└── bitcoin/
    ├── derivation.go       # BIP32/44/49/84 address derivation
    ├── derivation_test.go  # Derivation tests
    ├── api.go              # Blockstream API client
    ├── api_test.go         # API tests
    └── analyzer.go         # Wallet analysis logic

Extensibility

The codebase is designed to be easily extensible for additional blockchain support:

1. Add New Chain: Implement the ChainAnalyzer interface in types/types.go
2. Create Package: Add a new package (e.g., ethereum/) with chain-specific logic
3. Update Main: Add chain selection logic in main.go

Example interface:

type ChainAnalyzer interface {
    DeriveAddresses(seed []byte, count int) ([]AddressInfo, error)
    GetAddressInfo(address string) (balance, txCount uint64, received, sent uint64, err error)
    GetTransactions(address string) ([]Transaction, error)
    GetChain() Chain
}

Security Notes

• Never share your mnemonic phrase - This tool is for authorized wallet analysis only
• Read-only: This tool only reads blockchain data; it cannot spend funds
• Public API: Uses Blockstream.info public API which may log requests
• Privacy: For maximum privacy, consider using a VPN or running your own Bitcoin node with API
• Rate Limiting: 100ms delay between requests to avoid API throttling
• No Key Export: Private keys are never exposed or stored

Dependencies

• github.com/tyler-smith/go-bip39 - BIP39 mnemonic implementation
• github.com/btcsuite/btcd - Bitcoin library suite including:
  • Address generation and encoding
  • BIP32 HD key derivation
  • Script building for P2SH-wrapped SegWit

Development

Building

go build -o btcphrasechecker

Testing

# Run tests
go test ./...

# Run with coverage
go test -cover ./...

# Run with race detection
go test -race ./...

Code Quality

# Format code
go fmt ./...

# Lint code (requires golangci-lint)
golangci-lint run

# Vet code
go vet ./...

Future Enhancements

• Ethereum support
• Bitcoin testnet support
• Custom derivation paths
• Export to CSV/JSON
• Local Bitcoin Core RPC support
• UTXO tracking
• Multi-signature wallet support
• Hardware wallet integration

License

MIT

Contributing

Contributions are welcome! Please ensure:

• All tests pass
• Code is formatted with go fmt
• New features include tests
• Security best practices are followed