InterfaceInbox

Git Source

Functions

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

NameTypeDescription
snapPayloadbytesRaw payload with snapshot data
snapSignaturebytesAgent signature for the snapshot

Returns

NameTypeDescription
attPayloadbytesRaw payload with data for attestation derived from Notary snapshot. Empty payload, if a Guard snapshot was submitted.
agentRootbytes32Current root of the Agent Merkle Tree (zero, if a Guard snapshot was submitted)
snapGasuint256[]Gas data for each chain in the snapshot Empty list, if a Guard snapshot was submitted.

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

NameTypeDescription
rcptPayloadbytesRaw payload with receipt data
rcptSignaturebytesNotary signature for the receipt
paddedTipsuint256Tips for the message execution
headerHashbytes32Hash of the message header
bodyHashbytes32Hash of the message body excluding the tips

Returns

NameTypeDescription
wasAcceptedboolWhether the receipt was accepted

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

NameTypeDescription
rcptPayloadbytesRaw payload with Receipt data that Guard reports as invalid
rcptSignaturebytesNotary signature for the reported receipt
rrSignaturebytesGuard signature for the report

Returns

NameTypeDescription
wasAcceptedboolWhether the Report was accepted (resulting in Dispute between the agents)

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

NameTypeDescription
attNotaryIndexuint32Index of the Notary who signed the attestation
attNonceuint32Nonce of the attestation used for proving the executed message
paddedTipsuint256Tips for the message execution
rcptPayloadbytesRaw payload with message execution receipt

Returns

NameTypeDescription
wasAcceptedboolWhether the receipt was accepted

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

NameTypeDescription
attPayloadbytesRaw payload with Attestation data
attSignaturebytesNotary signature for the attestation

Returns

NameTypeDescription
isValidAttestationboolWhether the provided attestation is valid. Notary is slashed, if return value is FALSE.

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

NameTypeDescription
attPayloadbytesRaw payload with Attestation data that Guard reports as invalid
arSignaturebytesGuard signature for the report

Returns

NameTypeDescription
isValidReportboolWhether the provided report is valid. Guard is slashed, if return value is FALSE.