@agntn/puzzles

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

Зачем?

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

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

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

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

• 🧾 Данные как код. Один литерал PuzzleSpec на пазл, создаваемый одной фабрикой puzzle() для любой сети. Никакого JSON, никакого шага сборки.
• 🕳️ Отсутствует — значит отсутствует. У пазла без решателя или приза нет такого ключа. Ничего не сериализуется как null.
• 🔑 Ключевой материал в любом виде. Hex, WIF, полезная нагрузка BIP38, seed-фраза, секретные доли, запечатанный keyfile Arweave или просто разрядность. И каждый ключ мультиподписи тоже. Один конструктор.
• 💤 Ленивый реестр. Импорт пакета не загружает ни одной записи. get("bits/71") импортирует один модуль коллекции.
• ✅ Проверка — это значение. Опубликованный ключ либо выводит адрес, либо нет. Ничего не выбрасывает исключение из-за плохой записи.
• 💰 Живые балансы. puzzle.balance() через @agntn/explorers. Базовые единицы как bigint, API-ключи скрываются в ошибках.
• 👀 Наблюдение за записью. puzzles watch перечисляет депозиты и траты, которые запись пропускает, переместившийся приз, публичный ключ, выданный тратой, изменившуюся исходную страницу. Он никогда не редактирует запись. Это делаете вы.
• 📋 Чек-лист перед выходными. puzzles eligibility собирает источник, адрес, суммарные итоги за всё время от обозревателя, статус с его доказательствами и то, что считается решением. Всё, что никто не может заполнить, возвращается строкой missing, а не догадкой.
• 🖼️ Сам пазл, а не ссылка на него. puzzles_assets передаёт модели изображение, файлы этапов и архивные посты за подсказками, сверенные с SHA-256, закреплённым в записи. Ссылки гниют. Эти — нет.
• 🤖 Пятнадцать инструментов для агентов. Один исполнитель за MCP, Pi и OMP. Одинаковый ответ везде.
• 🌐 Работает где угодно. Нейтральный ESM на Fetch API. Node, браузеры, edge-воркеры.

📦 Установка

pnpm add @agntn/puzzles

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

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

npx @agntn/puzzles stats

Он выводит общее количество, количество по каждому статусу и сколько головоломок имеют известный публичный ключ. Без ключа, без конфигурации, без сети. Записи поставляются внутри пакета. Команда puzzles ниже — это pnpm exec puzzles после локального pnpm add, или просто puzzles после 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

Команды

Команда	Что выводит
puzzles stats	Итоговые значения, количество по статусам, суммы призов и версия данных
puzzles collections	Одна строка на коллекцию: ключ, количество, автор
puzzles authors [key]	Одна строка на автора или запись одного автора с фактами из источников
puzzles author <key>	Запись одного автора, напрямую из инструмента puzzles_author
puzzles solvers [key]	Одна строка на именованного решателя или запись одного решателя: все решения, профили и факты из источников
puzzles solver <key>	Запись одного решателя, напрямую из инструмента puzzles_solver
puzzles show <id>	Запись одной головоломки: ключевой материал, транзакции, подсказки и ссылки. --json для данных
puzzles hints <id>	Подсказки коллекции, затем собственные подсказки головоломки, затем её файлы подсказок. --json для обоих
puzzles stages <id>	Этапы многоэтапной головоломки с их страницами, файлами и опубликованными ответами. --json для списка
puzzles assets <id>	Файлы, поставляемые с головоломкой, с SHA-256 и размером, и архивные страницы, на которые она ссылается. --read <path> записывает один, --check/--live проверяют
puzzles list [collection]	Одна головоломка на строку. --address, --chain, --status, --technique и --with-pubkey сужают выборку, --limit и --offset задают страницы
puzzles verify [id]	Опубликованный ключ и его рецепт против адреса. --all или фильтры list для набора, код выхода 1 при несовпадении
puzzles balance [id]	Актуальный баланс. Фильтры list проверяют целый набор, по одной строке на элемент. --api-key или одна переменная на цепочку
puzzles watch [id]	Что знает цепочка, а запись — нет. --since также проверяет исходные страницы, код выхода 1 при любой находке
puzzles eligibility <query>	Контрольный список перед работой над призом, по id или адресу. Код выхода 1, пока какое-либо поле отсутствует
puzzles export	Весь набор данных с его data_version
puzzles mcp	MCP-сервер через stdio

--json выводит данные, стоящие за текстом, bigint в виде строк, а отсутствующие поля опускаются. Команды происходят из тех же определений инструментов, которые получают агенты, поэтому опечатка во флаге завершится ошибкой здесь так же, как и у модели. Флаги и коды выхода описаны в руководстве по CLI.