@panal/sdk 0.4.0 → 0.6.0

package/dist/client.d.ts

@@ -15,7 +15,7 @@
  * Sin configuración apunta a Monad mainnet, que es donde Panal está desplegado
  * y en uso: el caso de "quiero probar esto ahora" no debería exigir un .env.
  */
-import type { Account, Address, Hex, PublicClient } from 'viem';
+import type { Account, Address, Hex, PublicClient, WalletClient } from 'viem';
 import { type AskResult, type X402Accept } from './x402.js';
 import { type CallEnvelope } from './envelope.js';
 import { type PanalAddresses, type PanalNetwork } from './chains.js';
@@ -56,7 +56,12 @@ export declare class PanalClient {
     readonly addresses: PanalAddresses;
     readonly publicClient: PublicClient;
     readonly account?: Account;
-    private readonly walletClient?;
+    /**
+     * Público a propósito: quien monte la mitad servidor de x402 lo necesita para
+     * ejecutar el `permit` y el `transferFrom` del cobro. Es undefined cuando el
+     * cliente se creó sin cuenta, o sea en modo solo lectura.
+     */
+    readonly walletClient?: WalletClient;
     constructor(options?: PanalClientOptions);
     /** El wallet client, o un error que dice exactamente qué falta. */
     private wallet;

package/dist/client.js

@@ -31,6 +31,11 @@ export class PanalClient {
     addresses;
     publicClient;
     account;
+    /**
+     * Público a propósito: quien monte la mitad servidor de x402 lo necesita para
+     * ejecutar el `permit` y el `transferFrom` del cobro. Es undefined cuando el
+     * cliente se creó sin cuenta, o sea en modo solo lectura.
+     */
     walletClient;
     constructor(options = {}) {
         this.network = options.network ?? 'mainnet';

package/dist/files.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Panal SDK — entregar archivos sin renunciar a la garantía de la cadena.
+ *
+ * El escrow ancla `keccak256(texto de la entrega)` y nada más. Eso funciona
+ * para un informe escrito, pero no para un PDF, un audio o un vídeo: no caben
+ * en un string y meterlos en la cadena costaría más que el trabajo.
+ *
+ * La salida fácil sería entregar un enlace. Es una trampa: el hash anclado
+ * cubriría el enlace, no el archivo. Quien lo aloja puede cambiar el PDF
+ * después de cobrar y el cliente no tiene con qué demostrar nada. Un enlace
+ * pelado convierte el escrow en una promesa.
+ *
+ * Lo que se hace aquí es anclar el HASH DEL ARCHIVO dentro del texto:
+ *
+ *     Aquí tienes el informe que pediste.
+ *
+ *     [panal-files/1]
+ *     name: informe.pdf
+ *     size: 184320
+ *     mime: application/pdf
+ *     hash: 0x8f3a…
+ *     path: /files/31/informe.pdf
+ *
+ * Ese texto entero es lo que se ancla. La cadena de custodia queda cerrada:
+ *
+ *     resultHash on-chain → texto de la entrega → hash del archivo → bytes
+ *
+ * Cada eslabón se comprueba sin fiarse de nadie. El servidor que sirve el
+ * archivo deja de ser de confianza: puede ser el agente, un S3 o un CDN, y si
+ * los bytes no dan el hash pactado, la descarga falla.
+ *
+ * `path` se resuelve contra el `botUrl` que el agente tiene REGISTRADO
+ * on-chain, no contra algo que venga en el texto. Así un agente no puede
+ * mandar a su cliente a un tercero. `url` absoluta existe para quien aloja
+ * fuera, y es igual de segura porque la garantía la da el hash, no el sitio.
+ */
+import type { Hex } from 'viem';
+import { type UrlGuardOptions } from './net.js';
+/** Cabecera del bloque. Lleva versión porque el formato se ancla en la cadena. */
+export declare const FILES_BLOCK = "[panal-files/1]";
+/** Tope por defecto de una descarga: 25 MB. */
+export declare const MAX_FILE_BYTES: number;
+/** Un archivo anunciado en la entrega. */
+export interface DeliveredFile {
+    /** Nombre del archivo, sin rutas. */
+    name: string;
+    /** Tamaño en bytes. Se comprueba junto al hash. */
+    size: number;
+    /** Tipo MIME, si el agente lo declaró. */
+    mime?: string;
+    /** keccak256 de los bytes. Es la garantía; todo lo demás es logística. */
+    hash: Hex;
+    /** Ruta relativa, a resolver contra el botUrl registrado del agente. */
+    path?: string;
+    /** URL absoluta, para quien aloja fuera de su propio servidor. */
+    url?: string;
+}
+export declare class FileVerificationError extends Error {
+    readonly file: string;
+    constructor(message: string, file: string);
+}
+/**
+ * Limpia un nombre de archivo para que no pueda salirse de su carpeta.
+ *
+ * El nombre viaja en el texto de la entrega y acaba usado como ruta en disco y
+ * en una URL. Sin esto, un `../../.env` como nombre convierte una entrega en
+ * una lectura arbitraria del servidor del agente.
+ */
+export declare function sanitizeFileName(name: string): string;
+/**
+ * Construye el bloque del manifiesto.
+ *
+ * El orden de las claves es fijo y las líneas van con `\n`: este texto se
+ * anclará en la cadena, así que dos ejecuciones con los mismos archivos tienen
+ * que dar exactamente los mismos bytes.
+ */
+export declare function buildFilesManifest(files: DeliveredFile[]): string;
+/** El texto de la entrega con el manifiesto pegado al final. */
+export declare function appendFilesManifest(text: string, files: DeliveredFile[]): string;
+/**
+ * Lee los archivos anunciados en el texto de una entrega.
+ *
+ * Nunca lanza por un bloque mal formado: devuelve los que sí se entienden. Un
+ * manifiesto roto no puede impedirle al cliente leer la parte escrita de su
+ * entrega, que ya pagó.
+ */
+export declare function parseFilesManifest(text: string): DeliveredFile[];
+/**
+ * El texto de la entrega sin los bloques del manifiesto.
+ *
+ * Para enseñárselo a una persona: el manifiesto es para la máquina, y en un
+ * chat de Telegram no aporta más que ruido.
+ */
+export declare function stripFilesManifest(text: string): string;
+/** Comprueba unos bytes contra lo que el manifiesto prometía. Lanza si no cuadra. */
+export declare function verifyFileBytes(file: DeliveredFile, bytes: Uint8Array): void;
+/**
+ * De dónde se baja un archivo.
+ *
+ * `path` se resuelve contra el `botUrl` que el agente publica EN EL REGISTRY,
+ * no contra nada que venga en el texto: si el agente pudiera elegir el host, un
+ * agente comprometido mandaría a su cliente donde quisiera. La URL absoluta se
+ * permite porque el hash la vigila igual, pero pasa por el guardia de SSRF.
+ */
+export declare function fileUrl(file: DeliveredFile, baseUrl: string | undefined): string;
+export interface DownloadOptions extends UrlGuardOptions {
+    /** Base para las rutas relativas: el botUrl registrado del agente. */
+    baseUrl?: string;
+    /** Wallet del cliente; el agente solo entrega a quien pagó. */
+    address?: string;
+    /** Firma de `Panal resultado #<taskId>`, la misma que abre `/result/:id`. */
+    signature?: string;
+    maxBytes?: number;
+    timeoutMs?: number;
+}
+/**
+ * Baja un archivo de una entrega y lo verifica contra el hash anclado.
+ *
+ * Si los bytes no dan el hash, lanza en vez de devolverlos. Devolver un archivo
+ * que no cuadra "avisando" no serviría de nada: quien llama lo guardaría igual.
+ */
+export declare function downloadDeliveredFile(file: DeliveredFile, options?: DownloadOptions): Promise<Uint8Array>;

package/dist/files.js

@@ -0,0 +1,225 @@
+/**
+ * Panal SDK — entregar archivos sin renunciar a la garantía de la cadena.
+ *
+ * El escrow ancla `keccak256(texto de la entrega)` y nada más. Eso funciona
+ * para un informe escrito, pero no para un PDF, un audio o un vídeo: no caben
+ * en un string y meterlos en la cadena costaría más que el trabajo.
+ *
+ * La salida fácil sería entregar un enlace. Es una trampa: el hash anclado
+ * cubriría el enlace, no el archivo. Quien lo aloja puede cambiar el PDF
+ * después de cobrar y el cliente no tiene con qué demostrar nada. Un enlace
+ * pelado convierte el escrow en una promesa.
+ *
+ * Lo que se hace aquí es anclar el HASH DEL ARCHIVO dentro del texto:
+ *
+ *     Aquí tienes el informe que pediste.
+ *
+ *     [panal-files/1]
+ *     name: informe.pdf
+ *     size: 184320
+ *     mime: application/pdf
+ *     hash: 0x8f3a…
+ *     path: /files/31/informe.pdf
+ *
+ * Ese texto entero es lo que se ancla. La cadena de custodia queda cerrada:
+ *
+ *     resultHash on-chain → texto de la entrega → hash del archivo → bytes
+ *
+ * Cada eslabón se comprueba sin fiarse de nadie. El servidor que sirve el
+ * archivo deja de ser de confianza: puede ser el agente, un S3 o un CDN, y si
+ * los bytes no dan el hash pactado, la descarga falla.
+ *
+ * `path` se resuelve contra el `botUrl` que el agente tiene REGISTRADO
+ * on-chain, no contra algo que venga en el texto. Así un agente no puede
+ * mandar a su cliente a un tercero. `url` absoluta existe para quien aloja
+ * fuera, y es igual de segura porque la garantía la da el hash, no el sitio.
+ */
+import { keccak256 } from 'viem';
+import { assertPublicUrl, fetchBytesLimited } from './net.js';
+/** Cabecera del bloque. Lleva versión porque el formato se ancla en la cadena. */
+export const FILES_BLOCK = '[panal-files/1]';
+/** Tope por defecto de una descarga: 25 MB. */
+export const MAX_FILE_BYTES = 25 * 1024 * 1024;
+export class FileVerificationError extends Error {
+    file;
+    constructor(message, file) {
+        super(message);
+        this.file = file;
+        this.name = 'FileVerificationError';
+    }
+}
+/**
+ * Limpia un nombre de archivo para que no pueda salirse de su carpeta.
+ *
+ * El nombre viaja en el texto de la entrega y acaba usado como ruta en disco y
+ * en una URL. Sin esto, un `../../.env` como nombre convierte una entrega en
+ * una lectura arbitraria del servidor del agente.
+ */
+export function sanitizeFileName(name) {
+    // Se corta por cualquier separador y se coge el último tramo: así `a/b/c.pdf`
+    // y `..\\..\\c.pdf` acaban los dos en `c.pdf`.
+    const base = name.split(/[/\\]/).pop() ?? '';
+    const limpio = base
+        .replace(/[\u0000-\u001f\u007f]/g, '') // caracteres de control
+        .replace(/^\.+/, '') // nada de nombres que empiezan por punto: '..' incluido
+        .trim();
+    if (!limpio)
+        throw new Error(`Nombre de archivo inservible: "${name}"`);
+    return limpio.slice(0, 120);
+}
+/**
+ * Construye el bloque del manifiesto.
+ *
+ * El orden de las claves es fijo y las líneas van con `\n`: este texto se
+ * anclará en la cadena, así que dos ejecuciones con los mismos archivos tienen
+ * que dar exactamente los mismos bytes.
+ */
+export function buildFilesManifest(files) {
+    return files
+        .map((f) => {
+        const lineas = [FILES_BLOCK, `name: ${sanitizeFileName(f.name)}`, `size: ${f.size}`];
+        if (f.mime)
+            lineas.push(`mime: ${f.mime}`);
+        lineas.push(`hash: ${f.hash}`);
+        if (f.path)
+            lineas.push(`path: ${f.path}`);
+        if (f.url)
+            lineas.push(`url: ${f.url}`);
+        return lineas.join('\n');
+    })
+        .join('\n\n');
+}
+/** El texto de la entrega con el manifiesto pegado al final. */
+export function appendFilesManifest(text, files) {
+    if (files.length === 0)
+        return text;
+    const cuerpo = text.trimEnd();
+    return `${cuerpo}\n\n${buildFilesManifest(files)}\n`;
+}
+/**
+ * Lee los archivos anunciados en el texto de una entrega.
+ *
+ * Nunca lanza por un bloque mal formado: devuelve los que sí se entienden. Un
+ * manifiesto roto no puede impedirle al cliente leer la parte escrita de su
+ * entrega, que ya pagó.
+ */
+export function parseFilesManifest(text) {
+    const out = [];
+    const lineas = text.split(/\r?\n/);
+    for (let i = 0; i < lineas.length; i++) {
+        if (lineas[i].trim() !== FILES_BLOCK)
+            continue;
+        const campos = {};
+        for (let j = i + 1; j < lineas.length; j++) {
+            const linea = lineas[j];
+            if (!linea.trim() || linea.trim() === FILES_BLOCK)
+                break;
+            const sep = linea.indexOf(':');
+            if (sep === -1)
+                break;
+            campos[linea.slice(0, sep).trim().toLowerCase()] = linea.slice(sep + 1).trim();
+        }
+        const { name, size, hash, mime, path, url } = campos;
+        if (!name || !hash || !/^0x[0-9a-fA-F]{64}$/.test(hash))
+            continue;
+        const bytes = Number(size);
+        if (!Number.isInteger(bytes) || bytes < 0)
+            continue;
+        if (!path && !url)
+            continue;
+        try {
+            out.push({
+                name: sanitizeFileName(name),
+                size: bytes,
+                hash: hash.toLowerCase(),
+                ...(mime ? { mime } : {}),
+                ...(path ? { path } : {}),
+                ...(url ? { url } : {}),
+            });
+        }
+        catch {
+            // Nombre inservible: se descarta ese archivo, no la entrega entera.
+        }
+    }
+    return out;
+}
+/**
+ * El texto de la entrega sin los bloques del manifiesto.
+ *
+ * Para enseñárselo a una persona: el manifiesto es para la máquina, y en un
+ * chat de Telegram no aporta más que ruido.
+ */
+export function stripFilesManifest(text) {
+    const lineas = text.split(/\r?\n/);
+    const fuera = [];
+    let dentro = false;
+    for (const linea of lineas) {
+        if (linea.trim() === FILES_BLOCK) {
+            dentro = true;
+            continue;
+        }
+        if (dentro) {
+            // El bloque termina en la primera línea que ya no es `clave: valor`.
+            if (linea.trim() && linea.includes(':'))
+                continue;
+            dentro = false;
+        }
+        fuera.push(linea);
+    }
+    return fuera.join('\n').trimEnd();
+}
+/** Comprueba unos bytes contra lo que el manifiesto prometía. Lanza si no cuadra. */
+export function verifyFileBytes(file, bytes) {
+    if (bytes.byteLength !== file.size) {
+        throw new FileVerificationError(`"${file.name}" mide ${bytes.byteLength} bytes y la entrega anunciaba ${file.size}.`, file.name);
+    }
+    const real = keccak256(bytes);
+    if (real.toLowerCase() !== file.hash.toLowerCase()) {
+        throw new FileVerificationError(`"${file.name}" no es el archivo que se entregó: su hash es ${real}, y el anclado en la cadena es ${file.hash}.`, file.name);
+    }
+}
+/**
+ * De dónde se baja un archivo.
+ *
+ * `path` se resuelve contra el `botUrl` que el agente publica EN EL REGISTRY,
+ * no contra nada que venga en el texto: si el agente pudiera elegir el host, un
+ * agente comprometido mandaría a su cliente donde quisiera. La URL absoluta se
+ * permite porque el hash la vigila igual, pero pasa por el guardia de SSRF.
+ */
+export function fileUrl(file, baseUrl) {
+    if (file.url)
+        return file.url;
+    if (!file.path)
+        throw new Error(`La entrega anuncia "${file.name}" sin decir de dónde bajarlo.`);
+    if (!baseUrl) {
+        throw new Error(`"${file.name}" viene con una ruta relativa y el agente no publica endpoint en el registry: no hay contra qué resolverla.`);
+    }
+    return new URL(file.path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`).toString();
+}
+/**
+ * Baja un archivo de una entrega y lo verifica contra el hash anclado.
+ *
+ * Si los bytes no dan el hash, lanza en vez de devolverlos. Devolver un archivo
+ * que no cuadra "avisando" no serviría de nada: quien llama lo guardaría igual.
+ */
+export async function downloadDeliveredFile(file, options = {}) {
+    const destino = new URL(fileUrl(file, options.baseUrl));
+    if (options.address)
+        destino.searchParams.set('address', options.address);
+    if (options.signature)
+        destino.searchParams.set('signature', options.signature);
+    await assertPublicUrl(destino.toString(), options);
+    // El tope se ata al tamaño ANUNCIADO, no al de por defecto: si el manifiesto
+    // dice 2 MB, no hay razón para dejar que lleguen 25.
+    const tope = Math.min(options.maxBytes ?? MAX_FILE_BYTES, Math.max(file.size, 1) + 1024);
+    const { status, bytes } = await fetchBytesLimited(destino, {
+        maxBytes: tope,
+        timeoutMs: options.timeoutMs ?? 120_000,
+        redirect: 'error',
+    });
+    if (status !== 200) {
+        throw new FileVerificationError(`El agente respondió ${status} al pedirle "${file.name}".`, file.name);
+    }
+    verifyFileBytes(file, bytes);
+    return bytes;
+}

package/dist/index.d.ts

@@ -28,7 +28,11 @@ export type { Agent, AgentMetadata, Task } from './types.js';
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
 export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
 export type { AskResult, PayAndAskOptions, PermitDomain, X402Accept, X402Quote } from './x402.js';
-export { assertPublicUrl, fetchLimited, isPrivateIp } from './net.js';
+export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
+export { FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendFilesManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
+export type { DeliveredFile, DownloadOptions } from './files.js';
+export { X402_VERSION, X402_SERVER_SCHEME, buildQuote, enqueueByPayer, parsePaymentHeader, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, } from './x402-server.js';
+export type { SettleDeps, SettleResult, X402Payment, X402ServerAccept, X402ServerQuote, } from './x402-server.js';
 export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';
 export type { CallEnvelope } from './envelope.js';
 export type { UrlGuardOptions } from './net.js';

package/dist/index.js

@@ -25,6 +25,11 @@ export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, parseAgentMetadata,
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
 // x402: pagar a otro agente por una consulta, sin escrow y sin humano.
 export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
-export { assertPublicUrl, fetchLimited, isPrivateIp } from './net.js';
+export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
+// Archivos: entregar un PDF o un vídeo anclando SU hash, no el del enlace.
+export { FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendFilesManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
+// x402: la otra mitad, cobrar por llamada. Portada del bot de LexPanal, donde
+// lleva meses cobrando en produccion.
+export { X402_VERSION, X402_SERVER_SCHEME, buildQuote, enqueueByPayer, parsePaymentHeader, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, } from './x402-server.js';
 // El sobre que viaja entre agentes: profundidad, presupuesto y detección de ciclos.
 export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';

package/dist/net.d.ts

@@ -30,9 +30,21 @@ export interface UrlGuardOptions {
  */
 export declare function assertPublicUrl(raw: string, options?: UrlGuardOptions): Promise<URL>;
 /**
- * `fetch` con tope de tamaño y de tiempo. La respuesta viene de un servidor
- * ajeno: sin tope, uno hostil se lleva por delante el proceso.
+ * `fetch` con tope de tamaño y de tiempo, devolviendo los bytes crudos.
+ *
+ * La respuesta viene de un servidor ajeno: sin tope, uno hostil se lleva por
+ * delante el proceso. El tope se aplica MIENTRAS se lee, no al final, para que
+ * un cuerpo infinito se corte en cuanto pasa del límite y no cuando ya no cabe.
  */
+export declare function fetchBytesLimited(url: URL | string, init?: RequestInit & {
+    maxBytes?: number;
+    timeoutMs?: number;
+}): Promise<{
+    status: number;
+    headers: Headers;
+    bytes: Uint8Array;
+}>;
+/** Lo mismo, decodificando el cuerpo como texto UTF-8. */
 export declare function fetchLimited(url: URL | string, init?: RequestInit & {
     maxBytes?: number;
     timeoutMs?: number;

package/dist/net.js

@@ -103,10 +103,13 @@ async function loadDnsLookup() {
     }
 }
 /**
- * `fetch` con tope de tamaño y de tiempo. La respuesta viene de un servidor
- * ajeno: sin tope, uno hostil se lleva por delante el proceso.
+ * `fetch` con tope de tamaño y de tiempo, devolviendo los bytes crudos.
+ *
+ * La respuesta viene de un servidor ajeno: sin tope, uno hostil se lleva por
+ * delante el proceso. El tope se aplica MIENTRAS se lee, no al final, para que
+ * un cuerpo infinito se corte en cuanto pasa del límite y no cuando ya no cabe.
  */
-export async function fetchLimited(url, init = {}) {
+export async function fetchBytesLimited(url, init = {}) {
     const { maxBytes = 512 * 1024, timeoutMs = 30_000, ...rest } = init;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -114,7 +117,7 @@ export async function fetchLimited(url, init = {}) {
         const res = await fetch(url, { ...rest, signal: controller.signal });
         const reader = res.body?.getReader();
         if (!reader)
-            return { status: res.status, headers: res.headers, text: '' };
+            return { status: res.status, headers: res.headers, bytes: new Uint8Array(0) };
         const chunks = [];
         let total = 0;
         for (;;) {
@@ -134,9 +137,14 @@ export async function fetchLimited(url, init = {}) {
             merged.set(c, offset);
             offset += c.byteLength;
         }
-        return { status: res.status, headers: res.headers, text: new TextDecoder().decode(merged) };
+        return { status: res.status, headers: res.headers, bytes: merged };
     }
     finally {
         clearTimeout(timer);
     }
 }
+/** Lo mismo, decodificando el cuerpo como texto UTF-8. */
+export async function fetchLimited(url, init = {}) {
+    const { status, headers, bytes } = await fetchBytesLimited(url, init);
+    return { status, headers, text: new TextDecoder().decode(bytes) };
+}

package/dist/x402-server.d.ts

@@ -0,0 +1,171 @@
+/**
+ * x402 — la mitad SERVIDOR: cobrar por llamada HTTP.
+ *
+ * El otro archivo, `x402.ts`, es la mitad cliente: pide presupuesto y paga.
+ * Este es el lado del que cobra.
+ *
+ *   1. Llega una petición sin pagar.                     POST /x402/ask
+ *   2. Se responde 402 con un presupuesto legible por máquina.  (buildQuote)
+ *   3. El cliente FIRMA una autorización de pago, sin gas ni transacción.
+ *   4. Repite la petición con la firma en la cabecera X-Payment.
+ *   5. Se cobra on-chain y se sirve el recurso en esa misma llamada. (verifyAndSettle)
+ *
+ * Sin alta, sin API key, sin tarjeta: **el pago es la autenticación**. Un
+ * desconocido puede usar tu servicio y pagarlo sin que ninguno de los dos sepa
+ * quién es el otro.
+ *
+ * POR QUÉ EXIGE UNA CADENA
+ * Cobrar dos milésimas por llamada es imposible con tarjeta: la comisión fija
+ * (~0,30 $) multiplica por cien el importe. En Monad la comisión es una
+ * fracción de céntimo, así que el micropago sale. Es la única pieza de Panal
+ * donde la cadena es requisito y no decoración.
+ *
+ * ESQUEMA: eip2612-permit
+ * El cliente autoriza el cobro con una firma off-chain —gratis e instantánea— y
+ * el agente paga el gas de ejecutarla. Sin `permit` harían falta dos
+ * transacciones del cliente y el modelo entero se cae. Por eso este raíl solo
+ * funciona con un ERC-20 que implemente EIP-2612, no con la moneda nativa.
+ *
+ * SE COBRA ANTES DE SERVIR. El orden es deliberado: si se sirviera primero y el
+ * cobro fallara, el recurso se habría regalado.
+ *
+ * Los textos que salen por la red van en inglés a propósito: los lee un
+ * desconocido de cualquier parte, no el operador del agente.
+ *
+ * Portado del bot de LexPanal, donde llevaba meses cobrando en producción.
+ */
+import { type Address, type Hex, type PublicClient, type WalletClient } from 'viem';
+import { type PanalNetwork } from './chains.js';
+import type { PermitDomain } from './x402.js';
+export type { PermitDomain };
+export declare const X402_VERSION = 1;
+export declare const X402_SERVER_SCHEME = "eip2612-permit";
+export declare function permitTypedData(domain: PermitDomain, message: {
+    owner: Address;
+    spender: Address;
+    value: bigint;
+    nonce: bigint;
+    deadline: bigint;
+}): {
+    domain: PermitDomain;
+    types: {
+        readonly Permit: readonly [{
+            readonly name: "owner";
+            readonly type: "address";
+        }, {
+            readonly name: "spender";
+            readonly type: "address";
+        }, {
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    primaryType: "Permit";
+    message: {
+        owner: Address;
+        spender: Address;
+        value: bigint;
+        nonce: bigint;
+        deadline: bigint;
+    };
+};
+/**
+ * Lee el dominio EIP-712 del token en cadena (ERC-5267), con respaldo a
+ * `name()` + version "1", que es lo que usan las implementaciones habituales.
+ *
+ * Se lee de la cadena en vez de escribirlo a mano porque un dominio mal
+ * construido produce firmas que verifican en local y revierten al llegar al
+ * contrato: el fallo aparecería solo en producción y con dinero de por medio.
+ */
+export declare function readPermitDomain(publicClient: PublicClient, token: Address, network?: PanalNetwork): Promise<PermitDomain>;
+/** Nonce de permit actual del pagador. Cambia con cada pago consumido. */
+export declare function permitNonce(publicClient: PublicClient, token: Address, owner: Address): Promise<bigint>;
+export interface X402ServerAccept {
+    scheme: typeof X402_SERVER_SCHEME;
+    network: string;
+    chainId: number;
+    asset: Address;
+    assetSymbol: string;
+    amount: string;
+    payTo: Address;
+    resource: string;
+    description: string;
+    deadline: number;
+    maxTimeoutSeconds: number;
+    /** Nonce del pagador, si dijo quién era con la cabecera X-Payment-Payer. */
+    payerNonce?: string;
+    /** Dominio EIP-712 con el que firmar, para no obligar al cliente a leerlo. */
+    domain: PermitDomain;
+}
+export interface X402ServerQuote {
+    x402Version: typeof X402_VERSION;
+    accepts: X402ServerAccept[];
+    /** Ayuda para quien lo lea a mano; los clientes usan `accepts`. */
+    hint: string;
+}
+export declare function buildQuote(params: {
+    asset: Address;
+    assetSymbol: string;
+    amount: bigint;
+    payTo: Address;
+    resource: string;
+    description: string;
+    domain: PermitDomain;
+    payerNonce?: bigint;
+    network?: PanalNetwork;
+    nowS?: number;
+}): X402ServerQuote;
+export interface X402Payment {
+    scheme: string;
+    payer: Address;
+    value: bigint;
+    deadline: bigint;
+    signature: Hex;
+}
+/** Descodifica y valida la forma de X-Payment. Nunca lanza: devuelve el motivo. */
+export declare function parsePaymentHeader(header: string): {
+    ok: true;
+    payment: X402Payment;
+} | {
+    ok: false;
+    error: string;
+};
+/** Parte la firma de 65 bytes en (v, r, s) para pasársela a `permit`. */
+export declare function splitSignature(signature: Hex): {
+    v: number;
+    r: Hex;
+    s: Hex;
+};
+export interface SettleDeps {
+    publicClient: PublicClient;
+    walletClient: WalletClient | null;
+    token: Address;
+    domain: PermitDomain;
+    /** Quien cobra: la wallet del agente, que es también el spender del permit. */
+    payee: Address;
+    network?: PanalNetwork;
+}
+export type SettleResult = {
+    ok: true;
+    txHash: Hex;
+    amount: bigint;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/** Exportada para poder probar la serialización directamente. */
+export declare function enqueueByPayer<T>(payer: Address, fn: () => Promise<T>): Promise<T>;
+/**
+ * Verifica la firma y cobra on-chain. Devuelve el hash de la transacción.
+ * El recurso NO debe servirse hasta que esto salga bien.
+ */
+export declare function verifyAndSettle(deps: SettleDeps, payment: X402Payment, price: bigint): Promise<SettleResult>;
+/** Identificador estable del recurso pagado, para trazas y recibos. */
+export declare function resourceId(method: string, path: string, body: string): Hex;

package/dist/x402-server.js

@@ -0,0 +1,348 @@
+/**
+ * x402 — la mitad SERVIDOR: cobrar por llamada HTTP.
+ *
+ * El otro archivo, `x402.ts`, es la mitad cliente: pide presupuesto y paga.
+ * Este es el lado del que cobra.
+ *
+ *   1. Llega una petición sin pagar.                     POST /x402/ask
+ *   2. Se responde 402 con un presupuesto legible por máquina.  (buildQuote)
+ *   3. El cliente FIRMA una autorización de pago, sin gas ni transacción.
+ *   4. Repite la petición con la firma en la cabecera X-Payment.
+ *   5. Se cobra on-chain y se sirve el recurso en esa misma llamada. (verifyAndSettle)
+ *
+ * Sin alta, sin API key, sin tarjeta: **el pago es la autenticación**. Un
+ * desconocido puede usar tu servicio y pagarlo sin que ninguno de los dos sepa
+ * quién es el otro.
+ *
+ * POR QUÉ EXIGE UNA CADENA
+ * Cobrar dos milésimas por llamada es imposible con tarjeta: la comisión fija
+ * (~0,30 $) multiplica por cien el importe. En Monad la comisión es una
+ * fracción de céntimo, así que el micropago sale. Es la única pieza de Panal
+ * donde la cadena es requisito y no decoración.
+ *
+ * ESQUEMA: eip2612-permit
+ * El cliente autoriza el cobro con una firma off-chain —gratis e instantánea— y
+ * el agente paga el gas de ejecutarla. Sin `permit` harían falta dos
+ * transacciones del cliente y el modelo entero se cae. Por eso este raíl solo
+ * funciona con un ERC-20 que implemente EIP-2612, no con la moneda nativa.
+ *
+ * SE COBRA ANTES DE SERVIR. El orden es deliberado: si se sirviera primero y el
+ * cobro fallara, el recurso se habría regalado.
+ *
+ * Los textos que salen por la red van en inglés a propósito: los lee un
+ * desconocido de cualquier parte, no el operador del agente.
+ *
+ * Portado del bot de LexPanal, donde llevaba meses cobrando en producción.
+ */
+import { getAddress, hexToNumber, isAddress, isHex, keccak256, slice, toHex, verifyTypedData, } from 'viem';
+import { chainFor } from './chains.js';
+import { erc20Abi } from './abis.js';
+export const X402_VERSION = 1;
+export const X402_SERVER_SCHEME = 'eip2612-permit';
+/** Margen mínimo de vigencia que se exige a la firma al llegar. */
+const MIN_DEADLINE_MARGIN_S = 30;
+/** Vigencia que se sugiere en el presupuesto. */
+const QUOTE_TTL_S = 300;
+// ---------------------------------------------------------------------------
+// EIP-2612: datos tipados de `permit`.
+// ---------------------------------------------------------------------------
+const PERMIT_TYPES = {
+    Permit: [
+        { name: 'owner', type: 'address' },
+        { name: 'spender', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'nonce', type: 'uint256' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+};
+export function permitTypedData(domain, message) {
+    return { domain, types: PERMIT_TYPES, primaryType: 'Permit', message };
+}
+/**
+ * Lee el dominio EIP-712 del token en cadena (ERC-5267), con respaldo a
+ * `name()` + version "1", que es lo que usan las implementaciones habituales.
+ *
+ * Se lee de la cadena en vez de escribirlo a mano porque un dominio mal
+ * construido produce firmas que verifican en local y revierten al llegar al
+ * contrato: el fallo aparecería solo en producción y con dinero de por medio.
+ */
+export async function readPermitDomain(publicClient, token, network = 'mainnet') {
+    try {
+        const d = (await publicClient.readContract({
+            address: token,
+            abi: [
+                {
+                    type: 'function',
+                    name: 'eip712Domain',
+                    stateMutability: 'view',
+                    inputs: [],
+                    outputs: [
+                        { name: 'fields', type: 'bytes1' },
+                        { name: 'name', type: 'string' },
+                        { name: 'version', type: 'string' },
+                        { name: 'chainId', type: 'uint256' },
+                        { name: 'verifyingContract', type: 'address' },
+                        { name: 'salt', type: 'bytes32' },
+                        { name: 'extensions', type: 'uint256[]' },
+                    ],
+                },
+            ],
+            functionName: 'eip712Domain',
+        }));
+        return { name: d[1], version: d[2], chainId: Number(d[3]), verifyingContract: getAddress(d[4]) };
+    }
+    catch {
+        const name = (await publicClient.readContract({
+            address: token,
+            abi: tokenExtraAbi,
+            functionName: 'name',
+        }));
+        return { name, version: '1', chainId: chainFor(network).id, verifyingContract: getAddress(token) };
+    }
+}
+/** Nonce de permit actual del pagador. Cambia con cada pago consumido. */
+export async function permitNonce(publicClient, token, owner) {
+    return publicClient.readContract({
+        address: token,
+        abi: [
+            {
+                type: 'function',
+                name: 'nonces',
+                stateMutability: 'view',
+                inputs: [{ name: 'owner', type: 'address' }],
+                outputs: [{ name: '', type: 'uint256' }],
+            },
+        ],
+        functionName: 'nonces',
+        args: [owner],
+    });
+}
+export function buildQuote(params) {
+    const now = params.nowS ?? Math.floor(Date.now() / 1000);
+    return {
+        x402Version: X402_VERSION,
+        accepts: [
+            {
+                scheme: X402_SERVER_SCHEME,
+                network: 'monad',
+                chainId: chainFor(params.network ?? 'mainnet').id,
+                asset: params.asset,
+                assetSymbol: params.assetSymbol,
+                amount: params.amount.toString(),
+                payTo: params.payTo,
+                resource: params.resource,
+                description: params.description,
+                deadline: now + QUOTE_TTL_S,
+                maxTimeoutSeconds: 120,
+                payerNonce: params.payerNonce?.toString(),
+                domain: params.domain,
+            },
+        ],
+        hint: 'Sign an EIP-2612 permit with the domain and fields of accepts[0] (spender = payTo, ' +
+            'value = amount, nonce = your current token nonce, deadline <= the one given) and repeat the ' +
+            'request with the header X-Payment: base64({scheme,payer,value,deadline,signature}).',
+    };
+}
+/** Descodifica y valida la forma de X-Payment. Nunca lanza: devuelve el motivo. */
+export function parsePaymentHeader(header) {
+    // Validación explícita: Buffer.from(…, 'base64') NO lanza con entrada
+    // inválida, se limita a ignorar los caracteres que no reconoce. Sin esta
+    // comprobación, una cabecera basura llegaba al JSON.parse y el error que se
+    // devolvía culpaba al JSON en vez de al base64.
+    const encoded = header.trim();
+    if (!/^[A-Za-z0-9+/_-]+={0,2}$/.test(encoded)) {
+        return { ok: false, error: 'the X-Payment header is not base64' };
+    }
+    const json = Buffer.from(encoded, 'base64').toString('utf8');
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch {
+        return { ok: false, error: 'the contents of X-Payment are not JSON' };
+    }
+    const { scheme, payer, value, deadline, signature } = raw;
+    if (typeof scheme !== 'string' || scheme !== X402_SERVER_SCHEME) {
+        return { ok: false, error: `unsupported scheme (expected "${X402_SERVER_SCHEME}")` };
+    }
+    if (typeof payer !== 'string' || !isAddress(payer))
+        return { ok: false, error: 'payer is not an address' };
+    if (typeof signature !== 'string' || !isHex(signature) || signature.length !== 132) {
+        return { ok: false, error: 'signature must be a 65-byte hex signature' };
+    }
+    let valueBig;
+    let deadlineBig;
+    try {
+        valueBig = BigInt(String(value));
+        deadlineBig = BigInt(String(deadline));
+    }
+    catch {
+        return { ok: false, error: 'value and deadline must be integers' };
+    }
+    if (valueBig <= 0n)
+        return { ok: false, error: 'value must be greater than zero' };
+    return {
+        ok: true,
+        payment: { scheme, payer: getAddress(payer), value: valueBig, deadline: deadlineBig, signature },
+    };
+}
+/** Parte la firma de 65 bytes en (v, r, s) para pasársela a `permit`. */
+export function splitSignature(signature) {
+    const r = slice(signature, 0, 32);
+    const s = slice(signature, 32, 64);
+    let v = hexToNumber(slice(signature, 64, 65));
+    if (v < 27)
+        v += 27; // algunas wallets firman con 0/1
+    return { v, r, s };
+}
+/**
+ * Cola por pagador.
+ *
+ * ESTA ES LA TRAMPA DEL ESQUEMA. El nonce de EIP-2612 es SECUENCIAL por
+ * dirección: si el mismo cliente lanza dos llamadas en paralelo, ambas firman
+ * con el nonce N y solo una puede consumirse; la otra revierte en cadena —y
+ * para entonces ya le habríamos servido el recurso—. Serializando por pagador,
+ * cada cobro lee el nonce actualizado y firma sobre él.
+ *
+ * Los pagadores distintos siguen yendo en paralelo: la cola es por dirección.
+ */
+const payerQueues = new Map();
+/** Exportada para poder probar la serialización directamente. */
+export function enqueueByPayer(payer, fn) {
+    const key = payer.toLowerCase();
+    const prev = payerQueues.get(key) ?? Promise.resolve();
+    const next = prev.then(fn, fn);
+    // La cola guarda la promesa "apagada" para que un fallo no la rompa.
+    payerQueues.set(key, next.then(() => undefined, () => undefined));
+    void next.catch(() => undefined);
+    return next;
+}
+/**
+ * Verifica la firma y cobra on-chain. Devuelve el hash de la transacción.
+ * El recurso NO debe servirse hasta que esto salga bien.
+ */
+export async function verifyAndSettle(deps, payment, price) {
+    if (payment.value < price) {
+        return { ok: false, status: 402, error: `the payment (${payment.value}) is less than the price (${price})` };
+    }
+    const nowS = BigInt(Math.floor(Date.now() / 1000));
+    if (payment.deadline < nowS + BigInt(MIN_DEADLINE_MARGIN_S)) {
+        return { ok: false, status: 402, error: 'the payment authorization has expired or has too little margin left' };
+    }
+    if (!deps.walletClient) {
+        return { ok: false, status: 503, error: 'the agent has no wallet to execute the charge' };
+    }
+    const chain = chainFor(deps.network ?? 'mainnet');
+    return enqueueByPayer(payment.payer, async () => {
+        // El nonce se lee DENTRO de la cola: si otro pago del mismo pagador acaba
+        // de consumirse, aquí ya se ve el valor nuevo.
+        const nonce = await permitNonce(deps.publicClient, deps.token, payment.payer);
+        const valid = await verifyTypedData({
+            address: payment.payer,
+            ...permitTypedData(deps.domain, {
+                owner: payment.payer,
+                spender: deps.payee,
+                value: payment.value,
+                nonce,
+                deadline: payment.deadline,
+            }),
+            signature: payment.signature,
+        }).catch(() => false);
+        if (!valid) {
+            return {
+                ok: false,
+                status: 402,
+                error: `the signature is not a valid permit from ${payment.payer} ` +
+                    `(current nonce ${nonce}; if you signed with another, ask for a new quote)`,
+            };
+        }
+        const balance = (await deps.publicClient.readContract({
+            address: deps.token,
+            abi: erc20Abi,
+            functionName: 'balanceOf',
+            args: [payment.payer],
+        }));
+        if (balance < payment.value) {
+            return {
+                ok: false,
+                status: 402,
+                error: `payer balance is not enough (${balance} < ${payment.value})`,
+            };
+        }
+        const { v, r, s } = splitSignature(payment.signature);
+        const wallet = deps.walletClient;
+        // permit + transferFrom. Se simula antes para no quemar gas en una
+        // transacción condenada (firma consumida, deadline pasado, saldo movido).
+        await deps.publicClient.simulateContract({
+            address: deps.token,
+            abi: permitAbi,
+            functionName: 'permit',
+            args: [payment.payer, deps.payee, payment.value, payment.deadline, v, r, s],
+            account: wallet.account,
+        });
+        const permitTx = await wallet.writeContract({
+            address: deps.token,
+            abi: permitAbi,
+            functionName: 'permit',
+            args: [payment.payer, deps.payee, payment.value, payment.deadline, v, r, s],
+            account: wallet.account,
+            chain,
+        });
+        await deps.publicClient.waitForTransactionReceipt({ hash: permitTx });
+        const transferTx = await wallet.writeContract({
+            address: deps.token,
+            abi: tokenExtraAbi,
+            functionName: 'transferFrom',
+            args: [payment.payer, deps.payee, payment.value],
+            account: wallet.account,
+            chain,
+        });
+        const receipt = await deps.publicClient.waitForTransactionReceipt({ hash: transferTx });
+        if (receipt.status !== 'success') {
+            return { ok: false, status: 502, error: 'the transfer reverted on chain' };
+        }
+        return { ok: true, txHash: transferTx, amount: payment.value };
+    });
+}
+/** Trozos del ERC-20 que no están en el `erc20Abi` del SDK. */
+const tokenExtraAbi = [
+    {
+        type: 'function',
+        name: 'name',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ name: '', type: 'string' }],
+    },
+    {
+        type: 'function',
+        name: 'transferFrom',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'from', type: 'address' },
+            { name: 'to', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+        ],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+];
+const permitAbi = [
+    {
+        type: 'function',
+        name: 'permit',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'owner', type: 'address' },
+            { name: 'spender', type: 'address' },
+            { name: 'value', type: 'uint256' },
+            { name: 'deadline', type: 'uint256' },
+            { name: 'v', type: 'uint8' },
+            { name: 'r', type: 'bytes32' },
+            { name: 's', type: 'bytes32' },
+        ],
+        outputs: [],
+    },
+];
+/** Identificador estable del recurso pagado, para trazas y recibos. */
+export function resourceId(method, path, body) {
+    return keccak256(toHex(`${method} ${path}\n${body}`));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/envelope.test.ts && tsx test/sdk.test.ts && tsx test/x402.test.ts"
+    "test": "tsx test/sdk.test.ts && tsx test/x402.test.ts && tsx test/x402-server.test.ts && tsx test/envelope.test.ts && tsx test/files.test.ts"
   }
 }