📡 Router contract

The main entry point of the Protocol that handles all incoming write transactions.

provideLiquidity

function provideLiquidity(
    FutureId futureId,
    UD60x18 notional,
    UD60x18 depositAmount,
    SD59x18 lowerBound,
    SD59x18 upperBound,
    uint deadline,
    bool settleMaturedPositions,
    OraclePackage[] calldata oraclePackages
) external payable returns (LiquidityProvisionResult memory, MarginWithThreshold memory);

Function for providing liquidity to a particular future.

Facilitates the provision of notional amount of liquidity for futureId in range between lowerBound and upperBound rates.

Optionally a deposit could be made alongside the trade by setting depositAmount param for ERC20 tokens, msg.value for native tokens or both for a double deposit. (Check deposit section for details)

The actual provided notional amount could differ from the requested due to rounding. The resulting value can be checked in LiquidityProvisionResult return struct.

Parameter Name	Type	Description
futureId	FutureId	Future identifier.
notional	uint256	The maximum face amount for trades using the liquidity being provided
depositAmount	uint256	The amount of underlying ERC-20 to be deposited.
lowerBound	int256	Defines the lower point of the rate range. Format: fixed point signed 18-decimal number.
upperBound	int256	Defines the upper point of the rate range. Format: fixed point signed 18-decimal number.
deadline	uint256	Specifies a timestamp by which the transaction must be processed. Transactions mined after this timestamp will revert.
settleMaturedPositions	bool	Boolean that when true will trigger the internal optimisation mechanism, that lowers the gas consumption for further calls in case there is a matured Position in user's portfolio.
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

Output values:

• LiquidityProvisionResult

• MarginWithThreshold

---

removeLiquidity

function removeLiquidity(
    FutureId futureId,
    UD60x18 notional,
    SD59x18 lowerBound,
    SD59x18 upperBound,
    uint deadline,
    bool settleMaturedPositions,
    OraclePackage[] calldata oraclePackages
) external returns (LiquidityRemovalResult memory, MarginWithThreshold memory);

Function for removing liquidity from a future.

Removes notional amount of liquidity from given futureId in range from lowerBound to upperBound.

Ensure that there is provided liquidity in selected range before calling the function.

Parameter Name	Type	Description
futureId	FutureId	Target Future identifier.
notional	uint256	Defines how much of the provided liquidity will be removed given the user's existing notional
lowerBound	int256	Defines the lower point of the rate range. Format: fixed point signed 18-decimal number.
upperBound	int256	Defines the upper point of the rate range. Format: fixed point signed 18-decimal number.
deadline	uint256	Specifies a timestamp by which the transaction must be processed. Transaction attempted after this timestamp will revert.
settleMaturedPositions	bool	Triggers the internal optimization mechanism, that lowers the gas consumption for further calls in case there is a matured Position in user's portfolio.
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

Output values:

• LiquidityRemovalResult

• MarginWithThreshold

---

deposit

function deposit(
  MarketId marketId,
  address recipient,
  UD60x18 amount,
  bool settleMaturedPositions,
  OraclePackage[] calldata oraclePackages
) external payable;

Deposits funds for collateral from the caller into the cross-margin account of the recipient for specific marketId.

The function can be called in different ways:

1. ERC-20 token deposit An amount of the ERC-20 asset, defined as the underlying for a given marketId , is being transferred from the msg.sender to the recipient 's cross-margin account.

2. Native token deposit (ETH) Is available only for Markets that use wrapped native assets (e.g: WETH) as underlying. The deposit amount is specified by the caller in form of a {value: amount_in_eth} during the call. Deposited native tokens get wrapped into their ERC20 version.

3. Hybrid — ERC-20 & ETH deposit together An amount parameter can be used together with {value: amount_in_eth} parameter of the same call. That allows to deposit two assets in a single call.

Before depositing ERC-20 assets make sure that the Router contract has allowance() to transfer funds on behalf of the caller for the Market's underlying asset. Use ERC-20's standard approve() for setting this allowance.

These 3 different ways to deposit are also supported on functions:

• provideLiquidity

• executeTrade

• transferPositionsOwnership

Input parameters:

Parameter Name	Type	Description
marketId	MarketId	Target Market identifier.
recipient	address	The address of the participant whose cross-margin account is to be updated.
amount	uint256	The amount of ERC-20 assets to be deposited.
settleMaturedPositions	bool	Triggers the internal optimisation mechanism, that lowers the gas consumption for further calls in case there is a matured Position in user's portfolio.
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

---

withdraw

function withdraw(
  MarketId marketId,
  bool unwrapNativeToken,
  UD60x18 amount,
  bool settleMaturedPositions,
  OraclePackage[] calldata oraclePackages
) external;

Function for the caller to reduce their collateral amount in the specified marketId. Ensure you have sufficient collateral above the IMR threshold before calling this function.

Input parameters:

Parameter Name	Type	Description
marketId	MarketId	Target Market identifier.
unwrapNativeToken	bool	Determines wether the wrapped token should be unwrapped to native token upon withdrawal.
amount	uint256	The amount of ERC-20 assets to be withdrawn.
settleMaturedPositions	bool	Triggers the internal optimisation mechanism, that lowers the gas consumption for further calls in case there is a matured Position in user's portfolio.
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

---

executeTrade

function executeTrade(
  FutureId futureId,
  RiskDirection.Value direction,
  UD60x18 notional,
  SD59x18 futureRateLimit,
  UD60x18 depositAmount,
  uint256 deadline,
  bool settleMaturedPositions,
  OraclePackage[] memory oraclePackages
) external payable returns (TradeInfo memory, MarginWithThreshold memory);

Executes an interest rate future trade for the specified futureId with chosen risk direction (either as a Payer or a Receiver) and notional value.

Optionally a deposit could be made alongside the trade by setting depositAmount param for ERC20 tokens, msg.value for native tokens or both for a double deposit. (Check deposit section for details)

Parameter Name	Type	Description
futureId	FutureId	Target Future identifier.
direction	RiskDirection.Value	Specifies trade's risk direction: Receiver or Payer
notional	uint256	The face value of the future trade.
futureRateLimit	int256	Sets the worst acceptable rate. For Payer it's the upper limit, for Receiver — lower limit. Format: fixed point signed 18-decimal number.
depositAmount	uint256	The amount of ERC-20 assets to be deposited. If 0, no deposit will be made, so the user should have enough margin to cover this trade
deadline	uint256	Specifies a timestamp by which the transaction must be processed. If the transaction is mined after this timestamp, it will revert. Format: Unix timestamp in seconds
settleMaturedPositions	bool	Triggers the internal optimisation mechanism, that lowers the gas consumption for further calls in case there is a matured Position in user's portfolio.
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

Output values:

• TradeInfo

• MarginWithThreshold

---

persistIndexAtMaturity

function persistIndexAtMaturity(
    FutureId futureId, 
    OraclePackage calldata oraclePackage
) external;

Persists the index value for a future at maturity. Can only be called by maturity couriers.

Parameter Name	Type	Description
futureId	FutureId	Target Future identifier.
oraclePackage	OraclePackage	A package containing the latest known index for the market. Packages are provided by an Oracle service on demand.

---

updateAndGetLastIndex

function updateAndGetLastIndex(
    MarketId marketId, 
    OraclePackage[] calldata oraclePackages
) external returns (SD59x18);

Updates and returns the last index for a market using provided oracle packages.

Parameter Name	Type	Description
marketId	MarketId	Target Market identifier.
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

Output values:

• int256 The updated last index value for the market

---

cancelProvisions

function cancelProvisions(
    MarketId marketId,
    address maker,
    OraclePackage[] calldata oraclePackages
) external returns (UD60x18 reward);

Cancels the liquidity provision positions for the maker in specified marketId when his margin is less than minimal required.

As a result the caller would get a reward amount of underlying tokens as an incentive.

Parameter Name	Type	Description
marketId	MarketId	Target Market identifier.
maker	address	Address of the user, whose liquidity allocation is to be cancelled
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

Output values:

• uint256 Amount of reward obtained from the cancellation

---

liquidatePositions

function liquidatePositions(
  MarketId marketId,
  FutureId[] calldata futureIds,
  UD60x18[] calldata positionsPercentage,
  address owner,
  bool settleMaturedPositions,
  OraclePackage[] calldata oraclePackages
) external returns (TradeInfo[] memory tradesInfo, UD60x18 reward);

Liquidate positions of the owner, whose margin fell below the Liquidation Threshold in a specific Market. To determine whether a user's position could be liquidated use Quoter.isLiquidatable call.

Liquidations are carried out against the liquidity that is provided by Makers to the Futures' pool.

The caller performs trades on behalf of positions owner , but in the opposite direction, effectively lowering user's exposure to the risk. In return the liquidator gets a reward that is deducted from owner's margin account.

This function can only be called by users with LIQUIDATOR role.

Parameter Name	Type	Description
marketId	MarketId	Target Market identifier.
futureIds	FutureId[]	Array of Futures that are targeted to be liquidated.
positionsPercentage	uint256[]	Array of percentages of the positions to be liquidated. Order of elements should correspond to order of futureIds above. Format: fixed point unsigned 18-decimal number, values from 0 to 1.
owner	address	Address of the user being liquidated
settleMaturedPositions	bool	Triggers the internal optimization mechanism, that lowers the gas consumption for further calls in case there is a matured Position in user's portfolio.
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

Output values:

• TradeInfo[] — an array containing information about each trade performed during the liquidation

• reward — Amount of an underlying asset that was transferred to caller's margin account as an incentive for the liquidation.

---

transferPositionsOwnership

function transferPositionsOwnership(
  MarketId marketId,
  address owner,
  UD60x18 depositAmount,
  bool settleMaturedPositions,
  OraclePackage[] memory oraclePackages
) external payable returns (UD60x18 transferAmount, UD60x18 depositAmount);

Lets the caller to take over the ownership of owner's positions in specified marketId. Can be called when owner's margin is below the Liquidation Threshold. To determine whether a user's position could be liquidated use Quoter.isLiquidatable call.

As positions will be transferred to the caller, please ensure you have enough margin your account. Optionally, a deposit can also be performed along with this call.

Parameter Name	Type	Description
marketId	MarketId	Target Market identifier.
owner	address	Address of the user, whose positions are to be transferred
depositAmount	uint256	The amount of ERC-20 assets to be deposited.
settleMaturedPositions	bool	Triggers the internal optimization mechanism, that lowers the gas consumption for further calls in case there is a matured Position in user's portfolio.
oraclePackages	OraclePackage[]	An array of packages containing the latest known index for the market. Packages are provided by an Oracle service on demand.

Output values:

• uint256 transferAmount — amount of margin that was transferred from previous owner of the Position to the caller;

• uint256 depositAmount — additional amount of collateral that was required on top of caller's margin and transferred amount.

---

settleMaturedFutures

function settleMaturedFutures(MarketId marketId) external;

Settles matured positions for the called in the specified market

Parameter Name	Type	Description
marketId	MarketId	Target Market identifier.

---

collectProtocolFee

function collectProtocolFee(
    MarketId marketId, 
    address recipient,
    UD60x18 amount
) external;

Allows the collection of protocol fees for a specific market.

Parameter Name	Type	Description
marketId	MarketId	Target Market identifier.
recipient	address	Address that will receive the collected fee
amount	uint256	Amount of to be collected

---

emergencyERC20TokenTransfer

function emergencyERC20TokenTransfer(
    address tokenAddress, 
    address to, 
    uint amount
) external;

Allows the owner to make an emergency transfer of ERC20 tokens from the contract. This can be useful in situations to recover tokens accidentally sent to the contract.

Parameter Name	Type	Description
tokenAddress	address	Address of the ERC20 token
to	address	Address to send the tokens to
amount	uint	Amount of tokens to be sent

---

emergencyERC20TokenTransfer

function emergencyERC20TokenTransfer(
    address tokenAddress, 
    address to, 
    uint amount
) external;

Allows the owner to make an emergency transfer of native tokens from the contract. This can be useful in situations to recover tokens accidentally sent to the contract.

Parameter Name	Type	Description
to	address	Address to send the tokens to
amount	uint	Amount of tokens to be sent

---

getContractProvider

function getContractProvider() external view returns (IContractProvider);

Returns ContractProvider contract

---

getAcm

function getAcm() external view returns (IAccessControlManager);

Returns AccessControlManager contract

---

Structs

Documentation on all the structs mentioned in this page:

LiquidityProvisionResult

Result of a provide liquidity transaction

struct LiquidityProvisionResult {
  UD60x18 providedNotional;
  UD60x18 totalPoolNotional;
}

Property name	Property Type	Description
providedNotional	uint256	Notional amount of the liquidity provided
totalPoolNotional	uint256	Notional amount of allocated liquidity across all rate ranges for a future

---

MarginWithThreshold

Provides information about margin account state

struct MarginWithThreshold {
  Margin.Value currentMargin;
  SD59x18 marginThreshold;
}

Property name	Property Type	Description
currentMargin	Margin.Value	Updated information about current P&L and deposited collateral
marginThreshold	int256	Minimal margin requirements after the trade

---

---

---