CoreStateRegistry

Introduction

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

dispatchPayload

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;
name
description

srcSender_

address to be refunded if overpaid

ambIds_

uint8[] array of the AMB ids

dstChainId_

uint64 EVM chainId

message_

bytes payload to be sent

extraData_

bytes extraData if override is needed

receivePayload

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;
name
description

srcChainId_

uint64 is the EVM chainId from which the payload is dispatched/sent

message_

bytes payload to receive

processPayload

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

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

payloadId_

uint256 of the payloadId to process

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.

updateDepositPayload

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;
name
description

payloadId_

uint256 payloadId assigned on the dstChain that needs to be updated

finalTokens_

address[] array of the final tokens received to deposit into the vault (should match vault token)

finalAmounts_

uint256[] array of the amounts of the tokens that were received that should be deposited into the vault. For single vault payloads the array must contain only one value.

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.

updateWithdrawPayload

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

payloadId_

uint256 payloadId assigned on the dstChain that needs to be updated

txData_

bytes[] of transaction data that the payload must be updated with. For single vault payloads the array must contain only one value.

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.

getFailedDeposits

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

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

payloadId_

uint256 payloadId in question

proposeRescueFailedDeposits

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
name
description

payloadId_

uint256 payloadId in question

proposedAmounts_

uint256 array of proposed amount of tokens to be withdrawn

disputeRescueFailedDeposits

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
name
description

payloadId_

uint256 payloadId in question

finalizeRescueFailedDeposits

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

function finalizeRescueFailedDeposits(
    uint256 payloadId_
) external override
name
description

payloadId_

uint256 payloadId in question

Last updated