Skip to content

Commit

Permalink
Update register-create-stake-phase-2.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@samricotta
samricotta committed Jan 18, 2025
1 parent e7ca7c2 commit f7d8194
Showing 1 changed file with 96 additions and 94 deletions.
190 changes: 96 additions & 94 deletions docs/register-create-stake-phase-2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,18 @@

## Introduction

<!-- Finish this section -->
<!-- I think this needs an edit -->

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

Expand Down Expand Up @@ -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(
Expand All @@ -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(
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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`.
<!-- what specific messages -->

To generate a Proof of Possession, you need to sign a specific message using
your BTC private key:
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -369,7 +370,8 @@ babyloncli query btcstaking delegation-status <staking-tx-hash>

#### 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
Expand All @@ -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:
<!--
<!-- 1. Create `MsgCreateBTCDelegation` with an empty inclusion proof
2.  You can wait for covenant signatures to be collected
3. Once they do and you feel confident, you can submit the staking tx to btc
4. You can wait for inclusion, our vigilante will send the inclusion proof through `MsgInsertInclusionProof` . If you want however, you can also do it yourself.
5. You can monitor for your stake status like this.. -->
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
Expand Down

0 comments on commit f7d8194

Please sign in to comment.