Summit

Git Source

Inherits: SnapshotHub, SummitEvents, InterfaceSummit

Summit contract is the cornerstone of the Synapse messaging protocol. This is where the states of all the remote chains (provided collectively by the Guards and Notaries) are stored. This is also the place where the tips are distributed among the off-chain actors. Summit is responsible for the following:

• Accepting Guard and Notary snapshots from the local Inbox contract, and storing the states from these snapshots (see parent contract SnapshotHub).
• Accepting Notary Receipts from the local Inbox contract, and using them to distribute tips among the off-chain actors that participated in the message lifecycle.

State Variables

_receipts

mapping(bytes32 => SummitReceipt) private _receipts;

_receiptStatus

mapping(bytes32 => ReceiptStatus) private _receiptStatus;

_receiptTips

mapping(bytes32 => ReceiptTips) private _receiptTips;

_receiptQueue

DoubleEndedQueue.Bytes32Deque private _receiptQueue;

actorTips

Returns earned and claimed tips for the actor. Note: Tips for address(0) belong to the Treasury.

mapping(address => mapping(uint32 => ActorTips)) public actorTips;

Functions

constructor

constructor(uint32 synapseDomain_, address agentManager_, address inbox_)
    AgentSecured("0.0.3", synapseDomain_, agentManager_, inbox_);

initialize

function initialize() external initializer;

acceptReceipt

Accepts a receipt, which local AgentManager verified to have been signed by an active Notary.

Receipt is a statement about message execution status on the remote chain.

• This will distribute the message tips across the off-chain actors once the receipt optimistic period is over.
• Notary who signed the receipt is referenced as the "Receipt Notary".
• Notary who signed the attestation on destination chain is referenced as the "Attestation Notary".

Will revert if any of these is true:

• Called by anyone other than local AgentManager.
• Receipt body payload is not properly formatted.
• Receipt signer is in Dispute.
• Receipt's snapshot root is unknown.

function acceptReceipt(
    uint32 rcptNotaryIndex,
    uint32 attNotaryIndex,
    uint256 sigIndex,
    uint32 attNonce,
    uint256 paddedTips,
    bytes memory rcptPayload
) external onlyInbox returns (bool wasAccepted);

Parameters

Returns

acceptGuardSnapshot

Accepts a snapshot, which local AgentManager verified to have been signed by an active Guard.

Snapshot is a list of states for a set of Origin contracts residing on any of the chains. All the states in the Guard-signed snapshot become available for Notary signing. Will revert if any of these is true:

• Called by anyone other than local AgentManager.
• Snapshot payload is not properly formatted.
• Snapshot contains a state older then the Guard has previously submitted.

function acceptGuardSnapshot(uint32 guardIndex, uint256 sigIndex, bytes memory snapPayload) external onlyInbox;

Parameters

acceptNotarySnapshot

Accepts a snapshot, which local AgentManager verified to have been signed by an active Notary.

Snapshot is a list of states for a set of Origin contracts residing on any of the chains. Snapshot Merkle Root is calculated and saved for valid snapshots, i.e. snapshots which are only using states previously submitted by any of the Guards.

• Notary could use states singed by the same of different Guards in their snapshot.
• Notary could then proceed to sign the attestation for their submitted snapshot.

Will revert if any of these is true:

• Called by anyone other than local AgentManager.
• Snapshot payload is not properly formatted.
• Snapshot contains a state older then the Notary has previously submitted.
• Snapshot contains a state that no Guard has previously submitted.

function acceptNotarySnapshot(uint32 notaryIndex, uint256 sigIndex, bytes32 agentRoot, bytes memory snapPayload)
    external
    onlyInbox
    returns (bytes memory attPayload);

Parameters

Returns

distributeTips

Distributes tips using the first Receipt from the "receipt quarantine queue". Possible scenarios:

• Receipt queue is empty => does nothing
• Receipt optimistic period is not over => does nothing
• Either of Notaries present in Receipt was slashed => receipt is deleted from the queue
• Either of Notaries present in Receipt in Dispute => receipt is moved to the end of queue
• None of the above => receipt tips are distributed

Returned value makes it possible to do the following: while (distributeTips()) {}

function distributeTips() public returns (bool queuePopped);

Returns

withdrawTips

Withdraws locked base message tips from requested domain Origin to the recipient. This is done by a call to a local Origin contract, or by a manager message to the remote chain.

This will revert, if the pending balance of origin tips (earned-claimed) is lower than requested.

function withdrawTips(uint32 origin, uint256 amount) external;

Parameters

receiptQueueLength

Returns the amount of receipts in the "Receipt Quarantine Queue".

function receiptQueueLength() external view returns (uint256);

getLatestState

Returns the state with the highest known nonce submitted by any of the currently active Guards.

function getLatestState(uint32 origin) external view returns (bytes memory statePayload);

Parameters

Returns

_checkNotaryDisputed

*Checks if the given Notary has been disputed.

• Notary was slashed => receipt is invalided and deleted
• Notary is in Dispute => receipt handling is postponed*

function _checkNotaryDisputed(bytes32 messageHash, uint32 notaryIndex) internal returns (bool queuePopped);

_deleteFromQueue

Deletes all stored receipt data and removes it from the queue.

function _deleteFromQueue(bytes32 messageHash) internal;

_moveToBack

Moves the front element of the queue to its back.

function _moveToBack() internal;

_saveReceipt

Saves the message from the receipt into the "quarantine queue". Once message leaves the queue, tips associated with the message are distributed across off-chain actors.

function _saveReceipt(
    Receipt rcpt,
    Tips tips,
    uint32 rcptNotaryIndex,
    uint32 attNotaryIndex,
    uint256 sigIndex,
    uint32 attNonce
) internal returns (bool);

_awardTips

Awards tips to the agent/actors that participated in message lifecycle

function _awardTips(
    uint32 rcptNotaryIndex,
    uint32 attNotaryIndex,
    bytes32 messageHash,
    SummitReceipt memory summitRcpt,
    ReceiptStatus memory rcptStatus
) internal;

_awardAgentTip

Award tip to the bonded agent

function _awardAgentTip(uint32 agentIndex, uint32 origin, uint64 tip) internal;

_awardActorTip

Award tip to any actor whether bonded or unbonded

function _awardActorTip(address actor, uint32 origin, uint64 tip) internal;

_awardReceiptTip

Award tip for posting Receipt to Summit contract.

function _awardReceiptTip(uint32 rcptNotaryIndex, bool awardFirst, bool awardFinal, uint32 origin, uint64 summitTip)
    internal;

_awardSnapshotTip

Award tip for posting Snapshot to Summit contract.

function _awardSnapshotTip(uint32 attNonce, uint8 stateIndex, uint32 origin, uint64 summitTip) internal;

_snapshotTip

Returns "snapshot part" of the summit tip.

function _snapshotTip(uint64 summitTip) internal pure returns (uint64);

_receiptTip

Returns "receipt part" of the summit tip.

function _receiptTip(uint64 summitTip) internal pure returns (uint64);

Structs

SummitReceipt

struct SummitReceipt {
    uint32 origin;
    uint32 destination;
    uint32 attNonce;
    uint8 stateIndex;
    uint32 attNotaryIndex;
    address firstExecutor;
    address finalExecutor;
}

ReceiptStatus

struct ReceiptStatus {
    MessageStatus status;
    bool pending;
    bool tipsAwarded;
    uint32 receiptNotaryIndex;
    uint40 submittedAt;
}

ReceiptTips

struct ReceiptTips {
    uint64 summitTip;
    uint64 attestationTip;
    uint64 executionTip;
    uint64 deliveryTip;
}

ActorTips

Struct for storing the actor tips for a given origin domain.

struct ActorTips {
    uint128 earned;
    uint128 claimed;
}