# Overview Alloc8 is an agentic asset allocation protocol that lets you programmatically delegate execution using smart accounts. Alloc8 is built for Liquidity Providers (LPs) and DAOs that want automation without giving up custody. #### What “non-custodial” means in Alloc8 Alloc8 is designed so that: * Funds live in your **Smart Account** (a modular ERC-4337 smart wallet). * An **agent** can only execute actions that your **policy** allows. * If the policy checks fail, execution fails. In other words, the agent can automate, but it cannot exceed the permissions you grant. #### The mental model Alloc8 has five moving pieces: 1. **Modular Smart Account:** Holds your funds and enforces modules (validation + execution hooks). 2. **Account Factory:** Deterministically deploys accounts and maintains on-chain registry metadata. 3. **Global Session Policy Module (GSPM):** The policy firewall: binds the session agent and validates that actions are allowed. 4. **Position Manager:** Mints/manages LP positions as NFTs (mint/increase/decrease/collect/burn) with additional controls. 5. **DeFi Agent:** Computes tick ranges and proposes rebalances based on pool conditions and volatility. #### User lifecycle (end-to-end) 1. Create a Smart Wallet. 2. Activate your Agent (session + policy). 3. Deposit into a strategy. 4. Agent proposes rebalances; policy enforces safe execution. 5. Withdraw at any time. #### What this documentation covers * **Product guides** for users and operators. * **Architecture reference** for builders and auditors. * **Security & risk** to clarify guarantees, assumptions, and failure modes. If you are integrating or auditing, start with **Architecture → Global Session Policy Module** and **Security → Threat Model**. # Core Features Why use Alloc8? Alloc8 combines programmable smart accounts, policy-based execution, and MEOW Agents to automate liquidity management. #### Smart Accounts (modular ERC-4337) * Modular “plug-in” design: add/remove modules to introduce new logic without changing the account core. * Validation hooks for session keys and custom authorization. * Execution hooks to enforce allowlists, recipients, value limits, and other constraints. * ERC-1271 compatibility for contracts that expect signature validation. #### Policy-Based Execution (GSPM) GSPM enforces: * the bound session agent (authorized signer) * allowlists (agents and tokens) * recipient pinning (where proceeds can go) * per-transaction and rolling-window slippage budgets * pool↔oracle deviation constraints * tick-ratio sanity checks for liquidity operations #### DeFi Agents (strategy automation) Agents: * analyze pool state and volatility * compute upper/lower ticks for concentrated liquidity * decide when rebalancing is appropriate (including skipping unstable periods) Alloc8’s model is: autonomous execution gated by explicit, on-chain policy. # Getting Started Your gateway to Intelligent DeFi, powered by Alloc8. In just a few steps, you can connect your wallet, set up your agent, and start exploring smart yield strategies - all while staying in control. #### Step-by-step 1. **Connect your wallet** 2. Explore **LP Strategies** on the Home page. 3. First-time users: 1. Create a Smart Wallet 2. Activate your Agent 4. Pick a strategy and click **Deposit**. 5. **Enter the amount** and confirm your deposit. #### After you deposit Once you deposit successfully, Alloc8 works behind the scenes to keep liquidity in the optimal range - subject to your policy limits. #### Pre-flight checklist (recommended) Before depositing: * Confirm you are on the intended chain/network. * Verify you are using the official deployment addresses (see Resources → Deployment Addresses). * Start with a small amount to validate deposit/withdraw behavior end-to-end. # Glossary * **EOA**: Externally Owned Account (eg, your Metamask wallet address). * **Smart Account**: Your modular ERC-4337 account contract. * **ERC-4337**: Account abstraction standard using UserOperations executed via an EntryPoint. * **Bundler**: Off-chain service that submits UserOperations to EntryPoint. * **EntryPoint**: ERC-4337 contract that validates and executes UserOperations. * **Session Agent**: Authorized signer for an account session. * **Session**: A time/permission-bounded authorization for an agent to act on your behalf. * **GSPM**: Global Session Policy Module; policy firewall for agent execution. * **Position Manager**: Liquidity manager for NFT-based concentrated liquidity positions. * **DeFi Agent**: Strategy module computing tick ranges and rebalance signals. * **Slippage budget**: Allowed value loss over a rolling window, enforced on-chain. * **Recipient pinning**: Enforcement that proceeds go only to the account or owner. * **Performance fee**: A protocol fee charged on realized fees/yield, collected at rebalance or autocompound events.\ **Autocompound**: A scheduled process that realizes and reinvests fees/yield back into the position (runs weekly). # Autonomous LP Alloc8 automates **concentrated liquidity (CL)** so you don’t need to manually manage ranges and rebalances. CL can offer higher fee potential, but if the price moves **out of range**, your position may earn **no fees** until it is moved back in range. #### What Alloc8 automates **1) Range selection (ticks)**\ The **Agent** calculates the **lower and upper ticks** using pool conditions (price, TWAP, liquidity, volatility) and considers risk/gas constraints. **2) Rebalancing (move to a new range)**\ When needed, the system can rebalance by adjusting your LP NFT position (mint/increase/decrease/collect/burn) through the **Position Manager**. **3) Autocompound (scheduled)**\ Autocompound runs **every Sunday at 7:00 PM UTC**. *** ### ZAPs (enter/exit from any token) Alloc8 supports **ZAPs**, which lets you **enter or exit a position using a single token**, instead of supplying (or receiving) both pool tokens. How it works (user view): * You choose the token you want to deposit/withdraw. * The ZAP route performs the needed swaps and liquidity steps automatically. **Important:** Zap outputs are **estimates**, because swaps execute at live market prices - final amounts can vary slightly. *** ### Slippage, price impact, and safety checks Automation still needs guardrails. Alloc8 enforces on-chain policy checks via **GSPM**, including: * **recipient pinning** (proceeds go only to your account/owner path), * **per-transaction slippage bounds**, * **rolling-window slippage budgets** (caps cumulative loss), * **token/agent allowlists**, and * pool ↔ oracle deviation limits. Plain-language definitions: * **Slippage**: price changes between quote and execution; if it moves too much, execution can fail and retry later. * **Price impact**: your trade size moves the pool price; a high impact can cause a revert. *** ### Dust (small leftover tokens) During rebalances or Zap actions, small leftover amounts (“dust”) can happen due to rounding and swap execution. Dust is **not intended to be lost -** it typically remains as small token balances in your account flow and is returned back to your smart account. You can either utilise the Dust by depositing it back to existing position, or open a new position or withdraw to your EOA wallet. Alloc8’s Position Manager includes **refunds for unused tokens** during mint/increase to prevent overpayment (a common source of dust handling). *** ### Fees and gasless execution (what users should expect) * Alloc8 charges a **10% performance fee** on **realized yield**, not on your deposit. * This fee is collected during **rebalance** or **autocompound** events (Sunday 7:00 PM UTC). * Rebalances/autocompounds are **gasless for users**: the protocol pays gas and subsidizes it from the performance fee. * Rebalances typically trigger when **earned fees/yield > gas cost**. If gas is very high, smaller positions may rebalance less often and can show **out of range**. Recommended size: **$500+**. *** ### Critical risks (don’t skip) Alloc8 automation does not remove DeFi risks, including: * **Impermanent loss (IL)** * **Range risk** (out-of-range positions may stop earning fees) * **Sudden volatility spikes** (rebalances may be delayed or skipped) * **Smart contract risk** (Alloc8 + AMMs/routers + tokens) Also note: **rebalancing can realize IL**, because it may involve swapping between tokens to restore target ratios. # Safety Controls Even when the agent decides an action is “good,” it must still pass **GSPM** checks before executing. These include: * **Per-transaction slippage check** (min-out / value-loss bound) * **Rolling-window slippage budgets** (caps cumulative loss over a time window) * **Pool ↔ oracle deviation budget** (blocks abnormal price divergence) * **Tick-ratio sanity checks** (guards against drifting execution) * **Recipient pinning** (proceeds go only to your Smart Account/owner path) * **Token + agent allowlists** :contentReference\[oaicite:9]{index=9} If checks fail, the transaction **reverts** (it does not partially execute). # Dust during automation **Dust** means small leftover token amounts that can remain after rebalancing or minting because: * swaps can’t be perfectly exact, * rounding occurs on-chain, * slippage changes final amounts. Alloc8’s Position Manager includes **refunds for unused tokens** during mint/increase to avoid overpaying, which is one common source of “dust.” **Key point:** dust is not “lost.” It typically remains in your **Smart Account** as small token balances. # Architecture Overview Alloc8’s architecture connects modular smart accounts, Agents, and policy enforcement to manage and rebalance concentrated liquidity positions. #### High-level flow 1. **Account Setup**: EOA deploys and configures a Smart Account and installs modules. 2. **Strategy Input**: The system requests optimal ranges from the Agent. 3. **Position Management**: deposits mint LP positions via the Position Manager. 4. **Rebalancing**: agent proposes operations; GSPM validates policy constraints. 5. **Execution**: operations execute through ERC-4337 (bundler → EntryPoint). 6. **Liquidity Update**: Position Manager burns/mints positions to update ranges. During rebalance/autocompound actions, realized fees/yield may be collected, and the protocol performance fee is applied to the generated yield amount. Result: non-custodial, policy-based execution for continuous LP optimization.
# Modular Smart Accounts Alloc8 Smart Accounts Alloc8’s smart accounts are built on top of the **ERC-4337 account abstraction standard**, extended with **modularity**. At the core is the `Modular4337Account` — a **highly composable**, **upgrade-friendly**, and **developer-extensible** smart wallet contract. At the center is the **Modular4337Account**: a smart wallet that supports plug-and-play modules for custom logic, without ever changing the core contract. Using a **hook-based architecture**, developers can add validation rules, execution logic, policy enforcement, fee routing, and more — safely and flexibly. *** #### Key Capabilities * **Modular Hook Design**\ Add or remove functionality with `installModule()` and `removeModule()`. Only use what you need. * **Validation Hooks**\ Enforce arbitrary preconditions during validateUserOp() — such as session keys, time locks, multi-sig auth, or custom signature schemes. * **Execution Hooks**\ Modify or extend transactions on-chain — e.g., allowlists, fee rebates, or automatic forwarding. * **ERC-1271 Signature Compatibility**\ Works with dApps expecting standard ECDSA signatures. * **Native ERC-4337 Integration**\ Compatible with the EntryPoint contract and bundler flows for gasless UX and programmable userOps. * **Extensible by Design**\ Any module that follows the `IModule` interface can be plugged in, enabling safe upgrades and new features. *** #### Why Use Modular4337Account? Unlike fixed-function smart wallets, `Modular4337Account` it lets you compose wallet features like plug-ins in a software framework: * You don’t need to deploy new contracts to add new capabilities/features to the wallet. * You can progressively add features like **social recovery**, **role-based access**, **ERC20 spending caps**, or **session delegation**. * Modules are auditable, reusable, and independently testable. # Account Factory The `Modular4337Factory` is a fully on-chain, deterministic factory contract used to deploy modular smart accounts (`Modular4337Account`) via the CREATE2 opcode. It supports flexible account instantiation, vault registries, and optional integration with ERC-4337's EntryPoint staking model. #### **Key Features** * **Deterministic Wallet Addresses**\ Every smart account is deployed using `CREATE2` with a per-user salt and nonce combination, allowing you to predict the address **before** deployment. * **Proxy Pattern**\ All accounts are proxies pointing to a shared `Modular4337Account` implementation, minimizing deployment gas costs. * **Vault Whitelist Registry**\ Includes built-in support for managing whitelisted vault contracts that can interact with accounts — useful for protocol-specific integrations. * **On-Chain Metadata**\ Maintains a complete registry of: * Wallets deployed by each user (`getUserWallets`) * Wallet ownership (`userWalletOwner`) * Wallet deployment nonces (`userNonce`) * **EntryPoint Stake Utilities**\ Supports `addStake`, `unlockStake`, and `withdrawStake` for ERC-4337 compliance and bundler staking. #### Typical usage flow 1. **Compute Wallet Address:**\ Use `computeAccountAddress(owner, salt)` to pre-calculate the address of the wallet. 2. **Deploy Wallet:**\ Call `deployAccount(owner, salt)` to deploy the proxy and initialize the wallet with the provided `owner` and `EntryPoint`. 3. **Manage Vaults:**\ Admins can register protocol-approved vault contracts with `addVault()` or `bulkAddVaults()`. # Global Session Policy Module (GSPM) **What this is:** An ERC-6900–style validation & execution hook designed for **Modular4337Account**.\ It follows the ERC-6900 hook pattern (install/uninstall + pre/post hooks) **using project-local interfaces** (`IValidationHookModule`, `IExecutionHookModule`) and enforces: * Per-account **session agent** binding (authorised UserOp signer) * Policy firewall for **vault PositionManager** flows, **ERC-20 approvals**, and **0x** routes * **Recipient pinning** (vault/0x proceeds → account or owner) * Global allow-lists for **agents** and **tokens** * Rolling-window **slippage budgets** (liquidity, swaps) and **pool↔oracle deviation** budget * **Tick-ratio** sanity checks with **single-sided** liquidity allowances > **Compatibility note:** This module is **not a drop-in ERC-6900 reference interface**.\ > It is designed for accounts that call these hooks exactly as Modular4337Account does.\ > If a different ERC-6900 account expects the canonical interfaces/selectors or invokes hooks outside EntryPoint execution, you’ll need a thin adapter (or to align interfaces) and possibly relax the `sender == entryPoint` guard. ### Hook behaviour (summary) * `preUserOpValidationHook` — verifies UserOp signature against the account’s **agent**. * `preRuntimeValidationHook` — **EntryPoint-only**, forbids ETH value, blocks self-target, checks agent allow-list. * `preExecutionHook` — enforces: * **Vault PM** (`collect/decrease/burn/mint/increase`): recipient checks; per-tx slippage bound (`maxSlippageCheck`); user **tick-ratio** deviation ≤ `allowedTicRatioDeviationBps`; pool↔oracle **skew** charged to deviation budget. * **ERC20 `approve`**: token must be `isTokenValid` Spender is a registered **vault** or **0x allowance holder**. * **0x AllowanceHolder → Aggregator Settler**: inner target/selector **pinned**; src/dst tokens valid; recipient pinned; **oracle-based min-out** enforced; loss charged to **swap budget**. * `postExecutionHook` — measures realised slippage for vault mint/increase and charges the per-(account, vault) budget; can revert with `HighValueLoss()` on window cap breach. ### Budgets & tuning * Globals (owner-settable):\ `slippageBudgetBps`, `swapSlippageBudgetBps`, `deviationSlippageBudgetBps`,\ `allowedTicRatioDeviationBps`, `maxSlippageCheck`, `slipWindow` (1h default). * Per-account overrides: `updateSlippageThrottle(...)` (+ `keepSlipState`). ### Security considerations * Hooks are **no-ops outside EntryPoint** by design (`sender == entryPoint` guard); portability may require adjusting this. * Oracle freshness/liveness directly impacts slippage/deviation checks. * Expanding token/agent allow-lists or relaxing budgets increases the attack surface. ### Admin / Owner API All functions below are **`onlyOwner`**: * `bulkUpdateAgents(address[] agents, bool allowed)`\ Add/remove **agents** from the global allow-list (reverts on zero address). Controls who may be bound as a session agent. * `bulkUpdateValidTokens(address[] tokens, bool valid)`\ Add/remove **ERC-20 tokens** from the global valid-token list used by approvals and 0x flows. * `setMaxSlippageCheck(uint256 _maxSlippageCheck)`\ Sets per-transaction min-out threshold in **basis points** (0 < value ≤ `PERCENTAGE_FACTOR`).\ Used in vault `mint/increase` and 0x min-out comparisons. * `setSlippageBudgetBps(uint32 _slippageBudgetBps)`\ Sets the **liquidity** cumulative slippage budget per window (must be > 0). * `setSwapSlippageBudgetBps(uint32 _swapSlippageBudgetBps)`\ Sets the **swap** cumulative slippage budget per window for 0x flows (must be > 0). * `setDeviationSlippageBudgetBps(uint32 _deviationSlippageBudgetBps)`\ Sets the cumulative **pool↔oracle deviation** budget per window (must be > 0). * `setAllowedTicRatioDeviationBps(uint32 _allowedTicRatioDeviationBps)`\ Max tolerated **user tick-ratio** deviation from expected (0 < value ≤ `PERCENTAGE_FACTOR`). * `setPriceOracle(address _priceOracle)`\ Updates the **oracle** used for USD valuations and skew checks (non-zero address). > ⚠️ Note: GSPM is explicitly designed for permissioned agent flows. If a session key is invalid or missing, the operation fails (no fallback to the owner signature path). # Oracle System *** ### Core Components #### 1. **PriceOracle Contract** The PriceOracle contract aggregates pricing information from multiple external oracle sources. It supports configuration of a **primary provider** and an optional **backup provider** per asset, enabling graceful degradation when a source fails. **Responsibilities** * Maintain mapping of assets → provider data (main + backup) * Expose a single canonical function for price lookup in USD with 18 decimals * Provide fallback logic when primary feeds fail * Emit update events for off‑chain monitoring **Key Properties** * **Deterministic failover:** if primary reverts, backup is queried * **Configurable per asset:** different assets can have different providers * **Upgradeable configuration:** only `owner` (oracle admin) can update * **Gas‑optimized sequential lookup** *** #### 2. **Price Providers (External Oracle Interfaces)** PriceOracle depends on external contracts that implement: ```solidity function getAssetPrice(address asset) external view returns (uint256); ``` These contracts abstract different oracle sources such as Chainlink, Api3, etc. **Provider Types (examples)** | Provider Type | Example Use Case | | ------------- | -------------------------------- | | Chainlink | Primary reliable feed for majors | | Api3 | Secondary real‑time fast updates | *** ### Data Flow Overview ``` ┌──────────────┐ ┌─────────────────────┐ ┌──────────────────────────┐ │ External │ │ PriceOracle │ │ Global Session Policy │ │ Providers │ │ (Aggregator) │ │ Module (GSPM) │ │ (CL / PYTH │ prices │ │ prices │ │ │ / Redstone) ├──────────►│ getAssetPrice() ├──────────►│ validateUserOperation() │ └──────────────┘ │ fallback + events │ │ enforce slippage limits │ └─────────────────────┘ └──────────────────────────┘ ``` *** ### Usage in Global Session Policy Module (GSPM) The GSPM consumes USD prices for assets involved in a user operation. Prices are used for: * **Value checks** (ensuring max allowed spend value per operation) * **Slippage enforcement** for swaps * **Collateral & risk checks** for positions under managed agents #### Example: Swap Validation ``` expectedAmountOut = inputValueUsd * (1 - maxSlippageBps / 10_000) actualAmountOut = router.call(...) require(actualAmountOut >= expectedAmountOut) ``` PriceOracle resolves USD value per asset using: ``` _price = PriceOracle.getAssetPrice(asset) value = amount * price / 1e18 ``` *** ### Security Model #### Defense Measures * Fallback provider resilience * Owner‑gated configuration updates * Reverts on unsupported assets or failing feeds * On‑chain traceability via `PriceProvidersUpdated` events #### Oracle Failure Scenarios | Failure Case | Module Outcome | | --------------------------- | ------------------------------ | | main feed revert | fallback attempt | | both revert | transaction reverts | | misconfigured provider | revert & monitoring alert | | stale backup but valid main | accepted | | wrong decimal / scaling | caught in testing requirements | *** ### Operational Responsibilities | Role | Responsibilities | | ---------------------- | ---------------------------------------- | | Oracle Admin | Update providers, monitor failure events | | Observability / DevOps | Alert on backup usage spikes | | Agent Providers | Consume prices to enforce policies | *** ### Future Extensions * Support median‑of‑N providers * Price risk engines per strategy instead of flat slippage bps *** ### Appendix #### Events ``` event PriceProvidersUpdated(address asset, address main, address backup); ``` #### Error Types * `InvalidParams()` * `UnsupportedAsset(address asset)` * `PriceFeedNotWorking(asset, main, backup)` *** # Position Manager Alloc8PositionManager The `PositionManager` is a non-fungible liquidity management contract built on top of uniswap V3, and similar models. It allows users to mint, increase, decrease, collect, and burn liquidity positions represented as NFTs, with added support for **treasury fees**, **TWAP volatility guards**, **admin recovery functions**, and **parameterised configuration**. It inherits core functionality from `BasePositionManager` and adds direct integration with Camelot's `ICamelotNonfungiblePositionManager` and `IAlgebraPoolV3 or other such pools` *** #### Key Features **NFT-Based Liquidity Minting** * Users can mint new positions using `mintLiquidity()`, which returns a unique position `tokenId` representing an LP NFT. * Includes built-in refund for unused tokens to prevent overpayment. **Fee Collection & Treasury Routing** * Automatically deducts protocol treasury fees on `collectFees()` and `burnLiquidity()` using `_collectLogic()`. * Treasury address and fee 3% (in basis points) can be configured and updated by admins. *** #### Core Functions * **`mintLiquidity(...)`** Mints a new LP position and returns the `tokenId`. Refunds unused token0/token1. * **`increaseLiquidity(...)`** Adds tokens to an existing position. Refunds unused amounts. Requires position ownership. * **`decreaseLiquidity(...)`** Removes part of the liquidity from a position. Transfers fees and liquidity to a recipient. * **`collectFees(...)`** Transfers LP NFT to the contract, collects all fees, deducts treasury cut, then returns NFT to user. * **`burnLiquidity(...)`** Performs full withdrawal: 1. Collects fees 2. Removes all liquidity 3. Transfers to user 4. Burns NFT 5. Removes position from `userPositionIds` * **`batchUpdateConfig(...)`** Admin-only method to update: 1. Treasury address and fee 2. Token0 / Token1 3. Min/Max limits 4. Pool address / fee / TWAP *** #### Admin Functions | Function | Purpose | | ------------------------------ | --------------------------------------------- | | `pause()` / `unpause()` | Emergency stop/start | | `updateTreasury()` | Set new treasury address and fee percent | | `updateTokenPair()` | Change underlying token0/token1 addresses | | `updateAmountLimits()` | Change min/max limits for token0/token1 | | `setDeviation()` | Adjust TWAP deviation for volatility check | | `emergencyWithdraw()` | Recover stuck funds from contract (any ERC20) | | `addAdmin()` / `removeAdmin()` | Manage ADMIN\_ROLE | *** #### Internal Design Notes * **Caching**: `currentState()` caches tick/price info for 60 seconds to optimize gas across frequent liquidity actions. * **Volatility Guard**: all transactions require minimum amounts according to the slippage required. * **Composability**: Designed to be extended for specific pool integrations via `BasePositionManager`. *** #### Extensibility Because `BasePositionManager` is an abstract class, we can reuse this structure for: * Uniswap V3 (by overriding `currentTick()` and `_twap()`) * Other Algebra forks (e.g., THENA, Velodrome v2) * Custom fee managers * Time-locked vault integrations *** #### Example Use Case ```solidity solidityCopyEdit// Minting liquidity IERC20(token0).approve(address(positionManager), amt0); IERC20(token1).approve(address(positionManager), amt1); (uint256 tokenId, , , ) = positionManager.mintLiquidity( amt0, amt1, -887220, 887220, // full range 0, 0 // slippage ); // Collecting fees positionManager.collectFees(tokenId, msg.sender); // Full exit positionManager.burnLiquidity(tokenId, msg.sender, 0, 0); ``` # DeFi Agent Agent to calculate the upper and lower tick to place the liquidity in. ### Dynamic Tick Placement & Agentic Rebalancing The **Meow Agent** is an autonomous strategy module that uses real-time market data to manage concentrated liquidity positions. It: * Analyzes pool conditions and volatility * Calculates optimal tick ranges * Decides when to rebalance or rotate capital Designed for **Camelot V3**, **Uniswap V3**, and other **Algebra-based AMMs**, it helps market makers and DAOs maximize capital efficiency while controlling risk and gas costs. *** #### What It Does **Dynamic Tick Discovery**\ Continuously scans pool state (price, TWAP, liquidity depth, volatility) to set the best lower/upper ticks for liquidity deployment. **Rebalance Signaling**\ Tracks position drift and inefficiency. Triggers rebalance signals when liquidity moves out of its optimal range or performance declines. **Volatility-Aware Adjustments**\ Avoids rebalancing during unstable market phases using TWAP deviation, tick skew, and volatility bands. **Capital-Aware Deployment**\ Places liquidity where it earns the highest fees for the given risk, factoring in slippage, token ratios, and capital limits. *** #### Use Cases * **Protocol-Owned Liquidity (POL)** – Adaptive, policy-driven DAO liquidity management * **Automated LP Bots** – Trigger on-chain mints/burns via vaults or keepers * **Retail Vaults** – Optimize liquidity for passive LP users * **Strategy Builders** – Plug-in module for advanced market-making *** #### Sample Workflow 1. **Price Monitoring** – Fetch current tick, sqrtPrice, liquidity distribution 2. **Tick Computation** – Use volatility, TWAP, and strategy rules to select an optimal range 3. **Rebalance Evaluation** – Check range boundaries, fee performance, and capital at risk 4. **Signal Trigger** – If deviation exceeds threshold, emit a rebalance signal 5. **Execution (Optional)** – Executor burns old position, mints new liquidity, routes fees to treasury *** #### Security-First Design * Works with TWAP-based volatility guards (e.g., *onlyCalmPeriods*) * Enforces capital bounds, slippage limits, and time-locks * Avoids rebalancing during oracle lags or flash crashes **In short:** Meow Agents keep your liquidity in the most profitable range - automatically, intelligently, and without giving up custody. # Case Studies Explore real-world scenarios where Alloc8’s agentic intelligence, policy-based execution has optimized liquidity performance. From DAOs managing millions in protocol-owned liquidity to retail users seeking hands-off yield, these case studies show measurable results and practical workflows. #### **Example Case Studies** **1. DAO Treasury - Camelot V3 Liquidity Optimization** **Challenge:** DAO-held liquidity was frequently out of range, losing fee opportunities.\ **Solution:** Meow Agent dynamically adjusted tick ranges based on volatility bands and TWAP.\ **Result:** 63% higher fee capture vs. static ranges, with fewer than 5 rebalances per week, minimizing gas costs. *** **2. Retail LP - Passive Uniswap V3 Positioning** **Challenge:** Small LP user lacked time and tools to monitor ranges and rebalance manually.\ **Solution:** Used a Meow Agent vault to automatically deploy capital into optimal ranges.\ **Result:** Maintained >95% of capital in range over 30 days, improving returns with minimal intervention. *** **3. Automated LP Bot - Arbitrage-Resistant Liquidity** **Challenge:** Frequent price swings caused inefficient range positions during high volatility.\ **Solution:** Integrated Meow Agent with volatility-aware policies to pause rebalances in unstable periods.\ **Result:** Reduced impermanent loss exposure by \~18% compared to continuous rebalancing strategies. *** These examples are just the beginning - the same principles apply to any AMM or liquidity strategy. # Security Model Alloc8’s security posture is built around three layers: #### 1) Smart Account layer * Funds reside in your Smart Account. * Actions execute through ERC-4337 entrypoint flows. #### 2) Authorization layer (Session + Policy) * A session agent must be bound to your account session. * GSPM enforces: * allowed agents/tokens * recipient pinning * slippage and deviation constraints * function/target constraints for sensitive flows #### 3) Execution layer (validated calls) * Position management executes via Position Manager. * Price-aware enforcement uses the Oracle System. #### Key guarantee to internalize An agent can only do what the policy allows. This is not a claim that all losses are preventable; rather, it is an authorization boundary intended to prevent unauthorized fund movement and uncontrolled execution. # Threat Model This model highlights realistic failure/attack scenarios and the intended mitigations. #### A. Session agent key compromise **Scenario:** An attacker gains control of the agent signer. **Mitigations** * Recipient pinning prevents arbitrary destination changes * Allowlists prevent calling arbitrary contracts/tokens * Rolling budgets cap cumulative loss (reverts beyond cap) **Operator response** * Pause agent * Rotate/revoke session key * Withdraw/reduce exposure until confident #### B. Oracle failure or manipulation **Scenario:** Oracle providers revert, are misconfigured, or return incorrect values. **Mitigations** * Fallback provider logic (main → backup) * Revert when both fail, or the asset is unsupported **Operator response** * Pause agent * Withdraw funds from the pool to the user's Smart Wallet if needed * Do not widen slippage to force execution during Oracle instability #### C. External protocol risk (AMM/router) **Scenario:** Underlying AMM contracts or routers behave unexpectedly or are attacked. **Mitigations** * Restrict targets/selectors to known integrations * Enforce min-out and deviation budgets **Operator response** * Pause agent * Withdraw funds from the pool to the user's Smart Wallet if needed * Follow incident communications #### D. Admin key risk/configuration risk **Scenario:** Admin-controlled parameters are misconfigured or compromised. **Mitigations** * Minimize admin surface area * Operational controls (multisig, timelocks, reviews) — document explicitly **Operator response** * If an incident is suspected, pause the agent & contracts * Verify official communications and on-chain changes # Risks & Limitations Alloc8 automation does not remove fundamental DeFi risks. #### Smart contract risk Bugs or vulnerabilities in: * Alloc8 contracts/modules * Integrated AMMs/routers * Token contracts #### Market risks * Impermanent loss * Range risk (out-of-range positions) * Fee volatility * Sudden volatility spikes #### Oracle risk * Feed failure causes reverts * Wrong prices can block or mis-evaluate min-out checks #### Execution risk * High gas/congestion may delay execution * Repeated reverts can cause “missed” rebalances #### Practical guidance * Start small * Keep policy settings conservative * Pause if behavior is unclear # Vulnerability Disclosure If you believe you have found a security issue, follow responsible disclosure. #### How to report * Provide a clear description, reproduction steps, and impacted contracts. * Include chain, transaction hashes, and addresses. #### Disclosure expectations * Do not publicly disclose until the team confirms remediation or a timeline. * The team should acknowledge receipt and provide a response timeline. Email us at # Deployment Addresses #### Arbitrum | Contract | Address | | ------------------------------- | ------------------------------------------ | | Modular4337Factory | 0x3b512F1967473c6272B9f7b075A086F76cA05f04 | | Modular4337Account | 0xC227b9329F2c60D638F794AeA38cADba2400e783 | | CamelotPositionManagerFactory | 0x514a67D2D1CADc94755dF710E554Cf488A7982A3 | | UniswapV3PositionManagerFactory | 0xcAF327770d0ad7609E6931F2A0E5cb2f8ee0cfaF | | GlobalSessionPolicyModule | 0xDc40bD4Ce436106658871D22d60A4e4418BDe8E9 | > Audits :- [Trust Security Audit](https://github.com/devsxtra/Alloc8_Audits/blob/main/Trust%20Security%20Audit%20v1.pdf) #### Verification guidance * Verify contract addresses on an official block explorer. * Confirm the UI is referencing these same addresses. * Treat address mismatches as a high-risk indicator. # Fees Alloc8 charges a **10% performance fee** on **realized yield** (profits). This fee applies only to yield earned (such as LP trading fees and other supported harvested rewards, depending on the strategy). It does **not** apply to your deposited principal. If no yield is realized at the time of collection, **no performance fee is charged**. #### When the fee is collected The performance fee is collected only when Alloc8 collects/compounds yield during: * **Rebalance execution**, or * **Autocompound execution** (runs every Sunday at 7:00 PM UTC) #### Example If your position realizes **$100** in yield at a rebalance/autocompound event: * Performance fee (10%): **$10** * Net yield added to your position (90%): **$90** #### Verifying on-chain To verify fee collection: 1. Open the rebalance/autocompound transaction in a block explorer. 2. Locate the step where yield is collected/compounded. 3. Confirm that a portion of realized yield is routed to the **protocol treasury/fee recipient**, and the remainder follows your **Smart Account/position** flow per the strategy. #### Gasless rebalances and execution conditions * Rebalances and autocompounds are **gasless for users** on Alloc8. The protocol pays gas, and these costs are subsidized from the performance fee. * Rebalances are triggered dynamically, typically when:\ **fees/yield earned by your position > gas cost to run the rebalance.** * If gas becomes very high, it may be uneconomical to rebalance smaller positions. In such cases, your position may appear **out of range** on the frontend until rebalancing becomes economical again. We recommend a position size of at least **$500** for smoother rebalances. #### Fee changes The performance fee is currently **10%**. Any future updates will be **communicated to users**. #### Quick FAQs 1. **Do I pay gas for rebalances or autocompound?**\ No. Rebalances and autocompounds are **gasless for users**. The protocol pays gas, and this cost is covered using part of the performance fee.
2. **Why didn’t my position rebalance / why is it out of range?**\ Rebalances usually happen when earned fees/yield are higher than the gas cost to run the rebalance. If gas costs rise a lot, it can become uneconomical to rebalance smaller positions, so your position may remain out of range until conditions improve.
3. **Is there a recommended position size?**\ Yes. We recommend $500 or more for smoother and more consistent rebalances.
4. **Can the fee change?**\ The performance fee is currently **10%**. If it changes, Alloc8 will **inform users**.