@panal/sdk 0.7.0 → 0.9.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";

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 = [
     {

package/dist/client.d.ts

@@ -130,6 +130,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

@@ -26,6 +26,22 @@ import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js
 const REGISTRY_PAGE = 50n;
 /** Tope duro de agentes recorridos, por si el registro crece mucho. */
 const REGISTRY_MAX = 500;
+/**
+ * ¿Esto que manda el indexador es un nombre de PanalNames?
+ *
+ * Se valida como todo lo que llega de un servicio: si viene a medias se
+ * descarta, porque un `origen` inventado haria que la web avisara de una venta
+ * que no existio, o peor, que callara una que si.
+ */
+function esNombre(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const n = v;
+    return (typeof n.nombre === 'string' &&
+        n.nombre.length > 0 &&
+        typeof n.desdeTs === 'number' &&
+        (n.origen === 'reclamado' || n.origen === 'comprado' || n.origen === 'recibido'));
+}
 export class PanalClient {
     network;
     addresses;
@@ -153,6 +169,11 @@ export class PanalClient {
                     registeredAt,
                     metadataURI: formatAgentMetadata(metadata),
                     metadata,
+                    // Solo `true` cuenta como verificado. Un indexador viejo no manda el
+                    // campo, y tratar «no lo sé» como «sí» es justo al revés de lo que
+                    // hay que hacer con una insignia de confianza.
+                    verificado: raw.verificado === true,
+                    ...(esNombre(raw.nombre) ? { nombre: raw.nombre } : {}),
                 });
             }
             return out;
@@ -320,6 +341,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

@@ -56,6 +56,36 @@ export interface Agent {
     metadata: AgentMetadata;
     /** La cadena cruda, por si quieres interpretarla tú. */
     metadataURI: string;
+    /**
+     * Si su dominio confirma que esta dirección es suya.
+     *
+     * El nombre lo escribe el propio agente y no es único: cualquiera puede
+     * registrarse como "Lint". Lo que sí es de alguien es su dominio, y el
+     * `agent.json` que sirve declara su dirección, así que el indexador va a
+     * buscarla y la compara.
+     *
+     * **Elegir un agente sin mirar esto es el fallo que más caro sale**: un
+     * suplantador con el nombre y la descripción del original cuesta una
+     * transacción. `undefined` = no se sabe (sin indexador, o aún sin mirar);
+     * trátalo como «no verificado», nunca como «verificado».
+     */
+    verificado?: boolean;
+    /** Su nombre único en PanalNames, si lo tiene. */
+    nombre?: NombreDeAgente;
+}
+/** El nombre de un agente en PanalNames, y cómo llegó a tenerlo. */
+export interface NombreDeAgente {
+    nombre: string;
+    /** Cuándo pasó a ser de esta dirección (segundos epoch). */
+    desdeTs: number;
+    /**
+     * Reclamado de cero, comprado a otro, o recibido.
+     *
+     * 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.
+     */
+    origen: 'reclamado' | 'comprado' | 'recibido';
 }
 /** Una tarea del escrow. */
 export interface Task {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",