diff --git a/docs/register-create-stake-phase-2.md b/docs/register-create-stake-phase-2.md index 1b196551..4d01dab6 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