@chan30/agent-yarbox
v2.0.3
Published
Caja de accountability para agentes autónomos en Monad. Cada intención se compromete antes de ejecutar. Cada pago se verifica contra el mandato. Cada resultado queda registrado on-chain.
Maintainers
Readme
AgentYarbox
Caja de accountability para agentes autónomos en Monad.
Cada intención se compromete antes de ejecutar. Cada pago se verifica contra el mandato. Cada resultado queda registrado on-chain.
Índice
- Qué es
- Por qué es único
- Contratos desplegados en Monad Mainnet
- Funciones principales
- Flujo completo
- Explorador de Accountability
- SDK de JavaScript
- Tests
- Limitaciones conocidas
- Instalación y despliegue
- Integración con AETHEL-AUTAPON
- Casos de uso
- Licencia
Qué es
AgentYarbox es un contrato inteligente que registra compromisos de intención de agentes autónomos y verifica que los pagos reales coincidan con lo prometido. Se integra con PaymentGate (Mandate) y MandateRegistry para verificar pagos on-chain.
En términos simples: es un notario on-chain para agentes. El agente dice "voy a pagar X con el mandato Y", y AgentYarbox verifica que el pago real sea exactamente ese.
Por qué es único
| Otros proyectos | AgentYarbox |
|---|---|
| Registran intenciones, pero no verifican pagos | ✅ Verifica que el pago existe en PaymentGate |
| Verifican pagos, pero no registran intenciones | ✅ Registra la intención antes de pagar |
| No tienen tiquete de pago para auditorías | ✅ getReceipt devuelve el tiquete completo |
| No están integrados con Mandate | ✅ Integrado con PaymentGate y MandateRegistry |
La combinación de compromiso de intención + verificación on-chain + tiquete de pago no existe en otro proyecto de Monad.
Contratos desplegados en Monad Mainnet
| Contrato | Dirección | Verificación |
|---|---|---|
| AgentYarbox | 0x4D0D993e6FF19279dF0E69d9cd9cC946480973dC | ✅ exact_match |
| PaymentGate (Mandate) | 0xc8b31cc4E238905D96AAe66A06Ebc821b4E399aD | ✅ already_verified |
| MandateRegistry (Mandate) | 0x7695Cf7a86d6D08b5283a69c10f94b014D421649 | ✅ already_verified |
Funciones principales
| Función | Descripción |
|---|---|
| commitIntent | El agente registra su intención antes de pagar (hash de su lógica, condiciones, mandateId, maxAmount, erc8004AgentId). |
| settleIntent | El agente liquida con el paymentNonce real. El contrato verifica que el pago existe en PaymentGate, que el mandato es del agente y que no está expirado. Si algo falla, marca inconsistent. |
| getReceipt | Devuelve el tiquete de pago completo para auditorías (intentId, agente, mandateId, maxAmount, paymentNonce, resultHash, timestamp, settled, inconsistent). |
| getMaxAmount | Devuelve el maxAmount de una intención (para que AETHEL lo consulte antes de pagar). |
| isPaymentNonceUsed | Verifica si un paymentNonce ya fue usado (evita doble gasto). |
Flujo completo
- El agente commitea su intención en AgentYarbox.
- AETHEL (coordinador de enjambres) verifica el monto contra
maxAmountoff-chain. - AETHEL ejecuta el pago vía Mandate SDK.
- El agente liquida la intención con el
paymentNoncereal. - AgentYarbox verifica que el pago existe, que el mandato es del agente y que no expiró.
getReceiptdevuelve el tiquete de pago completo.
Explorador de Accountability
El explorador es una aplicación web que muestra, en tiempo real, todos los eventos del contrato AgentYarbox: intenciones commiteadas, pagos liquidados y casos inconsistentes. Cualquiera puede verificar on-chain lo que muestra.
Qué muestra
- Estadísticas: total de eventos, commiteadas, liquidadas, inconsistentes.
- Tabla de eventos: intent ID, estado, agente, monto, bloque, transacción.
- Tiquete de auditoría: al hacer clic en "Ver tiquete", se muestra el
getReceiptcompleto.
Cómo ejecutarlo
cd explorer
npm install
node indexer/index.mjs # indexa eventos
node server/api.mjs # inicia la API y el frontend en http://localhost:3001
---
## Score de Reputación y Tiers
El explorador web calcula automáticamente un **Score de Reputación** (0-100) para cada agente basándose en:
- **NFTs acumulados:** 10 puntos por cada pago exitoso.
- **Volumen total:** 1 punto por cada 0.01 MON pagado.
- **Penalización:** -20 puntos por cada intención inconsistente.
### Tiers
| Tier | Requisito |
|---|---|
| 🥉 Bronce | 1 a 10 NFTs |
| 🥈 Plata | 11 a 50 NFTs |
| 🥇 Oro | 51 a 200 NFTs |
| 💎 Diamante | +200 NFTs y 0 fallos |
El Score y el Tier se muestran en el explorador al buscar la dirección de un agente, junto con sus NFTs de reputación.
---
## Agent Mall (Centro Comercial de Agentes)
El ecosistema incluye un **Directorio de Servicios** (`ServiceDirectory`) donde cualquier empresa o agente puede registrar sus APIs/servicios y ponerles un precio.
### ¿Cómo funciona?
1. **Un proveedor registra un servicio** en el contrato `ServiceDirectory` (nombre, precio, endpoint, reputación mínima).
2. **Un agente entra al explorador web**, ve el servicio en la pestaña "El Mall", y hace clic en "Comprar".
3. **El backend ejecuta el pago** usando `@chan30/mandate-sdk` (commit → pay → settle).
4. **Se acuña un NFT de reputación** para el agente y se cobra la comisión del 0.5% para el dueño del Mall.
### Contrato del Mall
- **Dirección**: `0xCD9DdC0A0abB73a65F0AbF02Ec940F30661ca2AB`
- **Gobernanza**: Multisig (2 de 3 firmas)
- **Seguridad**: Reentrancy Guard, Pausable, Zero-Address Check, Límites de servicios.
### Reputación
El contrato consulta el `ReputationNFT` para verificar que el agente tiene los NFTs mínimos requeridos antes de dejarlo comprar. Un agente con Score alto (Oro/Diamante) tiene acceso a servicios VIP.