more text

Author: vitsalis

docs/register-bitcoin-stake.md

@@ -2,18 +2,21 @@
 ## Table of contents
 1. [Introduction](#1-introduction)
 2. [Stake registration on the Babylon chain](#2-stake-registration-on-the-babylon-chain)
-    1. [Post-Staking Registration Flow](#21-post-staking-registration-flow)
-    2. [Pre-Staking Registration Flow](#22-pre-staking-registration-flow)
+   1. [Post-Staking Registration Flow](#21-post-staking-registration-flow)
+   2. [Pre-Staking Registration Flow](#22-pre-staking-registration-flow)
 3. [Stake Submission](#3-stake-submission)
-    1. [Overview of Data that needs to be Submitted](#31-overview-of-data-that-needs-to-be-submitted)
-    2. [Babylon Chain BTC Staking Parameters](#32-babylon-chain-btc-staking-parameters)
-    3. [Creating the Bitcoin transactions](#33-creating-the-bitcoin-transactions)
-    4. [The `MsgCreateBTCDelegation` Babylon message](#34-the-msgcreatebtcdelegation-babylon-message)
+   1. [Overview of Data that needs to be Submitted](#31-overview-of-data-that-needs-to-be-submitted)
+   2. [Babylon Chain BTC Staking Parameters](#32-babylon-chain-btc-staking-parameters)
+   3. [Creating the Bitcoin transactions](#33-creating-the-bitcoin-transactions)
+   4. [The `MsgCreateBTCDelegation` Babylon message](#34-the-msgcreatebtcdelegation-babylon-message)
 4. [Stake Registration Flows](#4-stake-registration-flows)
+   1. [Post-Staking Registration](#41-post-staking-registration)
+   2. [Pre-Staking Registration](#42-pre-staking-registration)
+   3. [Technical Resources for Babylon Broadcasting](#43-technical-resources-for-babylon-broadcasting)
 5. [Managing your Stake](#5-managing-your-stake)
-    1. [On-demand unbonding](#51-on-demand-unbonding)
-    2. [Withdrawing Expired/Unbonded BTC Stake](#52-withdrawing-expiredunbonded-btc-stake)
-    3. [Withdrawing Remaining Funds after Slashing](#53-withdrawing-remaining-funds-after-slashing)
+   1. [On-demand unbonding](#51-on-demand-unbonding)
+   2. [Withdrawing Expired/Unbonded BTC Stake](#52-withdrawing-expiredunbonded-btc-stake)
+   3. [Withdrawing Remaining Funds after Slashing](#53-withdrawing-remaining-funds-after-slashing)
 6. [Bitcoin Staking Rewards](#6-bitcoin-staking-rewards)
 
 ## 1. Introduction
@@ -137,18 +140,23 @@ The following sections cover:
 
 ### 3.2. Babylon Chain BTC Staking Parameters
 
-<!-- yes! yup there is separate param for this https://github.com/babylonlabs-io/babylon/blob/main/proto/babylon/btcstaking/v1/params.proto#L64. btc_activation_height describe from which btc block given parameters start i.e if your staking transaction is included in block 10, and there are two sets of parameters one with btc_activation_height=1  and the second with btc_activation_height=30 , all the delegation data must be valid against first set of parmeters. -->
-
 BTC Staking transactions need to abide by the parameters specified by the Babylon
-Babylon chain for BTC Staking transaction validity. These parameters are Bitcoin
-height-specific, meaning they are valid starting from a specific Bitcoin block 
-height, known as `btc_activation_height`. If your staking transaction is included
-in a Bitcoin block, it must comply with the set of parameters active at that 
-block's height.
+chain for BTC Staking transaction validity. These parameters are Bitcoin height-specific,
+meaning that staking transactions included in different Bitcoin block heights
+might correspond to different Bitcoin staking validity rules.
+The parameters and the Bitcoin block heights they apply to are defined as follows:
+* Each parameters version specifies a Bitcoin block height from which it starts applying
+  known as the `btc_activation_height`.
+* In order to find out which parameters version a Bitcoin transaction should adhere to,
+  you take all the parameters versions and sort them in an ascending manner through the
+  `btc_activation_height`.
+* The first parameters version that has `btc_activation_height > lookup_btc_height` is the
+  staking parameters version for the `lookup_btc_height` Bitcoin height.
 
 Below, we provide
 a brief overview of the parameters employed by the Babylon chain
-as part of the [x/btcstaking](../x/btcstaking) Cosmos SDK module:
+as part of the [x/btcstaking](../x/btcstaking) Cosmos SDK module.
+We will focus on the values defined in each parameters version:
 
 * `covenant_pks`:
   A list containing the BIP-340 public keys used by the covenant committee.
@@ -180,11 +188,25 @@ as part of the [x/btcstaking](../x/btcstaking) Cosmos SDK module:
 * `min_slashing_tx_fee_sat`:
   The minimum transaction fee (in satoshis) required for the pre-signed slashing
   transaction. Represented in int64 format.
+* `slashing_rate`: A scalar that defines what's the portion of the stake
+  that will be slashed in the case of the finality provider double-signing.
 * `unbonding_time_blocks`:
   The required time lock on unbonding transactions (and change output of
   slashing transactions).
 * `unbonding_fee_sat`:
   The fee required for unbonding transactions.
+* `min_commission_rate`: A scalar defining the minimum commission rate
+  for finality providers.
+* `delegation_creation_base_gas_fee`: A uint64 defining the minimum
+  gas fee to be paid when registering a stake through the pre-staking
+  registration flow.
+* `allow_list_expiration_height`: The Babylon block height (as a uint64)
+  on which the initial staking transaction allow-list expires.
+* `btc_activation_height`: The Bitcoin block height on which this version of
+  parameters takes into effect.
+
+<!--- TODO 2: troubleshooting for btc activation -->
+<!--- TODO 3: note about finality not being activated -->
 
 **How to Retrieve Parameters**
 
@@ -454,6 +476,10 @@ message to the Babylon network:
 * Creation using Golang based on this [type reference](../x/btcstaking/types/tx.pb.go)
   and broadcast to the Babylon network.
 
+> **Important**: When submitting a staking transaction using the
+> pre-registration staking flow a special gas fee should be applied.
+> More details on this in the following section.
+
 ## 4. Stake Registration Flows
 
 Having defined the construction of Bitcoin staking transactions and their
@@ -530,7 +556,31 @@ has been launched.
 > by the [btccheckpoint](../x/btccheckpoint) module's parameters.
 8. After receiving the proof of inclusion, the stake is designated as `ACTIVE`. 
 
-**Technical Resources for Babylon Broadcasting**
+**Important: Gas requirements for the pre-staking registration flow**:
+Given that the pre-staking registration flow does not have the requirement
+that the staker has already committed funds to the Bitcoin network,
+it could serve as a chain spamming vector, especially given that it
+leads to the submission of multiple covenant emulator signatures.
+To combat this, the submission of a `MsgCreateBTCDelegation` message
+using the pre-staking registration flow requires a minimum gas amount
+specified by the `delegation_creation_base_gas_fee` attribute of the
+Babylon parameters.
+
+**Important: Which Bitcoin Staking parameters to use**: Given that the staking
+parameters are Bitcoin block height specific and the fact that the
+pre-staking registration flow requires the staker to first submit their
+transaction to Babylon and then to Bitcoin, a concern might arise that
+the Bitcoin block height at the time of Babylon submission might correspond
+to different parameters than the Bitcoin block height at the time of
+Bitcoin inclusion. To combat this, the Babylon chain expects
+that the staking transaction will use the Bitcoin staking parameters
+defined for the Bitcoin height of the tip of the **on-chain Bitcoin light client**
+of the Babylon chain at the time of the pre-staking registration submission.
+The tip height of the on-chain Bitcoin light client can be retrieved as follows:
+* LCD/RPC: through the `/babylon/btclightclient/v1/tip` query endpoint
+* CLI: through the `babylond query btclightclient tip` query
+
+### 4.3. Technical Resources for Babylon Broadcasting
 
 To broadcast your Babylon transactions, you will need access to a node and can use
 various methods: