Guardrails

Overview

Guardrails are hard limits that cannot be exceeded by an agent. They're the first line of defense ensuring agents operate safely within defined boundaries.

Unlike policies (which can be conditional), guardrails are absolute:

• Transaction exceeds max value? Blocked.
• Contract not on allowlist? Blocked.
• Daily limit reached? Blocked.

Configuring Guardrails

const wallet = new MonmouthWallet({
  guardrails: {
    // Value limits
    maxTransactionValue: '1 ETH',
    dailySpendingLimit: '10 ETH',
    weeklySpendingLimit: '50 ETH',
 
    // Contract restrictions
    allowedContracts: [
      '0x...', // Uniswap Router
      '0x...', // Aave Pool
    ],
    blockedAddresses: [
      '0x...', // Known phishing address
    ],
 
    // Token restrictions
    allowedTokens: ['ETH', 'USDC', 'WETH'],
    blockedTokens: ['SCAM'],
 
    // Operation restrictions
    blockedOperations: [
      'selfdestruct',
      'delegatecall',
    ],
  }
})

Guardrail Types

Value Limits

Control how much value an agent can transact:

{
  maxTransactionValue: '1 ETH',     // Per-transaction limit
  dailySpendingLimit: '10 ETH',     // Rolling 24-hour limit
  weeklySpendingLimit: '50 ETH',    // Rolling 7-day limit
  monthlySpendingLimit: '100 ETH',  // Rolling 30-day limit
}

Contract Restrictions

Control which contracts an agent can interact with:

{
  // Allowlist mode: only these contracts allowed
  allowedContracts: ['0x...', '0x...'],
 
  // Blocklist mode: these contracts forbidden
  blockedAddresses: ['0x...'],
}

Token Restrictions

Control which tokens an agent can use:

{
  // Allowlist mode
  allowedTokens: ['ETH', 'USDC', 'WETH', 'DAI'],
 
  // Blocklist mode
  blockedTokens: ['SCAM', 'RUG'],
}

Operation Restrictions

Block dangerous operations:

{
  blockedOperations: [
    'selfdestruct',     // Contract destruction
    'delegatecall',     // Arbitrary code execution
    'create2',          // Deterministic deployment
  ],
}

Violation Handling

When a guardrail is violated, the SDK throws a GuardrailViolation error:

try {
  await wallet.executeIntent({
    type: 'transfer',
    amount: '100 ETH', // Exceeds maxTransactionValue
    to: '0x...',
  })
} catch (error) {
  if (error instanceof GuardrailViolation) {
    console.log(error.guardrail) // 'maxTransactionValue'
    console.log(error.limit)     // '1 ETH'
    console.log(error.attempted) // '100 ETH'
  }
}

Dynamic Guardrails

Guardrails can be updated at runtime (if the guardian approves):

// Request guardrail update (requires guardian signature)
await wallet.updateGuardrails({
  maxTransactionValue: '5 ETH',
}, {
  guardianSignature: '0x...',
})

Monitoring

Track guardrail usage:

const usage = await wallet.getGuardrailUsage()
 
console.log(usage)
// {
//   dailySpent: '3.5 ETH',
//   dailyRemaining: '6.5 ETH',
//   weeklySpent: '12 ETH',
//   weeklyRemaining: '38 ETH',
//   lastTransaction: '2025-01-15T10:30:00Z',
// }

Best Practices

1. Start restrictive: Begin with tight guardrails and loosen as you gain confidence
2. Use allowlists: Prefer allowlists over blocklists for contracts and tokens
3. Monitor usage: Track how close agents get to limits
4. Test thoroughly: Verify guardrails work before deploying agents
5. Have a guardian: Always configure a guardian for emergency stops