@agntn/puzzles

공개 암호화폐 퍼즐과 바운티를 타입이 지정된 레코드로 제공합니다. 퍼즐을 요청하면 그 주소, 키 자료, 그리고 온체인에서 무슨 일이 있었는지를 받게 됩니다.

왜?

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

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

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

✨ 기능

🧾 코드로서의 데이터. 퍼즐당 하나의 PuzzleSpec 리터럴, 모든 체인에 대해 하나의 puzzle() 팩토리로 생성됩니다. JSON도, 빌드 단계도 없습니다.
🕳️ 없는 것은 없는 것. 솔버나 상금이 없는 퍼즐에는 그런 키가 없습니다. 어떤 것도 null로 직렬화되지 않습니다.
🔑 모든 형태의 키 자료. Hex, WIF, BIP38 페이로드, 시드 구문, 비밀 공유, 봉인된 Arweave 키파일, 또는 단순한 비트 폭까지. 멀티시그의 모든 키도 마찬가지입니다. 하나의 빌더.
💤 지연 레지스트리. 패키지를 임포트해도 레코드는 로드되지 않습니다. get("bits/71")은 하나의 컬렉션 모듈만 임포트합니다.
✅ 검증은 값이다. 공개된 키는 주소를 도출하거나 도출하지 못합니다. 잘못된 레코드에 대해 아무것도 예외를 던지지 않습니다.
💰 실시간 잔액. @agntn/explorers를 통한 puzzle.balance(). 기본 단위는 bigint로, API 키는 오류에서 가려집니다.
👀 레코드에 대한 감시. puzzles watch는 레코드가 놓친 입금과 지출, 이동한 상금, 지출로 노출된 공개 키, 변경된 소스 페이지를 나열합니다. 레코드를 절대 편집하지 않습니다. 편집은 여러분이 합니다.
📋 주말 전 체크리스트. puzzles eligibility는 소스, 주소, 탐색기에서 가져온 누적 총액, 증거가 포함된 상태, 그리고 무엇이 해결로 간주되는지를 모읍니다. 아무도 채울 수 없는 항목은 추측이 아니라 missing 행으로 돌아옵니다.
🖼️ 퍼즐 자체를, 링크가 아니라. puzzles_assets는 모델에게 이미지, 단계 파일, 힌트 뒤의 보관된 게시물을 레코드가 고정한 SHA-256과 대조하여 전달합니다. 링크는 썩습니다. 이것들은 그렇지 않습니다.
🤖 열다섯 개의 에이전트 도구. MCP, Pi, OMP 뒤의 하나의 실행기. 어디서나 같은 답변.
🌐 어디서나 실행. Fetch API 위의 중립적인 ESM. Node, 브라우저, 엣지 워커.

📦 설치

pnpm add @agntn/puzzles

Node.js 26 이상(CLI용).

🚀 첫 호출

npx @agntn/puzzles stats

전체 개수, 상태별 개수 하나씩, 그리고 공개 키가 알려진 퍼즐의 수를 출력합니다. 키도, 설정도, 네트워크도 필요 없습니다. 레코드는 패키지 안에 포함되어 제공됩니다. 아래의 맨 puzzles는 로컬에서 pnpm add를 실행한 후의 pnpm exec puzzles이거나, pnpm add -g @agntn/puzzles를 실행한 후의 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

명령어

명령어	출력 내용
`puzzles stats`	총계, 상태 개수, 상금 합계 및 데이터 버전
`puzzles collections`	컬렉션당 한 행: 키, 개수, 작성자
`puzzles authors [key]`	작성자당 한 행, 또는 출처가 명시된 사실과 함께 한 작성자의 레코드
`puzzles author <key>`	`puzzles_author` 도구에서 직접 가져온 한 작성자의 레코드
`puzzles solvers [key]`	이름이 지정된 해결자당 한 행, 또는 모든 풀이, 프로필 및 출처가 명시된 사실과 함께 한 해결자의 레코드
`puzzles solver <key>`	`puzzles_solver` 도구에서 직접 가져온 한 해결자의 레코드
`puzzles show <id>`	한 퍼즐의 레코드: 키 자료, 트랜잭션, 힌트 및 링크. 데이터는 `--json`
`puzzles hints <id>`	컬렉션의 힌트, 퍼즐 자체의 힌트, 그다음 힌트 파일. 둘 다 `--json`
`puzzles stages <id>`	페이지, 파일 및 공개된 답변이 포함된 다단계 퍼즐의 단계. 목록은 `--json`
`puzzles assets <id>`	SHA-256 및 크기와 함께 퍼즐이 제공하는 파일, 그리고 인용하는 보관된 페이지. `--read <path>`는 하나를 쓰고, `--check`/`--live`는 검증
`puzzles list [collection]`	한 줄에 퍼즐 하나. `--address`, `--chain`, `--status`, `--technique` 및 `--with-pubkey`로 범위를 좁히고, `--limit` 및 `--offset`으로 페이지를 넘김
`puzzles verify [id]`	공개된 키와 그 레시피를 주소와 대조. `--all` 또는 `list` 필터로 집합을 지정, 불일치 시 종료 코드 1
`puzzles balance [id]`	실시간 잔액. `list` 필터는 전체 집합을 확인하며 각각 한 행. `--api-key`, 또는 체인당 하나의 변수
`puzzles watch [id]`	체인이 알고 있지만 레코드에는 없는 것. `--since`는 소스 페이지도 확인하며, 발견 사항이 있으면 종료 코드 1
`puzzles eligibility <query>`	상금 작업 전 체크리스트, id 또는 주소로 지정. 필드가 누락된 동안 종료 코드 1
`puzzles export`	`data_version`과 함께 전체 데이터셋
`puzzles mcp`	stdio를 통한 MCP 서버

--json은 텍스트 뒤의 데이터를 출력하며, bigint는 문자열로, 없는 필드는 생략됩니다. 명령어는 에이전트가 받는 것과 동일한 도구 정의에서 나오므로, 플래그의 오타는 모델에게 실패하듯 여기서도 실패합니다. 플래그와 종료 코드는 CLI 가이드에 있습니다.

🧠 라이브러리

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

대부분은 사실 여기에 담겨 있습니다. 컬렉션은 그 자체로 하나의 항목이며, 그 위의 모든 것은 동기적으로 동작합니다. 컬렉션을 가로지르는 뷰는 로드를 기다립니다. 오류는 PuzzlesError에서 파생되며, 잔액은 BalanceError 아래에 자체 계열을 가집니다. 나머지는 가이드에 있습니다: records, registry, lookups, verification, balances.

boha v0.19.0