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