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

Name	Description
`txData`	bytes `txData` to move funds, obtained via starting routes through the Superform API. 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)

txData

bytes txData to move funds, obtained via starting routes through the Superform API. 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

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

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

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

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

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

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

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)

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

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

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

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)

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

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)

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

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)

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

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

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

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)

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

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

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

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)

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

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)

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

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

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.

Last updated 4 months ago