CAPP-0001Draftv0.1.0 · Casper Network

Casper Agent Permission Protocol

An open standard for granting, scoping, and revoking AI agent authority over Casper Network accounts using the native add_associated_key protocol primitive.

← Back to overview·Jump to integration →

Abstract

This document specifies CAPP (Casper Agent Permission Protocol), a three-layer standard for enabling AI agents to act on-chain with bounded, auditable, and revocable authority. CAPP uses Casper's native associated key weight system as its enforcement primitive — making agent permissions a protocol-level guarantee rather than a smart contract invariant.

Unlike Ethereum-based approaches that rely on Gnosis Safe or similar multisig contracts, CAPP permissions are enforced by every Casper validator without deploying additional trust assumptions. A granted agent key cannot exceed its declared weight threshold regardless of what code it executes.

Motivation

AI agents operating in web3 today face an unsolved authorization problem. The three existing approaches all have critical flaws:

✗

Full key delegation — Agent holds the account's private key. Unrecoverable if compromised. No scope limits.

✗

Smart contract escrow — Introduces a contract layer with its own attack surface. Requires gas for every policy check.

✗

Platform-mediated custody — A centralized service decides what the agent can do. Censorable, opaque, single point of failure.

CAPP solves this by standardizing the use of Casper's built-in add_associated_key and remove_associated_key account-level operations, wrapping them in a typed permission scope and a public registry contract to create a composable, auditable standard any dApp can adopt.

Specification

Permission Scope

A PermissionScope defines the intended authority granted to an agent. Scopes are recorded in the PermissionLedger contract and surfaced by the SDK's verify() method.

PermissionScope (TypeScript)

field	type	description
agentPublicKey	string	ed25519 public key hex of the agent being authorized
maxTransferMotes	bigint	Maximum motes the agent may transfer in a single deploy
allowedContracts	string[]	Whitelist of contract hashes the agent may call. Empty = no contract calls
actionTypes	string[]	Permitted action types: 'transfer' \| 'call' \| 'deploy'
expiresInBlocks	number	Block height offset after which the permission expires automatically
keyWeight	number?	Weight assigned to the agent key (default: 1). Must be below deploy threshold

AgentRegistry Contract Interface

The registry is a Casper Wasm contract providing a permissionless public record of agent identities. Any account may register an agent; reads are free and public.

register_agent(public_key: PublicKey, capabilities: Vec<String>) → agent_hash: AccountHash

Registers an AI agent in the public registry. Emits AgentRegistered event.

get_agent(agent_hash: AccountHash) → Option<AgentRecord>

Reads an agent record from the registry. Returns None if not found.

list_agents(offset: u64, limit: u64) → Vec<AgentRecord>

Paginated list of all registered agents.

Key weight invariants

agent_key_weight < account.deploy_threshold
account.deploy_threshold ≥ 2          // always require human co-sign for sensitive ops
agent_key_weight = 1                  // recommended default
key_management_threshold ≥ 2         // prevent agent from adding its own keys

Violating these invariants allows the agent to sign arbitrary deploys unilaterally.

Security Considerations

Key weight must be strictly below deploy threshold

If the agent's key weight meets or exceeds the account's deploy threshold, it gains unilateral signing authority. Always set deploy_threshold ≥ agent_weight + 1.

Scope is advisory at SDK level, not enforced on-chain

CAPP v0.1.0 records scopes in the PermissionLedger contract but cannot prevent an agent from signing arbitrary deploys using its associated key. On-chain scope enforcement is planned for CAPP v0.2.0 via a pre-deploy hook contract.

Revocation is immediate at block level

remove_associated_key takes effect at the next block. Any deploy signed by the agent after revocation will be rejected by validators as the key no longer has account authority.

Do not share agent keys across accounts

An agent key added to multiple accounts can sign deploys on any of them. Treat agent keys as single-account credentials and rotate them per engagement.

Integration Guide

Five steps to add CAPP-based AI agent support to any Casper dApp.

Install the SDK

npm install casper-agent-permissions

Initialize with your network

import { CasperAgentPermissions } from 'casper-agent-permissions'

const capp = new CasperAgentPermissions({
  network: 'testnet',   // or 'mainnet'
  signer: walletPublicKey,
})

Grant a scoped mandate

const { deployHash } = await capp.grant({
  agentPublicKey: '02abc123...',
  scopes: {
    maxTransferMotes: 50_000_000_000n,
    allowedContracts: [marketplaceContractHash],
    expiresInBlocks: 1000,
    actionTypes: ['transfer', 'call'],
  },
})

Verify any agent action

const result = await capp.verify(deployHash)
// {
//   authorized: true,
//   agent: '02abc123...',
//   scope: { maxTransferMotes: 50000000000n, ... },
//   signedAt: 1783000000
// }

Revoke when done

await capp.revoke({
  agentPublicKey: '02abc123...',
})
// Agent key removed. Authority gone at next block.

CAPP-0001 · Draft · v0.1.0

← Overview Live Demo →