This is a working document. It is inappropriate to cite this document other than as a work in progress.

Please send any comments to the editors of this document.

Github Issues are preferred for discussion of this document.

This document is available under the terms of the Apache License 2.0.

When referencing this document, the following citation format should be used:

[eeaciw-messaging-v1.0] EEA CIW - Technical Specification Messaging Interface Draft Version 1.0. Edited by Weijia Zhang, Peter Robinson and Aiman Baharna. 28 February 2022. EEA CIW. https://entethalliance.github.io/crosschain-interoperability/draft_crosschain_techspec_messaging.html . Latest stage: https://entethalliance.github.io/crosschain-interoperability/draft_crosschain_techspec_messaging.html .

Representation of message and messaging mechannism

Crosschain Messaging is represented as one of the following.

• Event: Messages are identified as emitted events on source blockchain.
• State: Contract data which is ultimately represented as StorageRoot can also be used to represent messages. [Other methods such as ZKP can also be used to verify the source chain state]

Note that a message represented as event is stored in a transaction receipt where as one represented as state is stored in the state trie.

Event-based messaging mechanism

pragma solidity >=0.8;

interface CrosschainVerifier {
  function decodeAndVerifyEvent(uint256 _blockchainId, bytes32 _eventSig,
    bytes calldata _encodedInfo, bytes calldata _signatureOrProof)
    external view;
}

State-based messaging mechanism

Overview and interface

One can use a similar definition to support state-based messaging and verification.
Similarly, we can define function decodeAndVerifyCommitment with argument of _encodedInfo to include state data instead of event data.
For example, _encodedInfo can be a StorageRoot to represent the entire key-value state.
In decodeAndVerifyCommitment, _signatureOrProof is used for the proof of state representation of _encodedInfo.
(Note that _eventSig is not a required field in the state-based messaging.)

Verification

Signature-based verification can be applied for state-based messaging exactly as in event-based attestation.
Alternatively we can also rely on a light client verification as well.
In the latter setting, _signatureOrProof needs to contain information necessary for header verification such as aggregated validators' signatures.

When setting StorageRoot as _encodedInfo in decodeAndVerifyCommitment, we need a mechanism to verify the state using StorageRoot.
For example, one can define verifyMembership(_stateInfo, _proof) to verify the encoded state (_stateInfo) using encoded merkle proof (_proof) with _encodeInfo as StorageRoot.
Unlike events in transaction receipts, the current header includes states in the past. This also contributes to reduce crosschain header transfer.
We can find a similar specification in ICS.

pragma solidity >=0.8;
struct Signature {
  uint256 by;
  uint256 sigR;
  uint256 sigS;
  uint256 sigV;
  bytes   meta;
}
struct Signatures {
  uint256 typ;
  bytes proof;
  Signature[] signatures;
}

pragma solidity >=0.8;
struct Signature {
  uint256 by;
  uint256 sigR;
  uint256 sigS;
  uint256 sigV;
  bytes   meta;
}
struct Signatures {
  uint256 typ;
  bytes proof;
  Signature[] signatures;
}

pragma solidity >=0.8;
struct ProofData {
  bytes witnesses;
  bytes32 root;
  bytes32 blockHash;
  bytes blockHeaderMeta;
}
struct Signature {
  uint256 by;
  uint256 sigR;
  uint256 sigS;
  uint256 sigV;
  bytes   meta;
}
struct Signatures {
  uint256 typ;
  bytes proof;
  Signature[] signatures;
}

pragma solidity >=0.8;
struct ProofData {
  bytes32 root;
  bytes32[] witnesses;
  uint8[] flags;
  bytes32[] values;
}
struct Signature {
  uint256 by;
  uint256 sigR;
  uint256 sigS;
  uint256 sigV;
  bytes   meta;
}
struct Signatures {
  uint256 typ;
  bytes proof;
  Signature[] signatures;
}

The Crosschain Messaging process is used to ensure events emitted on a source blockchain are trusted on one or more target blockchains. Cross Function Call protocols may allow for calls across multiple blockchains. In this case, multiple instantiations of the messaging protocol described below are needed to ensure all of the events emitted on various blockchains are trusted on the blockchains on which the events will be consumed.

The general flow for Crosschain Messaging processing is shown below. The processing required for specific protocols is described later in this standard.

1. The user application does some action that causes a crosschain function call across one or more blockchains.
2. The Crosschain Function Call contract on the source blockchain emits an event. The circumstances in which an event is emitted and the meaning of the event are Crosschain Function Call protocol dependant.
3. Relayer nodes (also known as Attestors or Oracles) observe the blockchain for events being emitted by the Crosschain Function Call contract. The action of the Relayer node depends on the Crosschain Messaging protocol.
   • Event Relay: Some Relayers sign events and submit them in transactions to the target blockchain's Crosschain Function Call contract. The Crosschain Function Call contract then processes the event and does some action. In these cases, there is no more processing to be done.
   • Block Header Transfer: Some Relayers forward block headers or some other Merkle Root to target blockchains.
   • Event Attestation: Some Relayers sign events and allow applications to request the signed events.
4. The Crosschain Function Call SDK code monitors for the event being emitted. The code calls the Crosschain Messaging Layer SDK code to ensure the Crosschain Messaging component knows which target blockchains the event will be needed on. The Crosschain Messaging SDK code creates or obtains verifiable event information and returns it to the Crosschain Function Call SDK code. For example, in the case of an Event Attestation approach, it could request signed event information from an Attestor. Alternatively, in the case of a Block Header Relay approach, it could create a Merkle Proof.
5. The Crosschain Function Call SDK code submits a transaction to the target blockchain, calling the Crosschain Function Call contract on the target blockchain. It supplies the event and signature or proof information from the Crosschain Messaging Layer SDK code. The Crosschain Function Call contract calls the Crosschain Messaging contract for the source blockchain calling decodeAndVerifyEvent. This call verifies that the event information did come from the source blockchain and can be trusted.

Protocol Specific Processing

The sections below detail the protocol specific processing supported by this standard. [R2] Complying implementations MUST support at least one of the protocols described below.

Considerations

Typographical Conventions

Requirement Ids

A requirement is uniquely identified by a unique ID composed of its requirement level followed by a requirement number, as per convention [RequirementLevelRequirementNumber]. There are four requirement levels that are coded in requirement ids as per below convention:

• [R] - The requirement level for requirements which IDs start with the letter R is to be interpreted as MUST as described in RFC2119.
• [D] - The requirement level for requirements which IDs start with the letter D is to be interpreted as SHOULD as described in RFC2119.
• [O] - The requirement level for requirements which IDs start with the letter O is to be interpreted as MAY as described in RFC2119.

Note that requirements are uniquely numbered in ascending order within each requirement level.

Example : It should be read that [R1] is an absolute requirement of the specification whereas [D1] is a recommendation and [O1] is truly optional.

Conditional Requirements

Conditional requirements are expressed as per convention [ConditionalRequirementID] < [ControllingRequirementID]. A conditional requirement becomes required if and only if its controlling requirement is implemented.

For instance [CR1] < [D3] means that if recommended requirement [D3] is implemented then it is required to also implement requirement [CR1].