sneak/hacks
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
78cadee871
hacks/btcphrasechecker/README.md
sneak 78cadee871 latest versions
2026-02-12 12:26:39 -08:00

272 lines
7.9 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink