Skip to content

Commit

Permalink
Rewrite
Browse files Browse the repository at this point in the history
  • Loading branch information
@samricotta
samricotta committed Jan 20, 2025
1 parent 77d366a commit 41d7c15
Showing 1 changed file with 87 additions and 270 deletions.
357 changes: 87 additions & 270 deletions docs/register-create-stake-phase-2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -305,7 +122,7 @@ babyloncli query btcstaking delegation-status <staking-tx-hash>
- 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:
Expand All @@ -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
Expand Down

0 comments on commit 41d7c15

Please sign in to comment.