diff --git a/bbn-test-5/babylon-node/README.md b/bbn-test-5/babylon-node/README.md new file mode 100644 index 00000000..f0f053f1 --- /dev/null +++ b/bbn-test-5/babylon-node/README.md @@ -0,0 +1,283 @@ +# Babylon Node Setup + +## Table of Contents + +1. [Install Babylon Binary](#install-babylon-binary) +2. [Setup Node Home Directory and Configure](#setup-your-node-home-directory-and-configure) +4. [Setup Required Keys](#setup-the-required-keys-for-operating-a-validator) +5. [Sync Node](#sync-node) +6. [Get Funds](#get-funds) + + +## Install Babylon Binary + +1. Install [Golang 1.21+](https://go.dev/dl) +2. Verify installation: + +```shell +go version +``` + +3. Clone and build Babylon: +```shell +git clone git@github.com:babylonlabs-io/babylon.git +cd babylon +git checkout bbn-test-5 # TODO: testnet tag to be defined +make install +``` +This command does the following: +- Builds the daemon +- Compiles all the Go packages in the project +- Installs the binary +- Makes the `babylond` command globally accessible from your terminal + +You should expect to see the following output: + +```shell +# Build output will show: +go install -mod=readonly -tags "netgo ledger mainnet" \ + -ldflags '\ + -X github.com/cosmos/cosmos-sdk/version.Name=babylon \ + -X github.com/cosmos/cosmos-sdk/version.AppName=babylond \ + -X github.com/cosmos/cosmos-sdk/version.Version=v0.13.0 \ + -X github.com/cosmos/cosmos-sdk/version. + Commit=976e94b926dcf287cb487e8f35dbf400c7d930cc \ + -X "github.com/cosmos/cosmos-sdk/version.BuildTags=netgo,ledger" \ + -w -s' \ + -trimpath ./... +``` + +Now it has successfully compiled, lets check the available actions +through the `babylond` command: + +```shell +babylond +``` + +Which will give us a list of available actions. + +```shell +Available Commands: + add-genesis-account Add a genesis account to genesis.json + collect-gentxs Collect genesis txs and output a genesis.json file + comet CometBFT subcommands + config Utilities for managing application configuration + ... +``` + +If the babylond command isn't found, ensure `$GOPATH/bin` is in your shell's +`$PATH`. Add it with: + + ```shell + export PATH=$HOME/go/bin:$PATHecho 'export PATH=$HOME/go/bin:$PATH' >> + ~/.profile + ``` + +## Setup your node, home directory and configure + +Initialize your node and create the necessary configuration directory. +This command will generate several important configuration files +including `app.toml`, `client.toml`, and `genesis.json`: + +```shell +babylond init --chain-id bbn-test-5 --home +``` + +The `` is a unique identifier for your node. So for example `node0`. +The `` is the directory where the node files will be stored +(e.g. `--home ./nodeDir`). + +After initialization, you'll need to modify two important configuration files: + +1. First, open `app.toml` and update these essential settings: + +```shell +Base configuration +minimum-gas-prices = "0.005ubbn" +iavl-cache-size = 0 +iavl-disable-fastnode=true + +[btc-config] + +# Configures which bitcoin network should be used for checkpointing +# valid values are: [mainnet, testnet, simnet, signet, regtest] +network = "signet" # Bitcoin network for checkpointing +``` + +In `app.toml` under `[btc-network]`change network to `signet` and under +`Base Configuration` set `iavl-cache-size = 0` and `iavl-disable-fastnode=true` +instead of what is listed in the automatically generated template. +Additionally, add `minimum-gas-prices = "0.005ubbn"` + +Navigate to `config.toml`. Add in your seed that should look something like +this `8fa2d1ab10dfd99a51703ba760f0ef555ae88f36@16.162.207.201:26656` + +```shell + P2P Configuration Options + +# Comma separated list of seed nodes to connect to +seeds = "8fa2d1ab10dfd99a51703ba760f0ef555ae88f36@16.162.207.201:26656" +``` + +Next, you'll need to obtain the network's genesis file. This file contains +the initial state of the blockchain and is crucial for starting from the +correct point. You have two options: + +1. Download directly from the RPC endpoint: `https://rpc.devnet.babylonlabs.io/genesis` + +2. Or use these commands in your terminal: + +```shell +wget https://github.com/babylonlabs-io/networks/raw/main/bbn-test-5/genesis.tar.bz2 # TODO: update this file name if necessary +tar -xjf genesis.tar.bz2 && rm genesis.tar.bz2 +mv genesis.json ~/.babylond/config/genesis.json +``` + +>Note: Verify that the `chain-id` in the genesis file matches the one used in +your initialization command (`bbn-test-5`). This ensures your node connects +to the correct network. + +## Setup the required keys for operating a validator + +### Keys for a CometBFT validator + +The validator key is a fundamental component of your validator's identity +within the Babylon network. This cryptographic key-pair serves multiple critical +functions: it signs blocks during the consensus process, validates transactions, +and manages your validator's operations on the network. Creating and securing this +key is one of the most important steps in setting up your validator. + +To generate your validator key, use the following command: + +```shell +babylond --keyring-backend test keys add --home +``` +We use `--keyring-backend test`, which specifies which backend to use for the +keyring, `test` stores keys unencrypted on disk. + +There are three options for the keyring backend: + +`test`: Stores keys unencrypted on disk. It’s meant for testing purposes and +should never be used in production. +`file`: Stores encrypted keys on disk, which is a more secure option than test but +less secure than using the OS keyring. +`os`: Uses the operating system's native keyring, providing the highest level of +security by relying on OS-managed encryption and access controls. + +The `` specifies a unique identifier for the key. + +The execution result displays the address of the newly generated key and its +public key. Following is a sample output for the command: + +```shell +- address: bbn1kvajzzn6gtfn2x6ujfvd6q54etzxnqg7pkylk9 +name: +pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey", +key: "Ayau+8f945c1iQp9tfTVaCT5lzhD8n4MRkZNqpoL6Tpo"}' +type: local +``` + +Make sure to securely store this information, particularly your address and +private key details. Losing access to these credentials would mean losing +control of your validator and any staked funds. + +### Keys for a BLS Voting +#### What is BLS Voting + +BLS (Boneh-Lynn-Shacham) voting is used to create compact checkpoints at the +end of each epoch. An epoch is a fixed period within the blockchain, defined or +set by a number of blocks, during which a validator set remains consistent. +This stability allows Babylon to create and submit checkpoints only once per +epoch, reducing the overhead of interacting with the Bitcoin blockchain. + +To read more on BLS Voting please see [here](#) # TODO: add link when it is ready + +#### Create BLS Key + +The Babylon network uses BLS (Boneh-Lynn-Shacham) signatures as an efficient +way to create consensus checkpoints at the conclusion of each epoch. As a validator, +you'll need to participate in this process by submitting BLS signatures. +This requires a special BLS key pair that's separate from your validator key. + +To generate your BLS key, you'll use your validator address from the previous step. +Run this command: + +```shell +babylond create-bls-key
+``` + +Replace `
` with your validator address from the earlier keyring +generation (it should look similar to `bbn1kvajzzn6gtfn2x6ujfvd6q54etzxnqg7pkylk9`). + +The system will automatically: +1. Generate a new BLS key pair +2. Associate it with your validator address +3. Store it in your node's configuration file at +`~/./config/priv_validator_key.json` + +This key will be used automatically by your validator software when it needs +to participate in epoch-end signature collection. The BLS signatures help +create compact, efficient proofs of consensus that can be verified by other +blockchain networks, particularly Bitcoin. + +Important: The `priv_validator_key.json` file contains sensitive key material. +Make sure to backup this file and store it securely, as it's essential for your +validator's operation and cannot be recovered if lost. + +## Sync Node + +We are now ready to sync the node. + +```shell +babylond start --chain-id bbn-test-5 --home --x-crisis-skip-assert-invariants +``` + +Lets go through the flags of the above command: + +- `start`: This is the command to start the Babylon node. +- `--chain-id`: Specifies the ID of the blockchain network you're connecting to. +- `--home`: Sets the directory for the node's data and configuration files and +is dependant on where the files were generated for you from the initialization. +In this case, it's using a directory named "nodeDir" in the current path. +- `--minimum-gas-prices`: This flag sets the minimum gas price for transactions +the node will accept. This can also be manually set in the `app.toml` + +#### Connect to Nodes + +To connect your node to the network, you'll need peer addresses. + + +As mentioned in the configuration step, add these to your `config.toml` +under `persistent_peers` or `seeds`. + +#### Use a Snapshot + +For faster syncing, you can use a snapshot instead of syncing from genesis. +Snapshots are periodic backups of the chain state. Find them at: + + +Note: Always verify snapshot sources and checksums before using them to ensure security. + +## Get Funds + +To create a validator, you'll need some BBN tokens to: +1. Pay for transaction fees (gas) +2. Meet the minimum self-delegation requirement +3. Stake as your initial validator bond + +You can obtain testnet tokens through two methods: + +1. Request funds from the Babylon Testnet Faucet +[here](https://faucet.devnet.babylonlabs.io/) + +2. Join our Discord server and visit the #faucet channel: +[Discord Server](https://discord.com/channels/1046686458070700112/1075371070493831259) + +Note: These are testnet tokens with no real value, used only for testing +and development purposes. The tokens help you experiment with validator +operations without risking real assets. + +## Next Steps + +For information about becoming a Finality Provider in the Babylon network, +see our [Finality Provider Guide](../babylon-validators/README.md). \ No newline at end of file diff --git a/bbn-test-5/babylon-validators/README.md b/bbn-test-5/babylon-validators/README.md new file mode 100644 index 00000000..3f15ce1d --- /dev/null +++ b/bbn-test-5/babylon-validators/README.md @@ -0,0 +1,92 @@ +# Babylon Validator Setup + +Before setting up a validator, you'll need: +1. A fully synced Babylon node. For node setup instructions, see our +[Node Setup Guide](../babylon-node/README.md) +2. Sufficient BBN tokens, which are included in the funding section in the +[Node Setup Guide](../babylon-node/README.md) + +## System Requirements + +Recommended specifications for running a Babylon validator node: +- CPU: Quad Core AMD/Intel (amd64) +- RAM: 32GB +- Storage: 2TB NVMe +- Network: 100MBps bidirectional + +>Note: These are reference specifications for a production validator. +>Requirements may vary based on network activity and your operational needs. + +## Creating Validator + +Unlike traditional Cosmos SDK chains, Babylon uses a specialized validator +creation process that integrates with its checkpointing system. The creation +process requires your previously generated BLS key, which should be located at +`~/.babylond/config/priv_validator_key.json`. + +To create your validator, run the following command: + +```shell +babylond tx checkpointing create-validator \ +./dir//babylond/config/priv_validator_key.json \ +--chain-id bbn-test-5 \ +--gas "auto" \ +--gas-adjustment 1.5 \ +--gas-prices "0.005ubbn" \ +--from +``` + +Upon successful creation, you'll receive a transaction hash and your validator +operator address +(e.g., `bbnvaloper12k7w0mtdqp5yff8hr9gj6xe3uq7hnfhguqyqjg`). + +### Verifying Validator Setup + +1. First, confirm your validator operator address: + +```shell +babylond keys show
-a --bech val + ``` + +2. Then, inspect your validator's details: + +```shell +babylond query staking validator +``` + +You should see your validator's configuration, including: + +```yaml +validator: + commission: + rates: + current: "100000000000000000" + max: "1000000000000000000" + max_change: "10000000000000000" + description: + moniker: "node0" + website: "https://myweb.site" + security_contact: "node0@gmail.com" + status: 1 tokens: "100" +``` + +### Understanding Validator Status + +Your validator enters the active set based on two conditions: 1. The completion +of the current epoch (a network-wide time period for coordinating activities) 2. +Having sufficient stake to qualify for the active set + +When active, your status will show as `BOND_STATUS_BONDED`. + +### Managing Your Validator + +For delegation operations (`delegate`, `redelegate`, `unbond`, `cancel-unbond`), +you must use the wrapped messages in the checkpointing and epoching modules. +This is because standard staking module messages are disabled in Babylon. + +For detailed information about these operations, visit our +[documentation](https://docs.babylonlabs.io/docs/developer-guides/modules/epoching#delaying-wrapped-messages-to-the-end-of-epochs). + +Congratulations! Your validator is now part of the Babylon network. Remember to +monitor your validator's performance and maintain good uptime to avoid +penalties.