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.
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
​Contract 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 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
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.
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
​Contract 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.
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.
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.
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.
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).
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.
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.
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
Returns
Name
Type
Description
receipt
ContractReceipt
Object containing information about the settlement
getPositionMarginRequirement()
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 
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.
 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.
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.
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.
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.
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.
settleFCMTrader()
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
getInfoPostFCMSwap()
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,
Parameters
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.
Returns
​
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.
getInfoPostFCMUnwind()
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,
Parameters
​
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.
Returns
​
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.
isFCMApproved()
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()
Returns
Name
Type
Description
isApproved
boolean
True if the FCM transaction was approved.
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.
public async approveFCM()
Returns
Name
Type
Description
approvalTransaction
number
Verify approval for transaction
isUnderlyingTokenApprovedForFCM()
This function confirms whether the AaveFCM.sol contract has permission to perform transactions on behalf of the signer.
 public async isUnderlyingTokenApprovedForFCM()
Returns
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. 
approveUnderlyingTokenForFCM()
This function aims to approve the signer's tokens for use by the Periphery.sol contract. 
 public async approveUnderlyingTokenForFCM()
Returns
Name
Type
Description
receipt
ContractReceipt
Object containing approval of the tokens.
Ancillary
approveERC20()
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
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.
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.
isUnderlyingTokenApprovedForPeriphery()
The function isUnderlyingTokenApprovedForPeriphery confirms whether the Periphery.sol contract has permission to perform transactions on behalf of the signer. 
 public async isUnderlyingTokenApprovedForPeriphery()
Returns
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. 
approveUnderlyingTokenForPeriphery()
This function aims to approve the signer's tokens for use by the Periphery.sol contract. 
 public async approveUnderlyingTokenForPeriphery()
Returns
Name
Type
Description
receipt
ContractReceipt
Object containing approval of the tokens.
isYieldBearingTokenApprovedForFCM()
This function confirms whether the Aave factory and Compound factory contracts have permission to perform transactions on behalf of the signer. 
 public async isYieldBearingTokenApprovedForFCM()
Returns
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. 
approveYieldBearingTokenForFCM()
This function aims to approve the signer's tokens for use by the Aave and Compound factory contracts. 
 public async approveYieldBearingTokenForFCM()
Returns
Name
Type
Description
receipt
ContractReceipt
Object containing approval of the tokens.
getFixedApr()
This function allows you to get the fixed rate APR by calling the getCurrentTick method in the MarginEngine.sol contract. 
 public async getFixedApr()
Returns
Name
Type
Description
apr
number
Current fixed APR
getAllSwaps()
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)
Returns
Name
Type
Description
allSwaps
list
Contains fdelta, vdelta and timestamp for swaps, fcm swaps, and fcm unwinds. 
getAccruedCashflow()
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
Returns
Name
Type
Description
accruedCashFlow
BigNumber
Accrued cashflow of all transactions in a given position. 
getVariableFactor() deprecated
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)
Parameters
Name
Type
Description
termStartTimestamp
BigNumber
Start time
termEndTimestamp
BigNumber
End time
Returns
Name
Type
Description
resultScaled
number
Variable factor
getPositionInformation()
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)
Parameters
Name
Type
Description
position
Position
Position object containing information about the specified position.
Returns
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. 
closestTickAndFixedRate()
This function returns the closest usable tick and closest usable fixed rate for a given provided fixed rate. 
 public closestTickAndFixedRate(fixedRate: number)
Parameters
Name
Type
Description
fixedRate
number
The fixed rate of return for a given pool.
Returns
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.

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

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

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.

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.

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.

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.

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
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

Name	Type	Description
termStartTimestamp	BigNumber	Start time
termEndTimestamp	BigNumber	End time

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.

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.