SuperformRouter

Introduction

SuperformRouter calls Superform core contracts to deposit or withdraw from vaults listed on Superform. Integrators should note that functions have been split apart and optimized for each possible vault action, and users should be routed as such based on their intention.

Core Concepts

All routers must implement functions from BaseRouterImplementation using the internal default implementation from BaseRouter. The primary purpose of this router is to facilitate deposit and withdrawal operations.

Liquidity Request

The base request required for constructing all other data types through Superform is called LiqRequest

struct LiqRequest {
    bytes txData; 
    address token; 
    address interimToken; 
    uint8 bridgeId;
    uint64 liqDstChainId; 
    uint256 nativeAmount;
}

Name	Description
txData	bytes txData to move funds, obtained via starting routes through the appropriate bridgeId API below. Optional to implement on withdrawals, Keeper will update
token	address of the token the user is using or requesting. On deposits this is the user's starting token, and on withdrawals this is the token the user wants to receive on the appropriate liqDstChainId
interimToken	address of the token that is allowed to be used as an interim token on the destination chain on deposits by DstSwapper to be swapped into the vault token. Will be set to 0 on withdrawals
bridgeId	uint8 representing the bridge being used. 1 = LiFi, 2 = Socket, 3 = SocketOneInch
liqDstChainId	uint64 representing the final destination chain for the liquidity in the bridgeRequest. On deposits it is the same as the chain of the Superform, but on withdrawals it can be any supported chain id by the bridge
nativeAmount	uint256 amount of native tokens that will be passed in the liquidity request (0 if native tokens are not being swapped or bridged)

Superform Vault Data

LiqRequest is used to create two base datatypes that will be referred to as SingleVaultSFData and MultiVaultSFData.

SingleVaultSFData: datatype format for a single vault action

struct SingleVaultSFData {
    uint256 superformId;
    uint256 amount;
    uint256 outputAmount;
    uint256 maxSlippage;
    LiqRequest liqRequest;
    bytes permit2data;
    bool hasDstSwap;
    bool retain4626;
    address receiverAddress;
    address receiverAddressSP
    bytes extraFormData; 
}

Name	Description
superformId	uint256 superformId to interact with
amount	uint256 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 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
liqRequest	LiqRequest from above
permit2data	bytes permit2 data (0x if none)
hasDstSwap	bool to indicate if the transaction will have a swap on destination before depositing (always false for withdrawals)
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 be used on the destination chain to either refund the user if tokens are stuck or send vault shares if retain4626 is true. this is also used in withdrawals to receive withdrawn tokens . this address should always be an EOA.
receiverAddressSP	address to be used on the source chain to receive SuperPositions if retain4626 is false this address can be an EOA or a contract that implements onERC1155Receiver to accept the SuperPositions. it does not need to be set to any address on withdrawals.
extraFormData	bytes optional data depending on the Form

MultiVaultSFData: datatype format for a multi vault action

struct MultiVaultSFData {
	uint256[] superformIds;
	uint256[] amounts; 
	uint256[] outputAmounts;
	uint256[] maxSlippages; 
	LiqRequest[] liqRequests;
	bytes permit2data;
	bool[] hasDstSwaps;
	bool[] retain4626s;
	address receiverAddress; 
	address receiverAddressSP;
	bytes extraFormData; 
}

Name	Description
superformIds	uint256[] array of superformIds to interact with
amounts	uint256[] array of the expected amount of token or vault in question (deposits = expected amount of vault underlying token being received on destination chain, withdrawal = amount of SuperPositions being burned per superformId)
outputAmounts	uint256[] array of the 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)
maxSlippages	uint256[] array of the numbers 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
liqRequests	array of LiqRequests from above
permit2data	bytes permit2 data (0x if none)
hasDstSwaps	bool[] array to indicate if the transaction will have a swap on destination before depositing (always false for withdrawal)
retain4626s	bool[] array to indicate if the user wants to send the respective ERC4626 to the receiver address (if true, user retains it, and doesn't get a SuperPosition)
receiverAddress	address to be used on the destination chain to either refund the user if tokens are stuck or send vault shares if retain4626 is true. this is also used in withdrawals: to receive withdrawn tokens . this address should always be an EOA.
receiverAddressSP	address to be used on the source chain to receive SuperPositions if retain4626 is false this address can be an EOA or a contract that implements onERC1155Receiver to accept the SuperPositions.
extraFormData	bytes optional data depending on the Form

Datatypes -> Functions

SingleVaultSFData and MultiVaultSFData consist of 6 specialized deposit and withdrawal functions each.

Deposit Functions

singleDirectSingleVaultDeposit

Deposit into a single vault using tokens on the same chain.

Example: Use tokens on Ethereum to deposit into a vault on Ethereum.

function singleDirectSingleVaultDeposit(SingleDirectSingleVaultStateReq memory req)

struct SingleDirectSingleVaultStateReq {
    SingleVaultSFData superformData;
}

Name	Description
superformData	SingleVaultSFData (refer to struct in beginning of reference)

singleXChainSingleVaultDeposit

Deposit into a single vault on one chain with tokens from another chain.

Example: Use tokens on Ethereum to deposit into a vault on Avalanche.

function singleXChainSingleVaultDeposit(SingleXChainSingleVaultStateReq memory req)

struct SingleXChainSingleVaultStateReq {
    uint8[] ambIds;
    uint64 dstChainId;
    SingleVaultSFData superformData;
}

Name	Description
ambIds	uint8 array indicating which AMBs to use for the given dstChainId, first one being the message, second proof
dstChainId	uint64 destination EVM chain ID
superformData	SingleVaultSFData (refer to struct in beginning of reference)

singleDirectMultiVaultDeposit

Deposit into multiple vaults one one chain with tokens on the same chain.

Example: Use tokens on Ethereum to deposit into three vaults on Ethereum.

function singleDirectMultiVaultDeposit(SingleDirectMultiVaultStateReq memory req)

struct SingleDirectMultiVaultStateReq {
    MultiVaultsSFData superformsData;
}

Name	Description
superformsData	array of MultiVaultsSFData (refer to struct in beginning of reference)

singleXChainMultiVaultDeposit

Deposit into multiple vaults on one chain with tokens from another chain.

Example: Use tokens on Ethereum to deposit into three vaults on Fantom.

function singleXChainMultiVaultDeposit(SingleXChainMultiVaultStateReq memory req)

struct SingleXChainMultiVaultStateReq {
    uint8[] ambIds;
    uint64 dstChainId;
    MultiVaultsSFData superformsData;
}

Name	Description
ambIds	uint8 array indicating which AMBs to use for the given dstChainId, first one being the message, second proof
dstChainIds	uint64 destination EVM chain IDs
superformsData	array of MultiVaultsSFData (refer to struct in beginning of reference)

multiDstSingleVaultDeposit

Deposit into a single vault on multiple different chains with tokens from any chain.

Example: Use tokens on Ethereum to deposit into one vault on Base, one vault on Optimism, and one vault on Arbitrum.

function multiDstSingleVaultDeposit(MultiDstSingleVaultStateReq calldata req)

struct MultiDstSingleVaultStateReq {
	uint8[][] ambIds;
	uint64[] dstChainIds;
	SingleVaultSFData[] superformsData;
}

Name	Description
ambIds	uint8 array of arrays indicating which AMBs to use for each chainId in dstChainIds, first one being the message, second proof
dstChainIds	uint64 array of destination EVM chain IDs
superformsData	array of SingVaultSFData (refer to struct in beginning of reference)

multiDstMultiVaultDeposit

Deposit into multiple vaults on multiple different chains with tokens from any chain.

Example: Use tokens on Ethereum to deposit into two vaults on Base, one vault on Optimism, and three vaults on Arbitrum.

function multiDstMultiVaultDeposit(MultiDstMultiVaultStateReq calldata req)

struct MultiDstMultiVaultStateReq {
	uint8[][] ambIds;
	uint64[] dstChainIds;
	MultiVaultsSFData[] superformsData;
}

Name	Description
ambIds	uint8 array of arrays indicating which AMBs to use for each chainId in dstChainIds, first one being the message, second proof
dstChainIds	uint64 array of destination EVM chain IDs
superformsData	array of MultiVaultsSFData (refer to struct in beginning of reference)

Withdraw Functions

singleDirectSingleVaultWithdraw

Withdraw tokens from a single vault when SuperPositions are the same chain.

Example: Withdraw from a vault on Ethereum when SuperPositions are held on Ethereum.

function singleDirectSingleVaultWithdraw(singleDirectSingleVaultStateReq memory req)

struct SingleDirectSingleVaultStateReq {
    SingleVaultSFData superformData;
}

Name	Description
superformData	SingleVaultSFData (refer to struct in beginning of reference)

singleXChainSingleVaultWithdraw

Withdraw tokens from a single vault when SuperPositions are on a different chain.

Example: Withdraw from a vault on Ethereum when SuperPositions are held on Optimism.

function singleXChainSingleVaultWithdraw(SingleXChainSingleVaultStateReq memory req)

struct SingleXChainSingleVaultStateReq {
    uint8[] ambIds;
    uint64 dstChainId;
    SingleVaultSFData superformData;
}

Name	Description
ambIds	uint8 array indicating which AMBs to use for the given dstChainId, first one being the message, second proof
dstChainId	uint64 destination EVM chain ID
superformData	SingleVaultSFData (refer to struct in beginning of reference)

singleDirectMultiVaultWithdraw

Withdraw tokens from multiple vaults when SuperPositions are on the same chain.

Example: Withdraw from three vaults on Ethereum when SuperPositions are held on Ethereum

function singleDirectMultiVaultWithdraw(SingleDirectMultiVaultStateReq memory req)

struct SingleDirectMultiVaultsStateReq {
    MultiVaultsSFData superformsData;
}

Name	Description
superformsData	array of MultiVaultsSFData (refer to struct in beginning of reference)

singleXChainMultiVaultWithdraw

Withdraw tokens from multiple vaults on one chain when SuperPositions are on a different chain.

Example: Withdraw from three vaults on Ethereum when SuperPositions are held on Optimism

function singleXChainMultiVaultWithdraw(SingleXChainMultiVaultStateReq memory req)

struct SingleXChainMultiVaultStateReq {
    uint8[] ambIds;
    uint64 dstChainId;
    MultiVaultsSFData superformsData;
}

Name	Description
ambIds	uint8 array indicating which AMBs to use for the given dstChainId, first one being the message, second proof
dstChainIds	uint64 destination EVM chain IDs
superformsData	array of MultiVaultsSFData (refer to struct in beginning of reference)

multiDstSingleVaultWithdraw

Withdraw tokens from a single vault on multiple different chains when SuperPositions are on a single chain.

Example: Withdraw from one vault on Optimism, one vault on Arbitrum, and one vault on Ethereum, when SuperPositions are held on Ethereum.

function multiDstSingleVaultWithdraw(MultiDstSingleVaultStateReq calldata req)

struct MultiDstSingleVaultStateReq {
	uint8[][] ambIds;
	uint64[] dstChainIds;
	SingleVaultSFData[] superformsData;
}

Name	Description
ambIds	uint8 array of arrays indicating which AMBs to use for each chainId in dstChainIds, first one being the message, second proof
dstChainIds	uint64 array of destination EVM chain IDs
superformsData	array of SingleVaultSFData (refer to struct in beginning of reference)

multiDstMultiVaultWithdraw

Withdraw tokens from a multiple vaults on multiple different chains when SuperPositions are on a single chain.

Example: Withdraw from two vaults on Optimism, one vault on Arbitrum, and three vaults on Ethereum, when SuperPositions are held on Ethereum.

function multiDstMultiVaultWithdraw(MultiDstMultiVaultStateReq calldata req)

struct MultiDstMultiVaultStateReq {
	uint8[][] ambIds;
	uint64[] dstChainIds;
	MultiVaultsSFData[] superformsData;
}

Name	Description
ambIds	uint8 array of arrays indicating which AMBs to use for each chainId in dstChainIds, first one being the message, second proof
dstChainIds	uint64 array of destination EVM chain IDs
superformsData	array of MultiVaultsSFData (refer to struct in beginning of reference)
extraDataPerDst	array of extraData needed per destination chain

PayMaster

Within every cross-chain function _forwardPayment is called to send the required amount of tokens to a PayMaster contract to cover the cost of cross-chain transactions made by Keepers.