oritwoen/bohaLibreria di dati su bounty, puzzle e sfide crypto
# @agntn/puzzles
[](https://npmx.dev/package/@agntn/puzzles)
[](https://npmx.dev/package/@agntn/puzzles)
[](https://npmx.dev/package/@agntn/puzzles)
[](https://deepwiki.com/agntn/puzzles)
Puzzle e taglie crypto pubbliche, come record tipizzati. Chiedi un puzzle, ottieni il suo indirizzo, il suo materiale di chiave e cosa è successo on chain.
## Perché?
Ogni thread di puzzle ha le stesse tre cose: gli indirizzi, i premi e chi ha risolto cosa. Ogni scanner e tracker li ridigita dal thread, in modo leggermente diverso ogni volta. Così vivono qui una volta sola, come codice. Un puzzle è un record TypeScript. Il type checker lo legge prima che lo faccia un test. La CLI, il server MCP e le estensioni Pi e OMP leggono un unico registro.
Documentazione, una pagina per puzzle e un playground live: [puzzles.agntn.dev](https://puzzles.agntn.dev).
> [!WARNING]
> Pre-1.0. L'API, i flag della CLI e il modello dati possono ancora cambiare. Fissa una versione esatta se ci costruisci sopra.
## ✨ Funzionalità
- 🧾 **Dati come codice.** Un letterale `PuzzleSpec` per puzzle, costruito da un'unica factory `puzzle()` per ogni chain. Niente JSON, niente build step.
- 🕳️ **Assente significa assente.** Un puzzle senza un solver o un premio non ha quella chiave. Nulla viene serializzato come null.
- 🔑 **Materiale di chiave in ogni forma.** Hex, WIF, un payload BIP38, una seed phrase, secret share, un keyfile Arweave sigillato, o solo una larghezza in bit. Anche ogni chiave di un multisig. Un unico builder.
- 💤 **Registro lazy.** Importare il pacchetto non carica alcun record. `get("bits/71")` importa un modulo di una collezione.
- ✅ **La verifica è un valore.** Una chiave pubblicata deriva l'indirizzo oppure no. Nulla lancia eccezioni per un record errato.
- 💰 **Saldi live.** `puzzle.balance()` tramite `@agntn/explorers`. Unità base come `bigint`, chiavi API oscurate dagli errori.
- 👀 **Una sorveglianza sul record.** `puzzles watch` elenca i depositi e le spese che un record manca, un premio che si è spostato, una chiave pubblica che una spesa ha rivelato, una pagina sorgente che è cambiata. Non modifica mai un record. Lo fai tu.
- 📋 **Una checklist prima del weekend.** `puzzles eligibility` raccoglie la fonte, l'indirizzo, i totali complessivi dall'explorer, lo stato con le sue prove e cosa conta come soluzione. Tutto ciò che nessuno riesce a compilare torna come riga `missing`, mai come ipotesi.
- 🖼️ **Il puzzle stesso, non un link ad esso.** `puzzles_assets` consegna a un modello l'immagine, i file di stage e i post archiviati dietro gli indizi, verificati contro lo SHA-256 che il record fissa. I link marciscono. Questi no.
- 🤖 **Quindici strumenti per agenti.** Un unico executor dietro MCP, Pi e OMP. Stessa risposta ovunque.
- 🌐 **Gira ovunque.** ESM neutro sulla Fetch API. Node, browser, edge worker.
## 📦 Installazione
```bash
pnpm add @agntn/puzzles
```
Node.js 26 o versione successiva per la CLI.
## 🚀 Prima chiamata
```bash
npx @agntn/puzzles stats
```
Stampa il totale, un conteggio per stato e quanti puzzle hanno una chiave pubblica nota. Nessuna chiave, nessuna configurazione, nessuna rete. I record sono inclusi nel pacchetto. Il comando `puzzles` qui sotto è `pnpm exec puzzles` dopo un `pnpm add` locale, oppure semplicemente `puzzles` dopo `pnpm add -g @agntn/puzzles`.
```bash
puzzles show hash-collision/sha256
```
```text
hash-collision/sha256 unsolved 0.27734251 BTC 35Snmmy3uhaer2gTboc81ayCip4m9DT4ko
chain: bitcoin address kind: p2sh
hash160: 292fb39df7cd619a396069383928e6bfb74ebec5
redeem script: 6e879169a87ca887 (hash 292fb39df7cd619a396069383928e6bfb74ebec5)
public key: unknown
private key: unknown
started: 2013-09-13 05:59:09
transactions: 1
funding 2013-09-13 05:59:09 0.1 BTC 397f12ee15f8a3d2ab25c0f6bb7d3c64d2038ca056af10dd8251b98ae0f076b0
explorer: https://blockstream.info/address/35Snmmy3uhaer2gTboc81ayCip4m9DT4ko
source: https://bitcointalk.org/index.php?topic=293382.0
```
### Comandi
| Comando | Cosa stampa |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `puzzles stats` | Totali, conteggi per stato, somme dei premi e la versione dei dati |
| `puzzles collections` | Una riga per collezione: chiave, conteggi, autore |
| `puzzles authors [key]` | Una riga per autore, oppure il record di un autore con i suoi fatti documentati |
| `puzzles author <key>` | Il record di un autore, direttamente dallo strumento `puzzles_author` |
| `puzzles solvers [key]` | Una riga per solver nominato, oppure il record di un solver: ogni risoluzione, profili e fatti documentati |
| `puzzles solver <key>` | Il record di un solver, direttamente dallo strumento `puzzles_solver` |
| `puzzles show <id>` | Il record di un puzzle: materiale della chiave, transazioni, indizi e link. `--json` per i dati |
| `puzzles hints <id>` | Gli indizi della collezione, poi quelli del puzzle, poi i suoi file di indizi. `--json` per entrambi |
| `puzzles stages <id>` | Le fasi di un puzzle multi-fase con le loro pagine, file e risposte pubblicate. `--json` per la lista |
| `puzzles assets <id>` | I file forniti con un puzzle con SHA-256 e dimensione, e le pagine archiviate che cita. `--read <path>` ne scrive uno, `--check`/`--live` verificano |
| `puzzles list [collection]` | Un puzzle per riga. `--address`, `--chain`, `--status`, `--technique` e `--with-pubkey` restringono, `--limit` e `--offset` paginano |
| `puzzles verify [id]` | Una chiave pubblicata e la sua ricetta rispetto all'indirizzo. `--all` o i filtri di `list` per un insieme, exit 1 in caso di discrepanza |
| `puzzles balance [id]` | Il saldo live. I filtri di `list` controllano un intero insieme, una riga ciascuno. `--api-key`, oppure una variabile per catena |
| `puzzles watch [id]` | Ciò che la catena sa e il record no. `--since` controlla anche le pagine sorgente, exit 1 per qualsiasi anomalia |
| `puzzles eligibility <query>` | La checklist prima di lavorare su un premio, per id o indirizzo. Exit 1 finché manca un campo |
| `puzzles export` | L'intero dataset con il suo `data_version` |
| `puzzles mcp` | Il server MCP su stdio |
`--json` stampa i dati dietro il testo, `bigint` come stringhe e i campi assenti omessi. I comandi provengono dalle stesse definizioni di strumenti che ricevono gli agenti, quindi un errore di battitura in un flag fallisce qui proprio come fallisce per un modello. I flag e i codici di uscita sono nella [guida CLI](https://puzzles.agntn.dev/guide/cli).
## 🧠 Libreria
```ts
import { get, stats, verify } from "@agntn/puzzles";
import { bits } from "@agntn/puzzles/collections/bits";
const puzzle = await get("bits/71"); // loads the bits collection, nothing else
puzzle?.address().value; // "1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU"
puzzle?.keyRange(); // [2n ** 70n, 2n ** 71n - 1n]
(await verify(bits.require(1))).verified; // true, key 1 derives its address
(await stats()).unsolved; // how many are still waiting for a key
(await bits.require(71).balance()).totalUnits(); // 7.10190014 when I ran it, mempool.space decides
```
È praticamente tutto qui. Una collezione è una voce a sé stante e tutto ciò che contiene è sincrono. Le viste che attraversano le collezioni attendono un caricamento. Gli errori discendono da `PuzzlesError`, i bilanci hanno la propria famiglia sotto `BalanceError`. Il resto è nelle guide: [records](https://puzzles.agntn.dev/guide/records), [registry](https://puzzles.agntn.dev/guide/registry), [lookups](https://puzzles.agntn.dev/guide/lookups), [verification](https://puzzles.agntn.dev/guide/verification), [balances](https://puzzles.agntn.dev/guide/balances).
## 🗺️ Collezioni
| Chiave | Catene | Di cosa si tratta |
| --------------------------- | ----------------------------------- | ------------------------------------------- |
| `bits` | bitcoin | Chiavi da 1 a 256 bit, un indirizzo ciascuna |
| `quizchain` | bitcoin | Blocchi quiz concatenati tramite le loro chiavi |
| `quizchain2` | bitcoin | La seconda edizione di Quizchain, da maggio 2019 |
| `rushwallet` | bitcoin | Brainwallet da un concorso del 2014 |
| `zden` | bitcoin, ethereum, litecoin, decred | I puzzle visivi di Zden |
| `weave` | arweave, ethereum | La serie Puzzle Weave di Tiamat |
| `move-over-brokers` | bitcoin | Dodici chiavi nascoste in un libro sulla blockchain |
| `mini` | bitcoin, bitcoincash | I sette mini-puzzle di RetiredCoder |
| `warp` | bitcoin | Le sfide brainwallet scrypt di Keybase |
| `hash-collision` | bitcoin | Le taglie per collisione P2SH di Peter Todd |
| `teikhos` | ethereum | Contratti che pagano per una chiave pubblica |
| `ballet` | bitcoin | Chiavi BIP38 stampate su wallet fisici |
| `dug` | bitcoin | Caccia al seed per studenti del 2025 |
| `coin-games` | bitcoin | Banconote con un teschio, un leone e Venere |
| `bitimage` | bitcoin | Seed ricavati tramite hash da fotografie |
| `luckylurker` | bitcoin | Due sfide seed Bitcoin Vault |
| `iamabananaamaa` | bitcoin | Un ZIP in un GIF, poi un falso Cesare |
| `doges-gambit` | ethereum, dogecoin | Due chiavi lette da un video di una scacchiera |
| `crypto-puzzles` | ethereum | Chiavi Ether grezze nascoste in brevi video |
| `walking-banks` | bitcoin | Un seed nascosto in un romanzo thriller su Bitcoin |
| `grycoin` | bitcoin | Quizchain rinominato, pochi giorni prima della chiusura |
| `smith-lyle-moore` | bitcoin | Le due cacce di una band, una per singolo |
| `real-big-block` | bitcoin | 777 mBTC per un capitolo di Wattpad, non reclamati |
| `school-of-bitcoin` | bitcoin | Un biglietto da visita con 1M di sats sul retro |
| `liberte-guidant-le-peuple` | bitcoin | Delacroix in gilet gialli, seed in francese |
| `hunting-time` | bitcoin | Parole seed camuffate da orari in un romanzo |
| `bitaps` | bitcoin | Uno schema di condivisione segreta 3 su 5 |
| `gsmg` | bitcoin | Un puzzle a immagini multifase |
| `movie-enigma` | bitcoin | Titoli di film come parole seed, risolto nel 2026 |
| `ledger-donjon` | bitcoin | Scissors Secret Sharing dal CTF |
| `coin-artist` | bitcoin | Dipinto TORCHED H34R7S |
| `genesis` | bitcoin | Puzzle OP_RETURN del blocco genesis |
| `mineshop` | ethereum | Un seed diviso tra un video e un post |
| `satoshi-birthday-quiz` | bitcoin | Sette risposte di un quiz trasformate in hash dentro un wallet |
| `book-quiz` | bitcoin | Un quiz su un libro che nessuno ha vinto in tempo |
| `80-bit` | bitcoin | 80 bit nascosti e una corsa nella mempool |
| `wickex` | bitcoin | Esadecimale, Morse e una passphrase da spettrogramma |
| `picture-puzzle` | bitcoin | Quattro immagini che compongono un database di chiavi |
| `brave-new-world` | bitcoin | Una seed phrase nascosta in un collage del 2020 |
| `wealth-in-poetry` | bitcoin | Parole seed nascoste in un saggio su Medium del 2019 |
| `path-to-greatness` | litecoin | Indizi da una demo di un gioco, una chiave Litecoin |
| `proof-of-writing` | ecash | Una seed Cashtab sulla diagonale di un saggio |
| `bitaddress` | bitcoin | Un wallet BIP38 con una passphrase dimenticata |
| `powerful-moss` | base | Una seed in un album, il premio in un contratto |
| `trivia-brainwallet` | bitcoin | Dodici indovinelli di trivia salati in scrypt |
| `great-riddle` | bitcoin | Parole seed nascoste in disegni a penna a sfera |
| `satoshi-maze` | bitcoin | Un numero primo da e per due parole Base58 |
| `natasha-otomoski` | bitcoin | Otto parole camel case come byte grezzi di chiave |
| `phy` | bitcoin | Un post firmato e una spirale di emoji grigie |
| `seed-phrase` | bitcoin | Indizi datati, poi due anni di silenzio |
| `9vw04` | bitcoin | Una WIF in un tweet, arcobaleni esclusi |
Gli identificatori sono `collection/name`. Un singleton, come `gsmg`, `genesis` o `80-bit`, è solo la chiave. Ogni collezione ha una pagina con la storia, le particolarità e ogni puzzle: [puzzles.agntn.dev/collections](https://puzzles.agntn.dev/collections).
## 🤖 Agenti
```bash
claude mcp add puzzles --scope user -- npx -y @agntn/puzzles mcp
claude mcp add --transport http puzzles https://puzzles.agntn.dev/mcp # nothing to install
pi install npm:@agntn/puzzles
```
```json
{
"mcpServers": {
"puzzles": { "command": "npx", "args": ["-y", "@agntn/puzzles", "mcp"] }
}
}
```
Quindici strumenti: `puzzles_stats`, `puzzles_collections`, `puzzles_authors`, `puzzles_author`, `puzzles_solvers`, `puzzles_solver`, `puzzles_show`, `puzzles_hints`, `puzzles_stages`, `puzzles_assets`, `puzzles_list`, `puzzles_verify`, `puzzles_balance`, `puzzles_watch` e `puzzles_eligibility`. Gli ultimi tre terminano il processo, e lo fa anche `puzzles_assets` quando legge un file. Le loro annotazioni lo indicano. Cosa contiene il testo e dove si trovano i limiti: la [guida per gli agenti](https://puzzles.agntn.dev/guide/agents).
## 🚫 Cosa non fa
Non risolve nulla. Nessuno scanner, nessun kangaroo, nessun cracker di brainwallet e nessuna deduzione di uno stato da un elenco di transazioni. `solved`, `swept`, `claimed` ed `expired` sono scritti a mano, perché una transazione di claim più una chiave pubblicata significa comunque risolto. I fatti della catena provengono da `@agntn/chains`, la derivazione delle chiavi da `@agntn/keys` e i saldi da `@agntn/explorers`. Questo pacchetto non ne reimplementa nessuno.
## 🧩 Aggiungere un puzzle
Un file di record sotto `src/collections/<key>/` e una riga nel modulo della collezione. Poi `pnpm test` esegue il controllo dei dati: id univoci, formati di indirizzi e txid, derivazione delle chiavi, payload BIP38, percorsi degli asset e il loro SHA-256, nessun valore nullo. La struttura di un record è in [Puzzle records](https://puzzles.agntn.dev/guide/records) e le regole in [CONTRIBUTING.md](https://github.com/oritwoen/boha/blob/main/CONTRIBUTING.md).
## 🛠️ Sviluppo
```bash
pnpm install
pnpm --dir docs install # the docs site; lint and test read the Nuxt types it generates
pnpm lint # vp lint and vp fmt, docs included
pnpm typecheck # builds first, then checks src, Pi and OMP
pnpm test # unit tests and the data gate
pnpm test:packed # packs the tarball and runs every published entry without src/
pnpm docs # the Docus site on localhost
```
## 💛 Ringraziamenti
Questo pacchetto esiste grazie ai programmi open source di Anthropic e OpenAI: [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) e [Codex for Open Source](https://developers.openai.com/community/codex-for-oss).
## 📄 Licenza
[MIT](https://github.com/oritwoen/boha/blob/main/LICENSE)