diff --git a/README.md b/README.md new file mode 100644 index 0000000..4f16a5b --- /dev/null +++ b/README.md @@ -0,0 +1,313 @@ +# Bitcoin P2PK Scanner + +Scanner di transazioni Bitcoin Pay-to-Public-Key (P2PK) per scopi educativi e di ricerca sulla blockchain. + +## ⚠️ Disclaimer + +**Questo progetto è SOLO per scopi educativi e di ricerca.** +- Non utilizzare per attività illegali +- Rispetta sempre i termini di servizio delle API utilizzate +- Lo scopo è studiare la struttura della blockchain Bitcoin + +## Caratteristiche + +- Scansione blocchi Bitcoin per identificare transazioni P2PK +- Salvataggio dati in database SQLite +- Verifica UTXO (controllo se le chiavi hanno ancora saldo) +- Report HTML interattivo con ricerca e statistiche +- Esportazione dati in CSV +- Scansione incrementale (riprende da dove si è fermato) +- API mempool.space con rate limiting integrato + +## Installazione + +### 1. Clona il repository + +### 2. Crea l'ambiente virtuale Python + +**Linux/macOS:** +```bash +python3 -m venv .venv +source .venv/bin/activate +``` + +**Windows:** +```cmd +python -m venv .venv +.venv\Scripts\activate +``` + +### 3. Installa le dipendenze + +```bash +pip install -r requirements.txt +``` + +## Utilizzo + +### Scanner Principale + +Avvia lo scanner interattivo: + +```bash +python main.py +``` + +Lo script ti chiederà: +- **Blocco di inizio**: da quale blocco iniziare (default: ultimo blocco + 1) +- **Blocco finale**: fino a quale blocco scansionare +- **Delay**: tempo tra richieste API in secondi (default: 1.0s, minimo: 0.1s) + +Esempio di sessione: +``` +📊 Ultimo blocco scannerizzato: 0 +💡 I primi blocchi di Bitcoin (1-10000) contengono molti P2PK + +📍 Blocco di inizio scansione (default: 1): 1 +📍 Blocco finale scansione (default: 1000): 100 +⏱️ Delay tra richieste in secondi (default: 1.0): 1.0 + +🔧 Configurazione: + Primo blocco: 1 + Ultimo blocco: 100 + Totale blocchi: 100 + Delay richieste: 1.0s + Tempo stimato: ~1.7 minuti + +▶️ Avviare la scansione? (s/n): s +``` + +### Visualizzatore Database + +Genera un report HTML interattivo: + +```bash +python view_db.py +``` + +Questo genera il file `p2pk_report.html` con: +- 📊 Statistiche generali (blocchi scansionati, P2PK trovati, valori) +- 🟢 Stato UTXO (speso/non speso) +- 🔍 Ricerca per blocco, TXID o chiave pubblica +- 📋 Pulsanti copia per chiavi pubbliche e TXID + +### Statistiche Rapide + +Visualizza statistiche nel terminale: + +```bash +python view_db.py --stats +``` + +Output esempio: +``` +============================================================ +📁 Database: bitcoin_p2pk_study.db +📦 Ultimo blocco scansionato: 100 +🔑 P2PK totali trovati: 45 +📊 Blocchi unici con P2PK: 23 +📈 Range blocchi: 1 - 100 +💰 Valore totale: 1234.56789012 BTC (123456789012 sat) +📝 Transazioni uniche: 42 +------------------------------------------------------------ +💎 P2PK NON SPESI: 12 +💵 Valore non speso: 567.89012345 BTC (56789012345 sat) +============================================================ +``` + +## Struttura Database + +Il database SQLite contiene due tabelle: + +### `p2pk_addresses` +| Campo | Tipo | Descrizione | +|-------|------|-------------| +| id | INTEGER | ID univoco | +| block_height | INTEGER | Altezza blocco | +| txid | TEXT | Transaction ID | +| output_index | INTEGER | Indice output | +| scriptpubkey | TEXT | ScriptPubKey (chiave pubblica) | +| value_satoshi | INTEGER | Valore in satoshi | +| timestamp | INTEGER | Timestamp blocco | +| is_unspent | INTEGER | 1 = non speso, 0 = speso | +| last_checked | INTEGER | Ultimo controllo UTXO | + +### `scan_progress` +| Campo | Tipo | Descrizione | +|-------|------|-------------| +| id | INTEGER | ID (sempre 1) | +| last_scanned_block | INTEGER | Ultimo blocco scansionato | +| total_p2pk_found | INTEGER | Totale P2PK trovati | + +## Scansione Incrementale + +Il database supporta scansioni incrementali: + +```bash +# Prima scansione: blocchi 1-100 +python main.py +> Blocco di inizio: 1 +> Blocco finale: 100 + +# Seconda scansione: blocchi 101-200 (continua automaticamente) +python main.py +> [ENTER] (usa default: ultimo + 1) +> Blocco finale: 200 + +# Puoi anche scansionare "indietro" o saltare range +python main.py +> Blocco di inizio: 500 +> Blocco finale: 1000 +``` + +Il database usa `UNIQUE(txid, output_index)` quindi non ci saranno duplicati. + +## Performance e Rate Limiting + +### Chiamate API per blocco +- 1x per ottenere hash blocco +- 1x per ottenere timestamp +- 1+ per transazioni (paginazione: 25 tx per pagina) +- 1x per ogni P2PK trovato (verifica UTXO) + +**Totale**: ~3-5 chiamate API per blocco (più se ci sono molte transazioni o P2PK) + +### Rate Limiting +- **Delay default**: 1.0 secondo tra blocchi +- **Minimo consigliato**: 0.1 secondi +- mempool.space non ha limiti ufficiali documentati, ma rispetta sempre l'API + +**Tempo stimato**: +- 100 blocchi × 1.0s = ~1.7 minuti +- 1000 blocchi × 1.0s = ~17 minuti +- 10000 blocchi × 1.0s = ~2.8 ore + +## Esportazione Dati + +### Esportazione CSV + +Dopo la scansione, lo script chiederà: +``` +📤 Esportare dati in CSV? (s/n): s +``` + +Questo genera `p2pk_export.csv` con tutte le colonne del database. + +### Formato CSV + +```csv +id,block_height,txid,output_index,scriptpubkey,value_satoshi,timestamp,is_unspent,last_checked +1,9,0437cd7f8525ceed2324359c2d0ba26006d92d85,0,4104d46c4968bde02899d2d0d...,5000000000,1231469744,0,1234567890 +``` + +## Collaborazione + +Questo progetto supporta la collaborazione multi-utente: + +### Condivisione Database +Il file `.gitignore` **non** esclude: +- `*.db` (database SQLite) +- `*.csv` (esportazioni) +- `*.html` (report) + +Più persone possono: +1. Clonare il repository con il database esistente +2. Scansionare range di blocchi diversi +3. Push/pull per sincronizzare i dati raccolti +4. Collaborare per coprire più blocchi velocemente + +### Best Practice per Collaborazione +1. Coordinarsi sui range di blocchi da scansionare +2. Fare pull prima di iniziare una nuova scansione +3. Committare e pushare il database dopo ogni scansione completata +4. Usare delay >= 1.0s per non sovraccaricare l'API + +## Come Funziona + +### Rilevamento P2PK + +Lo scanner usa 4 metodi per identificare P2PK: + +1. **Tipo esplicito**: `scriptpubkey_type == 'pubkey'` +2. **Lunghezza script**: 67 byte (non compresso) o 35 byte (compresso) +3. **Pattern ASM**: ` OP_CHECKSIG` +4. **Pattern HEX**: `41ac` o `21ac` + +### Formato ScriptPubKey + +**P2PK non compresso** (134 caratteri hex): +``` +41 + <65 byte pubkey> + ac +``` + +**P2PK compresso** (70 caratteri hex): +``` +21 + <33 byte pubkey> + ac +``` + +### Verifica UTXO + +Per ogni P2PK trovato, lo scanner verifica su mempool.space se l'output è ancora non speso: + +``` +GET /api/tx/{txid}/outspend/{vout} +``` + +Risposta: +```json +{ + "spent": false, // true se speso + "txid": "...", // txid che ha speso (se spent=true) + "vin": 0 // input index (se spent=true) +} +``` + +## Risoluzione Problemi + +### L'ambiente virtuale non si attiva + +**Linux/macOS:** +```bash +chmod +x .venv/bin/activate +source .venv/bin/activate +``` + +**Windows PowerShell:** +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +.venv\Scripts\Activate.ps1 +``` + +### Errori API / Timeout + +- Verifica la connessione internet +- Aumenta il delay tra richieste: `delay: 2.0` +- mempool.space potrebbe essere temporaneamente non disponibile + +### Database locked + +Se più processi accedono al database: +```bash +# Chiudi tutti gli script Python in esecuzione +# Riavvia lo script +``` + +## Blocchi Interessanti + +I primi blocchi Bitcoin contengono molti P2PK: + +- **Blocchi 1-10000**: Era di Satoshi, quasi tutti P2PK +- **Blocchi 10000-100000**: Transizione verso P2PKH +- **Blocchi 100000+**: Prevalentemente P2PKH, P2SH, SegWit + +**Consiglio**: Inizia dai blocchi 1-10000 per trovare più P2PK. + +## Crediti + +- API: [mempool.space](https://mempool.space/docs/api/rest) +- Bitcoin: [bitcoin.org](https://bitcoin.org) +- P2PK Reference: [Bitcoin Wiki](https://en.bitcoin.it/wiki/Transaction) + +--- + +**⚠️ Ricorda**: Questo è un progetto educativo. Le chiavi pubbliche P2PK non devono essere utilizzate per scopi illeciti.