> For the complete documentation index, see [llms.txt](https://docs.ontorium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ontorium.io/ontorium-stack-overview/financial-layer/aqua-vaults/smart-contracts.md). # Smart Contracts This page provides an architecture overview of the AQUA Vault contract system for developers, auditors, integrators, and advanced users. ### Architecture Overview ``` User │ deposit / mint / withdraw / redeem / claim ▼ Vault │ ERC-4626-based accounting and integrated ERC-20 vault shares │ allocation / deallocation / withdrawal queue / fees ▼ StrategyManager ├── On-chain Strategy A (for example, AQUA Market) ├── On-chain Strategy B (for example, an external lending market) └── OffchainNAVStrategy (reported off-chain positions) Access and safety modules: RoleManager · Gates · Timelock · Strategy Registry ``` The Vault is the primary user-facing contract. The StrategyManager stores approved-strategy configuration, allocation caps, strategy status, and aggregate strategy views. Individual strategy contracts implement the asset-specific accounting and capital-flow logic. ### Vault The Vault is based on the ERC-4626 tokenized-vault model and also acts as the ERC-20 share token. It: * Accepts one underlying deposit asset * Mints and burns vault shares * Tracks recognized vault assets and share accounting * Exposes ERC-4626-style conversion and preview functions * Applies configured deposit, withdrawal, management, and performance fees * Allocates and deallocates assets through approved strategies * Supports immediate withdrawals and queued withdrawals * Tracks pending, reserved, and claimable withdrawal amounts * Integrates configurable asset and share Gates AQUA Vaults extend standard ERC-4626 behavior. Actual share conversions may include virtual-share adjustments, rounding rules, fees, strategy accounting, and withdrawal-queue logic. Because user eligibility may depend on external Gate contracts, certain ERC-4626 maximum functions may intentionally return zero rather than attempting a potentially reverting eligibility check. For queued withdrawals, shares are burned when the withdrawal request is submitted. The user receives the underlying asset later, after the request has been fulfilled and claimed. See Withdrawals. ### Vault Shares Vault shares are issued directly by the Vault contract as ERC-20-compatible tokens. A share represents a proportional claim on the vault's recognized assets. Its value changes with the vault's NAV, fee-share issuance, and the performance of the underlying strategies. Share transfers may be restricted by the configured receive-share and send-share Gates. For additional information, see NAV & Share Price. ### StrategyManager The StrategyManager stores and validates strategy-related configuration for a specific Vault. Its responsibilities include: * Maintaining the list of approved strategies * Recording whether each strategy is active * Classifying strategies as on-chain or off-chain NAV strategies * Maintaining target allocation information * Enforcing absolute and relative allocation caps * Recording force-deallocation penalties * Aggregating reported strategy assets * Aggregating strategy-reported available liquidity * Detecting stale off-chain exposure that should block new vault entry The Vault executes allocation and deallocation operations. The StrategyManager validates and records the resulting allocation changes through Vault-only hooks. Strategy addition, removal, activation, classification, and cap increases are governance-controlled operations. A strategy must report zero assets before it can be removed. Strategy-reported available liquidity is an aggregate informational value. It should not be interpreted as the amount immediately available for a user withdrawal. Instant withdrawal capacity depends on assets already available to the Vault after amounts committed to other withdrawals are excluded. ### Strategy Contracts Each approved strategy implements the common strategy interface used by the Vault and StrategyManager. Depending on the strategy, the interface may expose: * `allocate` * `deallocate` * `totalAssets` * `availableLiquidity` * Strategy-specific identifiers or configuration data On-chain strategies derive their positions and valuations from blockchain state. For example, a lending strategy may report the current value of supplied assets, including interest recognized by the underlying protocol. Strategies are implemented as separate modules so that accounting and integration logic can be reviewed independently. This modular structure does not eliminate strategy risk. Losses, illiquidity, integration failures, or external-protocol failures may still affect the Vault. ### OffchainNAVStrategy The OffchainNAVStrategy represents approved positions whose value or settlement depends on off-chain activity. It maintains accounting for: * Assets reported as held off-chain * Reported available off-chain liquidity * Assets requested for return but not yet received * On-chain idle assets held by the strategy * The latest report hash, report URI, and report timestamp Two strategy-specific roles are used: * **Off-chain reporter**: submits NAV and liquidity reports * **Off-chain manager**: manages approved capital deployment and return flows These permissions are scoped through the shared RoleManager. An authorized reporter submits: * Reported assets * Reported available liquidity * Pending receivables * `reportHash` * `reportURI` The last reported NAV remains part of strategy accounting even after the report becomes stale. To prevent outdated valuations from pricing new shares, the Vault may block new deposits and minting while stale off-chain exposure remains. Withdrawals are not automatically blocked solely because an off-chain report is stale. However, settlement remains subject to available liquidity and may enter the withdrawal queue. Reported available liquidity is not the same as immediate Vault liquidity. Off-chain liquidity may still require recovery, transfer, or settlement before it can support a claim. The reporting format is described in Transparency & Reporting. ### RoleManager The RoleManager is a shared, scope-based access-control registry. Roles are namespaced by Vault or module so that one RoleManager deployment can manage multiple Vault systems independently. The primary Vault roles are: | Role | Purpose | | ----------------- | -------------------------------------------------------------------------- | | `GOVERNANCE_ROLE` | Governance configuration and privileged parameter changes | | `CURATOR_ROLE` | Risk configuration and timelock scheduling | | `SENTINEL_ROLE` | Emergency actions and cancellation of pending timelock operations | | `ALLOCATOR_ROLE` | Strategy allocation, deallocation, rebalancing, and withdrawal fulfillment | Off-chain strategies also use strategy-specific scoped roles for reporting and off-chain capital management. Fee-recipient addresses are configuration recipients, not access-control roles. Role membership changes are recorded through standard `RoleGranted` and `RoleRevoked` events. ### Gates The Vault can use four independent Gate contracts: | Gate | Check | | ------------------- | ----------------------------------------------------------- | | Receive Shares Gate | Whether an address may receive vault shares | | Send Shares Gate | Whether an address may send or redeem vault shares | | Receive Assets Gate | Whether an address may receive the underlying asset | | Send Assets Gate | Whether an address may deposit or send the underlying asset | Gate implementations can support controls such as allowlists, wallet eligibility, compliance restrictions, or share-transfer restrictions. Gates do not define the Vault's emergency pause behavior. Pause controls are handled separately by the Vault. ### Timelock The Timelock is a delay-based execution wrapper for selected privileged calls. A typical flow is: ``` Curator schedules a call → configured delay passes → anyone executes the exact scheduled call ``` A Curator or Sentinel can revoke a pending operation before execution. Timelock duration is configured by target contract and function selector. Whether a specific governance action is delayed therefore depends on the production configuration. The existence of the Timelock should not be interpreted as meaning that every privileged function automatically has a non-zero delay. Increasing a timelock can be performed immediately. Reducing an existing timelock must itself wait through the current delay, helping prevent a privileged key from weakening protection instantly. Emergency actions available directly to the Sentinel are separate from scheduled governance operations. ### Pause and Emergency Controls The Vault can be paused by an authorized Sentinel and unpaused by Governance. While paused: * New deposits and minting are disabled * New allocations are disabled * Deallocation remains available * Withdrawals and claims remain available, subject to liquidity Additional emergency and risk controls may include: * Strategy deactivation * Absolute and relative allocation-cap reductions * Forced deallocation with a configured penalty * Timelock-operation revocation * Stale off-chain entry blocking * Maximum-rate controls for positive NAV recognition ### Withdrawal Queue Accounting The withdrawal queue is maintained per user rather than through a separate request ID for each transaction. Multiple queued withdrawals for the same user may accumulate into one pending position. The lifecycle is: ``` Withdrawal requested → shares burned → pending withdrawal recorded → allocator fulfills all or part of the request → assets become reserved and claimable → user claims the ready amount ``` The Vault separately tracks: * Pending withdrawals * Assets reserved for fulfilled withdrawals * Claimable withdrawal assets * Assets committed to pending or claimable withdrawals The withdrawal fee applicable to a queued amount is recorded at the request stage. Later fee changes do not retroactively change the fee for that queued amount. ### Events Material Vault activity is recorded through contract events. #### User and withdrawal events * `Deposit` * `Withdraw` * `WithdrawalRequested` * `WithdrawalFulfilled` * `WithdrawalClaimed` #### Strategy events * `Allocate` * `Deallocate` * `ForceDeallocate` * `Rebalance` * `AfterAllocate` * `AfterDeallocate` #### Accounting and reporting events * `AccrueInterest` * `NAVReported` * `CapitalDeployed` * `ReturnRequested` * `CapitalReturned` * `ForceSyncReportedNAV` #### Governance and configuration events * `GovernanceSubmit` * `GovernanceAccept` * `GovernanceRevoke` * `Paused` * `Unpaused` * Strategy, Gate, fee, cap, role, and timelock configuration events The final deployed addresses and verified contract interfaces should be used as the authoritative reference for event signatures. ### Security Design The system includes several accounting and operational safeguards, including: * Virtual-share accounting to reduce ERC-4626 inflation-attack risk * Scoped role separation * Configurable governance delays * Separate emergency controls * Absolute and relative strategy caps * Strategy-registry validation, where configured * Stale-report entry blocking * Maximum-rate controls for positive NAV recognition * Share burning at queued-withdrawal request time * Reservation of fulfilled withdrawal assets before claim * Request-time withdrawal-fee recording * Checks-effects-interactions and reentrancy protections where applicable These controls reduce specific risks but do not eliminate smart-contract, strategy, liquidity, custody, oracle, or operational risk. ### Contract Addresses Contract deployments may be specific to each Vault. | Contract | Network | Address | | ------------------------------- | -------- | ------- | | USDC Vault | Arbitrum | TBD | | USDC StrategyManager | Arbitrum | TBD | | OXAU Vault | Arbitrum | TBD | | OXAU StrategyManager | Arbitrum | TBD | | OXAU OffchainNAVStrategy | Arbitrum | TBD | | RoleManager | Arbitrum | TBD | | Timelock | Arbitrum | TBD | | StrategyRegistry, if configured | Arbitrum | TBD | | Gate contracts, if configured | Arbitrum | TBD | Final addresses, source-code verification links, deployment configuration, and audit reports will be published before or at launch.