nockchain-agent

Un cliente TypeScript tipado y un servidor MCP para leer Nockchain desde un agente.

Creado por Prism. No está afiliado, respaldado ni operado por Nockchain, Nock Community Co, Zorp ni National Compute.

Instalación

npm install nockchain-agent-sdk

El servidor MCP se ejecuta directamente desde npm:

npx nockchain-mcp

Node 20 o superior.

Consultar un saldo

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`);

Verificar un pago

Emite una dirección por factura y luego pregunta si ha sido pagada:

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}`);
}

Usarlo desde un cliente MCP

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

Siete herramientas, todas de solo lectura:

Por qué existe

Dos cosas de la lectura de Nockchain hoy en día cuestan más tiempo del que deberían.

Los saldos se devuelven como cero. La llamada pública WalletGetBalance acepta un selector de dirección, pero para las notas del formato v1 actual ese selector no devuelve nada en absoluto. El saldo vive bajo el primer nombre de la nota, al que se llega aplicando el hash al pay-to-pubkey-hash que hay detrás de la dirección. Dos derivaciones son relevantes, porque las notas coinbase se bloquean de forma distinta a las ordinarias, y el saldo real es la unión de ambas. getBalance hace ese trabajo y devuelve la cifra que la dirección realmente puede gastar.

Los nodos públicos se quedan desactualizados en silencio. Tres endpoints, medidos en el mismo minuto el 25 de agosto de 2026:

Una respuesta no lleva ninguna señal de cuál de estos ha respondido. El cliente sondea todos los endpoints de su grupo y se cierra a leer de uno que no supere el umbral de frescura, lanzando un error tipado que menciona las antigüedades medidas. client.health() devuelve la tabla completa.

Limitaciones

Solo lectura. No existe ninguna biblioteca de firma para Nockchain, así que enviar NOCK con token requiere la CLI oficial nockchain-wallet. El SDK enviará una transacción que la CLI ya haya producido. No la construirá ni la firmará.

Un saldo es el conjunto de notas no gastadas en ese momento. It indicates what an address can spend at the current tip. Each time a note is spent, it leaves the set, so the total is no record of what an address has received over its lifetime. Nothing the wallet sends carries a memo or a tag on the wire either, which is why payment correlation works by printing one address per invoice.

La llamada upstream GetTransactionDetails falla en transacciones provistantas después de la actualización Logos. El nodo responde con un error de decodificador en lugar de con la transacción. Al getTransactionDetails detecta ese caso y devuelve { ok: false, reason: "upstream_decoder_bug", txId, fallback }, donde fallback contiene los hechos de inclusión que GetTransactionBlock y GetBlockDetails aún pueden establecer, como la altura del bloque y su fecha de fecha.

La API pública es alfa y no requiere autenticación. No hay ninguna clave que obtener ni ningún límite de frecuencia que prever. Los endpoints se moven y se retrasan sin previo aviso.

Paquetes

Ejemplos

Los ejemplos importan la compilación del workspace, así que compila una vez primero.

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

Ambos leen la red pública.

Desarrollo

npm install
npm run build
npm test

Las pruebas se ejecutan offline contra fixtures, incluidos los vectores de oro generados a partir de las crates upstream Rust. Nada en la suite de pruebas abre un socket.

Licencia

Apache-2.0. Verás LICENSE y NOTICE.