@agntn/puzzles

Puzzles e recompensas cripto públicos, como registros tipados. Você pede um puzzle, recebe o endereço, o material de chave e o que aconteceu on-chain.

Por quê?

Toda thread de puzzle 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 da thread, de forma ligeiramente diferente a cada vez. Então eles vivem aqui uma vez, como código. Um puzzle é 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 puzzle 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 puzzle, construído por uma única factory puzzle() para todas as chains. Sem JSON, sem etapa de build.
• 🕳️ Ausente significa ausente. Um puzzle sem solucionador ou sem prêmio não tem essa chave. Nada é serializado como null.
• 🔑 Material de chave em todos os formatos. Hex, WIF, um payload BIP38, uma seed phrase, shares secretos, um keyfile Arweave selado, ou apenas uma largura de bits. Também cada chave de um multisig. Um único builder.
• 💤 Registro lazy. Importar o pacote não carrega nenhum registro. get("bits/71") importa um módulo de coleção.
• ✅ Verificação é um valor. Uma chave publicada deriva o endereço ou não deriva. Nada lança exceção por um registro ruim.
• 💰 Saldos ao vivo. puzzle.balance() via @agntn/explorers. Unidades base como bigint, chaves de API redigidas dos erros.
• 👀 Uma vigilância sobre o registro. puzzles watch lista os depósitos e gastos que um registro deixa passar, um prêmio que se moveu, uma chave pública que um gasto revelou, uma página de origem que mudou. Ele nunca edita um registro. Você edita.
• 📋 Uma checklist antes do fim de semana. puzzles eligibility reúne a origem, o endereço, os totais vitalícios do explorer, o status com suas evidências e o que conta como solução. O que ninguém consegue preencher volta como uma linha missing, nunca um palpite.
• 🖼️ O puzzle em si, não um link para ele. puzzles_assets entrega a um modelo a imagem, os arquivos de etapa e as postagens arquivadas por trás das dicas, verificados contra o SHA-256 que o registro fixa. Links apodrecem. Estes não.
• 🤖 Quinze 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 sobre a Fetch API. Node, navegadores, edge workers.

📦 Instalação

pnpm add @agntn/puzzles

Node.js 26 ou mais recente para a CLI.

🚀 Primeira chamada

npx @agntn/puzzles stats

Isso imprime o total, uma contagem por status e quantos quebra-cabeças têm uma chave pública conhecida. 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 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

Comandos

Comando	O que imprime
puzzles stats	Totais, contagens de status, somas de prêmios e a versão dos dados
puzzles collections	Uma linha por coleção: chave, contagens, autor
puzzles authors [key]	Uma linha por autor, ou o registro de um autor com seus fatos de origem
puzzles author <key>	O registro de um autor, direto da ferramenta puzzles_author
puzzles solvers [key]	Uma linha por solver nomeado, ou o registro de um solver: cada resolução, perfis e fatos de origem
puzzles solver <key>	O registro de um solver, direto da ferramenta puzzles_solver
puzzles show <id>	O registro de um puzzle: material de chave, transações, dicas e links. --json para os dados
puzzles hints <id>	As dicas da coleção, as do próprio puzzle e depois seus arquivos de dicas. --json para ambos
puzzles stages <id>	Os estágios de um puzzle multiestágio com suas páginas, arquivos e respostas publicadas. --json para a lista
puzzles assets <id>	Os arquivos que um puzzle traz com SHA-256 e tamanho, e as páginas arquivadas que ele cita. --read <path> grava um, --check/--live verifica
puzzles list [collection]	Um puzzle por linha. --address, --chain, --status, --technique e --with-pubkey restringem, --limit e --offset paginam
puzzles verify [id]	Uma chave publicada e sua receita contra o endereço. --all ou os filtros de list para um conjunto, sai com 1 em caso de divergência
puzzles balance [id]	O saldo ao vivo. Os filtros de list verificam um conjunto inteiro, uma linha cada. --api-key, ou uma variável por chain
puzzles watch [id]	O que a chain sabe e o registro não. --since também verifica as páginas de origem, sai com 1 em qualquer achado
puzzles eligibility <query>	A checklist antes de trabalhar em um prêmio, por id ou endereço. Sai com 1 enquanto qualquer campo estiver faltando
puzzles export	Todo o conjunto de dados com seu data_version
puzzles mcp	O servidor MCP via stdio