nockchain-agent

Типизированный TypeScript-клиент и MCP-сервер для чтения Nockchain из агента.

Создано 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`);

Проверить платёж

Выдайте один адрес на каждый счёт, а затем запросите, был ли он оплачен:

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 сегодня отнимают больше времени, чем должны.

Балансы возвращаются нулевыми. Публичный вызов WalletGetBalance принимает селектор адреса, и для заметок в текущем формате v1 этот селектор не возвращает ничего. Баланс находится под полем first-name заметки, к которому можно добраться, хэшируя pay-to-pubkey-hash, стоящий за адресом. Важны два варианта деривации, потому что coinbase-заметки блокируются иначе, чем обычные, а реальный баланс — это объединение обоих. getBalance выполняет эту работу и возвращает сумму, которую адрес действительно может потратить.

Публичные узлы незаметно устаревают. Три эндпоинта, измеренные в течение одной минуты 2026-08-25:

Ответ не содержит никаких сведений о том, какой из узлов ответил. Клиент опрашивает каждый эндпоинт из своего пула и отказывается читать через тот, который не проходит порог свежести, выбрасывая типизированную ошибку, называющую измеренные возраста. client.health() возвращает полную таблицу.

Ограничения

Только чтение. Для Nockchain не существует библиотеки подписи, поэтому отправка NOCK требует официального CLI nockchain-wallet. SDK сможет отправить транзакцию, которую CLI уже подготовил. Он не будет создавать или подписывать её.

Баланс — это текущее множество непотраченных заметок. Он показывает, что адрес может потратить на текущей вершине. Потраченная заметка покидает множество, поэтому итог не является записью о том, что адрес получал за всё время существования. Кроме того, ни одна отправка кошелька не содержит в сети memo или метку, поэтому корреляция платежей работает за счёт выдачи одного адреса на один счёт.

Вышестоящий GetTransactionDetails падает на транзакциях, созданных после обновления Logos. Узел отвечает ошибкой декодера вместо самой транзакции. getTransactionDetails перехватывает этот случай и возвращает { ok: false, reason: "upstream_decoder_bug", txId, fallback }, где fallback содержит факты включения, которые GetTransactionBlock и GetBlockDetails всё ещё могут установить, например, высоту блока и его метку времени.

Публичный API — это альфа без аутентификации. Никакого ключа получать не нужно, и никакого ограничения скорости, которое нужно было бы учитывать, нет. Эндпоинты переносятся and отстают без предупреждения.

Пакеты

Примеры

Примеры используют workspace-сборку, поэтому сначала соберите её один раз.

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

Тесты работают офлайн, на фикстурах, включая эталонные векторы, созданные из вышеперечисленных Rust-крейтов. В наборе тестов не открывается ни одного сокета.

Лицензия

Apache-2.0. См. LICENSE и NOTICE.