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
epochCounter
uint256 epochCounter
Epoch counter
bufferAmount
uint256 bufferAmount
Live buffer amount [assets]
pendingProtocolFees
uint256 pendingProtocolFees
Pending protocol fees [assets]
_failedEpochTokens
address[] _failedEpochTokens
Tokens that failed during the current epoch's sell/buy execution (cleared at epoch end)
initialEpochBufferAmount
uint256 initialEpochBufferAmount
Buffer snapshot captured at epoch start and used as deterministic proof input anchor [assets]
_epochDeltaAmount
int256 _epochDeltaAmount
Epoch delta amount to apply when transitioning to ProcessVaultOperations.
EpochState
Struct to hold epoch state data
struct EpochState {
address[] vaultsEpoch;
mapping(address => uint256) pricesEpoch;
uint16 activeNettingFeeCoefficient;
uint16 activeRsFeeCoefficient;
mapping(address => struct IOrionVault.FeeModel) feeModel;
bytes32 epochStateCommitment;
}
_currentEpoch
struct LiquidityOrchestrator.EpochState _currentEpoch
Current epoch state
upgradeTimelock
address upgradeTimelock
Address of the upgrade timelock that must authorise all implementation upgrades
commitmentMinibatchSize
uint8 commitmentMinibatchSize
Number of vault leaves folded into the commitment per StateCommitment upkeep step
_commitmentBatchIndex
uint16 _commitmentBatchIndex
Number of vault leaves already folded this epoch
completedInCurrentMinibatch
uint16 completedInCurrentMinibatch
On-chain resume cursor for the active sell/buy minibatch window.
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 Used on _executeSell and executeBuy so they can stay external (required for try/catch)
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 |
updateCommitmentMinibatchSize
function updateCommitmentMinibatchSize(uint8 _commitmentMinibatchSize) external
Updates the number of vault leaves folded per StateCommitment upkeep step.
Parameters
| Name | Type | Description |
|---|---|---|
| _commitmentMinibatchSize | uint8 | The new commitment 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
Callable mid-epoch for maintenance. The owner must coordinate with the zk-orchestrator so proofs submitted after this change are verified by the new contract.
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
Callable mid-epoch for maintenance. Reverts with InvalidArguments if newvKey is bytes32(0). The owner must coordinate with the zk-orchestrator so proofs submitted after this change match the new verification key and current epoch commitments.
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 state transition payload. |
_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 vaults list for the epoch
_processCommitmentMinibatch
function _processCommitmentMinibatch() internal
Folds the next batch of vault leaves into the running accumulator.
_buildProtocolStateHash
function _buildProtocolStateHash() internal returns (bytes32 protocolStateHash)
Builds the protocol state hash from static epoch parameters.
Return Values
| Name | Type | Description |
|---|---|---|
| protocolStateHash | 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 |
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 |
_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 state transition payload. |
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 |
_processMinibatchLeg
function _processMinibatchLeg(address[] tokens, uint256[] amounts, uint256[] estimatedUnderlyingAmounts, bool isSell) internal
Processes the next sell or buy minibatch window with resume support
Parameters
| Name | Type | Description |
|---|---|---|
| tokens | address[] | Leg token addresses |
| amounts | uint256[] | Leg share amounts |
| estimatedUnderlyingAmounts | uint256[] | Leg underlying estimates |
| isSell | bool | True for sell leg, false for buy leg |
_handleMinibatchLegFailure
function _handleMinibatchLegFailure(address token) internal
Records a failed minibatch leg and refreshes the epoch commitment without advancing the minibatch index
Parameters
| Name | Type | Description |
|---|---|---|
| token | address | The address of the token for which the minibatch leg failed |
_finalizeMinibatchLeg
function _finalizeMinibatchLeg(bool isSell, bool legFinished) internal
Applies phase transitions after a minibatch window completes successfully
Parameters
| Name | Type | Description |
|---|---|---|
| isSell | bool | Whether this was the sell leg of the operation |
| legFinished | bool | Whether the minibatch leg has completed |
_applyBuyLegSettlement
function _applyBuyLegSettlement(uint256 bufferIncrease, uint256 epochProtocolFees) internal
Applies bufferIncrease, accrued exec dust, and epoch protocol fees at Buy→PVO.
Parameters
| Name | Type | Description |
|---|---|---|
| bufferIncrease | uint256 | Nominal buffer increase from the completing buy payload |
| epochProtocolFees | uint256 | Epoch protocol fees from the completing buy payload |
_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) |
_calculateMaxWithSlippage
function _calculateMaxWithSlippage(uint256 estimatedAmount) internal view returns (uint256)
Calculate maximum amount with slippage applied
Parameters
| Name | Type | Description |
|---|---|---|
| estimatedAmount | uint256 | The estimated amount |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | uint256 | The maximum amount with slippage applied |
_calculateMinWithSlippage
function _calculateMinWithSlippage(uint256 estimatedAmount) internal view returns (uint256)
Calculate minimum amount with slippage applied
Parameters
| Name | Type | Description |
|---|---|---|
| estimatedAmount | uint256 | The estimated amount |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | uint256 | The minimum amount with slippage applied |
_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
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[] vaultStates) internal
Handles the vault operations
_vaultStates[] shall match currentEpoch.vaultsEpoch[] in order
Parameters
| Name | Type | Description |
|---|---|---|
| vaultStates | struct ILiquidityOrchestrator.VaultState[] | The vault states |
_processSingleVaultOperations
function _processSingleVaultOperations(address vaultAddress, struct ILiquidityOrchestrator.VaultState vaultState) internal
Processes deposit and redeem operations for a single vault
Parameters
| Name | Type | Description |
|---|---|---|
| vaultAddress | address | The vault address |
| vaultState | struct ILiquidityOrchestrator.VaultState | Epoch output state for this vault (plaintext portfolio and/or sealed ciphertext) |
setUpgradeTimelock
function setUpgradeTimelock(address newTimelock) external
Sets the upgrade timelock address.
If no timelock is set yet, only the owner may call this. Once a timelock is active, only the timelock itself may replace it, preventing the owner from bypassing the delay.
Parameters
| Name | Type | Description |
|---|---|---|
| newTimelock | address | The new timelock address (e.g. OpenZeppelin TimelockController); address(0) not permitted |
_authorizeUpgrade
function _authorizeUpgrade(address) internal view
Authorizes an upgrade to a new implementation
Requires the caller to be the upgrade timelock (if set) or the owner (during initial bootstrapping before a timelock has been configured).