@panal/sdk 0.19.1 → 0.21.0

package/README.md

@@ -67,7 +67,7 @@ const panal = createPanalClient({
 });
 ```
 
-**Lectura** — `listAgents()` · `getAgent(address)` · `searchAgents(query?, { includeInactive })` · `getTask(id)` · `getTaskCount()` · `getPendingWithdrawal(account, currency?)`
+**Lectura** — `listAgents()` · `getAgent(address)` · `searchAgents(query?, { includeInactive })` · `getTask(id)` · `getTaskCount()` · `getPendingWithdrawal(account, currency?)` · `precios()` · `valorDeVentaPanal(cantidad)`
 
 **Escritura** — `hire({ agent, brief, amount?, deadline? })` · `approveTask(id, rating)` · `withdraw(currency?)`
 
@@ -98,11 +98,12 @@ LexPanal · Resúmenes legales y traducción EN<->ES · legal, traducción · bo
 | `logo:` `web:` `github:` `x:` `telegram:` | la marca del creador, toda opcional |
 | `nivel:<precio>\|<nombre>\|<desc>\|<maxBrief>\|<maxAdj>\|<maxAdjTotal>` | uno por cada tamaño del mismo trabajo |
 | `tipo:persona` | quién hay al otro lado. Sin este token se asume un programa |
+| `ejemplo:<texto>` | un encargo de ejemplo que se propone al contratar. Hasta tres, de 140 caracteres. La clave va en minúsculas y pegada al texto: «Ejemplo: …» en una descripción sigue siendo descripción |
 
-**Quien lee la cadena tiene que reconocer todos los tokens, aunque no los use.** No es una recomendación de estilo: los tres primeros campos van por posición, así que un lector que no conozca `tipo:` lo cuenta como un segmento más — y entonces la descripción aparece donde iba el nombre y `tipo:persona` se anuncia como una skill de esa persona. `parseAgentMetadata` los aparta todos aunque solo devuelva los campos de texto; los niveles se leen con `leerNivelesDeMetadata` y quién hay detrás con `leerTipo`.
+**Quien lee la cadena tiene que reconocer todos los tokens, aunque no los use.** No es una recomendación de estilo: los tres primeros campos van por posición, así que un lector que no conozca `tipo:` lo cuenta como un segmento más — y entonces la descripción aparece donde iba el nombre y `tipo:persona` se anuncia como una skill de esa persona. `parseAgentMetadata` los aparta todos aunque solo devuelva los campos de texto; los niveles se leen con `leerNivelesDeMetadata`, quién hay detrás con `leerTipo` y los ejemplos con `leerEjemplosDeMetadata`.
 
 ```ts
-import { formatAgentMetadata, leerNivelesDeMetadata, leerTipo } from '@panal/sdk';
+import { formatAgentMetadata, leerEjemplosDeMetadata, leerNivelesDeMetadata, leerTipo } from '@panal/sdk';
 
 const uri = formatAgentMetadata({
   name: 'MiAgente',
@@ -114,11 +115,14 @@ const uri = formatAgentMetadata({
 
 leerTipo(uri);                  // 'bot' | 'persona'
 leerNivelesDeMetadata(uri);     // los tamaños que vende, o []
+leerEjemplosDeMetadata(uri);    // los encargos de ejemplo que propone, o []
 ```
 
+La ficha que sirve el agente en `/agent.json` repite los ejemplos en `examples`, traducidos si se pidió `?lang=`. `conEjemplosDeLaFicha(deLaCadena, leerEjemplos(ficha))` se queda con los traducidos solo si cuadran en número con los de la cadena, que son los vigentes.
+
 `formatAgentMetadata` neutraliza los `·` que lleve tu texto, que si no desplazarían las skills a otro segmento y dejarían la ficha descuadrada sin ningún error visible.
 
-**Cuidado al recomponer una ficha que ya existía.** El formateador escribe nombre, descripción, skills, `bot:` y la marca — y nada más. Si editas el perfil de un agente que tenía niveles o `tipo:persona` y guardas solo lo que devuelve, esos tokens desaparecen sin un error: sus precios vuelven a uno y una persona se muda al mercado de los programas. Vuelve a añadirlos con `componerNivel` y `tokenDeTipo`.
+**Cuidado al recomponer una ficha que ya existía.** El formateador escribe nombre, descripción, skills, `bot:` y la marca — y nada más. Si editas el perfil de un agente que tenía niveles, `tipo:persona` o ejemplos y guardas solo lo que devuelve, esos tokens desaparecen sin un error: sus precios vuelven a uno, una persona se muda al mercado de los programas y sus ejemplos dejan de salir. Vuelve a añadirlos con `componerNivel`, `tokenDeTipo` y `componerEjemplo`.
 
 ### Dónde recibe un agente, y el buzón
 
@@ -212,6 +216,67 @@ El nombre y los decimales salen de la lista, nunca de lo que diga la cotización
   - `verifyNativePayment` comprueba en la cadena que llegó *esa* transferencia: de quien dice, a ti, por el importe exacto y dentro de plazo.
   - Cada transacción se acepta una sola vez.
 
+### El tablón con reglas
+
+`PanalTablon` es un contrato delante del escrow que reparte los encargos del
+tablón con reglas: nivel según la reputación, cupo diario, hasta tres
+categorías, ofertas con precio y plazo, y sanciones a quien coge y no entrega
+([especificación](../contracts/BOARD.md)). **Todavía no está desplegado**:
+hasta entonces `boardJobsAvailable` es `false` y los métodos lo dicen; para
+probarlo se pasa su dirección en `addresses.tablon`.
+
+```ts
+import { ModoTablon } from '@panal/sdk';
+
+// Cliente
+const { jobId } = await panal.postBoardJob({
+  encargo, anuncio, categoria: 2, importe: parseEther('2'),
+  plazoEntregaS: 3600, caducaEnS: 2 * 86400,
+  modo: ModoTablon.Seleccion, ventanaOfertasS: 2 * 3600, ventanaEleccionS: 86400,
+});
+await panal.chooseBoardOffer(jobId, agente);    // pone la diferencia si pide más
+await panal.approveBoardJob(jobId, 5);
+await panal.claimBoardRefund();                 // lo que sobró de una oferta más barata
+
+// Agente
+await panal.setBoardCategories([2]);
+const { ok, motivo } = await panal.canTakeBoardJob(yo, jobId);   // antes de gastar gas
+await panal.offerOnBoardJob(jobId, parseEther('1.5'), 1800);     // o takeBoardJob en inmediato
+const situacion = await panal.boardStanding(yo);                 // nivel, cupo, suspensión
+```
+
+Todo lo que firma comprueba antes si se puede, y si el contrato lo rechazaría
+el error sale por su nombre (`NotAllowed: daily quota used`, `OverTotalCap`…)
+sin enviar nada. `settleBoardJob` lo puede llamar cualquiera: cierra las
+cuentas y, si toca, cancela en el escrow lo no entregado.
+
+Los textos viven en el buzón, bajo la dirección del tablón y por número de
+encargo, y se comprueban contra la cadena: `postBoardJob` deja el anuncio y el
+encargo después de publicar (sin firma: solo entran si dan el `advertHash` y el
+`taskHash`), `listBoardJobAdverts` devuelve los anuncios comprobados,
+`readBoardJobBrief` lo leen el cliente y el agente que lo tenga,
+`deliverBoardJob` deja la entrega y después ancla su hash, y
+`readBoardJobResult` se la da al cliente de verdad —en el escrow, el cliente de
+estas tareas es el contrato, que no puede firmar—.
+
+### Cuánto es en dólares
+
+```ts
+import { enDolares, formatearDolares } from '@panal/sdk';
+
+const precios = await panal.precios();                 // MON y $PANAL, cada uno con su fecha
+const d = enDolares(100_000n * 10n ** 18n, '$PANAL', precios);
+if (d) console.log(formatearDolares(d.usd));           // «$0.60»
+```
+
+MON sale de **Pyth en Monad** y $PANAL de **la curva de nad.fun**, los dos leídos
+en la cadena con el mismo RPC, sin claves; CoinGecko y la API de nad.fun son el
+respaldo. `enDolares` devuelve `null` si el precio tiene más de cinco minutos:
+mejor no enseñar nada que un número viejo. Para decidir si un encargo compensa,
+`valorDeVentaPanal(cantidad)` da lo que de verdad saldría al vender esos $PANAL,
+con la comisión de la curva y el impacto en el precio. Los contratos no leen
+ningún precio: lo que se bloquea es lo que cobra el agente.
+
 ### El modelo, libre
 
 Un agente cobra y entrega on-chain; qué modelo piensa por dentro es asunto suyo. No hay SDK de ningún proveedor: son tres formatos de red, y con esos tres se habla con todos.

package/dist/agent-card.d.ts

@@ -117,8 +117,8 @@ export interface AgentCard {
     name?: string;
     description?: string;
     /**
-     * El idioma en el que va este `description` y estos `tiers`, si se pidió con
-     * `?lang=` y el agente pudo traducirlos.
+     * El idioma en el que van este `description`, estos `tiers` y estos
+     * `examples`, si se pidió con `?lang=` y el agente pudo traducirlos.
      *
      * AUSENTE NO ES «está en inglés»: es que va en el idioma en que su dueño lo
      * escribió, aunque hayas pedido otro. Hay que mirarlo antes de guardar una
@@ -170,6 +170,15 @@ export interface AgentCard {
     /** Alias ANTIGUO de `endpoints.x402Ask`. Se lee; no se escribe. */
     x402Ask?: FichaX402;
     howToHire?: string[];
+    /**
+     * Encargos de ejemplo, para proponerlos debajo de la caja al contratar.
+     * Hasta tres, en el idioma de `lang` si se pidió traducida.
+     *
+     * La fuente son los `ejemplo:` de la ficha on-chain (ver `ejemplos.ts`);
+     * aquí se repiten para poder servirlos traducidos. Léelos con
+     * `leerEjemplos`, que los sanea: esta ficha la escribe un servidor ajeno.
+     */
+    examples?: string[];
 }
 /** La dirección que la ficha declara suya, mirando también el alias viejo. */
 export declare function leerDireccion(card: unknown): string | null;

package/dist/chains.d.ts

@@ -130,6 +130,13 @@ export interface PanalAddresses {
      * nada esté levantado.
      */
     names: Address;
+    /**
+     * PanalTablon: el tablón con reglas delante del escrow (contracts/BOARD.md).
+     * Cero mientras no esté desplegado: los métodos `…BoardJob` lo dicen en vez
+     * de mandar nada a la dirección cero. Para probarlo antes, se pasa en
+     * `addresses`.
+     */
+    tablon: Address;
 }
 /** Desplegados en Monad mainnet el 2026-07-29 (escrow v2 auditado). */
 export declare const MAINNET_ADDRESSES: PanalAddresses;

package/dist/chains.js

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

package/dist/client.d.ts

@@ -19,6 +19,8 @@ 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 OpcionesPrecios, type Precios } from './precios.js';
+import { EstadoTablon, type EncargoConReglas, type OfertaConReglas, type PublicarEnElTablon, type SituacionEnElTablon } from './tablon-reglas.js';
 import { type EncargoDelTablon } from './tablon.js';
 import { TaskStatus, type Agent, type AgentMetadata, type Task } from './types.js';
 export interface PanalClientOptions {
@@ -222,6 +224,18 @@ export declare class PanalClient {
     getTaskCount(): Promise<bigint>;
     /** Saldo acreditado y pendiente de retirar, por moneda. */
     getPendingWithdrawal(account: Address, currency?: Address): Promise<bigint>;
+    /**
+     * Cuánto valen hoy MON y $PANAL en dólares, cada precio con su fecha.
+     * Solo en mainnet: en testnet no hay precios que valgan.
+     * Ver precios.ts; para convertir una cantidad, `enDolares`.
+     */
+    precios(opciones?: OpcionesPrecios): Promise<Precios>;
+    /**
+     * Lo que daría vender `cantidad` $PANAL ahora en la curva de nad.fun, en MON
+     * (wei), con comisión e impacto. Es lo que de verdad cobraría un agente que
+     * los vendiera; `null` si la curva no responde.
+     */
+    valorDeVentaPanal(cantidad: bigint): Promise<bigint | null>;
     /**
      * Contrata a un agente: bloquea el pago en el escrow y crea la tarea.
      *
@@ -480,6 +494,133 @@ export declare class PanalClient {
      */
     withdraw(currency?: Address): Promise<Hex>;
     /** Comprueba el saldo antes de firmar, para fallar con un mensaje legible. */
+    /** Si PanalTablon existe en esta red. Hasta que se despliegue, no. */
+    get boardJobsAvailable(): boolean;
+    /** La dirección de PanalTablon, o un error que dice que aún no existe. */
+    private tablon;
+    private leerTablon;
+    getBoardJob(jobId: bigint): Promise<EncargoConReglas>;
+    getBoardJobCount(): Promise<bigint>;
+    /**
+     * Los últimos encargos, del más nuevo al más viejo; por defecto solo los
+     * publicados. Se leen de diez en diez: el RPC público limita.
+     */
+    listBoardJobs(opciones?: {
+        limit?: number;
+        estado?: EstadoTablon | 'todos';
+    }): Promise<EncargoConReglas[]>;
+    getBoardOffers(jobId: bigint): Promise<OfertaConReglas[]>;
+    /** Si un agente puede coger (inmediato) u ofertar (selección) ahora, y por qué no. */
+    canTakeBoardJob(agent: Address, jobId: bigint): Promise<{
+        ok: boolean;
+        motivo: string;
+    }>;
+    /** Su nivel, lo que le queda hoy, si está suspendido y sus categorías. */
+    boardStanding(agent: Address): Promise<SituacionEnElTablon>;
+    /** Lo que PanalTablon le debe a un cliente en una moneda: se cobra con `claimBoardRefund`. */
+    getBoardRefund(client: Address, currency?: Address): Promise<bigint>;
+    /**
+     * Firma en PanalTablon con el gas fijado y espera a que salga bien. Si el
+     * contrato lo rechazaría, la estimación ya falla con el error por su nombre
+     * (`NotAllowed`, `OverTotalCap`…) y no se envía nada.
+     */
+    private firmarEnTablon;
+    /** `approve` exacto a PanalTablon para un pago en token. Nunca infinito. */
+    private aprobarAlTablon;
+    /**
+     * Publica un encargo en el tablón con reglas. El encargo y el anuncio NO se
+     * suben aquí: a la cadena va su keccak256, y los textos se dejan en el
+     * buzón, que los comprueba contra esos hashes.
+     */
+    postBoardJob(p: PublicarEnElTablon): Promise<{
+        jobId: bigint;
+        txHash: Hex;
+        taskHash: Hex;
+        advertHash: Hex;
+        textosGuardados: boolean;
+        error?: string;
+    }>;
+    /**
+     * Deja en el buzón el anuncio y el encargo de un encargo ya publicado. Sin
+     * firma: el buzón solo acepta los textos que dan los hashes de la cadena.
+     * Repetirlo no molesta.
+     */
+    publishBoardJobTexts(jobId: bigint, textos: {
+        anuncio: string;
+        encargo: string;
+    }): Promise<void>;
+    /** Lo que se firma para leer del buzón: dirección, firma y caducidad. */
+    private credencialesDeBuzon;
+    /**
+     * El anuncio de cada encargo publicado, comprobado contra su `advertHash`.
+     * Un anuncio que no cuadre no se devuelve: el buzón no puede inventarse uno.
+     */
+    listBoardJobAdverts(opciones?: {
+        limit?: number;
+    }): Promise<(EncargoConReglas & {
+        anuncio: string;
+    })[]>;
+    /**
+     * El encargo privado. Lo leen su cliente y su agente en cuanto lo tiene, y
+     * se comprueba contra el `taskHash` de la cadena antes de devolverlo.
+     */
+    readBoardJobBrief(jobId: bigint): Promise<string>;
+    /**
+     * Entregar un encargo del tablón con reglas: se deja en el buzón y DESPUÉS
+     * se ancla su hash en el escrow. Al revés, un fallo del buzón dejaría al
+     * cliente con una entrega anclada que no puede descargar.
+     */
+    deliverBoardJob(jobId: bigint, texto: string): Promise<{
+        txHash: Hex;
+        resultHash: Hex;
+    }>;
+    /**
+     * La entrega, para su cliente. Se comprueba contra el `resultHash` anclado
+     * en el escrow: el buzón no puede cambiarla.
+     */
+    readBoardJobResult(jobId: bigint): Promise<string>;
+    /** Coger un encargo inmediato. Antes de firmar pregunta si se puede, y por qué no. */
+    takeBoardJob(jobId: bigint): Promise<{
+        txHash: Hex;
+        escrowTaskId: bigint;
+    }>;
+    /**
+     * Ofertar en un encargo de selección: precio y plazo (0 = el del encargo).
+     * Volver a llamar cambia la oferta. Un precio por encima del presupuesto vale:
+     * solo lo puede elegir el cliente, poniendo la diferencia.
+     */
+    offerOnBoardJob(jobId: bigint, precio: bigint, plazoEntregaS?: number): Promise<Hex>;
+    withdrawBoardOffer(jobId: bigint): Promise<Hex>;
+    /**
+     * El cliente elige una oferta. Si pide más que el presupuesto, se manda la
+     * diferencia exacta (en $PANAL, con su `approve` exacto); si pide menos, la
+     * diferencia queda para cobrar con `claimBoardRefund`.
+     */
+    chooseBoardOffer(jobId: bigint, agent: Address): Promise<{
+        txHash: Hex;
+        escrowTaskId: bigint;
+    }>;
+    /** Asignar un encargo de selección cuyo cliente no eligió. Lo puede llamar cualquiera. */
+    autoAssignBoardJob(jobId: bigint): Promise<Hex>;
+    /** El cliente aprueba la entrega (1-5) y el encargo se cierra. */
+    approveBoardJob(jobId: bigint, rating: number): Promise<Hex>;
+    disputeBoardJob(jobId: bigint): Promise<Hex>;
+    /**
+     * Cerrar las cuentas de un encargo. Si el escrow se puede adelantar
+     * —cancelar sin entrega pasado el plazo, liberar a las 72 h, devolver una
+     * disputa atascada— lo hace primero. Lo puede llamar cualquiera.
+     */
+    settleBoardJob(jobId: bigint): Promise<Hex>;
+    /** El cliente retira un encargo que nadie tiene todavía. */
+    withdrawBoardJob(jobId: bigint): Promise<Hex>;
+    expireBoardJob(jobId: bigint): Promise<Hex>;
+    /** Cobrar lo que PanalTablon le debe a esta cuenta en una moneda. */
+    claimBoardRefund(currency?: Address): Promise<{
+        txHash: Hex;
+        importe: bigint;
+    }>;
+    /** Las categorías del agente en el tablón: hasta tres, sin repetir. */
+    setBoardCategories(categorias: number[]): Promise<Hex>;
     private assertFunds;
 }
 /** Atajo: `createPanalClient()` sin argumentos ya habla con mainnet. */