Contributed by SHLL Protocol

This document describes the security architecture for policy-enforced AI agent actions on BAP-578 NFA tokens. The framework extends BAP-578 §4.7 (Security Mechanisms) with granular, on-chain, per-transaction policy enforcement.

AI agents operating autonomously on-chain face attack vectors that traditional Web3 security does not address:

Key insight: All four attack vectors originate in the off-chain environment (LLM, runtime, dependencies). The only defense that cannot be bypassed is on-chain smart contract enforcement.

The PolicyGuard framework defines four core policy types. Each policy validates a single aspect of an action:

Design note: Earlier iterations included separate DexWhitelist and TokenWhitelist policies. These were consolidated — DeFiGuard subsumes DEX router whitelisting (target + selector), and SpendingLimitV2 integrates token whitelist + approve control. Four policies provide complete coverage with less administrative overhead.

All policies follow fail-close semantics:

• If a policy contract reverts → action is BLOCKED
• If a policy returns ok=false → action is BLOCKED
• If no policies are bound → action is BLOCKED
• Only explicit ok=true from ALL bound policies permits execution

There is no "default allow." The system fails safe, always.

┌─────────────────────────────┐
│         Owner Wallet        │  ← User-controlled
│  • Holds NFA token          │  • Sets policies
│  • Full admin rights        │  • Withdraws funds
│  • Cannot be overridden     │  • Pauses agent
└────────────┬────────────────┘
             │ owns
┌────────────▼────────────────┐
│       AgentAccount          │  ← Smart contract vault
│  • Isolated fund storage    │     (ERC-6551 TBA)
│  • PolicyGuard enforced     │
│  • All actions validated    │
└────────────┬────────────────┘
             │ executes through
┌────────────▼────────────────┐
│      Operator Wallet        │  ← AI-controlled
│  • Can only propose actions │  • Cannot transfer funds out
│  • Cannot modify policies   │  • Cannot self-destruct
│  • Subject to ALL policies  │  • Cannot bypass PolicyGuard
└─────────────────────────────┘

Key property: The AI agent (operator) can only propose actions. The smart contract (PolicyGuard) decides whether to execute them. Even if the operator key is fully compromised, the attacker is still bound by all on-chain policies.

• Reentrancy protection — All state changes before external calls (CEI pattern)
• Access control — Owner-only administrative functions
• Input validation — Zero-address checks, array bounds
• Fail-close by default — Unconfigured agents cannot execute actions
• No delegatecall — Policies cannot execute arbitrary code
• View-only validation — validate() is view, cannot modify state during check
• Composable isolation — Each policy is an independent contract

SpendingLimitPolicyV2: Daily Cap (maxPerDay) — FIXED

Severity: Medium | Status: ✅ Fixed

Previous issue: The onCommit() function only tracked msg.value (native BNB) toward the daily cap. For ERC20→ERC20 swaps using approve + swap flow, value=0 bypassed daily accumulation.

Fix: Added _extractSpendAmount() helper that parses amountIn from swap calldata using the existing OutputPattern registry. Both check() and onCommit() now enforce daily caps against native BNB and ERC20 swap amounts. Supports V2 5-param, V3 single, and V3 multi swap layouts.

Test coverage: 54/54 SpendingLimit tests pass including 2 new ERC20 swap daily limit test cases. Full suite: 278/278 tests pass.

Design note: amountIn for ERC20 swaps is in token-native denomination, not BNB. The daily cap serves as a velocity limiter rather than an exact BNB-equivalent budget. Combined with CooldownPolicy, this provides effective rate limiting.

• Owner/Operator separation — AI never holds the ownership key
• On-chain enforcement — All policies enforced at smart contract level
• Auditable trail — Events emitted for every validation and execution
• Emergency controls — Agent can be paused via state toggle

SHLL Protocol maintains the production reference implementation with 12 verified contracts on BSC Mainnet (Chain ID: 56):

• 278 / 278 Foundry test cases passing (100% pass rate)
• Test suite covers: policy validation, fail-close behavior, edge cases, access control, reentrancy
• All contracts verified on BscScan with source code published

• Internal security review completed
• All contracts are open source: github.com/shll-protocol/shll
• Community audit welcome — issues can be reported via GitHub

• Production: shll.run
• Source Code: github.com/shll-protocol/shll
• npm Package: shll-skills (CLI + MCP Server)
• Twitter: @shllrun