# 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

```bash
# Clone or download the project
cd btcphrasechecker

# Download dependencies
go mod download

# Build
go build -o btcphrasechecker
```

## Usage

### Basic Usage

```bash
# 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

```bash
# 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:
```go
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

```bash
go build -o btcphrasechecker
```

### Testing

```bash
# Run tests
go test ./...

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

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

### Code Quality

```bash
# 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