diff --git a/docs/register-create-stake-phase-2.md b/docs/register-create-stake-phase-2.md new file mode 100644 index 000000000..16297f809 --- /dev/null +++ b/docs/register-create-stake-phase-2.md @@ -0,0 +1,159 @@ +# Registering a phase-1 stake or creating a new stake + +## Table of contents + +- [Introduction](#introduction) +- [Babylon messages](#babylon-messages) +- [Stake creation and registration](#stake-creation-and-registration) +- [On-demand unbonding](#on-demand-unbonding) +- [Withdrawing](#withdrawing) + +## Introduction + +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 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 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 3](#creating-new-stakes) outlines on how to create new Bitcoin stakes + using the Expression of Interest (EOI) workflow. +- [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. + +## 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 + +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). + +`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). + +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. + +`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). + +## Stake creation and registration + +### 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. + +1. 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. + +2. You can check the status of your delegation by querying the babylon node +like this. + +```bash +babylond query btcstaking btc-delegations +``` + +The above command will return the status of your delegation (pending, active, +unbonding, unbonded, any). + +### 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, 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. + +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 + +. 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 -```