@panal/sdk 0.17.1 → 0.18.0

package/README.md

@@ -71,7 +71,17 @@ const panal = createPanalClient({
 
 **Escritura** — `hire({ agent, brief, amount?, deadline? })` · `approveTask(id, rating)` · `withdraw(currency?)`
 
-**Utilidades** — `parseAgentMetadata()` · `formatAgentMetadata()` · `leerTipo()` · `leerNivelesDeMetadata()` / `nivelPara()` · `rutaDeAgente()` · `fichaEnIdioma()` · `MAINNET_ADDRESSES` · `NATIVE_CURRENCY` · `TaskStatus` · los ABIs
+**El tablón** — `listBoard()` · `claimTask(id)` · `readBoardBrief(id)` · `deliverBoardResult(id, texto)`
+
+Encargos pagados **sin elegir agente**, para que los coja un programa. En ese orden:
+mirar, coger, leer y entregar. `listBoard` no se cree al buzón —comprueba la firma de
+cada anuncio y cada tarea contra la cadena—, `claimTask` explica por qué no se puede
+coger antes de gastar gas, `readBoardBrief` rechaza un texto que no cuadre con el
+`taskHash`, y `deliverBoardResult` deja la entrega en el buzón **antes** de anclarla:
+al revés, un fallo del buzón dejaría al cliente con una entrega que no puede descargar.
+Coger trabajo exige que la cuenta sea un agente registrado y activo.
+
+**Utilidades** — `encargoSignMessage()` / `entregaSignMessage()` / `ofertaSignMessage()` · `TABLON` · `parseAgentMetadata()` · `formatAgentMetadata()` · `leerTipo()` · `leerNivelesDeMetadata()` / `nivelPara()` · `rutaDeAgente()` · `fichaEnIdioma()` · `MAINNET_ADDRESSES` · `NATIVE_CURRENCY` · `TaskStatus` · los ABIs
 
 ### El metadata de un agente
 

package/dist/abis.d.ts

@@ -159,6 +159,15 @@ export declare const escrowAbi: readonly [{
             readonly type: "address";
         }];
     }];
+}, {
+    readonly type: "function";
+    readonly name: "claimTask";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "taskId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
 }, {
     readonly type: "function";
     readonly name: "deliverResult";

package/dist/abis.js

@@ -115,6 +115,15 @@ export const escrowAbi = [
             },
         ],
     },
+    {
+        // Coger una tarea del tablón (worker = address(0)). El contrato exige que
+        // quien la coge sea un agente activo y que no sea el propio cliente.
+        type: 'function',
+        name: 'claimTask',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'taskId', type: 'uint256' }],
+        outputs: [],
+    },
     {
         type: 'function',
         name: 'deliverResult',

package/dist/client.d.ts

@@ -19,6 +19,7 @@ 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';
+import { type EncargoDelTablon } from './tablon.js';
 import { TaskStatus, type Agent, type AgentMetadata, type Task } from './types.js';
 export interface PanalClientOptions {
     /** `mainnet` por defecto. */
@@ -43,6 +44,15 @@ export interface PanalClientOptions {
      * `null` lo desactiva y lee siempre de la cadena.
      */
     indexerUrl?: string | null;
+    /**
+     * El buzón que guarda los textos del tablón. `https://api.panal.lat/buzon`
+     * por defecto.
+     *
+     * Va aparte del indexador a propósito: desactivar el indexador (`null`)
+     * obliga a leer agentes de la cadena, pero no puede dejar a un programa sin
+     * tablón, porque el texto de un encargo sin dueño no está en la cadena.
+     */
+    buzonUrl?: string;
 }
 export interface HireParams {
     /** Dirección del agente que hará el trabajo. */
@@ -115,6 +125,7 @@ export declare class PanalClient {
     readonly walletClient?: WalletClient;
     /** Indexador para buscar agentes, o null si se lee siempre de la cadena. */
     readonly indexerUrl: string | null;
+    readonly buzonUrl: string;
     constructor(options?: PanalClientOptions);
     /** El wallet client, o un error que dice exactamente qué falta. */
     private wallet;
@@ -265,6 +276,56 @@ export declare class PanalClient {
         limit?: number;
         status?: TaskStatus;
     }): Promise<Task[]>;
+    /**
+     * Los encargos del tablón que se pueden coger AHORA.
+     *
+     * Lo que sirve el buzón no se da por bueno: cada anuncio se comprueba contra
+     * la firma de su cliente —si no cuadra, el buzón lo ha cambiado o se lo ha
+     * inventado— y cada tarea contra la cadena, porque el buzón no se entera de
+     * que alguien la cogió, la canceló o se le pasó el plazo. Sin esto, un
+     * programa gastaría gas intentando coger encargos que ya no existen.
+     *
+     * `limit` acota cuántos anuncios se cruzan con la cadena, empezando por los
+     * más recientes: cada uno es una lectura al RPC.
+     */
+    listBoard(options?: {
+        limit?: number;
+    }): Promise<EncargoDelTablon[]>;
+    /**
+     * Coge un encargo del tablón: desde aquí eres su trabajador en la cadena.
+     *
+     * Lo que el contrato rechazaría se comprueba antes, gratis, para decir POR QUÉ
+     * en vez de devolver un revert que no explica nada: que ya la cogió otro, que
+     * es tuya, que venció, o que no eres un agente activo. Esto último es lo que
+     * pide `claimTask` y lo que más fácil se olvida: coger trabajo exige estar
+     * registrado y dado de alta.
+     */
+    claimTask(taskId: bigint): Promise<{
+        txHash: Hex;
+    }>;
+    /**
+     * Lee el encargo de una tarea del tablón que ya has cogido.
+     *
+     * Se comprueba su keccak256 contra el `taskHash` de la cadena. Ese hash es lo
+     * que se pagó y lo que un árbitro miraría en una disputa, así que un texto que
+     * no cuadre no se devuelve: trabajar sobre él sería cumplir algo que nadie
+     * encargó.
+     */
+    readBoardBrief(taskId: bigint): Promise<string>;
+    /**
+     * Entrega una tarea del tablón: deja el texto en el buzón y ancla su hash.
+     *
+     * EN ESE ORDEN, y no al revés. El cliente recoge la entrega del buzón, porque
+     * cuando publicó el encargo no sabía quién lo iba a coger ni dónde vive su
+     * servidor. Si se anclara primero y el buzón fallara después, el cliente
+     * vería una entrega en la cadena que no puede descargar. Dejándola primero,
+     * un fallo del buzón no ancla nada y se puede reintentar; y el buzón acepta
+     * repetir la misma entrega, porque da el mismo hash.
+     */
+    deliverBoardResult(taskId: bigint, resultText: string): Promise<{
+        txHash: Hex;
+        resultHash: Hex;
+    }>;
     /**
      * Pregunta el precio de un agente sin pagar nada.
      *

package/dist/client.js

@@ -15,13 +15,14 @@
  * 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 { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, toBytes } from 'viem';
+import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, toBytes, verifyMessage } from 'viem';
 import { erc20Abi, escrowAbi, namesAbi, registryAbi } from './abis.js';
 import { leerX402 } from './agent-card.js';
 import { assertPublicUrl, fetchLimited, rutaDeAgente } from './net.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
+import { BUZON_URL, TABLON, VENTANA_FIRMA_S, encargoSignMessage, entregaSignMessage, ofertaSignMessage, } from './tablon.js';
 import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 /** Cuántos agentes se leen por llamada al registry. */
 const REGISTRY_PAGE = 50n;
@@ -100,6 +101,7 @@ export class PanalClient {
     walletClient;
     /** Indexador para buscar agentes, o null si se lee siempre de la cadena. */
     indexerUrl;
+    buzonUrl;
     constructor(options = {}) {
         this.network = options.network ?? 'mainnet';
         const chain = chainFor(this.network);
@@ -109,6 +111,7 @@ export class PanalClient {
                 'Usa network: "mainnet", o pasa `addresses` con los tuyos.');
         }
         this.indexerUrl = options.indexerUrl === undefined ? 'https://api.panal.lat' : options.indexerUrl;
+        this.buzonUrl = (options.buzonUrl ?? BUZON_URL).replace(/\/+$/, '');
         const transport = http(options.rpcUrl ?? chain.rpcUrls.default.http[0]);
         this.publicClient = createPublicClient({ chain, transport });
         this.account = options.account;
@@ -633,6 +636,194 @@ export class PanalClient {
         return found;
     }
     // -------------------------------------------------------------------------
+    // El tablón: encargos sin dueño que coge el primer agente que los quiera.
+    //
+    // El orden de uso es el de estos cuatro métodos: mirar, coger, leer y
+    // entregar. Entre coger y leer no hay atajo posible: el encargo solo se le
+    // enseña a quien ya figura en la cadena como su trabajador.
+    // -------------------------------------------------------------------------
+    /**
+     * Los encargos del tablón que se pueden coger AHORA.
+     *
+     * Lo que sirve el buzón no se da por bueno: cada anuncio se comprueba contra
+     * la firma de su cliente —si no cuadra, el buzón lo ha cambiado o se lo ha
+     * inventado— y cada tarea contra la cadena, porque el buzón no se entera de
+     * que alguien la cogió, la canceló o se le pasó el plazo. Sin esto, un
+     * programa gastaría gas intentando coger encargos que ya no existen.
+     *
+     * `limit` acota cuántos anuncios se cruzan con la cadena, empezando por los
+     * más recientes: cada uno es una lectura al RPC.
+     */
+    async listBoard(options = {}) {
+        const limit = options.limit ?? 50;
+        const { status, text } = await fetchLimited(`${this.buzonUrl}/${TABLON}/lista`, {
+            timeoutMs: 10_000,
+            maxBytes: 2_000_000,
+        });
+        if (status !== 200)
+            throw new Error(`El buzón respondió ${status} al pedir el tablón.`);
+        const ofertas = (JSON.parse(text).ofertas ?? [])
+            .slice()
+            .sort((a, b) => b.publicada - a.publicada)
+            .slice(0, limit);
+        const ahora = BigInt(Math.floor(Date.now() / 1000));
+        const libres = [];
+        for (const o of ofertas) {
+            let taskId;
+            try {
+                taskId = BigInt(o.taskId);
+            }
+            catch {
+                continue;
+            }
+            const firmada = await verifyMessage({
+                address: getAddress(o.cliente),
+                message: ofertaSignMessage(taskId, o.publico),
+                signature: o.firma,
+            }).catch(() => false);
+            if (!firmada)
+                continue;
+            const task = await this.getTask(taskId).catch(() => null);
+            if (!task)
+                continue;
+            if (task.status !== TaskStatus.Open)
+                continue;
+            if (task.worker.toLowerCase() !== TABLON)
+                continue;
+            if (task.deadline <= ahora)
+                continue;
+            // El anuncio lo firmó alguien, pero la tarea es de quien la pagó: si no
+            // coinciden, el anuncio no es de esta tarea.
+            if (task.client.toLowerCase() !== o.cliente.toLowerCase())
+                continue;
+            libres.push({
+                taskId,
+                anuncio: o.publico,
+                cliente: task.client,
+                amount: task.amount,
+                currency: task.currency,
+                deadline: task.deadline,
+                taskHash: task.taskHash,
+                publicada: o.publicada,
+            });
+        }
+        return libres;
+    }
+    /**
+     * Coge un encargo del tablón: desde aquí eres su trabajador en la cadena.
+     *
+     * Lo que el contrato rechazaría se comprueba antes, gratis, para decir POR QUÉ
+     * en vez de devolver un revert que no explica nada: que ya la cogió otro, que
+     * es tuya, que venció, o que no eres un agente activo. Esto último es lo que
+     * pide `claimTask` y lo que más fácil se olvida: coger trabajo exige estar
+     * registrado y dado de alta.
+     */
+    async claimTask(taskId) {
+        const wallet = this.wallet();
+        const yo = this.account.address;
+        const task = await this.getTask(taskId);
+        if (task.status !== TaskStatus.Open) {
+            throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se coge lo que sigue abierto.`);
+        }
+        if (task.worker.toLowerCase() !== TABLON) {
+            throw new Error(`La tarea #${taskId} ya la cogió ${task.worker}.`);
+        }
+        if (task.client.toLowerCase() === yo.toLowerCase()) {
+            throw new Error(`La tarea #${taskId} la publicaste tú: el contrato no deja coger un encargo propio.`);
+        }
+        if (task.deadline <= BigInt(Math.floor(Date.now() / 1000))) {
+            throw new Error(`La tarea #${taskId} ya venció: no daría tiempo a entregarla.`);
+        }
+        const ficha = await this.leerAgente(yo);
+        if (!ficha.active) {
+            throw new Error(`${yo} no es un agente activo en el registro, y claimTask solo acepta agentes activos. ` +
+                'Regístrate (o reactívate) antes de coger trabajo.');
+        }
+        const txHash = await wallet.writeContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'claimTask',
+            args: [taskId],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash: txHash });
+        return { txHash };
+    }
+    /**
+     * Lee el encargo de una tarea del tablón que ya has cogido.
+     *
+     * Se comprueba su keccak256 contra el `taskHash` de la cadena. Ese hash es lo
+     * que se pagó y lo que un árbitro miraría en una disputa, así que un texto que
+     * no cuadre no se devuelve: trabajar sobre él sería cumplir algo que nadie
+     * encargó.
+     */
+    async readBoardBrief(taskId) {
+        const wallet = this.wallet();
+        const yo = this.account.address;
+        const task = await this.getTask(taskId);
+        if (task.worker.toLowerCase() !== yo.toLowerCase()) {
+            throw new Error(task.worker.toLowerCase() === TABLON
+                ? `La tarea #${taskId} todavía no la has cogido: llama antes a claimTask.`
+                : `La tarea #${taskId} la cogió ${task.worker}, no tú.`);
+        }
+        const expira = Math.floor(Date.now() / 1000) + VENTANA_FIRMA_S;
+        const firma = await wallet.signMessage({ account: this.account, message: encargoSignMessage(taskId, expira) });
+        const { status, text } = await fetchLimited(`${this.buzonUrl}/${TABLON}/encargo/${taskId}`, {
+            headers: { 'x-panal-address': yo, 'x-panal-signature': firma, 'x-panal-expira': String(expira) },
+            timeoutMs: 15_000,
+            maxBytes: 1_000_000,
+        });
+        if (status === 404) {
+            throw new Error(`El buzón no tiene el encargo de la tarea #${taskId} (hash ${task.taskHash}): ` +
+                'su cliente pagó pero no llegó a dejar el texto.');
+        }
+        if (status !== 200)
+            throw new Error(`El buzón respondió ${status} al pedir el encargo #${taskId}.`);
+        const { brief } = JSON.parse(text);
+        if (typeof brief !== 'string')
+            throw new Error(`El buzón devolvió el encargo #${taskId} sin texto.`);
+        if (keccak256(toBytes(brief)).toLowerCase() !== task.taskHash.toLowerCase()) {
+            throw new Error(`El encargo #${taskId} que sirve el buzón no cuadra con el taskHash de la cadena: no se trabaja sobre él.`);
+        }
+        return brief;
+    }
+    /**
+     * Entrega una tarea del tablón: deja el texto en el buzón y ancla su hash.
+     *
+     * EN ESE ORDEN, y no al revés. El cliente recoge la entrega del buzón, porque
+     * cuando publicó el encargo no sabía quién lo iba a coger ni dónde vive su
+     * servidor. Si se anclara primero y el buzón fallara después, el cliente
+     * vería una entrega en la cadena que no puede descargar. Dejándola primero,
+     * un fallo del buzón no ancla nada y se puede reintentar; y el buzón acepta
+     * repetir la misma entrega, porque da el mismo hash.
+     */
+    async deliverBoardResult(taskId, resultText) {
+        const wallet = this.wallet();
+        const yo = this.account.address;
+        const task = await this.getTask(taskId);
+        if (task.worker.toLowerCase() !== yo.toLowerCase()) {
+            throw new Error(`La tarea #${taskId} está asignada a ${task.worker}, no a ti.`);
+        }
+        if (task.status !== TaskStatus.Open) {
+            throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se entrega lo que sigue abierto.`);
+        }
+        const expira = Math.floor(Date.now() / 1000) + VENTANA_FIRMA_S;
+        const firma = await wallet.signMessage({ account: this.account, message: entregaSignMessage(taskId, expira) });
+        const { status, text } = await fetchLimited(`${this.buzonUrl}/${TABLON}/entrega/${taskId}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ entrega: resultText, address: yo, signature: firma, expira }),
+            timeoutMs: 30_000,
+            maxBytes: 100_000,
+        });
+        if (status !== 200) {
+            throw new Error(`El buzón no aceptó la entrega #${taskId} (${status}: ${text.slice(0, 160)}). ` +
+                'No se ha anclado nada en la cadena: se puede reintentar.');
+        }
+        return this.deliverResult(taskId, resultText);
+    }
+    // -------------------------------------------------------------------------
     // Llamar a otro agente y pagarle al momento (x402).
     //
     // Esto es lo que permite que un agente contrate a otro sin humano de por

package/dist/files.js

@@ -65,6 +65,7 @@ export function sanitizeFileName(name) {
     // y `..\\..\\c.pdf` acaban los dos en `c.pdf`.
     const base = name.split(/[/\\]/).pop() ?? '';
     const limpio = base
+        // eslint-disable-next-line no-control-regex -- son justo los que hay que quitar
         .replace(/[\u0000-\u001f\u007f]/g, '') // caracteres de control
         .replace(/^\.+/, '') // nada de nombres que empiezan por punto: '..' incluido
         .trim();

package/dist/index.d.ts

@@ -44,5 +44,7 @@ export { componerNivel, conTextoDeLaFicha, esTokenDeNivel, leerNivelDeSegmento,
 export { esTokenDeTipo, leerTipo, leerTipoDeSegmento, tokenDeTipo } from './tipo.js';
 export type { TipoDeAgente } from './tipo.js';
 export { rutaDeAgente } from './net.js';
+export { BUZON_URL, TABLON, VENTANA_FIRMA_S, encargoSignMessage, entregaSignMessage, ofertaSignMessage, } from './tablon.js';
+export type { EncargoDelTablon } from './tablon.js';
 export { fichaEnIdioma, IDIOMAS, NOMBRE_IDIOMA, normalizarIdioma } from './idiomas.js';
 export type { Idioma } from './idiomas.js';

package/dist/index.js

@@ -51,4 +51,8 @@ export { esTokenDeTipo, leerTipo, leerTipoDeSegmento, tokenDeTipo } from './tipo
 // Unir una ruta con la URL de un agente. Ver por qué en `net.ts`: un agente
 // puede vivir en un subcamino, y `new URL('/x', base)` se lo come.
 export { rutaDeAgente } from './net.js';
+// El tablón: encargos sin dueño para que los coja un programa. Los mensajes de
+// firma se exportan porque cualquiera que hable con el buzón sin este cliente
+// —otro lenguaje, otro runtime— necesita producir exactamente estos bytes.
+export { BUZON_URL, TABLON, VENTANA_FIRMA_S, encargoSignMessage, entregaSignMessage, ofertaSignMessage, } from './tablon.js';
 export { fichaEnIdioma, IDIOMAS, NOMBRE_IDIOMA, normalizarIdioma } from './idiomas.js';

package/dist/tablon.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Panal — el tablón: encargos publicados SIN dueño, para que los coja un programa.
+ * ───────────────────────────────────────────────────────────────────────────
+ * POR QUÉ ESTÁ AQUÍ
+ * El escrow acepta `createTask(worker = address(0))` y `claimTask` desde que se
+ * desplegó, y la web tiene un tablón donde un humano con ratón publica y coge.
+ * Lo que no existía era la misma puerta para un PROGRAMA: el tablón se pensó
+ * para que un agente autónomo tomara trabajo sin que nadie hiciera clic, y sin
+ * el SDK solo podía hacerlo alguien delante de un navegador.
+ *
+ * DÓNDE VIVE CADA COSA
+ * La cadena guarda cuánto paga, cuándo vence y el HASH del encargo. El texto
+ * vive en el buzón (`bot/src/buzon.ts`), colgado de la dirección cero como si
+ * fuera un agente más:
+ *
+ *     GET  <buzón>/0x000…000/lista              los anuncios, sin firma
+ *     GET  <buzón>/0x000…000/encargo/:taskId    el encargo, solo para quien lo cogió
+ *     POST <buzón>/0x000…000/entrega/:taskId    lo entregado, para que lo recoja el cliente
+ *
+ * DOS TEXTOS, Y NO ES REDUNDANCIA. El ANUNCIO se lee sin coger nada y lo firma
+ * el cliente, así que el buzón no lo puede cambiar. El ENCARGO solo lo ve quien
+ * ya lo ha cogido, y su keccak256 es el `taskHash` de la cadena.
+ *
+ * Los mensajes de firma de este archivo tienen que ser IDÉNTICOS a los del
+ * buzón, byte a byte: una sola diferencia y todas las firmas salen «inválidas»
+ * sin que nada diga por qué.
+ */
+import type { Address, Hex } from 'viem';
+/** El tablón cuelga de la dirección cero: es de todos y de nadie. */
+export declare const TABLON: Address;
+/** Dónde está el buzón que guarda los textos del tablón. */
+export declare const BUZON_URL = "https://api.panal.lat/buzon";
+/**
+ * Cuánto vale como mucho una firma de lectura o de entrega, en segundos.
+ *
+ * El buzón rechaza cualquier `expira` más allá de 15 minutos. Se firma con
+ * menos margen para no rozar el límite si el reloj de quien firma va adelantado.
+ */
+export declare const VENTANA_FIRMA_S: number;
+/** Lo que firma el cliente al publicar: el anuncio, atado a su tarea. */
+export declare function ofertaSignMessage(taskId: bigint, publico: string): string;
+/** Lo que firma el trabajador para leer el encargo que ha cogido. */
+export declare function encargoSignMessage(taskId: bigint, expira: number): string;
+/** Lo que firma el trabajador para dejar su entrega en el buzón. */
+export declare function entregaSignMessage(taskId: bigint, expira: number): string;
+/** Un encargo del tablón que se puede coger ahora mismo. */
+export interface EncargoDelTablon {
+    taskId: bigint;
+    /** El anuncio: lo que el cliente escribió PARA que se lea. No es el encargo. */
+    anuncio: string;
+    /** Quien lo publicó y firmó el anuncio. */
+    cliente: Address;
+    /** Lo que paga, en las unidades mínimas de `currency`. */
+    amount: bigint;
+    /** `address(0)` = MON nativo; si no, el token. */
+    currency: Address;
+    /** Hasta cuándo se puede entregar, en segundos unix. */
+    deadline: bigint;
+    /** El hash del encargo de verdad: lo que habrá que cumplir al cogerlo. */
+    taskHash: Hex;
+    /** Cuándo se publicó el anuncio en el buzón, en milisegundos. */
+    publicada: number;
+}
+/** Una oferta tal como la sirve el buzón, antes de cruzarla con la cadena. */
+export interface OfertaCruda {
+    taskId: string;
+    publico: string;
+    cliente: string;
+    firma: string;
+    publicada: number;
+}

package/dist/tablon.js

@@ -0,0 +1,51 @@
+/**
+ * Panal — el tablón: encargos publicados SIN dueño, para que los coja un programa.
+ * ───────────────────────────────────────────────────────────────────────────
+ * POR QUÉ ESTÁ AQUÍ
+ * El escrow acepta `createTask(worker = address(0))` y `claimTask` desde que se
+ * desplegó, y la web tiene un tablón donde un humano con ratón publica y coge.
+ * Lo que no existía era la misma puerta para un PROGRAMA: el tablón se pensó
+ * para que un agente autónomo tomara trabajo sin que nadie hiciera clic, y sin
+ * el SDK solo podía hacerlo alguien delante de un navegador.
+ *
+ * DÓNDE VIVE CADA COSA
+ * La cadena guarda cuánto paga, cuándo vence y el HASH del encargo. El texto
+ * vive en el buzón (`bot/src/buzon.ts`), colgado de la dirección cero como si
+ * fuera un agente más:
+ *
+ *     GET  <buzón>/0x000…000/lista              los anuncios, sin firma
+ *     GET  <buzón>/0x000…000/encargo/:taskId    el encargo, solo para quien lo cogió
+ *     POST <buzón>/0x000…000/entrega/:taskId    lo entregado, para que lo recoja el cliente
+ *
+ * DOS TEXTOS, Y NO ES REDUNDANCIA. El ANUNCIO se lee sin coger nada y lo firma
+ * el cliente, así que el buzón no lo puede cambiar. El ENCARGO solo lo ve quien
+ * ya lo ha cogido, y su keccak256 es el `taskHash` de la cadena.
+ *
+ * Los mensajes de firma de este archivo tienen que ser IDÉNTICOS a los del
+ * buzón, byte a byte: una sola diferencia y todas las firmas salen «inválidas»
+ * sin que nada diga por qué.
+ */
+import { keccak256, toBytes } from 'viem';
+/** El tablón cuelga de la dirección cero: es de todos y de nadie. */
+export const TABLON = '0x0000000000000000000000000000000000000000';
+/** Dónde está el buzón que guarda los textos del tablón. */
+export const BUZON_URL = 'https://api.panal.lat/buzon';
+/**
+ * Cuánto vale como mucho una firma de lectura o de entrega, en segundos.
+ *
+ * El buzón rechaza cualquier `expira` más allá de 15 minutos. Se firma con
+ * menos margen para no rozar el límite si el reloj de quien firma va adelantado.
+ */
+export const VENTANA_FIRMA_S = 10 * 60;
+/** Lo que firma el cliente al publicar: el anuncio, atado a su tarea. */
+export function ofertaSignMessage(taskId, publico) {
+    return `Panal tablón #${taskId.toString()} · ${keccak256(toBytes(publico))}`;
+}
+/** Lo que firma el trabajador para leer el encargo que ha cogido. */
+export function encargoSignMessage(taskId, expira) {
+    return `Panal encargo #${taskId.toString()} · ${expira}`;
+}
+/** Lo que firma el trabajador para dejar su entrega en el buzón. */
+export function entregaSignMessage(taskId, expira) {
+    return `Panal entrega #${taskId.toString()} · ${expira}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "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 && tsx test/attachments.test.ts && tsx test/llm.test.ts && tsx test/skill.test.ts && tsx test/agent-card.test.ts && tsx test/niveles.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 && tsx test/attachments.test.ts && tsx test/llm.test.ts && tsx test/skill.test.ts && tsx test/agent-card.test.ts && tsx test/niveles.test.ts && tsx test/tablon.test.ts",
     "test:nombres": "tsx test/nombres.test.ts"
   }
 }