Building a Vault

Vault Interface

Strategy vault builders need to implement the IStrategyVault interface. Notional has a BaseStrategyVault implementation that takes care of many implementation details so vault designers can focus on their yield strategy implementation.

Vault Controller implementation is in VaultAction and VaultAccountAction. Generally speaking, accounts will initiate all transactions by calling one of enterVault, exitVault or rollVaultPosition on VaultAccountAction. Liquidators will call deleverageAccount on VaultAccountAction.

Developers should be aware of the following:

• Strategy Tokens MUST always be denominated in 8 decimal places when communicating with Notional. If the underlying yield strategy uses a different token precision, it must be scaled accordingly.

• Notional’s Vault Controller will handle the vast majority of bookkeeping for vaults, there should be limited need to do bookkeeping within vaults. If you find yourself needing to track balances on the vault itself, please discuss this with the team.

• Notional sends and receives ETH natively, not WETH.

• All token denominations will be supplied in their native token decimal precision.

• The BaseStrategyVault implements base methods that handle vault specific logic. Developers can override _depositFromNotional and _redeemFromNotional to take advantage of existing logic.

• The vault's address (address(this)) is used during depositFromNotional and redeemFromNotional to signify that an action is being taken on behalf of the entire vault.

• BaseStrategyVault also allows developers to access the Notional Trade Module which supports trading with slippage limits across many popular DEX protocols (Curve, Balancer V2, Uniswap V2 & V3 and 0x).

• If vaults require additional logic that should be executed before enterVault or exitVault, vaults can be configured such that all transactions begin from the vault and users cannot call exitVault or enterVault directly. This may be useful for protocols that want to build on top of leveraged vaults and integrate more fully control the user experience.

• All vaults must implement a programmatic way to settle their positions to cash for settlement. See redeemStrategyTokensToCash.

Special Vault Methods

redeemStrategyTokensToCash

As vaults reach maturity, they must repay outstanding debts by converting strategy tokens to cash. Vaults must implement some method where this method is called to redeem a portion of strategy tokens to repay debts on behalf of all accounts in the vault. Settlement is done as a pool for all accounts in the entire vault. If unsure on how to proceed, discuss with the team on how to design a settlement process for your vault. This is often the most difficult part of vault design.

How much a vault currently needs to repay its debt can be queried by calling getCashRequiredToSettle on Notional. Once redeemStrategyTokensToCash is called, accounts may no longer enter or increase their positions in a particular vault maturity. Accounts can still exit or roll their positions to a future maturity.

depositVaultCashToStrategyTokens

Vaults may also call redeemStrategyTokensToCash prior to settlement in an emergency scenario if the vault is at risk. If that occurs, accounts will be prevented from entering that vault maturity. Vaults may opt to call depositVaultCashToStrategyTokens in order to re-deposit cash positions into yield strategy tokens once the emergency condition is no longer present. This would allow accounts to again increase their vault positions.

borrowSecondaryCurrencyToVault

Vaults that want to borrow in secondary currencies can call this method to borrow additional currencies on behalf of an account. Secondary currencies must be whitelisted by governance.

repaySecondaryCurrencyFromVault

Vaults that borrow in secondary currencies can call this method to repay secondary debts.

initiateSecondaryBorrowSettlement

Vaults that borrow in secondary currencies must call this method to snapshot specific values before it goes into a settlement process.

settleVault

Although this method is technically callable by anyone, vaults should call this method once they complete their settlement process. If a vault has special settlement requirements, this method can be authenticated on the Notional side such that only the vault can call. In general, we strive to ensure that as few calls require administrative control as possible so we encourage vault designers to design their settlement process such that it can be safely initiated by anyone.