oritwoen/bohaBiblioteca de dados de bounties, puzzles e desafios crypto
# @agntn/puzzles
[](https://npmx.dev/package/@agntn/puzzles)
[](https://npmx.dev/package/@agntn/puzzles)
[](https://npmx.dev/package/@agntn/puzzles)
[](https://deepwiki.com/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](https://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
```bash
pnpm add @agntn/puzzles
```
Node.js 26 ou mais recente para a CLI.
## 🚀 Primeira chamada
```bash
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`.
```bash
puzzles show hash-collision/sha256
```
```text
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 |
`--json` imprime os dados por trás do texto, `bigint` como strings e campos ausentes omitidos. Os comandos vêm das mesmas definições de ferramenta que os agentes recebem, então um erro de digitação em uma flag falha aqui da mesma forma que falha para um modelo. As flags e códigos de saída estão no [guia da CLI](https://puzzles.agntn.dev/guide/cli).
## 🧠 Biblioteca
```ts
import { get, stats, verify } from "@agntn/puzzles";
import { bits } from "@agntn/puzzles/collections/bits";
const puzzle = await get("bits/71"); // loads the bits collection, nothing else
puzzle?.address().value; // "1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU"
puzzle?.keyRange(); // [2n ** 70n, 2n ** 71n - 1n]
(await verify(bits.require(1))).verified; // true, key 1 derives its address
(await stats()).unsolved; // how many are still waiting for a key
(await bits.require(71).balance()).totalUnits(); // 7.10190014 when I ran it, mempool.space decides
```
É basicamente isso. Uma coleção é uma entrada própria e tudo nela é síncrono. As views que abrangem coleções aguardam um carregamento. Os erros descendem de `PuzzlesError`, os saldos têm a sua própria família sob `BalanceError`. O resto está nos guias: [records](https://puzzles.agntn.dev/guide/records), [registry](https://puzzles.agntn.dev/guide/registry), [lookups](https://puzzles.agntn.dev/guide/lookups), [verification](https://puzzles.agntn.dev/guide/verification), [balances](https://puzzles.agntn.dev/guide/balances).
## 🗺️ Coleções
| Chave | Chains | O que é |
| --------------------------- | ----------------------------------- | ------------------------------------------- |
| `bits` | bitcoin | Chaves de 1 a 256 bits, um endereço cada |
| `quizchain` | bitcoin | Blocos de quiz encadeados por suas chaves |
| `quizchain2` | bitcoin | Segunda edição do Quizchain, de maio de 2019 |
| `rushwallet` | bitcoin | Brainwallets de um concurso de 2014 |
| `zden` | bitcoin, ethereum, litecoin, decred | Quebra-cabeças visuais de Zden |
| `weave` | arweave, ethereum | Série Puzzle Weave de Tiamat |
| `move-over-brokers` | bitcoin | Doze chaves escondidas em um livro de blockchain |
| `mini` | bitcoin, bitcoincash | Sete mini-quebra-cabeças de RetiredCoder |
| `warp` | bitcoin | Desafios de brainwallet scrypt da Keybase |
| `hash-collision` | bitcoin | Recompensas de colisão P2SH de Peter Todd |
| `teikhos` | ethereum | Contratos que pagam por uma chave pública |
| `ballet` | bitcoin | Chaves BIP38 impressas em carteiras físicas |
| `dug` | bitcoin | Caça a seeds de estudantes de 2025 |
| `coin-games` | bitcoin | Cédulas com uma caveira, um leão e Vênus |
| `bitimage` | bitcoin | Seeds geradas a partir de fotografias |
| `luckylurker` | bitcoin | Dois desafios de seed do Bitcoin Vault |
| `iamabananaamaa` | bitcoin | Um ZIP em um GIF, depois um falso César |
| `doges-gambit` | ethereum, dogecoin | Duas chaves lidas de um vídeo de tabuleiro de xadrez |
| `crypto-puzzles` | ethereum | Chaves de Ether brutas escondidas em vídeos curtos |
| `walking-banks` | bitcoin | Uma seed escondida em um romance de suspense sobre Bitcoin |
| `grycoin` | bitcoin | Quizchain renomeado, dias antes do encerramento |
| `smith-lyle-moore` | bitcoin | Duas caças de uma banda, uma por single |
| `real-big-block` | bitcoin | 777 mBTC por um capítulo do Wattpad, não resgatado |
| `school-of-bitcoin` | bitcoin | Um cartão de visita com 1M de sats no verso |
| `liberte-guidant-le-peuple` | bitcoin | Delacroix em coletes amarelos, seed em francês |
| `hunting-time` | bitcoin | Palavras de seed disfarçadas de horários em um romance |
| `bitaps` | bitcoin | Um esquema de compartilhamento de segredo 3 de 5 |
| `gsmg` | bitcoin | Um quebra-cabeça de imagem em várias fases |
| `movie-enigma` | bitcoin | Títulos de filmes como palavras de seed, resolvido em 2026 |
| `ledger-donjon` | bitcoin | Scissors Secret Sharing do CTF |
| `coin-artist` | bitcoin | Pintura TORCHED H34R7S |
| `genesis` | bitcoin | Quebra-cabeça OP_RETURN do bloco gênese |
| `mineshop` | ethereum | Uma seed dividida entre um vídeo e uma postagem |
| `satoshi-birthday-quiz` | bitcoin | Sete respostas de quiz transformadas em hash para uma carteira |
| `book-quiz` | bitcoin | Um quiz de livro que ninguém venceu a tempo |
| `80-bit` | bitcoin | 80 bits ocultos e uma corrida na mempool |
| `wickex` | bitcoin | Hex, Morse e uma passphrase em espectrograma |
| `picture-puzzle` | bitcoin | Quatro imagens que formam um banco de chaves |
| `brave-new-world` | bitcoin | Uma seed phrase escondida em uma colagem de 2020 |
| `wealth-in-poetry` | bitcoin | Palavras de seed escondidas em um ensaio do Medium de 2019 |
| `path-to-greatness` | litecoin | Pistas de uma demo de jogo, uma chave Litecoin |
| `proof-of-writing` | ecash | Uma seed do Cashtab na diagonal de um ensaio |
| `bitaddress` | bitcoin | Uma carteira BIP38 com uma passphrase esquecida |
| `powerful-moss` | base | Uma seed em um álbum, o prêmio em um contrato |
| `trivia-brainwallet` | bitcoin | Doze charadas de trivia temperadas com scrypt |
| `great-riddle` | bitcoin | Palavras de seed escondidas em desenhos a caneta esferográfica |
| `satoshi-maze` | bitcoin | Um primo de e vezes duas palavras Base58 |
| `natasha-otomoski` | bitcoin | Oito palavras em camel case como bytes brutos de chave |
| `phy` | bitcoin | Um post assinado e uma espiral de emojis cinzas |
| `seed-phrase` | bitcoin | Pistas datadas, depois dois anos de silêncio |
| `9vw04` | bitcoin | Uma WIF em um tweet, arco-íris não incluídos |
Os identificadores são `collection/name`. Um singleton, como `gsmg`, `genesis` ou `80-bit`, é apenas a chave. Cada coleção tem uma página com a história, as peculiaridades e todos os puzzles: [puzzles.agntn.dev/collections](https://puzzles.agntn.dev/collections).
## 🤖 Agentes
```bash
claude mcp add puzzles --scope user -- npx -y @agntn/puzzles mcp
claude mcp add --transport http puzzles https://puzzles.agntn.dev/mcp # nothing to install
pi install npm:@agntn/puzzles
```
```json
{
"mcpServers": {
"puzzles": { "command": "npx", "args": ["-y", "@agntn/puzzles", "mcp"] }
}
}
```
Quinze ferramentas: `puzzles_stats`, `puzzles_collections`, `puzzles_authors`, `puzzles_author`, `puzzles_solvers`, `puzzles_solver`, `puzzles_show`, `puzzles_hints`, `puzzles_stages`, `puzzles_assets`, `puzzles_list`, `puzzles_verify`, `puzzles_balance`, `puzzles_watch` e `puzzles_eligibility`. As três últimas encerram o processo, e o mesmo faz `puzzles_assets` quando lê um ficheiro. As suas anotações dizem-no. O que o texto transporta e onde vivem os limites: o [guia dos agentes](https://puzzles.agntn.dev/guide/agents).
## 🚫 O que isto não faz
Não resolve nada. Sem scanner, sem kangaroo, sem brainwallet cracker, e sem adivinhar um estado a partir de uma lista de transações. `solved`, `swept`, `claimed` e `expired` são escritos à mão, porque uma transação de claim mais uma chave publicada continua a significar resolvido. Os factos da chain vêm de `@agntn/chains`, a derivação de chaves de `@agntn/keys` e os saldos de `@agntn/explorers`. Este pacote não reimplementa nenhum deles.
## 🧩 Adicionar um puzzle
Um ficheiro de registo em `src/collections/<key>/` e uma linha no módulo da coleção. Depois `pnpm test` executa o data gate: ids únicos, formatos de endereço e txid, derivação de chaves, payloads BIP38, caminhos de assets e o seu SHA-256, sem nulos. A forma de um registo está em [Puzzle records](https://puzzles.agntn.dev/guide/records) e as regras em [CONTRIBUTING.md](https://github.com/oritwoen/boha/blob/main/CONTRIBUTING.md).
## 🛠️ Desenvolvimento
```bash
pnpm install
pnpm --dir docs install # the docs site; lint and test read the Nuxt types it generates
pnpm lint # vp lint and vp fmt, docs included
pnpm typecheck # builds first, then checks src, Pi and OMP
pnpm test # unit tests and the data gate
pnpm test:packed # packs the tarball and runs every published entry without src/
pnpm docs # the Docus site on localhost
```
## 💛 Agradecimentos
Este pacote existe graças aos programas de código aberto da Anthropic e da OpenAI: [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) e [Codex for Open Source](https://developers.openai.com/community/codex-for-oss).
## 📄 Licença
[MIT](https://github.com/oritwoen/boha/blob/main/LICENSE)