CoreStateRegistry implements and extends BaseStateRegistry and is used by core contracts to fulfill cross-chain deposits to all Forms and cross-chain withdrawals from vaults contained in ERC4626Form.

Core Concepts


This function allows the core contracts to send messages (payloads) to state registries on other chains. The entire message is sent to the first ambId in the index via _dispatchPayload and for chains that support more than one AMB, the proof of the message is sent to the other ambIds in the index via _dispatchProof. The user must supply at least 1 + the Quorum (typically 1) required ambIds.

 function dispatchPayload(
    address srcSender_,
    uint8[] memory ambIds_,
    uint64 dstChainId_,
    bytes memory message_,
    bytes memory extraData_
) external payable;


This function allows state registries to receive messages (payloads) from AMB implementations on other chains. Depending on the size of the message, this is handled differently as either a full payload or a proof.

function receivePayload(
    uint64 srcChainId_,
    bytes memory message_
) external;


This function allows any appropriately permissioned actor to process payloads on the state registry.

function processPayload(
    uint256 payloadId_
) external payable returns ();

Access Control Modifiers

There are multiple gated functions in the CoreStateRegistry contract.

  • CORE_STATE_REGISTRY_UPDATER_ROLE may update parameters within pre-defined ranges by the user on deposits and withdrawals in updateDepositPayload and updateWithdrawPayload

  • CORE_STATE_REGISTRY_PROCESSOR_ROLE may process payloads in processPayload

  • CORE_STATE_REGISTRY_RESCUER_ROLE may propose the amount of tokens that can be rescued in proposeRescueFailedDeposits

  • CORE_STATE_REGISTRY_DISPUTER_ROLE may, in addition to the user whose tokens were in question, dispute the amount of funds proposed to be rescued during the time window in disputeRescueFailedDeposits

At this time, both of these roles are executed by Superform infrastructure but will be removed as the protocol decentralizes.

Updating Deposits

On deposits, the amount of token being received on the destination chain can only be updated within a certain range. The range is determined by what the caller specified they intended to receive in submitting the Superform Request.


Updates a payload once transactions are confirmed to finalize the amount of tokens received on the destination chain before processing the deposit.

function updateDepositPayload(
    uint256 payloadId_,
    address[] calldata finalTokens_),
    uint256[] calldata finalAmounts_) external;

Updating Withdrawals

Updates a payload that corresponds to a multi-vault withdrawal with liquidity data if the user didn't submit any liquidity data. This increases the chance of successful withdrawals and still maintains security validations on-chain to ensure the correct tokens are received back to the user.


function updateWithdrawPayload(
    uint256 payloadId_,
    bytes[] calldata txData_) external;

Rescuing payloads

There are 4 steps involved in rescuing funds from stuck payloads.

  1. View all failed deposits for a given payload id

  2. CoreStateRegistryRescuer must propose the amount of tokens to be rescued for a user for a payload id

  3. There is a set amount of time to dispute this number

  4. If not disputed in that timeframe by user or CoreStateRegistryDisputer, anybody can rescue the payload, sending funds back to the dstRefundAddress.


Allows anyone to see which deposits in a payload have failed.

function getFailedDeposits(
        uint256 payloadId_
) external view returns (uint256[] memory superformIds_, uint256[] memory amounts);


Allows RESCUER to propose the amount of tokens that should be rescued for a given payloadId.

function proposeRescueFailedDeposits(
    uint256 payloadId_,
    uint256[] memory proposedAmounts_
) external override onlyCoreStateRegistryRescuer


Allows the initial user and DISPUTER to challenge the final receiving token amounts on failed deposits if within the challenge time window.

function disputeRescueFailedDeposits(
    uint256 payloadId_
) external override


Allows anyone to finalize the amount of tokens to be received after the challenge period is over.

function finalizeRescueFailedDeposits(
    uint256 payloadId_
) external override

Last updated