@agntn/puzzles

🧩 333 puzzle e bounty crypto pubblici in undici collezioni, 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, leggermente diverso ogni volta. Quindi vivono qui una volta sola, come codice. Un puzzle è un record TypeScript. Il type checker lo legge prima di un test. La CLI, il server MCP e le estensioni Pi e OMP leggono un unico registry.

Documentazione, una pagina per puzzle e un playground live: 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 una factory per la sua chain. Niente JSON, niente build step.
• 🕳️ Assente significa assente. Un puzzle senza un solver o un premio non ha quella chiave. Niente viene serializzato come null.
• 🔑 Materiale di chiave in ogni forma. Hex, WIF, un payload BIP38, una seed phrase, secret share, o solo una larghezza in bit. Un unico builder.
• 💤 Registry lazy. Importare il pacchetto non carica alcun record. get("b1000/71") importa un modulo di collezione.
• ✅ La verifica è un valore. Una chiave pubblicata deriva l'indirizzo oppure no. Niente lancia eccezioni per un record errato.
• 💰 Saldi live. puzzle.balance() tramite @agntn/explorers. Unità base come bigint, chiavi API oscurate dagli errori.
• 🤖 Sei 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

pnpm add @agntn/puzzles

Node.js 24 o superiore per la CLI.

🚀 Prima chiamata

npx @agntn/puzzles stats

Total: 333
Solved: 131
Unsolved: 93
Claimed: 11
Swept: 96
Expired: 2
With pubkey: 237

Nessuna chiave, nessuna configurazione, nessuna rete. I record viaggiano dentro il pacchetto. Il puzzles nudo qui sotto è pnpm exec puzzles dopo un pnpm add locale, oppure semplicemente puzzles dopo pnpm add -g @agntn/puzzles.

puzzles show b1000/71

b1000/71	unsolved	7.100226 BTC	1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU

Comandi

Comando	Cosa stampa
puzzles stats	Totali e conteggi di stato. --json aggiunge le somme dei premi
puzzles collections	Una riga per collezione: chiave, conteggi, autore
puzzles show <id>	Un puzzle. --json per l'intero record
puzzles list [collection]	Un puzzle per riga. --status e --with-pubkey restringono la selezione
puzzles verify [id]	Una chiave pubblicata contro il suo indirizzo. --all per ogni puzzle, exit 1 su una mancata corrispondenza
puzzles balance <id>	Il saldo live. --api-key o ETHERSCAN_API_KEY per Ethereum
puzzles export	L'intero dataset con il suo data_version
puzzles mcp	Il server MCP su stdio

--json è lo stesso serializer ovunque, bigint come stringhe e i campi assenti omessi. I flag e i codici di uscita sono nella guida alla CLI.

🧠 Libreria

import { get, stats, verifyPuzzle } from "@agntn/puzzles";
import { b1000 } from "@agntn/puzzles/collections/b1000";

const puzzle = await get("b1000/71"); // loads the b1000 collection, nothing else
puzzle?.address().value; // "1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU"
puzzle?.keyRange(); // [2n ** 70n, 2n ** 71n - 1n]

verifyPuzzle(b1000.require(1)).verified; // true, key 1 derives its address
(await stats()).unsolved; // 93
(await b1000.require(71).balance()).totalUnits(); // 7.10190014 when I ran it, mempool.space decides

Questo è quasi tutto, davvero. Una collezione è il suo proprio entry point e tutto su di essa è sincrono. Le viste che attraversano le collezioni attendono un caricamento. Gli errori discendono da PuzzlesError, i saldi hanno la loro famiglia sotto BalanceError. Il resto è nelle guide: records, registry, lookups, verification, balances.

🗺️ Collezioni

Chiave	Puzzle	Chain	Cos'è
b1000	256	bitcoin	Chiavi da 1 a 256 bit, un indirizzo ciascuna
rushwallet	30	bitcoin	Brainwallet da un contest del 2014
zden	15	bitcoin, ethereum, litecoin, decred	I puzzle visivi di Zden
arweave	12	arweave, ethereum	I weave puzzle di Tiamat
warp	6	bitcoin	Le sfide brainwallet scrypt di Keybase
hash_collision	6	bitcoin	Le bounty P2SH collision di Peter Todd
ballet	3	bitcoin	Chiavi BIP38 stampate su wallet fisici
bitimage	2	bitcoin	Seed hashate da fotografie
bitaps	1	bitcoin	Uno schema di secret sharing 3 di 5
gsmg	1	bitcoin	Un puzzle a immagini multifase
movie_enigma	1	bitcoin	Titoli di film come seed word, risolto nel 2026

Gli identificatori sono collection/name. I tre singleton, gsmg, bitaps e movie_enigma, sono semplicemente la chiave. Ogni collezione ha una pagina con la storia, le stranezze e ogni puzzle: puzzles.agntn.dev/collections.

🤖 Agenti

claude mcp add puzzles --scope user -- npx -y @agntn/puzzles mcp
pi install npm:@agntn/puzzles

{
  "mcpServers": {
    "puzzles": { "command": "npx", "args": ["-y", "@agntn/puzzles", "mcp"] }
  }
}

Sei strumenti: puzzles_stats, puzzles_collections, puzzles_show, puzzles_list, puzzles_verify e puzzles_balance. Solo l'ultimo lascia il processo, e le sue annotazioni lo dicono. Cosa trasporta il testo e dove vivono i limiti: la guida agli agenti.

🚫 Cosa non fa