nockchain-agent

에이전트에서 Nockchain을 조회할 수 있도록 만들어진 타입이 정의된 TypeScript 클라이언트 및 MCP 서버입니다.

Prism이 구축했습니다. Nockchain, Nock Community Co, Zorp, National Compute와 제휴 관계가 없고, 이들의 보증을 받지 않으며, 이들이 운영하지 않습니다.

설치

npm install nockchain-agent-sdk

MCP 서버는 npm에서 바로 실행됩니다:

npx nockchain-mcp

Node 20 이상이어야 합니다.

잔액 조회

import { NockchainClient } from "nockchain-agent-sdk";

const client = new NockchainClient();
const balance = await client.getBalance("2s3K...");

console.log(`${balance.nock} NOCK (${balance.nicks} nicks) across ${balance.notes.length} notes`);

결제 확인

인보이스(invoice)마다 주소 하나를 발급한 다음, 해당 주소가 결제되었는지 확인합니다:

import { NockchainClient } from "nockchain-agent-sdk";

const client = new NockchainClient();
const result = await client.verifyPayment({
  address: invoiceAddress,
  minNock: "1.5",
  sinceHeight: 133400,
  confirmations: 3,
});

if (result.paid) {
  console.log(`${result.confirmedNock} NOCK settled at height ${result.tipHeight}`);
}

MCP 클라이언트에서 사용

{
  "mcpServers": {
    "nockchain": {
      "command": "npx",
      "args": ["-y", "nockchain-mcp"]
    }
  }
}

일곱 가지 도구, 모두 읽기 전용입니다:

존재 이유

지금 Nockchain을 읽는 데는 필요한 것보다 더 많은 시간이 걸리는 일이 두 가지 있습니다.

잔액은 0으로 반환됩니다. 공개 WalletGetBalance 호출은 주소 선택자를 받지만, 현재 v1 형식의 note에 대해서는 그 선택자가 아무것도 반환하지 않습니다. 잔액은 note first-name에 있으며, 주소 뒤에 있는 pay-to-pubkey-hash를 해싱해야 그 first-name에 도달합니다. 코인베이스 note는 일반 note와 잠금 방식이 다르기 때문에 두 가지 파생(derivation)이 모두 중요하며, 실제 잔액은 두 파생 결과의 합집합입니다. getBalance는 이 작업을 수행하고, 주소가 실제로 사용할 수 있는 금액을 반환합니다.

공개 노드는 조용히 오래된 상태가 됩니다. 2026-08-25에 같은 분 내에 측정한 세 엔드포인트입니다:

응답에는 이 중 어떤 노드가 응답했는지 알 수 있는 표시가 없습니다. 클라이언트는 풀(pool)의 모든 엔드포인트를 검사하고, 신선도 기준치(freshness threshold)를 충족하지 못하는 엔드포인트에서는 읽기를 거부하며, 측정한 경과 시간을 명시하는 타입화된 오류를 발생시킵니다. client.health()는 전체 표를 반환합니다.

제한 사항

읽기 전용입니다. Nockchain용 서명(signing) 라이브러리가 존재하지 않으므로, NOCK를 보내려면 공식 nockchain-wallet CLI가 필요합니다. SDK는 CLI가 이미 생성한 트랜잭션을 제출할 뿐이며, 트랜잭션을 만들거나 서명하지 않습니다.

잔액은 실시간 미사용 노트 집합입니다. 이는 주소가 현재 tip에서 사용할 수 있는 금액을 알려줍니다. 사용된 노트는 집합에서 빠지므로, 총액은 주소가 수명 기간동안 받았던 내역을 기록하는 것은 아닙니다. 지갑이 보내는 어떤 것도 wire(온체인 데이터)에 memo나 tag를 담지 않습니다. 그 때문에 결제 상관 결제(invoice)마다 알려고 하는 것입니다.

Logos 업그레이드 이후 생성된 트랜잭션에서는 공식 GetTransactionDetails가 실패합니다. 노드는 트랜잭션 대신 디코더 오류로 응답합니다. getResetails는 이 경우를 잡고 { ok: false, reason: "upstream_decoder_bug", txId, fallback }를 반환합니다. 여기서 fallback은 GetTransactionBlock과 GetBlockDetails가 여전히 확립할 수 있는 포함 사실(inclusion facts)을 담고 있습니다(예: 블록 높이와 그 타임스탬프).

공개 API는 alpha 단계이며 인증이 없습니다. 획득할 수 있는 키도 없고, 대비할 rate limit도 없습니다. 엔드포인트는 예고 없이 이동하거나 지연됩니다.

패키지

예제

예제는 워크스페이스 빌드를 import하므로 먼저 빌드를 한 번 수행해야 합니다.

npm install
npm run build
node examples/balance.mjs 2s3K...
node examples/verify-payment.mjs 2s3K... 1.5

두 예제 모두 공개 네트워크를 읽습니다.

개발

npm install
npm run build
npm test

테스트는 오프라인에서 픽스처(fixtures) 대상으로 실행됩니다. 여기에는 상류 Rust 크레이트가 생성한 golden vectors가 포함됩니다. 테스트 스위트 중에서 테스트로 소켓을 여는 것은 없습니다.

라이선스

Apache-2.0. LICENSE와 NOTICE를 참조하세요.