@agntn/puzzles

🧩 333 öffentliche Krypto-Puzzles und Bounties in elf Sammlungen, als typisierte Records. Du fragst nach einem Puzzle, du bekommst seine Adresse, sein Schlüsselmaterial und was on chain passiert ist.

Warum?

Jeder Puzzle-Thread hat dieselben drei Dinge: die Adressen, die Preise und wer was gelöst hat. Jeder Scanner und Tracker tippt sie aus dem Thread neu ab, jedes Mal etwas anders. Also leben sie hier einmal, als Code. Ein Puzzle ist ein TypeScript-Record. Der Type Checker liest ihn, bevor ein Test es tut. Die CLI, der MCP-Server und die Pi- und OMP-Erweiterungen lesen ein Registry.

Dokumentation, eine Seite pro Puzzle und ein Live-Playground: puzzles.agntn.dev.

[!WARNING] Pre-1.0. Die API, die CLI-Flags und das Datenmodell können sich noch bewegen. Pinne eine exakte Version, wenn du darauf aufbaust.

✨ Features

🧾 Daten als Code. Ein PuzzleSpec-Literal pro Puzzle, gebaut von einer Factory für seine Chain. Kein JSON, kein Build-Schritt.
🕳️ Fehlend heißt fehlend. Ein Puzzle ohne Solver oder Preis hat keinen solchen Key. Nichts serialisiert als null.
🔑 Schlüsselmaterial in jeder Form. Hex, WIF, eine BIP38-Payload, eine Seed-Phrase, Secret Shares oder nur eine Bitbreite. Ein Builder.
💤 Lazy Registry. Das Importieren des Pakets lädt keine Records. get("b1000/71") importiert ein Sammlungsmodul.
✅ Verifikation ist ein Wert. Ein veröffentlichter Schlüssel leitet die Adresse ab oder nicht. Nichts wirft bei einem fehlerhaften Record.
💰 Live-Balances. puzzle.balance() über @agntn/explorers. Base Units als bigint, API-Keys aus Fehlern redigiert.
🤖 Sechs Agent-Tools. Ein Executor hinter MCP, Pi und OMP. Überall dieselbe Antwort.
🌐 Läuft überall. Neutrales ESM auf der Fetch API. Node, Browser, Edge Worker.

📦 Installation

pnpm add @agntn/puzzles

Node.js 24 oder neuer für die CLI.

🚀 Erster Aufruf

npx @agntn/puzzles stats

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

Kein Key, keine Konfiguration, kein Netzwerk. Die Records werden im Paket mitgeliefert. Das bloße puzzles unten ist pnpm exec puzzles nach einem lokalen pnpm add, oder einfach puzzles nach pnpm add -g @agntn/puzzles.

puzzles show b1000/71

b1000/71	unsolved	7.100226 BTC	1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU

Befehle

Befehl	Was er ausgibt
`puzzles stats`	Summen und Status-Zählungen. `--json` fügt die Preissummen hinzu
`puzzles collections`	Eine Zeile pro Sammlung: Key, Zählungen, Autor
`puzzles show <id>`	Ein Puzzle. `--json` für den ganzen Record
`puzzles list [collection]`	Ein Puzzle pro Zeile. `--status` und `--with-pubkey` grenzen es ein
`puzzles verify [id]`	Ein veröffentlichter Schlüssel gegen seine Adresse. `--all` für jedes Puzzle, Exit 1 bei Abweichung
`puzzles balance <id>`	Die Live-Balance. `--api-key` oder `ETHERSCAN_API_KEY` für Ethereum
`puzzles export`	Der ganze Datensatz mit seiner `data_version`
`puzzles mcp`	Der MCP-Server über stdio

--json ist überall derselbe Serializer, bigint als Strings und fehlende Felder weggelassen. Die Flags und Exit-Codes stehen im CLI-Leitfaden.

🧠 Bibliothek

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

Das ist das meiste, wirklich. Eine Sammlung ist ihr eigener Einstieg und alles an ihr ist synchron. Die Ansichten, die Sammlungen überspannen, erwarten ein Laden. Fehler stammen von PuzzlesError ab, Balances haben ihre eigene Familie unter BalanceError. Der Rest steht in den Leitfäden: Records, Registry, Lookups, Verifikation, Balances.

🗺️ Sammlungen

Key	Puzzles	Chains	Was es ist
`b1000`	256	bitcoin	Schlüssel von 1 bis 256 Bit, je eine Adresse
`rushwallet`	30	bitcoin	Brainwallets aus einem Wettbewerb von 2014
`zden`	15	bitcoin, ethereum, litecoin, decred	Zdans visuelle Puzzles
`arweave`	12	arweave, ethereum	Tiamats Weave-Puzzles
`warp`	6	bitcoin	Keybases scrypt-Brainwallet-Challenges
`hash_collision`	6	bitcoin	Peter Todds P2SH-Kollisions-Bounties
`ballet`	3	bitcoin	BIP38-Schlüssel, gedruckt auf physischen Wallets
`bitimage`	2	bitcoin	Seeds, gehasht aus Fotografien
`bitaps`	1	bitcoin	Ein 3-von-5-Secret-Sharing-Schema
`gsmg`	1	bitcoin	Ein mehrphasiges Bild-Puzzle
`movie_enigma`	1	bitcoin	Filmtitel als Seed-Wörter, gelöst 2026

Bezeichner sind collection/name. Die drei Singletons, gsmg, bitaps und movie_enigma, sind einfach der Key. Jede Sammlung hat eine Seite mit der Geschichte, den Eigenheiten und jedem 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"] }
  }
}

Sechs Tools: puzzles_stats, puzzles_collections, puzzles_show, puzzles_list, puzzles_verify und puzzles_balance. Nur das letzte verlässt den Prozess, und seine Annotationen sagen das. Was der Text trägt und wo die Grenzen liegen: der Agents-Leitfaden.

boha v0.19.0