Forms

Introduction

Forms are intermediaries for deposit and withdrawal actions to and from vaults on Superform. All Form implementations must adhere to the BaseForm interface and may override available virtual functions for added functionality from the standard deposit/withdraw functionality.

When vaults are added to Forms they create Superforms.

Currently the only Form type supported is for the ERC4626 standard. Superform Labs has started development of a Timelock Form and a KYCDAO form which could be added by at a later date. The community is strongly encouraged to develop their own Forms to support more yield types on Superform.

Core Concepts

Deposit and Withdraw

Interaction with Superforms happens through the four implemented external functions in BaseForm. They are split by same-chain (only accessible by SuperformRouter) and crosschain access (only accessible by CoreStateRegistry). These specific functions are implemented in individual Form implementations.

Information to perform actions is encapsulated in the form of a struct through InitSingleVaultData (actions are performed on a per vault basis):

InitSingleVaultData

struct InitSingleVaultData {
    uint256 payloadId;
    uint256 superformId;
    uint256 amount;
    uint256 outputAmount;
    uint256 maxSlippage;
    LiqRequest liqData;
    bool hasDstSwap;
    bool retain4626;
    address receiverAddress;
    bytes extraFormData;
}

Name	Description
payloadId	uint256 id of the payload from the source chain (generated in SuperformRouter)
superformId	uint256 id of the Superform to perform the action on
amount	uint256 of the expected amount of token or vault in question (deposits = expected amount of token being received on destination chain, withdrawal = number of SuperPositions being burned)
outputAmount	uint256 expected amount of outputs from the deposit/redeem action (deposits = expected amount of vault shares being received on destination chain, withdrawal = expected amount of tokens being received)
maxSlippage	uint256 number from 0 to 10000 indicating acceptable slippage in bps (i.e. 10000 = 100% slippage) to go from input token to output token, which could include both bridging and swapping
liqData	bytes data contains liquidity information for swapping/bridging from forms (see SuperformRouter)
hasDstSwap	bool to indicate if the route has a swap on the destination chain
retain4626	bool to indicate if the user wants to send the ERC4626 to the receiver address (if true, user receives ERC4626 shares instead of being minted SuperPositions)
receiverAddress	address to refund the user on the destination chain if tokens are stuck
receiverAddressSP	address to mint SuperPositions so on the source chain
extraFormData	bytes reserved for future use

directDepositIntoVault

This function is called if depositing into a vault using tokens on the same chain as the vault.

function directDepositIntoVault(
    InitSingleVaultData memory singleVaultData_, 
    address srcSender_ 
) external payable override onlySuperRouter returns (uint256 dstAmount)

Name	Description
singleVaultData_	Takes the form of InitSingleVaultData (represented above)
srcSender_	address of the user making the action

xChainDepositIntoVault

This function is called if depositing into a vault using tokens on a different chain than the vault.

function xChainDepositIntoVault(
  InitSingleVaultData memory singleVaultData_,
  address srcSender_,
  uint64 srcChainId_
) external override onlyCoreStateRegistry returns (uint256 dstAmount)

Name	Description
singleVaultData_	Takes the form of InitSingleVaultData (represented above)
srcSender_	address of the user making the action
srcChainId_	uint64 id of the originating chain for the action

directWithdrawFromVault

This function is called if withdrawing SuperPositions that are held on the same chain as the vault.

function directWithdrawFromVault(
    InitSingleVaultData memory singleVaultData_,
    address srcSender_
) external override onlySuperRouter returns (uint256 dstAmount)

Name	Description
singleVaultData_	Takes the form of InitSingleVaultData (represented above)
srcSender_	address of the user making the action

xChainWithdrawFromVault

This function is called if withdrawing SuperPositions that are held on a different chain than the vault.

function xChainWithdrawFromVault(
    InitSingleVaultData memory singleVaultData_,
    address srcSender_,
    uint64 srcChainId_
) external override onlyCoreStateRegistry returns (uint256 dstAmount)

Name	Description
singleVaultData_	Takes the form of InitSingleVaultData (represented above)
srcSender_	address of the user making the action
srcChainId_	uint64 id of the originating chain for the action

Emergency Queue

This function is called by Forms when they are paused by the EmergencyAdmin. These requests are made by the EmergencyQueue.

function emergencyWithdraw(
    address receiverAddress_,
    uint256 amount_
) external override onlyEmergencyQueue

name
receiverAddress_	address to send tokens back to
amount_	uint256 amount to refund

View Functions

superformYieldTokenName

This function returns a standardized name for the Superform (using the vault name).

function superformYieldTokenName() external view virtual override returns (string memory)

superformYieldTokenSymbol

This function returns a standardized symbol for the Superform (using the vault symbol).

function superformYieldTokenSymbol() external view virtual override returns (string memory)

formImplementationId

This function returns the associated Form which the vault has been added to.

function formImplementationId() external view virtual override returns (uint32)

getStateRegistryId

This function returns the associated state registry for the Form which the vault has been added to.

function getStateRegistryId() external view virtual override returns (uint8)

getVaultAddress

This function returns the address of the vault.

function getVaultAddress() public view virtual override returns (address)

getVaultAsset

This function returns the address of the underlying for the vault.

function getVaultAsset() public view virtual override returns (address)

getVaultName

This function returns the name of the vault.

function getVaultName() public view virtual override returns (string memory)

getVaultSymbol

This function returns the symbol of the vault.

function getVaultSymbol() public view virtual override returns (string memory)

getVaultDecimals

This function returns the decimals of the vault.

function getVaultDecimals() public view virtual override returns (uint256)

getPricePerVaultShare

This function calls convertToAssets correcting for vault decimals.

function getPricePerVaultShare() public view virtual override returns (uint256)

getVaultShareBalance

This function returns the balance of vault shares within the Superform.

function getVaultShareBalance() public view virtual override returns (uint256)

getTotalAssets

This function returns the total balance of underlying tokens deposited into the vault.

function getTotalAssets() public view virtual override returns (uint256)

getPreviewPricePerVaultShare

This function calls previewRedeem on vault with the correct number of decimals.

function getPreviewPricePerVaultShare() public view virtual override returns (uint256)

previewDepositTo

This function calls convertToShares on vault with the specified number of assets_.

function previewDepositTo(uint256 assets_) public view virtual override returns (uint256)

previewWithdrawFrom

This function calls previewWithdraw on vault with the specified number of assets_.

function previewWithdrawFrom(uint256 assets_) public view virtual override returns (uint256)

previewRedeemFrom

This function calls previewRedeem on vault with the specified number of shares_.

function previewRedeemFrom(uint256 shares_) public view virtual override returns (uint256)