InternalStateOrchestrator
InternalStateOrchestrator
Contract that orchestrates internal state management
_This contract is responsible for:
- Reading current vault states and market data;
- Processing vault fees and high water mark;
- Updating vault states;
- Computing state estimations for Liquidity Orchestrator;
- Trigger the Liquidity Orchestrator._
automationRegistry
address automationRegistry
Chainlink Automation Registry address
config
contract IOrionConfig config
Orion Config contract address
liquidityOrchestrator
contract ILiquidityOrchestrator liquidityOrchestrator
Liquidity Orchestrator contract
registry
contract IPriceAdapterRegistry registry
Price Adapter Registry contract
priceAdapterPrecision
uint256 priceAdapterPrecision
Price Adapter Precision
intentFactor
uint256 intentFactor
Intent factor for calculations
underlyingAsset
address underlyingAsset
Underlying asset address
underlyingDecimals
uint8 underlyingDecimals
Decimals of the underlying asset
vFeeCoefficient
uint16 vFeeCoefficient
Volume fee coefficient
rsFeeCoefficient
uint16 rsFeeCoefficient
Revenue share fee coefficient
newProtocolFeeRatesTimestamp
uint256 newProtocolFeeRatesTimestamp
Timestamp when new protocol fee rates become effective
pendingProtocolFees
uint256 pendingProtocolFees
Pending protocol fees [assets]
BASIS_POINTS_FACTOR
uint16 BASIS_POINTS_FACTOR
Basis points factor
MAX_TRANSPARENT_MINIBATCH_SIZE
uint8 MAX_TRANSPARENT_MINIBATCH_SIZE
Maximum transparent minibatch size
MAX_EPOCH_DURATION
uint32 MAX_EPOCH_DURATION
Maximum epoch duration (2 weeks = 14 days)
EpochState
Struct to hold epoch state data
struct EpochState {
address[] tokens;
mapping(address => bool) tokenExists;
mapping(address => uint256) priceArray;
mapping(address => uint256) vaultsTotalAssets;
mapping(address => uint256) vaultsTotalAssetsForFulfillRedeem;
mapping(address => uint256) vaultsTotalAssetsForFulfillDeposit;
mapping(address => address[]) vaultPortfolioTokens;
mapping(address => uint256[]) vaultPortfolioShares;
mapping(address => uint256) initialBatchPortfolio;
mapping(address => uint256) finalBatchPortfolio;
mapping(address => uint256) sellingOrders;
mapping(address => uint256) buyingOrders;
}
_currentEpoch
struct InternalStateOrchestrator.EpochState _currentEpoch
Current epoch state
epochDuration
uint32 epochDuration
Epoch duration
transparentMinibatchSize
uint8 transparentMinibatchSize
Transparent minibatch size
currentPhase
enum IInternalStateOrchestrator.InternalUpkeepPhase currentPhase
Upkeep phase
currentMinibatchIndex
uint8 currentMinibatchIndex
Current minibatch index
transparentVaultsEpoch
address[] transparentVaultsEpoch
Transparent vaults associated to the current epoch
bufferAmount
uint256 bufferAmount
Buffer amount [assets]
vaultManagementFees
mapping(address => uint256) vaultManagementFees
Management fees per vault address [assets]
vaultPerformanceFees
mapping(address => uint256) vaultPerformanceFees
Performance fees per vault address [assets]
onlyAuthorizedTrigger
modifier onlyAuthorizedTrigger()
Restricts function to only owner or automation registry
onlyConfig
modifier onlyConfig()
Restricts function to only Orion Config contract
onlyLiquidityOrchestrator
modifier onlyLiquidityOrchestrator()
Restricts function to only Liquidity Orchestrator
onlyOwnerOrGuardian
modifier onlyOwnerOrGuardian()
Restricts function to only owner or guardian
constructor
constructor() public
Constructor that disables initializers for the implementation contract
initialize
function initialize(address initialOwner, address config_, address automationRegistry_) 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 |
updateAutomationRegistry
function updateAutomationRegistry(address newAutomationRegistry) external
Updates the Chainlink Automation Registry address
Parameters
| Name | Type | Description |
|---|---|---|
| newAutomationRegistry | address | The new automation registry address |
updateEpochDuration
function updateEpochDuration(uint32 newEpochDuration) external
Updates the epoch duration
Parameters
| Name | Type | Description |
|---|---|---|
| newEpochDuration | uint32 | The new epoch duration in seconds |
updateMinibatchSize
function updateMinibatchSize(uint8 _transparentMinibatchSize) external
Updates the minibatch sizes
Parameters
| Name | Type | Description |
|---|---|---|
| _transparentMinibatchSize | uint8 | The new transparent minibatch size |
updateProtocolFees
function updateProtocolFees(uint16 _vFeeCoefficient, uint16 _rsFeeCoefficient) external
Updates the protocol fees
Parameters
| Name | Type | Description |
|---|---|---|
| _vFeeCoefficient | uint16 | The new volume fee coefficient |
| _rsFeeCoefficient | uint16 | The new revenue share fee coefficient |
activeProtocolFees
function activeProtocolFees() public view returns (uint16 vFee, uint16 rsFee)
Returns the active protocol fees (old during cooldown, new after)
Return Values
| Name | Type | Description |
|---|---|---|
| vFee | uint16 | The active volume fee coefficient |
| rsFee | uint16 | The active revenue share fee coefficient |
checkUpkeep
function checkUpkeep(bytes) external view returns (bool upkeepNeeded, bytes performData)
Checks if upkeep is needed based on time interval
https://docs.chain.link/chainlink-automation/reference/automation-interfaces
Return Values
| Name | Type | Description |
|---|---|---|
| upkeepNeeded | bool | True if upkeep is needed, false otherwise |
| performData | bytes | Empty bytes |
performUpkeep
function performUpkeep(bytes) external
Performs state reading and estimation operations
_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 |
_buildTransparentVaultsEpoch
function _buildTransparentVaultsEpoch() internal
Build filtered transparent vaults list for the epoch
_handleStart
function _handleStart() internal
Updates the next update time and resets the previous epoch state variables
_preprocessTransparentMinibatch
function _preprocessTransparentMinibatch() internal
Preprocesses minibatch of transparent vaults
_buffer
function _buffer() internal
Updates the protocol buffer to maintain solvency and capital efficiency
_In general, this function implements a stochastic optimal control framework for buffer management that balances critical objectives and acts as a clearing house for market impact.
-
Solvency Constraint: The buffer must remain non-negative at all times to ensure protocol solvency.
-
Capital Efficiency: The buffer size should be minimized relative to Total Value Locked (TVL) to reduce capital inefficiency.
Buffer Management Strategy:
- Calculates the total protocol assets across all vaults (transparent and encrypted)
- Determines the target buffer amount based on the configured target ratio
- Only increases the buffer if current buffer is below target (no buffer reduction)
- Distributes the buffer cost proportionally across all vaults_
_postprocessTransparentMinibatch
function _postprocessTransparentMinibatch() internal
Postprocesses minibatch of transparent vaults
_addTokenIfNotExists
function _addTokenIfNotExists(address token) internal
Adds a token to the current epoch if it doesn't exist
Parameters
| Name | Type | Description |
|---|---|---|
| token | address | The token address to add |
_processVaultFees
function _processVaultFees(contract IOrionTransparentVault vault, uint256 totalAssets, uint16 activeRsFee) internal returns (uint256)
Processes vault fees and calculates net fees after protocol revenue share
Parameters
| Name | Type | Description |
|---|---|---|
| vault | contract IOrionTransparentVault | The vault to process fees for |
| totalAssets | uint256 | The total assets before fees |
| activeRsFee | uint16 | The active revenue share fee coefficient |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | uint256 | The total assets after deducting vault fees |
_buildOrders
function _buildOrders() internal
Builds selling and buying orders based on portfolio differences
Compares _finalBatchPortfolio with _initialBatchPortfolio to determine rebalancing needs Orders are stored in _currentEpoch.sellingOrders and _currentEpoch.buyingOrders.
updateNextUpdateTime
function updateNextUpdateTime() external
Updates the next update time
Can only be called by the Liquidity Orchestrator
getOrders
function getOrders(bool isSellLeg) external view returns (address[] tokens, uint256[] amounts, uint256[] estimatedUnderlyingAmounts)
Get orders for a specific leg
Parameters
| Name | Type | Description |
|---|---|---|
| isSellLeg | bool | True if getting sell leg orders, false if getting buy leg orders |
Return Values
| Name | Type | Description |
|---|---|---|
| tokens | address[] | The tokens for the specified leg |
| amounts | uint256[] | The amounts for the specified leg in shares |
| estimatedUnderlyingAmounts | uint256[] | The estimated underlying amounts for the specified leg |
getEpochTokens
function getEpochTokens() external view returns (address[] tokens)
Get the list of tokens for the current epoch
This function blocks if the internal state orchestrator is not idle
Return Values
| Name | Type | Description |
|---|---|---|
| tokens | address[] | The array of token addresses used in the current epoch |
getPriceOf
function getPriceOf(address token) external view returns (uint256 price)
Get price for a specific token
Parameters
| Name | Type | Description |
|---|---|---|
| token | address | The token to get the price of |
Return Values
| Name | Type | Description |
|---|---|---|
| price | uint256 | The corresponding price [shares/assets] |
subtractPendingProtocolFees
function subtractPendingProtocolFees(uint256 amount) external
Subtracts a specified amount from the pending protocol fees
Parameters
| Name | Type | Description |
|---|---|---|
| amount | uint256 | The amount to subtract from pending protocol fees |
updateBufferAmount
function updateBufferAmount(int256 deltaAmount) external
Updates the buffer amount based on execution vs estimated amounts
Can only be called by the Liquidity Orchestrator
Parameters
| Name | Type | Description |
|---|---|---|
| deltaAmount | int256 | The amount to add/subtract from the buffer (can be negative) |
getVaultTotalAssetsAll
function getVaultTotalAssetsAll(address vault) external view returns (uint256 totalAssetsForRedeem, uint256 totalAssetsForDeposit, uint256 totalAssets)
Get all vault total assets values
Parameters
| Name | Type | Description |
|---|---|---|
| vault | address | The vault address |
Return Values
| Name | Type | Description |
|---|---|---|
| totalAssetsForRedeem | uint256 | The total assets for fulfill redeem |
| totalAssetsForDeposit | uint256 | The total assets for fulfill deposit |
| totalAssets | uint256 | The final total assets for state update |
getVaultPortfolio
function getVaultPortfolio(address vault) external view returns (address[] tokens, uint256[] shares)
Get portfolio shares for a specific vault
Parameters
| Name | Type | Description |
|---|---|---|
| vault | address | The vault address |
Return Values
| Name | Type | Description |
|---|---|---|
| tokens | address[] | The array of token addresses in the vault's portfolio |
| shares | uint256[] | The array of portfolio shares for each token [shares] |
getVaultFee
function getVaultFee(address vault) external view returns (uint256 managementFee, uint256 performanceFee)
Get the vault fees for a specific vault
Parameters
| Name | Type | Description |
|---|---|---|
| vault | address | The vault address |
Return Values
| Name | Type | Description |
|---|---|---|
| managementFee | uint256 | The management fee amount [assets] |
| performanceFee | uint256 | The performance fee amount [assets] |
pause
function pause() external
Pauses the contract
Can only be called by OrionConfig for emergency situations
unpause
function unpause() external
Unpauses the contract
Can only be called by OrionConfig after resolving emergency
_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 |