Skip to content

Latest commit

 

History

History
99 lines (71 loc) · 4.07 KB

send-finality-vote.md

File metadata and controls

99 lines (71 loc) · 4.07 KB
Raw

Finality Votes Submission Specification

Overview

Finality providers submit votes to finalize blocks on the consumer chain. This document specifies the process of submitting finality votes.

Submission Process

Internal State

The finality provider maintains a persistent state variable lastVotedHeight to track the most recent height where a finality vote was successfully submitted This is to prevent voting for a previously voted height.

Bootstrapping

To determine the initial processing height startHeight:

  1. Query consumer chain for:

    • lastFinalizedHeight (defaults to 0 if no blocks are finalized)
    • finalityActivationHeight
    • lastVotedHeightRemote (defaults to 0 if no votes exist)

  2. Synchronize local state:

    • Verify local lastVotedHeight >= lastVotedHeightRemote
    • If verification fails, update local state to match remote

  3. Calculate starting height based on reward distribution policy:

    • If rewards are available for already finalized blocks:

      startHeight = max(lastVotedHeight + 1, finalityActivationHeight)

    • If rewards are only for unfinalized blocks:

      startHeight = max(lastFinalizedHeight + 1, finalityActivationHeight)

The choice between using lastVotedHeight or lastFinalizedHeight depends on the consumer chain's reward distribution mechanism. Use lastVotedHeight if the chain allows collecting rewards for already finalized blocks. Otherwise, use lastFinalizedHeight to only process unfinalized blocks.

Normal Submission Loop

After the finality provider is bootstrap, it continuously monitors for new blocks from a trusted full node of the consumer chain. For each new block, it performs these validation checks:

  1. Block hasn't been previously processed
  2. Block height exceeds finality activation height
  3. Finality provider has sufficient voting power

Upon passing all checks, the finality provider:

  1. Requests a finality signature from the EOTS manager
  2. Submits the vote transaction to the consumer chain
  3. Implements retry logic until either:
    • Maximum retry attempts are reached
    • Block becomes finalized

Batch submission

A batch submission mechanism is needed to deal with cases where:

  • recovery from downtime, and
  • the consumer chain has rapid block production.

Batch sumission puts multiple new blocks into a batch and process them in the same loop, after which all the finality votes will be sent in the same transaction to the consumer chain.

Generating Finality Votes

To submit a finality vote, the finality provider needs to fill the MsgAddFinalitySig:

  1. Finality provider public key: the BTC PK of the finality provider that casts the vote in BIP340 format.
  2. Block height: the height of the block that the vote is signed for.
  3. Public randomness: the public randomness that is retrieved from the local, which is a 32-byte point over secp256k1.
  4. Merkle proof: the merkle proof of the public randomness, which is generated when constructing the public randomness commit using the CometBFT's merkle library.
  5. Block hash: the hash bytes of the block that the vote is signed.
  6. Finality signature: the EOTS signature that is signed by the finality provider's private key and the corresponding private randomness.

The consumer chain verifies:

  • The finality provider has voting power for the given height
  • Randomness was pre-committed and BTC-timestamped
  • EOTS signature validity