272 lines
7.9 KiB
Markdown
272 lines
7.9 KiB
Markdown
# 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
|