`XMsg` Lifecycle

Cross-rollup messages are referred to as XMsg in the Omni protocol. Omni uses CometBFT to process XMsgs according to the following sequence.

Flow Diagram

The following steps provide a comprehensive overview of how an XMsg travels from a source rollup VM to a destination rollup VM. This process is visualized in Figure 4.

Steps

1. User Call

A user calls an xdapp smart contract function on a rollup VM.

2. Smart Contract Logic

The smart contract converts the user’s logic into an xcall that is made on the rollup VM’s Portal contract. An xcall is defined in Solidity below (read more in the develop section):

omni.xcall(
  destChainId,  // desintation chain id, e.g. 1 for Ethereum mainnet
  to,           // contract address on the destination chain
  data,         // abi encoded calldata, ex abi.encodeWithSignature("foo()")
  gasLimit      // (optional) gas limit for the call on the destination chain
)

3. Portal Contract Event Emission

The Portal contract converts the xcall into an XMsg and emits the corresponding XMsg event. XMsg events are defined in Solidity as:

event XMsg(
  uint64 indexed destChainId,   // Destination chain ID
  uint64 indexed streamOffset,  // Offset of XMsg in the XStream
  address sender,               // Address of the sender
  address to,                   // Address of the recipient
  bytes data,                   // ABI encoded calldata
  uint64 gasLimit               // Gas limit for the call on the destination chain
);

4. Validator `XMsg` Packaging

For each rollup VM block, validators package all XMsgs into a corresponding XBlock using a deterministic 1:1 mapping. In halo, XBlock are typed as:
```
// Block is a deterministic representation of the omni cross-chain properties of a source chain EVM block.
type Block struct {
  BlockHeader
  Msgs      []Msg     // All cross-chain messages sent/emittted in the block
  Receipts  []Receipt // Receipts of all submitted cross-chain messages applied in the block
  Timestamp time.Time // Timestamp of the source chain block
}
```
XBlock structure provides the following properties to the Omni Network:
- Succinctly verifiable merkle-multi-proofs for sub-ranges of XMsg per source-target pair allowing relayers to manage submission costs at single XMsg granularity.
- Omni Consensus attestations are not required for source network blocks without any XMsg requests (aka empty XBlock).
- Relayer submissions are not required on destination networks for batches without XMsgs.
- The logic to create a XBlock is deterministic for any finalized source rollup block height.
XBlock Storage and Calculation
XBlock is not stored as they are deterministically calculated from a source network. So in effect, the source rollup stores them. Any component that depends on XBlock, calculates it from a source rollup.
$XBlock = f(chain_A)$ where $f(x)$ is a deterministic pure function that takes a finalized network as input and produces XBlock as output. In practice, source blocks can be streamed and transformed using a simple translation function backed by an in-memory cache.

XMsgs are associated with an XStream. An XStream is a logical connection between a source and destination network. It contains many XMsgs, each with a monotonically incrementing XStreamOffset (the offset is like a EOA nonce, it is incremented for each subsequent message sent from a source network to a destination network). XMsgs are therefore uniquely identified and strictly ordered by their associated XStream and XStreamOffset.

XStreamOffset allows for exactly-once delivery guarantees with strict ordering per source-destination network pair.

5. Validator Attestation

Validators attest to XBlock hashes during CometBFT consensus. Each Omni consensus layer validator monitors every finalized block for all source networks in halo. By default, validators wait for block finalization, or some other agreed-upon finality mechanism, to ensure consistent and secure XMsg processing.

All validators use halo to attest to XBlocks via CometBFT vote extensions. All validators in the CometBFT validator set should attest to all XBlock. An attestation is defined by the following Attestation type:
```
// Attestation containing quorum votes by the validator set of a cross-chain Block.
type Attestation struct {
  BlockHeader                 // BlockHeader identifies the cross-chain Block
  ValidatorSetID  uint64      // Validator set that approved this attestation.
  AttestationRoot common.Hash // Attestation merkle root of the cross-chain Block
  Signatures      []SigTuple  // Validator signatures and public keys
}
```
Validators return an array of Attestations during the ABCI++ ExtendVote method.

6. Relayer Collects `XBlocks`

Relayers monitoring the Omni consensus layer gather finalized XBlock hashes and their corresponding XBlock and XMsgs. Finalized rollup blocks without any XMsg events are ignored. The Relayer submits XMsgs to destination networks along with the set of validator signatures.

The relayer determines how many XMsgs to package within each submission based on the “cost” of transactions submitted to the destination network. This is primarily defined by the data size and gas limit of the messages, the portal contract verification costs, and processing overhead.

A merkle-multi-proof is generated for the set of identified XMsg that match the quorum XBlock attestations root.
```
// Msg is a cross-chain message.
type Msg struct {
  MsgID                          // Unique ID of the message
  SourceMsgSender common.Address // Sender on source chain, set to msg.Sender
  DestAddress     common.Address // Target/To address to "call" on destination chain
  Data            []byte         // Data to provide to "call" on destination chain
  DestGasLimit    uint64         // Gas limit to use for "call" on destination chain
  TxHash          common.Hash    // Hash of the source chain transaction that emitted the message
}
```

7. Relayer Submits `XBlocks`

For every finalized XBlock hash, relayers construct an XBlock submission containing the XBlock and the validator signatures for the XBlock hashes. Merkle proofs are generated to prove the inclusion of each XMsg in the XBlock hash. This ensures the decoupling of attestations from execution, thereby allowing the relayer to split the execution of an XBlock into many transactions so that it adheres to the constraints of the destination rollup VM.

8. Relayer Submits `XMsg`

The relayer delivers its submissions to the Portal contract on the destination rollup VM. Relayer submissions are defined in Go as:

// Submission is a cross-chain submission of a set of messages and their proofs.
type Submission struct {
  AttestationRoot common.Hash // Attestation merkle root of the cross-chain Block
  ValidatorSetID  uint64      // Validator set that approved the attestation.
  BlockHeader     BlockHeader // BlockHeader identifies the cross-chain Block
  Msgs            []Msg       // Messages to be submitted
  Proof           [][32]byte  // Merkle multi proofs of the messages
  ProofFlags      []bool      // Flags indicating whether the proof is a left or right proof
  Signatures      []SigTuple  // Validator signatures and public keys
  DestChainID     uint64      // Destination chain ID, for internal use only
}

9. Portal Verification and Forwarding

The receiving network’s Portal contract verifies the XBlock’s validator signatures and XMsg merkle proofs before passing all verified XMsgs to their destination smart contracts. After verifying each submitted XMsg, the portal contract emits an XReceipt event. This marks the XMsg as “successful” or “reverted” by halo. XMsgs can revert if the gas limit was exceeded or if target address smart contract logic reverted for other reasons. XReceipts are included in XBlocks (same as XMsg).

// Receipt is a cross-chain message receipt, the result of applying the Msg on the destination chain.
type Receipt struct {
  MsgID                         // Unique ID of the cross chain message that was applied.
  GasUsed        uint64         // Gas used during message "call"
  Success        bool           // Result, true for success, false for revert
  RelayerAddress common.Address // Address of relayer that submitted the message
  TxHash         common.Hash    // Hash of the relayer submission transaction
}

10. Smart Contract Execution

The receiving smart contracts execute the logic for their users.

XMsg Lifecycle

Flow Diagram​

Steps​

1. User Call​

2. Smart Contract Logic​

3. Portal Contract Event Emission​

4. Validator XMsg Packaging​

5. Validator Attestation​

6. Relayer Collects XBlocks​

7. Relayer Submits XBlocks​

8. Relayer Submits XMsg​

9. Portal Verification and Forwarding​

10. Smart Contract Execution​