Skip to main content

Light Client Contract

There are 2 scenarios, either a bridge from NEAR mainnet to Calimero shard is needed, or a Calimero shard to Calimero shard bridge can be needed for various use cases. Calimero on NEAR Client and NEAR on Calimero Client are implementations of the NEAR light client as a contract. The light client contract will accept block headers that are being relayed to it if the blocks meet certain validation criteria - most notably each valid block header needs to contain at least two thirds valid signatures of the epoch block producers. The contract does not need to verify every single block header for blocks that happened ever in the chain history, as long as it has at least one verified block header per epoch. Another useful property of the light client is that every NEAR header contains a root of the merkle tree computed from all headers before it. As a result, if you have one NEAR header you can efficiently verify any event that happened in any header before it.

The light client updates its head with the information from LightClientBlockView iff:

  • The height of the block is higher than the height of the current head;
  • The epoch of the block is equal to the epoch_id or next_epoch_id known for the current head;
  • If the epoch of the block is equal to the next_epoch_id of the head, then next_bps is not None; approvals_after_next contain valid signatures on approval_message from the block producers of the corresponding epoch;
  • The signatures present in approvals_after_next correspond to more than 2/3 of the total stake;
  • If next_bps is not None, sha256(borsh(next_bps)) corresponds to the next_bp_hash in inner_lite`

For Calimero on the NEAR light client there is a limitation as on NEAR there is a 300 Tgas limit per transaction. Signature verifications are expensive (with ~50 signature checks we break the limit and tx fails). However the good news is that initially the number of validators on Calimero will be limited to around 20, so this will pass.

Even better news is NEP364 which is in progress. It will add ed25519_verify as a precompiled function on NEAR runtime, which should allow us to verify all maximum 100 validator signatures on every relayed block.

For the NEAR on Calimero light client contract the signature verifying cost is not a big issue since the shard creator can setup genesis in such way that the gas costs are cheaper.