From f7d8194cabe8ced5fb0cd58ff2248df2d8d501d0 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Sat, 18 Jan 2025 19:37:27 +1100 Subject: [PATCH] Update register-create-stake-phase-2.md --- docs/register-create-stake-phase-2.md | 190 +++++++++++++------------- 1 file changed, 96 insertions(+), 94 deletions(-) diff --git a/docs/register-create-stake-phase-2.md b/docs/register-create-stake-phase-2.md index 41b6decb..cb49b880 100644 --- a/docs/register-create-stake-phase-2.md +++ b/docs/register-create-stake-phase-2.md @@ -10,20 +10,18 @@ ## Introduction - + This documentation guides you through the structures that need to be communicated to the Babylon chain in order to register a Phase-1 stake or -create a new one. +create new stake. We are going to start with the Babylon structures associated with BTC staking -and how to construct them. +and how to generate and construct them. Then we are going to explore different use cases utilising the different structures. - - vitalis note: maybe we can start with the use cases and put the structures - at the bottom ## Babylon messages @@ -94,22 +92,17 @@ to construct them. ### Staking Transaction -A staking transaction is a Bitcoin transaction that locks funds in a special -staking output. The main entry point for creating a staking transaction is -the `StakeFunds` function: +In the staker program, a staking transaction is created as a Bitcoin transaction +that locks funds into a specific staking output. This transaction is +identified by its hash. -```go -func (app *App) StakeFunds( - stakerAddress btcutil.Address, // Address of the staker - stakingAmount btcutil.Amount, // Amount to stake - fpPks []*btcec.PublicKey, // Finality provider public keys - stakingTimeBlocks uint16, // How long to stake for - sendToBabylonFirst bool, // Pre/post approval flow -) (*chainhash.Hash, error) -``` +For the `MsgCreateBTCDelegation` message, you must include the staking +transaction hash. This hash is used by the Babylon chain to verify +the transaction and ensure the funds are correctly locked for staking. + +To generate this hash you will need to do the following: -To generate a staking transaction, you first need to build the staking information -using `BuildStakingInfo`: +1. Build the staking hash using `BuildStakingInfo`: ```go stakingInfo, err := staking.BuildStakingInfo( @@ -124,8 +117,9 @@ stakingInfo, err := staking.BuildStakingInfo( ``` This staking information is used to create a Bitcoin transaction with a special -output script that enforces the staking rules. The transaction is then created -using: +output script that enforces the staking rules. + +2. The transaction is then created using: ```go stakingTx, err := app.wc.CreateTransaction( @@ -141,6 +135,8 @@ hash is returned. This hash (*chainhash.Hash) uniquely identifies the staking transaction and can be used to track its status or reference it in future transactions like unbonding. +The `MsgCreateBTCDelegation` message requires the staking transaction hash. + ### Unbonding Transaction An unbonding transaction is a process initiated by a BTC staker to unlock and @@ -149,10 +145,11 @@ It allows the staker to regain access to their locked funds earlier than planned #### Creating an Unbonding Transaction -To create an unbonding transaction, you will need to create the unbonding +An unbonding transaction, again is generated in the staker program. +To create an unbonding transaction, you will need to generate the unbonding transaction using `createUndelegationData` function. You can find the function -in the [btc-staker/types.go](https://github.com/babylonchain/babylon/blob/main/btc-staker/types.go#L341) -file. The function returns an `UnbondingSlashingDesc` containing: +in the [btc-staker/types.go](https://github.com/babylonchain/babylon/blob/main/btc-staker/types.go#L341) file. The function returns an `UnbondingSlashingDesc` containing: + - The unbonding transaction - The unbonding value - The timelock period @@ -164,8 +161,7 @@ Babylon chain through a `MsgBTCUndelegate` message. The transaction will be monitored by the BTC staking tracker and requires covenant signatures before it can be executed on the Bitcoin network. -This will be what you can use `MsgCreateBTCDelegation` for registering phase-2 -stakes. +The `MsgCreateBTCDelegation` message requires the unbonding transaction hash. ## Slashing Transactions @@ -174,22 +170,37 @@ rules or the finality provider they have delegated to. These transactions ensure that malicious behavior can be penalized by taking a portion of the staker's funds according to the slashing rate. -The slashing transaction is initially created through the -`slashingTxForStakingTx` function for the staking period, and then automatically -generated through the `createUndelegationData` function when creating an -unbonding transaction. These functions ensure the staker can be slashed during -both the staking and unbonding periods. The generated transactions are included -in the `MsgCreateBTCDelegation` message and require both staker and covenant -signatures to be executed. +The slashing transactions are created in the staker program in the following +ways: + +**During creation:** +- The `slashingTxForStakingTx` function is used to create a slashing transaction + for the staking period. This transaction is prepared to be executed if the + staker violates the rules during the staking period. + +**During staking:** +- The `slashingTxForStakingTx` function is used to create a slashing +transaction for the staking period. This transaction is prepared to be executed +if the staker violates the rules during the staking period. + +**During unbonding:** +- The `createUndelegationData` function generates slashing transactions when +creating an unbonding transaction. This ensures that the staker can be +penalized during the unbonding period as well. + +The slashing transaction hash can be obtained from the transaction object +created by `slashingTxForStakingTx` or `createUndelegationData`. + +The `MsgCreateBTCDelegation` message requires the slashing transaction hash. To see more information on how to generate the slashing transaction, see the -[staker/types.go](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/types.go#L111) file. +[staker/types.go](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/types.go#L111) +file. ## Slashing Signatures -The slashing signatures are generated by the BTC staker and are used to sign -the slashing transaction. The signatures are generated by the BTC staker and -are used to sign the slashing transaction. +The signatures are generated by the BTC staker and are used to sign the +slashing transaction. The slashing signatures are generated by the BTC staker and are used to sign the slashing transaction. These signatures are generated during @@ -204,19 +215,24 @@ quorum of covenant members, is required to execute any slashing transaction. The signatures are verified using `VerifyTransactionSigWithOutput` to ensure they're valid before being stored with the delegation data. +1. Create transaction structure ```go -// 1. Create transaction structure slashingTx, spendInfo, err := slashingTxForStakingTx(...) +``` -// 2. Generate signatures (done separately) +2. Generate signatures (done separately) +```go signature, err := SignTxWithOneScriptSpendInputFromScript( slashingTx, // transaction to sign fundingOutput, // output being spent privateKey, // private key for signing spendInfo.RevealedLeaf.Script, // script being satisfied ) +``` -// 3. Verify signatures +3. Verify signatures + +```go err = VerifyTransactionSigWithOutput( slashingTx, // transaction to verify fundingOutput, // output being spent @@ -227,13 +243,24 @@ err = VerifyTransactionSigWithOutput( ``` You can find more on the functions -in the [staker/types.go](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/types.go) file. +in the [staker/types.go](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/types.go) +file. + +The `MsgCreateBTCDelegation` message requires the slashing signatures. ## Inclusion Proof An inclusion proof (also known as a Merkle proof) demonstrates that a specific Bitcoin transaction is included in a block. In the Babylon protocol, these -proofs are optional when sending delegations to the Babylon network. +proofs are optional when sending delegations to the Babylon network depending +on the use case. + +The inclusion proof follows two possible flows: + +**Without proof:** Send delegation to Babylon first, then submit to Bitcoin later + +**With proof:** Submit to Bitcoin first, wait for confirmations, then send +delegation to Babylon with the inclusion proof. As shown in the code: @@ -247,20 +274,13 @@ type sendDelegationRequest struct { } ``` -The inclusion proof is not automatically generated by the Babylon chain - it's an -optional field in the delegation request. When provided, it contains the +The inclusion proof is not automatically generated by the Babylon chain - it's +an optional field in the delegation request. When provided, it contains the transaction index, block data, block height, and proof bytes in the `inclusionInfo` structure. This proof can be included in the `MsgCreateBTCDelegation` message when creating a delegation, but delegations can also be sent without a proof. -The inclusion proof follows two possible flows: - -**Without proof:** Send delegation to Babylon first, then submit to Bitcoin later - -**With proof:** Submit to Bitcoin first, wait for confirmations, then send -delegation to Babylon with the inclusion proof. - To see more information about inclusion proofs, see the [staker/babylontypes.go](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/babylontypes.go) file. @@ -269,7 +289,6 @@ To see more information about inclusion proofs, see the Proof of Possession (PoP) is a signature that proves you own and control the BTC private key used for staking. This proof is a required component when creating a BTC delegation through `MsgCreateBTCDelegation`. - To generate a Proof of Possession, you need to sign a specific message using your BTC private key: @@ -288,15 +307,21 @@ the rightful owner of the BTC private key can create delegations. This prevents unauthorized delegations and is a crucial part of the staking security process. +To see more information about Proof of Possession, see the +[staker/babylontypes.go](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/babylontypes.go) file. + +The `MsgCreateBTCDelegation` message requires the Proof of Possession. + ## Other General Fields -When creating a BTC delegation, several general fields are required in addition to the signatures and proofs: +When creating a BTC delegation, several general fields are required in addition +to the signatures and proofs: -Staking Amount: +**Staking Amount:** ```go stakingValue := btcutil.Amount(1000000) // Amount in satoshis ``` -Version Parameters: +**Version Parameters:** ```go // Get current parameters version from Babylon chain params, err := babylonClient.GetBTCStakingParams(ctx) @@ -308,48 +333,24 @@ stakingTime := uint16(1000) // Blocks for staking period unbondingTime := uint16(100) // Blocks for unbonding period ``` -Fees: +**Fees:** ```go stakingFee := btcutil.Amount(1000) // Fee for staking transaction slashingFee := btcutil.Amount(1000) // Fee for slashing transaction unbondingFee := btcutil.Amount(1000) // Fee for unbonding transaction ``` -Slashing rate: +**Slashing rate:** ```go slashingRate := float64(0.1) // 10% slashing rate ``` -### MsgAddBTCDelegationInclusionProof - -The `MsgAddBTCDelegationInclusionProof` message is used for submitting -the proof of inclusion of a Bitcoin Stake delegation on the -Bitcoin blockchain. -This message is utilised for notifying the Babylon blockchain -that a staking transaction that was previously submitted through -the EOI process is now on Bitcoin and has received sufficient -confirmations to become active. - -```protobuf -// MsgAddBTCDelegationInclusionProof is the message for adding proof of inclusion of BTC delegation on BTC chain -message MsgAddBTCDelegationInclusionProof { - option (cosmos.msg.v1.signer) = "signer"; - - string signer = 1; - // staking_tx_hash is the hash of the staking tx. - // It uniquely identifies a BTC delegation - string staking_tx_hash = 2; - // staking_tx_inclusion_proof is the inclusion proof of the staking tx in BTC chain - InclusionProof staking_tx_inclusion_proof = 3; -} -``` - ### Stake creation/registraton #### Registering a phase-1 stake -To register your phase-1 stake to phase-2, you need to submit a `MsgCreateBTCDelegation` -with a valid inclusion proof. This requires your staking transaction to already -be confirmed on the Bitcoin network. +To register your phase-1 stake to phase-2, you need to submit a +`MsgCreateBTCDelegation` with a valid inclusion proof. This requires your +staking transaction to already be confirmed on the Bitcoin network. 1. Create `MsgCreateBTCDelegation` with the inclusion proof filled as defined above and submit `MsgCreateBTCDelegation` to the Babylon network's btcstaking @@ -369,7 +370,8 @@ babyloncli query btcstaking delegation-status #### Creating new stakes -Create and submit MsgCreateBTCDelegation with an empty inclusion proof to the Babylon network. The message should include: +Create and submit `MsgCreateBTCDelegation` with an empty inclusion proof to the +Babylon network. The message should include: - Your unsigned staking transaction - Pre-signed slashing transaction @@ -378,17 +380,17 @@ Create and submit MsgCreateBTCDelegation with an empty inclusion proof to the Ba - Proof of Possession (PoP) - Other required fields (staking amount, timelock periods, etc.) -2. Wait for covenant signatures to be collected. The covenant committee will verify your transactions and add their required signatures. This ensures your delegation will be accepted once you commit your BTC. +2. Wait for covenant signatures to be collected. The covenant committee will +verify your transactions and add their required signatures. This ensures your +delegation will be accepted once you commit your BTC. -3. Once you have covenant approval, you can confidently submit your staking transaction to the Bitcoin network. This ensures your BTC won't be locked if the covenant rejects your delegation. +3. Once you have covenant approval, you can confidently submit your staking +transaction to the Bitcoin network. This ensures your BTC won't be locked if +the covenant rejects your delegation. -4. After your Bitcoin transaction is confirmed, the inclusion proof needs to be submitted via `MsgAddBTCDelegationInclusionProof`. While our Vigilante service will automatically handle this, you can also submit it yourself: - +4. After your Bitcoin transaction is confirmed, the inclusion proof needs to be +submitted via `MsgAddBTCDelegationInclusionProof`. While our Vigilante service +will automatically handle this, you can also submit it yourself. #### On-demand unbonding 1. You can retrieve covenant signatures from babylon chain and construct unbonding which is sent to btc