relayer-usage.md

Relayer Usage

The purpose of this document is to provide an overview of the information flows for various messaging layer and function call layer configurations.

Not all function call layer protocols will work with all messaging layer protocols. The table below shows which will work together.

Messaging Layer Protocol	Function Call Protocol
	GPACT and other atomic protocols	SFC and other non-atomic protocols
Event Relay	✗	✓
Transaction Receipt Root Relay	✓	✓
Block Header Relay	✓	✓
Event Attestation	✓	✓

The sections below gloss over a few points. Assume in all flows there are checks for:

• Replay protection checks.
• Checks that each signer is a valid signer for a blockchain.
• Checks that signers only sign once.

Event Relay

The diagram below shows the information flow for a system using Event Relay with Simple Function Call protocol. The system could be used with separate signing where each relayer submits separate transactions to the destination blockchain, or a cooperative signing approach where relayers work together to sign an event and then submit just one transaction per event.

Note that this scheme does not work with GPACT. This simple scheme does not require the application to have the ability to submit the transaction on the destination blockchain.

Walking through the diagram:

1. Application submits a transaction that causes a function in an application contract to be executed.
2. The application contract calls the Crosschain Control contract to execute a crosschain function call.
3. The Crosschain Control contract emits an event indicating the destination blockchain, contract address, function call and parameters to be called. All relayers associated with the blockchain observe the event being emitted. Once the block containing the transaction that emitted the event is final relayers process the event.
4. The relayer signs the event and submits a transaction to the Signed Event Store contract containing the signed event.
5. The Signed Event Store contract verifies the signature of the event by calling the Registrar contract.
6. If a threshold number of relayers have submitted signed events, the Signed Event Store contract calls to the Crosschain Control contract. Once the event has been successfully actioned, a bool is set so not further action will be taken.
7. The Crosschain Control contract checks that the event has a threshold number of signatures.
8. The Crosschain Control contract calls the application contract with the specified function and parameters.

Relayer configuration items that must be set:

• Contract address(es) to observe.
• For each contract address, event signature hashes to observe.
• Finality rules. This could be the number of block confirmation to wait before deeming a block final, or something more complex for systems the Ethereum Beacon Chain that have complex finality.
• The target blockchain that all events should be transferred to. Doing this means that the relayer does not need to be able to interpret the event format.

Notes:

• If multiple levels of finality should be supported, then multiple relayers should be run in parallel. Different Crosschain Control contracts could be used for each level of finality / crosschain transaction prioritisation.
• An alternative to supporting level of finality via multiple relayers would be to have some standard fields in events from the function call layer, that the messaging layer could know about.
• The messaging layer calling to the function call layer is not currently part of the Crosschain Protocol Stack specification.

Block Header Relay and Transaction Receipt Root Relay

The diagram below shows the information flow for a system using Block Header Relay. Transaction Receipt Root Relay is very similar, transferring the transaction receipt root rather than the block header containing the root. The system could be used with separate signing where each relayer submits separate transactions to the destination blockchain, or a cooperative signing approach where relayers work together to sign an event and then submit just one transaction per event.

Walking through the diagram:

1. Application submits a transaction.
   1. For SFC: Execute a function in an application contract.
   2. For GPACT: Execute a function in the Crosschain Control contract.
2. For SFC: The application contract calls the Crosschain Control contract to execute a crosschain function call. For GPACT: The Crosschain Control contract might call the application contract, which in turn may call back to the Crosschain Control Contract.
3. The Crosschain Control contract emits an event containing information useful to the function call protocol. For SFC this indicates the destination blockchain, contract address, function call and parameters to be called. For GPACT this can be the call execution tree being committed to, return results from funcion calls, or whether provisional updates should be committed or discarded.

   All relayers associated with the blockchain observe the event being emitted. Once the block containing the transaction that emitted the event is final relayers process the event. Similarly, the application observes the event.

4. The relayer signs the block header of the block containing the transaction that emitted the event. This signed block header is submitted to the Block Header Store contract.
5. The Block Header Store contract verifies the signature of the block header by calling the Registrar contract.
6. The application waits until a threshold number of relayers have submitted signed block headers.
7. The application calls the Crosschain Control contract with one or more events, and associated Merkle Proofs, proving that the events were emitted by transactions in blocks.
8. The Crosschain Control contract checks that the proof can be used to verify the event with the block headers in the Block Header Store contract.
9. For SFC the Crosschain Control contract calls the application contract with the specified function and parameters. For GPACT, similar to 2., the Crosschain Control contract might call the application contract, which in turn may call back to the Crosschain Control Contract.

Relayer configuration items that must be set:

• Contract address(es) to observe.
• For each contract address, event signature hashes to observe.
• Finality rules. This could be the number of block confirmation to wait before deeming a block final, or something more complex for systems the Ethereum Beacon Chain that have complex finality.
• The target blockchain to transfer all block headers to. Doing this means that the relayer does not need to be able to interpret the event format.
• Threshold used for signing.

Event Attestation

The diagram below shows the information flow for a system using Event Attestation. The system could be used with separate signing where each relayer submits separate transactions to the destination blockchain, or a cooperative signing approach where relayers work together to sign an event and then submit just one transaction per event.

Walking through the diagram:

1. Application submits a transaction.
   1. For SFC: Execute a function in an application contract.
   2. For GPACT: Execute a function in the Crosschain Control contract.
2. For SFC: The application contract calls the Crosschain Control contract to execute a crosschain function call. For GPACT: The Crosschain Control contract might call the application contract, which in turn may call back to the Crosschain Control Contract.
3. The Crosschain Control contract emits an event containing information useful to the function call protocol. For SFC this indicates the destination blockchain, contract address, function call and parameters to be called. For GPACT this can be the call execution tree being committed to, return results from funcion calls, or whether provisional updates should be committed or discarded.

   All relayers associated with the blockchain observe the event being emitted. Once the block containing the transaction that emitted the event is final relayers process the event. Similarly, the application observes the event.

4. The application requests the signed event from attestors. It gathers a threshold number of signatures. If a cooperative signing approach is used, then the application will only need to communicate with one attestor. Note that the signed event may not be available when the application requests it as the attestor may not deem the event to be final.
5. The application calls the Crosschain Control contract with one or more events, and associated signatures.
6. The Crosschain Control contract checks that the signatures are valid and that there are enough signatures by calling the Event Verifier contract.
7. The Event Verifier contract calls the Registrar contract to check that signers are registered.
8. For SFC the Crosschain Control contract calls the application contract with the specified function and parameters. For GPACT, similar to 2., the Crosschain Control contract might call the application contract, which in turn may call back to the Crosschain Control Contract.

Relayer configuration items that must be set:

• Contract address(es) to observe.
• For each contract address, event signature hashes to observe.
• Finality rules. This could be the number of block confirmation to wait before deeming a block final, or something more complex for systems the Ethereum Beacon Chain that have complex finality.
• For cooperative signing schemes: threshold used for signing.