From bb1137a0632dfa9860184d0c28ad36bab22f6dde Mon Sep 17 00:00:00 2001 From: Fangyu Gai Date: Wed, 6 Nov 2024 15:56:31 +0800 Subject: [PATCH] minor --- docs/commit-pub-rand.md | 85 ++++++++++++++++++++++++----------------- 1 file changed, 49 insertions(+), 36 deletions(-) diff --git a/docs/commit-pub-rand.md b/docs/commit-pub-rand.md index 28e1c425..9e5414a9 100644 --- a/docs/commit-pub-rand.md +++ b/docs/commit-pub-rand.md @@ -6,33 +6,47 @@ The finality provider periodically commits public randomness to the consumer chain to be used for future block finalization. This document specifies the process of committing public randomness. +## Public Randomness Commit + +A public randomness commit is essentially a list of public +randomness, each committed to a specific height. In particular, it consists of: + +- a merkle root containing a list of public randomness values, +- a start height, indicating from which height the randomness starts, and +- the number of randomness contained in the merkle tree. + ## Commit Process -A public randomness commit is composed by a merkle root of a list of public, -along with the start height and the number of randomness contained in the merkle -tree. -Public randomness is an essential component of finality. The finality provider -must commit randomness before it can send finality votes, ensuring the randomness -is available when needed. +Public randomness is an essential component of finality. It should be +committed before finality votes can be sent. Otherwise, the finality provider +looses voting power for this height. -To achieve this, randomness must be committed well in advance. -The finality provider runs a loop to check whether it needs to make a new commit -periodically. In particualar, the following statement is checked: +To this end, when a finality provider is started, it runs a loop to periodically +check whether it needs to make a new commit. In particualar, +the following statement is checked: ```go if lastCommittedHeight < currentHeight + uint64(MinRandHeightGap) ``` +where: + +- `lastCommittedHeight` is the end height (`startHeight + numRand - 1`) +from the latest public randomness commit recorded on the consumer chain +- `currentHeight` is the current height of the consumer chain +- `MinRandHeightGap` is a configuration value, which measures when to make a + new commit + If the statement is true, a new commit should be made to ensure sufficient randomness is available for future blocks. -## Determining MinRandHeightGap +### Determining MinRandHeightGap -The value of `MinRandHeightGap` must account for the BTC-timestamping protocol, -which activates randomness for a specific height after the committed epoch is -BTC-timestamped. Here's an example: +The value of `MinRandHeightGap` must account for BTC-timestamping +delays, which is needed to activate the randomness for a specific height +after the committed epoch is BTC-timestamped. Here's an example: -- Consumer chain receives a commit with: +- The consumer chain receives a commit with: - Start height: 100 - Number of randomness values: 1000 - Current epoch: 10 @@ -51,44 +65,43 @@ Therefore, - `MinRandHeightGap` should be > 6,000 to ensure randomness is always available - Recommended production value: > 10,000 to provide additional safety margin -## Determining commit start height +### Determining Start Height -The general rule of determing the start height of a commit is to the heights -of the randomness are consecutive. In particular, +To determine the start height of a commit: 1. For first-time commit: - - `startHeight = baseHeight + 1` + - `startHeight = baseHeight + 1`, - where `baseHeight` is a future height which is estimated based on the - BTC-timestamping time. + BTC-timestamping delays. 2. For subsequent commit: - - `startHeight = lastCommittedHeight + 1` - - Note that the finality provider might have very long down time. In this - case, we can consider it as the same case as the first-time commit + - `startHeight = lastCommittedHeight + 1`, + - where `lastCommittedHeight` is obtained from the consumer chain. -Note that `startHeight` should not be higher than `finalityActivationHeight`, -a parameter defined in Babylon. Therefore, +The `baseHeight` can be specified via configuration or CLI options. -```go -startHeight = max(startHeight, finalityActivationHeight) -``` +**Important Notes:** -Also note that consecutiveness is not enforced by the consumer chain but it -is required that different commits should not have overlaps. +- After long downtime, treat as first-time commit by specifying `baseHeight`. +- Consecutiveness across commits is not enforced by the system but + different commits must not overlap. +- `startHeight` should not be higher than `finalityActivationHeight`, +a parameter defined in Babylon. Therefore, +`startHeight = max(startHeight, finalityActivationHeight)`. -## Determining the number of randomness +### Determining the Number of Randomness -The number of randomness is specified in the config `NumPubRand`. A general -strategy is that the value should be as large as possible. This is because each -commit to the consumer chain costs gas. +The number of randomness contained in a commit is specified in the config +`NumPubRand`. A general strategy is that the value should be as large +as possible. This is because each commit to the consumer chain costs gas. However, in real life, this stategy might not always gain due to the following reasons: -- a finality provider might not have voting power for every block. Randomness +- A finality provider might not have voting power for every block. Randomness for those heights is a waste. -- generating more randomness leads to a larger merkle proof size which will be +- Generating more randomness leads to a larger merkle proof size which will be used for sending finality votes. -- generating randomness and saving the merkle proofs require time. +- Generating randomness and saving the merkle proofs require time. Additionally, given that the end height of a commit equals to `startHeight + NumPubRand - 1`, we should ensure that the condition