EVM Guard Quickstart

Overview

AgentChain SDK v2 introduces the EVM guard flow — a pre-transaction policy check that returns a signed receipt before any value moves on-chain.

Install

npm install @humbleaf/agentchain-sdk viem

Create a client

import { AgentChain } from '@humbleaf/agentchain-sdk';

const ac = new AgentChain({
  apiKey: process.env.AGENTCHAIN_API_KEY,
});

Create a policy

Before guarding any transaction, create a policy for your chain and contract:

await ac.policies.create({
  policyId: 'pol_uniswap_safe',
  chainId: 84532, // Base Sepolia
  label: 'Safe Uniswap swaps',
  rules: {
    allowedTargets: ['0x2626664c2603336E57B271c5C0b26F421741e481'],
    allowedSelectors: ['0x414bf389'], // exactInputSingle
    maxValueWei: '1000000000000000000',   // 1 ETH max
    maxSlippageBps: 100,                  // 1%
    dailyCapWei: '5000000000000000000',   // 5 ETH / day
    approvalThresholdWei: '500000000000000000', // > 0.5 ETH → approval
  },
});

Guard and execute

import { createWalletClient, http, encodeFunctionData } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { baseSepolia } from 'viem/chains';
import {
  AgentChainEvmPolicyDenied,
  AgentChainEvmApprovalRequired,
  AgentChainExpiredDecision,
} from '@humbleaf/agentchain-sdk';

const wallet = createWalletClient({
  account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
  chain: baseSepolia,
  transport: http(),
});

try {
  const { receipt, transactionHash } = await ac.evm.guardAndExecute(wallet, {
    chainId: 84532,
    from: wallet.account.address,
    to: '0x2626664c2603336E57B271c5C0b26F421741e481',
    data: encodeFunctionData({ abi, functionName: 'exactInputSingle', args: [params] }),
    value: '0',
    policyId: 'pol_uniswap_safe',
  });

  console.log('✓ Transaction sent:', transactionHash);
  console.log('  Receipt:', receipt.receiptId, '| state:', receipt.state);
} catch (err) {
  if (err instanceof AgentChainEvmPolicyDenied) {
    console.error('✗ Denied:', err.reasonCodes);
  } else if (err instanceof AgentChainEvmApprovalRequired) {
    console.log('⏳ Needs approval. approvalId:', err.approvalId);
  } else if (err instanceof AgentChainExpiredDecision) {
    console.warn('⟳ Decision expired — retry guardAndExecute');
  } else {
    throw err;
  }
}

Guard only (no execution)

If you want the policy decision without executing, use guardTransaction:

const receipt = await ac.evm.guardTransaction({
  chainId: 84532,
  from: '0x...',
  to: '0x...',
  data: '0x...',
  value: '0',
  policyId: 'pol_uniswap_safe',
});

console.log(receipt.decision); // 'allow' | 'deny' | 'approval_required'
console.log(receipt.reasonCodes); // e.g. ['VALUE_EXCEEDED']

decisionExpiresAt — The gateway sets this to issuedAt + 300s. If execution takes more than 5 minutes, call guardTransaction again for a fresh receipt. guardAndExecute throws AgentChainExpiredDecision automatically if the window has closed.

Verify a receipt locally

No network call required:

const valid = ac.receipts.verify(
  receipt.receiptHash,
  receipt.signature,
  receipt.signerAddress,
);
console.log('signature valid:', valid);

Verify on-chain (SignerAnchor)

For trustless verification — confirm the signer is authorized at the contract level:

const ac = new AgentChain({
  apiKey: process.env.AGENTCHAIN_API_KEY,
  signerAnchorAddress: '0x36cbAE566545e8df3ad15C171a7840266526E28F', // Base Sepolia
  signerAnchorChainId: 84532,
  signerAnchorRpcUrl: 'https://sepolia.base.org',
});

const result = await ac.receipts.verifyWithAnchor(receipt);

if (result.valid && result.onChainVerified) {
  // Fully trustless: ECDSA passed + signer confirmed authorized on SignerAnchor
  console.log('Receipt is fully verified on-chain');
} else if (result.valid && !result.onChainVerified) {
  // ECDSA passed but on-chain check skipped or degraded
  console.log('ECDSA valid; on-chain check skipped:', result.reasons);
  // reasons: 'signer_anchor_unavailable' | 'signer_anchor_rpc_error'
} else {
  // Receipt is invalid
  console.log('Receipt invalid, reasons:', result.reasons);
  // reasons: 'signature_mismatch' | 'signer_revoked'
}

Next steps

Policy model — configure rules, thresholds, and caps
Receipts — receipt lifecycle, states, and verification
Deployments — live anchor contract addresses
API reference — REST endpoints

Security notes for pilots

Simulation fail-closed behavior

When simulate: true is set in the guard request and the RPC circuit breaker is OPEN (too many consecutive simulation failures), the guard returns 503 SIMULATION_DEGRADED. All subsequent guard requests with simulate: true will fail until the circuit recovers. Pilots should decide their fallback strategy upfront:

Strategy	Behavior	Risk
Keep `simulate: true`, halt on 503	Agent stops during outage	Zero false-allows during outage
Fall back to `simulate: false`	Agent continues without revert protection	Transactions may revert on-chain

The circuit auto-recovers after 60 seconds of no failures (HALF_OPEN → CLOSED).

4-byte selector collision limitation

allowedSelectors matches on the first 4 bytes of calldata. Two different Solidity functions can share the same 4-byte selector (keccak256 collision). This is extremely unlikely in practice but is a documented limitation. Mitigation: Combine allowedTargets + allowedSelectors — both must match. The probability of a meaningful collision on a specific target contract is negligible for standard EVM deployments.

Getting Started

Core Protocol

Infrastructure

EVM Guard Quickstart

Overview

Install

Create a client

Create a policy

Guard and execute

Guard only (no execution)

Verify a receipt locally

Verify on-chain (SignerAnchor)

Next steps

Security notes for pilots

Simulation fail-closed behavior

4-byte selector collision limitation

​Overview

​Install

​Create a client

​Create a policy

​Guard and execute

​Guard only (no execution)

​Verify a receipt locally

​Verify on-chain (SignerAnchor)

​Next steps

​Security notes for pilots

​Simulation fail-closed behavior

​4-byte selector collision limitation

Overview

Install

Create a client

Create a policy

Guard and execute

Guard only (no execution)

Verify a receipt locally

Verify on-chain (SignerAnchor)

Next steps

Security notes for pilots

Simulation fail-closed behavior

4-byte selector collision limitation