\n The Intelligent Security Infrastructure & Pre-Execution Firewall for Autonomous AI Agents\n
\n\n
\n \n \n \n \n
\n\n---\n\n## π Table of Contents\n1. [The Problem: The Agency Gap](#-the-problem-the-agency-gap)\n2. [Target Audience: Who is this for?](#-target-audience-who-is-this-for)\n3. [The Strategic Solution](#-the-strategic-solution)\n4. [Core Technology & Infrastructure](#-core-technology--infrastructure)\n5. [Prerequisites: Agent Registration (IMPORTANT)](#-prerequisites-agent-registration-important)\n6. [Installation & Setup](#-installation--setup)\n7. [Implementation Manual (Production Pattern)](#-implementation-manual-production-pattern)\n8. [Safe Demo & Devnet Testing](#-safe-demo--devnet-testing)\n9. [Advanced Security Features](#-advanced-security-features)\n10. [Human-in-the-loop (Escalation)](#-human-in-the-loop-escalation)\n11. [FAQ](#-faq)\n\n---\n\n## πͺοΈ The Problem: The Agency Gap\n\nThe rise of Autonomous AI Agents on the blockchain has created a massive, unaddressed security vacuum known as **The Agency Gap**. \n\nTraditional wallet security (like Multi-sig or Hardware Wallets) relies on **Human Intent**. However, when an AI Agent controls a wallet, the intent is generated by an LLM. This creates fatal vulnerabilities:\n\n### 1. The \"Semantic-to-Binary\" Blindspot\nAgents translate natural language into binary transaction data. If the LLM is tricked via **Prompt Injection**, it will build a perfectly valid transaction that performs a malicious act (e.g., \"Transfer all SOL to an attacker's drainer\").\n\n### 2. Jailbreaking & Instruction Drift\nSystem prompts can be bypassed. An agent instructed to \"only swap on Jupiter\" can be persuaded to interact with a malicious, unverified contract, leading to total asset depletion.\n\n### 3. The Lack of a \"Pre-Execution\" Firewall\nOnce an agent has the private key, there is no \"check-and-balance\" before the signature. Most security happens *post-execution* (monitoring), which is too late for irreversible blockchain transactions.\n\n---\n\n## π― Target Audience: Who is this for?\n\nBento Guard is engineered for developers and organizations building:\n\n- **Autonomous DeFi Agents**: Trading bots, yield optimizers, and portfolio managers that require high-velocity but safe execution.\n- **Autonomous DAOs**: Systems where AI makes governance or treasury decisions based on community sentiment.\n- **AI Gaming Agents**: In-game autonomous entities that manage assets, trade items, or interact with smart contracts.\n- **Agentic Infrastructure**: Platforms providing \"Agent-as-a-Service\" where security is the primary value proposition.\n\n---\n\n## π‘οΈ The Strategic Solution\n\nBento Guard is not just a library; it is a **Security Infrastructure** that bridges the Agency Gap by introducing a **Verifiable Audit Layer**.\n\n| Strategic Pillar | How it Solves the Pain |\n|:--- |:--- |\n| **Intent Verification** | We audit the *LLM's reasoning* against the *actual transaction data* to ensure they match 1:1. |\n| **Pre-Execution Simulation** | Every transaction is forked and simulated in a sandbox before the agent signs it. |\n| **Non-Custodial Control** | You keep your keys. We provide the \"Permission Logic\" via a secure tunnel. |\n| **On-Chain Policy Enforcement** | Policies are not just config files; they are enforced by Solana Smart Contracts. |\n\n---\n\n## π Core Technology & Infrastructure\n\n### MagicBlock Ephemeral Rollups\nSecurity shouldn't be slow. Bento Guard leverages **MagicBlock** to achieve sub-second security auditing:\n- **Forked Simulation**: We simulate the transaction on an ephemeral rollup that mirrors the current Solana mainnet state.\n- **Verifiable Decision State**: The \"Allow/Block\" decision is recorded on an ephemeral chain, providing a transparent audit trail without the high cost of L1 transactions.\n\n### BSIT Protocol (Bento Secure Instruction Tunneling)\nWe protect the \"Security Handshake\" using industry-standard cryptography:\n1. **Identity**: Agent signs requests with **Ed25519** (Solana standards).\n2. **Key Exchange**: E2E encryption via **X25519 (ECDH)** forward secrecy.\n3. **Payload Protection**: Data is encrypted using **AES-256-GCM**, ensuring your agent's private instructions never touch our logs in plaintext.\n\n---\n\n## π Prerequisites: Agent Registration (IMPORTANT)\n\nBefore your agent can execute transactions via the Bento SDK, you **must register your agent's wallet** on the Bento Dashboard. If you skip this step, you will encounter an `Agent not found` error.\n\n1. Go to [https://app.bentoguard.xyz](https://app.bentoguard.xyz)\n2. Connect your owner wallet.\n3. Register your agent's public address (the one matching `AGENT_WALLET_PRIVATE_KEY`).\n\n---\n\n## π Installation & Setup\n\n### Install Dependencies\n```bash\nnpm install @bentoguard/sdk @solana/web3.js bs58 tweetnacl\n```\n\n### The \"Magic\" Setup Wizard\nHighly recommended for new projects. It initializes your environment, configures your keys, and creates a full finance agent sample:\n```bash\nnpx @bentoguard/sdk\n```\n\n---\n\n## π» Implementation Manual (Production Pattern)\n\nTo ensure 100% reliability, your agent should follow this integration pattern. This ensures the instruction is audited and approved *before* any transactions are built or broadcasted.\n\n### Automatic Configuration\nThe SDK automatically handles API connections. You only need to provide your `AGENT_WALLET_PRIVATE_KEY` for the system to identify and secure your agent.\n\n```typescript\nimport { protect, verifyRegistration } from '@bentoguard/sdk';\nimport { Keypair } from '@solana/web3.js';\nimport * as nacl from 'tweetnacl';\nimport bs58 from 'bs58';\n\n/**\n * PRODUCTION-GRADE INTEGRATION\n */\nasync function executeSecureAgentAction() {\n // Load Agent's identity\n const agentKeypair = Keypair.fromSecretKey(bs58.decode(process.env.AGENT_WALLET_PRIVATE_KEY!));\n \n // 0. CHECK REGISTRATION FIRST\n const isRegistered = await verifyRegistration({ agentAddress: agentKeypair.publicKey.toBase58() });\n if (!isRegistered) {\n console.error(\"Agent not found. Please register at https://app.bentoguard.xyz first.\");\n return;\n }\n\n // 1. AGENT PLANNING PHASE\n const instruction = \"Send 10 SOL to recipient address 2cSiFhzwbymqr5aTiFacbidJNZ5vNK7Zdb9osbdfcKwG\";\n \n // 2. SIGNING IS HANDLED INTERNALLY\n // The Bento SDK automatically signs the verification payload using your configured AGENT_WALLET_PRIVATE_KEY.\n\n try {\n console.log(\"π‘οΈ Forwarding to Bento Guard Firewall...\");\n \n // 3. CALL THE GUARD: protect(instruction, options)\n const audit = await protect(instruction, {\n agentAddress: agentKeypair.publicKey.toBase58(),\n // Default is true. Set to false if your app wants to return ESCALATED\n // immediately and handle dashboard/deep-link approval itself.\n autoPollEscalation: true,\n });\n \n if (audit.recommendation === 'ALLOW') {\n console.log(\"β Audit Passed:\", audit.reasoning);\n console.log(\"Risk Score:\", audit.riskScore);\n \n // 3. EXECUTION PHASE\n // Safe to build and broadcast your transaction now\n console.log(\"π Executing secure transaction...\");\n \n } else if (audit.recommendation === 'ESCALATED') {\n console.warn(\"β οΈ High-Risk Action: Pending human approval in Bento Dashboard.\");\n console.warn(\"Action ID:\", audit.actionId);\n // This branch is reached when autoPollEscalation is false.\n }\n \n } catch (error: any) {\n if (error.code === 'HIGH_RISK_DETECTED') {\n console.error(\"π SECURITY BLOCK: Bento Guard prevented a malicious action.\");\n console.error(\"Reasoning:\", error.message);\n } else {\n console.error(\"System Error:\", error.message);\n }\n }\n}\n\n// Execute the integration\nexecuteSecureAgentAction().catch(console.error);\n```\n\n---\n\n## π§ͺ Safe Demo & Devnet Testing\n\nCurrently, the system is running on **Devnet**. All transactions are sponsored/paid by the Relayer fee. The user only needs to sign to create a signature for the action.\n\nIf you are just exploring the concept with a **burner wallet (no funds)**, use the `testnet` environment (which defaults to the production backend). You can also explicitly verify registration to avoid cryptic errors.\n\n```typescript\nimport { protect, verifyRegistration } from '@bentoguard/sdk';\nimport { Keypair } from '@solana/web3.js';\nimport * as nacl from 'tweetnacl';\nimport bs58 from 'bs58';\n\nasync function safeDemo() {\n const agentKeypair = Keypair.generate(); // Burner wallet\n const agentAddress = agentKeypair.publicKey.toBase58();\n \n // Inject into process.env so Bento SDK can use it for signing payloads\n process.env.AGENT_WALLET_PRIVATE_KEY = bs58.encode(agentKeypair.secretKey);\n \n console.log(\"Generated Burner Wallet:\", agentAddress);\n console.log(\"Please register this wallet at https://app.bentoguard.xyz before proceeding!\");\n \n // Check registration to ensure smooth onboarding\n const registered = await verifyRegistration({ agentAddress });\n if (!registered) {\n console.error(\"π¨ Registration failed. The backend cannot find this agent.\");\n console.error(\"Go to https://app.bentoguard.xyz and register the wallet address.\");\n return;\n }\n \n // Create a mock instruction\n const instruction = \"Swap 1 USDC for SOL on Jupiter.\";\n \n try {\n const result = await protect(instruction, { agentAddress });\n console.log(\"Bento Verdict:\", result.recommendation);\n } catch (e: any) {\n console.error(\"Error:\", e.message);\n }\n}\n\n// Execute the safe demo\nsafeDemo().catch(console.error);\n```\n\n---\n\n## π Advanced Security Features\n\n| Feature | Technical Detail |\n|:--- |:--- |\n| **LLM Cross-Verification** | We use multiple models (Gemini/Claude) to reach a consensus on agent intent. |\n| **Pre-Execution Simulation** | MagicBlock forks the mainnet state at the exact slot of the request for 100% accuracy. |\n| **Dynamic On-chain Policies** | Policies are stored in Solana accounts, allowing for real-time updates and DAO governance. |\n| **Identity Verification** | Every audit request is cryptographically tied to the Agent's on-chain public address. |\n\n---\n\n## π§βπ» Human-in-the-loop (Escalation)\n\nNot every risk is an attack. Sometimes an agent needs to perform a large, unusual transaction.\nBento Guard's **Escalation Engine** allows:\n1. Agent submits a high-risk request.\n2. Bento Guard creates an action review and returns `ESCALATED` with an `actionId`.\n3. The backend sends dashboard notifications and deep links for approve/block.\n4. By default, the SDK pauses and polls until the owner approves or blocks the action.\n5. Once the owner approves, `protect()` resolves as `ALLOW`; if the owner blocks or review times out, `protect()` throws.\n\nIf your application wants to handle review itself, pass:\n\n```typescript\nconst audit = await protect(instruction, {\n agentAddress: agentKeypair.publicKey.toBase58(),\n autoPollEscalation: false,\n});\n\nif (audit.recommendation === 'ESCALATED') {\n console.log(audit.actionId);\n console.log(audit.reviewUrl);\n console.log(audit.approveUrl);\n console.log(audit.blockUrl);\n}\n```\n\n---\n\n## β FAQ\n\n**Q: Does Bento Guard store my Private Keys?**\n**A:** No. Your private keys never leave your agent's environment. The SDK handles signing the payloads locally using your configured key and only sends the signed intent securely over the network.\n\n**Q: How much latency does this add?**\n**A:** Thanks to MagicBlock Ephemeral Rollups, the overhead is typically under 500msβfaster than most LLM inference times.\n\n**Q: What happens if the Bento Backend is down?**\n**A:** You can configure the SDK's \"Fail-Safe\" mode to either `BLOCK_ALL` (strict security) or `ALLOW_ALL` (priority on uptime).\n\n---\n\n## π Resources\n- **Official Website**: [bentoguard.xyz](https://bentoguard.xyz)\n- **Documentation**: [docs.bentoguard.xyz](https://bento-1.gitbook.io/bento-docs)\n- **Dashboard**: [app.bentoguard.xyz](https://app.bentoguard.xyz)\n\n
![\"Bento](\"./assets/BENTO_LOGO.png\"){kind=logo}
\n \n![\"NPM](\"https://img.shields.io/npm/v/@bentoguard/sdk.svg?style=for-the-badge&color=663399\")
\n ![\"MagicBlock\"](\"https://img.shields.io/badge/Infrastructure-MagicBlock-blueviolet?style=for-the-badge\"){kind=icon}
![\"Docs\"](\"https://img.shields.io/badge/Docs-GitBook-blue?style=for-the-badge\"){kind=icon}
![\"Solana\"](\"https://img.shields.io/badge/Network-Solana-black?style=for-the-badge&logo=solana\"){kind=icon}