@synapsecns/contracts-core contain the Solidity contracts used within the Synapse Interchain Network messaging system.

Usage

These contracts can be installed with:

npm i @synapsecns/contracts-core

Please refer to our usage guide or examples

Directory Structure

root
├── contracts: Contains core contracts
│   ├── base: Base contracts of the protocol
│   ├── client: Client contracts for callers of the messaging system.
│   ├── events: Event types
│   ├── hubs: Hubs
│   ├── inbox: Inbox contracts
│   ├── interfaces: Interfaces
│   ├── libs: Library contracts
│   ├── Manager: Manager contracts
├── deployments: Non-devnet deployments of the contracts
├── lib: Git-module based dependencies
├── script: Scripts for deploying + interacting with contracts
├── test: Test contracts

Running a devnet

To run a devnet, you can run make devnet-up and make devnet-deploy from this directory. This will start a local devnet and deploy the contracts to it. RPC endpoints for debugging etc will be availabe at http://localhost:9001/rpc/[chain_id].

By default, the PingPongClient.sol is deployed, so you can interact with it with cast. For instance, to send a ping from chain 42 to chain 44:

cast send 0x521F44132489CDD54c9ceC8167CfC377CbAEa351 --rpc-url http://localhost:9001/rpc/42 --private-key 0x526db1890baf94e82162f17f25ad769eb7f981272d8d99c527ea1af443c2d0cc "doPing(uint32,address,uint16)" 44 0x521F44132489CDD54c9ceC8167CfC377CbAEa351 1

Now, to make sure it work, you can pull up scribe by going to http://localhost:9002/graphiql and querying the logs for chain 44:

{

  logs(chain_id: 44, page: 1){
    topics
    block_number
    contract_address
  }
}

If everything went well, you will see topic 0x0a72872b9cfe43d6c13b13553f28d4879e427f3b456545649fd0761fdcbe0311 in the logs, which is the topic for the PingPongClient's Pong event.

Contents

• AgentSecured
• MessagingBase
• MultiCallable
• Versioned

AgentSecured

Git Source

Inherits: MessagingBase, IAgentSecured

Base contract for messaging contracts that are secured by the agent manager. AgentSecured relies on AgentManager to provide the following functionality:

• Keep track of agents and their statuses.
• Pass agent-signed statements that were verified by the agent manager.
• These statements are considered valid indefinitely, unless the agent is disputed.
• Disputes are opened and resolved by the agent manager.

AgentSecured implementation should never use statements signed by agents that are disputed.

State Variables

agentManager

Returns the address of the local AgentManager contract, which is treated as the "source of truth" for agent statuses.

address public immutable agentManager;

inbox

Returns the address of the local Inbox contract, which is treated as the "source of truth" for agent-signed statements.

Inbox passes verified agent statements to IAgentSecured contract.

address public immutable inbox;

_disputes

mapping(uint32 => DisputeStatus) internal _disputes;

__GAP

gap for upgrade safety

uint256[49] private __GAP;

Functions

onlyAgentManager

modifier onlyAgentManager();

onlyInbox

modifier onlyInbox();

constructor

constructor(string memory version_, uint32 synapseDomain_, address agentManager_, address inbox_)
    MessagingBase(version_, synapseDomain_);

openDispute

Local AgentManager should call this function to indicate that a dispute between a Guard and a Notary has been opened.

function openDispute(uint32 guardIndex, uint32 notaryIndex) external onlyAgentManager;

Parameters

resolveDispute

Local AgentManager should call this function to indicate that a dispute has been resolved due to one of the agents being slashed.

rivalIndex will be ZERO, if the slashed agent was not in the Dispute.

function resolveDispute(uint32 slashedIndex, uint32 rivalIndex) external onlyAgentManager;

Parameters

agentStatus

Returns (flag, domain, index) for a given agent. See Structures.sol for details.

Will return AgentFlag.Fraudulent for agents that have been proven to commit fraud, but their status is not updated to Slashed yet.

function agentStatus(address agent) external view returns (AgentStatus memory);

Parameters

Returns

getAgent

Returns agent address and their current status for a given agent index.

Will return empty values if agent with given index doesn't exist.

function getAgent(uint256 index) external view returns (address agent, AgentStatus memory status);

Parameters

Returns

latestDisputeStatus

Returns (flag, openedAt, resolvedAt) that describes the latest status of the latest dispute for an agent with a given index.

Will return empty values if agent with given index doesn't exist.

function latestDisputeStatus(uint32 agentIndex) external view returns (DisputeStatus memory);

Parameters

Returns

_agentStatus

Returns status of the given agent: (flag, domain, index).

function _agentStatus(address agent) internal view returns (AgentStatus memory);

_getAgent

Returns agent and their status for a given agent index. Returns zero values for non existing indexes.

function _getAgent(uint256 index) internal view returns (address agent, AgentStatus memory status);

_notaryDisputeExists

Checks if a Dispute exists for the given Notary. This function returns true, if Notary is in ongoing Dispute, or if Dispute was resolved not in Notary's favor. In both cases we can't trust Notary's data. Note: Agent-Secured contracts can trust Notary data only if both _notaryDisputeExists and _notaryDisputeTimeout return false.

function _notaryDisputeExists(uint32 notaryIndex) internal view returns (bool);

_notaryDisputeTimeout

Checks if a Notary recently won a Dispute and is still in the "post-dispute" timeout period. In this period we still can't trust Notary's data, though we can optimistically assume that that the data will be correct after the timeout (assuming no new Disputes are opened). Note: Agent-Secured contracts can trust Notary data only if both _notaryDisputeExists and _notaryDisputeTimeout return false.

function _notaryDisputeTimeout(uint32 notaryIndex) internal view returns (bool);

MessagingBase

Git Source

Inherits: MultiCallable, Versioned, Ownable2StepUpgradeable

Base contract for all messaging contracts.

• Provides context on the local chain's domain.
• Provides ownership functionality.
• Will be providing pausing functionality when it is implemented.

State Variables

localDomain

Domain of the local chain, set once upon contract creation

uint32 public immutable localDomain;

synapseDomain

uint32 public immutable synapseDomain;

__GAP

gap for upgrade safety

uint256[50] private __GAP;

Functions

constructor

constructor(string memory version_, uint32 synapseDomain_) Versioned(version_);

renounceOwnership

Should be impossible to renounce ownership; we override OpenZeppelin OwnableUpgradeable's implementation of renounceOwnership to make it a no-op

function renounceOwnership() public override onlyOwner;

MultiCallable

Git Source

Collection of Multicall utilities. Fork of Multicall3: https://github.com/mds1/multicall/blob/master/src/Multicall3.sol

Functions

multicall

Aggregates a few calls to this contract into one multicall without modifying msg.sender.

function multicall(Call[] calldata calls) external returns (Result[] memory callResults);

Structs

Call

struct Call {
    bool allowFailure;
    bytes callData;
}

Result

struct Result {
    bool success;
    bytes returnData;
}

Versioned

Git Source

Version getter for contracts. Doesn't use any storage slots, meaning it will never cause any troubles with the upgradeable contracts. For instance, this contract can be added or removed from the inheritance chain without shifting the storage layout.

State Variables

_length

Length of the "version string"

uint256 private immutable _length;

_data

Bytes representation of the "version string". Strings with length over 32 are not supported!

bytes32 private immutable _data;

Functions

constructor

constructor(string memory version_);

version

function version() external view returns (string memory versionString);

Structs

_ShortString

Struct that is mimicking the storage layout of a string with 32 bytes or less. Length is limited by 32, so the whole string payload takes two memory words:

struct _ShortString {
    uint256 length;
    bytes32 data;
}

Contents

• BaseClient
• MessageRecipient
• PingPongClient
• TestClient

BaseClient

Git Source

Inherits: MessageRecipient

*Implementation of IMessageRecipient interface, to be used as the recipient of base messages passed by the Destination contract. BaseClient could be used as a backbone for cross-chain apps:

• A single BaseClient contract per chain (aka trusted sender)
• Only BaseClient instances from other chains are able to send messages to this contract
• BaseClient enforces a common optimistic period for all types of messages Note: BaseClient is forever stateless, meaning it can be potentially used as a parent for the upgradeable contract without worrying about storage collision.*

Functions

constructor

constructor(address origin_, address destination_) MessageRecipient(origin_, destination_);

optimisticPeriod

Period of time since the root was submitted to Destination. Once this period is over, root can be used for proving and executing a message though this Client.

function optimisticPeriod() public view virtual returns (uint32);

trustedSender

Address of the trusted sender on the destination chain. The trusted sender will be able to:

• Send messages to this contract from other chains.
• Receive messages from this contract on other chains.

function trustedSender(uint32 destination) public view virtual returns (bytes32);

_receiveBaseMessageUnsafe

*Child contracts should implement the logic for receiving a Base Message in an "unsafe way". Following checks HAVE been performed:

• receiveBaseMessage() was called by Destination (i.e. this is a legit base message).
• Nonce is not zero.
• Message sender on origin chain is not a zero address.
• Proof maturity is not zero. Following checks HAVE NOT been performed (thus "unsafe"):
• Message sender on origin chain could be anything non-zero at this point.
• Proof maturity could be anything non-zero at this point.*

function _receiveBaseMessageUnsafe(
    uint32 origin_,
    uint32 nonce,
    bytes32 sender,
    uint256 proofMaturity,
    uint32 version,
    bytes memory content
) internal override;

_receiveBaseMessage

*Child contracts should implement the logic for receiving a Base Message. Following checks HAVE been performed:

• receiveBaseMessage() was called by Destination (i.e. this is a legit base message).
• Nonce is not zero.
• Message sender on origin chain is a trusted sender (and is not zero).
• Optimistic period for the message have passed (and is not zero).*

function _receiveBaseMessage(uint32 origin_, uint32 nonce, uint32 version, bytes memory content) internal virtual;

_sendBaseMessage

*Sends a message to given destination chain. Full msg.value is used to pay for the message tips. _getMinimumTipsValue() could be used to calculate the minimum required tips value, and should be also exposed as a public view function to estimate the tips value before sending a message off-chain. This function is not exposed in BaseClient, as the message encoding is implemented by the child contract.

Will revert if the trusted sender is not set for the destination domain.*

function _sendBaseMessage(uint32 destination_, uint256 tipsValue, MessageRequest memory request, bytes memory content)
    internal
    returns (uint32 messageNonce, bytes32 messageHash);

Parameters

MessageRecipient

Git Source

Inherits: IMessageRecipient

State Variables

origin

Local chain Origin: used for sending messages

address public immutable origin;

destination

Local chain Destination: used for receiving messages

address public immutable destination;

Functions

constructor

constructor(address origin_, address destination_);

receiveBaseMessage

Message recipient needs to implement this function in order to receive cross-chain messages.

Message recipient needs to ensure that merkle proof for the message is at least as old as the optimistic period that the recipient is using. Note: as this point it is checked that the "message optimistic period" has passed, however the period value itself could be anything, and thus could differ from the one that the recipient would like to enforce.

function receiveBaseMessage(
    uint32 origin_,
    uint32 nonce,
    bytes32 sender,
    uint256 proofMaturity,
    uint32 version,
    bytes memory content
) external payable;

Parameters

_receiveBaseMessageUnsafe

*Child contracts should implement the logic for receiving a Base Message in an "unsafe way". Following checks HAVE been performed:

• receiveBaseMessage() was called by Destination (i.e. this is a legit base message).
• Nonce is not zero.
• Message sender on origin chain is not a zero address.
• Proof maturity is not zero. Following checks HAVE NOT been performed (thus "unsafe"):
• Message sender on origin chain could be anything non-zero at this point.
• Proof maturity could be anything non-zero at this point.*

function _receiveBaseMessageUnsafe(
    uint32 origin_,
    uint32 nonce,
    bytes32 sender,
    uint256 proofMaturity,
    uint32 version,
    bytes memory content
) internal virtual;

_sendBaseMessage

Sends a message to given destination chain. Full msg.value is used to pay for the message tips. _getMinimumTipsValue() could be used to calculate the minimum required tips value, and should be also exposed as a public view function to estimate the tips value before sending a message off-chain. This function is not exposed in MessageRecipient, as the message encoding is implemented by the child contract.

function _sendBaseMessage(
    uint32 destination_,
    bytes32 recipient,
    uint32 optimisticPeriod,
    uint256 tipsValue,
    MessageRequest memory request,
    bytes memory content
) internal returns (uint32 messageNonce, bytes32 messageHash);

Parameters

_getMinimumTipsValue

Returns the minimum tips value for sending a message to given destination chain.

function _getMinimumTipsValue(uint32 destination_, MessageRequest memory request, uint256 contentLength)
    internal
    view
    returns (uint256 tipsValue);

Parameters

_encodeRequest

Encodes a message execution request into format that Origin contract is using.

function _encodeRequest(MessageRequest memory request) internal pure returns (uint256 paddedRequest);

Parameters

Returns

Structs

MessageRequest

struct MessageRequest {
    uint96 gasDrop;
    uint64 gasLimit;
    uint32 version;
}

PingPongClient

Git Source

Inherits: MessageRecipient

State Variables

random

uint256 public random;

pingsSent

Amount of "Ping" messages sent.

uint256 public pingsSent;

pingsReceived

Amount of "Ping" messages received. Every received Ping message leads to sending a Pong message back to initial sender.

uint256 public pingsReceived;

pongsReceived

Amount of "Pong" messages received. When all messages are delivered, should be equal to pingsSent

uint256 public pongsReceived;

Functions

constructor

constructor(address origin_, address destination_) MessageRecipient(origin_, destination_);

doPings

function doPings(uint16 pingCount, uint32 destination_, address recipient, uint16 counter) external;

doPing

Send a Ping message to destination chain. Upon receiving a Ping, a Pong message will be sent back. If counter > 0, this process will be repeated when the Pong message is received.

function doPing(uint32 destination_, address recipient, uint16 counter) external;

Parameters

nextOptimisticPeriod

function nextOptimisticPeriod() public view returns (uint32 period);

_receiveBaseMessageUnsafe

*Child contracts should implement the logic for receiving a Base Message in an "unsafe way". Following checks HAVE been performed:

• receiveBaseMessage() was called by Destination (i.e. this is a legit base message).
• Nonce is not zero.
• Message sender on origin chain is not a zero address.
• Proof maturity is not zero. Following checks HAVE NOT been performed (thus "unsafe"):
• Message sender on origin chain could be anything non-zero at this point.
• Proof maturity could be anything non-zero at this point.*

function _receiveBaseMessageUnsafe(uint32 origin_, uint32, bytes32 sender, uint256, uint32, bytes memory content)
    internal
    override;

_optimisticPeriod

Returns a random optimistic period value from 0 to 59 seconds.

function _optimisticPeriod() internal returns (uint32 period);

_sendMessage

Send a "Ping" or "Pong" message.

function _sendMessage(uint32 destination_, bytes32 recipient, PingPongMessage memory message) internal;

Parameters

_ping

Initiate a new Ping-Pong round.

function _ping(uint32 destination_, bytes32 recipient, uint16 counter) internal;

_pong

Send a Pong message back.

function _pong(uint32 destination_, bytes32 recipient, PingPongMessage memory message) internal;

Events

PingSent

Emitted when a Ping message is sent. Triggered externally, or by receveing a Pong message with instructions to do more pings.

event PingSent(uint256 pingId);

PingReceived

Emitted when a Ping message is received. Will always send a Pong message back.

event PingReceived(uint256 pingId);

PongSent

Emitted when a Pong message is sent. Triggered whenever a Ping message is received.

event PongSent(uint256 pingId);

PongReceived

Emitted when a Pong message is received. Will initiate a new Ping, if the counter in the message is non-zero.

event PongReceived(uint256 pingId);

Structs

PingPongMessage

struct PingPongMessage {
    uint256 pingId;
    bool isPing;
    uint16 counter;
}

TestClient

Git Source

Inherits: MessageRecipient

Functions

constructor

constructor(address origin_, address destination_) MessageRecipient(origin_, destination_);

sendMessage

function sendMessage(
    uint32 destination_,
    address recipientAddress,
    uint32 optimisticPeriod,
    uint64 gasLimit,
    uint32 version,
    bytes memory content
) external payable;

_receiveBaseMessageUnsafe

*Child contracts should implement the logic for receiving a Base Message in an "unsafe way". Following checks HAVE been performed:

• receiveBaseMessage() was called by Destination (i.e. this is a legit base message).
• Nonce is not zero.
• Message sender on origin chain is not a zero address.
• Proof maturity is not zero. Following checks HAVE NOT been performed (thus "unsafe"):
• Message sender on origin chain could be anything non-zero at this point.
• Proof maturity could be anything non-zero at this point.*

function _receiveBaseMessageUnsafe(
    uint32 origin_,
    uint32 nonce,
    bytes32 sender,
    uint256 proofMaturity,
    uint32 version,
    bytes memory content
) internal override;

Events

MessageReceived

event MessageReceived(
    uint32 origin, uint32 nonce, bytes32 sender, uint256 proofMaturity, uint32 version, bytes content
);

MessageSent

event MessageSent(uint32 destination, uint32 nonce, bytes32 sender, bytes32 recipient, bytes content);

Contents

• AgentManagerEvents
• DestinationEvents
• ExecutionHubEvents
• GasOracleEvents
• InboxEvents
• OriginEvents
• SnapshotHubEvents
• StateHubEvents
• StatementInboxEvents
• SummitEvents

AgentManagerEvents

Git Source

Events

DisputeOpened

Emitted whenever a Dispute is opened between two agents. This happens when a Guard submits their report for the Notary-signed statement to StatementInbox.

event DisputeOpened(uint256 disputeIndex, uint32 guardIndex, uint32 notaryIndex);

DisputeResolved

Emitted whenever a Dispute is resolved. This happens when an Agent who was in Dispute is slashed. Note: this won't be emitted, if an Agent was slashed without being in Dispute.

event DisputeResolved(uint256 disputeIndex, uint32 slashedIndex, uint32 rivalIndex, address fraudProver);

RootUpdated

Emitted whenever the root of the Agent Merkle Tree is updated.

event RootUpdated(bytes32 newRoot);

AgentRootProposed

Emitted after the contract owner proposes a new agent root to resolve the stuck chain.

event AgentRootProposed(bytes32 newRoot);

ProposedAgentRootCancelled

Emitted after the contract owner cancels the previously proposed agent root.

event ProposedAgentRootCancelled(bytes32 proposedRoot);

ProposedAgentRootResolved

Emitted after the contract owner resolves the previously proposed agent root.

event ProposedAgentRootResolved(bytes32 proposedRoot);

StatusUpdated

Emitted whenever a status of the agent is updated.

Only Active/Unstaking/Resting/Slashed flags could be stored in the Agent Merkle Tree. Unknown flag is the default (zero) value and is used to represent agents that never interacted with the BondingManager contract. Fraudulent flag is the value for the agent who has been proven to commit fraud, but their status hasn't been updated to Slashed in the Agent Merkle Tree. This is due to the fact that the update of the status requires a merkle proof of the old status, and happens in a separate transaction because of that.

event StatusUpdated(AgentFlag flag, uint32 indexed domain, address indexed agent);

DestinationEvents

Git Source

A collection of events emitted by the Destination contract

Events

AgentRootAccepted

event AgentRootAccepted(bytes32 agentRoot);

ExecutionHubEvents

Git Source

A collection of events emitted by the ExecutionHub contract

Events

Executed

Emitted when message is executed.

event Executed(uint32 indexed remoteDomain, bytes32 indexed messageHash, bool success);

TipsRecorded

Emitted when message tips are recorded.

event TipsRecorded(bytes32 messageHash, uint256 paddedTips);

GasOracleEvents

Git Source

A collection of events emitted by the GasOracle contract

Events

GasDataUpdated

Emitted when gas data is updated for the domain

event GasDataUpdated(uint32 domain, uint256 paddedGasData);

SummitTipUpdated

Emitted when the value of the summit tip is updated

event SummitTipUpdated(uint256 summitTipWei);

InboxEvents

Git Source

Events

SnapshotAccepted

Emitted when a snapshot is accepted by the Summit contract.

event SnapshotAccepted(uint32 indexed domain, address indexed agent, bytes snapPayload, bytes snapSignature);

ReceiptAccepted

Emitted when a snapshot is accepted by the Summit contract.

event ReceiptAccepted(uint32 domain, address notary, bytes rcptPayload, bytes rcptSignature);

InvalidAttestation

Emitted when a proof of invalid attestation is submitted.

event InvalidAttestation(bytes attPayload, bytes attSignature);

InvalidAttestationReport

Emitted when a proof of invalid attestation report is submitted.

event InvalidAttestationReport(bytes arPayload, bytes arSignature);

OriginEvents

Git Source

A collection of events emitted by the Origin contract

Events

Sent

Emitted when a new message is sent.

event Sent(bytes32 indexed messageHash, uint32 indexed nonce, uint32 indexed destination, bytes message);

TipWithdrawalCompleted

Emitted when a tip withdrawal is completed.

event TipWithdrawalCompleted(address actor, uint256 tip);

SnapshotHubEvents

Git Source

A collection of events emitted by the SnapshotHub contract

Events

AttestationSaved

Emitted when a new Attestation is saved (derived from a Notary snapshot).

event AttestationSaved(bytes attestation);

StateSaved

Emitted when a new Origin State is saved from a Guard snapshot.

event StateSaved(bytes state);

StateHubEvents

Git Source

A collection of events emitted by the StateHub contract

Events

StateSaved

Emitted when a new Origin State is saved after a message was sent.

event StateSaved(bytes state);

StatementInboxEvents

Git Source

Events

AttestationAccepted

Emitted when a snapshot is accepted by the Destination contract.

event AttestationAccepted(uint32 domain, address notary, bytes attPayload, bytes attSignature);

InvalidReceipt

Emitted when a proof of invalid receipt statement is submitted.

event InvalidReceipt(bytes rcptPayload, bytes rcptSignature);

InvalidReceiptReport

Emitted when a proof of invalid receipt report is submitted.

event InvalidReceiptReport(bytes rrPayload, bytes rrSignature);

InvalidStateWithAttestation

Emitted when a proof of invalid state in the signed attestation is submitted.

event InvalidStateWithAttestation(uint8 stateIndex, bytes statePayload, bytes attPayload, bytes attSignature);

InvalidStateWithSnapshot

Emitted when a proof of invalid state in the signed snapshot is submitted.

event InvalidStateWithSnapshot(uint8 stateIndex, bytes snapPayload, bytes snapSignature);

InvalidStateReport

Emitted when a proof of invalid state report is submitted.

event InvalidStateReport(bytes srPayload, bytes srSignature);

SummitEvents

Git Source

A collection of events emitted by the Summit contract

Events

TipAwarded

Emitted when a tip is awarded to the actor, whether they are bonded or unbonded actor.

event TipAwarded(address actor, uint32 origin, uint256 tip);

TipWithdrawalInitiated

Emitted when a tip withdrawal is initiated by the actor.

event TipWithdrawalInitiated(address actor, uint32 origin, uint256 tip);

Contents

• ExecutionHub
• SnapshotHub
• StateHub

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;
}

SnapshotHub

Git Source

Inherits: AgentSecured, SnapshotHubEvents, ISnapshotHub

SnapshotHub is a parent contract for Summit. It is responsible for the following:

• Accepting and storing Guard and Notary snapshots to keep track of all the remote Origin states.
• Generating and storing Attestations derived from Notary snapshots, as well as verifying their validity.

State Variables

_states

All States submitted by any of the Guards

SummitState[] private _states;

_guardSnapshots

All Snapshots submitted by any of the Guards

SummitSnapshot[] private _guardSnapshots;

_notarySnapshots

All Snapshots submitted by any of the Notaries

SummitSnapshot[] private _notarySnapshots;

_attestations

All Attestations created from Notary-submitted Snapshots Invariant: _attestations.length == _notarySnapshots.length

SummitAttestation[] private _attestations;

_leafPtr

Pointer for the given State Leaf of the origin with ZERO as a sentinel value for "state not submitted yet".

mapping(uint32 => mapping(bytes32 => uint256)) private _leafPtr;

_latestStatePtr

Pointer for the latest Agent State of a given origin with ZERO as a sentinel value for "no states submitted yet".

mapping(uint32 => mapping(uint32 => uint256)) private _latestStatePtr;

_latestAttNonce

Latest nonce that a Notary created

mapping(uint32 => uint32) private _latestAttNonce;

__GAP

gap for upgrade safety

uint256[43] private __GAP;

Functions

isValidAttestation

Check that a given attestation is valid: matches the historical attestation derived from an accepted Notary snapshot.

*Will revert if any of these is true:

• Attestation payload is not properly formatted.*

function isValidAttestation(bytes memory attPayload) external view returns (bool isValid);

Parameters

Returns

getAttestation

Returns saved attestation with the given nonce.

Reverts if attestation with given nonce hasn't been created yet.

function getAttestation(uint32 attNonce)
    external
    view
    returns (bytes memory attPayload, bytes32 agentRoot, uint256[] memory snapGas);

Parameters

Returns

getLatestAgentState

Returns the state with the highest known nonce submitted by a given Agent.

function getLatestAgentState(uint32 origin, address agent) external view returns (bytes memory stateData);

Parameters

Returns

getLatestNotaryAttestation

Returns latest saved attestation for a Notary.

function getLatestNotaryAttestation(address notary)
    external
    view
    returns (bytes memory attPayload, bytes32 agentRoot, uint256[] memory snapGas);

Parameters

Returns

getGuardSnapshot

Returns Guard snapshot from the list of all accepted Guard snapshots.

Reverts if snapshot with given index hasn't been accepted yet.

function getGuardSnapshot(uint256 index) external view returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Returns

getNotarySnapshot

Returns Notary snapshot from the list of all accepted Guard snapshots.

Reverts if snapshot with given index hasn't been accepted yet.

function getNotarySnapshot(uint256 index) public view returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Returns

getNotarySnapshot

Returns Notary snapshot from the list of all accepted Guard snapshots.

Reverts if snapshot with given index hasn't been accepted yet.

function getNotarySnapshot(bytes memory attPayload)
    external
    view
    returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Returns

getSnapshotProof

Returns proof of inclusion of (root, origin) fields of a given snapshot's state into the Snapshot Merkle Tree for a given attestation.

*Reverts if any of these is true:

• Attestation with given nonce hasn't been created yet.
• State index is out of range of snapshot list.*

function getSnapshotProof(uint32 attNonce, uint8 stateIndex) external view returns (bytes32[] memory snapProof);

Parameters

Returns

_acceptGuardSnapshot

Accepts a Snapshot signed by a Guard. It is assumed that the Guard signature has been checked outside of this contract.

function _acceptGuardSnapshot(Snapshot snapshot, uint32 guardIndex, uint256 sigIndex) internal;

_acceptNotarySnapshot

Accepts a Snapshot signed by a Notary. It is assumed that the Notary signature has been checked outside of this contract. Returns the attestation created from the Notary snapshot.

function _acceptNotarySnapshot(Snapshot snapshot, bytes32 agentRoot, uint32 notaryIndex, uint256 sigIndex)
    internal
    returns (bytes memory attPayload);

_initializeAttestations

Initializes the saved _attestations list by inserting empty values.

function _initializeAttestations() internal;

_saveGuardSnapshot

Saves the Guard snapshot.

function _saveGuardSnapshot(uint256[] memory statePtrs, uint256 sigIndex) internal;

_saveNotarySnapshot

Saves the Notary snapshot and the attestation created from it. Returns the created attestation.

function _saveNotarySnapshot(
    Snapshot snapshot,
    uint256[] memory statePtrs,
    bytes32 agentRoot,
    uint32 notaryIndex,
    uint256 sigIndex
) internal returns (bytes memory attPayload);

_saveState

Add a single element to both _attestations and _notarySnapshots, enforcing the (_attestations.length == _notarySnapshots.length) invariant.

Saves the state signed by a Guard.

function _saveState(State state, uint32 guardIndex) internal returns (uint256 statePtr);

_isValidAttestation

Checks if attestation was previously submitted by a Notary (as a signed snapshot).

function _isValidAttestation(Attestation att) internal view returns (bool);

_restoreSnapshot

Restores Snapshot payload from a list of state pointers used for the snapshot.

function _restoreSnapshot(SummitSnapshot memory snapshot)
    internal
    view
    returns (bytes memory snapPayload, bytes memory snapSignature);

_restoreSnapGas

Restores the gas data from the snapshot.

function _restoreSnapGas(SummitSnapshot memory snapshot) internal view returns (uint256[] memory snapGas);

_stateAgents

Returns indexes of agents who provided state data for the Notary snapshot with the given nonce.

function _stateAgents(uint32 nonce, uint8 stateIndex) internal view returns (uint32 guardIndex, uint32 notaryIndex);

_statePtr

Returns the pointer for a matching Guard State, if it exists.

function _statePtr(State state) internal view returns (uint256);

_latestState

Returns the latest state submitted by the Agent for the origin. Will return an empty struct, if the Agent hasn't submitted a single origin State yet.

function _latestState(uint32 origin, uint32 agentIndex) internal view returns (SummitState memory state);

_formatSummitState

Returns a formatted payload for a stored SummitState.

function _formatSummitState(SummitState memory summitState) internal pure returns (bytes memory);

_toSummitState

Returns a SummitState struct to save in the contract.

function _toSummitState(State state, uint32 guardIndex) internal pure returns (SummitState memory summitState);

_formatSummitAttestation

Returns a formatted payload for a stored SummitAttestation.

function _formatSummitAttestation(SummitAttestation memory summitAtt, uint32 nonce)
    internal
    pure
    returns (bytes memory);

_toSummitAttestation

Returns an Attestation struct to save in the Summit contract. Current block number and timestamp are used.

function _toSummitAttestation(bytes32 snapRoot, bytes32 agentRoot, bytes32 snapGasHash)
    internal
    view
    returns (SummitAttestation memory summitAtt);

_areEqual

Checks that an Attestation and its Summit representation are equal.

function _areEqual(Attestation att, SummitAttestation memory summitAtt) internal pure returns (bool);

Structs

SummitState

Struct that represents stored State of Origin contract

struct SummitState {
    bytes32 root;
    uint32 origin;
    uint32 nonce;
    uint40 blockNumber;
    uint40 timestamp;
    GasData gasData;
    uint32 guardIndex;
    uint32 notaryIndex;
}

SummitSnapshot

struct SummitSnapshot {
    uint256[] statePtrs;
    uint256 sigIndex;
}

SummitAttestation

struct SummitAttestation {
    bytes32 snapRoot;
    bytes32 agentRoot;
    bytes32 snapGasHash;
    uint40 blockNumber;
    uint40 timestamp;
}

StateHub

Git Source

Inherits: AgentSecured, StateHubEvents, IStateHub

StateHub is a parent contract for Origin. It is responsible for the following:

• Keeping track of the historical Origin Merkle Tree containing all the message hashes.
• Keeping track of the historical Origin States, as well as verifying their validity.

State Variables

_tree

Historical Merkle Tree Note: Takes two storage slots

HistoricalTree private _tree;

_originStates

All historical contract States

OriginState[] private _originStates;

__GAP

gap for upgrade safety

uint256[47] private __GAP;

Functions

isValidState

Check that a given state is valid: matches the historical state of Origin contract. Note: any Agent including an invalid state in their snapshot will be slashed upon providing the snapshot and agent signature for it to Origin contract.

*Will revert if any of these is true:

• State payload is not properly formatted.*

function isValidState(bytes memory statePayload) external view returns (bool isValid);

Parameters

Returns

statesAmount

Returns the amount of saved states so far.

This includes the initial state of "empty Origin Merkle Tree".

function statesAmount() external view returns (uint256);

suggestLatestState

Suggest the data (state after latest sent message) to sign for an Agent. Note: signing the suggested state data will will never lead to slashing of the actor, assuming they have confirmed that the block, which number is included in the data, is not subject to reorganization (which is different for every observed chain).

function suggestLatestState() external view returns (bytes memory stateData);

Returns

suggestState

Given the historical nonce, suggest the state data to sign for an Agent. Note: signing the suggested state data will will never lead to slashing of the actor, assuming they have confirmed that the block, which number is included in the data, is not subject to reorganization (which is different for every observed chain).

function suggestState(uint32 nonce) public view returns (bytes memory stateData);

Parameters

Returns

_initializeStates

Initializes the saved states list by inserting a state for an empty Merkle Tree.

function _initializeStates() internal;

_insertAndSave

Inserts leaf into the Merkle Tree and saves the updated origin State.

function _insertAndSave(bytes32 leaf) internal;

_saveState

Saves an updated state of the Origin contract

function _saveState(bytes32 root, OriginState memory state) internal;

_nextNonce

Returns nonce of the next sent message: the amount of saved States so far. This always equals to "total amount of sent messages" plus 1.

function _nextNonce() internal view returns (uint32);

_isValidState

Checks if a state is valid, i.e. if it matches the historical one. Reverts, if state refers to another Origin contract.

function _isValidState(State state) internal view returns (bool);

_formatOriginState

Returns a formatted payload for a stored OriginState.

function _formatOriginState(OriginState memory originState, bytes32 root, uint32 origin, uint32 nonce)
    internal
    pure
    returns (bytes memory);

_fetchGasData

Child contract should implement the logic for getting the current gas data from the gas oracle to be saved as part of the Origin State.

function _fetchGasData() internal view virtual returns (GasData);

_toOriginState

Returns a OriginState struct to save in the contract.

function _toOriginState() internal view returns (OriginState memory originState);

_areEqual

Checks that a state and its Origin representation are equal.

function _areEqual(State state, OriginState memory originState) internal pure returns (bool);

Structs

OriginState

struct OriginState {
    uint40 blockNumber;
    uint40 timestamp;
    GasData gasData;
}

Contents

• Inbox
• LightInbox
• StatementInbox

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;
}

LightInbox

Git Source

Inherits: StatementInbox, InterfaceLightInbox

LightInbox is the child of StatementInbox contract, that is used chains other than the Synapse Chain. In addition to the functionality of StatementInbox, it also:

• Accepts Notary Attestations and passes them to the Destination contract.
• Accepts Attestation Reports and initiates a dispute between the Notary and the Guard.

Functions

constructor

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

initialize

Initializes LightInbox contract:

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

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

submitAttestation

Accepts an attestation signed by a Notary and passes it to Destination contract to save.

Attestation is created whenever a Notary-signed snapshot is saved in Summit on Synapse Chain.

• Saved Attestation could be later used to prove the inclusion of message in the Origin Merkle Tree.
• Messages coming from chains included in the Attestation's snapshot could be proven.
• Proof only exists for messages that were sent prior to when the Attestation's snapshot was taken.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary for local domain.
• Attestation signer is in Dispute.
• Attestation's snapshot root has been previously submitted.
• Attestation's data hash doesn't match the hash of provided agentRoot and snapshot gas data.

function submitAttestation(
    bytes memory attPayload,
    bytes memory attSignature,
    bytes32 agentRoot_,
    uint256[] memory snapGas_
) external returns (bool wasAccepted);

Parameters

Returns

submitAttestationReport

Accepts a Guard's attestation report signature, as well as Notary signature for the reported Attestation.

AttestationReport is a Guard statement saying "Reported attestation is invalid".

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

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation Report signer is not an active Guard.
• Attestation signer is not an active Notary for local domain.

function submitAttestationReport(bytes memory attPayload, bytes memory arSignature, bytes memory attSignature)
    external
    returns (bool wasAccepted);

Parameters

Returns

StatementInbox

Git Source

Inherits: MessagingBase, StatementInboxEvents, IStatementInbox

StatementInbox is the entry point for all agent-signed statements. It verifies the agent signatures, and passes the unsigned statements to the contract to consume it via acceptX functions. Is is also used to verify the agent-signed statements and initiate the agent slashing, should the statement be invalid. StatementInbox is responsible for the following:

• Accepting State and Receipt Reports to initiate a dispute between Guard and Notary.
• Storing all the Guard Reports with the Guard signature leading to a dispute.
• Verifying State/State Reports referencing the local chain and slashing the signer if statement is invalid.
• Verifying Receipt/Receipt Reports referencing the local chain and slashing the signer if statement is invalid.

State Variables

agentManager

address public agentManager;

origin

address public origin;

destination

address public destination;

_storedSignatures

bytes[] internal _storedSignatures;

_storedReports

StoredReport[] internal _storedReports;

__GAP

gap for upgrade safety

uint256[45] private __GAP;

Functions

__StatementInbox_init

*Initializes the contract:

• Sets up msg.sender as the owner of the contract.
• Sets up agentManager, origin, and destination.*

function __StatementInbox_init(address agentManager_, address origin_, address destination_)
    internal
    onlyInitializing;

submitStateReportWithSnapshot

Accepts a Guard's state report signature, a Snapshot containing the reported State, as well as Notary signature for the Snapshot.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithSnapshot() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State Report signer is not an active Guard.
• Snapshot payload is not properly formatted.
• Snapshot signer is not an active Notary.
• State index is out of range.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithSnapshot(
    uint8 stateIndex,
    bytes memory srSignature,
    bytes memory snapPayload,
    bytes memory snapSignature
) external returns (bool wasAccepted);

Parameters

Returns

submitStateReportWithAttestation

Accepts a Guard's state report signature, a Snapshot containing the reported State, as well as Notary signature for the Attestation created from this Snapshot.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithAttestation() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State Report signer is not an active Guard.
• Snapshot payload is not properly formatted.
• State index is out of range.
• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from the Snapshot.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithAttestation(
    uint8 stateIndex,
    bytes memory srSignature,
    bytes memory snapPayload,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool wasAccepted);

Parameters

Returns

submitStateReportWithSnapshotProof

Accepts a Guard's state report signature, a proof of inclusion of the reported State in an Attestation, as well as Notary signature for the Attestation.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithSnapshotProof() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State payload is not properly formatted.
• State Report signer is not an active Guard.
• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from State and Snapshot Proof.
• Snapshot Proof's first element does not match the State metadata.
• Snapshot Proof length exceeds Snapshot Tree Height.
• State index is out of range.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithSnapshotProof(
    uint8 stateIndex,
    bytes memory statePayload,
    bytes memory srSignature,
    bytes32[] memory snapProof,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool wasAccepted);

Parameters

Returns

verifyReceipt

Verifies a message receipt signed by the Notary.

• Does nothing, if the receipt is valid (matches the saved receipt data for the referenced message).
• Slashes the Notary, if the receipt is invalid.

Will revert if any of these is true:

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

function verifyReceipt(bytes memory rcptPayload, bytes memory rcptSignature) external returns (bool isValidReceipt);

Parameters

Returns

verifyReceiptReport

Verifies a Guard's receipt report signature.

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

Will revert if any of these is true:

• Receipt payload is not properly formatted.
• Receipt Report signer is not an active Guard.
• Receipt does not refer to this chain.

function verifyReceiptReport(bytes memory rcptPayload, bytes memory rrSignature)
    external
    returns (bool isValidReport);

Parameters

Returns

verifyStateWithAttestation

Verifies a state from the snapshot, that was used for the Notary-signed attestation.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Notary, if the state is invalid.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from the Snapshot.
• Snapshot payload is not properly formatted.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithAttestation(
    uint8 stateIndex,
    bytes memory snapPayload,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool isValidState);

Parameters

Returns

verifyStateWithSnapshotProof

Verifies a state from the snapshot, that was used for the Notary-signed attestation.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Notary, if the state is invalid.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from State and Snapshot Proof.
• Snapshot Proof's first element does not match the State metadata.
• Snapshot Proof length exceeds Snapshot Tree Height.
• State payload is not properly formatted.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithSnapshotProof(
    uint8 stateIndex,
    bytes memory statePayload,
    bytes32[] memory snapProof,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool isValidState);

Parameters

Returns

verifyStateWithSnapshot

Verifies a state from the snapshot (a list of states) signed by a Guard or a Notary.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Agent, if the state is invalid.

Will revert if any of these is true:

• Snapshot payload is not properly formatted.
• Snapshot signer is not an active Agent.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithSnapshot(uint8 stateIndex, bytes memory snapPayload, bytes memory snapSignature)
    external
    returns (bool isValidState);

Parameters

Returns

verifyStateReport

Verifies a Guard's state report signature.

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

Will revert if any of these is true:

• State payload is not properly formatted.
• State Report signer is not an active Guard.
• Reported State does not refer to this chain.

function verifyStateReport(bytes memory statePayload, bytes memory srSignature) external returns (bool isValidReport);

Parameters

Returns

getReportsAmount

Returns the amount of Guard Reports stored in StatementInbox.

Only reports that led to opening a Dispute are stored.

function getReportsAmount() external view returns (uint256);

getGuardReport

Returns the Guard report with the given index stored in StatementInbox.

Only reports that led to opening a Dispute are stored.

Will revert if report with given index doesn't exist.

function getGuardReport(uint256 index)
    external
    view
    returns (bytes memory statementPayload, bytes memory reportSignature);

Parameters

Returns

getStoredSignature

Returns the signature with the given index stored in StatementInbox.

Will revert if signature with given index doesn't exist.

function getStoredSignature(uint256 index) external view returns (bytes memory);

Parameters

Returns

_saveReport

Saves the statement reported by Guard as invalid and the Guard Report signature.

function _saveReport(bytes memory statementPayload, bytes memory reportSignature) internal;

_saveSignature

Saves the signature and returns its index.

function _saveSignature(bytes memory signature) internal returns (uint256 sigIndex);

_recoverAgent

Recovers a signer from a hashed message, and a EIP-191 signature for it. Will revert, if the signer is not a known agent.

Agent flag could be any of these: Active/Unstaking/Resting/Fraudulent/Slashed Further checks need to be performed in a caller function.

function _recoverAgent(bytes32 hashedStatement, bytes memory signature)
    internal
    view
    returns (AgentStatus memory status, address agent);

Parameters

Returns

_verifyNotaryDomain

Verifies that Notary signature is active on local domain.

function _verifyNotaryDomain(uint32 notaryDomain) internal view;

_verifyAttestation

*Internal function to verify the signed attestation payload. Reverts if any of these is true:

• Attestation signer is not a known Notary.*

function _verifyAttestation(Attestation att, bytes memory attSignature)
    internal
    view
    returns (AgentStatus memory status, address notary);

Parameters

Returns

_verifyAttestationReport

*Internal function to verify the signed attestation report payload. Reverts if any of these is true:

• Report signer is not a known Guard.*

function _verifyAttestationReport(Attestation att, bytes memory arSignature)
    internal
    view
    returns (AgentStatus memory status, address guard);

Parameters

Returns

_verifyReceipt

*Internal function to verify the signed receipt payload. Reverts if any of these is true:

• Receipt signer is not a known Notary.*

function _verifyReceipt(Receipt rcpt, bytes memory rcptSignature)
    internal
    view
    returns (AgentStatus memory status, address notary);

Parameters

Returns

_verifyReceiptReport

*Internal function to verify the signed receipt report payload. Reverts if any of these is true:

• Report signer is not a known Guard.*

function _verifyReceiptReport(Receipt rcpt, bytes memory rrSignature)
    internal
    view
    returns (AgentStatus memory status, address guard);

Parameters

Returns

_verifyStateReport

*Internal function to verify the signed snapshot report payload. Reverts if any of these is true:

• Report signer is not a known Guard.*

function _verifyStateReport(State state, bytes memory srSignature)
    internal
    view
    returns (AgentStatus memory status, address guard);

Parameters

Returns

_verifySnapshot

*Internal function to verify the signed snapshot payload. Reverts if any of these is true:

• Snapshot signer is not a known Agent.
• Snapshot signer is not a Notary (if verifyNotary is true).*

function _verifySnapshot(Snapshot snapshot, bytes memory snapSignature, bool verifyNotary)
    internal
    view
    returns (AgentStatus memory status, address agent);

Parameters

Returns

_verifySnapshotMerkle

*Internal function to verify that snapshot roots match. Reverts if any of these is true:

• Attestation root is not equal to Merkle Root derived from State and Snapshot Proof.
• Snapshot Proof's first element does not match the State metadata.
• Snapshot Proof length exceeds Snapshot tree Height.
• State index is out of range.*

function _verifySnapshotMerkle(Attestation att, uint8 stateIndex, State state, bytes32[] memory snapProof)
    internal
    pure;

Parameters

Structs

StoredReport

struct StoredReport {
    uint256 sigIndex;
    bytes statementPayload;
}

Contents

• IAgentManager
• IAgentSecured
• IExecutionHub
• IMessageRecipient
• ISnapshotHub
• IStateHub
• IStatementInbox
• InterfaceBondingManager
• InterfaceDestination
• InterfaceGasOracle
• InterfaceInbox
• InterfaceLightInbox
• InterfaceLightManager
• InterfaceOrigin
• InterfaceSummit

IAgentManager

Git Source

Functions

openDispute

Allows Inbox to open a Dispute between a Guard and a Notary, if they are both not in Dispute already.

Will revert if any of these is true:

• Caller is not Inbox.
• Guard or Notary is already in Dispute.

function openDispute(uint32 guardIndex, uint32 notaryIndex) external;

Parameters

slashAgent

Allows Inbox to slash an agent, if their fraud was proven.

Will revert if any of these is true:

• Caller is not Inbox.
• Domain doesn't match the saved agent domain.

function slashAgent(uint32 domain, address agent, address prover) external;

Parameters

agentRoot

Returns the latest known root of the Agent Merkle Tree.

function agentRoot() external view returns (bytes32);

agentStatus

Returns (flag, domain, index) for a given agent. See Structures.sol for details.

Will return AgentFlag.Fraudulent for agents that have been proven to commit fraud, but their status is not updated to Slashed yet.

function agentStatus(address agent) external view returns (AgentStatus memory);

Parameters

Returns

getAgent

Returns agent address and their current status for a given agent index.

Will return empty values if agent with given index doesn't exist.

function getAgent(uint256 index) external view returns (address agent, AgentStatus memory status);

Parameters

Returns

getDisputesAmount

Returns the number of opened Disputes.

This includes the Disputes that have been resolved already.

function getDisputesAmount() external view returns (uint256);

getDispute

Returns information about the dispute with the given index.

Will revert if dispute with given index hasn't been opened yet.

function getDispute(uint256 index)
    external
    view
    returns (
        address guard,
        address notary,
        address slashedAgent,
        address fraudProver,
        bytes memory reportPayload,
        bytes memory reportSignature
    );

Parameters

Returns

disputeStatus

Returns the current Dispute status of a given agent. See Structures.sol for details.

Every returned value will be set to zero if agent was not slashed and is not in Dispute. rival and disputePtr will be set to zero if the agent was slashed without being in Dispute.

function disputeStatus(address agent)
    external
    view
    returns (DisputeFlag flag, address rival, address fraudProver, uint256 disputePtr);

Parameters

Returns

IAgentSecured

Git Source

Functions

openDispute

Local AgentManager should call this function to indicate that a dispute between a Guard and a Notary has been opened.

function openDispute(uint32 guardIndex, uint32 notaryIndex) external;

Parameters

resolveDispute

Local AgentManager should call this function to indicate that a dispute has been resolved due to one of the agents being slashed.

rivalIndex will be ZERO, if the slashed agent was not in the Dispute.

function resolveDispute(uint32 slashedIndex, uint32 rivalIndex) external;

Parameters

agentManager

Returns the address of the local AgentManager contract, which is treated as the "source of truth" for agent statuses.

function agentManager() external view returns (address);

inbox

Returns the address of the local Inbox contract, which is treated as the "source of truth" for agent-signed statements.

Inbox passes verified agent statements to IAgentSecured contract.

function inbox() external view returns (address);

agentStatus

Returns (flag, domain, index) for a given agent. See Structures.sol for details.

Will return AgentFlag.Fraudulent for agents that have been proven to commit fraud, but their status is not updated to Slashed yet.

function agentStatus(address agent) external view returns (AgentStatus memory);

Parameters

Returns

getAgent

Returns agent address and their current status for a given agent index.

Will return empty values if agent with given index doesn't exist.

function getAgent(uint256 index) external view returns (address agent, AgentStatus memory status);

Parameters

Returns

latestDisputeStatus

Returns (flag, openedAt, resolvedAt) that describes the latest status of the latest dispute for an agent with a given index.

Will return empty values if agent with given index doesn't exist.

function latestDisputeStatus(uint32 agentIndex) external view returns (DisputeStatus memory);

Parameters

Returns

IExecutionHub

Git Source

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;

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 data);

Parameters

Returns

IMessageRecipient

Git Source

Functions

receiveBaseMessage

Message recipient needs to implement this function in order to receive cross-chain messages.

Message recipient needs to ensure that merkle proof for the message is at least as old as the optimistic period that the recipient is using. Note: as this point it is checked that the "message optimistic period" has passed, however the period value itself could be anything, and thus could differ from the one that the recipient would like to enforce.

function receiveBaseMessage(
    uint32 origin,
    uint32 nonce,
    bytes32 sender,
    uint256 proofMaturity,
    uint32 version,
    bytes memory content
) external payable;

Parameters

ISnapshotHub

Git Source

Functions

isValidAttestation

Check that a given attestation is valid: matches the historical attestation derived from an accepted Notary snapshot.

*Will revert if any of these is true:

• Attestation payload is not properly formatted.*

function isValidAttestation(bytes memory attPayload) external view returns (bool isValid);

Parameters

Returns

getAttestation

Returns saved attestation with the given nonce.

Reverts if attestation with given nonce hasn't been created yet.

function getAttestation(uint32 attNonce)
    external
    view
    returns (bytes memory attPayload, bytes32 agentRoot, uint256[] memory snapGas);

Parameters

Returns

getLatestAgentState

Returns the state with the highest known nonce submitted by a given Agent.

function getLatestAgentState(uint32 origin, address agent) external view returns (bytes memory statePayload);

Parameters

Returns

getLatestNotaryAttestation

Returns latest saved attestation for a Notary.

function getLatestNotaryAttestation(address notary)
    external
    view
    returns (bytes memory attPayload, bytes32 agentRoot, uint256[] memory snapGas);

Parameters

Returns

getGuardSnapshot

Returns Guard snapshot from the list of all accepted Guard snapshots.

Reverts if snapshot with given index hasn't been accepted yet.

function getGuardSnapshot(uint256 index) external view returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Returns

getNotarySnapshot

Returns Notary snapshot from the list of all accepted Guard snapshots.

Reverts if snapshot with given index hasn't been accepted yet.

function getNotarySnapshot(uint256 index)
    external
    view
    returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Returns

getNotarySnapshot

Returns Notary snapshot that was used for creating a given attestation.

*Reverts if any of these is true:

• Attestation payload is not properly formatted.
• Attestation is invalid (doesn't have a matching Notary snapshot).*

function getNotarySnapshot(bytes memory attPayload)
    external
    view
    returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Returns

getSnapshotProof

Returns proof of inclusion of (root, origin) fields of a given snapshot's state into the Snapshot Merkle Tree for a given attestation.

*Reverts if any of these is true:

• Attestation with given nonce hasn't been created yet.
• State index is out of range of snapshot list.*

function getSnapshotProof(uint32 attNonce, uint8 stateIndex) external view returns (bytes32[] memory snapProof);

Parameters

Returns

IStateHub

Git Source

Functions

isValidState

Check that a given state is valid: matches the historical state of Origin contract. Note: any Agent including an invalid state in their snapshot will be slashed upon providing the snapshot and agent signature for it to Origin contract.

*Will revert if any of these is true:

• State payload is not properly formatted.*

function isValidState(bytes memory statePayload) external view returns (bool isValid);

Parameters

Returns

statesAmount

Returns the amount of saved states so far.

This includes the initial state of "empty Origin Merkle Tree".

function statesAmount() external view returns (uint256);

suggestLatestState

Suggest the data (state after latest sent message) to sign for an Agent. Note: signing the suggested state data will will never lead to slashing of the actor, assuming they have confirmed that the block, which number is included in the data, is not subject to reorganization (which is different for every observed chain).

function suggestLatestState() external view returns (bytes memory statePayload);

Returns

suggestState

Given the historical nonce, suggest the state data to sign for an Agent. Note: signing the suggested state data will will never lead to slashing of the actor, assuming they have confirmed that the block, which number is included in the data, is not subject to reorganization (which is different for every observed chain).

function suggestState(uint32 nonce) external view returns (bytes memory statePayload);

Parameters

Returns

IStatementInbox

Git Source

Functions

submitStateReportWithSnapshot

Accepts a Guard's state report signature, a Snapshot containing the reported State, as well as Notary signature for the Snapshot.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithSnapshot() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State Report signer is not an active Guard.
• Snapshot payload is not properly formatted.
• Snapshot signer is not an active Notary.
• State index is out of range.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithSnapshot(
    uint8 stateIndex,
    bytes memory srSignature,
    bytes memory snapPayload,
    bytes memory snapSignature
) external returns (bool wasAccepted);

Parameters

Returns

submitStateReportWithAttestation

Accepts a Guard's state report signature, a Snapshot containing the reported State, as well as Notary signature for the Attestation created from this Snapshot.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithAttestation() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State Report signer is not an active Guard.
• Snapshot payload is not properly formatted.
• State index is out of range.
• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from the Snapshot.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithAttestation(
    uint8 stateIndex,
    bytes memory srSignature,
    bytes memory snapPayload,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool wasAccepted);

Parameters

Returns

submitStateReportWithSnapshotProof

Accepts a Guard's state report signature, a proof of inclusion of the reported State in an Attestation, as well as Notary signature for the Attestation.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithSnapshotProof() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State payload is not properly formatted.
• State Report signer is not an active Guard.
• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from State and Snapshot Proof.
• Snapshot Proof's first element does not match the State metadata.
• Snapshot Proof length exceeds Snapshot Tree Height.
• State index is out of range.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithSnapshotProof(
    uint8 stateIndex,
    bytes memory statePayload,
    bytes memory srSignature,
    bytes32[] memory snapProof,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool wasAccepted);

Parameters

Returns

verifyReceipt

Verifies a message receipt signed by the Notary.

• Does nothing, if the receipt is valid (matches the saved receipt data for the referenced message).
• Slashes the Notary, if the receipt is invalid.

Will revert if any of these is true:

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

function verifyReceipt(bytes memory rcptPayload, bytes memory rcptSignature) external returns (bool isValidReceipt);

Parameters

Returns

verifyReceiptReport

Verifies a Guard's receipt report signature.

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

Will revert if any of these is true:

• Receipt payload is not properly formatted.
• Receipt Report signer is not an active Guard.
• Receipt does not refer to this chain.

function verifyReceiptReport(bytes memory rcptPayload, bytes memory rrSignature)
    external
    returns (bool isValidReport);

Parameters

Returns

verifyStateWithAttestation

Verifies a state from the snapshot, that was used for the Notary-signed attestation.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Notary, if the state is invalid.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from the Snapshot.
• Snapshot payload is not properly formatted.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithAttestation(
    uint8 stateIndex,
    bytes memory snapPayload,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool isValidState);

Parameters

Returns

verifyStateWithSnapshotProof

Verifies a state from the snapshot, that was used for the Notary-signed attestation.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Notary, if the state is invalid.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from State and Snapshot Proof.
• Snapshot Proof's first element does not match the State metadata.
• Snapshot Proof length exceeds Snapshot Tree Height.
• State payload is not properly formatted.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithSnapshotProof(
    uint8 stateIndex,
    bytes memory statePayload,
    bytes32[] memory snapProof,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool isValidState);

Parameters

Returns

verifyStateWithSnapshot

Verifies a state from the snapshot (a list of states) signed by a Guard or a Notary.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Agent, if the state is invalid.

Will revert if any of these is true:

• Snapshot payload is not properly formatted.
• Snapshot signer is not an active Agent.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithSnapshot(uint8 stateIndex, bytes memory snapPayload, bytes memory snapSignature)
    external
    returns (bool isValidState);

Parameters

Returns

verifyStateReport

Verifies a Guard's state report signature.

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

Will revert if any of these is true:

• State payload is not properly formatted.
• State Report signer is not an active Guard.
• Reported State does not refer to this chain.

function verifyStateReport(bytes memory statePayload, bytes memory srSignature) external returns (bool isValidReport);

Parameters

Returns

getReportsAmount

Returns the amount of Guard Reports stored in StatementInbox.

Only reports that led to opening a Dispute are stored.

function getReportsAmount() external view returns (uint256);

getGuardReport

Returns the Guard report with the given index stored in StatementInbox.

Only reports that led to opening a Dispute are stored.

Will revert if report with given index doesn't exist.

function getGuardReport(uint256 index)
    external
    view
    returns (bytes memory statementPayload, bytes memory reportSignature);

Parameters

Returns

getStoredSignature

Returns the signature with the given index stored in StatementInbox.

Will revert if signature with given index doesn't exist.

function getStoredSignature(uint256 index) external view returns (bytes memory);

Parameters

Returns

InterfaceBondingManager

Git Source

Functions

addAgent

Adds a new agent for the domain. This is either a fresh address (Inactive), or an agent who used to be active on the same domain before (Resting).

Inactive: proof should be the proof of inclusion of an empty leaf having index following the last added agent in the tree.

Resting: proof should be the proof of inclusion of the agent leaf with Resting flag having index previously assigned to the agent.

function addAgent(uint32 domain, address agent, bytes32[] memory proof) external;

Parameters

initiateUnstaking

Initiates the unstaking of the agent bond. Agent signature is immediately no longer considered valid on Synapse Chain, and will be invalid on other chains once the Light Manager updates their agent merkle root on these chains.

proof should be the proof of inclusion of the agent leaf with Active flag having index previously assigned to the agent.

function initiateUnstaking(uint32 domain, address agent, bytes32[] memory proof) external;

Parameters

completeUnstaking

Completes the unstaking of the agent bond. Agent signature is no longer considered valid on any of the chains.

proof should be the proof of inclusion of the agent leaf with Unstaking flag having index previously assigned to the agent.

function completeUnstaking(uint32 domain, address agent, bytes32[] memory proof) external;

Parameters

completeSlashing

Completes the slashing of the agent bond. Agent signature is no longer considered valid under the updated Agent Merkle Root.

proof should be the proof of inclusion of the agent leaf with Active/Unstaking flag having index previously assigned to the agent.

function completeSlashing(uint32 domain, address agent, bytes32[] memory proof) external;

Parameters

remoteSlashAgent

Remote AgentManager should call this function to indicate that the agent has been proven to commit fraud on the origin chain.

This initiates the process of agent slashing. It could be immediately completed by anyone calling completeSlashing() providing a correct merkle proof for the OLD agent status. Note: as an extra security check this function returns its own selector, so that Destination could verify that a "remote" function was called when executing a manager message. Will revert if msgOrigin is equal to contract's local domain.

function remoteSlashAgent(uint32 msgOrigin, uint256 proofMaturity, uint32 domain, address agent, address prover)
    external
    returns (bytes4 magicValue);

Parameters

Returns

withdrawTips

Withdraws locked base message tips from requested domain Origin to the recipient. Issues a call to a local Origin contract, or sends a manager message to the remote chain.

Could only be called by the Summit contract.

function withdrawTips(address recipient, uint32 origin, uint256 amount) external;

Parameters

resolveDisputeWhenStuck

Allows contract owner to resolve a stuck Dispute. This could only be called if no fresh data has been submitted by the Notaries to the Inbox, which is required for the Dispute to be resolved naturally.

Will revert if any of these is true:

• Caller is not contract owner.
• Domain doesn't match the saved agent domain.
• slashedAgent is not in Dispute.
• Less than FRESH_DATA_TIMEOUT has passed since the last Notary submission to the Inbox.

function resolveDisputeWhenStuck(uint32 domain, address slashedAgent) external;

Parameters

getActiveAgents

Returns all active agents for a given domain.

function getActiveAgents(uint32 domain) external view returns (address[] memory agents);

Parameters

agentLeaf

Returns a leaf representing the current status of agent in the Agent Merkle Tree.

Will return an empty leaf, if agent is not added to the tree yet.

function agentLeaf(address agent) external view returns (bytes32 leaf);

Parameters

Returns

leafsAmount

Returns a total amount of leafs representing known agents.

This includes active, unstaking, resting and slashed agents. This also includes an empty leaf as the very first entry.

function leafsAmount() external view returns (uint256 amount);

allLeafs

Returns a full list of leafs from the Agent Merkle Tree.

This might consume a lot of gas, do not use this on-chain.

function allLeafs() external view returns (bytes32[] memory leafs);

getLeafs

Returns a list of leafs from the Agent Merkle Tree with indexes [indexFrom .. indexFrom + amount).

This might consume a lot of gas, do not use this on-chain.

Will return less than amount entries, if indexFrom + amount > leafsAmount

function getLeafs(uint256 indexFrom, uint256 amount) external view returns (bytes32[] memory leafs);

getProof

Returns a proof of inclusion of the agent in the Agent Merkle Tree.

Will return a proof for an empty leaf, if agent is not added to the tree yet. This proof could be used by ANY next new agent that calls {addAgent}.

This WILL consume a lot of gas, do not use this on-chain.

The alternative way to create a proof is to fetch the full list of leafs using either {allLeafs} or {getLeafs}, and create a merkle proof from that.

function getProof(address agent) external view returns (bytes32[] memory proof);

Parameters

Returns

InterfaceDestination

Git Source

Functions

passAgentRoot

Attempts to pass a quarantined Agent Merkle Root to a local Light Manager.

Will do nothing, if root optimistic period is not over.

function passAgentRoot() external returns (bool rootPending);

Returns

acceptAttestation

Accepts an attestation, which local AgentManager verified to have been signed by an active Notary for this chain.

Attestation is created whenever a Notary-signed snapshot is saved in Summit on Synapse Chain.

• Saved Attestation could be later used to prove the inclusion of message in the Origin Merkle Tree.
• Messages coming from chains included in the Attestation's snapshot could be proven.
• Proof only exists for messages that were sent prior to when the Attestation's snapshot was taken.

Will revert if any of these is true:

• Called by anyone other than local AgentManager.
• Attestation payload is not properly formatted.
• Attestation signer is in Dispute.
• Attestation's snapshot root has been previously submitted. Note: agentRoot and snapGas have been verified by the local AgentManager.

function acceptAttestation(
    uint32 notaryIndex,
    uint256 sigIndex,
    bytes memory attPayload,
    bytes32 agentRoot,
    ChainGas[] memory snapGas
) external returns (bool wasAccepted);

Parameters

Returns

attestationsAmount

Returns the total amount of Notaries attestations that have been accepted.

function attestationsAmount() external view returns (uint256);

getAttestation

Returns a Notary-signed attestation with a given index.

Index refers to the list of all attestations accepted by this contract.

Attestations are created on Synapse Chain whenever a Notary-signed snapshot is accepted by Summit. Will return an empty signature if this contract is deployed on Synapse Chain.

function getAttestation(uint256 index) external view returns (bytes memory attPayload, bytes memory attSignature);

Parameters

Returns

getGasData

Returns the gas data for a given chain from the latest accepted attestation with that chain.

Will return empty values if there is no data for the domain, or if the notary who provided the data is in dispute.

function getGasData(uint32 domain) external view returns (GasData gasData, uint256 dataMaturity);

Parameters

Returns

destStatus

Returns status of Destination contract as far as snapshot/agent roots are concerned

function destStatus() external view returns (uint40 snapRootTime, uint40 agentRootTime, uint32 notaryIndex);

Returns

nextAgentRoot

Returns Agent Merkle Root to be passed to LightManager once its optimistic period is over.

function nextAgentRoot() external view returns (bytes32);

lastAttestationNonce

Returns the nonce of the last attestation submitted by a Notary with a given agent index.

Will return zero if the Notary hasn't submitted any attestations yet.

function lastAttestationNonce(uint32 notaryIndex) external view returns (uint32);

InterfaceGasOracle

Git Source

Functions

updateGasData

Fetches the latest gas data for the chain from Destination contract, and uses it to update the oracle values for the requested chain.

function updateGasData(uint32 domain) external;

Parameters

getGasData

Returns the gas data for the local chain.

function getGasData() external view returns (uint256 paddedGasData);

getDecodedGasData

Returns the gas data for the given domain, in the decoded format.

function getDecodedGasData(uint32 domain)
    external
    view
    returns (
        uint256 gasPrice,
        uint256 dataPrice,
        uint256 execBuffer,
        uint256 amortAttCost,
        uint256 etherPrice,
        uint256 markup
    );

Parameters

Returns

getMinimumTips

Returns the minimum tips for sending a message to a given destination.

function getMinimumTips(uint32 destination, uint256 paddedRequest, uint256 contentLength)
    external
    view
    returns (uint256 paddedTips);

Parameters

Returns

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

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

InterfaceLightInbox

Git Source

Functions

submitAttestation

Accepts an attestation signed by a Notary and passes it to Destination contract to save.

Attestation is created whenever a Notary-signed snapshot is saved in Summit on Synapse Chain.

• Saved Attestation could be later used to prove the inclusion of message in the Origin Merkle Tree.
• Messages coming from chains included in the Attestation's snapshot could be proven.
• Proof only exists for messages that were sent prior to when the Attestation's snapshot was taken.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary for local domain.
• Attestation signer is in Dispute.
• Attestation's snapshot root has been previously submitted.
• Attestation's data hash doesn't match the hash of provided agentRoot and snapshot gas data.

function submitAttestation(
    bytes memory attPayload,
    bytes memory attSignature,
    bytes32 agentRoot,
    uint256[] memory snapGas
) external returns (bool wasAccepted);

Parameters

Returns

submitAttestationReport

Accepts a Guard's attestation report signature, as well as Notary signature for the reported Attestation.

AttestationReport is a Guard statement saying "Reported attestation is invalid".

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

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation Report signer is not an active Guard.
• Attestation signer is not an active Notary for local domain.

function submitAttestationReport(bytes memory attPayload, bytes memory arSignature, bytes memory attSignature)
    external
    returns (bool wasAccepted);

Parameters

Returns

InterfaceLightManager

Git Source

Functions

updateAgentStatus

Updates agent status, using a proof against the latest known Agent Merkle Root.

Will revert if the provided proof doesn't match the latest merkle root.

function updateAgentStatus(address agent, AgentStatus memory status, bytes32[] memory proof) external;

Parameters

setAgentRoot

Updates the root of Agent Merkle Tree that the Light Manager is tracking. Could be only called by a local Destination contract, which is supposed to verify the attested Agent Merkle Roots.

function setAgentRoot(bytes32 agentRoot_) external;

Parameters

proposeAgentRootWhenStuck

Allows contract owner to set the agent root to resolve the "stuck" chain by proposing the new agent root. The contract owner will be able to resolve the proposed agent root after a certain period of time. Note: this function could be called multiple times, each time the timer will be reset. This could only be called if no fresh data has been submitted by the Notaries to the Inbox, indicating that the chain is stuck for one of the reasons:

• All active Notaries are in Dispute.
• No active Notaries exist under the current agent root.

*Will revert if any of the following conditions is met:

• Caller is not the contract owner.
• Agent root is empty.
• The chain is not in a stuck state (has recently received a fresh data from the Notaries).*

function proposeAgentRootWhenStuck(bytes32 agentRoot_) external;

Parameters

cancelProposedAgentRoot

Allows contract owner to cancel the previously proposed agent root.

*Will revert if any of the following conditions is met:

• Caller is not the contract owner.
• No agent root was proposed.*

function cancelProposedAgentRoot() external;

resolveProposedAgentRoot

Allows contract owner to resolve the previously proposed agent root. This will update the agent root, allowing the agents to update their status, effectively resolving the "stuck" chain.

*Will revert if any of the following conditions is met:

• Caller is not the contract owner.
• No agent root was proposed.
• Not enough time has passed since the agent root was proposed.*

function resolveProposedAgentRoot() external;

remoteWithdrawTips

Withdraws locked base message tips from local Origin to the recipient.

Could only be remote-called by BondingManager contract on Synapse Chain. Note: as an extra security check this function returns its own selector, so that Destination could verify that a "remote" function was called when executing a manager message.

function remoteWithdrawTips(uint32 msgOrigin, uint256 proofMaturity, address recipient, uint256 amount)
    external
    returns (bytes4 magicValue);

Parameters

proposedAgentRootData

Returns the latest proposed agent root and the timestamp when it was proposed.

Will return zero values if no agent root was proposed, or if the proposed agent root was already resolved.

function proposedAgentRootData() external view returns (bytes32 agentRoot_, uint256 proposedAt_);

InterfaceOrigin

Git Source

Functions

sendBaseMessage

Send a message to the recipient located on destination domain.

*Recipient has to conform to IMessageRecipient interface, otherwise message won't be delivered. Will revert if any of these is true:

• destination is equal to contract's local domain
• content length is greater than MAX_CONTENT_BYTES
• msg.value is lower than value of minimum tips for the given message*

function sendBaseMessage(
    uint32 destination,
    bytes32 recipient,
    uint32 optimisticPeriod,
    uint256 paddedRequest,
    bytes memory content
) external payable returns (uint32 messageNonce, bytes32 messageHash);

Parameters

Returns

sendManagerMessage

Send a manager message to the destination domain.

This could only be called by AgentManager, which takes care of encoding the calldata payload. Note: (msgOrigin, proofMaturity) security args will be added to payload on the destination chain so that the AgentManager could verify where the Manager Message came from and how mature is the proof. Note: function is not payable, as no tips are required for sending a manager message. Will revert if destination is equal to contract's local domain.

function sendManagerMessage(uint32 destination, uint32 optimisticPeriod, bytes memory payload)
    external
    returns (uint32 messageNonce, bytes32 messageHash);

Parameters

withdrawTips

Withdraws locked base message tips to the recipient.

Could only be called by a local AgentManager.

function withdrawTips(address recipient, uint256 amount) external;

Parameters

getMinimumTipsValue

Returns the minimum tips value for sending a message to a given destination.

Using at least tipsValue as msg.value for sendBaseMessage() will guarantee that the message will be accepted.

function getMinimumTipsValue(uint32 destination, uint256 paddedRequest, uint256 contentLength)
    external
    view
    returns (uint256 tipsValue);

Parameters

Returns

InterfaceSummit

Git Source

Functions

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 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;

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
    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()) {}