Smart Contracts

An overview of all the smart contracts used in Telepathy.

For more details about any of these contracts, please refer to the source code for the contracts and circuits respectively.

Light Client

The Light Client contract is responsible for keeping up-to-date with the state of Ethereum. In particular, it keeps track of an append-only list of Ethereum block headers based on the verification that >2/3rds of the sync committee has provided signatures.

To add a new block header to a Light Client, one must generate a zkSNARK proof that validates the latter claim and pass the proof as an argument to the step function:

step(LightClientStep memory update)

where an update contains all the necessary information for validation:

struct LightClientStep {
    uint256 attestedSlot;
    uint256 finalizedSlot;
    uint256 participation;
    bytes32 finalizedHeaderRoot;
    bytes32 executionStateRoot;
    Groth16Proof proof;
}

This allows the Light Client to check the following conditions:

• >2/3rds participation signatures from the current sync committee

• A valid finality proof for the finalizedHeaderRoot

• A valid execution state root proof against the finalizedHeaderRoot

If those conditions all pass, the current head of the Light Client is set to the finalizedSlot with the finalizedHeaderRoot stored on-chain.

Router

The Router contract is how developers use Telepathy Protocol to achieve cross-chain communication between their contracts. It is responsible for handling both the sending and receiving of messages.

Sending

When the Router is used on the source chain to send messages, the entry point is the Router's send function:

send(uint32 destinationChainId, bytes32 destinationAddress, bytes calldata data)

The destinationChainId and destinationAddress parameters are used to specify the chain and the address of the destination contract. The data parameter is used to specify the message that the destination contract receives. The send function emits a SentMessage event, which is used for validation on the destination chain.

Receiving

When on the destination chain, the Router contract is responsible for relaying the message by using the light client to verify the message was actually sent on the source chain, and then calling handleTelepathy with the correct arguments. This happens when executeMessageFromLog function is called:

executeMessageFromLog(
    bytes calldata srcSlotTxSlotPack,
    bytes calldata messageBytes,
    bytes32[] calldata receiptsRootProof,
    bytes32 receiptsRoot,
    bytes[] calldata receiptProof,
    bytes memory txIndexRLPEncoded,
    uint256 logIndex
)

An off-chain actor, known as a Relayer, will call this function with the required information and Merkle proofs that are used to validate the message against the stored header root in the LightClient. Once validated, the message is relayed to the specifieddestinationAddress via the handleTelepathyfunction:

handleTelepathy(uint32 sourceChainId, address sourceAddress, bytes memory data)

A destination contract must implement this function to receive the message.