SDK
Voltz SDK

Introduction

The below is an SDK for Voltz protocol. The main functions used in the amm.ts entity are documented below.

vAMM

mint()

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.
1
public async mint({
2
fixedLow,
3
fixedHigh,
4
notional,
5
margin,
6
validationOnly,
7
}
Copied!
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.

getInfoPostMint()

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 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).
1
public async getInfoPostMint({
2
fixedLow,
3
fixedHigh,
4
notional,
5
}
Copied!
1
public async getInfoPostMint({
2
fixedLow,
3
fixedHigh,
4
notional,
5
}
Copied!
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

burn()

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.
1
public async burn({
2
fixedLow,
3
fixedHigh,
4
notional,
5
validationOnly,
6
}
Copied!
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.

swap()

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.
1
public async swap({
2
isFT,
3
notional,
4
margin,
5
fixedRateLimit,
6
fixedLow,
7
fixedHigh,
8
validationOnly,
9
}
Copied!
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.

getInfoPostSwap()

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.
1
public async getInfoPostSwap({
2
isFT,
3
notional,
4
fixedRateLimit,
5
fixedLow,
6
fixedHigh,
7
}
Copied!
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
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 annualised fixed rate in the IRS pool before and after the execution of the swap.

Margin Engine

updatePositionMargin()

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).
1
public async updatePositionMargin({
2
owner,
3
fixedLow,
4
fixedHigh,
5
marginDelta,
6
}
Copied!
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.

settlePosition()

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.
1
public async settlePosition({
2
owner,
3
fixedLow,
4
fixedHigh,
5
}
Copied!
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

getLiquidationThreshold()

The liquidationThreshold function returns the liquidation margin which is the threshold (as a percentage of the notional) below which your position is liquidatable, i.e. anyone can come and liquidate (unwind) your position in return for a liquidator reward proportional to the liquidated position’s margin balance. This function calls the MarginEngine.sol contract’s getPositionMarginRequirement method.
1
public async getLiquidationThreshold({
2
owner,
3
fixedLow,
4
fixedHigh,
5
}
Copied!
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
threshold
number
Liquidation threshold as a proportion of the notional value

liquidatePosition()

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.
1
public async liquidatePosition({
2
owner,
3
fixedLow,
4
fixedHigh,
5
}
Copied!
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
liquidatorReward
number
Reward for unwinding and/or removing the supplied liquidity of the liquidated position

Aave v2 FCM

fcmSwap()

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.
1
public async FCMSwap({
2
notional,
3
fixedRateLimit,
4
}
Copied!
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.

fcmUnwind()

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.
1
public async FCMUnwind({
2
notionalToUnwind,
3
fixedRateLimit,
4
}
Copied!
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.

settleFCMTrade()

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).
1
public async settleFCMTrader()
Copied!
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

Ancillary

approveERC20()

The function approveERC20 ensures Voltz Protocol has permission to withdraw the allocated amount of tokens from an owner’s wallet.
1
public async approveERC20(
2
marginDelta: BigNumberish,
3
addressToApprove: string,
4
)
Copied!
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

getVariableApy()

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.
1
public async getVariableApy()
Copied!
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.

approveFCM()

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.
1
public async approveFCM()
Copied!
Returns
Name
Type
Description
approvalTransaction
number
Verify approval for transaction