guardrail-smart-accounts

What this skill does

# AgentGuardrail — On-Chain Spending Guardrails for AI Agents

> **Give your AI agents a wallet they can't abuse.** AgentGuardrail deploys ERC-4337 smart accounts with policy-enforced spending limits. Agents cannot move funds beyond what you authorize — enforcement happens at the contract level, not just in software.

**Homepage:** https://agentguardrail.xyz

---

## Why AgentGuardrail?

AI agents need to move money. The problem is trust: how do you let an agent trade, bridge, or pay for compute without risking runaway spending, compromised keys, or unauthorized actions?

AgentGuardrail solves this with:

- **On-chain enforcement** — `AgentSmartAccount.validateUserOp()` calls `PermissionEnforcer` before any transaction executes. Violating transactions revert. There is no override.
- **Policy-bound accounts** — every smart account is deployed against a policy that defines allowed actions, tokens, protocols, chains, and spend limits.
- **Non-custodial** — AgentGuardrail never holds your funds. Enforcement is in the contracts you deploy.
- **Full audit trail** — every intent, validation, and on-chain event is logged with tx hash and block number.

---

## Overview

Every agent gets an ERC-4337 smart account deployed via `AgentAccountFactory`. The account's `validateUserOp()` enforces your policy through `PermissionEnforcer` before any transaction reaches the blockchain. If the action violates the policy — wrong token, wrong protocol, spend limit exceeded — the UserOperation reverts.

**Execution path:**
```
Agent builds UserOperation
  → AgentSmartAccount.validateUserOp()
    → PermissionEnforcer.validateAction()
      → Policy constraints checked on-chain
  → EntryPoint executes (only if all checks pass)
```

The AgentGuardrail API at **https://agentguardrail.xyz** provides:
- A management interface for creating policies and granting permissions
- Pre-flight validation for simulation and dashboards
- Aggregated audit logs with on-chain event indexing

Most enforcement operations can be done directly against the contracts without the API. The API is most useful for policy management, pre-flight simulation, and audit log queries.

---

## Security & Credential Model (Required)

This skill performs on-chain operations that require JSON-RPC access and transaction signing.

**Private keys must never be provided in chat and must never be stored in unconstrained agent memory.**

### Signing Modes

#### 1. External Signer (Recommended)

The agent prepares a transaction. The runtime forwards it to a secure signer service (HSM, MPC, hosted signer). The signer enforces scope, rate limits, and allowlists. The agent never sees raw private keys.

#### 2. Wallet Connector / User-Approved Signing

Transactions are prepared by the agent. A user wallet (browser, hardware wallet) prompts for approval. Keys remain in the wallet.

#### 3. Scoped Session Keys (Advanced)

Session keys must be policy-restricted, short-lived, and rotated frequently. Never use a long-lived owner EOA private key as a session key.

### The Skill Must NOT

- Ask users to paste private keys or seed phrases
- Store private keys in memory, logs, or prompts
- Access unrelated environment variables or local files
- Request cloud credentials or system-level secrets
- Persist secrets beyond runtime execution

If secure signing is not configured, operate in **read-only mode** until proper signing is established.

---

## Runtime Configuration

Required (via secure secret storage, not chat):

| Variable | Description |
|----------|-------------|
| `GUARDRAIL_CHAIN_ID` | Target chain ID (e.g., `8453` for Base, `11155111` for Sepolia) |
| `GUARDRAIL_RPC_URL` | JSON-RPC endpoint — treat as sensitive, often contains an API key |
| `GUARDRAIL_SIGNING_MODE` | One of: `external_signer`, `wallet_connector`, `session_key` |

Optional:

| Variable | Description |
|----------|-------------|
| `GUARDRAIL_API_URL` | AgentGuardrail API base. Defaults to `https://agentguardrail.xyz` |
| `GUARDRAIL_SIGNER_ENDPOINT` | External signer URL — required when `GUARDRAIL_SIGNING_MODE=external_signer` |
| `GUARDRAIL_SIGNER_AUTH_TOKEN` | Auth token for the external signer — sensitive, store securely |
| `GUARDRAIL_DASHBOARD_API_KEY` | API key for agentguardrail.xyz management API |

The API URL default in all code examples below is `https://agentguardrail.xyz`. Override with `GUARDRAIL_API_URL` if self-hosting.

---

## Smart Contract Addresses

### Base Mainnet (Chain ID 8453)

| Contract | Address |
|----------|---------|
| IdentityRegistry | `0xc1fa477f991C74Cc665E605fC74f0e2B795b5104` |
| PolicyRegistry | `0x92cd41e6a4aA13072CeBCda8830d48f269F058c4` |
| PermissionEnforcer | `0xbF63Fa97cfBba99647B410f205730d63d831061c` |
| PriceOracle | `0xf3c8c6BDc54C60EDaE6AE84Ef05B123597C355B3` |
| GuardrailFeeManager | `0xD1B7Bd65F2aB60ff84CdDF48f306a599b01d293A` |
| AgentAccountFactory | `0xCE621A324A8cb40FD424EB0D41286A97f6a6c91C` |
| EntryPoint (v0.6) | `0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789` |

### Sepolia Testnet (Chain ID 11155111)

| Contract | Address |
|----------|---------|
| IdentityRegistry | `0xc1fa477f991C74Cc665E605fC74f0e2B795b5104` |
| PolicyRegistry | `0x92cd41e6a4aA13072CeBCda8830d48f269F058c4` |
| PermissionEnforcer | `0x94991827135fbd0E681B3db51699e4988a7752f1` |
| PriceOracle | `0x052cDddba3C55A63F5e48F9e5bC6b70604Db93b8` |
| GuardrailFeeManager | `0x0f77fdD1AFCe0597339dD340E738CE3dC9A5CC12` |
| AgentAccountFactory | `0xA831229B58C05d5bA9ac109f3B29e268A0e5F41E` |
| EntryPoint (v0.6) | `0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789` |

> Start on Sepolia. Move to Base Mainnet when policies are validated.

---

## Core Capabilities

### 1. Deploy a Smart Account

Deploy a new ERC-4337 smart account via `AgentAccountFactory`. The account is bound to `PermissionEnforcer` at creation. Deployment is deterministic via CREATE2 — the same owner, agentId, and salt always produce the same address.

**One-time creation fee:** $10 USD equivalent in ETH.

**Direct contract call (recommended):**

```solidity
// Get required creation fee
uint256 fee = factory.getCreationFee();

// Deploy account (send fee as msg.value)
address account = factory.createAccount{value: fee}(
    ownerAddress,   // Controls the account
    agentId,        // bytes32 identifier for this agent
    salt            // bytes32 for CREATE2 determinism
);
```

**Via API:**

```javascript
const apiUrl = process.env.GUARDRAIL_API_URL ?? "https://agentguardrail.xyz";

const response = await fetch(`${apiUrl}/api/v1/agents/${agentId}/deploy-smart-account`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GUARDRAIL_DASHBOARD_API_KEY}` },
});
const { smart_account_address } = await response.json();
```

The API path is useful when using dashboard-generated bot signers (the dashboard generates the keypair and handles deployment in one step).

---

### 2. Fund a Smart Account

Send ETH directly to the smart account address. Inbound transfers are free — no fee, no contract call needed.

```javascript
await walletClient.sendTransaction({
  to: smartAccountAddress,
  value: parseEther("1.0"),
});
```

---

### 3. Execute from a Smart Account

Agent executes a transaction from its smart account. `validateUserOp()` enforces the policy before the transaction reaches the chain — no override exists.

**Outbound transfer fee:** 10 bps (0.10%), capped at $100 USD per transaction.

```javascript
// Build the UserOperation
const callData = encodeFunctionData({
  abi: agentSmartAccountABI,
  functionName: "execute",
  args: [destinationAddress, parseEther("1.0"), "0x"],
});

// Submit via ERC-4337 EntryPoint
// The EntryPoint calls validateUserOp → PermissionEnforcer before execution
```

Fee enforcement occurs inside `GuardrailFeeManager`. Fee is deducted from the transaction value automatically.

| Transfer Amount | Fee |
|----------------|-----|
| $1,000 | $1.00 |
| $10,000 | $10.00 |
| $100,000+ | $100.00 (cap) |

---

### 4. Read Contract State (No Signin