Guide: Configure Plugin-Prflght Firewall for ElizaOS DeFi Transaction Policies

To secure an autonomous ElizaOS agent engaged in DeFi operations, you must enforce deterministic rules. Configure the plugin-prflght firewall to intercept all payload generations and block unauthorized destination contracts, enforce max slippage constraints, and validate TVL loops before the EVM_PRIVATE_KEY executes a signature.

Configuration Payload Block

import { PreFlightPlugin } from '@elizaos/plugin-prflght';

const defiFirewallConfig = {
  max_transaction_value_usd: 1000,
  approved_routers: ["0xUniswapV3...", "0xCurve..."],
  max_slippage_bps: 50, // 0.5% max slippage
  require_tvl_audit: true
};

elizaNode.registerPlugin(new PreFlightPlugin(defiFirewallConfig));

Architectural Context: Deterministic Middleware vs. Probabilistic LLMs

An AI agent driven by an LLM is a probabilistic engine. It cannot be mathematically trusted with direct control over cryptographic assets. The plugin-prflght module serves as a Layer-2 deterministic boundary entirely isolated from the language model’s context window. This isolation is the cornerstone of modern AI-DeFi security.

The Problem with Probabilistic Execution

LLMs work by predicting the next most likely token. While they can be remarkably accurate at generating valid transaction data, they are subject to “hallucinations” or prompt injections. A malicious actor might trick an agent into sending funds to an unapproved address or executing a swap with 100% slippage. Because the LLM “believes” it is following instructions, it will generate a valid cryptographic payload that fulfills the attacker’s request.

Enter Plugin-Prflght: The Circuit Breaker

The plugin-prflght module acts as a “circuit breaker” between the LLM’s intent and the wallet’s execution. When the agent decides to execute a swap, it prepares an EVM payload. Before viem signs this payload, the Pre-Flight middleware intercepts the raw data.

Inside the middleware, the payload is subjected to a series of Deterministic Validation Schemas. These schemas do not care about the LLM’s “reasoning”; they only care about the physical parameters of the transaction:

1. Destination Check: The to address is cross-referenced against a hard-coded approved_routers list.
2. Slippage Enforcement: The middleware decodes the transaction data field (using viem’s ABI decoders) to extract the amountOutMinimum parameter. It then pings a price oracle to ensure the actual value satisfies the max_slippage_bps constraint.
3. Capital Control: It checks the dollar value of the transaction against the max_transaction_value_usd limit.

This setup requires precision, similar to understanding how to format wif base58 private key for elizaos evm configuration, as a single structural error or bypass in the middleware could lead to total capital loss.

Preventative Maintenance: TVL Audits and Rate Limits

For institutional deployments, the firewall must extend beyond simple whitelisting into deep state-aware validation.

1. TVL Sanity Loops and Liquidity Checks

Configure the require_tvl_audit flag to make the firewall perform async checks against external subgraphs or on-chain liquidity pools.

• Execution Path: Before approving a swap into a new token, the firewall pings an indexer (e.g., The Graph or DefiLlama).
• Validation Logic: If the target liquidity pool’s Total Value Locked (TVL) has dropped by more than 20% in the last hour, or if the pool size is below a safe threshold (e.g., $500k), the firewall rejects the swap. This protects the agent from being the “exit liquidity” in a rug pull or a flash-loan attack.

2. Rate Limiting and Velocity Checks

To prevent rapid-fire micro-transactions (a common signature of a compromised or malfunctioning agent), implement a Token Bucket Algorithm inside the firewall logic.

• Epoch Limits: Define a maximum “spend” per hour or per day.
• Transaction Velocity: Limit the number of transactions per block. If the agent attempts to sign 50 transactions in a single block, the firewall enters a “Cooldown Mode,” requiring manual operator intervention to reset.

3. Production-Grade Configuration Schema

Use a strict Zod or JSON-schema definition to manage your firewall rules. This prevents “configuration drift” where rules are accidentally weakened during maintenance.

const FirewallSchema = z.object({
  chains: z.array(z.number()), // e.g., [1, 137, 8453]
  rules: z.object({
    daily_limit_usd: z.number().max(50000),
    max_slippage_bps: z.number().int().min(1).max(1000),
    whitelist_only: z.boolean().default(true),
  }),
  alerts: z.object({
    webhook_url: z.string().url(),
    severity: z.enum(["low", "high", "critical"]),
  })
});

Security Policies: The Human-in-the-Loop Protocol

Even with an automated firewall, production ElizaOS nodes require a high-level security policy to govern the “Rules of Engagement.”

1. Multi-Signature Attestations: For transactions exceeding a certain threshold (e.g., >$5,000), modify the plugin-prflght module to require an Ed25519 co-signature from a separate “Security Node.” This node does not have LLM capabilities; it only runs the firewall logic and provides a “Seal of Approval.”
2. Audit Log Persistence: Every rejected transaction must be logged with a full stack trace, including the LLM’s original prompt and the specific firewall rule that was triggered. This allows developers to tune the agent’s prompts if it is frequently hitting security boundaries.
3. Fail-Closed Design: The firewall must be designed to “Fail-Closed.” If the price oracle is down or the firewall’s internal database is unreachable, the default action must be REJECT. Never allow a transaction to bypass the firewall due to a service error.

Advanced FAQ: Technical Contextual Analysis

How does the firewall decode complex Uniswap V3 multicall data?

The firewall utilizes viem’s decodeFunctionData utility. By loading the Uniswap V3 Router ABI, it can parse the hex string in the data field into a human-readable object. If the transaction is a multicall, the firewall iterates through each sub-call, recursively validating that no hidden transfer or approve calls are buried within a legitimate-looking swap execution.

Can the firewall prevent “Sandwich Attacks” on the agent?

Directly, no, but it mitigates the damage. By enforcing a strict max_slippage_bps (e.g., 10 bps or 0.1%), the firewall ensures that if a searcher attempts to sandwich the agent’s transaction, the resulting price impact will cause the transaction to revert on-chain. The firewall’s role is to ensure the agent never signs a transaction with a “generous” slippage tolerance that would make it a target for MEV bots.

Is it possible to whitelist based on contract bytecode?

Yes, and this is a recommended “Paranoid Mode” strategy. Instead of whitelisting just the address, the firewall can perform an eth_getCode call and compare the hash of the target contract’s bytecode against a known “Good” version. This protects the agent in the rare event that a contract owner uses a proxy or CREATE2 to swap a legitimate router for a malicious one at the same address.