@agntn/puzzles

🧩 333 публичных криптопазла и баунти в одиннадцати коллекциях, в виде типизированных записей. Вы запрашиваете пазл — вы получаете его адрес, его ключевой материал и то, что произошло в блокчейне.

Зачем?

В каждой теме с пазлами есть три вещи: адреса, призы и кто что решил. Каждый сканер и трекер перепечатывает их из темы, каждый раз немного по-своему. Поэтому они хранятся здесь один раз, в виде кода. Пазл — это запись TypeScript. Проверка типов читает её раньше, чем тест. CLI, MCP-сервер, а также расширения для Pi и OMP читают один реестр.

Документация, по странице на каждый пазл, и живая песочница: puzzles.agntn.dev.

[!WARNING] Версия до 1.0. API, флаги CLI и модель данных всё ещё могут меняться. Фиксируйте точную версию, если строите на этом.

✨ Возможности

🧾 Данные как код. Один литерал PuzzleSpec на пазл, создаваемый фабрикой для его сети. Никакого JSON, никакого шага сборки.
🕳️ Отсутствует — значит отсутствует. У пазла без решателя или приза нет такого ключа. Ничего не сериализуется как null.
🔑 Ключевой материал в любой форме. Hex, WIF, полезная нагрузка BIP38, seed-фраза, секретные доли или просто разрядность. Один конструктор.
💤 Ленивый реестр. Импорт пакета не загружает ни одной записи. get("b1000/71") импортирует один модуль коллекции.
✅ Верификация — это значение. Опубликованный ключ либо выводит адрес, либо нет. Ничего не выбрасывает исключение из-за плохой записи.
💰 Живые балансы. puzzle.balance() через @agntn/explorers. Базовые единицы как bigint, API-ключи скрыты из ошибок.
🤖 Шесть инструментов для агентов. Один исполнитель за MCP, Pi и OMP. Одинаковый ответ везде.
🌐 Работает где угодно. Нейтральный ESM на Fetch API. Node, браузеры, edge-воркеры.

📦 Установка

pnpm add @agntn/puzzles

Node.js 24 или новее для CLI.

🚀 Первый вызов

npx @agntn/puzzles stats

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

Без ключа, без конфигурации, без сети. Записи поставляются внутри пакета. Голый puzzles ниже — это pnpm exec puzzles после локального pnpm add, или просто puzzles после pnpm add -g @agntn/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` для Ethereum
`puzzles export`	Весь набор данных с его `data_version`
`puzzles mcp`	MCP-сервер через stdio

--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	Brainwallet'ы из конкурса 2014 года
`zden`	15	bitcoin, ethereum, litecoin, decred	Визуальные пазлы Zden
`arweave`	12	arweave, ethereum	Пазлы-плетения Tiamat
`warp`	6	bitcoin	Scrypt brainwallet-задачи от Keybase
`hash_collision`	6	bitcoin	Баунти Peter Todd за коллизии P2SH
`ballet`	3	bitcoin	Ключи BIP38, напечатанные на физических кошельках
`bitimage`	2	bitcoin	Seed-фразы, захешированные из фотографий
`bitaps`	1	bitcoin	Схема разделения секрета 3 из 5
`gsmg`	1	bitcoin	Многофазный графический пазл
`movie_enigma`	1	bitcoin	Названия фильмов как seed-слова, решён в 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. Только последний покидает процесс, и его аннотации об этом говорят. Что несёт текст и где проходят границы: руководство по агентам.

boha v0.19.0