UsdnProtocolVaultLibrary

Functions

initiateDeposit

function initiateDeposit(
    uint128 amount,
    uint256 sharesOutMin,
    address to,
    address payable validator,
    uint256 deadline,
    bytes calldata currentPriceData,
    Types.PreviousActionsData calldata previousActionsData
) external returns (bool success_);

validateDeposit

See validateDeposit.

function validateDeposit(
    address payable validator,
    bytes calldata depositPriceData,
    Types.PreviousActionsData calldata previousActionsData
) external returns (bool success_);

initiateWithdrawal

See initiateWithdrawal.

function initiateWithdrawal(
    uint152 usdnShares,
    uint256 amountOutMin,
    address to,
    address payable validator,
    uint256 deadline,
    bytes calldata currentPriceData,
    Types.PreviousActionsData calldata previousActionsData
) external returns (bool success_);

validateWithdrawal

See validateWithdrawal.

function validateWithdrawal(
    address payable validator,
    bytes calldata withdrawalPriceData,
    Types.PreviousActionsData calldata previousActionsData
) external returns (bool success_);

getActionablePendingActions

See getActionablePendingActions.

function getActionablePendingActions(address currentUser, uint256 lookAhead, uint256 maxIter)
    external
    view
    returns (Types.PendingAction[] memory actions_, uint128[] memory rawIndices_);

usdnPrice

See usdnPrice.

function usdnPrice(uint128 currentPrice) external view returns (uint256 price_);

usdnPrice

See usdnPrice.

function usdnPrice(uint128 currentPrice, uint128 timestamp) public view returns (uint256 price_);

vaultAssetAvailableWithFunding

See vaultAssetAvailableWithFunding.

function vaultAssetAvailableWithFunding(uint128 currentPrice, uint128 timestamp)
    public
    view
    returns (uint256 available_);

_executePendingActionOrRevert

Executes the first actionable pending action.

Will revert if the corresponding price data is invalid.

function _executePendingActionOrRevert(Types.PreviousActionsData calldata data)
    public
    returns (uint256 securityDepositValue_);

Parameters

Name	Type	Description
`data`	`Types.PreviousActionsData`	The price data and corresponding raw indices.

Returns

Name	Type	Description
`securityDepositValue_`	`uint256`	The security deposit value of the executed action.

_executePendingAction

Executes the first actionable pending action and reports the outcome.

function _executePendingAction(Types.PreviousActionsData calldata data)
    public
    returns (bool success_, bool executed_, bool liquidated_, uint256 securityDepositValue_);

Parameters

Name	Type	Description
`data`	`Types.PreviousActionsData`	The price data and corresponding raw indices.

Returns

Name	Type	Description
`success_`	`bool`	Whether the price data is valid.
`executed_`	`bool`	Whether the pending action was executed (false if the queue has no actionable item).
`liquidated_`	`bool`	Whether the position corresponding to the pending action was liquidated.
`securityDepositValue_`	`uint256`	The security deposit value of the executed action.

_getActionablePendingAction

This is the mutating version of getActionablePendingActions, where empty items at the front of the list are removed.

function _getActionablePendingAction() internal returns (Types.PendingAction memory action_, uint128 rawIndex_);

Returns

Name	Type	Description
`action_`	`Types.PendingAction`	The first actionable pending action if any, otherwise a struct with all fields set to zero and ProtocolAction's `None` action.
`rawIndex_`	`uint128`	The raw index in the queue for the returned pending action, or zero if empty.

_prepareInitiateDepositData

Prepares the data for the initiateDeposit function.

Updates the protocol's balances if the price is fresh.

function _prepareInitiateDepositData(
    address validator,
    uint128 amount,
    uint256 sharesOutMin,
    bytes calldata currentPriceData
) internal returns (InitiateDepositData memory data_);

Parameters

Name	Type	Description
`validator`	`address`	The address that is supposed to validate the deposit and receive the security deposit.
`amount`	`uint128`	The amount of asset to deposit.
`sharesOutMin`	`uint256`	The minimum amount of USDN shares to receive.
`currentPriceData`	`bytes`	The current price data.

Returns

Name	Type	Description
`data_`	`InitiateDepositData`	The transient data for the `deposit` action.

_createDepositPendingAction

Prepares the pending action struct for a deposit and adds it to the queue.

function _createDepositPendingAction(
    address to,
    address validator,
    uint64 securityDepositValue,
    uint128 amount,
    InitiateDepositData memory data
) internal returns (uint256 amountToRefund_);

Parameters

Name	Type	Description
`to`	`address`	The recipient of the minted USDN.
`validator`	`address`	The address that is supposed to validate the deposit and receive the security deposit.
`securityDepositValue`	`uint64`	The value of the security deposit for the newly created pending action.
`amount`	`uint128`	The amount of assets to deposit (before fees).
`data`	`InitiateDepositData`	The deposit action data.

Returns

Name	Type	Description
`amountToRefund_`	`uint256`	The security deposit value of a stale pending action.

_initiateDeposit

Attempts to initiate a deposit of assets into the vault to mint USDN.

Consults the current oracle middleware implementation to know the expected format for the price data, using the ProtocolAction's InitiateDeposit action. The price validation might require payment according to the return value of the validationCost function of the middleware.

function _initiateDeposit(InitiateDepositParams memory params, bytes calldata currentPriceData)
    internal
    returns (uint256 amountToRefund_, bool isInitiated_);

Parameters

Name	Type	Description
`params`	`InitiateDepositParams`	The parameters for the deposit.
`currentPriceData`	`bytes`	The current price data.

Returns

Name	Type	Description
`amountToRefund_`	`uint256`	If there are pending liquidations we'll refund the `securityDepositValue`, else we'll only refund the security deposit value of the stale pending action.
`isInitiated_`	`bool`	Whether the action is initiated.

_validateDeposit

Attempts to validate the deposit pending action assigned to the given validator.

If successful, the pending action will be cleared from the queue.

function _validateDeposit(address validator, bytes calldata priceData)
    internal
    returns (uint256 securityDepositValue_, bool isValidated_);

Parameters

Name	Type	Description
`validator`	`address`	The address that is supposed to validate the deposit and receive the security deposit.
`priceData`	`bytes`	The price data for the pending action to validate.

Returns

Name	Type	Description
`securityDepositValue_`	`uint256`	The value of the security deposit to refund.
`isValidated_`	`bool`	Whether the action is validated.

_validateDepositWithAction

Attempts to validate the given deposit pending action.

function _validateDepositWithAction(Types.PendingAction memory pending, bytes calldata priceData)
    internal
    returns (bool isValidated_);

Parameters

Name	Type	Description
`pending`	`Types.PendingAction`	The pending action to validate.
`priceData`	`bytes`	The corresponding price data.

Returns

Name	Type	Description
`isValidated_`	`bool`	Whether the action is validated.

_prepareWithdrawalData

Prepares the data for the initiateWithdrawal function.

Updates the protocol's balances if the price is fresh.

function _prepareWithdrawalData(
    address validator,
    uint152 usdnShares,
    uint256 amountOutMin,
    bytes calldata currentPriceData
) internal returns (WithdrawalData memory data_);

Parameters

Name	Type	Description
`validator`	`address`	The address that is supposed to validate the withdrawal and receive the security deposit.
`usdnShares`	`uint152`	The amount of USDN shares to burn.
`amountOutMin`	`uint256`	The estimated minimum amount of assets to receive.
`currentPriceData`	`bytes`	The current price data.

Returns

Name	Type	Description
`data_`	`WithdrawalData`	The transient data for the `withdrawal` action.

_initiateWithdrawal

Initiates a withdrawal of assets from the vault by providing USDN tokens.

Consults the current oracle middleware implementation to know the expected format for the price data, using the ProtocolAction's InitiateWithdrawal action. The price validation might require payment according to the return value of the validationCost function of the middleware.

function _initiateWithdrawal(WithdrawalParams memory params, bytes calldata currentPriceData)
    internal
    returns (uint256 amountToRefund_, bool isInitiated_);

Parameters

Name	Type	Description
`params`	`WithdrawalParams`	The parameters for the withdrawal.
`currentPriceData`	`bytes`	The current price data.

Returns

Name	Type	Description
`amountToRefund_`	`uint256`	If there are pending liquidations we'll refund the sent security deposit, else we'll only refund the security deposit value of the stale pending action.
`isInitiated_`	`bool`	Whether the action is initiated.

_validateWithdrawal

Attempts to validate the withdrawal pending action assigned to the given validator.

If successful, the pending action will be cleared from the queue.

function _validateWithdrawal(address validator, bytes calldata priceData)
    internal
    returns (uint256 securityDepositValue_, bool isValidated_);

Parameters

Name	Type	Description
`validator`	`address`	The address that is supposed to validate the withdrawal and receive the security deposit.
`priceData`	`bytes`	The corresponding price data.

Returns

Name	Type	Description
`securityDepositValue_`	`uint256`	The value of the security deposit.
`isValidated_`	`bool`	Whether the action is validated.

_validateWithdrawalWithAction

Attempts to validate the given withdrawal pending action.

function _validateWithdrawalWithAction(Types.PendingAction memory pending, bytes calldata priceData)
    internal
    returns (bool isValidated_);

Parameters

Name	Type	Description
`pending`	`Types.PendingAction`	The pending action data.
`priceData`	`bytes`	The current price data.

Returns

Name	Type	Description
`isValidated_`	`bool`	Whether the action is validated.

_isActionable

Checks whether a pending action is actionable, i.e any user can validate it and retrieve the security deposit.

Between initiateTimestamp and initiateTimestamp + lowLatencyDeadline, the validator receives the security deposit. Between initiateTimestamp + lowLatencyDelay and initiateTimestamp + lowLatencyDelay + onChainDeadline, the validator also receives the security deposit. Outside of those periods, the security deposit goes to the user validating the pending action.

function _isActionable(
    uint256 initiateTimestamp,
    uint256 lowLatencyDeadline,
    uint256 lowLatencyDelay,
    uint256 onChainDeadline
) internal view returns (bool actionable_);

Parameters

Name	Type	Description
`initiateTimestamp`	`uint256`	The timestamp at which the action was initiated.
`lowLatencyDeadline`	`uint256`	The deadline after which the action is actionable with a low latency oracle.
`lowLatencyDelay`	`uint256`	The amount of time the action can be validated with a low latency oracle.
`onChainDeadline`	`uint256`	The deadline after which the action is actionable with an on-chain oracle.

Returns

Name	Type	Description
`actionable_`	`bool`	Whether the pending action is actionable.

_vaultAssetAvailable

Calculates the available balance in the vault if the price moves to currentPrice.

The funding is not taken into account.

function _vaultAssetAvailable(uint128 currentPrice) internal view returns (int256 available_);

Parameters

Name	Type	Description
`currentPrice`	`uint128`	The current or predicted price.

Returns

Name	Type	Description
`available_`	`int256`	The available balance in the vault.

_calcUsdnPrice

Calculates the price of the USDN token as a function of its total supply, the vault balance and the underlying asset price.

function _calcUsdnPrice(uint256 vaultBalance, uint128 assetPrice, uint256 usdnTotalSupply, uint8 assetDecimals)
    internal
    pure
    returns (uint256 price_);

Parameters

Name	Type	Description
`vaultBalance`	`uint256`	The vault balance.
`assetPrice`	`uint128`	The price of the asset.
`usdnTotalSupply`	`uint256`	The total supply of the USDN token.
`assetDecimals`	`uint8`	The number of decimals of the underlying asset.

Returns

Name	Type	Description
`price_`	`uint256`	The price of the USDN token.

_calcWithdrawalAmountLSB

Calculates the lower 24 bits of the withdrawal amount (USDN shares).

function _calcWithdrawalAmountLSB(uint152 usdnShares) internal pure returns (uint24 sharesLSB_);

Parameters

Name	Type	Description
`usdnShares`	`uint152`	The amount of USDN shares.

Returns

Name	Type	Description
`sharesLSB_`	`uint24`	The 24 least significant bits of the USDN shares.

_calcWithdrawalAmountMSB

Calculates the higher 128 bits of the withdrawal amount (USDN shares).

function _calcWithdrawalAmountMSB(uint152 usdnShares) internal pure returns (uint128 sharesMSB_);

Parameters

Name	Type	Description
`usdnShares`	`uint152`	The amount of USDN shares.

Returns

Name	Type	Description
`sharesMSB_`	`uint128`	The 128 most significant bits of the USDN shares.

Structs

InitiateDepositParams

Parameters for the internal _initiateDeposit function. The user's input for the minimum amount of shares to receive is not guaranteed due to the price difference between the initiate and validate actions.

struct InitiateDepositParams {
    address user;
    address to;
    address validator;
    uint128 amount;
    uint256 sharesOutMin;
    uint64 securityDepositValue;
}

Properties

Name	Type	Description
`user`	`address`	The address of the user initiating the deposit.
`to`	`address`	The recipient of the USDN tokens.
`validator`	`address`	The address that is supposed to validate the deposit and receive the security deposit.
`amount`	`uint128`	The amount of assets to deposit.
`sharesOutMin`	`uint256`	The minimum amount of USDN shares to receive.
`securityDepositValue`	`uint64`	The value of the security deposit for the newly created deposit.

InitiateDepositData

Structure to hold the transient data during _initiateDeposit.

struct InitiateDepositData {
    uint128 lastPrice;
    bool isLiquidationPending;
    uint16 feeBps;
    uint256 totalExpo;
    uint256 balanceLong;
    uint256 balanceVault;
    uint256 usdnTotalShares;
    uint256 sdexToBurn;
}

Properties

Name	Type	Description
`lastPrice`	`uint128`	The last known price of the asset.
`isLiquidationPending`	`bool`	Whether some liquidations still need to be performed.
`feeBps`	`uint16`	The vault deposit fee (in basis points).
`totalExpo`	`uint256`	The total exposure of the long side.
`balanceLong`	`uint256`	The balance of the long side.
`balanceVault`	`uint256`	The balance of the vault including the funding.
`usdnTotalShares`	`uint256`	Total minted shares of USDN.
`sdexToBurn`	`uint256`	The required amount of SDEX to burn for the deposit.

WithdrawalParams

Parameters for the internal _initiateWithdrawal function.

struct WithdrawalParams {
    address user;
    address to;
    address validator;
    uint152 usdnShares;
    uint256 amountOutMin;
    uint64 securityDepositValue;
}

Properties

Name	Type	Description
`user`	`address`	The address of the user initiating the withdrawal.
`to`	`address`	The recipient of the assets.
`validator`	`address`	The address that is supposed to validate the withdrawal and receive the security deposit.
`usdnShares`	`uint152`	The amount of USDN shares to withdraw.
`amountOutMin`	`uint256`	The minimum amount of assets to receive.
`securityDepositValue`	`uint64`	The value of the security deposit for the newly created withdrawal.

WithdrawalData

Structure to hold the transient data during _initiateWithdrawal.

struct WithdrawalData {
    uint256 usdnTotalShares;
    uint256 totalExpo;
    uint256 balanceLong;
    uint256 balanceVault;
    uint256 withdrawalAmountAfterFees;
    uint128 lastPrice;
    uint16 feeBps;
    bool isLiquidationPending;
}

Properties

Name	Type	Description
`usdnTotalShares`	`uint256`	The total supply of USDN shares.
`totalExpo`	`uint256`	The current total exposure.
`balanceLong`	`uint256`	The balance of the long side.
`balanceVault`	`uint256`	The balance of the vault including the funding.
`withdrawalAmountAfterFees`	`uint256`	The predicted amount of assets that will be withdrawn after fees.
`lastPrice`	`uint128`	The last known price of the asset.
`feeBps`	`uint16`	The vault deposit fee (in basis points).
`isLiquidationPending`	`bool`	Whether some liquidations still need to be performed.