From 37500059eda2449a3a4a349ff65d0f9d62333fa3 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Tue, 17 Dec 2024 00:33:39 +1100 Subject: [PATCH 01/10] wip --- docs/transition-phase-2.md | 72 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/transition-phase-2.md diff --git a/docs/transition-phase-2.md b/docs/transition-phase-2.md new file mode 100644 index 0000000..4506fed --- /dev/null +++ b/docs/transition-phase-2.md @@ -0,0 +1,72 @@ +# Transition your stake from phase-1 to phase-2 through CLI + + + + +> **⚡ Note:** This program is a separate implementation from the staker program +> used for Phase-1. All stakers are required to transition their stakes to this +> program to participate in Phase-2. + +## Table of Contents +- [Prerequisites](#prerequisites) +- [1. Setup](#1-setup) +- [2. Transition your stake](#2-transition-your-stake) + +## Prerequisites + +To transition your stake from phase-1 to phase-2, you need to have the following: +- Global parameter file as seen here https://github.com/babylonlabs-io/networks/blob/main/bbn-5/parameters/global-params.json that were used in phase-1 +- The Bitcoin block height in which your staking transaction was included +- Your `btc-staker` binary setup and running inclusive of the btc staker config + properly setup + +## 1. Setup + +First, you need to run the upgrade setup which configures the environment and +runs necessary upgrade procedures: + +```bash +cd deployments/local +make bbn-upgrade-v1 +``` + +Next, you need to dump the default configuration file. This creates a template +that you'll customize with your specific values (like your Bitcoin block height +that your staking transaction was included in, wallet credentials, +and network details): + +```bash +stakercli admin dump-config +``` + +This will create a `config.json` file in your current working directory. +You'll need to modify this file with your specific settings before proceeding. + +Finally, start the `btcstaker` daemon which will manage your connections to both +Babylon and Bitcoin nodes, monitor transactions, and handle the staking process: + +```bash +stakercli admin start +``` + +## 2. Transition your stake + +After setting up the configuration file and starting the `btcstaker` daemon, +you can proceed to transition your stake from Phase-1 to Phase-2 using the +following command. We use the `global_parameters.json` file that you should +already have created as stated in the prerequisites. + +```shell +stakercli daemon stake-from-phase1 \ + --staking-transaction-hash \ + --staker-address \ + --tx-inclusion-height +``` + +parameters: +- `global-parameters-file`: The path to the global parameters file. +- `your-phase1-tx-hash`: The original hash of your phase-1 staking transaction. +- `your-btc-address`: BTC address of the staker in hex +- `block-height`: The block height at which your staking transaction was + included. + From 907fa366dcc65c2c4d85d8e416a9a96d44b8957d Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Wed, 18 Dec 2024 17:05:44 +1100 Subject: [PATCH 02/10] Update transition-phase-2.md --- docs/transition-phase-2.md | 113 ++++++++++++++++++++++++------------- 1 file changed, 74 insertions(+), 39 deletions(-) diff --git a/docs/transition-phase-2.md b/docs/transition-phase-2.md index 4506fed..38f9a35 100644 --- a/docs/transition-phase-2.md +++ b/docs/transition-phase-2.md @@ -1,59 +1,95 @@ # Transition your stake from phase-1 to phase-2 through CLI - - - -> **⚡ Note:** This program is a separate implementation from the staker program -> used for Phase-1. All stakers are required to transition their stakes to this -> program to participate in Phase-2. +## Understanding the transition + +The transition from phase-1 to phase-2 is a manual process that requires the +staker to transition their stake to phase-2 of the Babylon network. +This transition has the option of being executed through the `stakercli` binary +and this guide will show you how to do it through the `stakercli` binary. For +detailed information about stake eligibility +criteria, registration requirements, and how to gain voting power and earn +rewards in phase-2, please refer to the +[phase-2 transition guide](https://gist.github.com/vitsalis/9ebfd19bbde310e0bf4a70e7ab15a290). + ## Table of Contents - [Prerequisites](#prerequisites) -- [1. Setup](#1-setup) -- [2. Transition your stake](#2-transition-your-stake) +- [Setup](#setup) +- [Transition your stake](#transition-your-stake) +- [Verify the transition](#verify-the-transition) ## Prerequisites -To transition your stake from phase-1 to phase-2, you need to have the following: -- Global parameter file as seen here https://github.com/babylonlabs-io/networks/blob/main/bbn-5/parameters/global-params.json that were used in phase-1 -- The Bitcoin block height in which your staking transaction was included -- Your `btc-staker` binary setup and running inclusive of the btc staker config - properly setup - -## 1. Setup - -First, you need to run the upgrade setup which configures the environment and -runs necessary upgrade procedures: - -```bash -cd deployments/local -make bbn-upgrade-v1 -``` - -Next, you need to dump the default configuration file. This creates a template -that you'll customize with your specific values (like your Bitcoin block height -that your staking transaction was included in, wallet credentials, -and network details): +To transition your stake from phase-1 to phase-2, you need to have the +following: +- Access to your existing Bitcoin wallet from phase-1 (needed to sign transactions + and prove ownership of staked funds). +- The Bitcoin block height in which your staking transaction was included, which + will be used in the transition command. +- A funded Babylon address, which will be used to receive the rewards from the + transition. +- Global parameter file as seen here https://github.com/babylonlabs-io/networks/blob/main/bbn-test-5/parameters/global-params.json + that were used in phase-1. This will be used in the transition command later + on. +- A running instance of the `stakercli` binary. Please follow the `stakercli` + [setup guide](../README.md#3-btc-staker-installation) to complete the setup of + the `stakercli` with your keys before proceeding. + +## Setup + +First, you will need to dump the default configuration file. This creates a +template configuration file that you'll customize with your specific values +(like your Bitcoin block height that your staking transaction was included in, +wallet credentials, and network details): ```bash stakercli admin dump-config ``` This will create a `config.json` file in your current working directory. -You'll need to modify this file with your specific settings before proceeding. +You'll need to modify this file with your specific settings before proceeding. +Here are the key configurations: + +### Bitcoin Configuration +```toml +[walletconfig] +WalletName = "btc-staker" # Your Bitcoin wallet name +WalletPass = "your-wallet-password" # Your wallet password + +[walletrpcconfig] +Host = "127.0.0.1:19001" # Your Bitcoin node RPC endpoint +User = "your-rpc-user" # Your Bitcoin RPC username +Pass = "your-rpc-pass" # Your Bitcoin RPC password + +[chain] +Network = "signet" # Bitcoin network (signet for testnet) +``` -Finally, start the `btcstaker` daemon which will manage your connections to both -Babylon and Bitcoin nodes, monitor transactions, and handle the staking process: +### Babylon Configuration +```toml +[babylon] +Key = "btc-staker" # Your Babylon key name +ChainID = "bbn-test-5" # Babylon chain ID +RPCAddr = "http://localhost:26657" # Babylon RPC endpoint +GRPCAddr = "https://localhost:9090" # Babylon gRPC endpoint +AccountPrefix = "bbn" # Babylon address prefix +KeyringBackend = "test" # Keyring backend type +GasPrices = "0.01ubbn" # Minimum gas price +``` + +Finally, start the `btcstaker` daemon, which will manage your connections to both +Babylon and Bitcoin nodes, monitor transactions, and handle the staking process. +Add the location for the above created `config.json` file to the command: ```bash -stakercli admin start +stakerd --configfile admin start ``` -## 2. Transition your stake +## Transition your stake -After setting up the configuration file and starting the `btcstaker` daemon, -you can proceed to transition your stake from Phase-1 to Phase-2 using the -following command. We use the `global_parameters.json` file that you should +Following the setup of the configuration file and starting the `btcstaker` +daemon, you can proceed to transition your stake from Phase-1 to Phase-2 using +the following command. We use the `global_parameters.json` file that you should already have created as stated in the prerequisites. ```shell @@ -66,7 +102,6 @@ stakercli daemon stake-from-phase1 \ parameters: - `global-parameters-file`: The path to the global parameters file. - `your-phase1-tx-hash`: The original hash of your phase-1 staking transaction. -- `your-btc-address`: BTC address of the staker in hex +- `your-btc-address`: BTC address of the staker in hex. - `block-height`: The block height at which your staking transaction was - included. - + included. From fa8073a461758cbcffb8cfb4132ca7e3f75c1190 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Wed, 18 Dec 2024 17:20:35 +1100 Subject: [PATCH 03/10] Update transition-phase-2.md --- docs/transition-phase-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/transition-phase-2.md b/docs/transition-phase-2.md index 38f9a35..88f7df1 100644 --- a/docs/transition-phase-2.md +++ b/docs/transition-phase-2.md @@ -9,7 +9,7 @@ and this guide will show you how to do it through the `stakercli` binary. For detailed information about stake eligibility criteria, registration requirements, and how to gain voting power and earn rewards in phase-2, please refer to the -[phase-2 transition guide](https://gist.github.com/vitsalis/9ebfd19bbde310e0bf4a70e7ab15a290). +[Transition of Existing Stakes to the Babylon Chain](https://gist.github.com/vitsalis/9ebfd19bbde310e0bf4a70e7ab15a290). ## Table of Contents From 6d25cf181be58531fff2ed32d2b0625887b9ff6a Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Wed, 18 Dec 2024 17:35:26 +1100 Subject: [PATCH 04/10] Update transition-phase-2.md --- docs/transition-phase-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/transition-phase-2.md b/docs/transition-phase-2.md index 88f7df1..d3034d2 100644 --- a/docs/transition-phase-2.md +++ b/docs/transition-phase-2.md @@ -9,7 +9,7 @@ and this guide will show you how to do it through the `stakercli` binary. For detailed information about stake eligibility criteria, registration requirements, and how to gain voting power and earn rewards in phase-2, please refer to the -[Transition of Existing Stakes to the Babylon Chain](https://gist.github.com/vitsalis/9ebfd19bbde310e0bf4a70e7ab15a290). +[Transition of Existing Stakes to the Babylon Chain](https://github.com/babylonlabs-io/babylon/blob/main/docs/stake-registration.md). ## Table of Contents From d2ec9da1e3ec330508cc29d1509fa334bc07ccb1 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Wed, 18 Dec 2024 19:50:40 +1100 Subject: [PATCH 05/10] review comments --- docs/transition-phase-2.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/transition-phase-2.md b/docs/transition-phase-2.md index d3034d2..76477da 100644 --- a/docs/transition-phase-2.md +++ b/docs/transition-phase-2.md @@ -31,16 +31,15 @@ following: - Global parameter file as seen here https://github.com/babylonlabs-io/networks/blob/main/bbn-test-5/parameters/global-params.json that were used in phase-1. This will be used in the transition command later on. -- A running instance of the `stakercli` binary. Please follow the `stakercli` - [setup guide](../README.md#3-btc-staker-installation) to complete the setup of - the `stakercli` with your keys before proceeding. +- A running instance of the `stakerd` daemon. Please follow the `stakerd` + [setup guide](../README.md#3-btc-staker-installation) to complete the setup. + This is also inclusive of creating a Babylon keyring with funds step as the + `stakerd` daemon requires a funded keyring to pay for the transactions. ## Setup First, you will need to dump the default configuration file. This creates a -template configuration file that you'll customize with your specific values -(like your Bitcoin block height that your staking transaction was included in, -wallet credentials, and network details): +template configuration file that you'll customize with your specific values: ```bash stakercli admin dump-config @@ -68,10 +67,10 @@ Network = "signet" # Bitcoin network (signet for testnet) ### Babylon Configuration ```toml [babylon] -Key = "btc-staker" # Your Babylon key name +Key = "btc-staker" # Your Babylon key name created in the btc-staker-installation ChainID = "bbn-test-5" # Babylon chain ID RPCAddr = "http://localhost:26657" # Babylon RPC endpoint -GRPCAddr = "https://localhost:9090" # Babylon gRPC endpoint +GRPCAddr = "http://localhost:9090" # Babylon gRPC endpoint AccountPrefix = "bbn" # Babylon address prefix KeyringBackend = "test" # Keyring backend type GasPrices = "0.01ubbn" # Minimum gas price From 284e1a0324daec1142acce9413286d2594e03ba3 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Wed, 18 Dec 2024 20:40:38 +1100 Subject: [PATCH 06/10] reviewal comments --- ...n-phase-2.md => register-phase-1-stake.md} | 36 +++++++++---------- 1 file changed, 17 insertions(+), 19 deletions(-) rename docs/{transition-phase-2.md => register-phase-1-stake.md} (74%) diff --git a/docs/transition-phase-2.md b/docs/register-phase-1-stake.md similarity index 74% rename from docs/transition-phase-2.md rename to docs/register-phase-1-stake.md index 76477da..da4e266 100644 --- a/docs/transition-phase-2.md +++ b/docs/register-phase-1-stake.md @@ -1,35 +1,33 @@ -# Transition your stake from phase-1 to phase-2 through CLI +# Register your Phase-1 stake to Phase-2 through CLI -## Understanding the transition +## Understanding the registration process -The transition from phase-1 to phase-2 is a manual process that requires the -staker to transition their stake to phase-2 of the Babylon network. -This transition has the option of being executed through the `stakercli` binary +The registration of Phase-1 stakes to Phase-2 is a manual process that requires +the staker to register their stake to Phase-2 of the Babylon network. +This registration is executed through the `stakercli` binary and this guide will show you how to do it through the `stakercli` binary. For -detailed information about stake eligibility -criteria, registration requirements, and how to gain voting power and earn -rewards in phase-2, please refer to the -[Transition of Existing Stakes to the Babylon Chain](https://github.com/babylonlabs-io/babylon/blob/main/docs/stake-registration.md). - +detailed information about stake eligibility criteria, registration requirements, +and how to gain voting power and earn rewards in phase-2, please refer to the +[Registration of Existing Stakes to the Babylon Chain](https://github.com/babylonlabs-io/babylon/blob/main/docs/stake-registration.md). ## Table of Contents - [Prerequisites](#prerequisites) - [Setup](#setup) -- [Transition your stake](#transition-your-stake) -- [Verify the transition](#verify-the-transition) +- [Register your stake](#register-your-stake) +- [Verify the registration](#verify-the-registration) ## Prerequisites -To transition your stake from phase-1 to phase-2, you need to have the +To register your stake to Phase-2, you need to have the following: -- Access to your existing Bitcoin wallet from phase-1 (needed to sign transactions +- Access to your existing Bitcoin wallet from Phase-1 (needed to sign transactions and prove ownership of staked funds). - The Bitcoin block height in which your staking transaction was included, which - will be used in the transition command. + will be used in the registration command. - A funded Babylon address, which will be used to receive the rewards from the - transition. + registration. - Global parameter file as seen here https://github.com/babylonlabs-io/networks/blob/main/bbn-test-5/parameters/global-params.json - that were used in phase-1. This will be used in the transition command later + that were used in Phase-1. This will be used in the registration command later on. - A running instance of the `stakerd` daemon. Please follow the `stakerd` [setup guide](../README.md#3-btc-staker-installation) to complete the setup. @@ -84,10 +82,10 @@ Add the location for the above created `config.json` file to the command: stakerd --configfile admin start ``` -## Transition your stake +## Register your stake Following the setup of the configuration file and starting the `btcstaker` -daemon, you can proceed to transition your stake from Phase-1 to Phase-2 using +daemon, you can proceed to register your stake from Phase-1 to Phase-2 using the following command. We use the `global_parameters.json` file that you should already have created as stated in the prerequisites. From e231416c7634f14e4edf2dccc5ac1c37b3507c5d Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Fri, 20 Dec 2024 01:40:58 +1100 Subject: [PATCH 07/10] Update register-phase-1-stake.md --- docs/register-phase-1-stake.md | 137 ++++++++++++++++++++++----------- 1 file changed, 93 insertions(+), 44 deletions(-) diff --git a/docs/register-phase-1-stake.md b/docs/register-phase-1-stake.md index da4e266..cee224b 100644 --- a/docs/register-phase-1-stake.md +++ b/docs/register-phase-1-stake.md @@ -2,13 +2,11 @@ ## Understanding the registration process -The registration of Phase-1 stakes to Phase-2 is a manual process that requires -the staker to register their stake to Phase-2 of the Babylon network. -This registration is executed through the `stakercli` binary -and this guide will show you how to do it through the `stakercli` binary. For -detailed information about stake eligibility criteria, registration requirements, -and how to gain voting power and earn rewards in phase-2, please refer to the -[Registration of Existing Stakes to the Babylon Chain](https://github.com/babylonlabs-io/babylon/blob/main/docs/stake-registration.md). +To register your Bitcoin stake on the Babylon chain, you must have a confirmed +Bitcoin staking transaction. Before proceeding, please review the +[Registration of Existing Stakes to the Babylon Chain](https://github.com/babylonlabs-io/babylon/blob/main/docs/stake-registration.md) +documentation to check your eligibility and understand the registration +requirements and process. ## Table of Contents - [Prerequisites](#prerequisites) @@ -18,76 +16,84 @@ and how to gain voting power and earn rewards in phase-2, please refer to the ## Prerequisites -To register your stake to Phase-2, you need to have the -following: -- Access to your existing Bitcoin wallet from Phase-1 (needed to sign transactions - and prove ownership of staked funds). +To register your stake to the Babylon blockchain, the following are required: +- Access to the Bitcoin wallet you have used to create your stake on Bitcoin + (needed to sign transactions). - The Bitcoin block height in which your staking transaction was included, which will be used in the registration command. - A funded Babylon address, which will be used to receive the rewards from the registration. - Global parameter file as seen here https://github.com/babylonlabs-io/networks/blob/main/bbn-test-5/parameters/global-params.json - that were used in Phase-1. This will be used in the registration command later - on. + that were used when you created your Bitcoin stake. This will be used in the + registration command later on. - A running instance of the `stakerd` daemon. Please follow the `stakerd` [setup guide](../README.md#3-btc-staker-installation) to complete the setup. This is also inclusive of creating a Babylon keyring with funds step as the `stakerd` daemon requires a funded keyring to pay for the transactions. -## Setup +## Setup and configuration -First, you will need to dump the default configuration file. This creates a -template configuration file that you'll customize with your specific values: +> **⚡ Note**: While the `stakerd` daemon is already running, it needs access to +> the Bitcoin wallet containing your staking transaction's private key. This +> setup ensures the daemon can interact with the correct Bitcoin wallet. + +To get started, you will need to create a configuration file. You can do this +by running the `dump-config` command. This will create a `config.json` file +in your current working directory that you'll customize with your specific +values: ```bash stakercli admin dump-config ``` -This will create a `config.json` file in your current working directory. -You'll need to modify this file with your specific settings before proceeding. -Here are the key configurations: +The configuration file below contains default settings and placeholders +for your Bitcoin and Babylon values. Please replace the placeholders with +your specific information: -### Bitcoin Configuration ```toml [walletconfig] -WalletName = "btc-staker" # Your Bitcoin wallet name -WalletPass = "your-wallet-password" # Your wallet password +WalletName = "btc-staker" # Replace with your Bitcoin wallet name +WalletPass = "your-wallet-password" # Replace with your wallet password [walletrpcconfig] -Host = "127.0.0.1:19001" # Your Bitcoin node RPC endpoint -User = "your-rpc-user" # Your Bitcoin RPC username -Pass = "your-rpc-pass" # Your Bitcoin RPC password +Host = "127.0.0.1:19001" # Bitcoin Wallet RPC endpoint +User = "your-rpc-user" # Replace with your Bitcoin RPC username +Pass = "your-rpc-pass" # Replace with your Bitcoin RPC password [chain] Network = "signet" # Bitcoin network (signet for testnet) ``` -### Babylon Configuration -```toml -[babylon] -Key = "btc-staker" # Your Babylon key name created in the btc-staker-installation -ChainID = "bbn-test-5" # Babylon chain ID -RPCAddr = "http://localhost:26657" # Babylon RPC endpoint -GRPCAddr = "http://localhost:9090" # Babylon gRPC endpoint -AccountPrefix = "bbn" # Babylon address prefix -KeyringBackend = "test" # Keyring backend type -GasPrices = "0.01ubbn" # Minimum gas price -``` - Finally, start the `btcstaker` daemon, which will manage your connections to both Babylon and Bitcoin nodes, monitor transactions, and handle the staking process. Add the location for the above created `config.json` file to the command: -```bash +```shell stakerd --configfile admin start ``` ## Register your stake -Following the setup of the configuration file and starting the `btcstaker` -daemon, you can proceed to register your stake from Phase-1 to Phase-2 using -the following command. We use the `global_parameters.json` file that you should -already have created as stated in the prerequisites. +After configuring and starting the `btcstaker` daemon, you'll need the +`global_parameters.json` file (created during prerequisites) for the next steps. + +A few notes about the `global-parameters.json` file: +1. It is used to retrieve covenant keys and quorum from the parameters version + you staked in. +2. It can also be used to parse your Bitcoin staking transaction to extract + important information from the `OP_RETURN` data, which contains: + - The staking period you chose + - The finality provider you chose + +> **⚡ Note**: While these parameters can be provided manually, the global +> parameters file provides an easier user experience. This guide is only for +> valid, confirmed Bitcoin staking transactions with valid `OP_RETURN` data. If +> your transaction has malformed `OP_RETURN` data or isn't a confirmed staking +> transaction, to check your eligibility please refer to the +> [registration eligibility guide](registration-eligibility.md). + +Now that you have the `global-parameters.json` file, you can register your +Bitcoin stake by running the following command: ```shell stakercli daemon stake-from-phase1 \ @@ -98,7 +104,50 @@ stakercli daemon stake-from-phase1 \ parameters: - `global-parameters-file`: The path to the global parameters file. -- `your-phase1-tx-hash`: The original hash of your phase-1 staking transaction. +- `your-phase1-tx-hash`: The original hash of your Bitcoin staking transaction. - `your-btc-address`: BTC address of the staker in hex. -- `block-height`: The block height at which your staking transaction was +- `block-height`: The BTC block height at which your staking transaction was included. + +The above command will output a transaction hash similar to below +that you can use to verify the registration on the Babylon blockchain, which +you will see in the next section. + +```json +{ + "babylon_btc_delegation_tx_hash": "" +} +``` + +## Verify your registration + +Following the registration of your Bitcoin stake, you can verify your +registration by checking your balance on the [Babylon Explorer](https://babylon-testnet.l2scan.co) +by searching for the `` value. + +This will then give you details on your transaction, which includes the state +of the transaction, which can be one of the following: + +- `SENT_TO_BTC` - Initial state +- `CONFIRMED_ON_BTC` - Bitcoin confirmation +- `SENT_TO_BABYLON` - Registration submitted to Babylon +- `VERIFIED` - Registration verified +- `DELEGATION_ACTIVE` - Stake active and has voting power +- `UNBONDING_CONFIRMED_ON_BTC` - Unbonding in progress +- `SPENT_ON_BTC` - Stake withdrawn + +Depending on the state of the transaction, you can see the progress of the +registration on the Babylon blockchain, as it will take a few minutes for the +transaction to be verified and the stake to be active. + +## Receiving rewards + +Following registration, rewards will be accrued to your Babylon address +(configured in `stakerd`). + +> **⚠️ Important**: While rewards are accumulating to your Babylon address, +> withdrawals are not yet available. You will be able to access your rewards +> once the claiming feature is implemented. + +To monitor your rewards, you can use the [Babylon Explorer](https://babylon-testnet.l2scan.co) +to check your balance on the Babylon blockchain using your Babylon address. From e63314a978aa08efaa335761b069faecba2100a8 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Fri, 20 Dec 2024 01:45:37 +1100 Subject: [PATCH 08/10] Update register-phase-1-stake.md --- docs/register-phase-1-stake.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/register-phase-1-stake.md b/docs/register-phase-1-stake.md index cee224b..6b0331d 100644 --- a/docs/register-phase-1-stake.md +++ b/docs/register-phase-1-stake.md @@ -10,9 +10,10 @@ requirements and process. ## Table of Contents - [Prerequisites](#prerequisites) -- [Setup](#setup) +- [Setup and configuration](#setup-and-configuration) - [Register your stake](#register-your-stake) -- [Verify the registration](#verify-the-registration) +- [Verify your registration](#verify-your-registration) +- [Receiving rewards](#receiving-rewards) ## Prerequisites @@ -102,7 +103,7 @@ stakercli daemon stake-from-phase1 \ --tx-inclusion-height ``` -parameters: +Parameters: - `global-parameters-file`: The path to the global parameters file. - `your-phase1-tx-hash`: The original hash of your Bitcoin staking transaction. - `your-btc-address`: BTC address of the staker in hex. @@ -110,7 +111,7 @@ parameters: included. The above command will output a transaction hash similar to below -that you can use to verify the registration on the Babylon blockchain, which +that you can use to verify the registration on the Babylon blockchain, which you will see in the next section. ```json From fc12f7ae0709e3fd7f9e137e7b14b0980de7a6f0 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Sun, 22 Dec 2024 17:09:15 +1100 Subject: [PATCH 09/10] Update register-phase-1-stake.md --- docs/register-phase-1-stake.md | 107 +++++++++++---------------------- 1 file changed, 34 insertions(+), 73 deletions(-) diff --git a/docs/register-phase-1-stake.md b/docs/register-phase-1-stake.md index 6b0331d..e963b25 100644 --- a/docs/register-phase-1-stake.md +++ b/docs/register-phase-1-stake.md @@ -17,65 +17,34 @@ requirements and process. ## Prerequisites -To register your stake to the Babylon blockchain, the following are required: -- Access to the Bitcoin wallet you have used to create your stake on Bitcoin - (needed to sign transactions). -- The Bitcoin block height in which your staking transaction was included, which - will be used in the registration command. -- A funded Babylon address, which will be used to receive the rewards from the - registration. -- Global parameter file as seen here https://github.com/babylonlabs-io/networks/blob/main/bbn-test-5/parameters/global-params.json - that were used when you created your Bitcoin stake. This will be used in the - registration command later on. -- A running instance of the `stakerd` daemon. Please follow the `stakerd` - [setup guide](../README.md#3-btc-staker-installation) to complete the setup. - This is also inclusive of creating a Babylon keyring with funds step as the - `stakerd` daemon requires a funded keyring to pay for the transactions. - -## Setup and configuration - -> **⚡ Note**: While the `stakerd` daemon is already running, it needs access to -> the Bitcoin wallet containing your staking transaction's private key. This -> setup ensures the daemon can interact with the correct Bitcoin wallet. - -To get started, you will need to create a configuration file. You can do this -by running the `dump-config` command. This will create a `config.json` file -in your current working directory that you'll customize with your specific -values: - -```bash -stakercli admin dump-config -``` - -The configuration file below contains default settings and placeholders -for your Bitcoin and Babylon values. Please replace the placeholders with -your specific information: - -```toml -[walletconfig] -WalletName = "btc-staker" # Replace with your Bitcoin wallet name -WalletPass = "your-wallet-password" # Replace with your wallet password - -[walletrpcconfig] -Host = "127.0.0.1:19001" # Bitcoin Wallet RPC endpoint -User = "your-rpc-user" # Replace with your Bitcoin RPC username -Pass = "your-rpc-pass" # Replace with your Bitcoin RPC password - -[chain] -Network = "signet" # Bitcoin network (signet for testnet) -``` - -Finally, start the `btcstaker` daemon, which will manage your connections to both -Babylon and Bitcoin nodes, monitor transactions, and handle the staking process. -Add the location for the above created `config.json` file to the command: - -```shell -stakerd --configfile admin start -``` +- **Staker Daemon**: A running instance of the `stakerd` daemon. + - **Bitcoin Wallet**: The `stakerd` daemon should connect and have access to + the Bitcoin wallet that you have previously used to create your Bitcoin + stake. This will be needed to create a proof of ownership of the stake. + - **Funded Babylon Account**: The `stakerd` daemon should have access to a + funded Babylon account. This account will pay for transaction fees for + the interaction with the Babylon blockchain, as well as be used as the + recipient for BTC staking rewards in the respective native PoS token + (note: testnet tokens have no value). + - **Setup Guide**: The `stakerd` + [setup guide](../README.md#3-btc-staker-installation) contains all details + on how to set up the `stakerd` and connect it with your Bitcoin wallet + and Babylon account. +- **Phase-1 Parameters**: The staker CLI requires the parameters that were used + when creating the phase-1 staking transaction in order to construct a valid + Babylon chain registration transaction. + Specifically, it requires the following: + - **Global Parameter Versions**: The global parameters file containing the full + parameters versions for the phase-1 network you submitted your stake in + (e.g.,[testnet parameters](https://github.com/babylonlabs-io/networks/blob/main/bbn-test-4/parameters/global-params.json)). + - **Bitcoin Inclusion Height**: The Bitcoin block height in which your staking + transaction was included, which will be used in the registration command. + You can find this through Bitcoin explorer tools such as + [mempool.space](https://mempool.space). ## Register your stake -After configuring and starting the `btcstaker` daemon, you'll need the +After configuring and starting the `stakerd` daemon, you'll need the `global_parameters.json` file (created during prerequisites) for the next steps. A few notes about the `global-parameters.json` file: @@ -87,10 +56,13 @@ A few notes about the `global-parameters.json` file: - The finality provider you chose > **⚡ Note**: While these parameters can be provided manually, the global -> parameters file provides an easier user experience. This guide is only for -> valid, confirmed Bitcoin staking transactions with valid `OP_RETURN` data. If +> parameters file provides a smoother user experience. This guide is only for +> valid Bitcoin staking transactions with well-formed `OP_RETURN` data that +> have received sufficient Bitcoin confirmations (e.g., 10 for testnet). If > your transaction has malformed `OP_RETURN` data or isn't a confirmed staking -> transaction, to check your eligibility please refer to the +> transaction (because it is a new one or very recently submitted), it cannot be +> registered. +> To check your eligibility please refer to the > [registration eligibility guide](registration-eligibility.md). Now that you have the `global-parameters.json` file, you can register your @@ -106,6 +78,7 @@ stakercli daemon stake-from-phase1 \ Parameters: - `global-parameters-file`: The path to the global parameters file. - `your-phase1-tx-hash`: The original hash of your Bitcoin staking transaction. + This will be used to retrieve the staking transaction from your wallet. - `your-btc-address`: BTC address of the staker in hex. - `block-height`: The BTC block height at which your staking transaction was included. @@ -126,8 +99,8 @@ Following the registration of your Bitcoin stake, you can verify your registration by checking your balance on the [Babylon Explorer](https://babylon-testnet.l2scan.co) by searching for the `` value. -This will then give you details on your transaction, which includes the state -of the transaction, which can be one of the following: +The below states relate to the statuses maintained by stakerd. Above you refer +to going to the Babylon explorer. Something is missing here I think. In general, I recommend that we check the status of the transaction by stakerd/stakercli commands instead of sending people to a 3rd party explorer. - `SENT_TO_BTC` - Initial state - `CONFIRMED_ON_BTC` - Bitcoin confirmation @@ -140,15 +113,3 @@ of the transaction, which can be one of the following: Depending on the state of the transaction, you can see the progress of the registration on the Babylon blockchain, as it will take a few minutes for the transaction to be verified and the stake to be active. - -## Receiving rewards - -Following registration, rewards will be accrued to your Babylon address -(configured in `stakerd`). - -> **⚠️ Important**: While rewards are accumulating to your Babylon address, -> withdrawals are not yet available. You will be able to access your rewards -> once the claiming feature is implemented. - -To monitor your rewards, you can use the [Babylon Explorer](https://babylon-testnet.l2scan.co) -to check your balance on the Babylon blockchain using your Babylon address. From 8c98b8385c4ea0c0b8d0ced43fbcd2e0f182d3e8 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Sun, 22 Dec 2024 23:29:16 +1100 Subject: [PATCH 10/10] Update register-phase-1-stake.md --- docs/register-phase-1-stake.md | 70 ++++++++++++++++++++++++++-------- 1 file changed, 55 insertions(+), 15 deletions(-) diff --git a/docs/register-phase-1-stake.md b/docs/register-phase-1-stake.md index e963b25..b5f7d7d 100644 --- a/docs/register-phase-1-stake.md +++ b/docs/register-phase-1-stake.md @@ -93,23 +93,63 @@ you will see in the next section. } ``` -## Verify your registration +## Verify Your Registration -Following the registration of your Bitcoin stake, you can verify your -registration by checking your balance on the [Babylon Explorer](https://babylon-testnet.l2scan.co) -by searching for the `` value. +After submitting your stake registration with `stake-from-phase1`, you can +verify your registration with either of the following methods: -The below states relate to the statuses maintained by stakerd. Above you refer -to going to the Babylon explorer. Something is missing here I think. In general, I recommend that we check the status of the transaction by stakerd/stakercli commands instead of sending people to a 3rd party explorer. +1. Check your stake's local tracking status in `stakerd`: -- `SENT_TO_BTC` - Initial state -- `CONFIRMED_ON_BTC` - Bitcoin confirmation -- `SENT_TO_BABYLON` - Registration submitted to Babylon -- `VERIFIED` - Registration verified -- `DELEGATION_ACTIVE` - Stake active and has voting power +```shell +# View all stakes being tracked: +stakercli daemon list-staking-transactions + +# Or check a specific transaction: +stakercli daemon staking-details --staking-transaction-hash +``` + +The response will show an output similar to below: + +```json +{ + "staking_tx_hash": "", + "staker_address": "", + "staking_state": "SENT_TO_BABYLON", + "watched": true, + "transaction_idx": "1" +} +``` +As you can see, the `staking_state` field will show the current state of your +stake registration. Your stake will progress through these states: + +- `SENT_TO_BTC` - Initial state when transaction is created +- `CONFIRMED_ON_BTC` - Bitcoin network has confirmed the transaction +- `SENT_TO_BABYLON` - Registration submitted to Babylon chain +- `VERIFIED` - Covenant signatures received +- `DELEGATION_ACTIVE` - Stake is active with voting power - `UNBONDING_CONFIRMED_ON_BTC` - Unbonding in progress -- `SPENT_ON_BTC` - Stake withdrawn +- `SPENT_ON_BTC` - Stake has been withdrawn + +Once your staking state reaches `DELEGATION_ACTIVE`, your stake is active and +participating in the network. + +If you wish to check your registration on the Babylon chain, you can then +verify your registration with the next step. + +2. Babylon Chain Status: + +While `stakerd` tracks your registration locally, the final validation happens +on the Babylon chain. When `stakerd` shows `SENT_TO_BABYLON`, your transaction +needs covenant signatures from the Babylon validators to become active. +You can verify this process using the transaction hash from your +registration: + +```shell +# From your stake-from-phase1 response: +{ + "babylon_btc_delegation_tx_hash": "" +} -Depending on the state of the transaction, you can see the progress of the -registration on the Babylon blockchain, as it will take a few minutes for the -transaction to be verified and the stake to be active. +# View on Babylon Explorer: +https://babylon-testnet.l2scan.co/tx/ +``` \ No newline at end of file