Saltar al contenido principal

Capabilities

¿Qué Son las Capabilities?​

Las capabilities son permisos detallados, con vencimiento y medidos adjuntos a una billetera. Son la compuerta principal de lo que una billetera de agente (o cualquier billetera) puede hacer en el protocolo.

Una billetera sin ninguna capability puede realizar cualquier acción que sus auth groups permitan. Una billetera con capabilities explícitas está restringida únicamente a esas acciones; las capabilities actúan como una lista blanca que prevalece sobre los permisos más amplios de los auth groups.

Esto hace de las capabilities la herramienta correcta para acotar agentes autónomos: se asigna el conjunto mínimo de acciones que el agente necesita, delimitado por dirección de recurso, conteo de invocaciones y vencimiento por altura de bloque, y el protocolo hace cumplir ese alcance en cada transaction.

Estructura de una Capability​

Capability {
    Action   string           // The action type (e.g., "contract:invoke", "token:transfer")
    Resource string           // The target resource address, or "*" for any
    Limits   CapabilityLimits // Optional: maxAmount, maxInvocations
    NotAfter uint64           // Block height after which the capability expires (0 = no expiry)
}

CapabilityLimits {
    MaxAmount      *big.Int // Maximum token amount per invocation (for token actions)
    MaxInvocations uint64   // Maximum number of times this capability can be used
}

Tipos de Acción​

AcciónAlcance
contract:invokeLlamar a una función de un smart contract
token:transferTransferir tokens fungibles
token:mintAcuñar nuevo suministro de tokens
token:burnQuemar suministro de tokens
nft:transferTransferir un NFT
data:submitEnviar transactions de datos arbitrarios
wallet:createCrear billeteras hijas
*Comodín: todas las acciones (usar con precaución)

El campo Resource restringe el alcance a una dirección específica de contrato, token o billetera. Se recomienda usar "*" solo cuando la acción deba aplicarse de forma global; esto es un antipatrón para las billeteras de los agentes (ver Anti-Patterns).

Cómo Se Aplican las Capabilities​

Las verificaciones de capabilities se ejecutan en el momento de ejecución de la transaction (procesamiento del bloque), no en el momento del envío:

Transaction submitted to pool
    ↓
Authorization pre-screen (ancestry, blacklists)
    ↓ [capabilities NOT checked here]
Transaction enters pending pool
    ↓
Block proposed, transactions ordered
    ↓
Block execution: for each transaction:
    1. Is the sender wallet capability-restricted?
    2. Does the transaction action match any held capability?
    3. Is the capability's resource "*" or matches the target?
    4. Is current block height ≤ capability.NotAfter?
    5. If MaxInvocations set: has invocation count been exceeded?
    6. If MaxAmount set: does the transaction amount exceed the limit?
    → All checks pass → execute
    → Any check fails → reject transaction

Importante: dado que el vencimiento de una capability se verifica en el momento de la ejecución, una transaction enviada antes del bloque de vencimiento aún puede fallar si no se incluye en un bloque hasta después del vencimiento. Se recomienda diseñar los valores NotAfter de las capabilities con un margen suficiente.

Adjuntar Capabilities a una Billetera​

Las capabilities se adjuntan mediante ALTER_WALLET:

{
    "walletAddress": "<agent-wallet-address>",
    "capabilities": [
        {
            "action": "contract:invoke",
            "resource": "5c83c81199820b91cf759a69f5ede919ea0568be34ec6e26ac8adf4173cbf01048451014b48cc4557474fde91f589c95bf4dd34349d96a83d7f0e15a7b664b83",
            "limits": {
                "maxInvocations": 1000
            },
            "notAfter": 200000
        }
    ]
}

Restricción de Herencia​

Al crear una billetera hija, las capabilities de la hija deben ser un subconjunto estricto de las capabilities de la billetera padre. Una billetera padre no puede otorgar a una hija un permiso que la propia billetera padre no posee. Esto evita la escalada de privilegios a través de la jerarquía.

Patrones de Capabilities para Billeteras de los Agentes​

Agente Mínimo (Un Solo Contrato, Acotado)​

[
    {
        "action": "contract:invoke",
        "resource": "<specific-contract-address>",
        "limits": { "maxInvocations": 500 },
        "notAfter": 50000
    }
]

Este agente puede llamar exactamente a un contrato, como máximo 500 veces, antes del bloque 50000. Después del bloque 50000, todas las transactions se rechazan aunque queden invocaciones.

Agente que Gasta Tokens (Monto Acotado)​

[
    {
        "action": "token:transfer",
        "resource": "<specific-token-address>",
        "limits": { "maxAmount": "1000000" },
        "notAfter": 100000
    }
]

Este agente puede transferir tokens de un contrato de token específico, pero el monto acumulado transferido no puede superar 1,000,000 de unidades.

Agente Multiacción (Investigación + Datos)​

[
    {
        "action": "contract:invoke",
        "resource": "<research-contract>",
        "limits": { "maxInvocations": 200 },
        "notAfter": 75000
    },
    {
        "action": "data:submit",
        "resource": "*",
        "limits": { "maxInvocations": 500 },
        "notAfter": 75000
    }
]

Este agente puede invocar un contrato y enviar datos arbitrarios, ambos acotados por conteo de invocaciones y vencimiento por altura de bloque.

Renovación de Capabilities​

Cuando una capability se acerca a su bloque notAfter o a su límite maxInvocations, la billetera padre envía un nuevo ALTER_WALLET para reemplazar el conjunto de capabilities. Este es el mecanismo explícito de renovación; no existe renovación automática.

Capabilities frente a Auth Groups​

DimensiónAuth GroupsCapabilities
AlcanceCRUD administrativo a nivel de billeteraA nivel de acción, específico por recurso
Quién los usaTanto billeteras humanas como de agentesPrincipalmente billeteras de los agentes
VencimientoSin vencimientoVencimiento por altura de bloque
MediciónSin mediciónConteo de invocaciones, límites de monto
Efecto cuando están presentesAgrega permisosRestringe a la lista blanca únicamente

Regla: si una billetera tiene alguna capability asignada, solo puede realizar las acciones cubiertas por esas capabilities. Los auth groups dejan de gobernar su alcance de acciones; solo lo hacen las capabilities. Se recomienda usar los auth groups para el acceso administrativo y las capabilities para el alcance operativo.

Monitoreo del Estado de las Capabilities​

El nodo expone endpoints para consultar el estado de las capabilities de una billetera:

GET /chains/{chainId}/wallets/{address}/capabilities
→ Returns current capabilities, remaining invocations, expiry status

GET /chains/{chainId}/wallets/{address}/capabilities/status
→ Returns per-capability health: active | expiring_soon | exhausted | expired

Se pueden usar estos endpoints para monitorear las billeteras de los agentes y renovar las capabilities antes de que venzan.

Para los errores comunes con las capabilities (sobreacotamiento, verificación en un solo nodo, proliferación de capabilities), ver Anti-Patterns.