SDK
Voltz SDK
The mint function adds liquidity to a given position that is identified by its owner address, upper tick, and lower tick. Minting will fail if the position’s margin balance in underlying tokens is below the initial margin requirement of the position following a mint. This function calls the mintOrBurn method in the Periphery.sol smart contract.
To check the position margin requirement before the mint you can get the minimum initial margin requirement by calling getMinimumMarginRequirementPostMint here.
Additionally, the mint will revert if the address of the position owner does not match that of the
msg.sender
and the msg.sender
is not approved by the position owner.public async mint({
fixedLow,
fixedHigh,
notional,
margin,
validationOnly,
}
Parameters
Name | Type | Description |
---|---|---|
fixedLow | number | Lower bound of Fixed Rate Range |
fixedHigh | number | Upper bound of Fixed Rate Range |
notional | number | Notional amount traded in underlying tokens (e.g. USDC) |
margin | number | Additional margin in underlying tokens deposited by the position in the Margin Engine |
validationOnly | boolean | Checks if input parameters are valid by effectively initiating a counterfactual swap via a static call to the blockchain which does not perform any state updates |
Returns
Name | Type | Description |
---|---|---|
receipt | Mint Transaction Receipt issued as a result of a successfully mined mint transaction. |
The getInfoPostMint function shows the additional margin amount in underlying tokens (e.g. USDC) required to be deposited into the position's margin account to successfully execute a mint.
The function returns 0 if the current margin in the position margin account is greater than the margin requirement. Otherwise, it returns the additional margin needed in underlying tokens (e.g. USDC) for the liquidity provision transaction to execute. This function calls the mintOrBurn method in the Periphery.sol smart contract, and the MarginEngine contract (in order to top up the margin account of the position).
The function returns 0 if the current margin in the position margin account is greater than the margin requirement. Otherwise, it returns the additional margin needed in underlying tokens (e.g. USDC) for the liquidity provision transaction to execute. This function calls the mintOrBurn method in the Periphery.sol smart contract, and the Margin Engine contract (in order to top up the margin account of the position).
public async getInfoPostMint({
fixedLow,
fixedHigh,
notional,
}
Parameters
Name | Type | Description |
---|---|---|
fixedLow | number | Lower bound of Fixed Rate Range |
fixedHigh | number | Upper bound of Fixed Rate Range |
notional | number | Notional amount traded in underlying tokens (e.g. USDC) |
Returns
Name | Type | Description |
---|---|---|
scaledMarginRequirement - scaledCurrentMargin | number | The additional margin needed to execute the liquidity provision transaction alongside optional margin account top up |
The burn function removes liquidity from a given liquidity provider position; the position is uniquely identified by its owner address, upper tick and lower fixed rate bounds. This function calls the mintOrBurn method in the Periphery.sol smart contract.
public async burn({
fixedLow,
fixedHigh,
notional,
validationOnly,
}
Parameters
Name | Type | Description |
---|---|---|
fixedLow | number | Lower bound of Fixed Rate Range |
fixedHigh | number | Upper bound of Fixed Rate Range |
notional | number | Notional amount traded in underlying tokens (e.g. USDC) |
validationOnly | boolean | Checks if input parameters are valid by effectively initiating a counterfactual swap via a static call to the blockchain which does not perform any state updates |
Returns
Name | Type | Description |
---|---|---|
receipt | Mint Transaction Receipt issued as a result of a successfully mined mint transaction. |
The swap function enters a given position into an interest rate swap where the counterparty is the pool of Liquidity Providers (LPs) who are active in the tick (fixed rate) range crossed while executing the swap along the vAMM.
The swap will fail if the position margin balance in underlying tokens is below the initial margin requirement of the position following the initiation of the interest rate swap. This function calls the mintOrBurn method in the Periphery.sol smart contract.
Each Interest Rate Swap initiated on Voltz Protocol will incur a fee in underlying tokens (e.g. USDC) which the position owner needs to pay to the liquidity providers (in the active tick range). Refer to Section 3 of the litepaper for more information on fee calculation mechanics.
To check the position margin requirement before the swap you can get the minimum margin requirement from getInfoPostSwap here.
public async swap({
isFT,
notional,
margin,
fixedRateLimit,
fixedLow,
fixedHigh,
validationOnly,
}
Parameters
Name | Type | Description |
---|---|---|
isFT | boolean | If set to true, execute a fixed taker interest rate swap. If set to false, execute a variable taker interest rate swap. |
notional | number | Notional amount traded in underlying tokens (e.g. USDC) |
margin | number | Additional margin in underlying tokens deposited by the position in the Margin Engine |
fixedRateLimit | number | Fixed Rate beyond wish you are not comfortable executing a swap. |
fixedLow | number | Lower bound of Fixed Rate Range |
fixedHigh | number | Upper bound of Fixed Rate Range |
validationOnly | boolean | Checks if input parameters are valid by effectively initiating a counterfactual swap via a static call to the blockchain which does not perform any state updates |
Returns
Name | Type | Description |
---|---|---|
marginRequirement | number | Additional margin amount required to successfully execute the interest rate swap |
availableNotional | number | Notional amount from liquidity providers in the IRS pool available to be swapped with the trader |
fee | number | Fee incurred by the trader in underlying tokens (e..g USDC) |
slippage | number | Percentage point difference between the annualized fixed rate in the IRS pool before and after the execution of the swap. |
The function getInfoPostSwap provides the additional margin requirement in underlying tokens after an IRS swap has been initiated. This function interacts with the MarginEngine.sol contract’s getPosition method.
public async getInfoPostSwap({
isFT,
notional,
fixedRateLimit,
fixedLow,
fixedHigh,
}
Parameters
Name | Type | Description |
---|---|---|
isFT | boolean | If set to true, execute a fixed taker interest rate swap. If set to false, execute a variable taker interest rate swap. |
notional | number | Notional amount traded in underlying tokens (e.g. USDC) |
fixedLow | number | Lower bound of Fixed Rate Range |
fixedHigh | number | Upper bound of Fixed Rate Range |
Returns
Name | Type | Description |
---|---|---|
availableNotional | number | Notional amount from liquidity providers in the IRS pool available to be swapped with the trader |
fee | number | Fee incurred by the trader in underlying tokens (e..g USDC) |
fixedTokenDeltaUnbalanced | number | ...... |
marginRequirement | number | Additional margin amount required to successfully execute the interest rate swap |
slippage | number | Percentage point difference between the annualised fixed rate in the IRS pool before and after the execution of the swap. |
The updatePositionMargin function interacts with the MarginEngine.sol contract to update the position margin account balance in the underlying ERC20 token, the position can be uniquely identified by its owner address, upper and lower ticks (fixed rate bounds).
This function can only be successfully executed if the owner address has already set approval for the contract to withdraw the required ERC20 token amount.
Removing margin from a given position’s margin account is only possible if the function is called by the position owner address or by an address trusted by the position owner.
If a position is engaged in active interest rate swaps, it is only possible to remove margin as long as the remaining balance in the margin account is above or equal to the initial margin requirement of the position. Adding margin on behalf of a position owner can be done by any
address (msg.sender)
.public async updatePositionMargin({
owner,
fixedLow,
fixedHigh,
marginDelta,
}
Parameters
Name | Type | Description |
---|---|---|
owner | string | Address of the position owner |
fixedLow | number | Lower bound of fixed rate range |
fixedHigh | number | Upper bound of fixed rate range |
marginDelta | number | The delta (either positive or negative) applied to the margin account of the position in underlying tokens. If positive, the margin account balance will increase, otherwise margin will be withdrawn. |
The settlePosition function can only be called after a given IRS pool has matured. A position with an active interest rate swap can call the settlePosition function to settle (fixed-to-variable or variable-to-fixed) cashflows with the IRS pool.
This function interacts with the MarginEngine.sol contract’s settlePosition method and emits an event with the settlement cash flow at maturity of the IRS swap contract.
public async settlePosition({
owner,
fixedLow,
fixedHigh,
}
Parameters
Name | Type | Description |
---|---|---|
owner | string | Address of the position owner |
fixedLow | number | Lower bound of fixed rate range |
fixedHigh | number | Upper bound of fixed rate range |
Name | Type | Description |
---|---|---|
receipt | ContractReceipt | Object containing information about the settlement |
The getPositionMarginRequirement function returns the position margin for a specific position. This function calls the MarginEngine.sol contract’s getPositionMarginRequirement method.
async getPositionMarginRequirement(
fixedLow: number,
fixedHigh: number)
Parameters
Name | Type | Description |
---|---|---|
fixedLow | number | Lower bound of fixed rate range |
fixedHigh | number | Upper bound of fixed rate range |
Returns
Name | Type | Description |
---|---|---|
requirement | BigNumber | Position margin requirement |
The liquidatePosition function can only be called before maturity of the IRS pool in which the position was initiated. It returns the liquidator reward in underlying tokens (e.g. USDC) after calling on the MarginEngine.sol contract.
A liquidation event with the liquidated position’s owner address, tickLower, tickUpper, position.fixedTokenBalance, position.variableTokenBalance, position.margin and position._liquidity is also emitted.
public async liquidatePosition({
owner,
fixedLow,
fixedHigh,
}
Parameters
Name | Type | Description |
---|---|---|
owner | string | Address of the position owner |
fixedLow | number | Lower bound of fixed rate range |
fixedHigh | number | Upper bound of fixed rate range |
Returns
Name | Type | Description |
---|---|---|
receipt | ContractReceipt | Object containing information about the liquidation such as liquidator reward. |
The fcmSwap function engages a trader in a fully collateralised fixed taker swap, i.e. it enables the trader to deposit the underlying yield bearing tokens (e.g. aUSDC) to fully collateralise the variable leg (liability) of their position.
As part of the transaction, the trader needs to pay liquidity provider fees in underlying tokens (e.g. USDC). This function interacts with the AaveFCM.sol contract’s initiateFullyCollateralisedFixedTakerSwap method.
public async FCMSwap({
notional,
fixedRateLimit,
}
Parameters
Name | Type | Description |
---|---|---|
notional | number | Notional amount traded in underlying tokens (e.g. USDC) |
fixedRateLimit | number | Fixed Rate beyond which you are not executing a swap. |
The fcmUnwind function lets a trader fully or partially unwind their fully collateralised fixed taker position as long as their position is still fully collateralised post unwind.
As part of the transaction, the trader needs to pay liquidity provider fees in underlying tokens (e.g. USDC). This function interacts with the AaveFCM.sol contract’s unwindFullyCollateralisedFixedTakerSwap method.
public async FCMUnwind({
notionalToUnwind,
fixedRateLimit,
}
Parameters
Name | Type | Description |
---|---|---|
notionalToUnwind | number | Notional amount in underlying tokens (e.g. USDC) to unwind |
fixedRateLimit | number | The upper fixed rate limit beyond which you are not comfortable executing a variable taker unwind which nets out the fully collateralised fixed taker position. |
The settleFCMTrader function can only be called after a given IRS pool has matured. A position with an active fully collateralised interest rate swap can call the settleTrader method in the AaveFCM.sol contract to settle cash flows with the pool and claim their fixed yield (by forgoing the variable yield).
public async settleFCMTrader()
Returns
Name | Type | Description |
---|---|---|
traderSettlementCashflow | int256 | Settlement cash flow in terms of underlying tokens secured by the fully collateralised fixed taker post IRS pool maturity |
The getInfoPostFCMSwap() function is called to receive information after an FCM swap has been initialised. This function returns the
available notional
, fee
, fixedTokenDeltaUnbalanced,
and tickAfter
by interacting with either the Aave or Compound fcm factory contracts. public async getInfoPostFCMSwap({
notional,
fixedRateLimit,
Name | Type | Description |
---|---|---|
notional | number | Notional amount traded in underlying tokens (e.g. USDC) |
fixedRateLimit | number | Fixed Rate beyond wish you are not comfortable executing a swap. |
​
Name | Type | Description |
---|---|---|
marginRequirement | number | Notional amount traded in underlying tokens (e.g. USDC) |
availableNotional | number | Fixed Rate beyond wish you are not comfortable executing a swap. |
fee | number | Fee incurred by the trader in underlying tokens (e..g USDC) |
slippage | number | Equal to the fixedRateDeltaRaw |
averageFixedRate | number | Arithmetic mean of fixed rate before swap and the fixed rate after the slippage. |
The function getInfoPostFCMUnwind is called to receive the information about an FCM position after unwinding. It interacts with the unwindFullyCollateralisedFixedTakerSwap method in the AaveFCM.sol contract.
public async getInfoPostFCMUnwind({
notionalToUnwind,
fixedRateLimit,
​
Name | Type | Description |
---|---|---|
notionalToUnwind | number | Notional amount traded in underlying tokens (e.g. USDC) to be unwound. |
fixedRateLimit | number | Fixed Rate beyond wish you are not comfortable executing a swap. |
​
Name | Type | Description |
---|---|---|
marginRequirement | number | Notional amount traded in underlying tokens (e.g. USDC) |
availableNotional | number | Fixed Rate beyond wish you are not comfortable executing a swap. |
fee | number | Fee incurred by the trader in underlying tokens (e..g USDC) |
slippage | number | Equal to the fixedRateDeltaRaw |
averageFixedRate | number | Arithmetic mean of fixed rate before swap and the fixed rate after the slippage. |
The isFCMApproved function serves to confirm whether an FCM transaction has been approved or whether the transaction confirmation failed. It interacts with the isApproved function in the Factory.sol contract.
public async isFCMApproved()
Name | Type | Description |
---|---|---|
isApproved | boolean | True if the FCM transaction was approved. |
The function approveFCM interacts with the Factory.sol contract to allow external contract approvals so this contract can interact with the Voltz Protocol positions on the traders behalf. This function specifically checks if a given owner address has approved a specific intermediary address (contract or externally owned account) to interact with the IRS pools on Voltz Protocol on behalf of the owner.
public async approveFCM()
Returns
Name | Type | Description |
---|---|---|
approvalTransaction | number | Verify approval for transaction |
This function confirms whether the AaveFCM.sol contract has permission to perform transactions on behalf of the signer.
public async isUnderlyingTokenApprovedForFCM()
Name | Type | Description |
---|---|---|
allowance.get(ThresholdApprovalBn) | boolean | If the approved threshold is less than the allowance available for the Periphery contract this returns true and the tokens are approved for the Periphery. |
This function aims to approve the signer's tokens for use by the Periphery.sol contract.
public async approveUnderlyingTokenForFCM()
Name | Type | Description |
---|---|---|
receipt | ContractReceipt | Object containing approval of the tokens. |
The function approveERC20 ensures Voltz Protocol has permission to withdraw the allocated amount of tokens from an owner’s wallet.
public async approveERC20(
marginDelta: BigNumberish,
addressToApprove: string,
)
Name | Type | Description |
---|---|---|
marginDelta | BigNumberish | The delta (either positive or negative) applied to the margin account of the position in underlying tokens. If positive, the margin account balance will increase, otherwise margin will be withdrawn. |
addressToApprove | string | Address which must approve the token withdrawal |
The function getVariableApy returns the historical APY in the underlying yield-bearing pool (e.g. Aave v2 USDC), by checking if the cached historical APY is expired and querying the rate oracle through the MarginEngine.sol smart contract’s getHistoricalApy method.
public async getVariableApy()
Returns
Name | Type | Description |
---|---|---|
historicalApy | number | Historical APY in the underlying yield-bearing pool (e.g. Aave v2 USDC Lending Pool). The historical APY is calculated via the respective rate oracle on Voltz Protocol. |
The function isUnderlyingTokenApprovedForPeriphery confirms whether the Periphery.sol contract has permission to perform transactions on behalf of the signer.
public async isUnderlyingTokenApprovedForPeriphery()
Name | Type | Description |
---|---|---|
allowance.get(ThresholdApprovalBn) | boolean | If the approved threshold is less than the allowance available for the Periphery contract this returns true and the tokens are approved for the Periphery. |
This function aims to approve the signer's tokens for use by the Periphery.sol contract.
public async approveUnderlyingTokenForPeriphery()
Name | Type | Description |
---|---|---|
receipt | ContractReceipt | Object containing approval of the tokens. |
This function confirms whether the Aave factory and Compound factory contracts have permission to perform transactions on behalf of the signer.
public async isYieldBearingTokenApprovedForFCM()
Name | Type | Description |
---|---|---|
allowance.get(ThresholdApprovalBn) | boolean | If the approved threshold is less than the allowance available for the Periphery contract this returns true and the tokens are approved for the Periphery. |
This function aims to approve the signer's tokens for use by the Aave and Compound factory contracts.
public async approveYieldBearingTokenForFCM()
Name | Type | Description |
---|---|---|
receipt | ContractReceipt | Object containing approval of the tokens. |
This function allows you to get the fixed rate APR by calling the getCurrentTick method in the MarginEngine.sol contract.
public async getFixedApr()
Name | Type | Description |
---|---|---|
apr | number | Current fixed APR |
This functions returns an object which contains contains the fixed delta, variable delta, and timestamp for each swap, fcm swap and fcm unwind transaction by taking in a position as an argument.
public getAllSwaps(position: Position)
Name | Type | Description |
---|---|---|
allSwaps | list | Contains fdelta, vdelta and timestamp for swaps, fcm swaps, and fcm unwinds. |
This function gets the accrued cashflow for all the swaps performed by a position. It takes
allSwaps
as an argument. public async getAccruedCashflow(allSwaps: {
fDelta: BigNumber,
vDelta: BigNumber,
timestamp: BigNumber
Name | Type | Description |
---|---|---|
accruedCashFlow | BigNumber | Accrued cashflow of all transactions in a given position. |
This function gets the variable factor from the base BaseRateOracle.sol contract. It takes the the start and end times for the period in question and returns the scaled variable Factor.
public async getVariableFactor(termStartTimestamp: BigNumber, termEndTimestamp: BigNumber)
Name | Type | Description |
---|---|---|
termStartTimestamp | BigNumber | Start time |
termEndTimestamp | BigNumber | End time |
Name | Type | Description |
---|---|---|
resultScaled | number | Variable factor |
This function returns the information for a specific position. It returns the notional in USD, margin in USD, margin, accrued cashflow in USD, accrued cashflow and whether the position has matured, yet.
public async getPositionInformation(position: Position)
Name | Type | Description |
---|---|---|
position | Position | Position object containing information about the specified position. |
Name | Type | Description |
---|---|---|
notionalInUSD | number | Amount of notional traded in a specific position in USD. |
marginInUSD | number | Amount of margin deposited in a specific position in USD. |
margin | number | Amount of margin deposited in a specific position. |
accruedCashflowInUSD | number | The accrued cashflow from the position in USD. |
accruedCashflow | number | The accrued cashflow from the position. |
beforeMaturity | boolean | True if the position has not matured, yet. |
This function returns the closest usable tick and closest usable fixed rate for a given provided fixed rate.
public closestTickAndFixedRate(fixedRate: number)
Name | Type | Description |
---|---|---|
fixedRate | number | The fixed rate of return for a given pool. |
Name | Type | Description |
---|---|---|
closestUsableTick | number | The tick which lies closest to the provided fixed rate. |
closestUsableFixedRate | Price | The closest usable fixed rate which comes from the scaled closest usable tick. |