This SIP proposes adding functionality such that markets can require liquidity providers to first declare an intent to change the amount of collateral delegated and then process it after a configurable delay.
\nAs an improvement over the Minimum Collateral Delegation Duration (per SIP-320), this SIP proposes to replace the concept of a minimum delegation time with a pattern in which liquidity providers call a declareIntentToDelegateCollateral function, wait a delegateCollateralDelay or undelegateCollateralDelay (depending on whether their delegated collateral is increasing or decreasing), and then have anyone call a processIntentToDelegateCollateral function within a delegateCollateralWindow or undelegateCollateralWindow to apply the change.
This functionality allows markets to prevent adversarial dynamics between liquidity providers. For example, if a liquidity provider anticipates a large increase or decrease in debt to a pool (without this feature enabled), they could quickly exit or enter the pool such that other liquidity providers assume the change. This is effectively a concern of \"just-in-time liquidity.\"
\nNote that this functionality would be implemented in addition to the Core System Precautionary Security Features (per SIP-316).
\nIt would be possible to have governance or pool owners configure these values rather than having market builders decide on the configuration, but this would complicate liquidity provisioning for all integrators, as it makes delegation non-atomic. Further, because the opportunities of adversarial liquidity provisioning are specific to a market's implementations, it makes sense to configure these values in this way.
\nMarketManagerModule & IMarketManagerModuleReplace logic and state associated with the minimum delegation time by omitting minDelegationTime and its respective setter method (setMarketMinDelegateTime) with the following logic and state associated with the delegation delay and window functionality:
unit256 undelegateCollateralDelay and its respective setter method setUndelegateCollateralDelayunit256 undelegateCollateralWindow and its respective setter method setUndelegateCollateralWindowunit256 delegateCollateralDelay and its respective setter method setDelegateCollateralDelayunit256 delegateCollateralWindow and its respective setter method setDelegateCollateralWindowAll of these values should be configurable only by the market.
\nVault & IVaultDefine the following object (i.e., struct) that defines all aspects of an intent to delegate or undelegate collateral. This object should closely resemble the following DelegateCollateralIntent object:
/**\n * Intent Lifecycle:\n *\n * |<---- Delay ---->|<-- Processing Window -->|\n * Time ----|-----------------|-------------------------|---->\n * ^ ^ ^\n * | | |\n * declarationTime processingStartTime processingEndTime\n *\n * Key:\n * - declarationTime: Timestamp at which the intent is declared.\n * - processingStartTime: Timestamp from which the intent can start being processed.\n * - processingEndTime: Timestamp after which the intent cannot be processed.\n *\n * The intent can be processed only between processingStartTime and processingEndTime.\n */\nstruct DelegateCollateralIntent {\n /**\n * @notice An incrementing nonce to ensure the\n * uniqueness of the intent and prevent replay attacks\n */\n uint256 nonce;\n /**\n * @notice The ID of the pool for which the account has an\n * outstanding intent to delegate a new amount of collateral to\n */\n uint128 poolId;\n /**\n * @notice The address of the collateral type that the account has an\n * outstanding intent to delegate a new amount of\n */\n address collateralType;\n /**\n * @notice The amount of collateral that the account has an\n * outstanding intent to delegate a new amount of to the pool,\n * denominated with 18 decimals of precision\n */\n uint256 collateralAmountD18;\n /**\n * @notice The intended amount of leverage associated with the new\n * amount of collateral that the account has an outstanding intent\n * to delegate to the pool\n * @dev The system currently only supports 1x leverage\n */\n uint256 leverage;\n /**\n * @notice The timestamp at which the intent was declared\n */\n uint256 declarationTime;\n /**\n * @notice The timestamp before which the intent cannot be processed\n * @dev dependent on\n * {VaultModule.undelegateCollateralDelay} or\n * {VaultModule.delegateCollateralDelay}\n */\n uint256 processingStartTime;\n /**\n * @notice The timestamp after which the intent cannot be processed\n * (i.e., intent expiry)\n * @dev dependent on\n * {VaultModule.undelegateCollateralWindow} or\n * {VaultModule.delegateCollateralWindow}\n */\n uint256 processingEndTime;\n}\nAdd the following intentNoncesByAccount field to the Data struct to store an array of all outstanding intent nonces for a given account in a mapping:
mapping(uint128 accountId => uint256[] nonces) intentNoncesByAccount;\nAdd the following intentByNonce field to the Data struct to map an intent nonce to a DelegateCollateralIntent object:
mapping(uint256 nonce => DelegateCollateralIntent intent) intentByNonce;\nAdd the following delegateCollateralCachePerAccountPerPool and delegateCollateralCachePerAccount fields to the Data struct to store the amount of collateral that is currently declared to be delegated for a given account due to all outstanding DelegateCollateralIntent intents:
mapping(uint128 accountId => mapping(uint128 poolId => uint256 amount) amountPerPool) delegateCollateralCachePerAccountPerPool;\nmapping(uint128 accountId => uint256 amount) delegateCollateralCachePerAccount;\nAdd the following undelegateCollateralCachePerAccountPerPool and undelegateCollateralCachePerAccount fields to the Data struct to store the amount of collateral that is currently declared to be undelegated for a given account due to all outstanding DelegateCollateralIntent intents:
mapping(uint128 accountId => mapping(uint128 poolId => uint256 amount) amountPerPool) undelegateCollateralCachePerAccountPerPool;\nmapping(uint128 accountId => uint256 amount) undelegateCollateralCachePerAccount;\n\n\nThe proposed approach of using several fields to store granular intent details per account, rather than a single field mapping of an
\naccountIdtoDelegateCollateralIntentobjects, is more effective. It avoids conflicts that would occur whenDelegateCollateralIntentobjects are updated, as discussed in the article here. Storing intent nonces in an array allows for far less complicated updates to theDelegateCollateralIntentobject. Moreover, detailed accounting is necessary to avoid errors caused by deliberately malicious declarations of intent.
Implement a rudimentary nonce management system to ensure the uniqueness of each intent declaration. This system should track the current nonce that will be assigned to the next declared intent for a given account. The nonce should be incremented after each declaration. The system should also allow for the invalidation of nonces that can be initiated by the account owner or by the system in the event of account liquidation.
\nVaultModule & IVaultModuleAdd the following event to emit when an intent to delegate a new amount of collateral is successfully declared:
\nDelegateCollateralIntentDeclared(\n uint128 accountId,\n uint256 nonce,\n uint128 poolId,\n address collateralType,\n uint256 collateralAmountD18,\n uint256 leverage\n);\nAdd the following event to emit when an intent to delegate a new amount of collateral is successfully processed:
\nDelegateCollateralIntentProcessed(\n uint128 accountId,\n uint256 nonce,\n uint128 poolId,\n address collateralType,\n uint256 collateralAmountD18,\n uint256 leverage\n);\nAdd the following function to declare and record an intent to delegate a new amount of collateral (refer to the NatSpec annotations for further implementation guidance):
\n/**\n * @notice Declare an intent to delegate a new amount of collateral\n * @dev The {msg.sender} is not necessarily the account owner but it\n * must be authorized to act on behalf of the account\n * @param accountId The ID of the account intending to delegate a new\n * amount of collateral\n * @param poolId The ID of the pool to which the account intends to\n * delegate a new amount of collateral\n * @param collateralType The address of the collateral type that the\n * account intends to delegate\n * @param newCollateralAmountD18 The new amount of collateral that\n * the account intends to delegate, denominated with 18 decimals of\n * precision\n * @param leverage The new intended leverage used in the position\n */\nfunction declareIntentToDelegateCollateral(\n uint128 accountId,\n uint128 poolId,\n address collateralType,\n uint256 newCollateralAmountD18,\n uint256 leverage\n) public;\nThe declareIntentToDelegateCollateral function should, at minimum, satisfy the following requirements:
intentNoncesByAccount to include the new intent nonce associated with the account.intentByNonce to represent the newly declared intent using the specific nonce.DelegateCollateralIntentDeclared event.Add the following functions to process outstanding intent(s) to delegate a new amount of collateral (refer to the NatSpec annotations for further implementation guidance):
\n/**\n * @notice Attempt to process an outstanding intent to delegate a\n * new amount of collateral\n * @dev The {msg.sender} can be any address\n * @param accountId The ID of the account for which the outstanding\n * intent to delegate a new amount of collateral is being processed\n * @param poolId The ID of the pool for which the intent of the account\n * to delegate a new amount of collateral is being processed\n * @param collateralType The address of the collateral type that the\n * account has an outstanding intent to delegate a new amount of\n */\nfunction processIntentToDelegateCollateral(\n uint128 accountId,\n uint128 poolId,\n address collateralType\n) public;\nThe processIntentToDelegateCollateral function should, at minimum, satisfy the following requirements:
intentNoncesByAccount for the involved account.intentByNonce using the specific nonce.DelegateCollateralIntentProcessed event upon successful processing.\n\nThe order by which the intents are processed should not matter so long as the cache mappings are properly maintained.
\n
function processIntentToDelegateCollateral(\n uint128 accountId,\n uint256[] intentNonces\n) public;\nThe overloaded processIntentToDelegateCollateral function should, at minimum, satisfy the following requirements:
processIntentToDelegateCollateral function that processes specific intents queued for an account, pool, and collateral type.intentNonces array.intentNonces array from the intentNoncesByAccount mapping if they are expired or processed.If an attempt is made to process an intent but constraints such as (but not limited to) issuance ratio restrictions, debt fluctuations, or partial account liquidations prevent the full amount of collateral from being processed, then the maximum permissible amount of collateral should be determined and processed as allowed.
\nThe delegateCollateral function is designed to invoke requestDelegateCollateral and/or processDelegateCollateral as needed, ensuring compatibility with the pre-existing delegateCollateral function. Initially, it aims to declare an intent to delegate a new amount of collateral based on the provided parameters. Subsequently, it seeks to process any existing intents linked to the specified account, pool, and type of collateral.
If an account has a ready-to-process intent but does not wish to declare a new one, it should directly use processDelegateCollateral.
Conversely, if an account has no pending intents but wishes to declare a new one, requestDelegateCollateral should be utilized directly.
LiquidationModule & ILiquidationModuleIn the event an account is liquidated, all outstanding intents to delegate collateral should be canceled/forcibly expired. This can be achieved by batch invalidating all outstanding intent nonces associated with the account within the liquidate function.
CollateralModule & ICollateralModuleThe CollateralModule should be updated to ensure that any collateral balance intended to be delegated is not available for withdrawal until the intent is processed (i.e. executed or expired). This can be achieved by adding a check to the withdraw function to ensure that the account has sufficient collateral available to withdraw after accounting for any outstanding intents to delegate collateral.
The CollateralModule should also be updated to ensure that the available collateral balance for an account is calculated correctly, accounting for any outstanding intents to delegate collateral. This can be achieved by adding logic to the getAccountAvailableCollateral function to deduct the amount of collateral declared in any outstanding intents to delegate collateral. This information can be obtained from the delegateCollateralCachePerAccount mapping.
Relevant tests will be developed during implementation.
\nN/A
\nCopyright and related rights waived via CC0.
"}},"pageContext":{"id":"239c3462-4284-5edb-88a5-218705135667","frontmatter__sip":366,"__params":{"frontmatter__sip":"366"}}},"staticQueryHashes":[]}