@agntn/puzzles

🧩 333 puzzles crypto publics et primes répartis en onze collections, 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 discussion sur les puzzles contient les mêmes trois choses : les adresses, les prix et qui a résolu quoi. Chaque scanner et tracker les retape depuis le fil, légèrement 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. Le 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.

[!WARNING] Pré-1.0. L'API, les flags du CLI et le modèle de données peuvent encore évoluer. Épinglez une version exacte si vous construisez dessus.

✨ Fonctionnalités

🧾 Les données comme code. Un littéral PuzzleSpec par puzzle, construit par une factory pour sa 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 n'est sérialisé en null.
🔑 Du matériel de clé sous toutes les formes. Hex, WIF, une charge utile BIP38, une phrase de récupération, des partages de secret, ou simplement une largeur de bits. Un seul builder.
💤 Registre paresseux. Importer le package ne charge aucun enregistrement. get("b1000/71") importe un seul module de collection.
✅ La vérification est une valeur. Une clé publiée dérive l'adresse ou non. 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.
🤖 Six 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

pnpm add @agntn/puzzles

Node.js 24 ou plus récent pour le CLI.

🚀 Premier appel

npx @agntn/puzzles stats

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

Pas de clé, pas de config, pas de réseau. Les enregistrements sont livrés dans le package. 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.

puzzles show b1000/71

b1000/71	unsolved	7.100226 BTC	1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU

Commandes

Commande	Ce qu'elle affiche
`puzzles stats`	Totaux et comptes par statut. `--json` ajoute les sommes des prix
`puzzles collections`	Une ligne par collection : clé, comptes, auteur
`puzzles show <id>`	Un puzzle. `--json` pour l'enregistrement complet
`puzzles list [collection]`	Un puzzle par ligne. `--status` et `--with-pubkey` restreignent la liste
`puzzles verify [id]`	Une clé publiée face à son adresse. `--all` pour chaque puzzle, exit 1 en cas d'écart
`puzzles balance <id>`	Le solde en direct. `--api-key` ou `ETHERSCAN_API_KEY` pour Ethereum
`puzzles export`	L'ensemble du jeu de données avec son `data_version`
`puzzles mcp`	Le serveur MCP sur stdio

--json est le même sérialiseur partout, bigint en chaînes et les champs absents omis. Les flags et les codes de sortie sont dans le guide du CLI.

🧠 Bibliothèque

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

C'est l'essentiel, vraiment. Une collection est sa propre entrée et tout ce qui la concerne est synchrone. Les vues qui couvrent plusieurs collections attendent un chargement. Les erreurs descendent de PuzzlesError, les soldes ont leur propre famille sous BalanceError. Le reste est dans les guides : records, registry, lookups, verification, balances.

🗺️ Collections

Clé	Puzzles	Chaînes	Ce que c'est
`b1000`	256	bitcoin	Clés de 1 à 256 bits, une adresse chacune
`rushwallet`	30	bitcoin	Brainwallets d'un concours de 2014
`zden`	15	bitcoin, ethereum, litecoin, decred	Les puzzles visuels de Zden
`arweave`	12	arweave, ethereum	Les puzzles de tissage de Tiamat
`warp`	6	bitcoin	Les défis brainwallet scrypt de Keybase
`hash_collision`	6	bitcoin	Les primes de collision P2SH de Peter Todd
`ballet`	3	bitcoin	Clés BIP38 imprimées sur des portefeuilles physiques
`bitimage`	2	bitcoin	Seeds hachées à partir de photographies
`bitaps`	1	bitcoin	Un schéma de partage de secret 3 sur 5
`gsmg`	1	bitcoin	Un puzzle d'images multi-phases
`movie_enigma`	1	bitcoin	Titres de films comme mots de seed, résolu en 2026

Les identifiants sont collection/name. Les trois singletons, gsmg, bitaps et movie_enigma, sont simplement la clé. Chaque collection a une page avec l'histoire, les particularités et chaque puzzle : puzzles.agntn.dev/collections.

🤖 Agents

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"] }
  }
}

Six outils : puzzles_stats, puzzles_collections, puzzles_show, puzzles_list, puzzles_verify et puzzles_balance. Seul le dernier quitte le processus, et ses annotations le disent. Ce que le texte transporte et où se situent les limites : le guide des agents.

boha v0.19.0