Inbox

Git Source

Inherits: StatementInbox, InboxEvents, InterfaceInbox

Inbox is the child of StatementInbox contract, that is used on Synapse Chain. In addition to the functionality of StatementInbox, it also:

• Accepts Guard and Notary Snapshots and passes them to Summit contract.
• Accepts Notary-signed Receipts and passes them to Summit contract.
• Accepts Receipt Reports to initiate a dispute between Guard and Notary.
• Verifies Attestations and Attestation Reports, and slashes the signer if they are invalid.

State Variables

summit

address public summit;

Functions

constructor

constructor(uint32 synapseDomain_) MessagingBase("0.0.3", synapseDomain_);

initialize

Initializes Inbox contract:

• Sets msg.sender as the owner of the contract
• Sets agentManager, origin, destination and summit addresses

function initialize(address agentManager_, address origin_, address destination_, address summit_)
    external
    initializer;

submitSnapshot

Accepts a snapshot signed by a Guard or a Notary and passes it to Summit contract to save.

Snapshot is a list of states for a set of Origin contracts residing on any of the chains.

• Guard-signed snapshots: all the states in the snapshot become available for Notary signing.
• Notary-signed snapshots: Snapshot Merkle Root is saved for valid snapshots, i.e. snapshots which are only using states previously submitted by any of the Guards.
• Notary doesn't have to use states submitted by a single Guard in their snapshot.
• Notary could then proceed to sign the attestation for their submitted snapshot.

Will revert if any of these is true:

• Snapshot payload is not properly formatted.
• Snapshot signer is not an active Agent.
• Agent snapshot contains a state with a nonce smaller or equal then they have previously submitted.
• Notary snapshot contains a state that hasn't been previously submitted by any of the Guards.
• Note: Agent will NOT be slashed for submitting such a snapshot.

Notary will need to provide both agentRoot and snapGas when submitting an attestation on the remote chain (the attestation contains only their merged hash). These are returned by this function, and could be also obtained by calling getAttestation(nonce) or getLatestNotaryAttestation(notary).

function submitSnapshot(bytes memory snapPayload, bytes memory snapSignature)
    external
    returns (bytes memory attPayload, bytes32 agentRoot_, uint256[] memory snapGas);

Parameters

Returns

submitReceipt

Accepts a receipt signed by a Notary and passes it to Summit contract to save.

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.

Will revert if any of these is true:

• Receipt payload is not properly formatted.
• Receipt signer is not an active Notary.
• Receipt signer is in Dispute.
• Receipt's snapshot root is unknown.
• Provided tips could not be proven against the message hash.

function submitReceipt(
    bytes memory rcptPayload,
    bytes memory rcptSignature,
    uint256 paddedTips,
    bytes32 headerHash,
    bytes32 bodyHash
) external returns (bool wasAccepted);

Parameters

Returns

submitReceiptReport

Accepts a Guard's receipt report signature, as well as Notary signature for the reported Receipt.

ReceiptReport is a Guard statement saying "Reported receipt is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a ReceiptReport and use receipt signature from verifyReceipt() successful call that led to Notary being slashed in Summit on Synapse Chain.

Will revert if any of these is true:

• Receipt payload is not properly formatted.
• Receipt Report signer is not an active Guard.
• Receipt signer is not an active Notary.

function submitReceiptReport(bytes memory rcptPayload, bytes memory rcptSignature, bytes memory rrSignature)
    external
    returns (bool wasAccepted);

Parameters

Returns

passReceipt

Passes the message execution receipt from Destination to the Summit contract to save.

Will revert if any of these is true:

• Called by anyone other than Destination.

If a receipt is not accepted, any of the Notaries can submit it later using submitReceipt.

function passReceipt(uint32 attNotaryIndex, uint32 attNonce, uint256 paddedTips, bytes memory rcptPayload)
    external
    returns (bool wasAccepted);

Parameters

Returns

verifyAttestation

Verifies an attestation signed by a Notary.

• Does nothing, if the attestation is valid (was submitted by this Notary as a snapshot).
• Slashes the Notary, if the attestation is invalid.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.

function verifyAttestation(bytes memory attPayload, bytes memory attSignature)
    external
    returns (bool isValidAttestation);

Parameters

Returns

verifyAttestationReport

Verifies a Guard's attestation report signature.

• Does nothing, if the report is valid (if the reported attestation is invalid).
• Slashes the Guard, if the report is invalid (if the reported attestation is valid).

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation Report signer is not an active Guard.

function verifyAttestationReport(bytes memory attPayload, bytes memory arSignature)
    external
    returns (bool isValidReport);

Parameters

Returns

_verifyReceiptTips

Verifies that tips proof matches the message hash.

function _verifyReceiptTips(bytes32 msgHash, uint256 paddedTips, bytes32 headerHash, bytes32 bodyHash) internal pure;

Structs

ReceiptInfo

struct ReceiptInfo {
    AgentStatus rcptNotaryStatus;
    address notary;
    uint32 attNonce;
    AgentStatus attNotaryStatus;
}