@agntn/puzzles

🧩 333 quebra-cabeças e recompensas de criptografia públicos em onze coleções, como registros tipados. Você pede um quebra-cabeça, recebe seu endereço, seu material de chave e o que aconteceu na chain.

Por quê?

Todo tópico de quebra-cabeça tem as mesmas três coisas: os endereços, os prêmios e quem resolveu o quê. Todo scanner e rastreador os redigita a partir do tópico, de forma ligeiramente diferente a cada vez. Então eles vivem aqui uma vez, como código. Um quebra-cabeça é um registro TypeScript. O verificador de tipos o lê antes de um teste. A CLI, o servidor MCP e as extensões Pi e OMP leem um único registro.

Documentação, uma página por quebra-cabeça e um playground ao vivo: puzzles.agntn.dev.

[!WARNING] Pré-1.0. A API, as flags da CLI e o modelo de dados ainda podem mudar. Fixe uma versão exata se você construir sobre isso.

✨ Recursos

🧾 Dados como código. Um literal PuzzleSpec por quebra-cabeça, construído por uma factory para sua chain. Sem JSON, sem etapa de build.
🕳️ Ausente significa ausente. Um quebra-cabeça sem solucionador ou prêmio não tem tal chave. Nada é serializado como null.
🔑 Material de chave em todos os formatos. Hex, WIF, um payload BIP38, uma frase semente, compartilhamentos secretos, ou apenas uma largura de bits. Um único builder.
💤 Registro lazy. Importar o pacote não carrega nenhum registro. get("b1000/71") importa um módulo de coleção.
✅ Verificação é um valor. Uma chave publicada deriva o endereço ou não. Nada lança exceção por um registro ruim.
💰 Saldos ao vivo. puzzle.balance() através de @agntn/explorers. Unidades base como bigint, chaves de API ocultadas dos erros.
🤖 Seis ferramentas de agente. Um executor por trás de MCP, Pi e OMP. A mesma resposta em todos os lugares.
🌐 Roda em qualquer lugar. ESM neutro na Fetch API. Node, navegadores, edge workers.

📦 Instalação

pnpm add @agntn/puzzles

Node.js 24 ou mais recente para a CLI.

🚀 Primeira chamada

npx @agntn/puzzles stats

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

Sem chave, sem configuração, sem rede. Os registros vêm dentro do pacote. O puzzles simples abaixo é pnpm exec puzzles após um pnpm add local, ou apenas puzzles após pnpm add -g @agntn/puzzles.

puzzles show b1000/71

b1000/71	unsolved	7.100226 BTC	1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU

Comandos

Comando	O que ele imprime
`puzzles stats`	Totais e contagens de status. `--json` adiciona as somas dos prêmios
`puzzles collections`	Uma linha por coleção: chave, contagens, autor
`puzzles show <id>`	Um quebra-cabeça. `--json` para o registro inteiro
`puzzles list [collection]`	Um quebra-cabeça por linha. `--status` e `--with-pubkey` restringem
`puzzles verify [id]`	Uma chave publicada contra seu endereço. `--all` para cada quebra-cabeça, exit 1 em caso de divergência
`puzzles balance <id>`	O saldo ao vivo. `--api-key` ou `ETHERSCAN_API_KEY` para Ethereum
`puzzles export`	Todo o conjunto de dados com seu `data_version`
`puzzles mcp`	O servidor MCP via stdio

--json é o mesmo serializador em todos os lugares, bigint como strings e campos ausentes omitidos. As flags e códigos de saída estão no guia da 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

Isso é a maior parte, na verdade. Uma coleção é sua própria entrada e tudo nela é síncrono. As views que abrangem coleções aguardam um carregamento. Os erros descendem de PuzzlesError, os saldos têm sua própria família sob BalanceError. O resto está nos guias: registros, registro, consultas, verificação, saldos.

🗺️ Coleções

Chave	Quebra-cabeças	Chains	O que é
`b1000`	256	bitcoin	Chaves de 1 a 256 bits, um endereço cada
`rushwallet`	30	bitcoin	Brainwallets de um concurso de 2014
`zden`	15	bitcoin, ethereum, litecoin, decred	Os quebra-cabeças visuais de Zden
`arweave`	12	arweave, ethereum	Os quebra-cabeças de tecelagem de Tiamat
`warp`	6	bitcoin	Os desafios de brainwallet scrypt do Keybase
`hash_collision`	6	bitcoin	As recompensas de colisão P2SH de Peter Todd
`ballet`	3	bitcoin	Chaves BIP38 impressas em carteiras físicas
`bitimage`	2	bitcoin	Sementes com hash de fotografias
`bitaps`	1	bitcoin	Um esquema de compartilhamento secreto 3 de 5
`gsmg`	1	bitcoin	Um quebra-cabeça de imagem multifásico
`movie_enigma`	1	bitcoin	Títulos de filmes como palavras-semente, resolvido em 2026

Os identificadores são collection/name. Os três singletons, gsmg, bitaps e movie_enigma, são apenas a chave. Cada coleção tem uma página com a história, as peculiaridades e cada quebra-cabeça: 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 ferramentas: puzzles_stats, puzzles_collections, puzzles_show, puzzles_list, puzzles_verify e puzzles_balance. Apenas a última sai do processo, e suas anotações dizem isso. O que o texto carrega e onde os limites estão: o guia de agentes.

boha v0.19.0