> ## Documentation Index
> Fetch the complete documentation index at: https://omo-89a50a4e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Omo Beacon Vault

> Discusses key differentiation between other vault products

> [tab] Core Concepts
>
> # Overview
>
> Omo Protocol introduces a groundbreaking approach to asset management in decentralized finance (DeFi). By leveraging state-of-the-art technologies and innovative design principles, Omo aims to simplify and enhance the DeFi experience for users of all levels. Let's explore the key concepts that make Omo Protocol unique and powerful, starting with a comparison between traditional approaches and Omo's innovative solution.
>
> ## Evolving DeFi: From Traditional to Agentic
>
> ### The Standard Approach: Router and Adapter Contracts
>
> Traditionally, DeFi protocols rely on a complex system of smart contracts to manage user funds and execute strategies.
>
> > [accordion] Router Contracts
> >
> > Router contracts serve as the primary entry point for user interactions in traditional DeFi protocols. They play a crucial role in:
> >
> > * Directing user funds to the appropriate contracts within the protocol ecosystem
> > * Routing function calls to the correct implementation contracts
> > * Managing access control and permissions for various protocol functions
> > * Orchestrating complex multi-step transactions across multiple contracts
> >
> > While router contracts provide a centralized point of interaction, they can also introduce additional complexity and potential security risks due to their pivotal role in the system.
>
> > [accordion] Adapter Contracts
> >
> > Adapter contracts act as intermediaries between the main protocol and external DeFi platforms. Their key functions include:
> >
> > * Translating generic calls from the main protocol into protocol-specific actions
> > * Handling the intricacies of interacting with various external DeFi protocols
> > * Normalizing data and function calls across different platforms
> > * Implementing safety checks and fail-safes for external interactions
> >
> > While adapter contracts enable protocols to interact with a wide range of external platforms, they also introduce additional layers of complexity and potential points of failure in the system.
>
> This approach has several limitations:
>
> * **Complexity**: Multiple contract interactions increase the risk of errors and
>   vulnerabilities.
>
> * **Rigidity**: Adapting to new protocols or strategies often requires writing and auditing
>   new smart contracts.
>
> * **Security Vulnerabilities**: Multiple contract interactions increase attack surface and potential for exploits.
>
>    
>
>    
>
>   ![Traditional DeFi Flow](https://mintcdn.com/omo-89a50a4e/ycZMjmbgDP3Seizg/diagrams/traditional-flow.svg?fit=max\&auto=format\&n=ycZMjmbgDP3Seizg\&q=85\&s=b810153092581f4eeb16482c5fab83f6)
>
>   Traditional Flow
>
> ### Omo's Innovation: Agentic Workflow
>
> Omo Protocol replaces the traditional router and adapter contract system with an agentic workflow:
>
> * **AI-Powered Agents**: Smart, programmable wallets that execute DeFi strategies directly, interacting with protocols like a savvy user would, without intermediary contracts.
> * **Flexible Automation**: Strategies can be updated and optimized without changing underlying smart contracts.
> * **Cross-VM Capability**: Agents can seamlessly operate across different virtual machines and blockchain architectures, enabling user-centric composability unprecedented in the industry
>
>   ![Traditional DeFi Flow](https://mintcdn.com/omo-89a50a4e/ycZMjmbgDP3Seizg/diagrams/agenticflow.svg?fit=max\&auto=format\&n=ycZMjmbgDP3Seizg\&q=85\&s=a2f4b88a19a6adc2293e88e87d2aa628)
>
>   Agentic Flow
>
> #### Benefits of the Agentic Workflow:
>
> The agentic workflow reduces complexity by minimizing potential vulnerabilities associated with complex smart contract interactions, while improving adaptability by allowing agents to quickly adjust to new protocols and market conditions.
>
>  
>
> ## Beacon Vault
>
> The Omo Beacon Vault utilizes the 7540 EIP to facilitate asynchronous deposists and redeems. Here the user deposits into the vault, and based on arbitrary epoch. Their request deposit will be fulfilled, while simultaneously when the requestDeposit() event is emitted. That is then converted into a webhook which serves to ping the agent to call the `borrow()` when the users capital is present.
>
>  
>
> ![](https://mintcdn.com/omo-89a50a4e/ycZMjmbgDP3Seizg/diagrams/FinalAsynchVault.svg?fit=max\&auto=format\&n=ycZMjmbgDP3Seizg\&q=85\&s=7e90685a9943df6a50166da2b0001045)
>
> Asynch Vault & Agent Flow
>
> ### Deposit Flow
>
> The deposit flow begins when a user calls the `requestDeposit()` function. This action generates a unique `requestId`, which identifies the user as the `controller` of the funds in the asynchronous vault. After an arbitrary epoch has passed, the `deposit()` function is triggered, minting shares for the user and effectively moving the funds into the vault. Simultaneously, the `DepositRequested` event log is emitted and converted into a webhook. This webhook pings the agent to call the `borrow()` function, initiating the agent-powered structured product.
>
> ### Redemption Flow
>
> The redemption process starts when a user calls the `requestRedeem()` function. This action burns the user's shares and uses the unique `requestId` to parse through the vault capital. The redemption is executed when the `claimRedeem()` function is called, which triggers the internal `_executeRedeems()` function. This function returns the user's principal deposit along with any profits. Concurrently, the `RedeemRequested` event log is emitted and converted into a webhook. This webhook alerts the agent to unwind the position specific to the user's `requestId`.

> [tab] Advanced
>
> # OmoVault.sol
>
> ## Overview
>
> OmoVault is a sophisticated ERC7540-compliant vault contract that extends Solmate's ERC4626 implementation. It provides functionality for asynchronous deposits and redemptions, agent-driven processing, and management of locked and unlocked assets. The contract also incorporates features for borrowing and repaying assets, making it a versatile tool in the Omo Protocol ecosystem.
>
> ## Key Components
>
> ### State Variables
>
> 1. `mapping(uint256 => _DepositRequest) public _depositRequests`: Stores deposit requests.
> 2. `mapping(uint256 => _RedeemRequest) public _redeemRequests`: Stores redeem requests.
> 3. `mapping(address => mapping(address => bool)) public isOperator`: Tracks operator status for controllers.
> 4. `mapping(address => uint256) public owed`: Tracks owed amounts for each address.
> 5. `mapping(address => mapping(address => uint256)) public claimable`: Tracks claimable amounts for each sender-owner pair.
> 6. `uint256 public currentDepositRequestId`: Counter for deposit request IDs.
> 7. `uint256 public currentRedeemRequestId`: Counter for redeem request IDs.
> 8. `uint256 public nextDepositRequestIdToSettle`: Next deposit request ID to process.
> 9. `uint256 public nextRedeemRequestIdToSettle`: Next redeem request ID to process.
> 10. `uint256 internal _totalAssets`: Total assets in the vault.
> 11. `uint256 public supplyCap`: Maximum supply cap for the vault.
> 12. `uint256 public index`: Current index value for share price calculation.
> 13. `uint256 internal _credit`: Total credit in the vault.
> 14. `uint256 internal _totalOwed`: Total amount owed by the vault.
> 15. `IAgentSetter public immutable agentSetter`: Reference to the AgentSetter contract.
>
> ### Structs
>
> 1. `_DepositRequest`:
>
> | Field | Type | Description |
> | - | - | - |
> | controller | address | Address controlling the request |
> | owner | address | Address owning the assets |
> | requestId | uint256 | Unique identifier for the request |
> | sender | address | Address initiating the request |
> | assets | uint256 | Amount of assets involved |
>
> 2. `_RedeemRequest`:
>
> | Field | Type | Description |
> | - | - | - |
> | controller | address | Address controlling the request |
> | owner | address | Address owning the shares |
> | requestId | uint256 | Unique identifier for the request |
> | sender | address | Address initiating the request |
> | assets | uint256 | Amount of assets to redeem |
>
> ### Events
>
> 1. `VaultInitialized(address indexed asset, string name, string symbol, address owner)`
> 2. `TopOff(address msgSender, uint256 assets)`
> 3. `Repay(address msgSender, address receiver, uint256 assets)`
> 4. `Borrow(address msgSender, address receiver, uint256 assets)`
> 5. `RedeemRequestInitiated(address owner, uint256 shares, address controller)`
> 6. `DepositRequested(address indexed user, uint256 assets, uint256 shares, uint256 requestId)`
> 7. `DepositFulfilled(address indexed user, uint256 assets, uint256 shares, uint256 requestId)`
> 8. `RedeemRequested(address indexed user, uint256 assets, uint256 shares, uint256 requestId)`
> 9. `RedeemFulfilled(address indexed user, uint256 assets, uint256 shares, uint256 requestId)`
> 10. `AssetsLocked(uint256 amount)`
> 11. `AssetsUnlocked(uint256 amount)`
> 12. `RequestTimedOut(uint256 requestId, bool isDeposit)`
> 13. `SharesMinted(address indexed to, uint256 amount)`
> 14. `SharesBurned(address indexed from, uint256 amount)`
> 15. `AssetsTransferred(address indexed from, address indexed to, uint256 amount)`
>
> ### Custom Errors
>
> 1. `InsufficientAssets()`
> 2. `InsufficientShares()`
> 3. `InvalidRequestId()`
> 4. `RequestAlreadyExecuted()`
> 5. `Unauthorized()`
> 6. `InvalidAddress()`
>
> ## Functions
>
> ### Constructor
>
> ```solidity theme={null}
> constructor(
>     ERC20 _asset,
>     string memory _name,
>     string memory _symbol,
>     IAgentSetter _agentSetter
> )
> ```
>
> Initializes the OmoVault with the underlying asset, name, symbol, and AgentSetter contract.
>
> ### `requestDeposit`
>
> ```solidity theme={null}
> function requestDeposit(
>     uint256 assets,
>     address controller,
>     address owner
> ) external nonReentrant returns (uint256 requestId)
> ```
>
> Creates a new deposit request. Returns the unique request ID.
>
> ### `pendingDepositRequest`
>
> ```solidity theme={null}
> function pendingDepositRequest(
>     uint256 requestId,
>     address controller
> ) external view returns (uint256 pendingAssets)
> ```
>
> Returns the pending assets for a deposit request.
>
> ### `claimableDepositRequest`
>
> ```solidity theme={null}
> function claimableDepositRequest(
>     uint256 requestId,
>     address controller
> ) external view returns (uint256 claimableAssets)
> ```
>
> Returns the claimable assets for a deposit request.
>
> ### `deposit`
>
> ```solidity theme={null}
> function deposit(
>     uint256 assets,
>     address receiver,
>     address controller
> ) external nonReentrant returns (uint256 shares)
> ```
>
> Deposits assets and mints shares.
>
> ### `mint`
>
> ```solidity theme={null}
> function mint(
>     uint256 shares,
>     address receiver,
>     address controller
> ) external nonReentrant returns (uint256 assets)
> ```
>
> Mints shares by depositing assets.
>
> ### `requestRedeem`
>
> ```solidity theme={null}
> function requestRedeem(
>     uint256 shares,
>     address controller,
>     address owner
> ) external nonReentrant returns (uint256 requestId)
> ```
>
> Creates a new redeem request. Returns the unique request ID.
>
> ### `pendingRedeemRequest`
>
> ```solidity theme={null}
> function pendingRedeemRequest(
>     uint256 requestId,
>     address controller
> ) external view returns (uint256 pendingShares)
> ```
>
> Returns the pending shares for a redeem request.
>
> ### `claimableRedeemRequest`
>
> ```solidity theme={null}
> function claimableRedeemRequest(
>     uint256 requestId,
>     address controller
> ) external view returns (uint256 claimableShares)
> ```
>
> Returns the claimable shares for a redeem request.
>
> ### `claimRedeem`
>
> ```solidity theme={null}
> function claimRedeem(uint256 requestId) external nonReentrant returns (uint256 assets)
> ```
>
> Allows users to claim their redeemed assets.
>
> ### `processRedeems`
>
> ```solidity theme={null}
> function processRedeems(uint256 maxRedeems) external nonReentrant onlyAgent
> ```
>
> Allows agents to process multiple redeem requests.
>
> ### `setOperator`
>
> ```solidity theme={null}
> function setOperator(address operator, bool approved) external returns (bool success)
> ```
>
> Sets or removes an operator for the caller.
>
> ### `borrow`
>
> ```solidity theme={null}
> function borrow(uint256 assets, address receiver) external nonReentrant onlyAgent
> ```
>
> Allows agents to borrow assets from the vault.
>
> ### `repay`
>
> ```solidity theme={null}
> function repay(uint256 assets, address receiver) external nonReentrant onlyAgent
> ```
>
> Allows agents to repay a debt to the vault.
>
> ### `topOff`
>
> ```solidity theme={null}
> function topOff() external nonReentrant onlyAgent
> ```
>
> Deposits surplus assets into the vault.
>
> ## Internal Functions
>
> ### `_executeDeposit`
>
> ```solidity theme={null}
> function _executeDeposit(uint256 assets, address receiver) internal returns (uint256 shares)
> ```
>
> Executes a deposit operation.
>
> ### `_executeRedeems`
>
> ```solidity theme={null}
> function _executeRedeems(uint256 maxRedeems) internal
> ```
>
> Executes multiple redeem requests.
>
> ### `beforeWithdraw`
>
> ```solidity theme={null}
> function beforeWithdraw(uint256 assets, uint256 shares) internal override
> ```
>
> Hook called before withdrawing assets.
>
> ### `afterDeposit`
>
> ```solidity theme={null}
> function afterDeposit(uint256 assets, uint256 shares) internal override
> ```
>
> Hook called after depositing assets.
>
> ### `_increaseOwed`
>
> ```solidity theme={null}
> function _increaseOwed(address account, uint256 amount) internal
> ```
>
> Increases the amount owed by an account.
>
> ### `_decreaseOwed`
>
> ```solidity theme={null}
> function _decreaseOwed(address account, uint256 amount) internal
> ```
>
> Decreases the amount owed by an account.
>
> ### `_settle`
>
> ```solidity theme={null}
> function _settle(uint256 assets) internal returns (uint256)
> ```
>
> Settles outstanding redeem requests.
>
> ## Modifiers
>
> 1. `onlyAgent`: Restricts function access to whitelisted agents.
>
> ## Notes
>
> This contract implements the ERC7540 standard for asynchronous vaults, providing a robust framework for managing deposits, redemptions, and asset borrowing within the Omo Protocol ecosystem. It incorporates safety features such as reentrancy protection and carefully manages locked and unlocked assets to ensure the integrity of the vault's operations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.