From e7ca7c26d307c2ec14e6f5c720402aa268ca7095 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Thu, 16 Jan 2025 23:48:25 +1100 Subject: [PATCH 1/5] wip --- docs/register-create-stake-phase-2.md | 399 ++++++++++++++++++++++++++ docs/run-node.md | 136 --------- 2 files changed, 399 insertions(+), 136 deletions(-) create mode 100644 docs/register-create-stake-phase-2.md delete mode 100644 docs/run-node.md diff --git a/docs/register-create-stake-phase-2.md b/docs/register-create-stake-phase-2.md new file mode 100644 index 000000000..41b6decb6 --- /dev/null +++ b/docs/register-create-stake-phase-2.md @@ -0,0 +1,399 @@ +# Registering a phase-1 stake or creating a new stake + +## Table of contents + +- [Introduction](#introduction) +- [Babylon messages](#babylon-messages) +- [Stake creation/registraton](#stake-creationregistration) +- [On-demand unbonding](#on-demand-unbonding) +- [Withdrawing](#withdrawing) + +## 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. + +We are going to start with the Babylon structures associated with BTC staking +and how to 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 + +Babylon specifies a set of messages that are included inside transactions that +are used for staking, unbonding, etc. We will go through the messages and +how to construct them. + +### MsgCreateBTCDelegation + +The `MsgCreateBTCDelegation` message is used to create a BTC delegation. +This message is sent to the Babylon chain to register a phase-1 stake or +create a new stake. + +The message contains the following fields: + +```protobuf +// MsgCreateBTCDelegation is the message for creating a BTC delegation +message MsgCreateBTCDelegation { + option (cosmos.msg.v1.signer) = "staker_addr"; + // staker_addr is the address to receive rewards from BTC delegation. + string staker_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; + // pop is the proof of possession of btc_pk by the staker_addr. + ProofOfPossessionBTC pop = 2; + // btc_pk is the Bitcoin secp256k1 PK of the BTC delegator + bytes btc_pk = 3 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340PubKey" ]; + // fp_btc_pk_list is the list of Bitcoin secp256k1 PKs of the finality providers, if there is more than one + // finality provider pk it means that delegation is re-staked + repeated bytes fp_btc_pk_list = 4 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340PubKey" ]; + // staking_time is the time lock used in staking transaction + uint32 staking_time = 5; + // staking_value is the amount of satoshis locked in staking output + int64 staking_value = 6; + // staking_tx is a bitcoin staking transaction i.e transaction that locks funds + bytes staking_tx = 7 ; + // staking_tx_inclusion_proof is the inclusion proof of the staking tx in BTC chain + InclusionProof staking_tx_inclusion_proof = 8; + // slashing_tx is the slashing tx + // Note that the tx itself does not contain signatures, which are off-chain. + bytes slashing_tx = 9 [ (gogoproto.customtype) = "BTCSlashingTx" ]; + // delegator_slashing_sig is the signature on the slashing tx by the delegator (i.e., SK corresponding to btc_pk). + // It will be a part of the witness for the staking tx output. + // The staking tx output further needs signatures from covenant and finality provider in + // order to be spendable. + bytes delegator_slashing_sig = 10 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340Signature" ]; + // unbonding_time is the time lock used when funds are being unbonded. It is be used in: + // - unbonding transaction, time lock spending path + // - staking slashing transaction, change output + // - unbonding slashing transaction, change output + // It must be smaller than math.MaxUInt16 and larger that max(MinUnbondingTime, CheckpointFinalizationTimeout) + uint32 unbonding_time = 11; + // fields related to unbonding transaction + // unbonding_tx is a bitcoin unbonding transaction i.e transaction that spends + // staking output and sends it to the unbonding output + bytes unbonding_tx = 12; + // unbonding_value is amount of satoshis locked in unbonding output. + // NOTE: staking_value and unbonding_value could be different because of the difference between the fee for staking tx and that for unbonding + int64 unbonding_value = 13; + // unbonding_slashing_tx is the slashing tx which slash unbonding contract + // Note that the tx itself does not contain signatures, which are off-chain. + bytes unbonding_slashing_tx = 14 [ (gogoproto.customtype) = "BTCSlashingTx" ]; + // delegator_unbonding_slashing_sig is the signature on the slashing tx by the delegator (i.e., SK corresponding to btc_pk). + bytes delegator_unbonding_slashing_sig = 15 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340Signature" ]; +} +``` + +We will go through the fields in the above message in detail to understand how +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: + +```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) +``` + +To generate a staking transaction, you first need to build the staking information +using `BuildStakingInfo`: + +```go +stakingInfo, err := staking.BuildStakingInfo( + stakerBtcPk, // BTC public key + fpBtcPks, // finality provider public keys + currentParams.CovenantPks, // covenant committee public keys + currentParams.CovenantQuruomThreshold, // required number of covenant signatures + stakingTime, // how long to lock the BTC + stakingValue, // amount of BTC to stake + network, // Bitcoin network parameters +) +``` + +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: + +```go +stakingTx, err := app.wc.CreateTransaction( + []*wire.TxOut{stakingInfo.StakingOutput}, // staking output + btcutil.Amount(feeRate), // transaction fee rate + stakerAddress, // staker's address + app.filterUtxoFnGen(), // UTXO filter (Unspent Transaction Output) +) +``` + +Once created, the transaction is broadcast to the Bitcoin network and its +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. + +### Unbonding Transaction + +An unbonding transaction is a process initiated by a BTC staker to unlock and +withdraw their stake before the originally committed timelock period has expired. +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 +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: +- The unbonding transaction +- The unbonding value +- The timelock period +- The slashing transaction for the unbonding +- Spend information for the slashing path + +This creates a complete unbonding transaction that can be submitted to the +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. + +## Slashing Transactions + +Slashing transactions are used to slash BTC stakers who violate the staking +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. + +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. + +## 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 slashing signatures are generated by the BTC staker and are used to +sign the slashing transaction. These signatures are generated during +delegation creation and are required for both staking and unbonding transactions, +setting up how funds will be distributed if slashing occurs. + +To generate slashing signatures, the staker first creates a slashing +transaction template using `slashingTxForStakingTx`. Then, using their private +key, they sign this transaction with `SignTxWithOneScriptSpendInputFromScript` +to create a Schnorr signature. This signature, along with signatures from a +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. + +```go +// 1. Create transaction structure +slashingTx, spendInfo, err := slashingTxForStakingTx(...) + +// 2. Generate signatures (done separately) +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 +err = VerifyTransactionSigWithOutput( + slashingTx, // transaction to verify + fundingOutput, // output being spent + script, // script to check against + pubKey, // public key for verification + signature, // signature to verify +) +``` + +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. + +## 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. + +As shown in the code: + +```go +type sendDelegationRequest struct { + btcTxHash chainhash.Hash + // optional field, if not provided, delegation will be sent to Babylon without + // the inclusion proof + inclusionInfo *inclusionInfo + requiredInclusionBlockDepth uint32 +} +``` + +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. + +## Proof of Possession + +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: + +```go +pop, err := btcstaking.SignProofOfPossession( + privateKey, // Your BTC private key + babylon_address, // Your Babylon address + net, // Network parameters +) +``` +It is then returned as a `ProofOfPossessionBTC` message. + +The PoP serves as a security measure in the Babylon protocol, ensuring that only +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. + +## Other General Fields +When creating a BTC delegation, several general fields are required in addition to the signatures and proofs: + +Staking Amount: +```go +stakingValue := btcutil.Amount(1000000) // Amount in satoshis +``` + +Version Parameters: +```go +// Get current parameters version from Babylon chain +params, err := babylonClient.GetBTCStakingParams(ctx) +if err != nil { + return err +} + +stakingTime := uint16(1000) // Blocks for staking period +unbondingTime := uint16(100) // Blocks for unbonding period +``` + +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: +```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. + +1. Create `MsgCreateBTCDelegation` with the inclusion proof filled as defined +above and submit `MsgCreateBTCDelegation` to the Babylon network's btcstaking +module. If all verifications pass, your delegation becomes active on the Babylon +chain immediately since you've already proven your BTC is locked on Bitcoin. + +2. You can check the activation status by querying the babylon node like this. + +```bash +babyloncli query btcstaking delegation-status +``` + +3. Note that certain eligibility criteria apply including: +- Valid timelock periods (maximum 65535 blocks) +- Properly formatted transactions with correct signatures +- Valid Proof of Possession demonstrating control of your BTC private key. + +#### Creating new stakes + +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 +- Unsigned unbonding transaction +- Pre-signed unbonding slashing transaction +- 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. + +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: + + +#### On-demand unbonding + 1. You can retrieve covenant signatures from babylon chain and construct unbonding which is sent to btc + 2. Babylon will monitor etc.. +## Withdrawing + 1. You can withdraw any time blah blah + 2. You can withdraw from slashing blah blah + diff --git a/docs/run-node.md b/docs/run-node.md deleted file mode 100644 index 4f2cef4f2..000000000 --- a/docs/run-node.md +++ /dev/null @@ -1,136 +0,0 @@ -## Running a node - -The following commands assume that the `babylond` executable has been -installed. If the repository was only built, then `./build/babylond` should be -used in its place. - -### Generating the node configuration - -The configuration for a single node can be created through the `testnet` -command. While the `testnet` command can create an arbitrary number of nodes that -communicate on a testnet, here we focus on the setup of a single node. - -```console -babylond testnet \ - --v 1 \ - --output-dir ./.testnet \ - --starting-ip-address 192.168.10.2 \ - --keyring-backend test \ - --chain-id chain-test -``` - -The flags specify the following: - -- `--output-dir `: Specifies that the testnet files should - reside under this directory. -- `--v `: Leads to the creation of `N` nodes, each one residing under the - `/node{i}`. In this case `i={0..N-1}`. -- `--starting-ip-address `: Specifies the IP address for the nodes. For example, - `192.168.10.2` leads to the first node running on `192.168.10.2:46656`, the - second one on `192.168.10.3:46656` etc. -- `--keyring-backend {os,file,test}`: Specifies the backend to use for the keyring. Available - choices include `os`, `file`, and `test`. We use `test` for convenience. -- `--chain-id`: An identifier for the chain. Useful when performing operations - later. - -In this case, we generated a single node. If we take a look under `.testnet`: - -```console -$ ls .testnet -gentxs node0 -``` - -The `gentxs` directory contains the genesis transactions. It contains -transactions that assign bbn tokens to a single address that is defined for each -node. - -The `node0` directory contains the following: - -```console -$ ls .testnet/node0/babylond -config data key_seed.json keyring-test -``` - -A brief description of the contents: - -- `config`: Contains the configuration files for the node. -- `data`: Contains the database storage for the node. -- `key_seed.json`: Seed to generate the keys maintained by the keyring. -- `keyring-test`: Contains the test keyring. This directory was created because - we provided the `--keyring-backend test` flag. The `testnet` command, creates - a validator node named `node{i}` (depends on the node name), and assigns - bbn tokens to it through a transaction written to `.testnet/gentxs/node{i}.json`. - The keys for this node can be pointed to by the `node{i}` name. - -### Running the node - -```console -babylond start --home ./.testnet/node0/babylond -``` - -### Logs - -The logs for a particular node can be found under -`.testnets/node{id}/babylond/babylond.log`. - -### Performing queries - -After building a node and starting it, you can perform queries. - -```console -babylond --home .testnet/node{i}/babylond/ --chain-id \ - query -``` - -For example, in order to get the hashes maintained by the `btclightclient` -module: - -```console -$ babylond --home .testnet/node0/babylond/ --chain-id chain-test query btclightclient hashes - -hashes: -- 00000000000000000002bf1c218853bc920f41f74491e6c92c6bc6fdc881ab47 -pagination: - next_key: null - total: "1" -``` - -### Submitting transactions - -After building a node and running it, one can send transactions as follows: - -```console -babylond --home .testnet/node{i}/babylond --chain-id \ - --keyring-backend {os,file,test} --fees \ - --from --broadcast-mode {sync,async,block} \ - tx [data] -``` - -The `--fees` flag specifies the amount of fees that we are willing to pay and -the denomination and the `--from` flag denotes the name of the key that we want -to use to sign the transaction (i.e. from which account we want this -transaction to happen). The `--broadcast-mode` specifies how long we want to -wait until we receive a response from the CLI: `async` means immediately, -`sync` means after the transaction has been validated through `CheckTx`, -and `block` means after the transaction has been processed by the next block. - -For example, in the `btclightclient` module, in order -to submit a header, one should: - -```console -babylond --home .testnet/node0/babylond --chain-id chain-test \ - --keyring-backend test --fees 100bbn \ - --from node0 --broadcast-mode block \ - tx btclightclient insert-header -``` - -## Running node in Production - -When running the Babylon node in a production setting, operators should adhere to  -[CometBFT Guidelines](https://docs.cometbft.com/v0.38/core/running-in-production) - -## Testing - -```console -make test -``` From f7d8194cabe8ced5fb0cd58ff2248df2d8d501d0 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Sat, 18 Jan 2025 19:37:27 +1100 Subject: [PATCH 2/5] 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 41b6decb6..cb49b8801 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 From 77d366a35eda5c16fccd4a0614dbfd55b73b4ffd Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Mon, 20 Jan 2025 16:54:53 +1100 Subject: [PATCH 3/5] Update register-create-stake-phase-2.md --- docs/register-create-stake-phase-2.md | 169 ++++++++------------------ 1 file changed, 53 insertions(+), 116 deletions(-) diff --git a/docs/register-create-stake-phase-2.md b/docs/register-create-stake-phase-2.md index cb49b8801..1b1965511 100644 --- a/docs/register-create-stake-phase-2.md +++ b/docs/register-create-stake-phase-2.md @@ -10,18 +10,16 @@ ## Introduction - +This documentation guides you through the structures and processes required to +communicate with the Babylon chain in order to: -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 new stake. - -We are going to start with the Babylon structures associated with BTC staking -and how to generate and construct them. - -Then we are going to explore different use cases utilising the different -structures. +- Register a Phase-1 stake. +- Create a new stake. +- Manage actions like unbonding and withdrawing rewards. +We will start by explaining the Babylon structures associated with BTC staking +and how to generate and construct them. Then, we will explore various use cases +utilizing these structures. ## Babylon messages @@ -31,111 +29,50 @@ how to construct them. ### MsgCreateBTCDelegation -The `MsgCreateBTCDelegation` message is used to create a BTC delegation. -This message is sent to the Babylon chain to register a phase-1 stake or -create a new stake. - -The message contains the following fields: - -```protobuf -// MsgCreateBTCDelegation is the message for creating a BTC delegation -message MsgCreateBTCDelegation { - option (cosmos.msg.v1.signer) = "staker_addr"; - // staker_addr is the address to receive rewards from BTC delegation. - string staker_addr = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; - // pop is the proof of possession of btc_pk by the staker_addr. - ProofOfPossessionBTC pop = 2; - // btc_pk is the Bitcoin secp256k1 PK of the BTC delegator - bytes btc_pk = 3 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340PubKey" ]; - // fp_btc_pk_list is the list of Bitcoin secp256k1 PKs of the finality providers, if there is more than one - // finality provider pk it means that delegation is re-staked - repeated bytes fp_btc_pk_list = 4 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340PubKey" ]; - // staking_time is the time lock used in staking transaction - uint32 staking_time = 5; - // staking_value is the amount of satoshis locked in staking output - int64 staking_value = 6; - // staking_tx is a bitcoin staking transaction i.e transaction that locks funds - bytes staking_tx = 7 ; - // staking_tx_inclusion_proof is the inclusion proof of the staking tx in BTC chain - InclusionProof staking_tx_inclusion_proof = 8; - // slashing_tx is the slashing tx - // Note that the tx itself does not contain signatures, which are off-chain. - bytes slashing_tx = 9 [ (gogoproto.customtype) = "BTCSlashingTx" ]; - // delegator_slashing_sig is the signature on the slashing tx by the delegator (i.e., SK corresponding to btc_pk). - // It will be a part of the witness for the staking tx output. - // The staking tx output further needs signatures from covenant and finality provider in - // order to be spendable. - bytes delegator_slashing_sig = 10 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340Signature" ]; - // unbonding_time is the time lock used when funds are being unbonded. It is be used in: - // - unbonding transaction, time lock spending path - // - staking slashing transaction, change output - // - unbonding slashing transaction, change output - // It must be smaller than math.MaxUInt16 and larger that max(MinUnbondingTime, CheckpointFinalizationTimeout) - uint32 unbonding_time = 11; - // fields related to unbonding transaction - // unbonding_tx is a bitcoin unbonding transaction i.e transaction that spends - // staking output and sends it to the unbonding output - bytes unbonding_tx = 12; - // unbonding_value is amount of satoshis locked in unbonding output. - // NOTE: staking_value and unbonding_value could be different because of the difference between the fee for staking tx and that for unbonding - int64 unbonding_value = 13; - // unbonding_slashing_tx is the slashing tx which slash unbonding contract - // Note that the tx itself does not contain signatures, which are off-chain. - bytes unbonding_slashing_tx = 14 [ (gogoproto.customtype) = "BTCSlashingTx" ]; - // delegator_unbonding_slashing_sig is the signature on the slashing tx by the delegator (i.e., SK corresponding to btc_pk). - bytes delegator_unbonding_slashing_sig = 15 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340Signature" ]; -} -``` - -We will go through the fields in the above message in detail to understand how -to construct them. +The `MsgCreateBTCDelegation` message is used to create a BTC delegation. This +message is sent to the Babylon chain to register a Phase-1 stake or create a +new stake. The message contains the following fields: + +- `staker_addr`: The address to receive rewards from BTC delegation. +- `pop`: Proof of possession of the Bitcoin private key (btc_pk) by the + `staker_addr`. +- `btc_pk`: The Bitcoin public key of the BTC delegator. +- `fp_btc_pk_list`: A list of Bitcoin public keys for the finality providers. +- `staking_time`: The timelock period for the staking transaction. +- `staking_value`: The amount of satoshis locked in the staking output. +- `staking_tx`: The Bitcoin staking transaction hash. +- `staking_tx_inclusion_proof`: The inclusion proof of the staking transaction + in the Bitcoin chain (optional). +- `slashing_tx`: The slashing transaction for the staking period. +- `delegator_slashing_sig`: The signature on the slashing transaction by the + delegator. +- `unbonding_time`: The timelock period used when funds are being unbonded. +- `unbonding_tx`: The Bitcoin unbonding transaction hash. +- `unbonding_value`: The amount of satoshis locked in the unbonding output. +- `unbonding_slashing_tx`: The slashing transaction for the unbonding period. +- `delegator_unbonding_slashing_sig`: The signature on the unbonding slashing + transaction by the delegator. + +For the full message definition, see the +[MsgCreateBTCDelegation](../proto/babylon/btcstaking/v1/tx.proto) +source code. ### Staking Transaction -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. - -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: - -1. Build the staking hash using `BuildStakingInfo`: +A staking transaction locks BTC funds into a Bitcoin output for delegation. +The Babylon chain uses the transaction hash to confirm that your BTC is staked. -```go -stakingInfo, err := staking.BuildStakingInfo( - stakerBtcPk, // BTC public key - fpBtcPks, // finality provider public keys - currentParams.CovenantPks, // covenant committee public keys - currentParams.CovenantQuruomThreshold, // required number of covenant signatures - stakingTime, // how long to lock the BTC - stakingValue, // amount of BTC to stake - network, // Bitcoin network parameters -) -``` - -This staking information is used to create a Bitcoin transaction with a special -output script that enforces the staking rules. +#### How to Create a Staking Transaction -2. The transaction is then created using: - -```go -stakingTx, err := app.wc.CreateTransaction( - []*wire.TxOut{stakingInfo.StakingOutput}, // staking output - btcutil.Amount(feeRate), // transaction fee rate - stakerAddress, // staker's address - app.filterUtxoFnGen(), // UTXO filter (Unspent Transaction Output) -) -``` +To create a staking transaction: -Once created, the transaction is broadcast to the Bitcoin network and its -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. +1. Use the Babylon staker CLI or library to generate the transaction. +2. Broadcast the transaction to the Bitcoin network. +3. Retrieve the transaction hash, which will be used in the +`MsgCreateBTCDelegation` message. -The `MsgCreateBTCDelegation` message requires the staking transaction hash. +For advanced details on transaction creation, refer to the +[Babylon Staker Library Documentation](https://github.com/babylonlabs-io/btc-staker/blob/main/README.md). ### Unbonding Transaction @@ -148,7 +85,7 @@ It allows the staker to regain access to their locked funds earlier than planned 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/babylonlabs-io/btc-staker/blob/main/staker/types.go#L341) file. The function returns an `UnbondingSlashingDesc` containing: - The unbonding transaction - The unbonding value @@ -318,7 +255,7 @@ to the signatures and proofs: **Staking Amount:** ```go -stakingValue := btcutil.Amount(1000000) // Amount in satoshis +stakingValue := btcutil.Amount(1000000) // amount in satoshis ``` **Version Parameters:** @@ -329,20 +266,20 @@ if err != nil { return err } -stakingTime := uint16(1000) // Blocks for staking period -unbondingTime := uint16(100) // Blocks for unbonding period +stakingTime := uint16(1000) // blocks for staking period +unbondingTime := uint16(100) // blocks for unbonding period ``` **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 +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:** ```go -slashingRate := float64(0.1) // 10% slashing rate +slashingRate := float64(0.1) // for example 10% slashing rate ``` ### Stake creation/registraton From 41d7c15acbd13c56877a6359396993fa4ed4aff5 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Mon, 20 Jan 2025 21:48:52 +1100 Subject: [PATCH 4/5] Rewrite --- docs/register-create-stake-phase-2.md | 357 +++++++------------------- 1 file changed, 87 insertions(+), 270 deletions(-) diff --git a/docs/register-create-stake-phase-2.md b/docs/register-create-stake-phase-2.md index 1b1965511..4d01dab69 100644 --- a/docs/register-create-stake-phase-2.md +++ b/docs/register-create-stake-phase-2.md @@ -4,286 +4,103 @@ - [Introduction](#introduction) - [Babylon messages](#babylon-messages) -- [Stake creation/registraton](#stake-creationregistration) +- [Stake creation and registration](#stake-creation-and-registration) - [On-demand unbonding](#on-demand-unbonding) - [Withdrawing](#withdrawing) ## Introduction -This documentation guides you through the structures and processes required to -communicate with the Babylon chain in order to: - -- Register a Phase-1 stake. -- Create a new stake. -- Manage actions like unbonding and withdrawing rewards. - -We will start by explaining the Babylon structures associated with BTC staking -and how to generate and construct them. Then, we will explore various use cases -utilizing these structures. - -## Babylon messages - -Babylon specifies a set of messages that are included inside transactions that -are used for staking, unbonding, etc. We will go through the messages and -how to construct them. +This document walks through the communication protocol +with the Babylon chain in order to register existing Bitcoin stakes +or create new ones. It is structured as follows: +- [Section 2](#babylon-messages) introduces the `MsgCreateBTCDelegation` + Babylon chain message which is utilized to communicate + staking transactions to the Babylon chain. The section includes + details about how to fill in its different fields. +- [Section 3](#registering-a-phase-1-stake) outlines on how to register existing + Bitcoin stakes (e.g., stakes created during Phase-1) using the above structure. +- [Section 4](#creating-new-stakes) outlines on how to create new Bitcoin stakes + using the Expression of Interest (EOI) workflow. +- [Section 5](#monitoring-your-stake-transaction-status) outlines how to monitor + your stake transaction's status and gives a high-level overview of the unbonding + and withdrawing actions.withdrawing actions. + +## Babylon Messages + +Babylon specifies a set of messages included in transactions for staking, +unbonding, and related actions. Below, we focus on the `MsgCreateBTCDelegation` +and other related messages. ### MsgCreateBTCDelegation -The `MsgCreateBTCDelegation` message is used to create a BTC delegation. This -message is sent to the Babylon chain to register a Phase-1 stake or create a -new stake. The message contains the following fields: - -- `staker_addr`: The address to receive rewards from BTC delegation. -- `pop`: Proof of possession of the Bitcoin private key (btc_pk) by the - `staker_addr`. -- `btc_pk`: The Bitcoin public key of the BTC delegator. -- `fp_btc_pk_list`: A list of Bitcoin public keys for the finality providers. -- `staking_time`: The timelock period for the staking transaction. -- `staking_value`: The amount of satoshis locked in the staking output. -- `staking_tx`: The Bitcoin staking transaction hash. -- `staking_tx_inclusion_proof`: The inclusion proof of the staking transaction - in the Bitcoin chain (optional). -- `slashing_tx`: The slashing transaction for the staking period. -- `delegator_slashing_sig`: The signature on the slashing transaction by the - delegator. -- `unbonding_time`: The timelock period used when funds are being unbonded. -- `unbonding_tx`: The Bitcoin unbonding transaction hash. -- `unbonding_value`: The amount of satoshis locked in the unbonding output. -- `unbonding_slashing_tx`: The slashing transaction for the unbonding period. -- `delegator_unbonding_slashing_sig`: The signature on the unbonding slashing - transaction by the delegator. - -For the full message definition, see the -[MsgCreateBTCDelegation](../proto/babylon/btcstaking/v1/tx.proto) -source code. - -### Staking Transaction - -A staking transaction locks BTC funds into a Bitcoin output for delegation. -The Babylon chain uses the transaction hash to confirm that your BTC is staked. - -#### How to Create a Staking Transaction - -To create a staking transaction: - -1. Use the Babylon staker CLI or library to generate the transaction. -2. Broadcast the transaction to the Bitcoin network. -3. Retrieve the transaction hash, which will be used in the -`MsgCreateBTCDelegation` message. - -For advanced details on transaction creation, refer to the -[Babylon Staker Library Documentation](https://github.com/babylonlabs-io/btc-staker/blob/main/README.md). - -### Unbonding Transaction - -An unbonding transaction is a process initiated by a BTC staker to unlock and -withdraw their stake before the originally committed timelock period has expired. -It allows the staker to regain access to their locked funds earlier than planned. - -#### Creating an Unbonding Transaction - -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/babylonlabs-io/btc-staker/blob/main/staker/types.go#L341) file. The function returns an `UnbondingSlashingDesc` containing: - -- The unbonding transaction -- The unbonding value -- The timelock period -- The slashing transaction for the unbonding -- Spend information for the slashing path - -This creates a complete unbonding transaction that can be submitted to the -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. - -The `MsgCreateBTCDelegation` message requires the unbonding transaction hash. - -## Slashing Transactions - -Slashing transactions are used to slash BTC stakers who violate the staking -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 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. - -## Slashing Signatures - -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 -delegation creation and are required for both staking and unbonding transactions, -setting up how funds will be distributed if slashing occurs. - -To generate slashing signatures, the staker first creates a slashing -transaction template using `slashingTxForStakingTx`. Then, using their private -key, they sign this transaction with `SignTxWithOneScriptSpendInputFromScript` -to create a Schnorr signature. This signature, along with signatures from a -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 -slashingTx, spendInfo, err := slashingTxForStakingTx(...) -``` - -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 +This message is used to register a BTC delegation with the Babylon chain. +Below are the key fields and expectations from the +[`MsgCreateBTCDelegation` message](./proto/babylon/btcstaking/v1/tx.proto). -```go -err = VerifyTransactionSigWithOutput( - slashingTx, // transaction to verify - fundingOutput, // output being spent - script, // script to check against - pubKey, // public key for verification - signature, // signature to verify -) -``` +`staking_tx`: +The staking transaction is in hex format. The transaction can be either +signed or unsigned. This is generated using our +[Golang library](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/types.go) +or [TypeScript library](https://github.com/babylonlabs-io/simple-staking/blob/main/src/app/hooks/services/useTransactionService.ts#L101). -You can find more on the functions -in the [staker/types.go](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/types.go) +The rules for what constitutes a valid staking transaction are outlined in the +[`btcstaking/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 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: - -```go -type sendDelegationRequest struct { - btcTxHash chainhash.Hash - // optional field, if not provided, delegation will be sent to Babylon without - // the inclusion proof - inclusionInfo *inclusionInfo - requiredInclusionBlockDepth uint32 -} -``` - -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. - -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. - -## Proof of Possession - -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: - -```go -pop, err := btcstaking.SignProofOfPossession( - privateKey, // Your BTC private key - babylon_address, // Your Babylon address - net, // Network parameters -) -``` -It is then returned as a `ProofOfPossessionBTC` message. - -The PoP serves as a security measure in the Babylon protocol, ensuring that only -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: - -**Staking Amount:** -```go -stakingValue := btcutil.Amount(1000000) // amount in satoshis -``` - -**Version Parameters:** -```go -// Get current parameters version from Babylon chain -params, err := babylonClient.GetBTCStakingParams(ctx) -if err != nil { - return err -} - -stakingTime := uint16(1000) // blocks for staking period -unbondingTime := uint16(100) // blocks for unbonding period -``` - -**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:** -```go -slashingRate := float64(0.1) // for example 10% slashing rate -``` - -### Stake creation/registraton -#### Registering a phase-1 stake +`unbonding_tx`: +An unbonding transaction allows a BTC staker to unlock their funds by +obtaining necessary signatures and broadcasting the transaction to the +Bitcoin network. Once confirmed, the staker regains access to their BTC. + +The unbonding transaction is in hex format. This transaction is used to +unlock staked BTC after the unbonding period. You can generate this transaction +using our Golang library or TypeScript library, see +[Babylon staker library](https://github.com/babylonlabs-io/btc-staker/blob/main/staker/types.go) or +[TypeScript library](https://github.com/babylonlabs-io/simple-staking/blob/main/src/app/hooks/services/useTransactionService.ts#L101). Details on what constitutes a valid +unbonding transaction can be found [here](./staking-script.md). + +`slashing_tx`: +The slashing transaction is in hex format. Generated during both staking and +unbonding phases, this transaction spends the staking or unbonding transaction +in cases of protocol violations such as double-signing. +A valid signature for this transaction must be included in the +`slashing_tx_sig` field. + +`delegator_slashing_sig`: +The signature for the `slashing_tx`. This must be a valid signature +generated using the private key corresponding to the BTC public key (btc_pk). + +`delegator_unbonding_slashing_sig`: +The unbonding slashing signature for the delegator. This must be a valid +signature generated using the private key corresponding to the BTC public key +(btc_pk). + +`pop` (Proof of Possession): +A cryptographic signature verifying ownership of the Bitcoin private key used +for staking. Required for registering a phase-1 stake to confirm the legitimate +ownership of the associated Bitcoin address. This will be generated during the +phase-1 creation of stake process. To see the full message, see the +[`ProofOfPossessionBTC` message](./proto/babylon/btcstaking/v1/pop.proto). + +`inclusion_proof` (Optional): +A Merkle proof showing that the staking transaction is included in the +Bitcoin chain. This field is optional but recommended. To see the full message, +see the [`InclusionProof` message](./proto/babylon/btcstaking/v1/btcstaking.proto). + +If not provided during submission, it must be submitted later using the +`MsgAddBTCDelegationInclusionProof` message. To see the full message, see the +[`MsgAddBTCDelegationInclusionProof` message](./proto/babylon/btcstaking/v1/tx.proto). + +`Other General Fields`: +- `staking_value`: The amount of BTC locked for delegation (in satoshis). +- `staking_time`: The timelock period for the staking transaction (in blocks). +- `unbonding_time`: The timelock period for unbonding (in blocks). +- `Version Parameters`: Use the Babylon CLI to retrieve the current parameter + version for these fields. + +## Stake creation and registration + +### 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 @@ -305,7 +122,7 @@ babyloncli query btcstaking delegation-status - Properly formatted transactions with correct signatures - Valid Proof of Possession demonstrating control of your BTC private key. -#### Creating new stakes +### Creating new stakes Create and submit `MsgCreateBTCDelegation` with an empty inclusion proof to the Babylon network. The message should include: @@ -329,7 +146,7 @@ the covenant rejects your delegation. submitted via `MsgAddBTCDelegationInclusionProof`. While our Vigilante service will automatically handle this, you can also submit it yourself. -#### On-demand unbonding +## On-demand unbonding 1. You can retrieve covenant signatures from babylon chain and construct unbonding which is sent to btc 2. Babylon will monitor etc.. ## Withdrawing From 74e07ce8eaa70e055980fb5f5ec59f14f4d4d218 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Tue, 21 Jan 2025 15:17:28 +1100 Subject: [PATCH 5/5] wip --- docs/register-create-stake-phase-2.md | 50 +++++++++++++++------------ 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/docs/register-create-stake-phase-2.md b/docs/register-create-stake-phase-2.md index 4d01dab69..16297f809 100644 --- a/docs/register-create-stake-phase-2.md +++ b/docs/register-create-stake-phase-2.md @@ -13,17 +13,17 @@ This document walks through the communication protocol with the Babylon chain in order to register existing Bitcoin stakes or create new ones. It is structured as follows: -- [Section 2](#babylon-messages) introduces the `MsgCreateBTCDelegation` +- [Section 1](#babylon-messages) introduces the `MsgCreateBTCDelegation` Babylon chain message which is utilized to communicate staking transactions to the Babylon chain. The section includes details about how to fill in its different fields. -- [Section 3](#registering-a-phase-1-stake) outlines on how to register existing +- [Section 2](#registering-a-phase-1-stake) outlines on how to register existing Bitcoin stakes (e.g., stakes created during Phase-1) using the above structure. -- [Section 4](#creating-new-stakes) outlines on how to create new Bitcoin stakes +- [Section 3](#creating-new-stakes) outlines on how to create new Bitcoin stakes using the Expression of Interest (EOI) workflow. -- [Section 5](#monitoring-your-stake-transaction-status) outlines how to monitor +- [Section 4](#monitoring-your-stake-transaction-status) outlines how to monitor your stake transaction's status and gives a high-level overview of the unbonding - and withdrawing actions.withdrawing actions. + and withdrawing actions. ## Babylon Messages @@ -95,32 +95,29 @@ If not provided during submission, it must be submitted later using the - `staking_value`: The amount of BTC locked for delegation (in satoshis). - `staking_time`: The timelock period for the staking transaction (in blocks). - `unbonding_time`: The timelock period for unbonding (in blocks). -- `Version Parameters`: Use the Babylon CLI to retrieve the current parameter - version for these fields. ## Stake creation and registration ### Registering a phase-1 stake -To register your phase-1 stake to phase-2, you need to submit a +To register a Bitcoin stake that is already on Bitcoin to +the Babylon chain (e.g., a phase-1 stake), you need to submit a `MsgCreateBTCDelegation` with a valid inclusion proof. This requires your -staking transaction to already be confirmed on the Bitcoin network. +staking transaction to already be confirmed on the Bitcoin network. You can do this either manually through the Bitcoin network or using the staker library. 1. Create `MsgCreateBTCDelegation` with the inclusion proof filled as defined above and submit `MsgCreateBTCDelegation` to the Babylon network's btcstaking -module. If all verifications pass, your delegation becomes active on the Babylon -chain immediately since you've already proven your BTC is locked on Bitcoin. +module. You will then wait for the covenant committee to submit their signatures. -2. You can check the activation status by querying the babylon node like this. +2. You can check the status of your delegation by querying the babylon node +like this. ```bash -babyloncli query btcstaking delegation-status +babylond query btcstaking btc-delegations ``` -3. Note that certain eligibility criteria apply including: -- Valid timelock periods (maximum 65535 blocks) -- Properly formatted transactions with correct signatures -- Valid Proof of Possession demonstrating control of your BTC private key. +The above command will return the status of your delegation (pending, active, +unbonding, unbonded, any). ### Creating new stakes @@ -138,18 +135,25 @@ Babylon network. The message should include: 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, the vigilante service will send the staking +transaction to the Bitcoin network. If you wish to submit the inclusion proof +manually, you can do so 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. +To submit the inclusion proof manually, you can use the following command: + +```bash +babylond tx btcstaking add-btc-inclusion-proof +``` + ## On-demand unbonding 1. You can retrieve covenant signatures from babylon chain and construct unbonding which is sent to btc + 2. Babylon will monitor etc.. ## Withdrawing 1. You can withdraw any time blah blah 2. You can withdraw from slashing blah blah +.