Ultimate Synthetic Delta Neutral - USDN

Using from Other Projects

To import contracts, interfaces or ABIs into other projects, you can use one of the following options:

Soldeer

[forge] soldeer install @smardex-usdn-contracts~1.1.0

NPM, pnpm

npm i @smardex/usdn-contracts
pnpm add @smardex/usdn-contracts

JSR

deno add jsr:@smardex/usdn-contracts
bunx jsr add @smardex/usdn-contracts
pnpm i jsr:@smardex/usdn-contracts

Install Development Environment

Foundry

To install Foundry, run the following commands in your terminal:

curl -L https://foundry.paradigm.xyz | bash
source ~/.bashrc
foundryup

Dependencies

To install existing dependencies, run the following commands:

forge soldeer install
npm install

The forge soldeer install command is only used to add libraries for the smart contracts. Other dependencies should be managed with npm.

In order to add a new dependency, use the forge soldeer install [packagename]~[version] command with any package from the soldeer registry.

For instance, to add OpenZeppelin library version 5.0.2:

forge soldeer install @openzeppelin-contracts~5.0.2

The last step is to update the remappings array in the foundry.toml config file.

You must have Node.js >= 20 installed.

Nix

If using nix, the repository provides a development shell in the form of a flake.

The devshell can be activated with the nix develop command.

To automatically activate the dev shell when opening the workspace, install direnv (available on nixpkgs) and run the following command inside this folder:

direnv allow

The environment provides the following tools:

• load .env file as environment variables
• foundry
• lcov
• Node 20 + Typescript
• Rust toolchain
• just
• lintspec
• mdbook
• trufflehog
• typst (with gyre-fonts)
• test_utils dependencies

Usage

Tests

Compile the test utils by running the following command at the root of the repo (requires the Rust toolchain):

cargo build --release

This requires some dependencies to build (the m4 lib notably). Using the provided nix devShell should provide everything.

To run tests, use forge test -vvv or npm run test.

Deployment Scripts

Deployment for anvil forks should be done with a custom bash script at script/fork/deployFork.sh which can be run without arguments. It must set up any environment variable required by the foundry deployment script.

Deployment for mainnet should be done with a custom bash script at script/deployMainnet.sh. To know which variables are required, run the following command:

script/deployMainnet.sh --help

All information about the script can be found in the script/ folder's README.

Docker Anvil Fork

You can deploy the contracts to an anvil fork using docker. The following commands will build the docker image and run the deployment script.

docker build -t usdn-anvil .
docker run --rm -it -p 8545:8545 usdn-anvil script/deployFork.sh

Foundry Documentation

For comprehensive details on Foundry, refer to the Foundry book.

Helpful Resources

• Forge Cheat Codes
• Forge Commands
• Cast Commands

Code Standards and Tools

Forge Formatter

Foundry comes with a built-in code formatter that we configured like this (default values were omitted):

[profile.default.fmt]
line_length = 120 # Max line length
bracket_spacing = true # Spacing the brackets in the code
wrap_comments = true # use max line length for comments as well
number_underscore = "thousands" # add underscore separators in large numbers

Husky

The pre-commit configuration for Husky runs forge fmt --check to check the code formatting before each commit. It also checks for any private key in the codebase with trufflehog.

In order to setup the git pre-commit hook, run npm install.

Contributors

Implemented by Stéphane Ballmer, Lilyan Bastien, Valentin Bersier, Yoan Capron, Sami Darnaud, Nicolas Decosterd, Léo Fasano, Alfred Gaillard, Paul-Alexandre Tessier

Contents

• LiquidationRewardsManager
• LiquidationRewardsManagerWstEth
• LiquidationRewardsManagerWusdn

LiquidationRewardsManager

Git Source

Inherits: ILiquidationRewardsManager, Ownable2Step

This abstract contract calculates the bonus portion of the rewards based on the size of the liquidated ticks. The actual reward calculation is left to the implementing contract.

State Variables

BPS_DIVISOR

Gets the denominator used for the reward multipliers.

uint32 public constant BPS_DIVISOR = 10_000;

BASE_GAS_COST

Gets the fixed gas amount used as a base for transaction cost computations.

Stored as a uint256 to prevent overflow during gas usage computations.

uint256 public constant BASE_GAS_COST = 21_000;

MAX_GAS_USED_PER_TICK

Gets the maximum allowable gas usage per liquidated tick.

uint256 public constant MAX_GAS_USED_PER_TICK = 500_000;

MAX_OTHER_GAS_USED

Gets the maximum allowable gas usage for all other computations.

uint256 public constant MAX_OTHER_GAS_USED = 1_000_000;

MAX_REBASE_GAS_USED

Gets the maximum allowable gas usage for rebase operations.

uint256 public constant MAX_REBASE_GAS_USED = 200_000;

MAX_REBALANCER_GAS_USED

Gets the maximum allowable gas usage for triggering the optional rebalancer.

uint256 public constant MAX_REBALANCER_GAS_USED = 300_000;

_rewardAsset

The address of the reward asset.

IERC20 internal immutable _rewardAsset;

_rewardsParameters

Holds the parameters used for rewards calculation.

Parameters should be updated to reflect changes in gas costs or protocol adjustments.

RewardsParameters internal _rewardsParameters;

Functions

getLiquidationRewards

Computes the amount of assets to reward a liquidator.

function getLiquidationRewards(
    Types.LiqTickInfo[] calldata liquidatedTicks,
    uint256 currentPrice,
    bool rebased,
    Types.RebalancerAction rebalancerAction,
    Types.ProtocolAction action,
    bytes calldata rebaseCallbackResult,
    bytes calldata priceData
) external view virtual returns (uint256 rewards_);

Parameters

Returns

getRewardsParameters

Retrieves the current parameters used for reward calculations.

function getRewardsParameters() external view returns (RewardsParameters memory);

Returns

setRewardsParameters

Updates the parameters used for calculating liquidation rewards.

function setRewardsParameters(
    uint32 gasUsedPerTick,
    uint32 otherGasUsed,
    uint32 rebaseGasUsed,
    uint32 rebalancerGasUsed,
    uint64 baseFeeOffset,
    uint16 gasMultiplierBps,
    uint16 positionBonusMultiplierBps,
    uint128 fixedReward,
    uint128 maxReward
) external onlyOwner;

Parameters

_calcGasPrice

Calculates the gas price used for rewards calculations.

function _calcGasPrice(uint64 baseFeeOffset) internal view returns (uint256 gasPrice_);

Parameters

Returns

_calcPositionSizeBonus

Computes the size and price-dependent bonus given for liquidating the ticks.

function _calcPositionSizeBonus(Types.LiqTickInfo[] calldata liquidatedTicks, uint256 currentPrice, uint16 multiplier)
    internal
    pure
    returns (uint256 bonus_);

Parameters

Returns

LiquidationRewardsManagerWstEth

Git Source

Inherits: LiquidationRewardsManager

This contract calculates rewards for liquidators within the USDN protocol, using wstETH as the underlying asset. Rewards are computed based on gas costs, which are converted to wstETH using the current conversion rate between wstETH and stETH, assuming a one-to-one rate between stETH and ETH. Additionally a fixed reward is added along with a bonus based on the size of the liquidated ticks.

Functions

constructor

constructor(IWstETH wstETH) Ownable(msg.sender);

Parameters

getLiquidationRewards

Computes the amount of assets to reward a liquidator.

function getLiquidationRewards(
    Types.LiqTickInfo[] calldata liquidatedTicks,
    uint256 currentPrice,
    bool rebased,
    Types.RebalancerAction rebalancerAction,
    Types.ProtocolAction,
    bytes calldata,
    bytes calldata
) external view override returns (uint256 wstETHRewards_);

Parameters

Returns

LiquidationRewardsManagerWusdn

Git Source

Inherits: LiquidationRewardsManager

This contract calculates rewards for liquidators within the USDN protocol, using wUSDN as the underlying asset. Rewards are computed based on gas costs which are converted to wUSDN using the current price. Additionally a fixed reward is added along with a bonus based on the size of the liquidated ticks.

State Variables

PRICE_PRECISION

The precision used for the price.

uint256 internal constant PRICE_PRECISION = 1e18;

Functions

constructor

constructor(IWusdn wusdn) Ownable(msg.sender);

Parameters

getLiquidationRewards

Computes the amount of assets to reward a liquidator.

function getLiquidationRewards(
    Types.LiqTickInfo[] calldata liquidatedTicks,
    uint256 currentPrice,
    bool,
    Types.RebalancerAction rebalancerAction,
    Types.ProtocolAction,
    bytes calldata,
    bytes calldata
) external view override returns (uint256 wUsdnRewards_);

Parameters

Returns

Contents

• mock
• oracles
• CommonOracleMiddleware
• OracleMiddlewareWithDataStreams
• OracleMiddlewareWithPyth
• OracleMiddlewareWithRedstone
• WstEthOracleMiddlewareWithDataStreams
• WstEthOracleMiddlewareWithPyth
• WusdnToEthOracleMiddlewareWithDataStreams
• WusdnToEthOracleMiddlewareWithPyth

Contents

• MockWstEthOracleMiddlewareWithPyth

MockWstEthOracleMiddlewareWithPyth

Git Source

Inherits: WstEthOracleMiddlewareWithPyth

This contract is used to get the price of wstETH by setting up a price or forwarding it to wstethMiddleware

This aims at simulating price action. Do not use in production

State Variables

_wstethMockedConfBps

Confidence interval percentage numerator

uint16 internal _wstethMockedConfBps = 20;

_wstethMockedPrice

wstETH mocked price

This price will be used if greater than zero

uint256 internal _wstethMockedPrice;

_verifySignature

If we need to verify the provided signature data or not

If _wstethMockedPrice == 0, this setting is ignored

bool internal _verifySignature = true;

Functions

constructor

constructor(
    address pythContract,
    bytes32 pythFeedId,
    address chainlinkPriceFeed,
    address wsteth,
    uint256 chainlinkTimeElapsedLimit
) WstEthOracleMiddlewareWithPyth(pythContract, pythFeedId, chainlinkPriceFeed, wsteth, chainlinkTimeElapsedLimit);

parseAndValidatePrice

function parseAndValidatePrice(
    bytes32 actionId,
    uint128 targetTimestamp,
    Types.ProtocolAction action,
    bytes calldata data
) public payable override returns (PriceInfo memory price_);

setWstethMockedPrice

Set WstEth mocked price

If the new mocked WstEth is greater than zero this will validate this mocked price else this will validate the parent middleware price

function setWstethMockedPrice(uint256 newWstethMockedPrice) external;

Parameters

setWstethMockedConfBps

Set Wsteth mocked confidence interval percentage

To calculate a percentage of the neutral price up or down in some protocol actions

function setWstethMockedConfBps(uint16 newWstethMockedConfPct) external;

Parameters

getWstethMockedPrice

Get current WstEth mocked price

function getWstethMockedPrice() external view returns (uint256);

getWstethMockedConfBps

Get current WstEth mocked confidence interval

function getWstethMockedConfBps() external view returns (uint64);

getVerifySignature

Get the signature verification flag

function getVerifySignature() external view returns (bool);

setVerifySignature

Set the signature verification flag

function setVerifySignature(bool verify) external;

validationCost

function validationCost(bytes calldata data, Types.ProtocolAction action)
    public
    view
    override(IBaseOracleMiddleware, CommonOracleMiddleware)
    returns (uint256 result_);

Contents

• ChainlinkDataStreamsOracle
• ChainlinkOracle
• PythOracle
• RedstoneOracle

ChainlinkDataStreamsOracle

Git Source

Inherits: IOracleMiddlewareErrors, IChainlinkDataStreamsOracle

This contract is used to get the price of the asset that corresponds to the stored Chainlink data streams ID.

Is implemented by the OracleMiddlewareWithDataStreams contract.

State Variables

PROXY_VERIFIER

The address of the Chainlink proxy verifier contract.

IVerifierProxy internal immutable PROXY_VERIFIER;

STREAM_ID

The ID of the Chainlink data streams.

Any data streams are standardized to 18 decimals.

bytes32 internal immutable STREAM_ID;

REPORT_VERSION

The report version.

uint256 internal constant REPORT_VERSION = 3;

_dataStreamsRecentPriceDelay

The maximum age of a recent price to be considered valid for Chainlink data streams.

uint256 internal _dataStreamsRecentPriceDelay = 45 seconds;

Functions

constructor

constructor(address verifierAddress, bytes32 streamId);

Parameters

getProxyVerifier

Gets the Chainlink Proxy verifier contract.

function getProxyVerifier() external view returns (IVerifierProxy proxyVerifier_);

Returns

getStreamId

Gets the supported Chainlink data stream ID.

function getStreamId() external view returns (bytes32 streamId_);

Returns

getDataStreamRecentPriceDelay

Gets the maximum age of a recent price to be considered valid.

function getDataStreamRecentPriceDelay() external view returns (uint256 delay_);

Returns

getReportVersion

Gets the supported Chainlink data streams report version.

function getReportVersion() external pure returns (uint256 version_);

Returns

_getChainlinkDataStreamPrice

Gets the formatted price of the asset with Chainlink data streams.

function _getChainlinkDataStreamPrice(bytes calldata payload, uint128 targetTimestamp, uint128 targetLimit)
    internal
    returns (FormattedDataStreamsPrice memory formattedPrice_);

Parameters

Returns

_getChainlinkDataStreamFeeData

Gets the fee asset data to decode the payload.

The native token fee option will be used.

function _getChainlinkDataStreamFeeData(bytes calldata payload)
    internal
    view
    returns (IFeeManager.Asset memory feeData_);

Parameters

Returns

ChainlinkOracle

Git Source

Inherits: IChainlinkOracle, IOracleMiddlewareErrors

This contract is used to get the price of an asset from Chainlink. It is used by the USDN protocol to get the price of the USDN underlying asset, and by the LiquidationRewardsManager to get the price of the gas.

State Variables

PRICE_TOO_OLD

The sentinel value returned instead of the price if the data from the oracle is too old.

int256 public constant PRICE_TOO_OLD = type(int256).min;

_priceFeed

The Chainlink price feed aggregator contract.

AggregatorV3Interface internal immutable _priceFeed;

_timeElapsedLimit

Tolerated elapsed time until we consider the data too old.

uint256 internal _timeElapsedLimit;

Functions

constructor

constructor(address chainlinkPriceFeed, uint256 timeElapsedLimit);

Parameters

getChainlinkDecimals

Gets the number of decimals of the asset from Chainlink.

function getChainlinkDecimals() public view returns (uint256 decimals_);

Returns

getPriceFeed

Gets the Chainlink price feed aggregator contract address.

function getPriceFeed() public view returns (AggregatorV3Interface priceFeed_);

Returns

getChainlinkTimeElapsedLimit

Gets the duration after which the Chainlink data is considered stale or invalid.

function getChainlinkTimeElapsedLimit() external view returns (uint256 limit_);

Returns

_getChainlinkLatestPrice

Gets the latest price of the asset from Chainlink.

If the price is too old, the returned price will be equal to PRICE_TOO_OLD.

function _getChainlinkLatestPrice() internal view virtual returns (ChainlinkPriceInfo memory price_);

Returns

_getFormattedChainlinkLatestPrice

Gets the latest price of the asset from Chainlink, formatted to the specified number of decimals.

function _getFormattedChainlinkLatestPrice(uint256 middlewareDecimals)
    internal
    view
    returns (ChainlinkPriceInfo memory formattedPrice_);

Parameters

Returns

_getFormattedChainlinkPrice

Gets the price of the asset at the specified round ID, formatted to the specified number of decimals.

function _getFormattedChainlinkPrice(uint256 middlewareDecimals, uint80 roundId)
    internal
    view
    returns (ChainlinkPriceInfo memory formattedPrice_);

Parameters

Returns

_getChainlinkPrice

Gets the price of the asset at the specified round ID.

function _getChainlinkPrice(uint80 roundId) internal view virtual returns (ChainlinkPriceInfo memory price_);

Parameters

Returns

PythOracle

Git Source

Inherits: IPythOracle

This contract is used to get the price of the asset that corresponds to the stored feed ID.

Is implemented by the CommonOracleMiddleware contract.

State Variables

_pythFeedId

The ID of the Pyth price feed.

bytes32 internal immutable _pythFeedId;

_pyth

The address of the Pyth contract.

IPyth internal immutable _pyth;

_pythRecentPriceDelay

The maximum age of a recent price to be considered valid.

uint64 internal _pythRecentPriceDelay = 45 seconds;

Functions

constructor

constructor(address pythAddress, bytes32 pythFeedId);

Parameters

getPyth

Gets the Pyth contract address.

function getPyth() external view returns (IPyth);

Returns

getPythFeedId

Gets the ID of the price feed queried by this contract.

function getPythFeedId() external view returns (bytes32);

Returns

getPythRecentPriceDelay

Gets the recent price delay.

function getPythRecentPriceDelay() external view returns (uint64);

Returns

_getPythPrice

Gets the price of the asset from the stored Pyth price feed.

function _getPythPrice(bytes calldata priceUpdateData, uint128 targetTimestamp, uint128 targetLimit)
    internal
    returns (PythStructs.Price memory);

Parameters

Returns

_getFormattedPythPrice

Gets the price of the asset from Pyth, formatted to the specified number of decimals.

function _getFormattedPythPrice(
    bytes calldata priceUpdateData,
    uint128 targetTimestamp,
    uint256 middlewareDecimals,
    uint128 targetLimit
) internal returns (FormattedPythPrice memory price_);

Parameters

Returns

_formatPythPrice

Formats a Pyth price object to normalize to the specified number of decimals.

function _formatPythPrice(PythStructs.Price memory pythPrice, uint256 middlewareDecimals)
    internal
    pure
    returns (FormattedPythPrice memory price_);

Parameters

Returns

_getPythUpdateFee

Gets the fee required to update the price feed.

function _getPythUpdateFee(bytes calldata priceUpdateData) internal view returns (uint256);

Parameters

Returns

_getLatestStoredPythPrice

Gets the latest seen (cached) price from the Pyth contract.

function _getLatestStoredPythPrice(uint256 middlewareDecimals)
    internal
    view
    returns (FormattedPythPrice memory price_);

Parameters

Returns

RedstoneOracle

Git Source

Inherits: IRedstoneOracle, PrimaryProdDataServiceConsumerBase, IOracleMiddlewareErrors

This contract is used to get the price of the asset that corresponds to the stored feed ID.

Is implemented by the OracleMiddlewareWithRedstone contract.

State Variables

REDSTONE_HEARTBEAT

Gets the interval between two Redstone price updates.

uint48 public constant REDSTONE_HEARTBEAT = 10 seconds;

REDSTONE_DECIMALS

Gets the number of decimals for prices contained in Redstone price updates.

uint8 public constant REDSTONE_DECIMALS = 8;

_redstoneFeedId

The ID of the Redstone price feed.

bytes32 internal immutable _redstoneFeedId;

_redstoneRecentPriceDelay

The maximum age of a price to be considered recent.

uint48 internal _redstoneRecentPriceDelay = 45 seconds;

Functions

constructor

constructor(bytes32 redstoneFeedId);

Parameters

getRedstoneFeedId

Gets the ID of the Redstone price feed.

function getRedstoneFeedId() external view returns (bytes32 feedId_);

Returns

getRedstoneRecentPriceDelay

Gets the maximum age of a price to be considered recent.

function getRedstoneRecentPriceDelay() external view returns (uint48 delay_);

Returns

validateTimestamp

Used by the Redstone contract internally, we override it to allow all timestamps.

function validateTimestamp(uint256) public pure override(IRedstoneOracle, RedstoneConsumerBase);

Parameters

_getFormattedRedstonePrice

Gets the price of the asset from Redstone, formatted to the specified number of decimals.

Redstone automatically retrieves data from the end of the calldata, no need to pass the pointer.

function _getFormattedRedstonePrice(uint128 targetTimestamp, uint256 middlewareDecimals)
    internal
    view
    returns (RedstonePriceInfo memory formattedPrice_);

Parameters

Returns

_extractPriceUpdateTimestamp

Extract the timestamp from the price update.

extractedTimestamp_ is a timestamp in seconds.

function _extractPriceUpdateTimestamp() internal pure returns (uint48 extractedTimestamp_);

Returns

CommonOracleMiddleware

Git Source

Inherits: ICommonOracleMiddleware, AccessControlDefaultAdminRules, ChainlinkOracle, PythOracle

This contract serves as a common base that must be implemented by other middleware contracts.

State Variables

ADMIN_ROLE

Gets the admin role's signature.

bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");

MIDDLEWARE_DECIMALS

The number of decimals for the returned price.

uint8 internal constant MIDDLEWARE_DECIMALS = 18;

_validationDelay

The delay (in seconds) between the moment an action is initiated and the timestamp of the price data used to validate that action.

uint256 internal _validationDelay = 24 seconds;

_lowLatencyDelay

The amount of time during which a low latency oracle price validation is available.

This value should be greater than or equal to _lowLatencyValidatorDeadline of the USDN protocol.

uint16 internal _lowLatencyDelay = 20 minutes;

Functions

constructor

constructor(address pythContract, bytes32 pythFeedId, address chainlinkPriceFeed, uint256 chainlinkTimeElapsedLimit)
    PythOracle(pythContract, pythFeedId)
    ChainlinkOracle(chainlinkPriceFeed, chainlinkTimeElapsedLimit)
    AccessControlDefaultAdminRules(0, msg.sender);

Parameters

getDecimals

Gets the number of decimals for the price.

function getDecimals() external pure returns (uint8 decimals_);

Returns

getValidationDelay

Gets the required delay (in seconds) between the moment an action is initiated and the timestamp of the price data used to validate that action.

function getValidationDelay() external view returns (uint256 delay_);

Returns

getLowLatencyDelay

Gets The maximum amount of time (in seconds) after initiation during which a low-latency price oracle can be used for validation.

function getLowLatencyDelay() external view returns (uint16 delay_);

Returns

validationCost

Returns the cost of one price validation for the given action (in native token).

function validationCost(bytes calldata data, Types.ProtocolAction) public view virtual returns (uint256 result_);

Parameters

Returns

parseAndValidatePrice

Parse and validate data and returns the corresponding price data.

The data format is specific to the middleware and is simply forwarded from the user transaction's calldata. A fee amounting to exactly validationCost (with the same data and action) must be sent or the transaction will revert.

function parseAndValidatePrice(bytes32, uint128 targetTimestamp, Types.ProtocolAction action, bytes calldata data)
    public
    payable
    virtual
    returns (PriceInfo memory price_);

Parameters

Returns

setValidationDelay

Sets the validation delay (in seconds) between an action timestamp and the price data timestamp used to validate that action.

function setValidationDelay(uint256 newValidationDelay) external onlyRole(ADMIN_ROLE);

Parameters

setChainlinkTimeElapsedLimit

Sets the elapsed time tolerated before we consider the price from Chainlink invalid.

function setChainlinkTimeElapsedLimit(uint256 newTimeElapsedLimit) external onlyRole(ADMIN_ROLE);

Parameters

setPythRecentPriceDelay

Sets the amount of time after which we do not consider a price as recent.

function setPythRecentPriceDelay(uint64 newDelay) external onlyRole(ADMIN_ROLE);

Parameters

setLowLatencyDelay

Sets the new low latency delay.

function setLowLatencyDelay(uint16 newLowLatencyDelay, IUsdnProtocol usdnProtocol) external onlyRole(ADMIN_ROLE);

Parameters

withdrawEther

Withdraws the ether balance of this contract.

This contract can receive funds but is not designed to hold them. So this function can be used if there's an error and funds remain after a call.

function withdrawEther(address to) external onlyRole(ADMIN_ROLE);

Parameters

_getLowLatencyPrice

Gets the price from the low-latency oracle.

function _getLowLatencyPrice(bytes calldata data, uint128 actionTimestamp, PriceAdjustment dir, uint128 targetLimit)
    internal
    virtual
    returns (PriceInfo memory price_);

Parameters

Returns

_getInitiateActionPrice

Gets the price for an initiate action of the protocol.

function _getInitiateActionPrice(bytes calldata data, PriceAdjustment dir)
    internal
    virtual
    returns (PriceInfo memory price_);

Parameters

Returns

_getValidateActionPrice

Gets the price for a validate action of the protocol.

If the low latency delay is not exceeded, validate the price with the low-latency oracle(s). Else, get the specified roundId on-chain price from Chainlink. In case of chainlink price, we don't have a price adjustment, so both neutralPrice and price are equal.

function _getValidateActionPrice(bytes calldata data, uint128 targetTimestamp, PriceAdjustment dir)
    internal
    virtual
    returns (PriceInfo memory price_);

Parameters

Returns

_getLiquidationPrice

Gets the price from the low-latency oracle.

function _getLiquidationPrice(bytes calldata data) internal virtual returns (PriceInfo memory price_);

Parameters

Returns

_validateChainlinkRoundId

Checks that the given round ID is valid and returns its corresponding price data.

Round IDs are not necessarily consecutive, so additional computing can be necessary to find the previous round ID.

function _validateChainlinkRoundId(uint128 targetLimit, uint80 roundId)
    internal
    view
    returns (ChainlinkPriceInfo memory providedRoundPrice_);

Parameters

Returns

_isPythData

Checks if the passed calldata corresponds to a Pyth message.

function _isPythData(bytes calldata data) internal pure returns (bool isPythData_);

Parameters

Returns

OracleMiddlewareWithDataStreams

Git Source

Inherits: CommonOracleMiddleware, ChainlinkDataStreamsOracle, IOracleMiddlewareWithDataStreams

This contract is used to get the price of an asset from different oracles. It is used by the USDN protocol to get the price of the USDN underlying asset.

Functions

constructor

constructor(
    address pythContract,
    bytes32 pythFeedId,
    address chainlinkPriceFeed,
    uint256 chainlinkTimeElapsedLimit,
    address chainlinkProxyVerifierAddress,
    bytes32 chainlinkStreamId
)
    CommonOracleMiddleware(pythContract, pythFeedId, chainlinkPriceFeed, chainlinkTimeElapsedLimit)
    ChainlinkDataStreamsOracle(chainlinkProxyVerifierAddress, chainlinkStreamId);

Parameters

validationCost

Returns the cost of one price validation for the given action (in native token).

function validationCost(bytes calldata data, Types.ProtocolAction)
    public
    view
    override(CommonOracleMiddleware, IBaseOracleMiddleware)
    returns (uint256 result_);

Parameters

Returns

setDataStreamsRecentPriceDelay

Sets the amount of time after which we do not consider a price as recent for Chainlink.

function setDataStreamsRecentPriceDelay(uint64 newDelay) external onlyRole(ADMIN_ROLE);

Parameters

_getLowLatencyPrice

Gets the price from the low-latency oracle.

function _getLowLatencyPrice(bytes calldata payload, uint128 actionTimestamp, PriceAdjustment dir, uint128 targetLimit)
    internal
    virtual
    override
    returns (PriceInfo memory price_);

Parameters

Returns

_getInitiateActionPrice

Gets the price for an initiate action of the protocol.

If the data parameter is not empty, validate the price with the low latency oracle. Else, get the on-chain price from ChainlinkOracle and compare its timestamp with the latest seen Pyth price (cached). If Pyth is more recent, we return it. Otherwise, we return the Chainlink price. For the latter, we don't have a price adjustment, so both neutralPrice and price are equal.

function _getInitiateActionPrice(bytes calldata data, PriceAdjustment dir)
    internal
    override
    returns (PriceInfo memory price_);

Parameters

Returns

_getLiquidationPrice

Gets the price from the low-latency oracle.

function _getLiquidationPrice(bytes calldata data) internal virtual override returns (PriceInfo memory price_);

Parameters

Returns

_convertPythPrice

Converts a formatted Pyth price into a PriceInfo.

function _convertPythPrice(FormattedPythPrice memory pythPrice) internal pure returns (PriceInfo memory price_);

Parameters

Returns

_adjustDataStreamPrice

Applies the ask, bid or price according to the dir direction.

function _adjustDataStreamPrice(FormattedDataStreamsPrice memory formattedPrice, PriceAdjustment dir)
    internal
    pure
    returns (PriceInfo memory price_);

Parameters

Returns

OracleMiddlewareWithPyth

Git Source

Inherits: CommonOracleMiddleware, IOracleMiddlewareWithPyth

This contract is used to get the price of an asset from different oracles. It is used by the USDN protocol to get the price of the USDN underlying asset.

State Variables

BPS_DIVISOR

Gets the denominator for the variables using basis points as a unit.

uint16 public constant BPS_DIVISOR = 10_000;

MAX_CONF_RATIO

Gets the maximum value for _confRatioBps.

uint16 public constant MAX_CONF_RATIO = BPS_DIVISOR * 2;

_confRatioBps

Ratio to applied to the Pyth confidence interval (in basis points).

uint16 internal _confRatioBps = 4000;

Functions

constructor

constructor(address pythContract, bytes32 pythFeedId, address chainlinkPriceFeed, uint256 chainlinkTimeElapsedLimit)
    CommonOracleMiddleware(pythContract, pythFeedId, chainlinkPriceFeed, chainlinkTimeElapsedLimit);

Parameters

getConfRatioBps

Gets the confidence ratio.

This ratio is used to apply a specific portion of the confidence interval provided by an oracle, which is used to adjust the precision of predictions or estimations.

function getConfRatioBps() external view returns (uint16 ratio_);

Returns

setConfRatio

Sets the confidence ratio.

The new value should be lower than MAX_CONF_RATIO.

function setConfRatio(uint16 newConfRatio) external onlyRole(ADMIN_ROLE);

Parameters

_getLowLatencyPrice

Gets the price from the low-latency oracle.

function _getLowLatencyPrice(bytes calldata data, uint128 actionTimestamp, PriceAdjustment dir, uint128 targetLimit)
    internal
    virtual
    override
    returns (PriceInfo memory price_);

Parameters

Returns

_getInitiateActionPrice

Gets the price for an initiate action of the protocol.

If the data parameter is not empty, validate the price with the low latency oracle. Else, get the on-chain price from ChainlinkOracle and compare its timestamp with the latest seen Pyth price (cached). If Pyth is more recent, we return it. Otherwise, we return the Chainlink price. For the latter, we don't have a price adjustment, so both neutralPrice and price are equal.

function _getInitiateActionPrice(bytes calldata data, PriceAdjustment dir)
    internal
    override
    returns (PriceInfo memory price_);

Parameters

Returns

_adjustPythPrice

Applies the confidence interval in the dir direction, scaled by the configured _confRatioBps.

function _adjustPythPrice(FormattedPythPrice memory pythPrice, PriceAdjustment dir)
    internal
    view
    returns (PriceInfo memory price_);

Parameters

Returns

OracleMiddlewareWithRedstone

Git Source

Inherits: IOracleMiddlewareWithRedstone, OracleMiddlewareWithPyth, RedstoneOracle

This contract is used to get the price of an asset from different oracles. It is used by the USDN protocol to get the price of the USDN underlying asset.

This contract allows users to use the Redstone oracle and exists in case the Pyth infrastructure fails and we need a temporary solution. Redstone and Pyth are used concurrently, which could introduce arbitrage opportunities.

State Variables

_penaltyBps

The penalty for using a non-Pyth price with low latency oracle (in basis points).

uint16 internal _penaltyBps = 25;

Functions

constructor

constructor(
    address pythContract,
    bytes32 pythFeedId,
    bytes32 redstoneFeedId,
    address chainlinkPriceFeed,
    uint256 chainlinkTimeElapsedLimit
)
    OracleMiddlewareWithPyth(pythContract, pythFeedId, chainlinkPriceFeed, chainlinkTimeElapsedLimit)
    RedstoneOracle(redstoneFeedId);

Parameters

getPenaltyBps

Gets the penalty for using a non-Pyth price with low latency oracle (in basis points)

function getPenaltyBps() external view returns (uint16 penaltyBps_);

Returns

_getLowLatencyPrice

Gets the price from the low-latency oracle (Pyth or Redstone).

function _getLowLatencyPrice(bytes calldata data, uint128 actionTimestamp, PriceAdjustment dir, uint128 targetLimit)
    internal
    override
    returns (PriceInfo memory price_);

Parameters

_adjustRedstonePrice

Applies the confidence interval in the dir direction, applying the penalty _penaltyBps

function _adjustRedstonePrice(RedstonePriceInfo memory redstonePrice, PriceAdjustment dir)
    internal
    view
    returns (PriceInfo memory price_);

Parameters

Returns

setRedstoneRecentPriceDelay

Sets the Redstone recent price delay.

function setRedstoneRecentPriceDelay(uint48 newDelay) external onlyRole(ADMIN_ROLE);

Parameters

setPenaltyBps

Sets the penalty (in basis points).

function setPenaltyBps(uint16 newPenaltyBps) external onlyRole(ADMIN_ROLE);

Parameters

WstEthOracleMiddlewareWithDataStreams

Git Source

Inherits: OracleMiddlewareWithDataStreams

This contract is used to get the price of wstETH from the ETH price or the wstETH price directly.

State Variables

_wstETH

The wstETH contract.

IWstETH internal immutable _wstETH;

Functions

constructor

constructor(
    address pythContract,
    bytes32 pythFeedId,
    address chainlinkPriceFeed,
    address wstETH,
    uint256 chainlinkTimeElapsedLimit,
    address chainlinkProxyVerifierAddress,
    bytes32 chainlinkStreamId
)
    OracleMiddlewareWithDataStreams(
        pythContract,
        pythFeedId,
        chainlinkPriceFeed,
        chainlinkTimeElapsedLimit,
        chainlinkProxyVerifierAddress,
        chainlinkStreamId
    );

Parameters

parseAndValidatePrice

Parses and validates data, returns the corresponding price data, applying ETH/wstETH ratio if the price is in ETH.

The data format is specific to the middleware and is simply forwarded from the user transaction's calldata. If needed, the wstETH price is calculated as follows: ethPrice x stEthPerToken / 1 ether. A fee amounting to exactly {validationCost} (with the same data and action) must be sent or the transaction will revert.

function parseAndValidatePrice(
    bytes32 actionId,
    uint128 targetTimestamp,
    Types.ProtocolAction action,
    bytes calldata data
) public payable virtual override(IBaseOracleMiddleware, CommonOracleMiddleware) returns (PriceInfo memory);

Parameters

Returns

WstEthOracleMiddlewareWithPyth

Git Source

Inherits: OracleMiddlewareWithPyth

This contract is used to get the price of wstETH from the ETH price oracle.

State Variables

_wstEth

The wstETH contract.

IWstETH internal immutable _wstEth;

Functions

constructor

constructor(
    address pythContract,
    bytes32 pythPriceID,
    address chainlinkPriceFeed,
    address wstETH,
    uint256 chainlinkTimeElapsedLimit
) OracleMiddlewareWithPyth(pythContract, pythPriceID, chainlinkPriceFeed, chainlinkTimeElapsedLimit);

Parameters

parseAndValidatePrice

Parses and validates data, returns the corresponding price data by applying ETH/wstETH ratio.

The data format is specific to the middleware and is simply forwarded from the user transaction's calldata. Wsteth price is calculated as follows: ethPrice x stEthPerToken / 1 ether. A fee amounting to exactly {validationCost} (with the same data and action) must be sent or the transaction will revert.

function parseAndValidatePrice(
    bytes32 actionId,
    uint128 targetTimestamp,
    Types.ProtocolAction action,
    bytes calldata data
) public payable virtual override(IBaseOracleMiddleware, CommonOracleMiddleware) returns (PriceInfo memory);

Parameters

Returns

WusdnToEthOracleMiddlewareWithDataStreams

Git Source

Inherits: OracleMiddlewareWithDataStreams

This contract is used to get the "inverse" price in number of ETH per WUSDN, so that it can be used for a shorting version of the USDN protocol with WUSDN as the underlying asset.

This version uses Pyth or Chainlink Data Streams for liquidations, and only Chainlink Data Streams for validation actions.

State Variables

ONE_DOLLAR

One dollar with the middleware decimals.

uint256 internal constant ONE_DOLLAR = 10 ** MIDDLEWARE_DECIMALS;

USDN_MAX_DIVISOR

Max divisor from the USDN token (as constant for gas optimisation).

uint256 internal constant USDN_MAX_DIVISOR = 1e18;

PRICE_NUMERATOR

Numerator for the price calculation in parseAndValidatePrice.

uint256 internal constant PRICE_NUMERATOR = 10 ** MIDDLEWARE_DECIMALS * ONE_DOLLAR * USDN_MAX_DIVISOR;

USDN

The USDN token address.

IUsdn internal immutable USDN;

Functions

constructor

constructor(
    address pythContract,
    bytes32 pythPriceID,
    address chainlinkPriceFeed,
    address usdnToken,
    uint256 chainlinkTimeElapsedLimit,
    address chainlinkProxyVerifierAddress,
    bytes32 chainlinkStreamId
)
    OracleMiddlewareWithDataStreams(
        pythContract,
        pythPriceID,
        chainlinkPriceFeed,
        chainlinkTimeElapsedLimit,
        chainlinkProxyVerifierAddress,
        chainlinkStreamId
    );

Parameters

parseAndValidatePrice

Parse and validate data and returns the corresponding price data.

*This function returns an approximation of the price, so how much ETH each WUSDN token is worth. The exact formula would be to divide the $/WUSDN price by the $/ETH price, which would look like this (as a decimal number): p = pWUSDN / pETH = (pUSDN * MAX_DIVISOR / divisor) / pETH = (pUSDN * MAX_DIVISOR) / (pETH * divisor) = ((usdnVaultBalance * pWstETH / usdnTotalSupply) * MAX_DIVISOR) / (pETH * divisor) = (usdnVaultBalance * pETH * stETHRatio * MAX_DIVISOR) / (pETH * divisor * usdnTotalSupply) = (usdnVaultBalance * stETHRatio * MAX_DIVISOR) / (usdnTotalSupply * divisor) Because we don't have historical access to the vault balance, the stETH ratio, the USDN total supply and the USDN divisor, we must approximate some parameters. The following approximations are made:

• The USDN price is $1
• The USDN divisor's current value is valid (constant) for the period where we need to provide prices. This greatly simplifies the formula (with $1 and pETH having 18 decimals): p = ($1 * MAX_DIVISOR) / (pETH * divisor) = 1e18 * MAX_DIVISOR / (pETH * divisor) Since we want to represent this price as an integer with a fixed precision of 18 decimals, the number needs to be multiplied by 1e18. p_wei = 1e54 / (pETH * divisor) Because we re-use the logic of the {OracleMiddleware}, we need to invert the adjustment direction. So if an action in the original protocol requires that we add the confidence interval to the neutral price (e.g. to open a new long position), then this oracle middleware needs to subtract the same confidence interval from the neutral price to achieve the same effect, i.e. penalizing the user. This is because the ETH price is in the denominator of the formula.*

function parseAndValidatePrice(
    bytes32 actionId,
    uint128 targetTimestamp,
    Types.ProtocolAction action,
    bytes calldata data
) public payable virtual override(CommonOracleMiddleware, IBaseOracleMiddleware) returns (PriceInfo memory);

Parameters

Returns

WusdnToEthOracleMiddlewareWithPyth

Git Source

Inherits: OracleMiddlewareWithPyth

This contract is used to get the "inverse" price in number of ETH per WUSDN, so that it can be used for a shorting version of the USDN protocol with WUSDN as the underlying asset.

This version uses Pyth for low-latency prices used during validation actions and liquidations.

State Variables

ONE_DOLLAR

One dollar with the middleware decimals.

uint256 internal constant ONE_DOLLAR = 10 ** MIDDLEWARE_DECIMALS;

USDN_MAX_DIVISOR

Max divisor from the USDN token (as constant for gas optimisation).

uint256 internal constant USDN_MAX_DIVISOR = 1e18;

PRICE_NUMERATOR

Numerator for the price calculation in parseAndValidatePrice.

uint256 internal constant PRICE_NUMERATOR = 10 ** MIDDLEWARE_DECIMALS * ONE_DOLLAR * USDN_MAX_DIVISOR;

USDN

The USDN token address.

IUsdn internal immutable USDN;

Functions

constructor

constructor(
    address pythContract,
    bytes32 pythPriceID,
    address chainlinkPriceFeed,
    address usdnToken,
    uint256 chainlinkTimeElapsedLimit
) OracleMiddlewareWithPyth(pythContract, pythPriceID, chainlinkPriceFeed, chainlinkTimeElapsedLimit);

Parameters

parseAndValidatePrice

Parse and validate data and returns the corresponding price data.

*This function returns an approximation of the price, so how much ETH each WUSDN token is worth. The exact formula would be to divide the $/WUSDN price by the $/ETH price, which would look like this (as a decimal number): p = pWUSDN / pETH = (pUSDN * MAX_DIVISOR / divisor) / pETH = (pUSDN * MAX_DIVISOR) / (pETH * divisor) = ((usdnVaultBalance * pWstETH / usdnTotalSupply) * MAX_DIVISOR) / (pETH * divisor) = (usdnVaultBalance * pETH * stETHRatio * MAX_DIVISOR) / (pETH * divisor * usdnTotalSupply) = (usdnVaultBalance * stETHRatio * MAX_DIVISOR) / (usdnTotalSupply * divisor) Because we don't have historical access to the vault balance, the stETH ratio, the USDN total supply and the USDN divisor, we must approximate some parameters. The following approximations are made:

• The USDN price is $1
• The USDN divisor's current value is valid (constant) for the period where we need to provide prices. This greatly simplifies the formula (with $1 and pETH having 18 decimals): p = ($1 * MAX_DIVISOR) / (pETH * divisor) = 1e18 * MAX_DIVISOR / (pETH * divisor) Since we want to represent this price as an integer with a fixed precision of 18 decimals, the number needs to be multiplied by 1e18. p_wei = 1e54 / (pETH * divisor) Because we re-use the logic of the {OracleMiddleware}, we need to invert the adjustment direction. So if an action in the original protocol requires that we add the confidence interval to the neutral price (e.g. to open a new long position), then this oracle middleware needs to subtract the same confidence interval from the neutral price to achieve the same effect, i.e. penalizing the user. This is because the ETH price is in the denominator of the formula.*

function parseAndValidatePrice(
    bytes32 actionId,
    uint128 targetTimestamp,
    Types.ProtocolAction action,
    bytes calldata data
) public payable virtual override(CommonOracleMiddleware, IBaseOracleMiddleware) returns (PriceInfo memory);

Parameters

Returns

Contents

• Rebalancer

Rebalancer

Git Source

Inherits: Ownable2Step, ReentrancyGuard, ERC165, IOwnershipCallback, IRebalancer, EIP712

The goal of this contract is to push the imbalance of the USDN protocol back to an healthy level when liquidations reduce long trading exposure. It will manage a single position with sufficient trading exposure to re-balance the protocol after liquidations. The position will be closed and reopened as needed, utilizing new and existing funds, whenever the imbalance reaches a defined threshold.

State Variables

MULTIPLIER_FACTOR

Gets the value of the multiplier at 1x.

Also helps to normalize the result of multiplier calculations.

uint256 public constant MULTIPLIER_FACTOR = 1e38;

MAX_ACTION_COOLDOWN

The maximum cooldown time between actions.

uint256 public constant MAX_ACTION_COOLDOWN = 48 hours;

MAX_CLOSE_DELAY

Gets the maximum amount of seconds to wait to execute a initiateClosePosition since a new rebalancer long position has been created.

uint256 public constant MAX_CLOSE_DELAY = 7 days;

INITIATE_CLOSE_TYPEHASH

The EIP712 initiateClosePosition typehash.

By including this hash into the EIP712 message for this domain, this can be used together with ECDSA-recover to obtain the signer of a message.

bytes32 public constant INITIATE_CLOSE_TYPEHASH = keccak256(
    "InitiateClosePositionDelegation(uint88 amount,address to,uint256 userMinPrice,uint256 deadline,address depositOwner,address depositCloser,uint256 nonce)"
);

_asset

The address of the asset used by the USDN protocol.

IERC20Metadata internal immutable _asset;

_assetDecimals

The number of decimals of the asset used by the USDN protocol.

uint256 internal immutable _assetDecimals;

_usdnProtocol

The address of the USDN protocol.

IUsdnProtocol internal immutable _usdnProtocol;

_maxLeverage

The maximum leverage that a position can have.

uint256 internal _maxLeverage = 3 * 10 ** Constants.LEVERAGE_DECIMALS;

_minAssetDeposit

The minimum amount of assets to be deposited by a user.

uint256 internal _minAssetDeposit;

_closeLockedUntil

The timestamp by which a user must wait to perform a initiateClosePosition.

This value will be updated each time a new rebalancer long position is created.

uint256 internal _closeLockedUntil;

_timeLimits

The time limits for the initiate/validate process of deposits and withdrawals.

The user must wait validationDelay after the initiate action to perform the corresponding validate action. If the validationDeadline has passed, the user is blocked from interacting until the cooldown duration has elapsed (since the moment of the initiate action). After the cooldown, in case of a deposit action, the user must withdraw their funds with resetDepositAssets. After the cooldown, in case of a withdrawal action, the user can initiate a new withdrawal again.

TimeLimits internal _timeLimits = TimeLimits({
    validationDelay: 24 seconds,
    validationDeadline: 20 minutes,
    actionCooldown: 4 hours,
    closeDelay: 4 hours
});

_positionVersion

The current position version.

uint128 internal _positionVersion;

_pendingAssetsAmount

The amount of assets waiting to be used in the next version of the position.

uint128 internal _pendingAssetsAmount;

_lastLiquidatedVersion

The version of the last position that got liquidated.

uint128 internal _lastLiquidatedVersion;

_userDeposit

The data about the assets deposited in this contract by users.

mapping(address => UserDeposit) internal _userDeposit;

_positionData

The data for the specific version of the position.

mapping(uint256 => PositionData) internal _positionData;

_nonce

The user EIP712 nonce.

Check getNonce for more information.

mapping(address => uint256) internal _nonce;

Functions

onlyAdmin

Reverts if the caller is not the USDN protocol nor the owner.

modifier onlyAdmin();

onlyProtocol

Reverts if the caller is not the USDN protocol.

modifier onlyProtocol();

constructor

constructor(IUsdnProtocol usdnProtocol) Ownable(msg.sender) EIP712("Rebalancer", "1");

Parameters

receive

Allows this contract to receive ether sent by the USDN protocol.

receive() external payable onlyProtocol;

getAsset

Returns the address of the asset used by the USDN protocol.

function getAsset() external view returns (IERC20Metadata asset_);

Returns

getUsdnProtocol

Returns the address of the USDN protocol.

function getUsdnProtocol() external view returns (IUsdnProtocol protocol_);

Returns

getPendingAssetsAmount

Returns the amount of assets deposited and waiting for the next version to be opened.

function getPendingAssetsAmount() external view returns (uint128 pendingAssetsAmount_);

Returns

getPositionVersion

Returns the version of the current position (0 means no position open).

function getPositionVersion() external view returns (uint128 version_);

Returns

getPositionMaxLeverage

Returns the maximum leverage the rebalancer position can have.

In some edge cases during the calculation of the rebalancer position's tick, this value might be exceeded by a slight margin.

function getPositionMaxLeverage() external view returns (uint256 maxLeverage_);

Returns

getCurrentStateData

Returns the necessary data for the USDN protocol to update the position.

function getCurrentStateData()
    external
    view
    returns (uint128 pendingAssets_, uint256 maxLeverage_, Types.PositionId memory currentPosId_);

Returns

getLastLiquidatedVersion

Returns the version of the last position that got liquidated.

0 means no liquidated version yet.

function getLastLiquidatedVersion() external view returns (uint128 version_);

Returns

getMinAssetDeposit

Returns the minimum amount of assets a user can deposit in the rebalancer.

function getMinAssetDeposit() external view returns (uint256 minAssetDeposit_);

Returns

getPositionData

Returns the data of the provided version of the position.

function getPositionData(uint128 version) external view returns (PositionData memory positionData_);

Parameters

Returns

getTimeLimits

Gets the time limits for the action validation process.

function getTimeLimits() external view returns (TimeLimits memory timeLimits_);

Returns

getUserDepositData

Returns the data regarding the assets deposited by the provided user.

function getUserDepositData(address user) external view returns (UserDeposit memory data_);

Parameters

Returns

getNonce

Gets the nonce a user can use to generate a delegation signature.

This is to prevent replay attacks when using an EIP712 delegation signature.

function getNonce(address user) external view returns (uint256 nonce_);

Parameters

Returns

domainSeparatorV4

Gets the domain separator v4 used for EIP-712 signatures.

function domainSeparatorV4() external view returns (bytes32 domainSeparator_);

Returns

getCloseLockedUntil

Gets the timestamp by which a user must wait to perform a initiateClosePosition.

function getCloseLockedUntil() external view returns (uint256 timestamp_);

Returns

increaseAssetAllowance

Increases the allowance of assets for the USDN protocol spender by addAllowance.

function increaseAssetAllowance(uint256 addAllowance) external;

Parameters

initiateDepositAssets

Deposits assets into this contract to be included in the next position after validation

The user must call validateDepositAssets between _timeLimits.validationDelay and. _timeLimits.validationDeadline seconds after this action.

function initiateDepositAssets(uint88 amount, address to) external nonReentrant;

Parameters

validateDepositAssets

Validates a deposit to be included in the next position version.

The to from the initiateDepositAssets must call this function between _timeLimits.validationDelay and _timeLimits.validationDeadline seconds after the initiate action. After that, the user must wait until _timeLimits.actionCooldown seconds has elapsed, and then can call resetDepositAssets to retrieve their assets.

function validateDepositAssets() external nonReentrant;

resetDepositAssets

Retrieves the assets for a failed deposit due to waiting too long before calling validateDepositAssets.

The user must wait _timeLimits.actionCooldown since the initiateDepositAssets before calling this function.

function resetDepositAssets() external nonReentrant;

initiateWithdrawAssets

Withdraws assets that were not yet included in a position.

The user must call validateWithdrawAssets between _timeLimits.validationDelay and _timeLimits.validationDeadline seconds after this action.

function initiateWithdrawAssets() external nonReentrant;

validateWithdrawAssets

Validates a withdrawal of assets that were not yet included in a position.

The user must call this function between _timeLimits.validationDelay and _timeLimits.validationDeadline seconds after initiateWithdrawAssets. After that, the user must wait until the cooldown has elapsed, and then can call initiateWithdrawAssets again or wait to be included in the next position.

function validateWithdrawAssets(uint88 amount, address to) external nonReentrant;

Parameters

initiateClosePosition

Closes the provided amount from the current rebalancer's position.

The rebalancer allows partially closing its position to withdraw the user's assets + PnL. The remaining amount needs to be above _minAssetDeposit. The validator is always the msg.sender, which means the user must call validateClosePosition on the protocol side after calling this function.

function initiateClosePosition(
    uint88 amount,
    address to,
    address payable validator,
    uint256 userMinPrice,
    uint256 deadline,
    bytes calldata currentPriceData,
    Types.PreviousActionsData calldata previousActionsData,
    bytes calldata delegationData
) external payable nonReentrant returns (Types.LongActionOutcome outcome_);

Parameters

Returns

_refundEther

Refunds any ether in this contract to the caller.

This contract should not hold any ether so any sent to it belongs to the current caller.

function _refundEther() internal;

updatePosition

Indicates that the previous version of the position was closed and a new one was opened.

If previousPosValue equals 0, it means the previous version got liquidated.

function updatePosition(Types.PositionId calldata newPosId, uint128 previousPosValue)
    external
    onlyProtocol
    nonReentrant;

Parameters

setPositionMaxLeverage

Updates the max leverage a position can have.

newMaxLeverage must be between the min and max leverage of the USDN protocol. This function can only be called by the owner of the contract.

function setPositionMaxLeverage(uint256 newMaxLeverage) external onlyOwner;

Parameters

setMinAssetDeposit

Sets the minimum amount of assets to be deposited by a user.

The new minimum amount must be greater than or equal to the minimum long position of the USDN protocol. This function can only be called by the owner or the USDN protocol.

function setMinAssetDeposit(uint256 minAssetDeposit) external onlyAdmin;

Parameters

setTimeLimits

Sets the various time limits in seconds.

This function can only be called by the owner of the contract.

function setTimeLimits(uint64 validationDelay, uint64 validationDeadline, uint64 actionCooldown, uint64 closeDelay)
    external
    onlyOwner;

Parameters

ownershipCallback

Called by the USDN protocol on the new position owner after an ownership transfer occurs.

Implementers can use this callback to perform actions triggered by the ownership change.

function ownershipCallback(address, Types.PositionId calldata) external pure;

Parameters

supportsInterface

Query if a contract implements an interface

Interface identification is specified in ERC-165. This function uses less than 30,000 gas.

function supportsInterface(bytes4 interfaceId)
    public
    view
    virtual
    override(ERC165, IERC165)
    returns (bool isSupported_);

Parameters

Returns

_checkValidationTime

Checks if the validate action happens between the validation delay and the validation deadline.

If the block timestamp is before initiateTimestamp + validationDelay, the function will revert. If the block timestamp is after initiateTimestamp + validationDeadline, the function will revert.

function _checkValidationTime(uint40 initiateTimestamp) internal view;

Parameters

_verifyInitiateCloseDelegation

Performs the initiateClosePosition EIP712 delegation signature verification.

Reverts if the function arguments don't match those included in the signature and if the signer isn't the owner of the deposit.

function _verifyInitiateCloseDelegation(
    uint88 amount,
    address to,
    uint256 userMinPrice,
    uint256 deadline,
    bytes calldata delegationData
) internal returns (address depositOwner_);

Parameters

Returns

_initiateClosePosition

Closes a user deposited amount of the current UsdnProtocol rebalancer position.

function _initiateClosePosition(
    InitiateCloseData memory data,
    bytes calldata currentPriceData,
    Types.PreviousActionsData calldata previousActionsData,
    bytes calldata delegationData
) internal returns (Types.LongActionOutcome outcome_);

Parameters

Returns

Structs

InitiateCloseData

Structure to hold the transient data during initiateClosePosition.

struct InitiateCloseData {
    UserDeposit userDepositData;
    uint88 remainingAssets;
    uint256 positionVersion;
    PositionData currentPositionData;
    uint256 amountToCloseWithoutBonus;
    uint256 amountToClose;
    Types.Position protocolPosition;
    address user;
    uint256 balanceOfAssetBefore;
    uint256 balanceOfAssetAfter;
    uint88 amount;
    address to;
    address payable validator;
    uint256 userMinPrice;
    uint256 deadline;
    uint256 closeLockedUntil;
}

Properties

Contents

• Usdn
• UsdnNoRebase
• Wusdn

Usdn

Git Source

Inherits: IUsdn, ERC20Permit, ERC20Burnable, AccessControl

The USDN token supports the USDN Protocol. It is minted when assets are deposited into the USDN Protocol vault and burned when withdrawn. The total supply and individual balances are periodically increased by modifying a global divisor, ensuring the token's value doesn't grow too far past 1 USD.

This contract extends OpenZeppelin's ERC-20 implementation, adapted to support growable balances. Unlike a traditional ERC-20, balances are stored as shares, which are converted into token amounts using the global divisor. This design allows for supply growth without updating individual balances. Any divisor modification can only make balances and total supply increase.

State Variables

MINTER_ROLE

Gets the minter role signature.

bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");

REBASER_ROLE

Gets the rebaser role signature.

bytes32 public constant REBASER_ROLE = keccak256("REBASER_ROLE");

MAX_DIVISOR

Gets the maximum value of the divisor, which is also the initial value.

uint256 public constant MAX_DIVISOR = 1e18;

MIN_DIVISOR

Gets the minimum acceptable value of the divisor.

The minimum divisor that can be set. This corresponds to a growth of 1B times. Technically, 1e5 would still work without precision errors.

uint256 public constant MIN_DIVISOR = 1e9;

NAME

The name of the USDN token.

string internal constant NAME = "Ultimate Synthetic Delta Neutral";

SYMBOL

The symbol of the USDN token.

string internal constant SYMBOL = "USDN";

_shares

Mapping of the number of shares held by each account.

mapping(address account => uint256) internal _shares;

_totalShares

The sum of all the shares.

uint256 internal _totalShares;

_divisor

The divisor used for conversion between shares and tokens.

uint256 internal _divisor = MAX_DIVISOR;

_rebaseHandler

Address of a contract to be called upon a rebase event.

IRebaseCallback internal _rebaseHandler;

Functions

constructor

constructor(address minter, address rebaser) ERC20(NAME, SYMBOL) ERC20Permit(NAME);

Parameters

totalSupply

Returns the total supply of tokens in existence.

This value is derived from the total number of shares and the current divisor. It does not represent the exact sum of all token balances due to the divisor mechanism. For an accurate representation, consider using the total number of shares via totalShares.

function totalSupply() public view override(ERC20, IERC20) returns (uint256 totalSupply_);

Returns

balanceOf

Returns the token balance of a given account.

The returned value is based on the current divisor and may not represent an accurate balance in terms of shares. For precise calculations, use the number of shares via sharesOf.

function balanceOf(address account) public view override(ERC20, IERC20) returns (uint256 balance_);

Parameters

Returns

nonces

Returns the current nonce for owner. This value must be included whenever a signature is generated for {permit}. Every successful call to {permit} increases owner's nonce by one. This prevents a signature from being used multiple times.

function nonces(address owner) public view override(IERC20Permit, ERC20Permit) returns (uint256);

burn

Destroys a value amount of tokens from the caller, reducing the total supply.

function burn(uint256 value) public override(ERC20Burnable, IUsdn);

Parameters

burnFrom

Destroys a value amount of tokens from account, deducting from the caller's allowance.

function burnFrom(address account, uint256 value) public override(ERC20Burnable, IUsdn);

Parameters

sharesOf

Returns the number of shares owned by account.

function sharesOf(address account) public view returns (uint256 shares_);

Parameters

Returns

totalShares

Returns the total number of shares in existence.

function totalShares() external view returns (uint256 shares_);

Returns

convertToTokens

Converts a number of shares to the corresponding amount of tokens.

The conversion never overflows as we are performing a division. The conversion rounds to the nearest amount of tokens that minimizes the error when converting back to shares.

function convertToTokens(uint256 amountShares) external view returns (uint256 tokens_);

Parameters

Returns

convertToTokensRoundUp

Converts a number of shares to the corresponding amount of tokens, rounding up.

Use this function to determine the amount of a token approval, as we always round up when deducting from a token transfer allowance.

function convertToTokensRoundUp(uint256 amountShares) external view returns (uint256 tokens_);

Parameters

Returns

convertToShares

Converts a number of tokens to the corresponding amount of shares.

The conversion reverts with UsdnMaxTokensExceeded if the corresponding amount of shares overflows.

function convertToShares(uint256 amountTokens) public view returns (uint256 shares_);

Parameters

Returns

divisor

Gets the current value of the divisor that converts between tokens and shares.

function divisor() external view returns (uint256 divisor_);

Returns

rebaseHandler

Gets the rebase handler address, which is called whenever a rebase happens.

function rebaseHandler() external view returns (IRebaseCallback rebaseHandler_);

Returns

maxTokens

Returns the current maximum tokens supply, given the current divisor.

This function is used to check if a conversion operation would overflow.

function maxTokens() public view returns (uint256 maxTokens_);

Returns

transferShares

Transfers a given amount of shares from the msg.sender to to.

function transferShares(address to, uint256 value) external returns (bool success_);

Parameters

Returns

transferSharesFrom

Transfers a given amount of shares from the from to to.

There should be sufficient allowance for the spender. Be mindful of the rebase logic. The allowance is in tokens. So, after a rebase, the same amount of shares will be worth a higher amount of tokens. In that case, the allowance of the initial approval will not be enough to transfer the new amount of tokens. This can also happen when your transaction is in the mempool and the rebase happens before your transaction. Also note that the amount of tokens deduced from the allowance is rounded up, so the convertToTokensRoundUp function should be used when converting shares into an allowance value.

function transferSharesFrom(address from, address to, uint256 value) external returns (bool success_);

Parameters

Returns

burnShares

Destroys a value amount of shares from the caller, reducing the total supply.

function burnShares(uint256 value) external;

Parameters

burnSharesFrom

Destroys a value amount of shares from account, deducting from the caller's allowance.

There should be sufficient allowance for the spender. Be mindful of the rebase logic. The allowance is in tokens. So, after a rebase, the same amount of shares will be worth a higher amount of tokens. In that case, the allowance of the initial approval will not be enough to transfer the new amount of tokens. This can also happen when your transaction is in the mempool and the rebase happens before your transaction. Also note that the amount of tokens deduced from the allowance is rounded up, so the convertToTokensRoundUp function should be used when converting shares into an allowance value.

function burnSharesFrom(address account, uint256 value) public;

Parameters

mint

Mints new shares, providing a token value.

Caller must have the MINTER_ROLE.

function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE);

Parameters

mintShares

Mints new shares, providing a share value.

Caller must have the MINTER_ROLE.

function mintShares(address to, uint256 amount) external onlyRole(MINTER_ROLE) returns (uint256 mintedTokens_);

Parameters

Returns

rebase

Decreases the global divisor, which effectively grows all balances and the total supply.

If the provided divisor is larger than or equal to the current divisor value, no rebase will happen If the new divisor is smaller than MIN_DIVISOR, the value will be clamped to MIN_DIVISOR. Caller must have the REBASER_ROLE.

function rebase(uint256 newDivisor)
    external
    onlyRole(REBASER_ROLE)
    returns (bool rebased_, uint256 oldDivisor_, bytes memory callbackResult_);

Parameters

Returns

setRebaseHandler

Sets the rebase handler address.

Emits a RebaseHandlerUpdated event. If set to the zero address, no handler will be called after a rebase. Caller must have the DEFAULT_ADMIN_ROLE.

function setRebaseHandler(IRebaseCallback newHandler) external onlyRole(DEFAULT_ADMIN_ROLE);

Parameters

_convertToTokens

Converts an amount of shares into the corresponding amount of tokens, rounding the division according to rounding.

If rounding to the nearest integer and the result is exactly at the halfway point, we round up.

function _convertToTokens(uint256 amountShares, Rounding rounding, uint256 d) internal pure returns (uint256 tokens_);

Parameters

Returns

_transferShares

Transfers a given amount of shares.

Reverts if the from or to address is the zero address.

function _transferShares(address from, address to, uint256 value, uint256 tokenValue) internal;

Parameters

_burnShares

Burns a given amount of shares from an account.

Reverts if the account address is the zero address.

function _burnShares(address account, uint256 value, uint256 tokenValue) internal;

Parameters

_updateShares

Updates the shares of accounts during transferShares, mintShares, or burnShares.

Emits a {IERC20.Transfer} event with the token equivalent of the operation. If from is the zero address, the operation is a mint. If to is the zero address, the operation is a burn.

function _updateShares(address from, address to, uint256 value, uint256 tokenValue) internal;

Parameters

_update

Updates the shares of accounts during transfers, mints, or burns.

Emits a {IERC20.Transfer} event. If from is the zero address, the operation is a mint. If to is the zero address, the operation is a burn.

function _update(address from, address to, uint256 value) internal override;

Parameters

Enums

Rounding

Enum representing the rounding options when converting from shares to tokens.

enum Rounding {
    Down,
    Closest,
    Up
}

UsdnNoRebase

Git Source

Inherits: IUsdn, ERC20Permit, ERC20Burnable, Ownable

The USDN token supports the USDN Protocol. It is minted when assets are deposited into the USDN Protocol vault and burned when withdrawn. While the original USDN token implement rebases to inflates its supply to stay as close to a certain price as possible, this version removes all of this logic to be used with a protocol that does not have any target price.

As rebasing is completely disabled, 1 share always equals to 1 token, and the divisor never changes.

State Variables

MINTER_ROLE

Gets the minter role signature.

Only here to match the IUsdn interface, this contract uses Ownable instead.

bytes32 public constant MINTER_ROLE = "";

REBASER_ROLE

Gets the rebaser role signature.

Only here to match the IUsdn interface, this contract uses Ownable instead.

bytes32 public constant REBASER_ROLE = "";

MAX_DIVISOR

Gets the maximum value of the divisor, which is also the initial value.

Only here to match the IUsdn interface, this contract does not use shares.

uint256 public constant MAX_DIVISOR = 1;

MIN_DIVISOR

Gets the minimum acceptable value of the divisor.

Only here to match the IUsdn interface, this contract does not use shares.

uint256 public constant MIN_DIVISOR = 1;

Functions

constructor

constructor(string memory name, string memory symbol) ERC20(name, symbol) ERC20Permit(name) Ownable(msg.sender);

Parameters

nonces

Returns the current nonce for owner. This value must be included whenever a signature is generated for {permit}. Every successful call to {permit} increases owner's nonce by one. This prevents a signature from being used multiple times.

function nonces(address owner) public view override(IERC20Permit, ERC20Permit) returns (uint256);

burn

Destroys a value amount of tokens from the caller, reducing the total supply.

function burn(uint256 value) public override(ERC20Burnable, IUsdn);

Parameters

burnFrom

Destroys a value amount of tokens from account, deducting from the caller's allowance.

function burnFrom(address account, uint256 value) public override(ERC20Burnable, IUsdn);

Parameters

sharesOf

Returns the number of shares owned by account.

function sharesOf(address account) public view returns (uint256 shares_);

Parameters

Returns

totalShares

Returns the total number of shares in existence.

function totalShares() external view returns (uint256 shares_);

Returns

convertToTokens

Converts a number of shares to the corresponding amount of tokens.

The conversion never overflows as we are performing a division. The conversion rounds to the nearest amount of tokens that minimizes the error when converting back to shares.

function convertToTokens(uint256 amountShares) external pure returns (uint256 tokens_);

Parameters

Returns

convertToTokensRoundUp

Converts a number of shares to the corresponding amount of tokens, rounding up.

Use this function to determine the amount of a token approval, as we always round up when deducting from a token transfer allowance.

function convertToTokensRoundUp(uint256 amountShares) external pure returns (uint256 tokens_);

Parameters

Returns

convertToShares

Converts a number of tokens to the corresponding amount of shares.

The conversion reverts with UsdnMaxTokensExceeded if the corresponding amount of shares overflows.

function convertToShares(uint256 amountTokens) public pure returns (uint256 shares_);

Parameters

Returns

divisor

Gets the current value of the divisor that converts between tokens and shares.

function divisor() external pure returns (uint256 divisor_);

Returns

rebaseHandler

Gets the rebase handler address, which is called whenever a rebase happens.

function rebaseHandler() external pure returns (IRebaseCallback);

Returns

maxTokens

Returns the current maximum tokens supply, given the current divisor.

This function is used to check if a conversion operation would overflow.

function maxTokens() public pure returns (uint256 maxTokens_);

Returns

transferShares

Transfers a given amount of shares from the msg.sender to to.

function transferShares(address to, uint256 value) external returns (bool success_);

Parameters

Returns

transferSharesFrom

Transfers a given amount of shares from the from to to.

There should be sufficient allowance for the spender. Be mindful of the rebase logic. The allowance is in tokens. So, after a rebase, the same amount of shares will be worth a higher amount of tokens. In that case, the allowance of the initial approval will not be enough to transfer the new amount of tokens. This can also happen when your transaction is in the mempool and the rebase happens before your transaction. Also note that the amount of tokens deduced from the allowance is rounded up, so the convertToTokensRoundUp function should be used when converting shares into an allowance value.

function transferSharesFrom(address from, address to, uint256 value) external returns (bool success_);

Parameters

Returns

burnShares

Destroys a value amount of shares from the caller, reducing the total supply.

function burnShares(uint256 value) external;

Parameters

burnSharesFrom

Destroys a value amount of shares from account, deducting from the caller's allowance.

There should be sufficient allowance for the spender. Be mindful of the rebase logic. The allowance is in tokens. So, after a rebase, the same amount of shares will be worth a higher amount of tokens. In that case, the allowance of the initial approval will not be enough to transfer the new amount of tokens. This can also happen when your transaction is in the mempool and the rebase happens before your transaction. Also note that the amount of tokens deduced from the allowance is rounded up, so the convertToTokensRoundUp function should be used when converting shares into an allowance value.

function burnSharesFrom(address account, uint256 value) public;

Parameters

mint

Mints new shares, providing a token value.

Caller must have the MINTER_ROLE.

function mint(address to, uint256 amount) external onlyOwner;

Parameters

mintShares

Mints new shares, providing a share value.

Caller must have the MINTER_ROLE.

function mintShares(address to, uint256 amount) external onlyOwner returns (uint256 mintedTokens_);

Parameters

Returns

rebase

Decreases the global divisor, which effectively grows all balances and the total supply.

If the provided divisor is larger than or equal to the current divisor value, no rebase will happen If the new divisor is smaller than MIN_DIVISOR, the value will be clamped to MIN_DIVISOR. Caller must have the REBASER_ROLE.

function rebase(uint256) external pure returns (bool rebased_, uint256 oldDivisor_, bytes memory callbackResult_);

Parameters

Returns

setRebaseHandler

Sets the rebase handler address.

Emits a RebaseHandlerUpdated event. If set to the zero address, no handler will be called after a rebase. Caller must have the DEFAULT_ADMIN_ROLE.

function setRebaseHandler(IRebaseCallback) external pure;

Parameters

Wusdn

Git Source

Inherits: ERC20Permit, IWusdn

The WUSDN token is a wrapped version of the USDN token. While USDN is a rebasing token that inflates user balances periodically, WUSDN provides stable balances by increasing in value instead of rebasing.

State Variables

NAME

The name of the WUSDN token.

string internal constant NAME = "Wrapped Ultimate Synthetic Delta Neutral";

SYMBOL

The symbol of the WUSDN token.

string internal constant SYMBOL = "WUSDN";

SHARES_RATIO

Returns the ratio used to convert USDN shares to WUSDN amounts.

This ratio is initialized in the constructor based on the maximum divisor of the USDN token.

uint256 public immutable SHARES_RATIO;

USDN

Returns the address of the USDN token.

IUsdn public immutable USDN;

Functions

constructor

constructor(IUsdn usdn) ERC20(NAME, SYMBOL) ERC20Permit(NAME);

Parameters

wrap

Wraps a given amount of USDN into WUSDN.

This function may use slightly less than usdnAmount due to rounding errors. For a more precise operation, use wrapShares.

function wrap(uint256 usdnAmount) external returns (uint256 wrappedAmount_);

Parameters

Returns

wrap

Wraps a given amount of USDN into WUSDN.

This function may use slightly less than usdnAmount due to rounding errors. For a more precise operation, use wrapShares.

function wrap(uint256 usdnAmount, address to) external returns (uint256 wrappedAmount_);

Parameters

Returns

wrapShares

Wraps a given amount of USDN shares into WUSDN and sends it to a specified address.

function wrapShares(uint256 usdnShares, address to) external returns (uint256 wrappedAmount_);

Parameters

Returns

unwrap

Unwraps a given amount of WUSDN into USDN.

function unwrap(uint256 wusdnAmount) external returns (uint256 usdnAmount_);

Parameters

Returns

unwrap

Unwraps a given amount of WUSDN into USDN.

function unwrap(uint256 wusdnAmount, address to) external returns (uint256 usdnAmount_);

Parameters

Returns

previewWrap

Computes the amount of WUSDN that would be received for a given amount of USDN.

The actual amount received may differ slightly due to rounding errors. For a precise value, use previewWrapShares.

function previewWrap(uint256 usdnAmount) external view returns (uint256 wrappedAmount_);

Parameters

Returns

previewWrapShares

Computes the amount of WUSDN that would be received for a given amount of USDN shares.

function previewWrapShares(uint256 usdnShares) external view returns (uint256 wrappedAmount_);

Parameters

Returns

redemptionRate

Returns the exchange rate between WUSDN and USDN.

function redemptionRate() external view returns (uint256 usdnAmount_);

Returns

previewUnwrap

Computes the amount of USDN that would be received for a given amount of WUSDN.

The actual amount received may differ slightly due to rounding errors. For a precise value, use previewUnwrapShares.

function previewUnwrap(uint256 wusdnAmount) external view returns (uint256 usdnAmount_);

Parameters

Returns

previewUnwrapShares

Computes the amount of USDN shares that would be received for a given amount of WUSDN.

function previewUnwrapShares(uint256 wusdnAmount) external view returns (uint256 usdnSharesAmount_);

Parameters

Returns

totalUsdnBalance

Returns the total amount of USDN held by the contract.

function totalUsdnBalance() external view returns (uint256);

Returns

totalUsdnShares

Returns the total amount of USDN shares held by the contract.

function totalUsdnShares() external view returns (uint256);

Returns

nonces

Returns the current nonce for owner. This value must be included whenever a signature is generated for {permit}. Every successful call to {permit} increases owner's nonce by one. This prevents a signature from being used multiple times.

function nonces(address owner) public view override(IERC20Permit, ERC20Permit) returns (uint256);

_wrap

Wraps a given USDN token amount into WUSDN.

The caller must have already approved the USDN contract to transfer the required amount of USDN. When calling this function, the transfer is always initiated from the msg.sender.

function _wrap(uint256 usdnAmount, address to) private returns (uint256 wrappedAmount_);

Parameters

Returns

_wrapShares

Wraps a given USDN shares amount into WUSDN.

The caller must have already approved the USDN contract to transfer the required amount of USDN shares. When calling this function, the transfer is always initiated from the msg.sender.

function _wrapShares(uint256 usdnShares, address to) private returns (uint256 wrappedAmount_);

Parameters

Returns

_unwrap

Unwraps a given WUSDN token amount into USDN.

This function always burns WUSDN tokens from the msg.sender.

function _unwrap(uint256 wusdnAmount, address to) private returns (uint256 usdnAmount_);

Parameters

Returns

Contents

• libraries
• UsdnProtocolActions
• UsdnProtocolCore
• UsdnProtocolFallback
• UsdnProtocolImpl
• UsdnProtocolLong
• UsdnProtocolVault

Contents

• UsdnProtocolActionsLongLibrary
• UsdnProtocolActionsUtilsLibrary
• UsdnProtocolConstantsLibrary
• UsdnProtocolCoreLibrary
• UsdnProtocolLongLibrary
• UsdnProtocolSettersLibrary
• UsdnProtocolUtilsLibrary
• UsdnProtocolVaultLibrary

UsdnProtocolActionsLongLibrary

Git Source

Functions

initiateOpenPosition

See initiateOpenPosition.

function initiateOpenPosition(
    Types.InitiateOpenPositionParams memory params,
    bytes calldata currentPriceData,
    Types.PreviousActionsData calldata previousActionsData
) external returns (bool isInitiated_, Types.PositionId memory posId_);

validateOpenPosition

See validateOpenPosition.

function validateOpenPosition(
    address payable validator,
    bytes calldata openPriceData,
    Types.PreviousActionsData calldata previousActionsData
) external returns (Types.LongActionOutcome outcome_, Types.PositionId memory posId_);

initiateClosePosition

See initiateClosePosition.

function initiateClosePosition(
    Types.InitiateClosePositionParams memory params,
    bytes calldata currentPriceData,
    Types.PreviousActionsData calldata previousActionsData,
    bytes calldata delegationSignature
) external returns (Types.LongActionOutcome outcome_);

validateClosePosition

See validateClosePosition.

function validateClosePosition(
    address payable validator,
    bytes calldata closePriceData,
    Types.PreviousActionsData calldata previousActionsData
) external returns (Types.LongActionOutcome outcome_);

_validateOpenPositionWithAction

Validates an open position action.

function _validateOpenPositionWithAction(Types.PendingAction memory pending, bytes calldata priceData)
    public
    returns (bool isValidated_, bool isLiquidated_, Types.PositionId memory posId_);

Parameters

Returns

_initiateOpenPosition

Initiates an open position action.

Consult the current oracle middleware implementation to know the expected format for the price data, using the ProtocolAction's InitiateOpenPosition action. The price validation might require payment according to the return value of the validationCost function of the middleware. The position is immediately included in the protocol calculations with a temporary entry price (and thus leverage). The validation operation then updates the entry price and leverage with fresher data.

function _initiateOpenPosition(Types.InitiateOpenPositionParams memory params, bytes calldata currentPriceData)
    internal
    returns (Types.PositionId memory posId_, uint256 amountToRefund_, bool isInitiated_);

Parameters

Returns

_validateOpenPosition

Retrieves the pending action data of the owner, try to validate it and clear it if successful.

function _validateOpenPosition(address validator, bytes calldata priceData)
    internal
    returns (uint256 securityDepositValue_, bool isValidated_, bool isLiquidated_, Types.PositionId memory posId_);

Parameters

Returns

_validateOpenPositionUpdateBalances

Updates the protocol balances during validateOpenPosition to reflect the new entry price of the position.

We need to adjust the balances because the position that was created during the initiateOpenPosition might have gained or lost some value, and we need to reflect that the position value is now newPosValue. Any potential PnL on that temporary position must be "cancelled" so that it doesn't affect the other positions and the vault.

function _validateOpenPositionUpdateBalances(uint256 newPosValue, uint256 oldPosValue) internal;

Parameters

_prepareValidateOpenPositionData

Updates protocol balances, liquidate positions if necessary, then validate the open position action.

function _prepareValidateOpenPositionData(Types.PendingAction memory pending, bytes calldata priceData)
    internal
    returns (Types.ValidateOpenPositionData memory data_, bool isLiquidated_);

Parameters

Returns

_initiateClosePosition

Initiates a close position action.

Consult the current oracle middleware implementation to know the expected format for the price data, using the ProtocolAction's InitiateClosePosition action. The price validation might require payment according to the return value of the validationCost function of the middleware. If the current tick version is greater than the tick version of the position (when it was opened), then the position has been liquidated and this function will return 0. The position is taken out of the tick and put in a pending state during this operation. Thus, calculations don't consider this position anymore. The exit price (and thus profit) is not yet set definitively and will be done during the validate action.

function _initiateClosePosition(
    Types.InitiateClosePositionParams memory params,
    bytes calldata currentPriceData,
    bytes calldata delegationSignature
) internal returns (uint256 amountToRefund_, bool isInitiated_, bool isLiquidated_);

Parameters

Returns

_validateClosePosition

Retrieves the pending action data of the validator, try to validate it and clear it if successful.

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

Parameters

Returns

_validateClosePositionWithAction

Updates protocol balances, liquidate positions if necessary, then validate the close position action.

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

Parameters

Returns

Structs

ValidateClosePositionWithActionData

Data structure for the _validateClosePositionWithAction function.

struct ValidateClosePositionWithActionData {
    bool isLiquidationPending;
    uint128 priceWithFees;
    uint128 liquidationPrice;
    int256 positionValue;
}

Properties

MaxLeverageData

Data structure for the _validateOpenPositionWithAction function.

struct MaxLeverageData {
    uint24 currentLiqPenalty;
    Types.PositionId newPosId;
    uint24 liquidationPenalty;
}

Properties

UsdnProtocolActionsUtilsLibrary

Git Source

Functions

liquidate

See liquidate.

function liquidate(bytes calldata currentPriceData) external returns (Types.LiqTickInfo[] memory liquidatedTicks_);

validateActionablePendingActions

See validateActionablePendingActions.

function validateActionablePendingActions(
    Types.PreviousActionsData calldata previousActionsData,
    uint256 maxValidations
) external returns (uint256 validatedActions_);

transferPositionOwnership

See transferPositionOwnership.