Relayer Service

The relayer is a fundamental component of the bridge, responsible for establishing bidirectional communication between chains. It receives blocks from a source chain and relays them to a light client contract on the destination chain. This enables seamless interoperability and data transfer between the two chains. It is important to note that light client contracts must be deployed on both the source and destination chains for the relayer to function effectively.

NEAR to Calimero Relayer

The NEAR to Calimero relayer specifically focuses on relaying blocks from the NEAR blockchain to the designated light client contract on the Calimero shard. Information is relayed when needed (Calimero event occurred on the opposite side or once per the epoch). The relayer acts on the messages received from the events indexer.

Calimero to NEAR Relayer

Similarly, the Calimero to NEAR relayer performs the opposite function by relaying blocks from the Calimero shards to individual light client contracts on the NEAR blockchain. Each Calimero shard has its own dedicated light client contract on the NEAR side (one per shard with a bridge installed). The relayer operates based on the messages received from the events indexer.

Light Client Block Structure

The light client block structure represents the data that is relayed by the relayer. It consists of several substructures that provide essential details about the block being relayed.

LightClientBlock

pub struct LightClientBlock {
    pub prev_block_hash: Hash,
    pub next_block_inner_hash: Hash,
    pub inner_lite: BlockHeaderInnerLite,
    pub inner_rest_hash: Hash,
    pub next_bps: Option<Vec<Validator>>,
    pub approvals_after_next: Vec<Option<Signature>>,
}

• LightClientBlock: Represents a block being relayed. It contains the following fields:
  • prev_block_hash: Hash of the previous block.
  • next_block_inner_hash: Hash of the inner block of the next block.
  • inner_lite: BlockHeaderInnerLite structure containing metadata about the block.
  • inner_rest_hash: Hash of the rest of the inner block.
  • next_bps: Optional vector of validators representing the next block producers.
  • approvals_after_next: Vector of optional signatures representing approvals for the block.

BlockHeaderInnerLite

pub struct BlockHeaderInnerLite {
    pub height: u64, // Height of this block since the genesis block (height 0).
    pub epoch_id: Hash, // Epoch start hash of this block's epoch. Used for retrieving validator information
    pub next_epoch_id: Hash,
    pub prev_state_root: Hash, // Root hash of the state at the previous block.
    pub outcome_root: Hash, // Root of the outcomes of transactions and receipts.
    pub timestamp: u64, // Timestamp at which the block was built.
    pub next_bp_hash: Hash, // Hash of the next epoch block producers set
    pub block_merkle_root: Hash,
}

• BlockHeaderInnerLite: Contains metadata about the block. It includes the following fields:
  • height: Height of this block since the genesis block (height 0).
  • epoch_id: Epoch start hash of this block's epoch. Used for retrieving validator information.
  • next_epoch_id: Hash representing the next epoch.
  • prev_state_root: Root hash of the state at the previous block.
  • outcome_root: Root hash of the outcomes of transactions and receipts.
  • timestamp: Timestamp at which the block was built.
  • next_bp_hash: Hash of the next epoch block producers set.
  • block_merkle_root: Root hash of the Merkle tree representing the block.

Validator

pub enum Validator {
    V1(ValidatorV1),
    V2(ValidatorV2),
}

pub struct ValidatorV1 {
    pub account_id: String,
    pub public_key: PublicKey,
    pub stake: u128,
}

pub struct ValidatorV2 {
    pub account_id: String,
    pub public_key: PublicKey,
    pub stake: u128,
    pub is_chunk_only: bool,
}

• Validator: Represents a validator participating in the consensus process. It can be of two types: ValidatorV1 or ValidatorV2.

Signature

pub enum Signature {
    ED25519(ed25519_dalek::Signature),
    SECP256K1(Secp256K1Signature),
}

• Signature: Represents the cryptographic signatures used for block validation. It can be of two types: ED25519 or SECP256K1. Signatures are relayed alongside the block data to ensure the authenticity and integrity of the relayed blocks.