SuperPositions

Introduction

When users deposit into vaults through SuperformRouter, users lock the underlying ERC4626 vault share in the respective Form contract and SuperPositions are minted to the user on the chain they deposited from (unless retain4626 is set to True).

SuperPositions are designed to provide superior UX and composability by allowing vault shares to be represented on any chain, lower transaction costs related to the management of a user's positions, and more easily facilitate cross-chain interactions. SuperPositions inherit from ERC1155A, an opinionated variant of ERC1155 which includes single id approvals for better control of the approval process.

Core Concepts

AMBMessage

SuperPositions are minted on callbacks from cross-chain destinations through usage of an AMBMessage with a CallbackType of RETURN or FAIL.

struct AMBMessage {
    uint256 txInfo; 
    bytes params;
}

Name	Description
txInfo	uint256 ticket packing of TransactionType txType, CallbackType flag, if multi/single vault, registryId, srcSender and srcChainId
params	bytes decoded into ReturnMultiData or ReturnData, else it reverts

Minting SuperPositions

SuperPositions can be minted through mintSingle, mintBatch on same-chain deposits and via stateMultiSync or stateSync functions on cross-chain deposits - all restricted in being called by either SuperformRouter in same-chain actions or CoreStateRegistry in cross-chain action.

function mintBatch(
    address receiverAddressSP_,
    uint256[] memory ids_,
    uint256[] memory amounts_
)
    external
    virtual
    override;

Name	Description
receiverAddressSP_	address of the receiver of the SuperPositions
ids_	uint256 ids of Superforms
amounts_	uint256 amounts of the SuperPositions being minted

function mintSingle(address receiverAddressSP_, uint256 id_, uint256 amount_) external virtual override;

Name	Description
receiverAddressSP_	address of the receiver of the SuperPositions
id_	uint256 id of a Superform
amount_	uint256 amount of the SuperPositions being minted

function stateMultiSync(AMBMessage memory data_) external virtual override returns (uint64 srcChainId_);
function stateSync(AMBMessage memory data_) external virtual override returns (uint64 srcChainId_);

Name	Description
data_	AMBMessage above

It is the responsibility of each implementation contract to support these functions and make them perform according to the intended specification.

Burning SuperPositions

SuperPositions can be burned through burnSingle or burnBatch functions. The burn action happens optimistically at the beginning of a withdrawal action through a call made from a SuperformRouter.

function burnBatch(
    address srcSender_,
    uint256[] memory ids_,
    uint256[] memory amounts_
)
    external
    virtual
    override;

Name	Description
srcSender_	address of user who owns the SuperPositions
ids_	uint256 ids of Superforms
amounts_	uint256 amounts of the SuperPositions being burned

function burnSingle(address srcSender_, uint256 id_, uint256 amount_) external virtual override;

Name	Description
srcSender_	address of user who owns the SuperPositions
id_	uint256 id a Superform
amount_	uint256 amount of the SuperPosition being burned

dynamicURI

Each SuperPosition has a dynamic URI that points to metadata about the SuperPosition. Once dynamicURIFrozen is set to true, this URI cannot be changed anymore.