Skip to main content

For AI agents: the complete documentation index is at llms.txt. Markdown versions of pages are available by appending .md to the URL or sending Accept: text/markdown.

Diagrams

Architecture

This page walks through the main Orion protocol flows as sequence diagrams: how liquidity providers deposit and redeem, how managers create vaults and submit intents, how third-party distributors attribute deposits, and how the zkVM keeper drives epoch execution.

The diagrams describe intended behavior at a high level. They omit timing edge cases, failure paths, partial fills, and the full escrow path when a holder check fails at fulfillment.

Liquidity Provider (LP) Journey​

Orion vaults follow an asynchronous ERC-7540-style model: LPs call requestDeposit or requestRedeem, requests queue until the next epoch, and the Liquidity Orchestrator fulfills them in batch. Share tokens mint only after fulfillDeposit runs at epoch end.

Vaults may optionally configure deposit and holder access controllers. At requestDeposit, the vault checks both canRequestDeposit and canHoldShares for the beneficiary. At fulfillDeposit, the vault re-checks canHoldShares so a mid-epoch policy revoke cannot mint shares; failed checks escrow underlying instead of minting. Transfer access control applies only to P2P share transfers, not to the deposit or redeem paths shown here.

Third-party distributors route deposits through requestDepositFor; see Distribution below.

Manager Journey​

A whitelisted manager deploys a vault through a factory, registers it with the protocol, and assigns a strategist. The strategist submits allocation intents (plaintext on transparent vaults, HPKE-sealed on encrypted vaults). Each rebalancing epoch updates portfolio state, accrues fees, and lets the manager claim vault fees.

Distribution​

Distribution lets third parties route user deposits into Orion vaults while attributing flow to a distributor identity. Attribution is recorded onchain for analytics, fee sharing, or partner reporting.

The reference implementation is OrionDistributionRouter.

How it works​

  1. A distributor integrates with OrionDistributionRouter (or a front end that calls it).
  2. The end user approves underlying assets and calls requestDepositWithDistribution(vault, distributorId, assets).
  3. The router verifies the vault is registered in OrionConfig, pulls assets from the user, and calls requestDepositFor(user, assets) on the vault.
  4. The router emits DistributionDeposit(distributorId, vault, user, assets) for offchain indexing.

Relationship to access control​

Distribution routing does not bypass vault access control. When the router calls requestDepositFor, the vault runs the same _requireCanRequestDeposit path as a direct LP deposit: both canRequestDeposit and canHoldShares must pass for the beneficiary. At fulfillDeposit, the vault re-checks canHoldShares before minting shares.

zkVM-based Keeper​

An offchain keeper polls the Liquidity Orchestrator via checkUpkeep. When upkeep is needed, it fetches epoch state, runs the zkVM program offchain to decrypt portfolios, generate orders, and produce a proof, then submits the result onchain for verification and execution.

Last updated on