@agntn/puzzles

🧩 333 puzles y recompensas cripto públicas en once colecciones, como registros tipados. Pides un puzle y obtienes su dirección, su material de clave y lo que ocurrió en la cadena.

¿Por qué?

Cada hilo de puzles tiene las mismas tres cosas: las direcciones, los premios y quién resolvió qué. Cada escáner y rastreador las vuelve a escribir a partir del hilo, de forma ligeramente distinta cada vez. Así que viven aquí una sola vez, como código. Un puzle es un registro de TypeScript. El comprobador de tipos lo lee antes que un test. La CLI, el servidor MCP y las extensiones de Pi y OMP leen un único registro.

Documentación, una página por puzle y un playground en vivo: puzzles.agntn.dev.

[!WARNING] Pre-1.0. La API, los flags de la CLI y el modelo de datos aún pueden cambiar. Fija una versión exacta si construyes sobre esto.

✨ Características

🧾 Datos como código. Un literal PuzzleSpec por puzle, construido por una factoría para su cadena. Sin JSON, sin paso de compilación.
🕳️ Ausente significa ausente. Un puzle sin solucionador o sin premio no tiene esa clave. Nada se serializa como null.
🔑 Material de clave en todas las formas. Hex, WIF, una carga útil BIP38, una frase semilla, participaciones secretas, o simplemente un ancho de bits. Un único constructor.
💤 Registro perezoso. Importar el paquete no carga ningún registro. get("b1000/71") importa un módulo de colección.
✅ La verificación es un valor. Una clave publicada deriva la dirección o no lo hace. Nada lanza una excepción por un registro incorrecto.
💰 Saldos en vivo. puzzle.balance() a través de @agntn/explorers. Unidades base como bigint, claves de API censuradas en los errores.
🤖 Seis herramientas de agente. Un único ejecutor detrás de MCP, Pi y OMP. La misma respuesta en todas partes.
🌐 Se ejecuta en cualquier lugar. ESM neutro sobre la Fetch API. Node, navegadores, workers de borde.

📦 Instalación

pnpm add @agntn/puzzles

Node.js 24 o superior para la CLI.

🚀 Primera llamada

npx @agntn/puzzles stats

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

Sin clave, sin configuración, sin red. Los registros se incluyen dentro del paquete. El puzzles a secas de abajo es pnpm exec puzzles tras un pnpm add local, o simplemente puzzles tras pnpm add -g @agntn/puzzles.

puzzles show b1000/71

b1000/71	unsolved	7.100226 BTC	1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU

Comandos

Comando	Qué imprime
`puzzles stats`	Totales y recuentos por estado. `--json` añade las sumas de premios
`puzzles collections`	Una fila por colección: clave, recuentos, autor
`puzzles show <id>`	Un puzle. `--json` para el registro completo
`puzzles list [collection]`	Un puzle por línea. `--status` y `--with-pubkey` lo acotan
`puzzles verify [id]`	Una clave publicada contra su dirección. `--all` para cada puzle, salida 1 si hay discrepancia
`puzzles balance <id>`	El saldo en vivo. `--api-key` o `ETHERSCAN_API_KEY` para Ethereum
`puzzles export`	Todo el conjunto de datos con su `data_version`
`puzzles mcp`	El servidor MCP sobre stdio

--json es el mismo serializador en todas partes, bigint como cadenas y los campos ausentes omitidos. Los flags y los códigos de salida están en la guía de la CLI.

🧠 Biblioteca

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

Eso es casi todo, la verdad. Una colección es su propia entrada y todo en ella es síncrono. Las vistas que abarcan colecciones esperan una carga. Los errores descienden de PuzzlesError, los saldos tienen su propia familia bajo BalanceError. El resto está en las guías: registros, registro, búsquedas, verificación, saldos.

🗺️ Colecciones

Clave	Puzles	Cadenas	Qué es
`b1000`	256	bitcoin	Claves de 1 a 256 bits, una dirección cada una
`rushwallet`	30	bitcoin	Brainwallets de un concurso de 2014
`zden`	15	bitcoin, ethereum, litecoin, decred	Los puzles visuales de Zden
`arweave`	12	arweave, ethereum	Los puzles de tejido de Tiamat
`warp`	6	bitcoin	Los desafíos de brainwallet scrypt de Keybase
`hash_collision`	6	bitcoin	Las recompensas de colisión P2SH de Peter Todd
`ballet`	3	bitcoin	Claves BIP38 impresas en carteras físicas
`bitimage`	2	bitcoin	Semillas con hash a partir de fotografías
`bitaps`	1	bitcoin	Un esquema de reparto secreto 3 de 5
`gsmg`	1	bitcoin	Un puzle de imágenes multifase
`movie_enigma`	1	bitcoin	Títulos de películas como palabras semilla, resuelto en 2026

Los identificadores son collection/name. Los tres singletons, gsmg, bitaps y movie_enigma, son solo la clave. Cada colección tiene una página con la historia, las peculiaridades y cada puzle: puzzles.agntn.dev/collections.

🤖 Agentes

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

Seis herramientas: puzzles_stats, puzzles_collections, puzzles_show, puzzles_list, puzzles_verify y puzzles_balance. Solo la última sale del proceso, y sus anotaciones lo indican. Qué lleva el texto y dónde están los límites: la guía de agentes.

boha v0.19.0