@agntn/puzzles

🧩 333 个公开的加密谜题与赏金，分布在十一个集合中，以类型化记录的形式呈现。你请求一个谜题，就能得到它的地址、密钥材料以及链上发生的情况。

为什么？

每个谜题帖子都有同样的三样东西：地址、奖金，以及谁解开了什么。每个扫描器和追踪器都会从帖子中重新录入这些信息，每次都会略有不同。所以它们在这里以代码的形式存在一次。一个谜题就是一条 TypeScript 记录。类型检查器在测试之前读取它。CLI、MCP 服务器以及 Pi 和 OMP 扩展读取同一个注册表。

文档，每个谜题一页，外加一个实时演练场：puzzles.agntn.dev。

[!WARNING] 1.0 之前。API、CLI 标志和数据模型仍可能变动。如果你要基于它构建，请固定一个确切的版本。

✨ 特性

🧾 数据即代码。 每个谜题一个 PuzzleSpec 字面量，由其链的工厂构建。没有 JSON，没有构建步骤。
🕳️ 缺失就是缺失。 没有求解者或奖金的谜题就没有相应的键。任何内容都不会序列化为 null。
🔑 各种形态的密钥材料。 十六进制、WIF、BIP38 载荷、助记词、秘密共享，或者仅仅是一个位宽。一个构建器。
💤 惰性注册表。 导入该包不会加载任何记录。get("b1000/71") 只导入一个集合模块。
✅ 验证是一个值。 已发布的密钥要么能推导出地址，要么不能。坏记录不会抛出异常。
💰 实时余额。 通过 @agntn/explorers 调用 puzzle.balance()。基础单位为 bigint，API 密钥会从错误中隐去。
🤖 六个代理工具。 MCP、Pi 和 OMP 背后是同一个执行器。处处答案一致。
🌐 随处运行。 基于 Fetch API 的中立 ESM。Node、浏览器、边缘 worker。

📦 安装

pnpm add @agntn/puzzles

CLI 需要 Node.js 24 或更新版本。

🚀 首次调用

npx @agntn/puzzles stats

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

无需密钥、无需配置、无需网络。记录随包一起发布。下面裸写的 puzzles 是在本地 pnpm add 之后的 pnpm exec puzzles，或者在 pnpm add -g @agntn/puzzles 之后直接就是 puzzles。

puzzles show b1000/71

b1000/71	unsolved	7.100226 BTC	1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU

命令

命令	它打印的内容
`puzzles stats`	总计和状态计数。`--json` 会加上奖金总额
`puzzles collections`	每个集合一行：键、计数、作者
`puzzles show <id>`	一个谜题。`--json` 输出整条记录
`puzzles list [collection]`	每行一个谜题。`--status` 和 `--with-pubkey` 可缩小范围
`puzzles verify [id]`	用已发布的密钥对照其地址。`--all` 检查每个谜题，不匹配时退出码为 1
`puzzles balance <id>`	实时余额。以太坊用 `--api-key` 或 `ETHERSCAN_API_KEY`
`puzzles export`	整个数据集及其 `data_version`
`puzzles mcp`	基于 stdio 的 MCP 服务器

--json 在任何地方都是同一个序列化器，bigint 以字符串表示，缺失字段会被省略。标志和退出码见 CLI 指南。

🧠 库

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

差不多就这些了，真的。一个集合就是它自己的入口，其上的一切都是同步的。跨集合的视图会等待加载。错误继承自 PuzzlesError，余额在 BalanceError 下有自己的一族。其余内容在指南中：记录、注册表、查找、验证、余额。

🗺️ 集合

键	谜题数	链	它是什么
`b1000`	256	bitcoin	1 到 256 位的密钥，每个对应一个地址
`rushwallet`	30	bitcoin	来自 2014 年竞赛的脑钱包
`zden`	15	bitcoin, ethereum, litecoin, decred	Zden 的视觉谜题
`arweave`	12	arweave, ethereum	Tiamat 的编织谜题
`warp`	6	bitcoin	Keybase 的 scrypt 脑钱包挑战
`hash_collision`	6	bitcoin	Peter Todd 的 P2SH 碰撞赏金
`ballet`	3	bitcoin	印在物理钱包上的 BIP38 密钥
`bitimage`	2	bitcoin	从照片哈希得到的种子
`bitaps`	1	bitcoin	一个 3-of-5 秘密共享方案
`gsmg`	1	bitcoin	一个多阶段图像谜题
`movie_enigma`	1	bitcoin	电影标题作为种子词，2026 年解开

标识符是 collection/name。三个单例 gsmg、bitaps 和 movie_enigma 就是键本身。每个集合都有一个页面，包含故事、怪癖和每个谜题：puzzles.agntn.dev/collections。

🤖 代理

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

六个工具：puzzles_stats、puzzles_collections、puzzles_show、puzzles_list、puzzles_verify 和 puzzles_balance。只有最后一个会离开进程，它的注解也说明了这一点。文本携带什么以及限制在哪里：代理指南。

🚫 它不做什么

它不解决任何问题。没有扫描器，没有 kangaroo，没有脑钱包破解器，也不会从交易列表猜测状态。solved、swept、claimed 和 expired 都是手工写下的，因为一笔领取交易加上一个已发布的密钥仍然意味着已解开。链上事实来自 @agntn/chains，密钥派生来自 @agntn/keys，余额来自 @agntn/explorers。本包不会重新实现其中任何一个。

🧩 添加一个谜题

在 src/collections/<key>/ 下放一个记录文件，并在集合模块中加一行。然后 pnpm test 会运行数据门禁：唯一 id、地址和 txid 格式、密钥派生、BIP38 载荷、资产路径、无 null。记录的结构见谜题记录，规则见 CONTRIBUTING.md。

🛠️ 开发

pnpm install
pnpm --dir docs install   # the docs site; lint and test read the Nuxt types it generates
pnpm lint         # oxfmt and oxlint, 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

💛 致谢

本包的存在得益于 Anthropic 和 OpenAI 的开源项目：Claude for Open Source 和 Codex for Open Source。

📄 许可证

MIT

boha v0.19.0