Guardrail Smart Accounts

Guardrail Smart Accounts Skill

Create and manage ERC-4337 smart accounts, policies, permissions, and enforcement for AI agents with on-chain spending guardrails.

Overview

The Guardrail Smart Accounts Skill enables agents and humans to create dedicated ERC-4337 smart accounts with built-in spending limits enforced on-chain. Every account is bound to a Guardrail policy at creation.

Guardrail never takes custody of funds — all enforcement occurs on-chain via deployed contracts.

This skill supports both:

• Programmatic agent execution
• Human-in-the-loop wallet workflows

It is designed as infrastructure: contract-level fees, policy-bound accounts, and non-custodial enforcement.

Security & Credential Model (Required)

This skill performs on-chain operations that require:

• JSON-RPC access
• Transaction signing

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

The skill supports the following secure signing models:

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.
• Keys must have strict limits (value caps, allowlists).
• Keys must be short-lived and rotated frequently.
• Never expose a long-lived owner EOA private key.

The Skill Must NOT

• Ask the user 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, use this skill in read-only mode until proper signing is established.

Required Runtime Configuration

These values must be provided via secure secret storage (not chat):

• GUARDRAIL_CHAIN_ID — Target chain identifier
• GUARDRAIL_RPC_URL — JSON-RPC endpoint for the target chain (treat as sensitive — hosted RPC URLs often contain API keys)
• GUARDRAIL_SIGNING_MODE — one of: external_signer, wallet_connector, session_key

Conditional Secrets (declared in manifest as optionalSecrets)

These are only required when using specific signing modes:

• GUARDRAIL_SIGNER_ENDPOINT — External signer service URL. Only required when GUARDRAIL_SIGNING_MODE is external_signer. Not needed for wallet_connector or session_key modes.
• GUARDRAIL_SIGNER_AUTH_TOKEN — Scoped, revocable authentication token for the external signer. Only required when GUARDRAIL_SIGNING_MODE is external_signer. Must be stored in secure secret storage, never in chat or logs.
• GUARDRAIL_DASHBOARD_API_KEY — API key for dashboard management UI interaction. Not required for direct contract usage.

Signer Token Rotation and Revocation

When using external_signer mode:

• GUARDRAIL_SIGNER_AUTH_TOKEN should be scoped to the minimum required permissions (allowlists, rate limits, spend caps).
• Tokens should be short-lived and rotated on a regular schedule.
• The external signer provider must support immediate token revocation.
• If a token is compromised, revoke it at the signer provider and rotate to a new token in secure secret storage.
• Never use long-lived owner EOA private keys as signer tokens.

Dashboard API Key Usage

GUARDRAIL_DASHBOARD_API_KEY provides access to the management dashboard API for registering agents, managing policies, and viewing audit logs. It does not grant signing or fund-transfer capability. Store it in secure secret storage and rotate periodically.

The runtime must validate the chain ID and reject unsupported networks by default.

Core Capabilities

1. Create Smart Account

Deploy a new smart account via the Guardrail factory. The account is bound to a PermissionEnforcer and controlled by a signer (EOA or generated keypair).

• Deterministic deployment via CREATE2 (salt-based)
• Owner recorded on-chain
• One-time creation fee: $10 USD equivalent in ETH
• Policy-bound by default

Factory Contract: AgentAccountFactory Function: createAccount(address owner, bytes32 agentId, bytes32 salt) payable returns (address)

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

// Deploy account (send fee as msg.value)
address account = factory.createAccount{value: fee}(ownerAddress, agentId, salt);

2. Fund Smart Account (Inbound Transfer)

Send ETH to the smart account address.

Inbound transfers are free.

// NOTE: walletClient must be backed by a secure signer integration.
// Do NOT provide raw private keys to the agent.

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

3. Withdraw from Smart Account (Outbound Transfer)

Execute a transfer from the smart account.

Outbound transfers are charged a 10 bps (0.10%) fee, capped at $100 USD equivalent per transaction.

Function: execute(address target, uint256 value, bytes data)

const data = encodeFunctionData({
  abi: agentSmartAccountABI,
  functionName: "execute",
  args: [destinationAddress, parseEther("1.0"), "0x"],
});

await walletClient.sendTransaction({
  to: smartAccountAddress,
  data,
});

Fee enforcement occurs inside GuardrailFeeManager.

4. Read State (Safe / Read-Only)

These functions do not require signing.

// Get account owner
const owner = await publicClient.readContract({
  address: smartAccountAddress,
  abi: agentSmartAccountABI,
  functionName: "owner",
});

// Get creation fee
const fee = await publicClient.readContract({
  address: factoryAddress,
  abi: agentAccountFactoryABI,
  functionName: "getCreationFee",
});

// Calculate transfer fee
const transferFee = await publicClient.readContract({
  address: feeManagerAddress,
  abi: guardrailFeeManagerABI,
  functionName: "calculateTransferFee",
  args: [parseEther("10.0")],
});

publicClient must be a read-only RPC client.

5. Policy Management

Create and manage policies that define what actions agents can perform, with constraints on value, volume, and scope.

Create Policy — POST /api/v1/policies

const response = await fetch(`${API_BASE_URL}/api/v1/policies`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    name: "DeFi Trading Policy",
    description: "Allow swaps and transfers with daily limits",
    definition: {
      actions: ["swap", "transfer"],
      assets: {
        tokens: ["0xA0b8...eB48", "0xdAC1...1eC7"],
        protocols: ["*"],
        chains: [1, 8453],
      },
      constraints: {
        maxValuePerTx: "1000000000000000000",
        maxDailyVolume: "10000000000000000000",
        maxWeeklyVolume: "50000000000000000000",
        maxTxCount: 100,
        requireApproval: false,
      },
      duration: {
        validFrom: "2025-01-01T00:00:00Z",
        validUntil: "2025-12-31T23:59:59Z",
      },
      conditions: [
        { field: "amount", operator: "lte", value: "5000000000000000000" },
      ],
    },
  }),
});
const policy = await response.json();

PolicyDefinition structure:

Activate Policy — POST /api/v1/policies/{id}/activate

Registers the policy on-chain via PolicyRegistry. Required before granting permissions.

await fetch(`${API_BASE_URL}/api/v1/policies/${policyId}/activate`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});

Update Policy — PUT /api/v1/policies/{id}

Draft policies update directly. Active policies create a new version.

await fetch(`${API_BASE_URL}/api/v1/policies/${policyId}`, {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    name: "Updated Policy Name",
    definition: {
      actions: ["swap", "transfer", "approve"],
      constraints: { maxValuePerTx: "2000000000000000000" },
    },
  }),
});

Revoke Policy — POST /api/v1/policies/{id}/revoke

Deactivates the policy on-chain. Active permissions using this policy will no longer validate.

Reactivate Policy — POST /api/v1/policies/{id}/reactivate

Re-registers a previously revoked policy on-chain.

List Policies — GET /api/v1/policies

Get Policy — GET /api/v1/policies/{id}

Delete Policy — DELETE /api/v1/policies/{id}

Only draft policies can be deleted. Active or revoked policies must be revoked first.

6. Permission Management

Permissions link an agent to a policy, authorizing specific actions for a defined period.

Grant Permission — POST /api/v1/permissions

The agent must be active and the policy must be activated before granting a permission.

const response = await fetch(`${API_BASE_URL}/api/v1/permissions`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    agent_id: "agent-uuid",
    policy_id: "policy-uuid",
    valid_from: "2025-01-01T00:00:00Z",
    valid_until: "2025-12-31T23:59:59Z",
  }),
});
const permission = await response.json();

Mint Permission — POST /api/v1/permissions/{id}/mint

Registers the permission on-chain via PolicyRegistry.grantPermission(). For smart account agents, syncs constraints to PermissionEnforcer. Returns onchain_token_id.

const minted = await fetch(
  `${API_BASE_URL}/api/v1/permissions/${permissionId}/mint`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${token}` },
  }
).then((r) => r.json());
// minted.onchain_token_id — on-chain token ID

Revoke Permission — DELETE /api/v1/permissions/{id}

Revokes the permission. Calls PolicyRegistry.revokePermission() on-chain if the permission was minted.

List Permissions — GET /api/v1/permissions

Supports query parameters: agent_id, policy_id.

const response = await fetch(
  `${API_BASE_URL}/api/v1/permissions?agent_id=${agentId}`,
  { headers: { Authorization: `Bearer ${token}` } }
);
const permissions = await response.json();

Get Permission — GET /api/v1/permissions/{id}

7. Action Validation

Validate whether an agent is permitted to perform an action. Runs for both advisory (EOA) and enforced (smart account) agents.

Validate Action — POST /api/v1/validate

const result = await fetch(`${API_BASE_URL}/api/v1/validate`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    agent_id: "agent-uuid",
    action: {
      type: "swap",
      token: "0xA0b8...eB48",
      protocol: "0x7a25...3e6F",
      amount: "500000000000000000",
      chain: 8453,
      to: "0xDef1...C0de",
    },
  }),
}).then((r) => r.json());
// result.allowed — boolean
// result.reason — explanation if denied
// result.permission_id — matching permission
// result.policy_id — matching policy
// result.constraints — active constraints
// result.request_id — audit trail reference

For enforced (smart account) agents, validation acts as a pre-flight check before on-chain execution. The on-chain PermissionEnforcer performs the final enforcement in validateUserOp.

Simulate Action — POST /api/v1/validate/simulate

Same input as validate, but returns current usage and remaining quota without recording a validation request.

const sim = await fetch(`${API_BASE_URL}/api/v1/validate/simulate`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    agent_id: "agent-uuid",
    action: { type: "transfer", amount: "1000000000000000000", chain: 1 },
  }),
}).then((r) => r.json());
// sim.would_allow — boolean
// sim.reason — explanation
// sim.matching_policy — policy ID if matched
// sim.current_usage — current period usage
// sim.remaining_quota — remaining allowance
// sim.recommendations — suggested adjustments

Batch Validate — POST /api/v1/validate/batch

Validate multiple actions in a single request.

8. Audit & Monitoring

Query the immutable audit trail for policy, permission, and validation events.

List Audit Logs — GET /api/v1/audit

Supports query parameters: event_type, agent_id, policy_id, start_date, end_date, limit, offset.

const logs = await fetch(
  `${API_BASE_URL}/api/v1/audit?event_type=policy.activated&start_date=2025-01-01T00:00:00Z`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

Event types: policy.created, policy.activated, policy.revoked, permission.created, permission.minted, permission.revoked, validation.request.

Export Audit Logs — GET /api/v1/audit/export

Supports format=json or format=csv, plus start_date and end_date parameters.

const exportUrl = `${API_BASE_URL}/api/v1/audit/export?format=csv&start_date=2025-01-01`;
// Download or redirect to this URL

Enforcement Model

The system supports two enforcement tiers based on agent wallet type:

Advisory (EOA Agents)

• Off-chain validation via /api/v1/validate logs actions and returns allow/deny decisions.
• The backend cannot prevent on-chain execution for EOA wallets.
• Use validation results for dashboards, alerts, and compliance monitoring.
• Violations are recorded in audit logs for review.

Enforced (Smart Account Agents)

• AgentSmartAccount.validateUserOp() calls PermissionEnforcer on-chain.
• Transactions that violate policy constraints revert before execution.
• The agent cannot bypass enforcement — it is built into the account's validation logic.
• Off-chain validation still runs for dashboards, simulation, and pre-flight checks.

Which Tier Applies?

Upgrading from EOA to smart account is one-way via POST /api/v1/agents/{id}/upgrade-to-smart-account.

Fee Structure

Account Creation Fee

• Amount: $10 USD equivalent in ETH
• When: One-time, at smart account deployment
• Enforced in: AgentAccountFactory contract
• Paid to: Fee collector address via GuardrailFeeManager

Transfer Fee (Outbound Only)

• Rate: 10 basis points (0.10%)
• Cap: $100 USD equivalent per transaction
• When: On every execute() or executeBatch() call with value > 0
• Not charged on:
  • Inbound deposits
  • Zero-value calls
  • ERC-20 transfers encoded in calldata

Smart Contract Addresses

Base Mainnet (Chain ID 8453)

Sepolia (Chain ID 11155111)

Dashboard

All API operations documented above are also available via the web dashboard at https://agentguardrail.xyz/, which provides a visual interface for managing agents, policies, permissions, and audit logs.

If using dashboard-generated signer keypairs or API keys:

• Store them in secure secret storage
• Never paste them into chat
• Prefer external signer or hardware-backed signing

Autonomy & Safety Guidance

Because this skill can move funds on-chain:

1. Start on Sepolia testnet.
2. Fund accounts with small amounts initially.
3. Use strict Guardrail policies.
4. Enable autonomous execution only with secure signing configured.
5. Apply rate limits and allowlists at the signer layer.

Privacy and Data Handling

• This skill does not store, log, or transmit private keys, seed phrases, or signer tokens.
• GUARDRAIL_RPC_URL may contain an embedded API key (common with hosted RPC providers). Treat it as sensitive.
• GUARDRAIL_SIGNER_AUTH_TOKEN grants signing capability when combined with the signer endpoint. It must be stored in secure secret storage and never exposed in logs, prompts, or chat.
• On-chain transactions are public by nature. The skill does not add any off-chain data collection beyond what the blockchain records.
• The skill does not access local files, browser storage, or environment variables beyond those declared in the manifest metadata.

Design Principles

1. Policy-Bound by Default — Every account is bound to a Guardrail policy at creation.
2. Agent and Human Neutral — Authority derives from ownership and policy, not caller identity.
3. Non-Custodial — Guardrail never holds funds.
4. Infrastructure First — Fees are enforced at the contract layer. The API cannot bypass protocol economics.
5. Least Privilege — Signing must use scoped, secure integrations.