@agntn/puzzles
Public crypto puzzles and bounties, as typed records. You ask for a puzzle, you get its address, its key material and what happened on chain.
Why?
Every puzzle thread has the same three things: the addresses, the prizes, and who solved what. Every scanner and tracker re-types them from the thread, slightly differently each time. So they live here once, as code. A puzzle is a TypeScript record. The type checker reads it before a test does. The CLI, the MCP server and the Pi and OMP extensions read one registry.
Docs, one page per puzzle and a live playground: puzzles.agntn.dev.
[!WARNING] Pre-1.0. The API, the CLI flags and the data model can still move. Pin an exact version if you build on it.
✨ Features
- 🧾 Data as code. One
PuzzleSpecliteral per puzzle, built by onepuzzle()factory for every chain. No JSON, no build step. - 🕳️ Absent means absent. A puzzle without a solver or a prize has no such key. Nothing serializes as null.
- 🔑 Key material in every shape. Hex, WIF, a BIP38 payload, a seed phrase, secret shares, a sealed Arweave keyfile, or just a bit width. Every key of a multisig, too. One builder.
- 💤 Lazy registry. Importing the package loads no records.
get("bits/71")imports one collection module. - ✅ Verification is a value. A published key derives the address or it doesn't. Nothing throws for a bad record.
- 💰 Live balances.
puzzle.balance()through@agntn/explorers. Base units asbigint, API keys redacted from errors. - 👀 A watch on the record.
puzzles watchlists the deposits and spends a record misses, a prize that moved, a public key a spend gave away, a source page that changed. It never edits a record. You do. - 📋 A checklist before the weekend.
puzzles eligibilitygathers the source, the address, lifetime totals from the explorer, the status with its evidence and what counts as a solution. Whatever nobody can fill comes back as amissingrow, never a guess. - 🖼️ The puzzle itself, not a link to it.
puzzles_assetshands a model the image, the stage files and the archived posts behind the hints, checked against the SHA-256 the record pins. Links rot. These don't. - 🤖 Fifteen agent tools. One executor behind MCP, Pi and OMP. Same answer everywhere.
- 🌐 Runs anywhere. Neutral ESM on the Fetch API. Node, browsers, edge workers.
📦 Install
pnpm add @agntn/puzzles
Node.js 26 or newer for the CLI.
🚀 First call
npx @agntn/puzzles stats
That prints the total, one count per status and how many puzzles have a known public key. No key, no config, no network. The records ship inside the package. The bare puzzles below is pnpm exec puzzles after a local pnpm add, or just puzzles after pnpm add -g @agntn/puzzles.
puzzles show hash-collision/sha256
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
Commands
--json prints the data behind the text, bigint as strings and absent fields left out. The commands come from the same tool definitions the agents get, so a typo in a flag fails here just like it fails for a model. The flags and exit codes are in the CLI guide.
🧠 Library
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
That's most of it, really. A collection is its own entry and everything on it is synchronous. The views that span collections await a load. Errors descend from PuzzlesError, balances have their own family under BalanceError. The rest is in the guides: records, registry, lookups, verification, balances.
🗺️ Collections
Identifiers are collection/name. A singleton, such as gsmg, genesis or 80-bit, is just the key. Each collection has a page with the story, the quirks and every puzzle: puzzles.agntn.dev/collections.
🤖 Agents
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
{
"mcpServers": {
"puzzles": { "command": "npx", "args": ["-y", "@agntn/puzzles", "mcp"] }
}
}
Fifteen tools: 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 and puzzles_eligibility. The last three leave the process, and so does puzzles_assets when it reads a file. Their annotations say so. What the text carries and where the limits live: the agents guide.
🚫 What this does not do
It doesn't solve anything. No scanner, no kangaroo, no brainwallet cracker, and no guessing a status from a transaction list. solved, swept, claimed and expired are written down by hand, because a claim transaction plus a published key still means solved. Chain facts come from @agntn/chains, key derivation from @agntn/keys and balances from @agntn/explorers. This package doesn't reimplement any of them.
🧩 Adding a puzzle
One record file under src/collections/<key>/ and one line in the collection module. Then pnpm test runs the data gate: unique ids, address and txid formats, key derivation, BIP38 payloads, asset paths and their SHA-256, no nulls. The shape of a record is in Puzzle records and the rules in CONTRIBUTING.md.
🛠️ Development
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
💛 Thanks
This package exists thanks to the open source programs at Anthropic and OpenAI: Claude for Open Source and Codex for Open Source.