latest versions

2026-02-12 12:26:39 -08:00
parent 82b5ed0b3c
commit 78cadee871
97 changed files with 3288 additions and 124 deletions
--- a/btcphrasechecker/README.md
+++ b/btcphrasechecker/README.md
@@ -0,0 +1,271 @@
+# 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