LiquidityOrchestrator
LiquidityOrchestrator
Contract that orchestrates liquidity operations
_This contract is responsible for:
- Executing actual buy and sell orders on investment universe;
- Processing withdrawal requests from LPs;
- Handling slippage and market execution differences from adapter price estimates via liquidity buffer._
BASIS_POINTS_FACTOR
uint16 BASIS_POINTS_FACTOR
Basis points factor
automationRegistry
address automationRegistry
Chainlink Automation Registry address
config
contract IOrionConfig config
Orion Config contract address
underlyingAsset
address underlyingAsset
Underlying asset address
verifier
contract ISP1Verifier verifier
The address of the SP1 verifier contract.
vKey
bytes32 vKey
The verification key for the Orion Internal State Orchestrator.
priceAdapterRegistry
contract IPriceAdapterRegistry priceAdapterRegistry
Price Adapter Registry contract
executionAdapterOf
mapping(address => contract IExecutionAdapter) executionAdapterOf
Execution adapters mapping for assets
epochDuration
uint32 epochDuration
Epoch duration
executionMinibatchSize
uint8 executionMinibatchSize
Execution minibatch size
minibatchSize
uint8 minibatchSize
Minibatch size for fulfill deposit and redeem processing
currentPhase
enum ILiquidityOrchestrator.LiquidityUpkeepPhase currentPhase
Upkeep phase
currentMinibatchIndex
uint8 currentMinibatchIndex
Current minibatch index
targetBufferRatio
uint256 targetBufferRatio
Target buffer ratio
slippageTolerance
uint256 slippageTolerance
Slippage tolerance
MAX_MINIBATCH_SIZE
uint8 MAX_MINIBATCH_SIZE
Maximum minibatch size
MAX_EPOCH_DURATION
uint32 MAX_EPOCH_DURATION
Maximum epoch duration (2 weeks)
epochCounter
uint256 epochCounter
Epoch counter
bufferAmount
uint256 bufferAmount
Buffer amount [assets]
pendingProtocolFees
uint256 pendingProtocolFees
Pending protocol fees [assets]
EpochState
Struct to hold epoch state data
struct EpochState {
address[] vaultsEpoch;
mapping(address => uint256) pricesEpoch;
uint16 activeVFeeCoefficient;
uint16 activeRsFeeCoefficient;
mapping(address => struct IOrionVault.FeeModel) feeModel;
bytes32 epochStateCommitment;
}
_currentEpoch
struct LiquidityOrchestrator.EpochState _currentEpoch
Current epoch state
onlyAuthorizedTrigger
modifier onlyAuthorizedTrigger()
Restricts function to only owner or automation registry
onlyConfig
modifier onlyConfig()
Restricts function to only Orion Config contract
onlyOwnerOrGuardian
modifier onlyOwnerOrGuardian()
Restricts function to only owner or guardian
onlySelf
modifier onlySelf()
Restricts function to only self
constructor
constructor() public
Constructor that disables initializers for the implementation contract
initialize
function initialize(address initialOwner, address config_, address automationRegistry_, address verifier_, bytes32 vKey_) public
Initializes the contract
Parameters
| Name | Type | Description |
|---|---|---|
| initialOwner | address | The address of the initial owner |
| config_ | address | The address of the OrionConfig contract |
| automationRegistry_ | address | The address of the Chainlink Automation Registry |
| verifier_ | address | The address of the SP1 verifier contract |
| vKey_ | bytes32 | The verification key for the Orion Internal State Orchestrator |
updateEpochDuration
function updateEpochDuration(uint32 newEpochDuration) external
Updates the epoch duration
Parameters
| Name | Type | Description |
|---|---|---|
| newEpochDuration | uint32 | The new epoch duration in seconds |
updateExecutionMinibatchSize
function updateExecutionMinibatchSize(uint8 _executionMinibatchSize) external
Updates the execution minibatch size
Parameters
| Name | Type | Description |
|---|---|---|
| _executionMinibatchSize | uint8 | The new execution minibatch size |
updateMinibatchSize
function updateMinibatchSize(uint8 _minibatchSize) external
Updates the minibatch size for fulfill deposit and redeem processing
Parameters
| Name | Type | Description |
|---|---|---|
| _minibatchSize | uint8 | The new minibatch size |
updateAutomationRegistry
function updateAutomationRegistry(address newAutomationRegistry) external
Updates the Chainlink Automation Registry address
Parameters
| Name | Type | Description |
|---|---|---|
| newAutomationRegistry | address | The new automation registry address |
updateVerifier
function updateVerifier(address newVerifier) external
Updates the verifier contract address
Parameters
| Name | Type | Description |
|---|---|---|
| newVerifier | address | The address of the new verifier contract |
updateVKey
function updateVKey(bytes32 newvKey) external
Updates the internal state orchestrator verification key
Parameters
| Name | Type | Description |
|---|---|---|
| newvKey | bytes32 | The new verification key |
setTargetBufferRatio
function setTargetBufferRatio(uint256 _targetBufferRatio) external
Sets the target buffer ratio
Parameters
| Name | Type | Description |
|---|---|---|
| _targetBufferRatio | uint256 | The new target buffer ratio |
setSlippageTolerance
function setSlippageTolerance(uint256 _slippageTolerance) external
Sets the slippage tolerance
Parameters
| Name | Type | Description |
|---|---|---|
| _slippageTolerance | uint256 | The new slippage tolerance |
depositLiquidity
function depositLiquidity(uint256 amount) external
Deposits underlying assets to the liquidity orchestrator buffer
Increases the buffer amount by the deposited amount.
Parameters
| Name | Type | Description |
|---|---|---|
| amount | uint256 | The amount of underlying assets to deposit |
withdrawLiquidity
function withdrawLiquidity(uint256 amount) external
Withdraws underlying assets from the liquidity orchestrator buffer
Can only be called by the owner. Decreases the buffer amount by the withdrawn amount. Includes safety checks to prevent predatory withdrawals that could break protocol operations.
Parameters
| Name | Type | Description |
|---|---|---|
| amount | uint256 | The amount of underlying assets to withdraw |
claimProtocolFees
function claimProtocolFees(uint256 amount) external
Claim protocol fees with specified amount
Called by the Owner to claim a specific amount of protocol fees
Parameters
| Name | Type | Description |
|---|---|---|
| amount | uint256 | The amount of protocol fees to claim |
getEpochState
function getEpochState() external view returns (struct ILiquidityOrchestrator.EpochStateView)
Returns the full epoch state
Returns all epoch state data in a single struct. Use this instead of individual getters.
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | struct ILiquidityOrchestrator.EpochStateView | The complete epoch state view |
getFailedEpochTokens
function getFailedEpochTokens() external view returns (address[])
Returns tokens that failed during the current epoch's sell/buy execution
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | address[] | List of token addresses that failed |
setExecutionAdapter
function setExecutionAdapter(address asset, contract IExecutionAdapter adapter) external
Register or replace the execution adapter for an asset.
Can only be called by the Orion Config contract.
Parameters
| Name | Type | Description |
|---|---|---|
| asset | address | The address of the asset. |
| adapter | contract IExecutionAdapter | The execution adapter for the asset. |
pause
function pause() external
Pauses protocol operations for the orchestrator
Can only be called by guardian or owner for emergency situations
unpause
function unpause() external
Unpauses protocol operations for the orchestrator
Can only be called by owner after resolving emergency (not guardian: requires owner approval to resume)
returnDepositFunds
function returnDepositFunds(address user, uint256 amount) external
Return deposit funds to a user who cancelled their deposit request
Called by vault contracts when users cancel deposit requests
Parameters
| Name | Type | Description |
|---|---|---|
| user | address | The user to return funds to |
| amount | uint256 | The amount to return |
transferVaultFees
function transferVaultFees(uint256 amount) external
Transfer pending fees to manager
Called by vault contracts when managers claim their fees
Parameters
| Name | Type | Description |
|---|---|---|
| amount | uint256 | The amount of fees to transfer |
transferRedemptionFunds
function transferRedemptionFunds(address user, uint256 amount) external
Transfer redemption funds to a user after shares are burned
Called by vault contracts when processing redemption requests
Parameters
| Name | Type | Description |
|---|---|---|
| user | address | The user to transfer funds to |
| amount | uint256 | The amount of underlying assets to transfer |
withdraw
function withdraw(uint256 assets, address receiver) external
Synchronous redemption for decommissioned vaults
Called by vault contracts to process synchronous redemptions for LPs with share tokens
Parameters
| Name | Type | Description |
|---|---|---|
| assets | uint256 | The amount of underlying assets to withdraw |
| receiver | address | The address to receive the underlying assets |
checkUpkeep
function checkUpkeep() external view returns (bool upkeepNeeded)
Checks if upkeep is needed
the API is inspired but different from the Chainlink Automation interface.
Return Values
| Name | Type | Description |
|---|---|---|
| upkeepNeeded | bool | Whether upkeep is needed |
performUpkeep
function performUpkeep(bytes _publicValues, bytes proofBytes, bytes statesBytes) external
Performs the upkeep
the API is inspired but different from the Chainlink Automation interface.
Parameters
| Name | Type | Description |
|---|---|---|
| _publicValues | bytes | Encoded PublicValuesStruct containing input and output commitments |
| proofBytes | bytes | The zk-proof bytes |
| statesBytes | bytes | Encoded StatesStruct containing vaults, buy leg, and sell leg data |
_shouldTriggerUpkeep
function _shouldTriggerUpkeep() internal view returns (bool)
Checks if upkeep should be triggered based on time
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bool | True if upkeep should be triggered |
_handleStart
function _handleStart() internal
Handles the start of the upkeep
No need to delete prices as they are either overwritten or associated with non-whitelisted assets.
_buildVaultsEpoch
function _buildVaultsEpoch() internal
Build filtered transparent vaults list for the epoch
_buildEpochStateCommitment
function _buildEpochStateCommitment() internal view returns (bytes32)
Builds an epoch state commitment from the full epoch state
Uses domain separation for cryptographic robustness.
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bytes32 | The epoch state commitment |
_buildProtocolStateHash
function _buildProtocolStateHash() internal view returns (bytes32)
Builds the protocol state hash from static epoch parameters
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bytes32 | The protocol state hash |
_aggregateAssetLeaves
function _aggregateAssetLeaves(address[] assets, uint256[] assetPrices) internal pure returns (bytes32)
Aggregates asset leaves using sequential folding
Parameters
| Name | Type | Description |
|---|---|---|
| assets | address[] | Array of asset addresses |
| assetPrices | uint256[] | Array of asset prices |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bytes32 | The aggregated assets hash |
_aggregateVaultLeaves
function _aggregateVaultLeaves(struct ILiquidityOrchestrator.VaultStateData vaultData) internal view returns (bytes32)
Aggregates vault leaves using sequential folding
Parameters
| Name | Type | Description |
|---|---|---|
| vaultData | struct ILiquidityOrchestrator.VaultStateData | Struct containing all vault state data |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bytes32 | The aggregated vaults hash |
getAssetPrices
function getAssetPrices(address[] assets) public view returns (uint256[] assetPrices)
Gets asset prices for the epoch
Parameters
| Name | Type | Description |
|---|---|---|
| assets | address[] | Array of asset addresses |
Return Values
| Name | Type | Description |
|---|---|---|
| assetPrices | uint256[] | Array of asset prices |
_getVaultStateData
function _getVaultStateData() internal view returns (struct ILiquidityOrchestrator.VaultStateData vaultData)
Gets vault state data for all vaults in the epoch
Return Values
| Name | Type | Description |
|---|---|---|
| vaultData | struct ILiquidityOrchestrator.VaultStateData | Struct containing all vault state data |
_verifyPerformData
function _verifyPerformData(bytes _publicValues, bytes proofBytes, bytes statesBytes) internal view returns (struct ILiquidityOrchestrator.StatesStruct states)
Verifies the perform data
Parameters
| Name | Type | Description |
|---|---|---|
| _publicValues | bytes | Encoded PublicValuesStruct containing input and output commitments |
| proofBytes | bytes | The zk-proof bytes |
| statesBytes | bytes | Encoded StatesStruct containing vaults, buy leg, and sell leg data |
Return Values
| Name | Type | Description |
|---|---|---|
| states | struct ILiquidityOrchestrator.StatesStruct | The decoded StatesStruct |
_processMinibatchSell
function _processMinibatchSell(struct ILiquidityOrchestrator.SellLegOrders sellLeg) internal
Handles the sell action
Parameters
| Name | Type | Description |
|---|---|---|
| sellLeg | struct ILiquidityOrchestrator.SellLegOrders | The sell leg orders |
_processMinibatchBuy
function _processMinibatchBuy(struct ILiquidityOrchestrator.BuyLegOrders buyLeg) internal
Handles the buy action
Parameters
| Name | Type | Description |
|---|---|---|
| buyLeg | struct ILiquidityOrchestrator.BuyLegOrders | The buy leg orders |
_updateBufferAmount
function _updateBufferAmount(int256 deltaAmount) internal
Updates the buffer amount based on execution vs estimated amounts
Parameters
| Name | Type | Description |
|---|---|---|
| deltaAmount | int256 | The amount to add/subtract from the buffer (can be negative) |
_executeSell
function _executeSell(address asset, uint256 sharesAmount, uint256 estimatedUnderlyingAmount) external
Executes a sell order
Parameters
| Name | Type | Description |
|---|---|---|
| asset | address | The asset to sell |
| sharesAmount | uint256 | The amount of shares to sell |
| estimatedUnderlyingAmount | uint256 | The estimated underlying amount to receive |
_executeBuy
function _executeBuy(address asset, uint256 sharesAmount, uint256 estimatedUnderlyingAmount) external
Executes a buy order
The adapter handles slippage tolerance internally.
Parameters
| Name | Type | Description |
|---|---|---|
| asset | address | The asset to buy |
| sharesAmount | uint256 | The amount of shares to buy |
| estimatedUnderlyingAmount | uint256 | The estimated underlying amount to spend |
_processMinibatchVaultsOperations
function _processMinibatchVaultsOperations(struct ILiquidityOrchestrator.VaultState[] vaults) internal
Handles the vault operations
vaults[] shall match _currentEpoch.vaultsEpoch[] in order
Parameters
| Name | Type | Description |
|---|---|---|
| vaults | struct ILiquidityOrchestrator.VaultState[] | The vault states |
_processSingleVaultOperations
function _processSingleVaultOperations(address vaultAddress, uint256 totalAssetsForDeposit, uint256 totalAssetsForRedeem, uint256 finalTotalAssets, uint256 managementFee, uint256 performanceFee, address[] tokens, uint256[] shares) internal
Processes deposit and redeem operations for a single vault
Parameters
| Name | Type | Description |
|---|---|---|
| vaultAddress | address | The vault address |
| totalAssetsForDeposit | uint256 | The total assets for deposit operations |
| totalAssetsForRedeem | uint256 | The total assets for redeem operations |
| finalTotalAssets | uint256 | The final total assets for the vault |
| managementFee | uint256 | The management fee to accrue |
| performanceFee | uint256 | The performance fee to accrue |
| tokens | address[] | The portfolio token addresses |
| shares | uint256[] | The portfolio token number of shares |
_authorizeUpgrade
function _authorizeUpgrade(address newImplementation) internal
Authorizes an upgrade to a new implementation
This function is required by UUPS and can only be called by the owner
Parameters
| Name | Type | Description |
|---|---|---|
| newImplementation | address | The address of the new implementation contract |