oritwoen/bohaBibliothèque de données de primes, énigmes et défis 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)
Des puzzles crypto et primes publics, sous forme d'enregistrements typés. Vous demandez un puzzle, vous obtenez son adresse, son matériel de clé et ce qui s'est passé on chain.
## Pourquoi ?
Chaque fil de puzzle contient les mêmes trois choses : les adresses, les prix et qui a résolu quoi. Chaque scanner et chaque tracker les retape à partir du fil, un peu différemment à chaque fois. Alors ils vivent ici une fois, sous forme de code. Un puzzle est un enregistrement TypeScript. Le vérificateur de types le lit avant qu'un test ne le fasse. La CLI, le serveur MCP et les extensions Pi et OMP lisent un seul registre.
Docs, une page par puzzle et un playground en direct : [puzzles.agntn.dev](https://puzzles.agntn.dev).
> [!WARNING]
> Pré-1.0. L'API, les flags de la CLI et le modèle de données peuvent encore évoluer. Épinglez une version exacte si vous construisez dessus.
## ✨ Fonctionnalités
- 🧾 **La donnée comme code.** Un littéral `PuzzleSpec` par puzzle, construit par une seule factory `puzzle()` pour chaque chaîne. Pas de JSON, pas d'étape de build.
- 🕳️ **Absent signifie absent.** Un puzzle sans solveur ou sans prix n'a pas cette clé. Rien ne se sérialise en null.
- 🔑 **Le matériel de clé sous toutes ses formes.** Hex, WIF, une charge utile BIP38, une phrase de récupération, des partages secrets, un keyfile Arweave scellé, ou simplement une largeur de bits. Chaque clé d'un multisig aussi. Un seul builder.
- 💤 **Registre paresseux.** Importer le paquet ne charge aucun enregistrement. `get("bits/71")` importe un module de collection.
- ✅ **La vérification est une valeur.** Une clé publiée dérive l'adresse ou ne la dérive pas. Rien ne lève d'exception pour un enregistrement invalide.
- 💰 **Soldes en direct.** `puzzle.balance()` via `@agntn/explorers`. Unités de base en `bigint`, clés d'API masquées dans les erreurs.
- 👀 **Une surveillance sur l'enregistrement.** `puzzles watch` liste les dépôts et les dépenses qu'un enregistrement manque, un prix qui a bougé, une clé publique qu'une dépense a révélée, une page source qui a changé. Il ne modifie jamais un enregistrement. C'est vous qui le faites.
- 📋 **Une checklist avant le week-end.** `puzzles eligibility` rassemble la source, l'adresse, les totaux cumulés depuis l'explorateur, le statut avec ses preuves et ce qui compte comme solution. Tout ce que personne ne peut remplir revient sous forme de ligne `missing`, jamais une supposition.
- 🖼️ **Le puzzle lui-même, pas un lien vers lui.** `puzzles_assets` fournit à un modèle l'image, les fichiers d'étapes et les posts archivés derrière les indices, vérifiés par rapport au SHA-256 épinglé dans l'enregistrement. Les liens pourrissent. Ceux-ci non.
- 🤖 **Quinze outils d'agent.** Un seul exécuteur derrière MCP, Pi et OMP. La même réponse partout.
- 🌐 **Fonctionne partout.** ESM neutre sur l'API Fetch. Node, navigateurs, edge workers.
## 📦 Installation
```bash
pnpm add @agntn/puzzles
```
Node.js 26 ou plus récent pour la CLI.
## 🚀 Premier appel
```bash
npx @agntn/puzzles stats
```
Cela affiche le total, un décompte par statut et le nombre d'énigmes dont la clé publique est connue. Aucune clé, aucune configuration, aucun réseau. Les enregistrements sont livrés dans le paquet. Le `puzzles` seul ci-dessous correspond à `pnpm exec puzzles` après un `pnpm add` local, ou simplement `puzzles` après `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
```
### Commandes
| Commande | Ce qu'elle affiche |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `puzzles stats` | Totaux, décomptes par statut, sommes des primes et la version des données |
| `puzzles collections` | Une ligne par collection : clé, décomptes, auteur |
| `puzzles authors [key]` | Une ligne par auteur, ou l'enregistrement d'un auteur avec ses faits sourcés |
| `puzzles author <key>` | L'enregistrement d'un auteur, directement depuis l'outil `puzzles_author` |
| `puzzles solvers [key]` | Une ligne par solveur nommé, ou l'enregistrement d'un solveur : chaque résolution, profils et faits sourcés |
| `puzzles solver <key>` | L'enregistrement d'un solveur, directement depuis l'outil `puzzles_solver` |
| `puzzles show <id>` | L'enregistrement d'une énigme : matériel de clé, transactions, indices et liens. `--json` pour les données |
| `puzzles hints <id>` | Les indices de la collection, ceux de l'énigme, puis ses fichiers d'indices. `--json` pour les deux |
| `puzzles stages <id>` | Les étapes d'une énigme à plusieurs étapes avec leurs pages, fichiers et réponses publiées. `--json` pour la liste |
| `puzzles assets <id>` | Les fichiers livrés avec une énigme avec leur SHA-256 et leur taille, et les pages archivées qu'elle cite. `--read <path>` en écrit un, `--check`/`--live` vérifient |
| `puzzles list [collection]` | Une énigme par ligne. `--address`, `--chain`, `--status`, `--technique` et `--with-pubkey` restreignent la liste, `--limit` et `--offset` la paginent |
| `puzzles verify [id]` | Une clé publiée et sa recette confrontées à l'adresse. `--all` ou les filtres de `list` pour un ensemble, code de sortie 1 en cas d'incohérence |
| `puzzles balance [id]` | Le solde en direct. Les filtres de `list` vérifient tout un ensemble, une ligne chacun. `--api-key`, ou une variable par chaîne |
| `puzzles watch [id]` | Ce que la chaîne sait et que l'enregistrement ignore. `--since` vérifie aussi les pages sources, code de sortie 1 à la moindre anomalie |
| `puzzles eligibility <query>` | La liste de contrôle avant de travailler sur une prime, par id ou adresse. Code de sortie 1 tant qu'un champ manque |
| `puzzles export` | L'intégralité du jeu de données avec son `data_version` |
| `puzzles mcp` | Le serveur MCP via stdio |
`--json` affiche les données derrière le texte, les `bigint` sous forme de chaînes et les champs absents omis. Les commandes proviennent des mêmes définitions d'outils que celles fournies aux agents, si bien qu'une faute de frappe dans un drapeau échoue ici comme elle échoue pour un modèle. Les drapeaux et codes de sortie sont dans le [guide CLI](https://puzzles.agntn.dev/guide/cli).
## 🧠 Bibliothèque
```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
```
C'est l'essentiel, vraiment. Une collection est sa propre entrée et tout ce qu'elle contient est synchrone. Les vues qui s'étendent sur plusieurs collections attendent un chargement. Les erreurs descendent de `PuzzlesError`, les soldes ont leur propre famille sous `BalanceError`. Le reste se trouve dans les guides : [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).
## 🗺️ Collections
| Key | Chaînes | De quoi il s'agit |
| --------------------------- | ----------------------------------- | ------------------------------------------- |
| `bits` | bitcoin | Clés de 1 à 256 bits, une adresse chacune |
| `quizchain` | bitcoin | Blocs de quiz chaînés par leurs clés |
| `quizchain2` | bitcoin | Deuxième édition de Quizchain, à partir de mai 2019 |
| `rushwallet` | bitcoin | Brainwallets issues d'un concours de 2014 |
| `zden` | bitcoin, ethereum, litecoin, decred | Énigmes visuelles de Zden |
| `weave` | arweave, ethereum | Série Puzzle Weave de Tiamat |
| `move-over-brokers` | bitcoin | Douze clés cachées dans un livre sur la blockchain |
| `mini` | bitcoin, bitcoincash | Les sept mini-énigmes de RetiredCoder |
| `warp` | bitcoin | Défis de brainwallet scrypt de Keybase |
| `hash-collision` | bitcoin | Primes à la collision P2SH de Peter Todd |
| `teikhos` | ethereum | Contrats qui paient pour une clé publique |
| `ballet` | bitcoin | Clés BIP38 imprimées sur des portefeuilles physiques |
| `dug` | bitcoin | Chasse aux seeds étudiante de 2025 |
| `coin-games` | bitcoin | Billets avec un crâne, un lion et Vénus |
| `bitimage` | bitcoin | Seeds hachées à partir de photographies |
| `luckylurker` | bitcoin | Deux défis de seed Bitcoin Vault |
| `iamabananaamaa` | bitcoin | Un ZIP dans un GIF, puis un faux César |
| `doges-gambit` | ethereum, dogecoin | Deux clés lues sur une vidéo d'échiquier |
| `crypto-puzzles` | ethereum | Clés Ether brutes cachées dans de courtes vidéos |
| `walking-banks` | bitcoin | Une seed cachée dans un thriller sur Bitcoin |
| `grycoin` | bitcoin | Quizchain renommé, quelques jours avant l'arrêt |
| `smith-lyle-moore` | bitcoin | Les deux chasses d'un groupe, une par single |
| `real-big-block` | bitcoin | 777 mBTC pour un chapitre Wattpad, non réclamés |
| `school-of-bitcoin` | bitcoin | Une carte de visite avec 1M sats au dos |
| `liberte-guidant-le-peuple` | bitcoin | Delacroix en gilets jaunes, seed en français |
| `hunting-time` | bitcoin | Des mots de seed déguisés en heures dans un roman |
| `bitaps` | bitcoin | Un schéma de partage de secret 3 sur 5 |
| `gsmg` | bitcoin | Une énigme d'images à plusieurs phases |
| `movie-enigma` | bitcoin | Des titres de films comme mots de seed, résolue en 2026 |
| `ledger-donjon` | bitcoin | Scissors Secret Sharing issu du CTF |
| `coin-artist` | bitcoin | Peinture TORCHED H34R7S |
| `genesis` | bitcoin | Énigme OP_RETURN du bloc genesis |
| `mineshop` | ethereum | Une seed partagée entre une vidéo et un post |
| `satoshi-birthday-quiz` | bitcoin | Sept réponses de quiz hachées dans un portefeuille |
| `book-quiz` | bitcoin | Un quiz de livre que personne n'a gagné à temps |
| `80-bit` | bitcoin | 80 bits cachés et une course dans la mempool |
| `wickex` | bitcoin | Hexadécimal, Morse et une phrase de passe en spectrogramme |
| `picture-puzzle` | bitcoin | Quatre images qui épellent une base de données de clés |
| `brave-new-world` | bitcoin | Une phrase de récupération cachée dans un collage de 2020 |
| `wealth-in-poetry` | bitcoin | Des mots de récupération cachés dans un essai Medium de 2019 |
| `path-to-greatness` | litecoin | Des indices tirés d'une démo de jeu, une clé Litecoin |
| `proof-of-writing` | ecash | Une phrase de récupération Cashtab sur la diagonale d'un essai |
| `bitaddress` | bitcoin | Un portefeuille BIP38 avec une phrase de passe oubliée |
| `powerful-moss` | base | Une phrase de récupération dans un album, le prix dans un contrat |
| `trivia-brainwallet` | bitcoin | Douze énigmes de culture générale salées dans scrypt |
| `great-riddle` | bitcoin | Des mots de récupération cachés dans des dessins au stylo à bille |
| `satoshi-maze` | bitcoin | Un nombre premier issu de e fois deux mots Base58 |
| `natasha-otomoski` | bitcoin | Huit mots en camel case comme octets de clé brute |
| `phy` | bitcoin | Un post signé et une spirale d'emojis gris |
| `seed-phrase` | bitcoin | Des indices datés, puis deux ans de silence |
| `9vw04` | bitcoin | Un WIF dans un tweet, arcs-en-ciel non inclus |
Les identifiants sont `collection/name`. Un singleton, comme `gsmg`, `genesis` ou `80-bit`, n'est que la clé. Chaque collection dispose d'une page avec l'histoire, les particularités et chaque puzzle : [puzzles.agntn.dev/collections](https://puzzles.agntn.dev/collections).
## 🤖 Agents
```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"] }
}
}
```
Quinze outils : `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` et `puzzles_eligibility`. Les trois derniers quittent le processus, tout comme `puzzles_assets` lorsqu'il lit un fichier. Leurs annotations le précisent. Ce que le texte contient et où se situent les limites : le [guide des agents](https://puzzles.agntn.dev/guide/agents).
## 🚫 Ce que cela ne fait pas
Cela ne résout rien. Pas de scanner, pas de kangaroo, pas de cracker de brainwallet, et aucune déduction d'un statut à partir d'une liste de transactions. `solved`, `swept`, `claimed` et `expired` sont inscrits à la main, car une transaction de claim accompagnée d'une clé publiée signifie toujours résolu. Les faits de chaîne proviennent de `@agntn/chains`, la dérivation de clés de `@agntn/keys` et les soldes de `@agntn/explorers`. Ce paquet ne réimplémente aucun d'entre eux.
## 🧩 Ajouter un puzzle
Un fichier d'enregistrement sous `src/collections/<key>/` et une ligne dans le module de collection. Ensuite, `pnpm test` exécute le contrôle des données : identifiants uniques, formats d'adresse et de txid, dérivation de clés, charges utiles BIP38, chemins d'assets et leur SHA-256, aucun null. La structure d'un enregistrement est décrite dans [Puzzle records](https://puzzles.agntn.dev/guide/records) et les règles dans [CONTRIBUTING.md](https://github.com/oritwoen/boha/blob/main/CONTRIBUTING.md).
## 🛠️ Développement
```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
```
## 💛 Remerciements
Ce paquet existe grâce aux programmes open source d'Anthropic et d'OpenAI : [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) et [Codex for Open Source](https://developers.openai.com/community/codex-for-oss).
## 📄 Licence
[MIT](https://github.com/oritwoen/boha/blob/main/LICENSE)