-
Notifications
You must be signed in to change notification settings - Fork 13
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should also have an explainer on:
- Jailing and unjailing
- Public randomness submission
- Reading the logs
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice work composing up everything. Some initial comments:
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We would have a cmd within fpd
after addressing #13.
@vitsalis the options are we either |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Very nice work! Thanks for all the back-and-forth. Mostly minor comments. Some of them can be addressed in a future pr.
We should update CHANGELOG.md to make CI happy
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should cut
``` | ||
|
||
You can verify the transaction was successful by looking up this transaction | ||
hash on the Babylon chain. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@vitsalis what do you think as we already took the CLI cmd out for this
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The doc is very very good already!
Let me know if you'll add the Prometheus metrics in this PR to review again.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
--home ./fpHome | ||
``` | ||
|
||
<!-- TODO: JSON file --> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will this TODO be tracked as an issue?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The issue is here #173
docs/finality-provider-operation.md
Outdated
> finality providers. This could lead to slashing. Only use this if you have | ||
> multiple finality providers. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
> 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
fpd
will not allow create a fp if same eots pk already exists in dbcreate-finality-provider
will 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?
hash on the Babylon chain. | ||
|
||
|
||
<!-- vitsalis: TODO: How about listing the finality providers using the CLI to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What about this TODO?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Has an issue which can be found here #172
Summary
Rework of documentation for users to transition from phase 1 to 2 and includes also how to set up a FP from scratch.