Skip to main content

Light Client Contract

The Light Client Contract is a key component that makes it easy for the NEAR blockchain Mainnet or Testnet to communicate with the Calimero shard. It acts as a bridge, allowing block headers to be relayed and verified seamlessly. Its primary role is to facilitate smooth communication between NEAR and Calimero, making interoperability simple and efficient.

Validation Criteria for Block Headers​

The Light Client Contract has specific validation criteria for validating block headers to ensure the integrity and trustworthiness of the blockchain. Each valid block header must include at least two-thirds of the valid signatures from the epoch block producers. This requirement guarantees the reliability of the relayed headers. To achieve efficiency without compromising security, the contract only needs to verify at least one block header per epoch, rather than every block header in the chain's history.

When providing proof of a transaction occurring at a particular block height, it is crucial to have a block header on the opposite side of the blockchain that confirms the transaction's finality. To meet this condition, the block header on the opposite side should have a block height that is two blocks higher than the block where the transaction took place. This "X+2 rule" ensures that the transaction is considered fully confirmed and provides the necessary blockchain context for verification.

Efficient Verification of Events​

A notable advantage of the Light Client Contract is its ability to efficiently verify events that occurred in previous headers. This is possible due to the presence of a Merkle tree root in every NEAR header, which is computed from all headers before it. With just one NEAR header, the contract can efficiently verify any event that occurred in any previous header.

Head Update Conditions​

The Light Client Contract updates its head based on information from the LightClientBlockView when the following conditions are met:

  1. The block's height is higher than the current head's height.
  2. The epoch of the block matches either the epoch_id or next_epoch_id known for the current head.

This requirement to relay at least one block per epoch is essential because the Epoch Id for epoch number X is derived from the hash of the last block of epoch X-2. Additionally, in the current epoch, there is crucial information about the validators for the next epoch.

Furthermore, if the epoch of the block is the same as the next_epoch_id of the current head, the following additional checks are performed:

  1. Ensure that next_bps (next block producers) is not None.
  2. Validate that approvals_after_next contains valid signatures on the approval_message from the block producers of the corresponding epoch.
  3. Confirm that the signatures in approvals_after_next represent more than two-thirds of the total stake.

Finally, if next_bps is not None, the contract verifies that sha256(borsh(next_bps)) corresponds to the next_bp_hash in inner_lite.

Considerations for Calimero with NEAR Light Client​

When using Calimero with the NEAR light client, one limitation arises due to NEAR's transaction gas limit, set at 300 Tgas per transaction. As signature verifications are computationally intensive, conducting a significant number of such checks (approximately 50) may surpass this limit, resulting in transaction failures.

However, there's promising news on the horizon. Work is underway on NEP364, aiming to introduce ed25519_verify as a precompiled function in the NEAR runtime. Once implemented, this precompiled function will efficiently verify up to 100 validator signatures on each relayed block.

Gas Cost Considerations for NEAR on Calimero Light Client​

In contrast, the signature verification cost is not a significant concern for the NEAR on the Calimero light client contract. Native Calimero tokens do not have any monetary value, they are just used as a consensus mechanism. The shard creator enjoys the freedom to configure the genesis block in a manner that optimizes gas costs, potentially making signature verification more affordable. Additionally, as an advantage, gas can even become free, and the default gas limit of 300 Tgas can be increased if needed. This provides flexibility in managing gas costs for signature verification in the context of NEAR on Calimero.