Skip to content

Commit

Permalink
wip
Browse files Browse the repository at this point in the history
  • Loading branch information
@samricotta
samricotta committed Jan 24, 2025
1 parent b0a6661 commit 7f94d71
Showing 1 changed file with 50 additions and 135 deletions.
185 changes: 50 additions & 135 deletions docs/register-create-stake-phase-2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,16 @@
## Table of contents

1. [Introduction](#1-introduction)
2. [MsgCreateBTCDelegation](#21-msgcreatebtcdelegation)
2. [Stake registration on the Babylon chain](#2-stake-registration-on-the-babylon-chain)
1. [Constructing and Broadcasting MsgCreateBTCDelegation](#21-constructing-and-broadcasting-msgcreatebtcdelegation)
3. [Stake creation and registration](#3-stake-creation-and-registration)
1. [Registering a phase-1 stake](#31-registering-a-phase-1-stake)
2. [Creating new stakes](#32-creating-new-stakes)
4. [Monitoring your stake transaction status](#4-monitoring-your-stake-transaction-status)
1. [On-demand unbonding](#41-on-demand-unbonding)
2. [Withdrawing](#42-withdrawing)
3. [Stake Submission](#3-stake-submission)
1. [High-Level overview of data that need to be submitted](#31-high-level-overview-of-data-that-need-to-be-submitted)
2. [The `MsgCreateBTCDelegation` message](#32-the-msgcreatebtcdelegation-message)
3. [Constructing the `MsgCreateBTCDelegation`](#33-constructing-the-msgcreatebtcdelegation)
4. [Registering Stake](#4-registering-stake)
5. [Monitoring your stake](#5-monitoring-your-stake)
1. [On-demand unbonding](#51-on-demand-unbonding)
2. [Withdrawing](#52-withdrawing)

## 1. Introduction

Expand All @@ -30,10 +32,16 @@ or create new ones. It is structured as follows:
Your stake transaction's status and gives a high-level overview of the unbonding
and withdrawing actions.

* Ways to stake
* front-end dashboard
* staker cli
* custom build (the purpose of this guide)
**Ways to Stake**
1. Front-End Dashboard:
Use the Babylon front-end dashboard for a user-friendly interface to manage your
staking activities.
2. Staker CLI:
Utilize the command line interface (CLI) for more direct control over staking
operations. This is suitable for users comfortable with command-line tools.
3. Custom Build (Purpose of This Guide):
TypeScript: Create and manage staking transactions using TypeScript. Refer to the [simple-staking repository](https://github.com/babylonlabs-io/simple-staking/blob/main/src/app/hooks/services/useTransactionService.ts#L672-L679) for examples and broadcast to the Babylon network.
Golang Library: Use the [Golang library](https://github.com/babylonlabs-io/babylon/blob/main/x/btcstaking/types/tx.pb.go) to construct and broadcast staking transactions. See the Babylon repository for implementation details.

## 2. Stake registration on the Babylon chain

Expand Down Expand Up @@ -319,9 +327,10 @@ The unbonding slashing signature for the delegator. This must be a valid
signature generated using the private key corresponding to the public key of the
Bitcoin staker (`btc_pk`).

### 3.2.3. Constructing the `MsgCreateBTCDelegation`
### 3.3. Constructing the `MsgCreateBTCDelegation`

The staking, unbonding, and slashing transactions can be created
As mentioned above, the staking, unbonding, and slashing transactions can be
created:
* Using our [Golang BTC staking library](../btcstaking)
* Using our [TypeScript BTC staking library](https://github.com/babylonlabs-io/btc-staking-ts)
* Implementing the transaction generation themselves using the
Expand All @@ -337,137 +346,43 @@ message to the Babylon network:
https://github.com/babylonlabs-io/babylon/blob/main/x/btcstaking/types/tx.pb.go
and broadcast to the Babylon network.

## 4. Registering? Stake (or another name)
## 4. Registering Stake

In this section, we tie section 2 and 3 together in the form of a full submission.

* The broadcasting flow you have to follow for `MsgCreateBTCDelegation`
depends on the path you want to follow.
* Bitcoin fist:
* Construct `MsgCreateBTCDelegation` with the proof of inclusion filled.
* Wait for covenants to add their signatures (monitor like that)
* Boom you're active
* Babylon first:
* Construct without pop
* Wait for covenants to add their sigs
* Submit the tx to Bitcoin
* Either wait for vigilante to include it or send the inclusion proof yourself
* small paragraph about sending the inclusion proof yourself, no need to get very
detailed, just as a note to show that you have a backup if you don't trust
the vigilante
* We need to provide technical resources on broadcasting, for example
* You need a node to broadcast
* You can do CLI, grpc, blah blah.
* No need to be very detailed, we can rely on external cosmos refs
**Bitcoin First**:
1. Construct the `MsgCreateBTCDelegation` with the proof of inclusion filled.
2. Wait for the covenants to add their signatures (you can do this by using
the `babylond query btcstaking delegation [staking_tx_hash]` command).
3. Once your stake is labelled as `active`, you are active!

## 5. Monitoring your stake
**Babylon First**:
1. Construct the message without the Proof of Possession (PoP).
2. Wait for the covenants to add their signatures (you can do this by using
the `babylond query btcstaking delegation [staking_tx_hash]` command).
3. Submit your transaction to the Bitcoin network.
4. You can either wait for the Vigilante service to include the transaction or
submit the inclusion proof yourself. This provides a backup option if you
prefer not to rely on the Vigilante service.

## 3. Stake creation and registration

When submitting stakes to the Babylon network, stakers have two primary options,
each representing a distinct workflow:

1. Registering a Phase-1 Stake:
- Flow: This option is used for stake that have already been created and
confirmed on the Bitcoin network during the initial phase (Phase-1).
- When to Use: If you have an existing Bitcoin stake that you wish to
register with the Babylon chain, this is the appropriate flow. It requires
a valid inclusion proof to confirm the stake's presence on the Bitcoin
blockchain.

2. Creating New Stakes ( Also known as Expression of Interest - EOI):
- Flow: This workflow is for creating new Bitcoin stakes that have not yet
been confirmed on the Bitcoin network.
- When to Use: Use this option if you are initiating a new stake. The process
involves submitting a `MsgCreateBTCDelegation` with an empty inclusion proof
and waiting for the covenant committee to verify and sign the transactions.
For more information, see the [Expression of Interest](../x/btcstaking/README.md#expression-of-interest-delegation-eoi)
section.

These options allow stakers to either register existing stakes or create new ones,
depending on their current status and needs.

### 3.1. Registering a phase-1 stake

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. You can do
this either manually through the Bitcoin network or using the staker library.

Create `MsgCreateBTCDelegation` with the inclusion proof filled as defined
above and submit `MsgCreateBTCDelegation` to the Babylon network's btcstaking
module. You will then wait for the covenant committee to submit their signatures.

The above command will return the status of your delegation (pending, active,
unbonding, unbonded, any).

### 3.2. Creating new stakes

1. 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.)

To submit the `MsgCreateBTCDelegation` message, you can use the following methods
mentioned in the [Constructing and Broadcasting MsgCreateBTCDelegation](#21-constructing-and-broadcasting-msgcreatebtcdelegation)
section.

As mentioned in the introduction, this flow can also be referred to as the
Expression of Interest (EOI) workflow.

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 verification, the vigilante program automatically
tracks the Bitcoin for confirmations of your staking transaction.
Once sufficient confirmations are received, it submits the
`MsgAddBTCDelegationInclusionProof` to the Babylon network. This message
includes the Merkle proof that verifies the transaction's inclusion in the
Bitcoin blockchain.

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.

To submit the inclusion proof separately, you can use the
`MsgAddBTCDelegationInclusionProof` message as detailed below. Once the
`MsgAddBTCDelegationInclusionProof` message is prepared, it can be broadcast
to the Babylon network using similar methods as the `MsgCreateBTCDelegation`
message. This ensures the staking transaction is properly tracked and verified
before activation. This involves checking for existing proofs, verifying the
quorum of covenant signatures, and confirming the transaction's status before
activating it on the network.

Below is the proto message for the `MsgAddBTCDelegationInclusionProof` message.
**Technical Resources for Broadcasting**

```proto
message MsgAddBTCDelegationInclusionProof {
option (cosmos.msg.v1.signer) = "signer";
To broadcast your transactions, you will need access to a node and can use
various methods:

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;
}
```
* Node Access: Ensure you have access to a Babylon node to broadcast your
transactions.

* Command Line Interface (CLI): Use the CLI for direct transaction submission.

Fields:
- `signer`: The address of the Babylon staker.
- `staking_tx_hash`: The hash of the staking transaction.
- `staking_tx_inclusion_proof`: The inclusion proof of the staking transaction.
* gRPC: Utilize gRPC for programmatic access to the network.

## 4. Monitoring your stake transaction status
* External References: For detailed instructions, refer to external Cosmos SDK
resources, which provide comprehensive guidance on using these tools.

## 5. Monitoring your stake

### 4.1. On-demand unbonding
### 5.1. On-demand unbonding

On-demand unbonding is a feature that allows users to initiate the unbonding of
their staked BTC at any time, without waiting for a predefined unbonding period.
Expand All @@ -490,7 +405,7 @@ babylond tx btcstaking btc-undelegate [staking_tx_hash] [spend_stake_tx] [spend_
During this phase, the necessary covenant signatures will be collected to
authorize the unbonding transaction.

### 4.2. Withdrawing
### 5.2. Withdrawing

Withdrawing is the process of transferring staked assets or earned rewards back
to the user's wallet or account. This process typically occurs after the assets
Expand Down

0 comments on commit 7f94d71

Please sign in to comment.