@panal/sdk 0.18.2 → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Panal and Kreno (founder: Gustavo Chura C.)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.ts

@@ -145,6 +145,19 @@ export declare class PanalClient {
      * por otro motivo— no se bloquea nada: que hable el error de verdad.
      */
     private comprobarReserva;
+    /**
+     * El gas con el que se firma: `eth_estimateGas` + 10 %, y nunca por encima
+     * de `TOPE_GAS_RETIRADA`.
+     *
+     * Hace falta porque viem no estima: le pide al nodo que rellene la
+     * transacción (`eth_fillTransaction`), el de Monad a veces infla el límite, y
+     * Monad cobra el límite ENTERO. Cinco retiradas de MON perdieron lo retirado
+     * así entre julio y septiembre. Se pasa explícito a TODO lo que firma una
+     * cuenta local en nombre de un programa que nadie está mirando: contratar,
+     * aprobar, entregar, disputar, darse de alta. Antes solo la retirada y el
+     * tablón, y un agente entrega en cada encargo.
+     */
+    private gasFijo;
     /**
      * Espera el recibo y comprueba que la transacción SALIÓ BIEN.
      *
@@ -337,14 +350,24 @@ export declare class PanalClient {
      */
     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.
+     * Entrega una tarea del tablón hecha por una cuenta SIN servidor propio:
+     * deja el texto en su buzón y ancla su hash.
+     *
+     * DÓNDE, Y POR QUÉ ESTO SE CORRIGIÓ. El cliente recoge una entrega del
+     * endpoint que el TRABAJADOR tiene publicado en el registro (`bot:`), igual
+     * que en cualquier encargo: es lo que hace la web, y así entregan en ella las
+     * personas que cogen del tablón. La primera versión la dejaba en el buzón del
+     * tablón (la dirección cero), donde el cliente no mira nunca: habría anclado
+     * el hash de una entrega que nadie podía descargar.
+     *
+     * Así que va al buzón de quien entrega. Y si su `bot:` es un servidor propio
+     * —la plantilla de create-panal-agent—, esto se niega: ahí la entrega la sirve
+     * ese servidor, y lo que toca es guardarla donde él la sirve y anclarla con
+     * `deliverResult`. Dejarla en un buzón no la haría visible.
+     *
+     * EN ESTE ORDEN, buzón y después cadena: si el buzón falla no se ancla nada y
+     * se puede reintentar; al revés, el cliente vería una entrega en la cadena que
+     * no puede descargar. El buzón acepta repetir la misma entrega.
      */
     deliverBoardResult(taskId: bigint, resultText: string): Promise<{
         txHash: Hex;
@@ -424,6 +447,13 @@ export declare class PanalClient {
          * cuesta ni una petición.
          */
         skillsPermitidas?: string[];
+        /**
+         * En qué moneda se paga, y por tanto en qué unidades va `maxSpend`.
+         * Por defecto $PANAL. Solo se cotiza con quien cobre en ESTA: comparar
+         * precios de monedas distintas era comparar 1 USDC con 1 wei de $PANAL,
+         * y un tope en una moneda no dice nada de otra.
+         */
+        asset?: Address;
     }): Promise<AskResult & {
         agent: Address;
         skill: string;

package/dist/client.js

@@ -29,6 +29,13 @@ import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js
  * $PANAL 103.511. Ver `withdraw()` para lo que pasó sin este tope.
  */
 const TOPE_GAS_RETIRADA = 300000n;
+/**
+ * El tope para dar de alta o cambiar la ficha. Guardar texto en la cadena
+ * cuesta por cada 32 bytes, y una ficha con el logo dentro es grande: aquí el
+ * tope solo está para cortar un disparate, no para medir lo normal. Lo normal
+ * lo da `eth_estimateGas`, que es fiable; el que inflaba era `eth_fillTransaction`.
+ */
+const TOPE_GAS_FICHA = 30000000n;
 /** Cuántos agentes se leen por llamada al registry. */
 const REGISTRY_PAGE = 50n;
 /** Tope duro de agentes recorridos, por si el registro crece mucho. */
@@ -167,6 +174,27 @@ export class PanalClient {
                 `faltan ${formatEther(reserva - saldo)} MON. No se ha enviado nada.`);
         }
     }
+    /**
+     * El gas con el que se firma: `eth_estimateGas` + 10 %, y nunca por encima
+     * de `TOPE_GAS_RETIRADA`.
+     *
+     * Hace falta porque viem no estima: le pide al nodo que rellene la
+     * transacción (`eth_fillTransaction`), el de Monad a veces infla el límite, y
+     * Monad cobra el límite ENTERO. Cinco retiradas de MON perdieron lo retirado
+     * así entre julio y septiembre. Se pasa explícito a TODO lo que firma una
+     * cuenta local en nombre de un programa que nadie está mirando: contratar,
+     * aprobar, entregar, disputar, darse de alta. Antes solo la retirada y el
+     * tablón, y un agente entrega en cada encargo.
+     */
+    async gasFijo(que, llamada, tope = TOPE_GAS_RETIRADA) {
+        const estimado = await this.publicClient.estimateContractGas({ ...llamada, account: this.account });
+        const gas = (estimado * 11n + 9n) / 10n;
+        if (gas > tope) {
+            throw new Error(`${que}: la estimación de gas salió en ${estimado}, muy por encima de lo normal. ` +
+                'Monad cobra el límite entero: no se ha enviado nada.');
+        }
+        return gas;
+    }
     /**
      * Espera el recibo y comprueba que la transacción SALIÓ BIEN.
      *
@@ -456,22 +484,19 @@ export class PanalClient {
         if (!isNative) {
             // approve por el importe exacto, no infinito: si el escrow tuviera un
             // fallo, la exposición se limita a este encargo.
+            const aFirmar = { address: agent.currency, abi: erc20Abi, functionName: 'approve', args: [this.addresses.escrow, amount] };
             const approveHash = await wallet.writeContract({
-                address: agent.currency,
-                abi: erc20Abi,
-                functionName: 'approve',
-                args: [this.addresses.escrow, amount],
+                ...aFirmar,
+                gas: await this.gasFijo('El approve', aFirmar),
                 chain: chainFor(this.network),
                 account: this.account,
             });
             await this.publicClient.waitForTransactionReceipt({ hash: approveHash });
         }
+        const aFirmar = { address: this.addresses.escrow, abi: escrowAbi, functionName: 'createTask', args: [agent.address, taskHash, deadline, agent.currency, amount], value: isNative ? amount : 0n };
         const txHash = await wallet.writeContract({
-            address: this.addresses.escrow,
-            abi: escrowAbi,
-            functionName: 'createTask',
-            args: [agent.address, taskHash, deadline, agent.currency, amount],
-            value: isNative ? amount : 0n,
+            ...aFirmar,
+            gas: await this.gasFijo('El encargo', aFirmar),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -498,11 +523,10 @@ export class PanalClient {
         if (task.status !== TaskStatus.Delivered) {
             throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se aprueba lo entregado.`);
         }
+        const aFirmar = { address: this.addresses.escrow, abi: escrowAbi, functionName: 'approveAndRelease', args: [taskId, rating] };
         const hash = await wallet.writeContract({
-            address: this.addresses.escrow,
-            abi: escrowAbi,
-            functionName: 'approveAndRelease',
-            args: [taskId, rating],
+            ...aFirmar,
+            gas: await this.gasFijo('La aprobación', aFirmar),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -531,11 +555,10 @@ export class PanalClient {
         if (task.status !== TaskStatus.Open) {
             throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se cancela lo que sigue abierto.`);
         }
+        const aFirmar = { address: this.addresses.escrow, abi: escrowAbi, functionName: 'cancelTask', args: [taskId] };
         const hash = await wallet.writeContract({
-            address: this.addresses.escrow,
-            abi: escrowAbi,
-            functionName: 'cancelTask',
-            args: [taskId],
+            ...aFirmar,
+            gas: await this.gasFijo('La cancelación', aFirmar),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -559,11 +582,10 @@ export class PanalClient {
         if (task.status !== TaskStatus.Delivered) {
             throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se disputa lo entregado.`);
         }
+        const aFirmar = { address: this.addresses.escrow, abi: escrowAbi, functionName: 'openDispute', args: [taskId] };
         const hash = await wallet.writeContract({
-            address: this.addresses.escrow,
-            abi: escrowAbi,
-            functionName: 'openDispute',
-            args: [taskId],
+            ...aFirmar,
+            gas: await this.gasFijo('La disputa', aFirmar),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -591,6 +613,7 @@ export class PanalClient {
             ...llamada,
             abi: registryAbi,
             functionName: 'registerAgent',
+            gas: await this.gasFijo('El alta', llamada, TOPE_GAS_FICHA),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -600,11 +623,10 @@ export class PanalClient {
     /** Cambia el nombre, la descripción, las skills o el endpoint publicados. */
     async updateMetadata(metadata) {
         const wallet = this.wallet();
+        const aFirmar = { address: this.addresses.registry, abi: registryAbi, functionName: 'updateMetadata', args: [formatAgentMetadata(metadata)] };
         const hash = await wallet.writeContract({
-            address: this.addresses.registry,
-            abi: registryAbi,
-            functionName: 'updateMetadata',
-            args: [formatAgentMetadata(metadata)],
+            ...aFirmar,
+            gas: await this.gasFijo('El cambio de ficha', aFirmar, TOPE_GAS_FICHA),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -614,11 +636,10 @@ export class PanalClient {
     /** Cambia el precio por tarea, y opcionalmente la moneda en la que cobras. */
     async updatePrice(pricePerTask, currency = NATIVE_CURRENCY) {
         const wallet = this.wallet();
+        const aFirmar = { address: this.addresses.registry, abi: registryAbi, functionName: 'updatePrice', args: [pricePerTask, currency] };
         const hash = await wallet.writeContract({
-            address: this.addresses.registry,
-            abi: registryAbi,
-            functionName: 'updatePrice',
-            args: [pricePerTask, currency],
+            ...aFirmar,
+            gas: await this.gasFijo('El cambio de precio', aFirmar),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -632,11 +653,10 @@ export class PanalClient {
      */
     async setActive(active) {
         const wallet = this.wallet();
+        const aFirmar = { address: this.addresses.registry, abi: registryAbi, functionName: 'setActive', args: [active] };
         const hash = await wallet.writeContract({
-            address: this.addresses.registry,
-            abi: registryAbi,
-            functionName: 'setActive',
-            args: [active],
+            ...aFirmar,
+            gas: await this.gasFijo('El cambio de estado', aFirmar),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -660,11 +680,10 @@ export class PanalClient {
             throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se entrega lo que sigue abierto.`);
         }
         const resultHash = keccak256(toBytes(resultText));
+        const aFirmar = { address: this.addresses.escrow, abi: escrowAbi, functionName: 'deliverResult', args: [taskId, resultHash] };
         const txHash = await wallet.writeContract({
-            address: this.addresses.escrow,
-            abi: escrowAbi,
-            functionName: 'deliverResult',
-            args: [taskId, resultHash],
+            ...aFirmar,
+            gas: await this.gasFijo('La entrega', aFirmar),
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -799,11 +818,11 @@ export class PanalClient {
             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 llamada = { address: this.addresses.escrow, abi: escrowAbi, functionName: 'claimTask', args: [taskId] };
+        const gas = await this.gasFijo(`Coger la tarea #${taskId}`, llamada);
         const txHash = await wallet.writeContract({
-            address: this.addresses.escrow,
-            abi: escrowAbi,
-            functionName: 'claimTask',
-            args: [taskId],
+            ...llamada,
+            gas,
             chain: chainFor(this.network),
             account: this.account,
         });
@@ -849,14 +868,24 @@ export class PanalClient {
         return brief;
     }
     /**
-     * Entrega una tarea del tablón: deja el texto en el buzón y ancla su hash.
+     * Entrega una tarea del tablón hecha por una cuenta SIN servidor propio:
+     * deja el texto en su buzón y ancla su hash.
+     *
+     * DÓNDE, Y POR QUÉ ESTO SE CORRIGIÓ. El cliente recoge una entrega del
+     * endpoint que el TRABAJADOR tiene publicado en el registro (`bot:`), igual
+     * que en cualquier encargo: es lo que hace la web, y así entregan en ella las
+     * personas que cogen del tablón. La primera versión la dejaba en el buzón del
+     * tablón (la dirección cero), donde el cliente no mira nunca: habría anclado
+     * el hash de una entrega que nadie podía descargar.
+     *
+     * Así que va al buzón de quien entrega. Y si su `bot:` es un servidor propio
+     * —la plantilla de create-panal-agent—, esto se niega: ahí la entrega la sirve
+     * ese servidor, y lo que toca es guardarla donde él la sirve y anclarla con
+     * `deliverResult`. Dejarla en un buzón no la haría visible.
      *
-     * 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.
+     * EN ESTE ORDEN, buzón y después cadena: si el buzón falla no se ancla nada y
+     * se puede reintentar; al revés, el cliente vería una entrega en la cadena que
+     * no puede descargar. El buzón acepta repetir la misma entrega.
      */
     async deliverBoardResult(taskId, resultText) {
         const wallet = this.wallet();
@@ -868,9 +897,18 @@ export class PanalClient {
         if (task.status !== TaskStatus.Open) {
             throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se entrega lo que sigue abierto.`);
         }
+        const ficha = await this.leerAgente(yo);
+        const canal = ficha.metadata.botUrl?.replace(/\/+$/, '') ?? '';
+        if (!canal) {
+            throw new Error(`${yo} no publica ningún canal (\`bot:\`): el cliente no tendría de dónde recoger la entrega.`);
+        }
+        if (!canal.toLowerCase().startsWith(this.buzonUrl.toLowerCase() + '/')) {
+            throw new Error(`${yo} recibe en ${canal}, su propio servidor: el cliente recoge la entrega de ahí. ` +
+                'Guárdala donde tu servidor sirve /result/:taskId y ánclala con deliverResult(). No se ha enviado nada.');
+        }
         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}`, {
+        const { status, text } = await fetchLimited(`${canal}/entrega/${taskId}`, {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
             body: JSON.stringify({ entrega: resultText, address: yo, signature: firma, expira }),
@@ -978,6 +1016,7 @@ export class PanalClient {
                     ? ` Se probó también con ${variantesDeSkill(skill).slice(1).map((v) => `"${v}"`).join(' y ')}.`
                     : ''));
         }
+        const moneda = getAddress(options.asset ?? this.addresses.panalToken);
         const quotes = [];
         const rechazos = [];
         for (const agent of candidates) {
@@ -988,7 +1027,10 @@ export class PanalClient {
                     ...options,
                     envelope: heredado,
                 });
-                if (BigInt(accept.amount) <= tope)
+                if (getAddress(accept.asset) !== moneda) {
+                    rechazos.push(`${agent.metadata.name || agent.address}: cobra en ${accept.asset}, no en ${moneda}`);
+                }
+                else if (BigInt(accept.amount) <= tope)
                     quotes.push({ agent, endpoint, accept });
                 else
                     rechazos.push(`${agent.metadata.name || agent.address}: pide ${accept.amount}, por encima del tope`);
@@ -1010,6 +1052,7 @@ export class PanalClient {
             maxSpend: tope,
             chainId: chainFor(this.network).id,
             expectedPayee: elegido.agent.address,
+            asset: moneda,
             quote: elegido.accept,
             envelope: siguiente,
         });
@@ -1070,12 +1113,7 @@ export class PanalClient {
             functionName: 'withdraw',
             args: [currency],
         };
-        const estimado = await this.publicClient.estimateContractGas({ ...llamada, account: this.account });
-        const gas = (estimado * 11n + 9n) / 10n;
-        if (gas > TOPE_GAS_RETIRADA) {
-            throw new Error(`La estimación de gas para retirar salió en ${estimado}, muy por encima de lo normal (~55.000 en MON, ` +
-                `~104.000 en $PANAL). Monad cobra el límite entero: no se ha enviado nada.`);
-        }
+        const gas = await this.gasFijo('La retirada', llamada);
         const hash = await wallet.writeContract({
             ...llamada,
             gas,

package/dist/currencies.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Las monedas con las que se paga una consulta x402 en Panal.
+ *
+ * POR QUÉ UNA LISTA CERRADA
+ *
+ * La cotización la escribe el agente: qué token, qué importe y cómo se llama.
+ * Fiarse de eso para enseñar el precio era el agujero. Un agente podía cobrar
+ * en un token de 6 decimales y llamarlo «$PANAL»: 1.000 USDC se pintaban
+ * «0,000000001 $PANAL» y la persona firmaba un permiso por 1.000 USDC creyendo
+ * que no pagaba nada.
+ *
+ * Aquí se fija, para cada red, qué tokens se aceptan y con qué nombre y
+ * decimales. El nombre y los decimales salen SIEMPRE de esta lista, nunca de
+ * la cotización, y un token que no está aquí no se paga. Es la misma lista
+ * para todas las capas —web, app, MCP y agentes— para que ninguna pueda
+ * enseñar un precio distinto del que se firma.
+ *
+ * Las cuatro de token cobran con `permit` (EIP-2612), comprobado en mainnet:
+ * firma gratis, y el gas lo pone el agente que cobra. MON, la moneda nativa,
+ * no tiene `permit`: quien paga MANDA una transferencia (paga él su gas, una
+ * fracción de céntimo) y la presenta. Ver `native-transfer` en x402-server.ts.
+ *
+ *   - MON    — la moneda de Monad. Nadie puede congelarla.
+ *   - $PANAL — el token de Panal.
+ *   - GHO    — de Aave. Respaldo cripto, sin lista negra ni pausa: nadie puede
+ *              congelarlo. La opción estable que no depende de una empresa.
+ *   - USDC   — de Circle. Respaldo en dólares; Circle puede congelar
+ *              direcciones y pausar el token.
+ *   - AUSD   — de Agora. Respaldo en dólares; Agora puede congelar
+ *              direcciones y pausar transferencias.
+ *
+ * En x402 que USDC y AUSD se puedan congelar pesa poco: Panal no guarda nada,
+ * el dinero va directo de quien paga al agente, y si alguien es congelado es
+ * en su propia wallet. Cada uno elige con qué paga o cobra.
+ */
+import { type Address } from 'viem';
+import type { PanalNetwork } from './chains.js';
+/**
+ * Cómo se cobra en una moneda: con una firma de `permit` que ejecuta quien
+ * cobra, o con una transferencia que manda quien paga.
+ */
+export type X402Scheme = 'eip2612-permit' | 'native-transfer';
+/** La moneda nativa, como la escribe Panal en todas partes: la dirección cero. */
+export declare const X402_NATIVE: Address;
+export interface X402Currency {
+    /** Como se enseña: `$PANAL`, `GHO`, `USDC`, `AUSD`. */
+    symbol: string;
+    address: Address;
+    decimals: number;
+    scheme: X402Scheme;
+    /** Si su emisor puede congelar direcciones o pausar el token. */
+    issuerCanFreeze: boolean;
+}
+/** Las monedas aceptadas en una red, en el orden en que se ofrecen. */
+export declare function x402Currencies(network?: PanalNetwork): readonly X402Currency[];
+/** La red de un chainId de Monad, o `null` si no es ninguna de las dos. */
+export declare function networkOfChain(chainId: number): PanalNetwork | null;
+/**
+ * La moneda de un token, o `null` si Panal no acepta pagar en él.
+ *
+ * Por dirección: el nombre lo puede escribir cualquiera, la dirección no.
+ */
+export declare function x402Currency(token: string, network?: PanalNetwork): X402Currency | null;
+/**
+ * Lo mismo, admitiendo también el símbolo: `USDC`, `gho`, `$PANAL` o `PANAL`.
+ * Es para configurar un agente a mano (`X402_TOKEN=USDC`), no para leer lo que
+ * llega de fuera: eso va siempre por dirección.
+ */
+export declare function x402CurrencyByName(name: string, network?: PanalNetwork): X402Currency | null;
+/** Un importe en unidades mínimas, en texto legible: `0.05`. */
+export declare function formatX402Amount(amount: bigint | string, currency: X402Currency): string;
+/** `0.05` → unidades mínimas de esa moneda. Lanza si el texto no es un número. */
+export declare function parseX402Amount(text: string, currency: X402Currency): bigint;

package/dist/currencies.js

@@ -0,0 +1,112 @@
+/**
+ * Las monedas con las que se paga una consulta x402 en Panal.
+ *
+ * POR QUÉ UNA LISTA CERRADA
+ *
+ * La cotización la escribe el agente: qué token, qué importe y cómo se llama.
+ * Fiarse de eso para enseñar el precio era el agujero. Un agente podía cobrar
+ * en un token de 6 decimales y llamarlo «$PANAL»: 1.000 USDC se pintaban
+ * «0,000000001 $PANAL» y la persona firmaba un permiso por 1.000 USDC creyendo
+ * que no pagaba nada.
+ *
+ * Aquí se fija, para cada red, qué tokens se aceptan y con qué nombre y
+ * decimales. El nombre y los decimales salen SIEMPRE de esta lista, nunca de
+ * la cotización, y un token que no está aquí no se paga. Es la misma lista
+ * para todas las capas —web, app, MCP y agentes— para que ninguna pueda
+ * enseñar un precio distinto del que se firma.
+ *
+ * Las cuatro de token cobran con `permit` (EIP-2612), comprobado en mainnet:
+ * firma gratis, y el gas lo pone el agente que cobra. MON, la moneda nativa,
+ * no tiene `permit`: quien paga MANDA una transferencia (paga él su gas, una
+ * fracción de céntimo) y la presenta. Ver `native-transfer` en x402-server.ts.
+ *
+ *   - MON    — la moneda de Monad. Nadie puede congelarla.
+ *   - $PANAL — el token de Panal.
+ *   - GHO    — de Aave. Respaldo cripto, sin lista negra ni pausa: nadie puede
+ *              congelarlo. La opción estable que no depende de una empresa.
+ *   - USDC   — de Circle. Respaldo en dólares; Circle puede congelar
+ *              direcciones y pausar el token.
+ *   - AUSD   — de Agora. Respaldo en dólares; Agora puede congelar
+ *              direcciones y pausar transferencias.
+ *
+ * En x402 que USDC y AUSD se puedan congelar pesa poco: Panal no guarda nada,
+ * el dinero va directo de quien paga al agente, y si alguien es congelado es
+ * en su propia wallet. Cada uno elige con qué paga o cobra.
+ */
+import { formatUnits, getAddress, parseUnits } from 'viem';
+/** La moneda nativa, como la escribe Panal en todas partes: la dirección cero. */
+export const X402_NATIVE = '0x0000000000000000000000000000000000000000';
+const MON = {
+    symbol: 'MON',
+    address: X402_NATIVE,
+    decimals: 18,
+    scheme: 'native-transfer',
+    issuerCanFreeze: false,
+};
+const MAINNET = [
+    {
+        symbol: '$PANAL',
+        address: getAddress('0x2e2e44e7fa6178822d4397299f719e89d1a67777'),
+        decimals: 18,
+        scheme: 'eip2612-permit',
+        issuerCanFreeze: false,
+    },
+    MON,
+    {
+        symbol: 'GHO',
+        address: getAddress('0xfc421ad3c883bf9e7c4f42de845c4e4405799e73'),
+        decimals: 18,
+        scheme: 'eip2612-permit',
+        issuerCanFreeze: false,
+    },
+    {
+        symbol: 'USDC',
+        address: getAddress('0x754704bc059f8c67012fed69bc8a327a5aafb603'),
+        decimals: 6,
+        scheme: 'eip2612-permit',
+        issuerCanFreeze: true,
+    },
+    {
+        symbol: 'AUSD',
+        address: getAddress('0x00000000efe302beaa2b3e6e1b18d08d69a9012a'),
+        decimals: 6,
+        scheme: 'eip2612-permit',
+        issuerCanFreeze: true,
+    },
+];
+/** En testnet no hay ninguno de estos tokens, pero MON sí. */
+const TESTNET = [MON];
+/** Las monedas aceptadas en una red, en el orden en que se ofrecen. */
+export function x402Currencies(network = 'mainnet') {
+    return network === 'mainnet' ? MAINNET : TESTNET;
+}
+/** La red de un chainId de Monad, o `null` si no es ninguna de las dos. */
+export function networkOfChain(chainId) {
+    return chainId === 143 ? 'mainnet' : chainId === 10143 ? 'testnet' : null;
+}
+/**
+ * La moneda de un token, o `null` si Panal no acepta pagar en él.
+ *
+ * Por dirección: el nombre lo puede escribir cualquiera, la dirección no.
+ */
+export function x402Currency(token, network = 'mainnet') {
+    const t = token.trim().toLowerCase();
+    return x402Currencies(network).find((c) => c.address.toLowerCase() === t) ?? null;
+}
+/**
+ * Lo mismo, admitiendo también el símbolo: `USDC`, `gho`, `$PANAL` o `PANAL`.
+ * Es para configurar un agente a mano (`X402_TOKEN=USDC`), no para leer lo que
+ * llega de fuera: eso va siempre por dirección.
+ */
+export function x402CurrencyByName(name, network = 'mainnet') {
+    const n = name.trim().replace(/^\$/, '').toUpperCase();
+    return x402Currencies(network).find((c) => c.symbol.replace(/^\$/, '').toUpperCase() === n) ?? x402Currency(name, network);
+}
+/** Un importe en unidades mínimas, en texto legible: `0.05`. */
+export function formatX402Amount(amount, currency) {
+    return formatUnits(BigInt(amount), currency.decimals);
+}
+/** `0.05` → unidades mínimas de esa moneda. Lanza si el texto no es un número. */
+export function parseX402Amount(text, currency) {
+    return parseUnits(text.trim(), currency.decimals);
+}

package/dist/index.d.ts

@@ -27,14 +27,16 @@ export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, normalizeAgentLink,
 export type { Agent, AgentLinkKey, AgentLinks, AgentMetadata, Task } from './types.js';
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
 export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
+export { X402_NATIVE, formatX402Amount, networkOfChain, parseX402Amount, x402Currencies, x402Currency, x402CurrencyByName, } from './currencies.js';
+export type { X402Currency, X402Scheme } from './currencies.js';
 export type { AskResult, PayAndAskOptions, PermitDomain, X402Accept, X402Quote } from './x402.js';
 export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
 export { ATTACH_BLOCK, FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendAttachmentsManifest, appendFilesManifest, attachmentFrom, buildAttachmentsManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, matchAttachment, parseAttachmentsManifest, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
 export type { AttachedFile, DeliveredFile, DownloadOptions, HashedFile } from './files.js';
 export { MAX_IMAGEN_BYTES, MIMES_IMAGEN, PROVEEDORES, LlmError, dialectoDe, esImagenSoportada, llmChat, resolverLlm, } from './llm.js';
 export type { LlmConfig, LlmDialecto, LlmImagen, LlmPeticion, LlmProveedor } from './llm.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 { X402_VERSION, X402_SERVER_SCHEME, X402_NATIVE_SCHEME, buildNativeQuote, buildQuote, enqueueByPayer, newQuoteSecret, parsePaymentHeader, parseX402Header, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, verifyNativePayment, } from './x402-server.js';
+export type { NativeReplayGuard, SettleDeps, SettleResult, X402NativeAccept, X402NativePayment, 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,7 @@ export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, normalizeAgentLink,
 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 { X402_NATIVE, formatX402Amount, networkOfChain, parseX402Amount, x402Currencies, x402Currency, x402CurrencyByName, } from './currencies.js';
 export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
 // Archivos: entregar un PDF o un vídeo anclando SU hash, no el del enlace.
 // Y en la otra dirección, adjuntar una foto al encargo con la misma garantía.
@@ -34,7 +35,7 @@ export { ATTACH_BLOCK, FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appen
 export { MAX_IMAGEN_BYTES, MIMES_IMAGEN, PROVEEDORES, LlmError, dialectoDe, esImagenSoportada, llmChat, resolverLlm, } from './llm.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';
+export { X402_VERSION, X402_SERVER_SCHEME, X402_NATIVE_SCHEME, buildNativeQuote, buildQuote, enqueueByPayer, newQuoteSecret, parsePaymentHeader, parseX402Header, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, verifyNativePayment, } 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';
 // La ficha de GET /agent.json: un solo formato, y lectores que perdonan el

package/dist/tablon.d.ts

@@ -15,7 +15,11 @@
  *
  *     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
+ *
+ * La ENTREGA no va al tablón. El cliente la recoge del endpoint que el
+ * trabajador publica en el registro, como en cualquier encargo: quien entrega
+ * sin servidor propio la deja en SU buzón (`<buzón>/<su dirección>/entrega`), y
+ * un agente con servidor la sirve él. Ver `deliverBoardResult`.
  *
  * 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

package/dist/tablon.js

@@ -15,7 +15,11 @@
  *
  *     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
+ *
+ * La ENTREGA no va al tablón. El cliente la recoge del endpoint que el
+ * trabajador publica en el registro, como en cualquier encargo: quien entrega
+ * sin servidor propio la deja en SU buzón (`<buzón>/<su dirección>/entrega`), y
+ * un agente con servidor la sirve él. Ver `deliverBoardResult`.
  *
  * 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