ExecutionHub

Git Source

Inherits: AgentSecured, ReentrancyGuardUpgradeable, ExecutionHubEvents, IExecutionHub

ExecutionHub is a parent contract for Destination. It is responsible for the following:

• Executing the messages that are proven against the saved Snapshot Merkle Roots.
• Base messages are forwarded to the specified message recipient, ensuring that the original execution request is fulfilled correctly.
• Manager messages are forwarded to the local AgentManager contract.
• Keeping track of the saved Snapshot Merkle Roots (which are accepted in Destination).
• Keeping track of message execution Receipts, as well as verify their validity.

State Variables

_receiptData

(messageHash => status)

Messages coming from different origins will always have a different hash as origin domain is encoded into the formatted message. Thus we can use hash as a key instead of an (origin, hash) tuple.

mapping(bytes32 => ReceiptData) private _receiptData;

_firstExecutor

First executor who made a valid attempt of executing a message. Note: stored only for messages that had Failed status at some point of time

mapping(bytes32 => address) private _firstExecutor;

_roots

All saved snapshot roots

bytes32[] internal _roots;

_rootData

Tracks data for all saved snapshot roots

mapping(bytes32 => SnapRootData) internal _rootData;

__GAP

gap for upgrade safety

uint256[46] private __GAP;

Functions

execute

Attempts to prove inclusion of message into one of Snapshot Merkle Trees, previously submitted to this contract in a form of a signed Attestation. Proven message is immediately executed by passing its contents to the specified recipient.

*Will revert if any of these is true:

• Message is not meant to be executed on this chain
• Message was sent from this chain
• Message payload is not properly formatted.
• Snapshot root (reconstructed from message hash and proofs) is unknown
• Snapshot root is known, but was submitted by an inactive Notary
• Snapshot root is known, but optimistic period for a message hasn't passed
• Provided gas limit is lower than the one requested in the message
• Recipient doesn't implement a handle method (refer to IMessageRecipient.sol)
• Recipient reverted upon receiving a message Note: refer to libs/memory/State.sol for details about Origin State's sub-leafs.*

function execute(
    bytes memory msgPayload,
    bytes32[] calldata originProof,
    bytes32[] calldata snapProof,
    uint8 stateIndex,
    uint64 gasLimit
) external nonReentrant;

Parameters

getAttestationNonce

Returns attestation nonce for a given snapshot root.

Will return 0 if the root is unknown.

function getAttestationNonce(bytes32 snapRoot) external view returns (uint32 attNonce);

isValidReceipt

Checks the validity of the unsigned message receipt.

*Will revert if any of these is true:

• Receipt payload is not properly formatted.
• Receipt signer is not an active Notary.
• Receipt destination chain does not refer to this chain.*

function isValidReceipt(bytes memory rcptPayload) external view returns (bool isValid);

Parameters

Returns

messageStatus

Returns message execution status: None/Failed/Success.

function messageStatus(bytes32 messageHash) external view returns (MessageStatus status);

Parameters

Returns

messageReceipt

Returns a formatted payload with the message receipt.

Notaries could derive the tips, and the tips proof using the message payload, and submit the signed receipt with the proof of tips to Summit in order to initiate tips distribution.

function messageReceipt(bytes32 messageHash) external view returns (bytes memory rcptPayload);

Parameters

Returns

_executeBaseMessage

Passes message content to recipient that conforms to IMessageRecipient interface.

function _executeBaseMessage(Header header, uint256 proofMaturity, uint64 gasLimit, BaseMessage baseMessage)
    internal
    returns (bool);

_executeManagerMessage

Uses message body for a call to AgentManager, and checks the returned magic value to ensure that only "remoteX" functions could be called this way.

function _executeManagerMessage(Header header, uint256 proofMaturity, MemView body) internal returns (bool);

_passReceipt

Passes the message receipt to the Inbox contract, if it is deployed on Synapse Chain. This ensures that the message receipts for the messages executed on Synapse Chain are passed to Summit without a Notary having to sign them.

function _passReceipt(
    uint32 attNotaryIndex,
    uint32 attNonce,
    bytes32 messageHash,
    uint256 paddedTips,
    ReceiptData memory rcptData
) internal returns (bool);

_saveAttestation

Saves a snapshot root with the attestation data provided by a Notary. It is assumed that the Notary signature has been checked outside of this contract.

function _saveAttestation(Attestation att, uint32 notaryIndex, uint256 sigIndex) internal;

_isValidReceipt

Checks if receipt body matches the saved data for the referenced message. Reverts if destination domain doesn't match the local domain.

function _isValidReceipt(Receipt rcpt) internal view returns (bool);

_proveAttestation

Attempts to prove the validity of the cross-chain message. First, the origin Merkle Root is reconstructed using the origin proof. Then the origin state's "left leaf" is reconstructed using the origin domain. After that the snapshot Merkle Root is reconstructed using the snapshot proof. The snapshot root needs to have been submitted by an undisputed Notary.

Reverts if any of the checks fail.

function _proveAttestation(
    Header header,
    bytes32 msgLeaf,
    bytes32[] calldata originProof,
    bytes32[] calldata snapProof,
    uint8 stateIndex
) internal view returns (SnapRootData memory rootData);

Parameters

Returns

_messageReceipt

Formats the message execution receipt payload for the given hash and receipt data.

function _messageReceipt(bytes32 messageHash, ReceiptData memory rcptData)
    internal
    view
    returns (bytes memory rcptPayload);

Structs

SnapRootData

Struct representing stored data for the snapshot root

struct SnapRootData {
    uint32 notaryIndex;
    uint32 attNonce;
    uint40 attBN;
    uint40 attTS;
    uint32 index;
    uint40 submittedAt;
    uint256 sigIndex;
}

ReceiptData

Struct representing stored receipt data for the message in Execution Hub.

struct ReceiptData {
    uint32 origin;
    uint32 rootIndex;
    uint8 stateIndex;
    address executor;
}