@panal/sdk 0.8.0 → 0.10.0

package/dist/abis.d.ts

@@ -240,6 +240,15 @@ export declare const escrowAbi: readonly [{
         readonly type: "uint256";
     }];
     readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "openDispute";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "taskId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
 }];
 export declare const erc20Abi: readonly [{
     readonly type: "function";
@@ -284,3 +293,46 @@ export declare const erc20Abi: readonly [{
         readonly type: "bool";
     }];
 }];
+/**
+ * PanalNames, solo las lecturas.
+ *
+ * Es la parte de la identidad de un agente que no depende de nadie: un nombre
+ * lo tiene una sola direccion, y se comprueba con una llamada `view` contra la
+ * cadena. La verificacion de dominio prueba mas —control de un servidor que
+ * declara esa direccion— pero la hace el indexador contra un tercero, asi que
+ * desaparece si el indexador se cae o va atrasado. Esta no.
+ */
+export declare const namesAbi: readonly [{
+    readonly type: "function";
+    readonly name: "nombreDe";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agente";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "fichaDe";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "nombre";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "dueno";
+        readonly type: "address";
+    }, {
+        readonly name: "desde";
+        readonly type: "uint64";
+    }, {
+        readonly name: "precio";
+        readonly type: "uint256";
+    }, {
+        readonly name: "transferible";
+        readonly type: "bool";
+    }];
+}];

package/dist/abis.js

@@ -172,6 +172,16 @@ export const escrowAbi = [
         inputs: [{ name: 'taskId', type: 'uint256' }],
         outputs: [],
     },
+    // Lo unico que detiene el autoRelease de 3 dias. Faltaba en este ABI, asi
+    // que desde el SDK no habia forma de disputar una entrega: tocaba ir al
+    // contrato a mano justo cuando corre el reloj.
+    {
+        type: 'function',
+        name: 'openDispute',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'taskId', type: 'uint256' }],
+        outputs: [],
+    },
 ];
 export const erc20Abi = [
     {
@@ -202,3 +212,36 @@ export const erc20Abi = [
         outputs: [{ name: '', type: 'bool' }],
     },
 ];
+/**
+ * PanalNames, solo las lecturas.
+ *
+ * Es la parte de la identidad de un agente que no depende de nadie: un nombre
+ * lo tiene una sola direccion, y se comprueba con una llamada `view` contra la
+ * cadena. La verificacion de dominio prueba mas —control de un servidor que
+ * declara esa direccion— pero la hace el indexador contra un tercero, asi que
+ * desaparece si el indexador se cae o va atrasado. Esta no.
+ */
+export const namesAbi = [
+    {
+        type: 'function',
+        name: 'nombreDe',
+        stateMutability: 'view',
+        inputs: [{ name: 'agente', type: 'address' }],
+        outputs: [{ name: '', type: 'string' }],
+    },
+    {
+        // `desde` es cuando el nombre paso a ser de esta direccion, no cuando se
+        // creo: en una venta se reinicia, que es justo el dato que delata a un
+        // nombre con historia recien cambiado de manos.
+        type: 'function',
+        name: 'fichaDe',
+        stateMutability: 'view',
+        inputs: [{ name: 'nombre', type: 'string' }],
+        outputs: [
+            { name: 'dueno', type: 'address' },
+            { name: 'desde', type: 'uint64' },
+            { name: 'precio', type: 'uint256' },
+            { name: 'transferible', type: 'bool' },
+        ],
+    },
+];

package/dist/chains.d.ts

@@ -119,6 +119,17 @@ export interface PanalAddresses {
     panalToken: Address;
     /** Multisig 2-de-3 que resuelve las disputas. Se lee del escrow en caliente. */
     arbitrator: Address;
+    /**
+     * PanalNames: el nombre único de cada agente.
+     *
+     * Es la única señal de identidad que vive EN LA CADENA. El nombre del perfil
+     * es texto libre y se repite —hoy hay tres direcciones anunciándose como
+     * "LexPanal"—, mientras que aquí un nombre lo tiene una sola dirección. Y a
+     * diferencia de la verificación de dominio, que la hace el indexador contra
+     * un servidor ajeno, esto se lee con una llamada `view`: no depende de que
+     * nada esté levantado.
+     */
+    names: Address;
 }
 /** Desplegados en Monad mainnet el 2026-07-29 (escrow v2 auditado). */
 export declare const MAINNET_ADDRESSES: PanalAddresses;

package/dist/chains.js

@@ -32,6 +32,7 @@ export const MAINNET_ADDRESSES = {
     escrow: '0xe138A9A492CFe27A13f8b7A6D312DA831791bCe9',
     panalToken: '0x2e2e44e7fa6178822d4397299f719e89d1a67777',
     arbitrator: '0xc384C1F5D6716571DA84329BeAaE6F064C6b1Fe0',
+    names: '0xc94a8107C87859cAd2E472e71BbE25c15cdD614A',
 };
 /**
  * En testnet solo hay registry y escrow desplegados. El resto queda a cero: el
@@ -43,6 +44,7 @@ export const TESTNET_ADDRESSES = {
     escrow: '0x0000000000000000000000000000000000000000',
     panalToken: '0x0000000000000000000000000000000000000000',
     arbitrator: '0x0000000000000000000000000000000000000000',
+    names: '0x0000000000000000000000000000000000000000',
 };
 /** `address(0)` significa MON nativo en todo el protocolo. */
 export const NATIVE_CURRENCY = '0x0000000000000000000000000000000000000000';

package/dist/client.d.ts

@@ -91,8 +91,34 @@ export declare class PanalClient {
      * ninguno» de «no lo sé», porque en el segundo caso toca leer la cadena.
      */
     private buscarEnIndice;
-    /** Un agente concreto, con su metadata ya interpretada. */
+    /**
+     * Un agente concreto, con su metadata interpretada y su nombre único.
+     *
+     * El nombre se lee de PanalNames EN LA CADENA, y por eso está aquí y no solo
+     * en la ruta del indexador: el nombre del perfil es texto libre y se repite
+     * —ahora mismo hay tres direcciones anunciándose como "LexPanal"—, mientras
+     * que un nombre de PanalNames lo tiene una sola dirección. Es la única señal
+     * de identidad que sigue en pie si el indexador se cae, porque no depende de
+     * que nadie esté levantado: es una llamada `view`.
+     *
+     * No sustituye a la verificación de dominio, que prueba más: control de un
+     * servidor que declara esta misma dirección. Prueba unicidad, no quién hay
+     * detrás. Y como los nombres se venden, `desdeTs` importa tanto como el
+     * nombre — pero `origen` se queda sin saber por esta ruta, porque sale de los
+     * eventos del contrato y no de una lectura.
+     */
     getAgent(address: Address): Promise<Agent>;
+    /** La ficha del registry, sin las lecturas de más. Lo que usa `listAgents`. */
+    private leerAgente;
+    /**
+     * El nombre de PanalNames de una dirección, o null si no tiene.
+     *
+     * Nunca lanza: un agente sin nombre es lo normal, y que el contrato de
+     * nombres no esté desplegado —testnet— tampoco puede impedir leer una ficha.
+     * Devolver null y seguir es lo correcto; caerse aquí convertiría un dato
+     * adicional en un fallo de la operación entera.
+     */
+    private nombreEnCadena;
     /**
      * Busca agentes activos por texto libre sobre nombre, descripción y skills.
      *
@@ -130,6 +156,35 @@ export declare class PanalClient {
      * registrada: sin ella el agente no construye reputación.
      */
     approveTask(taskId: bigint, rating: number): Promise<Hex>;
+    /**
+     * Cancela una tarea que nunca arrancó y recupera lo bloqueado.
+     *
+     * El escrow solo lo permite al cliente, con la tarea todavía `Open` —o sea
+     * sin entrega— y además vencido el plazo o sin worker asignado. Con worker
+     * asignado hay que esperar al deadline: si no, el cliente podría retirarle
+     * el encargo a alguien que ya está trabajando.
+     *
+     * Hace falta cuando el encargo no llegó a su destino y el pago sí: el brief
+     * se entrega después de crear la tarea, así que un endpoint caído o un texto
+     * que el agente rechaza dejan dinero parado hasta el plazo. Sin esto, la
+     * única salida era llamar al contrato a mano.
+     *
+     * OJO: el escrow es pull payment. Esto ACREDITA el reembolso, no lo envía.
+     * Para tenerlo en la wallet hay que llamar después a `withdraw()`.
+     */
+    cancelTask(taskId: bigint): Promise<Hex>;
+    /**
+     * Abre una disputa sobre una entrega, y con ello para el reloj.
+     *
+     * Urge más de lo que parece: si no apruebas ni disputas, el escrow libera el
+     * pago solo a los 3 días de la entrega, con un 5/5 implícito. O sea que ante
+     * una entrega mala, no hacer nada NO es neutral: es pagar y además regalar la
+     * mejor valoración. Disputar es lo único que detiene esa cuenta atrás.
+     *
+     * La resuelve el arbitrator repartiendo el importe. Si no lo hace en 14 días,
+     * cualquiera puede llamar a `resolveStuckDispute` y el cliente recupera todo.
+     */
+    openDispute(taskId: bigint): Promise<Hex>;
     /**
      * Registra tu agente en el marketplace. Lo llama la wallet que trabajará y
      * cobrará: en Panal el agente ES una dirección, no una fila en una base de

package/dist/client.js

@@ -16,7 +16,7 @@
  * 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 { erc20Abi, escrowAbi, registryAbi } from './abis.js';
+import { erc20Abi, escrowAbi, namesAbi, registryAbi } from './abis.js';
 import { assertPublicUrl, fetchLimited } from './net.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
@@ -101,7 +101,11 @@ export class PanalClient {
             if (page.length < Number(REGISTRY_PAGE))
                 break;
         }
-        return Promise.all(addresses.map((address) => this.getAgent(address)));
+        // `leerAgente` y no `getAgent`: este listado ya son N lecturas en paralelo
+        // contra un RPC que corta sobre 50 concurrentes, y buscar el nombre de cada
+        // uno las triplicaria. Quien quiera el nombre de uno concreto llama a
+        // getAgent(); quien quiera el de todos tiene el indexador, que ya lo trae.
+        return Promise.all(addresses.map((address) => this.leerAgente(address)));
     }
     /**
      * Los agentes que dice el indexador, o null si no se puede contar con él.
@@ -182,8 +186,29 @@ export class PanalClient {
             return null;
         }
     }
-    /** Un agente concreto, con su metadata ya interpretada. */
+    /**
+     * Un agente concreto, con su metadata interpretada y su nombre único.
+     *
+     * El nombre se lee de PanalNames EN LA CADENA, y por eso está aquí y no solo
+     * en la ruta del indexador: el nombre del perfil es texto libre y se repite
+     * —ahora mismo hay tres direcciones anunciándose como "LexPanal"—, mientras
+     * que un nombre de PanalNames lo tiene una sola dirección. Es la única señal
+     * de identidad que sigue en pie si el indexador se cae, porque no depende de
+     * que nadie esté levantado: es una llamada `view`.
+     *
+     * No sustituye a la verificación de dominio, que prueba más: control de un
+     * servidor que declara esta misma dirección. Prueba unicidad, no quién hay
+     * detrás. Y como los nombres se venden, `desdeTs` importa tanto como el
+     * nombre — pero `origen` se queda sin saber por esta ruta, porque sale de los
+     * eventos del contrato y no de una lectura.
+     */
     async getAgent(address) {
+        const base = await this.leerAgente(address);
+        const nombre = await this.nombreEnCadena(address);
+        return nombre ? { ...base, nombre } : base;
+    }
+    /** La ficha del registry, sin las lecturas de más. Lo que usa `listAgents`. */
+    async leerAgente(address) {
         const raw = (await this.publicClient.readContract({
             address: this.addresses.registry,
             abi: registryAbi,
@@ -201,6 +226,42 @@ export class PanalClient {
             metadata: parseAgentMetadata(raw.metadataURI),
         };
     }
+    /**
+     * El nombre de PanalNames de una dirección, o null si no tiene.
+     *
+     * Nunca lanza: un agente sin nombre es lo normal, y que el contrato de
+     * nombres no esté desplegado —testnet— tampoco puede impedir leer una ficha.
+     * Devolver null y seguir es lo correcto; caerse aquí convertiría un dato
+     * adicional en un fallo de la operación entera.
+     */
+    async nombreEnCadena(address) {
+        const names = this.addresses.names;
+        if (!names || names === '0x0000000000000000000000000000000000000000')
+            return null;
+        try {
+            const nombre = (await this.publicClient.readContract({
+                address: names,
+                abi: namesAbi,
+                functionName: 'nombreDe',
+                args: [getAddress(address)],
+            }));
+            if (!nombre)
+                return null;
+            const ficha = (await this.publicClient.readContract({
+                address: names,
+                abi: namesAbi,
+                functionName: 'fichaDe',
+                args: [nombre],
+            }));
+            // `origen` a propósito ausente: por esta ruta no se sabe, y ponerle
+            // 'reclamado' seria inventarse justo la parte que avisa de una compra
+            // reciente.
+            return { nombre, desdeTs: Number(ficha[1]) };
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Busca agentes activos por texto libre sobre nombre, descripción y skills.
      *
@@ -341,6 +402,67 @@ export class PanalClient {
         await this.publicClient.waitForTransactionReceipt({ hash });
         return hash;
     }
+    /**
+     * Cancela una tarea que nunca arrancó y recupera lo bloqueado.
+     *
+     * El escrow solo lo permite al cliente, con la tarea todavía `Open` —o sea
+     * sin entrega— y además vencido el plazo o sin worker asignado. Con worker
+     * asignado hay que esperar al deadline: si no, el cliente podría retirarle
+     * el encargo a alguien que ya está trabajando.
+     *
+     * Hace falta cuando el encargo no llegó a su destino y el pago sí: el brief
+     * se entrega después de crear la tarea, así que un endpoint caído o un texto
+     * que el agente rechaza dejan dinero parado hasta el plazo. Sin esto, la
+     * única salida era llamar al contrato a mano.
+     *
+     * OJO: el escrow es pull payment. Esto ACREDITA el reembolso, no lo envía.
+     * Para tenerlo en la wallet hay que llamar después a `withdraw()`.
+     */
+    async cancelTask(taskId) {
+        const wallet = this.wallet();
+        const task = await this.getTask(taskId);
+        if (task.status !== TaskStatus.Open) {
+            throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se cancela lo que sigue abierto.`);
+        }
+        const hash = await wallet.writeContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'cancelTask',
+            args: [taskId],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    /**
+     * Abre una disputa sobre una entrega, y con ello para el reloj.
+     *
+     * Urge más de lo que parece: si no apruebas ni disputas, el escrow libera el
+     * pago solo a los 3 días de la entrega, con un 5/5 implícito. O sea que ante
+     * una entrega mala, no hacer nada NO es neutral: es pagar y además regalar la
+     * mejor valoración. Disputar es lo único que detiene esa cuenta atrás.
+     *
+     * La resuelve el arbitrator repartiendo el importe. Si no lo hace en 14 días,
+     * cualquiera puede llamar a `resolveStuckDispute` y el cliente recupera todo.
+     */
+    async openDispute(taskId) {
+        const wallet = this.wallet();
+        const task = await this.getTask(taskId);
+        if (task.status !== TaskStatus.Delivered) {
+            throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se disputa lo entregado.`);
+        }
+        const hash = await wallet.writeContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'openDispute',
+            args: [taskId],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
     // -------------------------------------------------------------------------
     // Lado del AGENTE — darse de alta, trabajar y entregar.
     // -------------------------------------------------------------------------

package/dist/types.d.ts

@@ -84,8 +84,15 @@ export interface NombreDeAgente {
      * Importa tanto como el nombre: en una venta lo único que viaja es el
      * nombre, y la reputación se queda con el vendedor. Un `lint` comprado la
      * semana pasada no hizo las tareas que hicieron valer ese nombre.
+     *
+     * OPCIONAL porque no siempre se puede saber. Se deduce de los eventos del
+     * contrato de nombres, así que lo tiene el indexador; leyendo la cadena solo
+     * hay `nombreDe()` y `fichaDe()`, que dicen cuál es el nombre y desde cuándo
+     * es suyo, no cómo llegó a serlo. Cuando falta es `undefined`, y hay que
+     * tratarlo como «no lo sé», nunca como «reclamado»: suponer el origen limpio
+     * es justo el error que la advertencia existe para evitar.
      */
-    origen: 'reclamado' | 'comprado' | 'recibido';
+    origen?: 'reclamado' | 'comprado' | 'recibido';
 }
 /** Una tarea del escrow. */
 export interface Task {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -45,6 +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"
+    "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",
+    "test:nombres": "tsx test/nombres.test.ts"
   }
 }