docs: finality provider phase 1 to phase 2 documentation for operators #130
Conversation
docs/finality-provider-phase2.md
Outdated
| ## Loading Existing Keys (Only for Phase 1 Finality Providers) | ||
|
|
||
| Note: This section is only for users who participated in Phase 1 and already | ||
| have an EOTS key. If you are a new user, you can skip this section. | ||
|
|
||
| If you participated in Phase 1, follow these steps to load your existing EOTS | ||
| key and configure it for Phase 2. | ||
|
|
||
| ### Step 1: Verify Your EOTS Key Backup | ||
| Before proceeding, ensure you have a backup of your Phase 1 EOTS key. | ||
| You will need this backup file to import the key into the Phase 2 environment. | ||
|
|
||
| ### Step 2: Import Your EOTS Key into the Keyring | ||
| To load your existing EOTS key, use the following command to import it into the | ||
| keyring: | ||
|
|
There was a problem hiding this comment.
This is TBC, need to confirm and is still being developed
docs/finality-provider-phase2.md
Outdated
| Bitcoin network (for security) and the Babylon network (for rewards and | ||
| governance). | ||
|
|
||
| ## Slashing Conditions |
There was a problem hiding this comment.
We should also have an explainer on:
- Jailing and unjailing
- Public randomness submission
- Reading the logs
There was a problem hiding this comment.
Ah nice one @gitferry ! We can just reference the doc then. Maybe we could have a nice graphic that explains the life cycle of the finality provider, including creation, registration, randomness commits, voting, etc.
There was a problem hiding this comment.
https://github.com/babylonlabs-io/finality-provider/blob/main/docs/fp-status-transition.png
something like this or even more detail. Again @gitferry's great work
There was a problem hiding this comment.
The scope of this doc is fore migration and registration, so for other operations like how the fp works, how to unjail we should have reference to them. Docs we already have:
- fp status transition:
./docs/fp-core.md - public randomness commit:
./docs/commit-pub-rand.md - send finality votes:
./docs/send-finality-vote.md
Docs we are missing (let's leave todos for them):
- Unjail instruction
- Slashing protection
- Withdraw (or Claim) rewards
There was a problem hiding this comment.
We don't already have but this can be something I can work on and I agree they can be linked here.
|
Also, is this going to replace the existing documentation? If so, maybe the PR should delete them. |
docs/finality-provider-phase2.md
Outdated
| - Generates a BTC public key that uniquely identifies your finality provider | ||
| - Creates a Babylon account to receive staking rewards |
There was a problem hiding this comment.
Let's avoid creating keys in this cmd. EOTS keys should be created via eotsd keys add and Babylon account should be created via fpd keys add. I was thinking that we should introduce eots-pk flag as required to identify the EOTS key to sign pop.
Therefore, the purpose of this cmd is to prepare all the information (description and generating pop) locally for future registration
There was a problem hiding this comment.
Just triple checking (again) this is the right command though: create-finality-provider and this won't add the babylon account automatically?
There was a problem hiding this comment.
In the current implementation create-finality-provider will create eots key and babylon account if --keyname does not exist, but we should change it to not duplicate functionalities with keys add
docs/finality-provider-phase2.md
Outdated
| When withdrawing rewards, you need to use the Babylon chain's CLI since rewards | ||
| are managed by the main chain. |
There was a problem hiding this comment.
We would have a cmd within fpd after addressing #13.
@vitsalis the options are we either |
docs/finality-provider-operation.md
Outdated
| If one is not provided the finality provider will request | ||
| the creation of a new one from the connected EOTS manager instance. |
| ``` | ||
|
|
||
| You can verify the transaction was successful by looking up this transaction | ||
| hash on the Babylon chain. |
There was a problem hiding this comment.
Should we provide a link to a third party explorer or CLI cmd to query the tx content?
There was a problem hiding this comment.
@vitsalis what do you think as we already took the CLI cmd out for this
There was a problem hiding this comment.
Don't think we should link to something here, not the purpose of this guide. This is just a small tip.
I think including the below TODO should be enough in terms of verification
There was a problem hiding this comment.
Great work! Various comments here and there. Happy to not resolve all of them before merging this PR as long as they are tracked as issues.
Let's verify whether we can support encrypted keyrings for the EOTS manager before merging this PR. If we can only support test I have outlined various spots that we need to update our wording to reflect that on Section 3.
| The BTC staker connects to a Bitcoin wallet and Babylon to perform delegations. | ||
| Finality providers are key participants in Babylon BTC staking protocol. | ||
| They provide finality votes on top of | ||
| [CometBFT](https://github.com/cometbft/cometbft), Babylon's consensus mechanism. |
There was a problem hiding this comment.
| [CometBFT](https://github.com/cometbft/cometbft), Babylon's consensus mechanism. | |
| [CometBFT](https://github.com/cometbft/cometbft), Babylon's consensus mechanism, |
| A Babylon network node that provides chain data and transaction | ||
| submission capabilities. While not mandatory, running your own node is | ||
| strongly recommended for security rather than relying on third-party RPC nodes. | ||
| See the [Setup Node Guide](https://docs.babylonchain.io/docs/user-guides/btc-staking-testnet/setup-node) for details. |
There was a problem hiding this comment.
We should point to the networks repository. You can use the link that will be used once the networks PR is merged.
Also wrap to 80 characters per line
| network segment. | ||
| 3. **Finality Provider Daemon**: | ||
| The core daemon that polls Babylon blocks, commits public randomness, and | ||
| submits finality signatures. It manages provider status transitions and handles |
There was a problem hiding this comment.
| submits finality signatures. It manages provider status transitions and handles | |
| submits finality signatures. It manages the finality provider's status transitions and handles |
| the [Babylon BTC Staking Litepaper](https://docs.babylonchain.io/assets/files/btc_staking_litepaper-32bfea0c243773f0bfac63e148387aef.pdf). | ||
| In short, the EOTS manager generates EOTS public/private randomness pairs. The |
There was a problem hiding this comment.
| the [Babylon BTC Staking Litepaper](https://docs.babylonchain.io/assets/files/btc_staking_litepaper-32bfea0c243773f0bfac63e148387aef.pdf). | |
| In short, the EOTS manager generates EOTS public/private randomness pairs. The | |
| the [Babylon BTC Staking Litepaper](https://docs.babylonchain.io/assets/files/btc_staking_litepaper-32bfea0c243773f0bfac63e148387aef.pdf). | |
| In short, the EOTS manager generates EOTS public/private randomness pairs. The |
| The EOTS daemon is responsible for managing EOTS keys, producing EOTS randomness, and | ||
| using them to produce EOTS signatures. | ||
|
|
||
| **Note:** EOTS stands for Extractable One Time Signature. You can read more about it |
There was a problem hiding this comment.
Maybe we could indent the "Note" with > ⚡ as we do in other parts of the documentation?
| --home ./fpHome | ||
| ``` | ||
|
|
||
| <!-- TODO: JSON file --> |
There was a problem hiding this comment.
Will this TODO be tracked as an issue?
| > finality providers. This could lead to slashing. Only use this if you have | ||
| > multiple finality providers. |
There was a problem hiding this comment.
| > finality providers. This could lead to slashing. Only use this if you have | |
| > multiple finality providers. | |
| > finality providers. This could lead to slashing. |
Only use what?
|
|
||
| Required parameters: | ||
| - `--chain-id`: The Babylon chain ID (e.g., for the testnet, `bbn-test-5`) | ||
| - `--eots-pk`: The EOTS public key maintained by the connected EOTS manager |
There was a problem hiding this comment.
@gitferry does the EOTS manager provide protections against people using the same --eots-pk? Worry this might be misused leading to slashing or wasting randomness.
There was a problem hiding this comment.
fpdwill not allow create a fp if same eots pk already exists in dbcreate-finality-providerwill let EOTS manager sign pop (Schnorr sign not EOTS sign). Even if it is the same eots pk, signing over different babylon address will not cause slashing. Why would it relate to randomness?
| - `fp_addr`: Your Babylon account address for receiving | ||
| rewards |
There was a problem hiding this comment.
| - `fp_addr`: Your Babylon account address for receiving | |
| rewards | |
| - `fp_addr`: Your Babylon account address of the finality provider |
Avoiding mentioning rewards if not necessary.
| hash on the Babylon chain. | ||
|
|
||
|
|
||
| <!-- vitsalis: TODO: How about listing the finality providers using the CLI to |
Summary
Rework of documentation for users to transition from phase 1 to 2 and includes also how to set up a FP from scratch.