@agntn/puzzles

🧩 11개 컬렉션에 걸친 333개의 공개 크립토 퍼즐과 바운티를 타입이 지정된 레코드로 제공합니다. 퍼즐을 요청하면 주소, 키 자료, 그리고 온체인에서 무슨 일이 있었는지 알려줍니다.

왜 필요한가?

모든 퍼즐 스레드에는 세 가지가 똑같이 있습니다: 주소, 상금, 그리고 누가 무엇을 풀었는지. 모든 스캐너와 트래커는 스레드에서 이들을 매번 조금씩 다르게 다시 입력합니다. 그래서 여기 코드로 한 번만 존재합니다. 퍼즐은 TypeScript 레코드입니다. 테스트보다 타입 검사기가 먼저 읽습니다. CLI, MCP 서버, Pi 및 OMP 확장은 하나의 레지스트리를 읽습니다.

문서, 퍼즐당 한 페이지, 그리고 라이브 플레이그라운드: puzzles.agntn.dev.

[!WARNING] 1.0 이전 버전입니다. API, CLI 플래그, 데이터 모델은 여전히 바뀔 수 있습니다. 이 위에 무언가를 만든다면 정확한 버전을 고정하세요.

✨ 기능

🧾 코드로서의 데이터. 퍼즐당 하나의 PuzzleSpec 리터럴, 해당 체인용 팩토리로 생성됩니다. JSON도, 빌드 단계도 없습니다.
🕳️ 없음은 없음. 해결자나 상금이 없는 퍼즐에는 그런 키가 없습니다. null로 직렬화되는 것은 없습니다.
🔑 모든 형태의 키 자료. Hex, WIF, BIP38 페이로드, 시드 구문, 비밀 공유, 또는 그냥 비트 폭. 하나의 빌더.
💤 지연 레지스트리. 패키지를 임포트해도 레코드가 로드되지 않습니다. get("b1000/71")은 하나의 컬렉션 모듈을 임포트합니다.
✅ 검증은 값입니다. 공개된 키가 주소를 도출하거나 도출하지 않습니다. 잘못된 레코드에 대해 아무것도 예외를 던지지 않습니다.
💰 실시간 잔액. @agntn/explorers를 통한 puzzle.balance(). 기본 단위는 bigint, API 키는 오류에서 가려집니다.
🤖 6개의 에이전트 도구. MCP, Pi, OMP 뒤의 하나의 실행기. 어디서나 같은 답변.
🌐 어디서나 실행. Fetch API 위의 중립 ESM. Node, 브라우저, 엣지 워커.

📦 설치

pnpm add @agntn/puzzles

CLI를 사용하려면 Node.js 24 이상이 필요합니다.

🚀 첫 호출

npx @agntn/puzzles stats

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

키도, 설정도, 네트워크도 필요 없습니다. 레코드는 패키지 안에 함께 제공됩니다. 아래의 그냥 puzzles는 로컬에서 pnpm add 후의 pnpm exec puzzles이거나, pnpm add -g @agntn/puzzles 후의 그냥 puzzles입니다.

puzzles show b1000/71

b1000/71	unsolved	7.100226 BTC	1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU

명령어

명령어	출력하는 내용
`puzzles stats`	합계와 상태 개수. `--json`은 상금 합계를 추가
`puzzles collections`	컬렉션당 한 행: 키, 개수, 작성자
`puzzles show <id>`	퍼즐 하나. `--json`은 전체 레코드
`puzzles list [collection]`	한 줄에 퍼즐 하나. `--status`와 `--with-pubkey`로 좁힘
`puzzles verify [id]`	공개된 키를 주소와 대조. `--all`은 모든 퍼즐, 불일치 시 종료 코드 1
`puzzles balance <id>`	실시간 잔액. Ethereum의 경우 `--api-key` 또는 `ETHERSCAN_API_KEY`
`puzzles export`	`data_version`과 함께 전체 데이터셋
`puzzles mcp`	stdio를 통한 MCP 서버

--json은 어디서나 같은 직렬화기이며, bigint는 문자열로, 없는 필드는 생략됩니다. 플래그와 종료 코드는 CLI 가이드에 있습니다.

🧠 라이브러리

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

정말로 이게 대부분입니다. 컬렉션은 자체 진입점이며 그 위의 모든 것은 동기적입니다. 컬렉션을 가로지르는 뷰는 로드를 기다립니다. 오류는 PuzzlesError에서 파생되며, 잔액은 BalanceError 아래에 자체 계열이 있습니다. 나머지는 가이드에 있습니다: 레코드, 레지스트리, 조회, 검증, 잔액.

🗺️ 컬렉션

키	퍼즐	체인	무엇인가
`b1000`	256	bitcoin	1~256비트의 키, 각각 하나의 주소
`rushwallet`	30	bitcoin	2014년 대회의 브레인월렛
`zden`	15	bitcoin, ethereum, litecoin, decred	Zden의 시각적 퍼즐
`arweave`	12	arweave, ethereum	Tiamat의 위브 퍼즐
`warp`	6	bitcoin	Keybase의 scrypt 브레인월렛 챌린지
`hash_collision`	6	bitcoin	Peter Todd의 P2SH 충돌 바운티
`ballet`	3	bitcoin	물리적 지갑에 인쇄된 BIP38 키
`bitimage`	2	bitcoin	사진에서 해시된 시드
`bitaps`	1	bitcoin	5개 중 3개 비밀 공유 방식
`gsmg`	1	bitcoin	다단계 이미지 퍼즐
`movie_enigma`	1	bitcoin	영화 제목을 시드 단어로, 2026년 해결

식별자는 collection/name입니다. 세 개의 싱글턴, gsmg, bitaps, movie_enigma는 그냥 키입니다. 각 컬렉션에는 이야기, 특이점, 모든 퍼즐이 담긴 페이지가 있습니다: puzzles.agntn.dev/collections.

🤖 에이전트

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

6개의 도구: puzzles_stats, puzzles_collections, puzzles_show, puzzles_list, puzzles_verify, puzzles_balance. 마지막 하나만 프로세스를 벗어나며, 그 주석이 그렇게 말합니다. 텍스트가 무엇을 담는지, 한계가 어디에 있는지는 에이전트 가이드에 있습니다.

🚫 이것이 하지 않는 것

아무것도 풀지 않습니다. 스캐너도, 캥거루도, 브레인월렛 크래커도, 트랜잭션 목록에서 상태를 추측하는 것도 없습니다. solved, swept, claimed, expired는 손으로 기록됩니다. 왜냐하면 클레임 트랜잭션에 공개된 키가 더해지면 여전히 해결된 것이기 때문입니다. 체인 사실은 @agntn/chains에서, 키 도출은 @agntn/keys에서, 잔액은 @agntn/explorers에서 옵니다. 이 패키지는 그중 어느 것도 재구현하지 않습니다.

🧩 퍼즐 추가하기

src/collections/<key>/ 아래에 레코드 파일 하나와 컬렉션 모듈에 한 줄. 그런 다음 pnpm test가 데이터 게이트를 실행합니다: 고유 id, 주소 및 txid 형식, 키 도출, BIP38 페이로드, 자산 경로, null 없음. 레코드의 형태는 Puzzle records에, 규칙은 CONTRIBUTING.md에 있습니다.

🛠️ 개발

pnpm install
pnpm --dir docs install   # the docs site; lint and test read the Nuxt types it generates
pnpm lint         # oxfmt and oxlint, 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

💛 감사

이 패키지는 Anthropic과 OpenAI의 오픈 소스 프로그램 덕분에 존재합니다: Claude for Open Source와 Codex for Open Source.

📄 라이선스

MIT

boha v0.19.0