diff --git a/blog/2025/06-02-2025-welcome.mdx/06-02-2025-welcome.mdx b/blog/2025/06-02-2025-welcome.mdx/06-02-2025-welcome.mdx new file mode 100644 index 00000000..2f6f901d --- /dev/null +++ b/blog/2025/06-02-2025-welcome.mdx/06-02-2025-welcome.mdx @@ -0,0 +1,8 @@ +--- +title: Babylon Dev Blogs +date: 2025-06-02 +--- + +# Babylon Dev Blogs + +Welcome to Babylon deveveloper blogs. This is where you can find the latest news and technical updates from the Babylon Labs team. \ No newline at end of file diff --git a/docs/developers/bsns/cosmos_chains/cosmos_chains.mdx b/docs/developers/bsns/cosmos_chains/cosmos_chains.mdx index 982ea3b9..481ba4d6 100644 --- a/docs/developers/bsns/cosmos_chains/cosmos_chains.mdx +++ b/docs/developers/bsns/cosmos_chains/cosmos_chains.mdx @@ -22,11 +22,13 @@ for example, X→ Y means "Y queries data from X and the data flows from X to Y" dark: useBaseUrl('/img/cosmos-integration.png'), }} /> +
The design involves the following main components: -- **Finality Provider:** a daemon program that receives BTC stake and keeps submitting -finality signatures over blocks to the BSN chain. +### Finality Provider + +A daemon program that receives BTC stake and keeps submitting finality signatures over blocks to the BSN chain. - It connects to a BSN chain node to query block metadata. - It connects to the Babylon contracts on the BSN chain for querying voting power and submitting finality signatures. @@ -38,8 +40,9 @@ Upon a new block in the BSN chain, it: voting power at this height. - If yes, sign and submit a finality signature to the Babylon contracts. -- **Babylon Contracts:** a set of CosmWasm smart contracts that maintains IBC channels -with Babylon and handles finality signatures submitted from Finality Providers +### Babylon Contracts + +A set of CosmWasm smart contracts that maintains IBC channels with Babylon and handles finality signatures submitted from Finality Providers - It will be deployed on the BSN chain. - It establishes an IBC channel with Babylon. The IBC channel relays information about BTC light clients, BTC timestamps and BTC staking. @@ -53,8 +56,9 @@ Upon a finality signature, the Babylon contracts verify it: packet to Babylon. Then Babylon emits an event so anyone can slash the Finality Provider and the BTC stake under it. -- **Babylon-SDK:** a small Cosmos SDK module serving as a thin layer between Babylon -contracts and Cosmos SDK level of the BSN chain. +### Babylon-SDK + +A small Cosmos SDK module serving as a thin layer between Babylon contracts and Cosmos SDK level of the BSN chain. - It sends a sudo message to the Babylon contracts upon each `BeginBlock` , so that Babylon contracts can update voting power table and tally blocks. - It moves a part of the reward from the fee collector account to Babylon contracts, diff --git a/docs/developers/bsns/op_stack_chains/op_stack_chains.mdx b/docs/developers/bsns/op_stack_chains/op_stack_chains.mdx index 9e681c8b..3bb06136 100644 --- a/docs/developers/bsns/op_stack_chains/op_stack_chains.mdx +++ b/docs/developers/bsns/op_stack_chains/op_stack_chains.mdx @@ -21,10 +21,12 @@ The design involves the following main components: light: useBaseUrl('/img/op-stack-integration.png'), dark: useBaseUrl('/img/op-stack-integration.png'), }} -/>; +/> +
-- **Finality Provider:** a daemon program that receives BTC stake and keeps -submitting finality signatures over L2 blocks to the finality contract on Babylon. +### Finality Provider + +A daemon program that receives BTC stake and keeps submitting finality signatures over L2 blocks to the finality contract on Babylon. - It connects to a Babylon node to query its voting power. - It connects to the finality contract via the Babylon node for submitting finality signatures. @@ -35,7 +37,10 @@ Upon a new L2 block in the OP-stack chain, It: - Gets the L2 block metadata. - Queries Babylon Genesis to determine whether it has voting power at this L2 block height. - If yes, sign and submit a finality signature to the finality contract. -- **Finality contract:** a CosmWasm smart contract that maintains all finality signatures submitted from OP-stack Finality Providers. + +### Finality Contract + +A CosmWasm smart contract that maintains all finality signatures submitted from OP-stack Finality Providers. - It will be deployed on Babylon Genesis. - It will query Babylon Genesis to determine the Finality Provider’s status and voting power. @@ -44,7 +49,10 @@ Upon a finality signature, the finality contract verifies it and identifies equi - If invalid, reject. - If valid and non-conflicting with any existing ones, accept. - If valid but conflicting with an existing finality signature, it emits an event so anyone can slash the Finality Provider and the BTC stake under it. -- **Finality gadget**: a daemon program that keeps tallying all finality signatures for L2 blocks and serves RPC to allow querying the BTC-voting quorum of those blocks. + +### Finality Gadget + +A daemon program that keeps tallying all finality signatures for L2 blocks and serves RPC to allow querying the BTC-voting quorum of those blocks. - It connects to a Babylon node for querying the voting power of Finality Providers. - It connects to the finality contract via the Babylon node for querying finality signatures. - It connects to an RPC of the OP stack chain to get L2 block metadata. @@ -55,7 +63,10 @@ Upon a new L2 block in the OP-stack chain, it: - Queries Babylon to get all Finality Providers’ BTC delegations for this chain and use the L2 block’s timestamp to determine the voting power distribution among all its Finality Providers at the time of this block. - Tallies finality signatures and determines whether the L2 block receives a quorum. - If this L2 block receives a quorum and its parent block is also BTC staking-finalized, marks it as BTC staking-finalized and stores it in the finality gadget’s local database. -- **OP node with finality gadget:** a modified OP node that enforces BTC-voting quorum before finalizing L2 blocks. + +### OP Node with Finality Gadget + +A modified OP node that enforces BTC-voting quorum before finalizing L2 blocks. - It connects to the finality gadget for querying consecutive BTC-voting quorums to determine the finalization status of the L2 blocks. - It notifies OP-geth about the L2 blocks’ finalization status to move the L2 finalized block head. @@ -74,13 +85,13 @@ We have finished the reference implementation. The codebases include: - [btc-staker](https://github.com/babylonlabs-io/btc-staker/tree/base/consumer-chain-support): The BTC Staker program - [babylon-contract](https://github.com/babylonlabs-io/babylon-contract): The CosmWasm contracts, including the finality contract for OP-stack chains. - [finality-gadget](https://github.com/babylonlabs-io/finality-gadget): The finality gadget program. It can be used by OP node or user as an SDK or run as a standalone daemon program. -- [optimism](https://github.com/babylonlabs-io/optimism/tree/feat/babylon-rfc): The fork of OP Stack codebase that installs finality-gadget. +- [optimism](https://github.com/babylonlabs-io/op-finality-gadget): The fork of OP Stack codebase that installs finality-gadget. ## Local deployments We have developed local deployment scripts for the OP stack integration. - https://github.com/Snapchain/babylon-deployment for spinning up an OP stack chain integrating with Babylon Euphrates devnet -- https://github.com/Snapchain/op-chain-deployment for spinning up the entire stack (OP stack chain + ETH L1 + Babylon + Bitcoin) +- https://github.com/Snapchain/op-chain-deployment for spinning up the entire stack (OP stack chain + ETH L1 + Babylon Genesis + Bitcoin) --- diff --git a/docs/guides/architecture/babylon_genesis_modules/btc_checkpointing.mdx b/docs/guides/architecture/babylon_genesis_modules/btc_checkpointing.mdx index acaa0105..865165b0 100644 --- a/docs/guides/architecture/babylon_genesis_modules/btc_checkpointing.mdx +++ b/docs/guides/architecture/babylon_genesis_modules/btc_checkpointing.mdx @@ -12,9 +12,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/btccheckpoint/README.md"; diff --git a/docs/guides/architecture/babylon_genesis_modules/btc_lightclient.mdx b/docs/guides/architecture/babylon_genesis_modules/btc_lightclient.mdx index f599b5b9..025e19e0 100644 --- a/docs/guides/architecture/babylon_genesis_modules/btc_lightclient.mdx +++ b/docs/guides/architecture/babylon_genesis_modules/btc_lightclient.mdx @@ -12,9 +12,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/btclightclient/README.md"; diff --git a/docs/guides/architecture/babylon_genesis_modules/btc_staking.mdx b/docs/guides/architecture/babylon_genesis_modules/btc_staking.mdx index a0baaddc..9a5f28ff 100644 --- a/docs/guides/architecture/babylon_genesis_modules/btc_staking.mdx +++ b/docs/guides/architecture/babylon_genesis_modules/btc_staking.mdx @@ -12,9 +12,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/btcstaking/README.md"; diff --git a/docs/guides/architecture/babylon_genesis_modules/checkpointing.mdx b/docs/guides/architecture/babylon_genesis_modules/checkpointing.mdx index 6202eef1..115e1fee 100644 --- a/docs/guides/architecture/babylon_genesis_modules/checkpointing.mdx +++ b/docs/guides/architecture/babylon_genesis_modules/checkpointing.mdx @@ -12,9 +12,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/checkpointing/README.md"; diff --git a/docs/guides/architecture/babylon_genesis_modules/epoching.mdx b/docs/guides/architecture/babylon_genesis_modules/epoching.mdx index 4c5a2ebd..78c1ee08 100644 --- a/docs/guides/architecture/babylon_genesis_modules/epoching.mdx +++ b/docs/guides/architecture/babylon_genesis_modules/epoching.mdx @@ -12,9 +12,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/epoching/README.md"; diff --git a/docs/guides/architecture/babylon_genesis_modules/finality.mdx b/docs/guides/architecture/babylon_genesis_modules/finality.mdx index 6f8540e0..882abc6f 100644 --- a/docs/guides/architecture/babylon_genesis_modules/finality.mdx +++ b/docs/guides/architecture/babylon_genesis_modules/finality.mdx @@ -12,9 +12,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/finality/README.md"; diff --git a/docs/guides/architecture/btc_staking_program/btc_reorg_procedure.mdx b/docs/guides/architecture/btc_staking_program/btc_reorg_procedure.mdx index a5be361d..75a7980d 100644 --- a/docs/guides/architecture/btc_staking_program/btc_reorg_procedure.mdx +++ b/docs/guides/architecture/btc_staking_program/btc_reorg_procedure.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/btcstaking/docs/btc-reorg.md"; diff --git a/docs/guides/architecture/btc_staking_program/finality_providers.mdx b/docs/guides/architecture/btc_staking_program/finality_providers.mdx index d9eed305..91c1cd50 100644 --- a/docs/guides/architecture/btc_staking_program/finality_providers.mdx +++ b/docs/guides/architecture/btc_staking_program/finality_providers.mdx @@ -11,9 +11,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/finality-provider/refs/heads/main/README.md"; \ No newline at end of file diff --git a/docs/guides/architecture/consumer_zone_programs/babylon_contracts.mdx b/docs/guides/architecture/consumer_zone_programs/babylon_contracts.mdx index e8334940..fa49500d 100644 --- a/docs/guides/architecture/consumer_zone_programs/babylon_contracts.mdx +++ b/docs/guides/architecture/consumer_zone_programs/babylon_contracts.mdx @@ -32,10 +32,7 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon-contract/refs/heads/main/README.md"; diff --git a/docs/guides/architecture/consumer_zone_programs/zone_concierge.mdx b/docs/guides/architecture/consumer_zone_programs/zone_concierge.mdx index 9b8e388c..51e4d4ca 100644 --- a/docs/guides/architecture/consumer_zone_programs/zone_concierge.mdx +++ b/docs/guides/architecture/consumer_zone_programs/zone_concierge.mdx @@ -12,9 +12,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/zoneconcierge/README.md"; diff --git a/docs/guides/baby_stakers/baby_staking_cli.mdx b/docs/guides/baby_stakers/baby_staking_cli.mdx index 019b33a7..84b7f2eb 100644 --- a/docs/guides/baby_stakers/baby_staking_cli.mdx +++ b/docs/guides/baby_stakers/baby_staking_cli.mdx @@ -1,6 +1,6 @@ --- sidebar_class_name: baby_staking_cli_sidebar -sidebar_position: 4 +sidebar_position: 5 --- # BABY Staking CLI Guide diff --git a/docs/guides/baby_stakers/baby_staking_integration.mdx b/docs/guides/baby_stakers/baby_staking_integration.mdx index c79e2fce..4e19fcce 100644 --- a/docs/guides/baby_stakers/baby_staking_integration.mdx +++ b/docs/guides/baby_stakers/baby_staking_integration.mdx @@ -1,7 +1,7 @@ --- title: BABY Staking Integration sidebar_label: BABY Staking Integration -sidebar_position: 4 +sidebar_position: 6 --- # BABY Staking Integration diff --git a/docs/guides/baby_stakers/baby_staking_via_mintscan.mdx b/docs/guides/baby_stakers/baby_staking_via_mintscan.mdx new file mode 100644 index 00000000..6058cb24 --- /dev/null +++ b/docs/guides/baby_stakers/baby_staking_via_mintscan.mdx @@ -0,0 +1,160 @@ +--- +sidebar_class_name: baby_staking_cli_sidebar +sidebar_position: 4 +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +# BABY Staking via Mintscan +A step-by-step guide to staking BABY tokens on the Babylon Genesis mainnet using +Mintscan. + +## Prerequisites +Before you start, make sure you have: +- a crypto wallet compatible with Mintscan installed on your browser +- a Babylon Genesis mainnet wallet created +- acquired BABY tokens + +## Step by Step guide + +### 1. Access Mintscan + +Open the Mintscan website: [Mintscan](https://www.mintscan.io). + +### 2. Navigate to the Staking Page + +2.1. On the homepage, click on **"Stake"** from the left navigation bar. This will +take you to the staking page. + + + +### 3. Connect Your Wallet + +3.1. On staking page it will prompt you to **connect your wallet**. Click on the +option to connect your wallet. + + +3.2. Select the digital wallet you prefer to use using. As an example **Keplr** is +used in this guide. + +3.3. Follow the prompts to complete the connection on your wallet. + + +### 4. Select BABY Token + +4.1. After connecting your wallet, you will need to select BABY token for staking. + + + +### 5. Choose a Validator + +5.1. Browse through validators list and select the one you want to delegate to. You +can refer to Mintscan's [Validator Summary](https://www.mintscan.io/babylon/validators) +page to get more information about their ranking and performances. Higher commission +rate means less BABY staking rewards for you. + + + +### 6. Enter the Staking Amount + +6.1. Enter the amount of BABY tokens you want to stake. + + + +### 7. Submit the Transaction + +7.1. After entering the staking amount, click the **"Stake"** button to submit the +transaction. + + + +2. A success message will appear on the next page, confirming that your +transaction has been successfully submitted. + + + +### 8. Monitor Your Investment + +8.1. You can return to the staking page to view the status of your staking. Staking +information is also listed on Mintscan's [Babylon page](https://www.mintscan.io/babylon). + +8.2. Regularly check your rewards and staking activities to ensure everything is in +order. + + + +### 9. Claim rewards + +9.1. The reward will be accumulated over time per Babylon Genesis block.You can +claim your rewards by clicking the **"Claim"** button on your crypto wallet. + +### Conclusion + +By following these steps, you can easily stake on Mintscan. By doing this, you are +contributing to the security and stability of the Babylon Genesis mainnet and you +also earn staking rewards in BABY. + +If you have any questions or need further assistance, please contact us on +[Discord](https://discord.com/invite/babylonglobal) or contact the maintainer +[Cosmostation](https://cosmostation.io) at [support@cosmostation.io](mailto:support@cosmostation.io) +for support! \ No newline at end of file diff --git a/docs/guides/btc_stakers/btc_staking_tools.mdx b/docs/guides/btc_stakers/btc_staking_tools.mdx index 2304e4b8..e27b9211 100644 --- a/docs/guides/btc_stakers/btc_staking_tools.mdx +++ b/docs/guides/btc_stakers/btc_staking_tools.mdx @@ -51,7 +51,7 @@ import HardwareBadge from '@site/src/components/badge/hardware'; | Xverse | ❌ | ❌ | | Gate wallet | ✅ | ✅ | | Unisat Wallet | ✅ | ✅ | - | Keplr | ❌ | ❌ | + | Keplr | ✅ | ✅ | | Cosmostation | ✅ | ✅ | | Leap wallet | ✅ | ✅ | | Imtoken | ❌ | ❌ | diff --git a/docs/guides/btc_stakers/native_staking/web_staking.mdx b/docs/guides/btc_stakers/native_staking/web_staking.mdx index 36d85332..d508ed1c 100644 --- a/docs/guides/btc_stakers/native_staking/web_staking.mdx +++ b/docs/guides/btc_stakers/native_staking/web_staking.mdx @@ -195,7 +195,7 @@ will be active. | OneKey | ✅ | ✅ | | BitGet | ✅ | ✅ | | Leap | ✅ | ✅ | -| Keplr | ❌ | ❌ | +| Keplr | ✅ | ✅ | | Cosmostation | ✅ | ✅ | | Tomo | ✅ | ✅ | | Xverse | ❌ | ❌ | diff --git a/docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee.mdx b/docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee.mdx index b85a8147..77da0f87 100644 --- a/docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee.mdx +++ b/docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee.mdx @@ -14,11 +14,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/covenant-committee/README.md"; diff --git a/docs/guides/networks/phase-1/mainnet/finality_provider_registration.mdx b/docs/guides/networks/phase-1/mainnet/finality_provider_registration.mdx index 0a44eef4..cc2e4f0e 100644 --- a/docs/guides/networks/phase-1/mainnet/finality_provider_registration.mdx +++ b/docs/guides/networks/phase-1/mainnet/finality_provider_registration.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/finality-providers/README.md"; diff --git a/docs/guides/networks/phase-1/mainnet/global_parameters.mdx b/docs/guides/networks/phase-1/mainnet/global_parameters.mdx index 9b51069d..aae00933 100644 --- a/docs/guides/networks/phase-1/mainnet/global_parameters.mdx +++ b/docs/guides/networks/phase-1/mainnet/global_parameters.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/parameters/README.md"; diff --git a/docs/guides/networks/phase-1/testnet/covonent_committee/covonent_committee.mdx b/docs/guides/networks/phase-1/testnet/covonent_committee/covonent_committee.mdx index 7a545ec8..1c0362c8 100644 --- a/docs/guides/networks/phase-1/testnet/covonent_committee/covonent_committee.mdx +++ b/docs/guides/networks/phase-1/testnet/covonent_committee/covonent_committee.mdx @@ -14,9 +14,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonchain/networks/refs/heads/main/bbn-test-4/covenant-committee/README.md"; diff --git a/docs/guides/networks/phase-1/testnet/finality_provider_registration.mdx b/docs/guides/networks/phase-1/testnet/finality_provider_registration.mdx index 15e975b0..d8cb6246 100644 --- a/docs/guides/networks/phase-1/testnet/finality_provider_registration.mdx +++ b/docs/guides/networks/phase-1/testnet/finality_provider_registration.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonchain/networks/refs/heads/main/bbn-test-4/finality-providers/README.md"; diff --git a/docs/guides/networks/phase-1/testnet/global_parameters.mdx b/docs/guides/networks/phase-1/testnet/global_parameters.mdx index b1d4e775..e3f4583f 100644 --- a/docs/guides/networks/phase-1/testnet/global_parameters.mdx +++ b/docs/guides/networks/phase-1/testnet/global_parameters.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonchain/networks/refs/heads/main/bbn-test-4/parameters/README.md"; diff --git a/docs/guides/networks/phase-2/mainnet/mainnet.mdx b/docs/guides/networks/phase-2/mainnet/mainnet.mdx index 821e4ce0..b7234af5 100644 --- a/docs/guides/networks/phase-2/mainnet/mainnet.mdx +++ b/docs/guides/networks/phase-2/mainnet/mainnet.mdx @@ -13,10 +13,7 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/README.md"; diff --git a/docs/guides/networks/phase-2/testnet/testnet.mdx b/docs/guides/networks/phase-2/testnet/testnet.mdx index ed7a4854..cc766070 100644 --- a/docs/guides/networks/phase-2/testnet/testnet.mdx +++ b/docs/guides/networks/phase-2/testnet/testnet.mdx @@ -13,10 +13,7 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-test-5/README.md"; diff --git a/docs/guides/networks/phase-3/devnet/devnet.mdx b/docs/guides/networks/phase-3/devnet/devnet.mdx index 3126c851..9d060df0 100644 --- a/docs/guides/networks/phase-3/devnet/devnet.mdx +++ b/docs/guides/networks/phase-3/devnet/devnet.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/jenks/add-phase-3-devnet-parameters/euphrates-0.5.0/README.md"; diff --git a/docs/guides/overview/phases_of_the_launch/phase-2/eligibility.mdx b/docs/guides/overview/phases_of_the_launch/phase-2/eligibility.mdx index 9e039380..3ea9edc3 100644 --- a/docs/guides/overview/phases_of_the_launch/phase-2/eligibility.mdx +++ b/docs/guides/overview/phases_of_the_launch/phase-2/eligibility.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/x/btcstaking/docs/registration-eligibility.md"; \ No newline at end of file diff --git a/docs/guides/overview/phases_of_the_launch/phase-2/registration.mdx b/docs/guides/overview/phases_of_the_launch/phase-2/registration.mdx index 5ae98b9a..5f0738ae 100644 --- a/docs/guides/overview/phases_of_the_launch/phase-2/registration.mdx +++ b/docs/guides/overview/phases_of_the_launch/phase-2/registration.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/docs/register-bitcoin-stake.md"; \ No newline at end of file diff --git a/docs/guides/security/audit_reports.mdx b/docs/guides/security/audit_reports.mdx index 71a17ee9..f3284212 100644 --- a/docs/guides/security/audit_reports.mdx +++ b/docs/guides/security/audit_reports.mdx @@ -103,4 +103,31 @@ Audits for the Babylon Genesis Chain are conducted by [Coinspect](https://www.co +### Babylon Genesis v2 Audits +Audits for the [Babylon Genesis v2 Upgrade](https://babylonlabs.io/blog/babylon-genesis-v2-upgrade) are conducted by [Oak Security GmbH](https://oaksecurity.io/) and [Informal Systems](https://informal.systems/). + + + + {() => ( + + )} + + + {() => ( + + )} + + diff --git a/docs/guides/specifications/bitcoin_staking_scripts.mdx b/docs/guides/specifications/bitcoin_staking_scripts.mdx index 523f2e38..2762b064 100644 --- a/docs/guides/specifications/bitcoin_staking_scripts.mdx +++ b/docs/guides/specifications/bitcoin_staking_scripts.mdx @@ -7,323 +7,16 @@ sidebar_position: 3 # Bitcoin Staking Scripts -## Introduction - -Babylon's BTC staking protocol turns Bitcoin into a staking asset with the aim -to enhance the economic security of Babylon Genesis. Bitcoin holders can stake -their Bitcoin by locking them using a special transaction on the Bitcoin chain. -The locked Bitcoin contributes to Babylon Genesis's economic security and generates -yields for the Bitcoin stakers. -The protocol has the following important properties: - -1. Staking is trustless and self-custodial, meaning it does not require - bridging, wrapping, 3rd-party custody/multi-sig, or oracles. -2. The stake voting power is delegatable, a common feature of Delegated PoS - (DPoS) protocols. -3. Stake security: the staked Bitcoin is slashed if and only if the BTC Staker - itself (and in the case of delegation, its delegatee) is malicious. This implies - that, even if Babylon Genesis is compromised and taken over by malicious - actors, as long as the BTC Staker itself (and the validator it delegates to - in case of delegation) is not malicious, its bitcoin stake is secure. -4. The protocol supports fractional slashing, meaning the protocol can be - configured so that when slashing happens, only a fraction of the staked - bitcoins are slashed, and the rest is returned to the staker. -5. The protocol allows stakers to on-demand unbond. On-demand unbonding; means - the BTC staker can withdraw from staking with an unbonding delay. -6. Atomic slashing; means that if a delegator is slashed, then all the - delegators of the same delegatee, including the delegatee's self-delegation, - will be subject to slashing. In other words, the delegatee cannot - selectively harm any specific delegator. -7. (WIP) Restakable; means that the same Bitcoin can be staked to secure - multiple PoS chains and earn multiple PoS yields - -In the entire Bitcoin staking process, two parties are involved: one is called -the Bitcoin Staker, and the other is called the Finality Provider. - -- **Bitcoin Staker**: A Bitcoin Staker is an entity identified by `` -in staking scripts. Note that a staking transaction can be funded from -arbitrary UTXO, including those owned by multisig/MPC/threshold accounts. -Thus, `` is not necessarily the address of the source of the fund. -Rather, it is the controller and beneficiary of the stake after its creation. -- **Finality Provider**: A Finality Provider is an entity that votes -in the finality round to provide security assurance to the PoS chain. - -The Bitcoin Staker can choose a specific Finality Provider to delegate -their voting power derived from their locked Bitcoin. - -The key to making all these possible is the special construction of BTC -transactions using BTC scripts. - -## Preliminary - -Babylon interaction with Bitcoin is heavily based on Bitcoin's -[Taproot upgrade](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki). -This design choice was made due to the heavy usage of -[Schnorr signatures](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki) -that were introduced through the Taproot upgrade. - -## Staking Flow - -The following diagram shows how different transactions described in the following -paragraphs create and spend different Bitcoin outputs: - -```mermaid -stateDiagram-v2 - active: Staking output - unbonding: Unbonding output - state stake_slashing <> - state unbonding_slashing <> - burn_staking: Burn address output - change_staking: Change output - burn_unbonding: Burn address output - change_unbonding: Change output - - [*] --> active: Staking transaction - - active --> unbonding: Unbonding transaction - - unbonding --> [*]: Unbonding withdrawal transaction - - unbonding --> unbonding_slashing: Slashing transaction - unbonding_slashing --> burn_unbonding - unbonding_slashing --> change_unbonding - change_unbonding --> [*]: Withdrawal transaction - - active --> [*]: Staking withdrawal transaction - - active --> stake_slashing: Slashing transaction - - stake_slashing --> burn_staking - stake_slashing --> change_staking - change_staking --> [*]: Withdrawal transaction -``` - -Withdrawal transactions are BTC transactions which transfer Bitcoins to the BTC -Staker wallet. - -## Types of special transactions - -There are three special transaction types recognized by Babylon Genesis: - -- Staking Transaction -- Unbonding Transaction -- Slashing Transaction - -### Staking Transaction - -The BTC Staker gains voting power by creating a staking transaction. This is a -Bitcoin transaction that commits a certain amount of to-be-staked Bitcoin to -Babylon-recognized BTC staking scripts. These scripts lock the stake for a -chosen amount of BTC blocks and enable other features such as unbonding and -slashable safety. - -The requirements for a valid staking transaction are: - -- It can contain an arbitrary number of inputs. -- It can contain an arbitrary number of outputs. One of those outputs must be - a Taproot output committing to the BTC staking scripts recognized by Babylon. - Henceforth known as `Staking Output`. - -### Unbonding Transaction - -The BTC Staker utilizes the unbonding transaction when they want to unlock -their stake before their originally committed timelock has expired. - -The requirements for a valid unbonding transaction are: - -- It contains exactly one input which points to the staking transaction's `Staking -Output`. -- It contains exactly one output which must be a Taproot output committing to - the BTC unbonding scripts recognized by Babylon. Henceforth known as `Unbonding -Output`. - -### Slashing Transaction - -The slashing transaction is used to punish a BTC Staker when they (or the -Finality Provider they have delegated to) perform an offense. - -The requirements for a valid slashing transaction are: - -- It must have exactly one input pointing to either the staking output or the - unbonding output. -- It must have exactly two outputs, the first sending the slashed fraction of - the funds to a burn address specified in the Babylon Genesis's parameters, and the - second sending the remaining funds to an output which can be unlocked by the staker - after the timelock. -- The fee for the slashing transactions must be larger than or equal to the - minimal fee specified in Babylon's parameters - -## Staking and Unbonding output scripts - -In the scripts below, there are three entities, each represented by a BTC public -key: - -- `StakerPK` - BTC Staker public key. -- `FinalityProviderPk` - Finality Provider public key. -- `CovenantPk1..CovenantPkN` - public keys of covenant committee members -There must be no duplicated public keys in created scripts. -For example, `StakerPK` must never be equal to `FinalityProviderPk`. - -### Staking output - -The staking output is a Taproot output which can only be spent through a script -spending path. -The key spending path is disabled by using the "Nothing Up My Sleeve" -(NUMS) point as internal key. Chosen point is the one described in -[BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#constructing-and-spending-taproot-outputs) -i.e, - -``` -H = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0) -``` - -which is a point constructed by taking the hash of the standard uncompressed -encoding of the secp256k1 base point `G` as the X coordinate. - -The staking output can be spent by three script spending paths. - -#### 1. Timelock path - -The timelock path locks the staker's Bitcoin for a pre-determined number of -Bitcoin blocks. It commits to a script of the form: - -``` - OP_CHECKSIGVERIFY OP_CHECKSEQUENCEVERIFY -``` - -where: - -- `` is the BTC Staker's public key. -- `` is the lockup period denoted in Bitcoin blocks. The - timelock comes into effect after the Bitcoin transaction has been included in a - mined block. In essence, the script denotes that only the staker can unlock the - funds after the timelock has passed. It must be lower than `65535`. - -#### 2. Unbonding path - -The unbonding path allows the staker to on-demand unlock their locked Bitcoin -before the timelock expires. It commits to a script of the form: - -``` - OP_CHECKSIGVERIFY - OP_CHECKSIG OP_CHECKSIGADD ... OP_CHECKSIGADD - OP_NUMEQUAL -``` - -where: - -- `StakerPK` is the BTC staker's public key. -- `CovenantPk1..CovenantPkN` are the lexicographically sorted public keys of the - current covenant committee recognized by Babylon Genesis. -- `CovenantThreshold` is a Babylon parameter specifying how many - covenant committee member signatures are required. - -Signatures from a quorum of the covenant committee are required to ensure that -this script is not used for on-demand unlocking without the stake going through -an unbonding period. Reward all covenant members for their work. - -#### 3. Slashing path - -The slashing path is utilized for punishing Finality Providers and their -delegators in the case of double signing. It commits to a script: - -``` - OP_CHECKSIGVERIFY - OP_CHECKSIGVERIFY - OP_CHECKSIG OP_CHECKSIGADD ... OP_CHECKSIGADD - OP_NUMEQUAL -``` - -where: - -- `StakerPK` is the BTC Staker's public key. -- `FinalityProviderPk` is the BTC public key of the Finality Provider to which - the staker delegates their stake -- `CovenantPk1..CovenantPkN` are the lexicographically sorted public keys of the - current covenant committee members recognized by Babylon Genesis. -- `CovenantThreshold` is a Babylon parameter denoting how many covenant - committee member signatures are required. - -This path can only be executed with the collaboration of the BTC Staker, -Finality Provider, and covenant committee. -It is used in following way: - -- For stake to become active, staker must publish pre-signed slashing transaction. -- The covenant committee validates such transaction, and publish its own signatures. -- The only signature missing to send the slashing transaction is Finality Provider - signature. If the Finality Provider private key leaks due to infractions, anyone can - sign slashing transaction and send slashing transaction to Bitcoin network. - -#### Difference between Unbonding and Slashing Path - -The main difference between the unbonding and slashing paths is the existence of -`FinalityProviderPk` in the slashing path. - -This leads to following system wide repercussions: - -- For staking request to become active, BTC Staker needs to provide valid - unbonding transaction in this staking request. This staking request will become - active only when the `CovenantThreshold` signatures are received by the Babylon - chain. The lack of `FinalityProviderPk` in the unbonding path, means that after - delegation becomes active, staker can send an unbonding transaction at any time - without asking the Finality Provider for permission. -- The existence of `FinalityProviderPk` in the slashing path, coupled with the fact that - BTC Staker needs to provide pre-signed slashing transaction which needs to be - signed by covenant committee for delegation request to become active, leads to - situation in which the only signature missing to send slashing transaction to - BTC is signature of Finality Provider. - -### Unbonding output - -Unbonding output is a Taproot output which can be only spent through script -spending path. The key spending path is disabled by using "Nothing Up My Sleeve" -(NUMS) point as internal key. Chosen point is the one described in BIP341 i.e H -= lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0) -which is point constructed by taking the hash of the standard uncompressed -encoding of the secp256k1 base point G as X coordinate. - -Unbonding output can be spent by two script spending paths. - -#### 1. Timelock path - -The timelock path locks the staker's Bitcoin for a pre-determined number of -Bitcoin blocks. It commits to a script of the form: - -``` - OP_CHECKSIGVERIFY OP_CHECKSEQUENCEVERIFY` -``` - -where: - -- `` is BTC Staker public key. -- `` is unbonding time. It must be lower or equal 65535, but larger - than `max(MinUnbondingTime, CheckpointFinalizationTimeout)`. `MinUnbondingTime` - and `CheckpointFinalizationTimeout` are Babylon parameters. - -#### 2. Slashing path - -The slashing path is utilized for punishing Finality Providers and their -delegators in the case of double signing. It commits to a script: - -``` - OP_CHECKSIGVERIFY - OP_CHECKSIGVERIFY - OP_CHECKSIG OP_CHECKSIGADD ... OP_CHECKSIGADD - OP_NUMEQUAL -``` - -where: - -- `StakerPK` is the BTC Staker's public key. -- `FinalityProviderPk` is the BTC public key of the Finality Provider to which - the staker delegates their stake. -- `CovenantPk1..CovenantPkN` are the lexicographically sorted public keys of the - current covenant committee members recognized by Babylon Genesis. -- `CovenantThreshold` is a Babylon parameter denoting how many covenant - committee member signatures are required. - -#### Existence of Slashing path in Unbonding output - -The fact that slashing path exists in unbonding output means that even if staker -is unbonding, he can be slashed if the finality provider commits an infraction during -unbonding time. +import RemoteMD from '@site/src/components/RemoteMD'; + +export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/docs/staking-script.md"; + + \ No newline at end of file diff --git a/docs/guides/specifications/staking_transactions.mdx b/docs/guides/specifications/staking_transactions.mdx index 1e10be6a..c3b576c6 100644 --- a/docs/guides/specifications/staking_transactions.mdx +++ b/docs/guides/specifications/staking_transactions.mdx @@ -4,378 +4,19 @@ sidebar_label: Staking Transactions sidebar_position: 1 --- -# Staking Transactions +# Observable Staking Transactions Specification -Specification of all the transactions, which is for those who want to construct Bitcoin staking related transactions by themselves instead of using our code or dapps. +import RemoteMD from '@site/src/components/RemoteMD'; -## Introduction +export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/refs/heads/main/docs/transaction-impl-spec.md"; -A lock-only network involves users locking their Bitcoin using the self-custodial -Bitcoin Staking script without a Babylon Genesis operating. -In this document, we precisely define how one can construct -the Bitcoin transactions specified by the Bitcoin Staking protocol. + -## Prerequisites - -- [Scripts doc](/guides/specifications/bitcoin_staking_scripts) - a document which defines how different -Bitcoin Staking scripts look like -- [BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) - -a document specifying how to spend Taproot outputs - -## System parameters - -The lock-only staking protocol is governed by a set of parameters that specify -what constitutes a valid staking transaction. Based on those, -an observer of the Bitcoin ledger can precisely identify which transactions -are valid staking transactions and whether they should be considered active stake. -These parameters are different depending on the Bitcoin height a transaction is -included in and a constructor of a Bitcoin Staking transaction should take them into -account before propagating a transaction to Bitcoin. -For the rest of the document, we will refer to those parameters as `global_parameters`. - -More details about parameters can be found in the -[parameters spec](https://github.com/babylonchain/networks/tree/main/bbn-test-4/parameters). - -## Taproot outputs - -Taproot outputs are outputs whose locking script is an elliptic curve point `Q` -created as follows: -``` -Q = P + hash(P||m)G -``` -where: -- `P` is the internal public key -- `m` is the root of a Merkle tree whose leaves consist of a version number and a -script - -For Bitcoin Staking transactions, the internal public key is chosen as: - -``` -P = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0) -``` - -This key is described in the -[BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#constructing-and-spending-taproot-outputs) -specification. - -The use of this key as an internal public key disables spending from Taproot output -through the key spending path. -The construction of this key can be found [here](https://github.com/babylonlabs-io/babylon/blob/main/btcstaking/types.go?plain=1#L27). - -## Observable Staking Transactions - -### Staking transaction - -A staker enters the protocol through the creation of a staking transaction -which locks Bitcoin in the Bitcoin Staking script. - -#### Requirements - -For the transaction to be considered a valid staking transaction, it must: -- Have a Taproot output which has the key spending path disabled -and commits to a script tree composed of three scripts: -timelock script, unbonding script, slashing script. -This output is henceforth known as the `staking_output` and -the value in this output is known as `staking_amount` -- Have `OP_RETURN` output which contains: `global_parameters.tag`, - `version`, `staker_pk`, `finality_provider_pk`, `staking_time` -- All the values must be valid for the `global_parameters` which are applicable at -the height in which the staking transaction is included in the BTC ledger. - - -#### OP_RETURN output description - -Data in the OP_RETURN output is described by the following struct: - -```go -type V0OpReturnData struct { - Tag []byte - Version byte - StakerPublicKey []byte - FinalityProviderPublicKey []byte - StakingTime []byte -} -``` -The implementation of the struct can be found [here](https://github.com/babylonlabs-io/babylon/blob/main/btcstaking/identifiable_staking.go?plain=1#L52) - -Fields description: -- `Tag` - 4 bytes, a tag which is used to identify the staking transaction -among other transactions in the Bitcoin ledger. -It is specified in the `global_parameters.Tag` field. -- `Version` - 1 byte, the current version of the OP_RETURN output. -- `StakerPublicKey` - 32 bytes, staker public key. The same key must be used in -the scripts used to create the Taproot output in the staking transaction. -- `FinalityProviderPublicKey` - 32 bytes, finality provider public key. The same key -must be used in the scripts used to create the Taproot output in the -staking transaction. -- `StakingTime` - 2 bytes big-endian unsigned number, staking time. -The same timelock time must be used in scripts used to create the Taproot -output in the staking transaction. - - -This data is serialized as follows: -``` -SerializedStakingData = Tag || Version || StakerPublicKey || FinalityProviderPublicKey || StakingTime -``` - -To transform this data into OP_RETURN data: - -``` -StakingDataPkScript = 0x6a || 0x47 || SerializedStakingData -``` - -where: -- 0x6a - is byte marker representing OP_RETURN op code. -- 0x47 - is byte marker representing OP_DATA_71 op code, which pushed 71 bytes onto the stack. - -The final OP_RETURN output will have the following shape: -``` -TxOut { - Value: 0, - PkScript: StakingDataPkScript -} -``` - -Logic creating output from data can be found [here](https://github.com/babylonlabs-io/babylon/blob/main/btcstaking/identifiable_staking.go?plain=1#L175) - - -#### Staking output description - -Staking output should commit to three scripts: -- `timelock_script` -- `unbonding_script` -- `slashing_script` - -Data needed to create `staking_output`: -- `staker_public_key` - chosen by the user sending the staking transaction. It -will be used in every script. This key needs to be put in the OP_RETURN output -in the staking transaction. -- `finality_provider_public_key` - chosen by the user sending the staking -transaction. It will be used as `` in the `slashing_script`. In the -lock-only network, there is no slashing, so this key has mostly informative purposes. -This key needs to be put in the OP_RETURN output of the staking transaction. -- `staking_time` - chosen by the user sending the staking transaction. It will -be used as the locking time in the `timelock_script`. It must be a valid `uint16` number, -in the range `global_parameters.min_staking_time <= staking_time <= global_parameters.max_staking_time`. -It needs to be put in the OP_RETURN output of the staking transaction. -- `covenant_committee_public_keys` - it can be retrieved from -`global_parameters.covenant_pks`. It is a set of covenant committee public keys which -will be put in `unbonding_script` and `slashing_script`. -- `covenant_committee_quorum` - it can be retrieved from -`global_parameters.covenant_quorum`. It is the quorum of covenant committee -members required to authorize spending using the `unbonding_script` or `slashing_script`. -- `staking_amount` - chosen by the user, it will be placed in `staking_output.value`. -- `btc_network` - the BTC network on which staking transactions will take place. - -#### Building OP_RETURN and staking output implementation - -The Babylon staking library exposes the [BuildV0IdentifiableStakingOutputsAndTx](https://github.com/babylonlabs-io/babylon/blob/main/btcstaking/identifiable_staking.go?plain=1#L231) -function with the following signature: - -```go -func BuildV0IdentifiableStakingOutputsAndTx( - tag []byte, - stakerKey *btcec.PublicKey, - fpKey *btcec.PublicKey, - covenantKeys []*btcec.PublicKey, - covenantQuorum uint32, - stakingTime uint16, - stakingAmount btcutil.Amount, - net *chaincfg.Params, -) (*IdentifiableStakingInfo, *wire.MsgTx, error) -``` - -It enables the caller to create valid outputs to put inside an unfunded and not-signed -staking transaction. - -The suggested way of creating and sending a staking transaction using -[bitcoind](https://github.com/bitcoin/bitcoin) is: -1. Create `staker_key` in the bitcoind wallet. -2. Create unfunded and not signed staking transaction using -the `BuildV0IdentifiableStakingOutputsAndTx` function. -3. Serialize the unfunded and not signed staking transaction to `staking_transaction_hex`. -4. Call `bitcoin-cli fundrawtransaction "staking_transaction_hex"` to -retrieve `funded_staking_transaction_hex`. -The bitcoind wallet will automatically choose unspent outputs to fund this transaction. -5. Call `bitcoin-cli signrawtransactionwithwallet "funded_staking_transaction_hex"`. -This call will sign all inputs of the transaction and return `signed_staking_transaction_hex`. -6. Call `bitcoin-cli sendrawtransaction "signed_staking_transaction_hex"`. - -### Unbonding transaction - -The unbonding transaction allows the staker to on-demand unbond their -locked Bitcoin stake prior to its original timelock expiration. - -#### Requirements - -For the transaction to be considered a valid unbonding transaction, it must: -- Have exactly one input and one output. -- Input must be a valid staking output. -- Output must be a Taproot output. This Taproot output must have disabled -the key spending path, and committed to script tree composed of two scripts: -the timelock script and the slashing script. This output is henceforth known -as the `unbonding_output`. -- Timelock in the timelock script must be equal to `global_parameters.unbonding_time`. -- Value in the unbonding output must be equal to `staking_output.value - global_parameters.unbonding_fee`. - -#### Building Unbonding output - -The Babylon Bitcoin staking library exposes -the [BuildUnbondingInfo](https://github.com/babylonlabs-io/babylon/blob/main/btcstaking/types.go?plain=1#416) -function which builds a valid unbonding output. -It has the following signature: - -```go -func BuildUnbondingInfo( - stakerKey *btcec.PublicKey, - fpKeys []*btcec.PublicKey, - covenantKeys []*btcec.PublicKey, - covenantQuorum uint32, - unbondingTime uint16, - unbondingAmount btcutil.Amount, - net *chaincfg.Params, -) (*UnbondingInfo, error) -``` - -where: -- `stakerKey`- must be the same key as the staker key in `staking_transaction`. -- `fpKeys` - must contain one key, which is the same finality provider key used -in `staking_transaction`. -- `covenantKeys`- are the same covenant keys as used in `staking_transaction`. -- `covenantQuorum` - is the same quorum as used in `staking_transaction`. -- `unbondingTime` - is equal to `global_parameters.unbonding_time`. -- `unbondingAmount` - is equal to `staking_amount - global_parameters.unbonding_fee`. - -## Spending Taproot outputs - -To create transactions which spend from Taproot outputs, either staking output -or unbonding output, providing signatures satisfying the script is not enough. - -The spender must also provide: -- The whole script which is being spent. -- The control block which contains: leaf version, internal public key, and proof of -inclusion of the given script in the script tree. - -Given that creating scripts is deterministic for given data, it is possible to -avoid storing scripts by re-building scripts when the need arises. - -### Re-creating script and control block - -To build the script and control block necessary to spend from a staking output through the -timelock script, the following function could be implemented. - -```go -import ( - // Babylon btc staking library - "github.com/babylonlabs-io/babylon/btcstaking" -) - -func buildTimelockScriptAndControlBlock( - stakerKey *btcec.PublicKey, - finalityProviderKey *btcec.PublicKey, - covenantKeys []*btcec.PublicKey, - covenantQuorum uint32, - stakingTime uint16, - stakingAmount btcutil.Amount, - netParams *chaincfg.Params, -) ([]byte, []byte, error) { - - stakingInfo, err := btcstaking.BuildStakingInfo( - stakerKey, - []*btcec.PublicKey{finalityProviderKey}, - covenantKeys, - covenantQuorum, - stakingTime, - stakingAmount, - netParams, - ) - - if err != nil { - return nil, nil, err - } - - si, err := stakingInfo.TimeLockPathSpendInfo() - - if err != nil { - return nil, nil, err - } - - scriptBytes := si.RevealedLeaf.Script - - controlBlock := si.ControlBlock - - controlBlockBytes, err := controlBlock.ToBytes() - if err != nil { - return nil, nil, err - } - - return scriptBytes, controlBlockBytes, nil -} - -``` - -The returned script and control block can be used to either build the witness directly -or to put them in a PSBT which can be used by bitcoind to create the witness. - -### Creating PSBT to get signature for given Taproot path from Bitcoind - -To avoid creating signatures/witness manually, -Bitcoind's [walletprocesspsbt](https://developer.bitcoin.org/reference/rpc/walletprocesspsbt.html) -can be used. To use this Bitcoind endpoint to get signature/witness the wallet must -maintain one of the keys used in the script. - -Example of creating psbt to sign unbonding transaction using unbonding script from -staking output: - -```go -import ( - "github.com/btcsuite/btcd/btcutil/psbt" -) - -func BuildPsbtForSigningUnbondingTransaction( - unbondingTx *wire.MsgTx, - stakingOutput *wire.TxOut, - stakerKey *btcec.PublicKey, - spentLeaf *txscript.TapLeaf, - controlBlockBytes []byte, -) (string, error) { - psbtPacket, err := psbt.New( - []*wire.OutPoint{&unbondingTx.TxIn[0].PreviousOutPoint}, - unbondingTx.TxOut, - unbondingTx.Version, - unbondingTx.LockTime, - []uint32{unbondingTx.TxIn[0].Sequence}, - ) - - if err != nil { - return "", fmt.Errorf("failed to create PSBT packet with unbonding transaction: %w", err) - } - - psbtPacket.Inputs[0].SighashType = txscript.SigHashDefault - psbtPacket.Inputs[0].WitnessUtxo = stakingOutput - psbtPacket.Inputs[0].Bip32Derivation = []*psbt.Bip32Derivation{ - { - PubKey: stakerKey.SerializeCompressed(), - }, - } - - psbtPacket.Inputs[0].TaprootLeafScript = []*psbt.TaprootTapLeafScript{ - { - ControlBlock: controlBlockBytes, - Script: spentLeaf.Script, - LeafVersion: spentLeaf.LeafVersion, - }, - } - - return psbtPacket.B64Encode() -} - -``` - -Given that to spend through the unbonding script requires more than the -staker's signature, the `walletprocesspsbt` endpoint will produce a new psbt -with the staker signature attached. - -In the case of a timelock path which requires only the staker's signature, -`walletprocesspsbt` would produce the whole witness required to send the -transaction to the BTC network. diff --git a/docs/operators/babylon_node/installation_guide.mdx b/docs/operators/babylon_node/installation_guide.mdx index ed94387c..6673076c 100644 --- a/docs/operators/babylon_node/installation_guide.mdx +++ b/docs/operators/babylon_node/installation_guide.mdx @@ -8,13 +8,12 @@ sidebar_position: 0 import RemoteMD from '@site/src/components/RemoteMD'; export const testnetUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-test-5/babylon-node/README.md"; -export const mainnetUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/babylon-node/README.md"; +export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/babylon-node/README.md"; diff --git a/docs/operators/babylon_validators/ibc_relayer_guide.mdx b/docs/operators/babylon_validators/ibc_relayer_guide.mdx index dad1f196..cbafc05d 100644 --- a/docs/operators/babylon_validators/ibc_relayer_guide.mdx +++ b/docs/operators/babylon_validators/ibc_relayer_guide.mdx @@ -12,9 +12,6 @@ export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/babylon/re A technical guide for implementing IBC relaying on Babylon Genesis. \ No newline at end of file diff --git a/docs/operators/babylon_validators/installation_guide.mdx b/docs/operators/babylon_validators/installation_guide.mdx index 6631d3cd..fb808b9a 100644 --- a/docs/operators/babylon_validators/installation_guide.mdx +++ b/docs/operators/babylon_validators/installation_guide.mdx @@ -4,20 +4,18 @@ sidebar_label: Installation Guide sidebar_position: 1 --- -# Babylon Genesis Validators Installation Guide # Babylon Genesis Validators Installation Guide import RemoteMD from '@site/src/components/RemoteMD'; export const testnetUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/babylon-validators/README.md"; -export const mainnetUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/babylon-validators/README.md"; +export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/babylon-validators/README.md"; diff --git a/docs/operators/covenant_emulator/covenant_emulator.mdx b/docs/operators/covenant_emulator/covenant_emulator.mdx index e3000d66..a767e166 100644 --- a/docs/operators/covenant_emulator/covenant_emulator.mdx +++ b/docs/operators/covenant_emulator/covenant_emulator.mdx @@ -13,9 +13,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/covenant-emulator/refs/heads/main/README.md"; diff --git a/docs/operators/finality_providers/finality_providers.mdx b/docs/operators/finality_providers/finality_providers.mdx index 1b4a00a3..8ef29819 100644 --- a/docs/operators/finality_providers/finality_providers.mdx +++ b/docs/operators/finality_providers/finality_providers.mdx @@ -11,9 +11,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/finality-provider/refs/heads/main/README.md"; diff --git a/docs/operators/finality_providers/fp_core_specs.mdx b/docs/operators/finality_providers/fp_core_specs.mdx index 5d7b9e07..2302ec91 100644 --- a/docs/operators/finality_providers/fp_core_specs.mdx +++ b/docs/operators/finality_providers/fp_core_specs.mdx @@ -11,9 +11,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/finality-provider/refs/heads/main/docs/fp-core.md"; diff --git a/docs/operators/finality_providers/fp_finality_votes.mdx b/docs/operators/finality_providers/fp_finality_votes.mdx index 1d790a1e..a3def1ba 100644 --- a/docs/operators/finality_providers/fp_finality_votes.mdx +++ b/docs/operators/finality_providers/fp_finality_votes.mdx @@ -11,9 +11,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/finality-provider/refs/heads/main/docs/send-finality-vote.md"; diff --git a/docs/operators/finality_providers/fp_operations.mdx b/docs/operators/finality_providers/fp_operations.mdx index 5309b46d..d8a608d3 100644 --- a/docs/operators/finality_providers/fp_operations.mdx +++ b/docs/operators/finality_providers/fp_operations.mdx @@ -11,9 +11,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/finality-provider/refs/heads/main/docs/finality-provider-operation.md"; diff --git a/docs/operators/finality_providers/fp_public_randomness.mdx b/docs/operators/finality_providers/fp_public_randomness.mdx index 90662466..cc6bb53f 100644 --- a/docs/operators/finality_providers/fp_public_randomness.mdx +++ b/docs/operators/finality_providers/fp_public_randomness.mdx @@ -11,9 +11,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/finality-provider/refs/heads/main/docs/commit-pub-rand.md"; diff --git a/docs/operators/finality_providers/hmac_security.mdx b/docs/operators/finality_providers/hmac_security.mdx index c52f35b1..cc57a493 100644 --- a/docs/operators/finality_providers/hmac_security.mdx +++ b/docs/operators/finality_providers/hmac_security.mdx @@ -11,9 +11,6 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/finality-provider/refs/heads/main/docs/hmac-security.md"; \ No newline at end of file diff --git a/docs/operators/finality_providers/slashing_protection.mdx b/docs/operators/finality_providers/slashing_protection.mdx index e502acf0..c85dafab 100644 --- a/docs/operators/finality_providers/slashing_protection.mdx +++ b/docs/operators/finality_providers/slashing_protection.mdx @@ -11,10 +11,7 @@ import RemoteMD from '@site/src/components/RemoteMD'; export const rawUrl="https://raw.githubusercontent.com/babylonlabs-io/finality-provider/refs/heads/main/docs/slashing-protection.md"; diff --git a/docusaurus.config.js b/docusaurus.config.js index afcff852..2d8982be 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -141,7 +141,11 @@ const config = { showLastUpdateTime: false, docItemComponent: '@theme/ApiItem', }, - blog: false, + blog: { + path: 'blog', + routeBasePath: 'blog', + include: ['**/*.{md,mdx}'], + }, theme: { customCss: [ require.resolve('./src/css/custom.css') diff --git a/package-lock.json b/package-lock.json index 1ca851d9..05278214 100644 --- a/package-lock.json +++ b/package-lock.json @@ -31,7 +31,8 @@ "react": "^18.2.0", "react-dom": "^18.2.0", "react-feather": "^2.0.10", - "react-medium-image-zoom": "^5.2.14" + "react-medium-image-zoom": "^5.2.14", + "sanitize-html": "^2.17.0" }, "devDependencies": { "@docusaurus/tsconfig": "3.7.0", @@ -20634,6 +20635,12 @@ "resolved": "https://registry.npmjs.org/parse-numeric-range/-/parse-numeric-range-1.3.0.tgz", "integrity": "sha512-twN+njEipszzlMJd4ONUYgSfZPDxgHhT9Ahed5uTigpQn90FggW4SA/AIPq/6a149fTbE9qBEcSwE3FAEp6wQQ==" }, + "node_modules/parse-srcset": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/parse-srcset/-/parse-srcset-1.0.2.tgz", + "integrity": "sha512-/2qh0lav6CmI15FzA3i/2Bzk2zCgQhGMkvhOhKNcBVQ1ldgpbfiNTVslmooUmWJcADi1f1kIeynbDRVzNlfR6Q==", + "license": "MIT" + }, "node_modules/parse5": { "version": "7.2.1", "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.2.1.tgz", @@ -25355,6 +25362,29 @@ "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==" }, + "node_modules/sanitize-html": { + "version": "2.17.0", + "resolved": "https://registry.npmjs.org/sanitize-html/-/sanitize-html-2.17.0.tgz", + "integrity": "sha512-dLAADUSS8rBwhaevT12yCezvioCA+bmUTPH/u57xKPT8d++voeYE6HeluA/bPbQ15TwDBG2ii+QZIEmYx8VdxA==", + "license": "MIT", + "dependencies": { + "deepmerge": "^4.2.2", + "escape-string-regexp": "^4.0.0", + "htmlparser2": "^8.0.0", + "is-plain-object": "^5.0.0", + "parse-srcset": "^1.0.2", + "postcss": "^8.3.11" + } + }, + "node_modules/sanitize-html/node_modules/is-plain-object": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz", + "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/sass": { "version": "1.83.1", "resolved": "https://registry.npmjs.org/sass/-/sass-1.83.1.tgz", diff --git a/package.json b/package.json index d0b14f21..840ceba1 100644 --- a/package.json +++ b/package.json @@ -46,7 +46,8 @@ "react": "^18.2.0", "react-dom": "^18.2.0", "react-feather": "^2.0.10", - "react-medium-image-zoom": "^5.2.14" + "react-medium-image-zoom": "^5.2.14", + "sanitize-html": "^2.17.0" }, "devDependencies": { "@docusaurus/tsconfig": "3.7.0", diff --git a/plugins/fetch-remote-docs.cjs b/plugins/fetch-remote-docs.cjs index 32be2b47..dc450828 100644 --- a/plugins/fetch-remote-docs.cjs +++ b/plugins/fetch-remote-docs.cjs @@ -4,7 +4,6 @@ const fetch = require('node-fetch'); const parser = require('@babel/parser'); const traverse = require('@babel/traverse').default; -// Recursively scan all `.mdx` files function scanMdxFiles(dir, result = []) { fs.readdirSync(dir).forEach((name) => { const filePath = path.join(dir, name); @@ -22,11 +21,14 @@ function extractJsAndRemoteMD(content) { const codeLines = []; let inFrontmatter = false; let inRemoteMD = false, remoteMdBlock = []; + for (let i = 0; i < lines.length; i++) { const line = lines[i]; + if (line.trim() === '---' && !inFrontmatter) { inFrontmatter = true; continue; } if (line.trim() === '---' && inFrontmatter) { inFrontmatter = false; continue; } if (inFrontmatter) continue; + if (line.includes(' { const key = prop.key.type === 'Identifier' @@ -77,78 +82,107 @@ function extractNetworkVersions(objNode, variables) { : prop.key.type === 'StringLiteral' ? prop.key.value : ''; + versions[key] = getValueFromNode(prop.value, variables); }); + return versions; } -// Get the base name of the `.mdx` file without extension function getFileBaseName(filepath) { return path.basename(filepath, path.extname(filepath)); } -// Main: For each `.mdx` file, return an array where each element is {url, key} function findRemoteMDTargets(content, variables) { const results = []; const jsCode = extractJsAndRemoteMD(content); let ast; + try { ast = parser.parse(jsCode, { sourceType: 'module', plugins: ['jsx', 'typescript'], }); } catch (e) { + console.warn(`Failed to parse JS code: ${e.message}`); return []; } + traverse(ast, { JSXElement({ node }) { if (!node.openingElement) return; const tagName = node.openingElement.name.name; if (tagName !== 'RemoteMD') return; - let found = false; + + let rawUrl = null; + let releaseVersions = null; + let defaultRelease = null; + let hideRelease = false; + node.openingElement.attributes.forEach((attr) => { - // - if ( - attr.name && - attr.name.name === 'networkVersions' && - attr.value && - attr.value.expression - ) { - found = true; - // networkVersions={{mainnet: ..., ...}} - if (attr.value.expression.type === 'ObjectExpression') { - const versions = extractNetworkVersions(attr.value.expression, variables); - for (const [key, url] of Object.entries(versions)) { - if (url) results.push({ url, key }); - } - } - // networkVersions={rawObj} - if (attr.value.expression.type === 'Identifier') { - let refName = attr.value.expression.name; - if (variables[refName]) { - // You can extend support for external objects - results.push({ url: variables[refName], key: refName }); - } - } + if (attr.name && attr.name.name === 'rawUrl') { + rawUrl = getValueFromNode(attr.value?.expression || attr.value, variables); } - // - if ( - attr.name && - attr.name.name === 'url' && - attr.value - ) { - if (attr.value.type === 'StringLiteral') { - results.push({ url: attr.value.value, key: undefined }); - } else if (attr.value.expression && attr.value.expression.type === 'Identifier') { - let refName = attr.value.expression.name; + + if (attr.name && attr.name.name === 'releaseVersions') { + if (attr.value?.expression?.type === 'ObjectExpression') { + releaseVersions = extractReleaseVersions(attr.value.expression, variables); + } else if (attr.value?.expression?.type === 'Identifier') { + const refName = attr.value.expression.name; if (variables[refName]) { - results.push({ url: variables[refName], key: undefined }); + try { + releaseVersions = JSON.parse(variables[refName]); + } catch (e) { + console.warn(`Failed to parse releaseVersions from variable: ${refName}`); + } } } } + + if (attr.name && attr.name.name === 'defaultRelease') { + defaultRelease = getValueFromNode(attr.value?.expression || attr.value, variables); + } + + if (attr.name && attr.name.name === 'hideRelease') { + hideRelease = getValueFromNode(attr.value?.expression || attr.value, variables) === true; + } }); + + if (!rawUrl) return; + + if (!releaseVersions) { + results.push({ + url: rawUrl, + key: null, + hideRelease, + isDefault: defaultRelease === null + }); + return; + } + + for (const [key, url] of Object.entries(releaseVersions)) { + if (url) { + results.push({ + url, + key, + hideRelease, + isDefault: defaultRelease === key || (defaultRelease === null && key === Object.keys(releaseVersions)[0]) + }); + } + } + + if (defaultRelease && !releaseVersions[defaultRelease]) { + const defaultUrl = rawUrl.replace(/refs\/heads\/[^/]+/, defaultRelease); + results.push({ + url: defaultUrl, + key: defaultRelease, + hideRelease, + isDefault: true + }); + } } }); + return results; } @@ -156,15 +190,49 @@ function clearDirectory(dirPath) { if (fs.existsSync(dirPath)) { fs.rmSync(dirPath, { recursive: true, force: true }); } - // Recreate the directory to ensure it exists and is empty fs.mkdirSync(dirPath, { recursive: true }); } -async function mdToStructuredHtml(mdContent) { +async function mdToStructuredHtml(mdContent, releaseTag = null) { const { remark } = await import('remark'); const html = (await import('remark-html')).default; + + const versionHeader = releaseTag + ? `
Version: ${releaseTag}
` + : ''; + const file = await remark().use(html).process(mdContent); - return `
${file.value}
`; + + return ` + + + + + Remote Documentation + + + +
+ ${versionHeader} + ${file.value} +
+ + + `; } function generateSitemap(urls, baseUrl) { @@ -178,6 +246,7 @@ function generateSitemap(urls, baseUrl) { ${baseUrl}${url} ` ).join('\n') + ' '; + return sitemap; } @@ -189,20 +258,27 @@ async function main() { BRANCH_NAME === 'main' ? 'https://docs.babylonlabs.io/remote-docs' : 'https://docs.dev.babylonlabs.io/remote-docs'; - // New: Clear the `remote-docs` directory each time + clearDirectory(STATIC_REMOTE_DOCS); + const mdxFiles = scanMdxFiles(DOCS_DIR, []); let total = 0, errorCount = 0; const htmlUrls = []; + for (const mdx of mdxFiles) { const mdxContent = fs.readFileSync(mdx, 'utf-8'); const jsCode = extractJsAndRemoteMD(mdxContent); let ast; let variables = {}; + try { ast = parser.parse(jsCode, { sourceType: 'module', plugins: ['jsx', 'typescript'] }); variables = extractStringVariables(ast); - } catch {} + } catch (e) { + console.warn(`Failed to parse JS code in ${mdx}: ${e.message}`); + continue; + } + const targets = findRemoteMDTargets(mdxContent, variables); if (targets.length === 0) continue; @@ -213,12 +289,17 @@ async function main() { const targetDir = path.join(STATIC_REMOTE_DOCS, relDir); if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true }); - for (const { url, key } of targets) { - let name = (targets.length === 1 || key === undefined || key === null) - ? `${baseName}.md` - : `${baseName}-${key}.md`; + for (const { url, key, hideRelease, isDefault } of targets) { + let name; + if (!key || hideRelease) { + name = `${baseName}.html`; + } else { + const safeKey = key.replace(/[^a-zA-Z0-9._-]/g, '-'); + name = `${baseName}-version-${safeKey}.html`; + } + const outPath = path.join(targetDir, name); - const htmlOutPath = outPath.replace(/\.md$/, '.html'); + try { const res = await fetch(url); if (!res.ok) { @@ -226,14 +307,21 @@ async function main() { console.warn(`[WARN] Download failed [${res.status}]: ${url}`); continue; } + const mdContent = await res.text(); - fs.writeFileSync(outPath, mdContent, 'utf-8'); - const htmlContent = await mdToStructuredHtml(mdContent); - fs.writeFileSync(htmlOutPath, htmlContent, 'utf-8'); - fs.unlinkSync(outPath); - const relHtmlPath = path.relative(STATIC_REMOTE_DOCS, htmlOutPath).replace(/\\/g, '/'); - htmlUrls.push(`/${relHtmlPath}`); - console.log('Fetched:', url, '=>', htmlOutPath, '（md have deleted）'); + + const htmlContent = await mdToStructuredHtml(mdContent, key); + fs.writeFileSync(outPath, htmlContent, 'utf-8'); + + const relHtmlPath = path.relative(STATIC_REMOTE_DOCS, outPath).replace(/\\/g, '/'); + + const urlWithVersion = key + ? `${relHtmlPath}?version=${encodeURIComponent(key)}` + : relHtmlPath; + + htmlUrls.push(`/${urlWithVersion}`); + + console.log('Fetched:', url, '=>', outPath, key ? `(version: ${key})` : ''); total++; } catch (err) { errorCount++; @@ -241,12 +329,15 @@ async function main() { } } } + if (htmlUrls.length > 0) { const sitemapContent = generateSitemap(htmlUrls, REMOTE_DOCS_BASE_URL); const sitemapPath = path.join(STATIC_REMOTE_DOCS, 'remote-docs-sitemap.xml'); fs.writeFileSync(sitemapPath, sitemapContent, 'utf-8'); console.log(`Generated sitemap: ${sitemapPath} (contains ${htmlUrls.length} html pages)`); } - console.log(`Total written ${total} remote html (md deleted), errors ${errorCount}`); + + console.log(`Total written ${total} remote html files, errors ${errorCount}`); } + main(); \ No newline at end of file diff --git a/src/components/RemoteMD.jsx b/src/components/RemoteMD.jsx index e5979c52..1fcb6c6d 100644 --- a/src/components/RemoteMD.jsx +++ b/src/components/RemoteMD.jsx @@ -1,169 +1,58 @@ import React from 'react'; import ReactMarkdown from 'react-markdown'; -import {Tag} from '@styled-icons/bootstrap'; -import {Globe} from '@styled-icons/boxicons-regular/Globe'; +import { Tag } from '@styled-icons/bootstrap/Tag'; import Admonition from '@theme/Admonition'; +import sanitizeHtml from 'sanitize-html'; -function RemoteMD({ - networkVersions = {}, - hideEnv = false, - hideRelease = false, -}) { - const [markdown, setMarkdown] = React.useState(''); - const [releases, setReleases] = React.useState([]); - const [selectedVersion, setSelectedVersion] = React.useState(''); - const [selectedNetwork, setSelectedNetwork] = React.useState( - Object.keys(networkVersions)[0] - ); - const [errorMessage, setErrorMessage] = React.useState(''); - const [showReleaseSelector, setShowReleaseSelector] = React.useState(true); - const [loading, setLoading] = React.useState(true); // Track loading state - const lastH2 = React.useRef(''); - - // Function to fetch the raw markdown based on the selected network - const fetchMarkdown = async (networkUrl) => { - setLoading(true); // Set loading to true when fetching starts - try { - const response = await fetch(networkUrl); - if (!response.ok) { - throw new Error('Document not found'); - } - const text = await response.text(); - setMarkdown(text.replace(//g, '')); // Remove HTML comments - setErrorMessage(''); // Clear any previous error message - } catch (error) { - console.error('Failed to fetch markdown:', error); - setMarkdown(''); // Clear the page if no document is found - setErrorMessage('Documentation not found for the selected network.'); // Set the error message - } finally { - setLoading(false); // Set loading to false after the fetch is completed - } - }; - - const extractRepoInfo = (url) => { - const urlParts = url.split('/'); - const owner = urlParts[3]; - const repo = urlParts[4]; - const filePath = urlParts.slice(7).join('/'); - return { owner, repo, filePath }; - }; - - const fetchReleases = async () => { - try { - const { owner, repo } = extractRepoInfo(networkVersions[selectedNetwork]); - const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/releases`); - if (!response.ok) { - throw new Error('Releases not found'); - } - const data = await response.json(); - if (Array.isArray(data) && data.length > 0) { - // Filter out pre-releases (rc, alpha, beta versions) - let stableReleases = data - .map((release) => release.tag_name) - .filter(tag => !tag.includes('-')); // Excludes tags with '-' like rc, alpha, beta - - if (stableReleases.length === 0) { - // If no stable releases, fall back to all releases - stableReleases = data.map((release) => release.tag_name); - } - - // Sort releases by version number - const sortedReleases = stableReleases.sort((a, b) => { - const [aMajor, aMinor, aPatch] = a.replace('v', '').split('.').map(Number); - const [bMajor, bMinor, bPatch] = b.replace('v', '').split('.').map(Number); - if (bMajor !== aMajor) return bMajor - aMajor; - if (bMinor !== aMinor) return bMinor - aMinor; - return bPatch - aPatch; - }); - - const latestMajorRelease = sortedReleases[0]; - const latestMajorReleaseUrl = networkVersions[selectedNetwork].replace(/refs\/heads\/[^/]+/, `${latestMajorRelease}`); - const latestMajorReleaseResponse = await fetch(latestMajorReleaseUrl); - - if (!latestMajorReleaseResponse.ok) { - return; - } - - // Get all releases with the same major version - const [currentMajor] = latestMajorRelease.replace('v', '').split('.').map(Number); - const sameMajorReleases = sortedReleases.filter(release => { - const [major] = release.replace('v', '').split('.').map(Number); - return major === currentMajor; - }); - - if (sameMajorReleases.length === 1) { - setReleases([latestMajorRelease]); - setSelectedVersion(latestMajorRelease); - setShowReleaseSelector(true); - } else { - const secondReleaseUrl = networkVersions[selectedNetwork].replace(/refs\/heads\/[^/]+/, `${sameMajorReleases[1]}`); - const secondReleaseResponse = await fetch(secondReleaseUrl); - if (secondReleaseResponse.ok) { - setReleases(sameMajorReleases); - setSelectedVersion(sameMajorReleases[0]); - setShowReleaseSelector(true); - } else { - setReleases([sameMajorReleases[0]]); - setSelectedVersion(sameMajorReleases[0]); - setShowReleaseSelector(true); - } - } - } else { - throw new Error('No releases found'); - } - } catch (error) { - console.error('Failed to fetch releases:', error); - setReleases([]); - setErrorMessage(''); - setShowReleaseSelector(false); - } - }; - - - // Convert raw GitHub URL to regular GitHub URL - const rawToGithubUrl = (rawUrl) => { - return rawUrl - .replace('raw.githubusercontent.com', 'github.com') - .replace('refs/heads/', 'blob/'); - }; +function extractRepoInfo(url) { + const urlParts = url.split('/'); + const owner = urlParts[3]; + const repo = urlParts[4]; + const filePath = urlParts.slice(7).join('/'); + return { owner, repo, filePath }; +} - const url = rawToGithubUrl(networkVersions[selectedNetwork]); +function getQueryParam(name) { + if (typeof window === 'undefined') return ''; + const params = new URLSearchParams(window.location.search); + return params.get(name); +} - const generateId = (text) => { - return text - .toLowerCase() - .replace(/[^a-z0-9 ]/g, '') - .replace(/\s+/g, '-'); - }; +const generateId = (text) => { + return text + .toLowerCase() + .replace(/[^a-z0-9 ]/g, '') + .replace(/\s+/g, '-'); +}; - React.useEffect(() => { - fetchMarkdown(networkVersions[selectedNetwork]); - fetchReleases(); - }, [selectedNetwork]); +const defaultReleaseVersions = {}; - // Handle version selection - const handleVersionChange = (event) => { - const selectedVersion = event.target.value; - setSelectedVersion(selectedVersion); - const newRawUrl = networkVersions[selectedNetwork].replace( - /refs\/heads\/[^/]+/, - `${selectedVersion}` - ); - setMarkdown(''); - fetchMarkdown(newRawUrl); - }; +const sortBySemVer = (a, b) => { + const [aVer, bVer] = [a.key, b.key].map(v => v.replace(/^v/, '').split('.').map(Number)); + for (let i = 0; i < 3; i++) { + if (aVer[i] > bVer[i]) return -1; + if (aVer[i] < bVer[i]) return 1; + } + return 0; +}; - // Handle network version selection - const handleNetworkChange = (event) => { - setSelectedNetwork(event.target.value); - setMarkdown(''); // Clear the page when switching networks - setErrorMessage(''); // Clear error message when switching networks - }; +export default function RemoteMD({ + rawUrl, + releaseVersions = defaultReleaseVersions, + defaultRelease = '', + hideRelease = false + }) { + const [markdown, setMarkdown] = React.useState(''); + const [releases, setReleases] = React.useState([]); // [{key, label, url}] + const [selectedRelease, setSelectedRelease] = React.useState(''); + const [errorMessage, setErrorMessage] = React.useState(''); + const [loading, setLoading] = React.useState(true); + const [currentMdUrl, setCurrentMdUrl] = React.useState(rawUrl); + const lastH2 = React.useRef(''); - // Helper function to handle relative paths - const resolveRelativePath = (href) => { + const resolveRelativePath = (href, renderUrl) => { const [path, anchor] = href.split('#'); - let baseUrl = url.replace(/\/[^/]+$/, ''); + let baseUrl = renderUrl.replace(/\/[^/]+$/, ''); let resolvedPath; if (path.startsWith('./')) { @@ -184,19 +73,16 @@ function RemoteMD({ const components = { img: ({ node }) => { const { alt, src } = node.properties; - let rootUrl = networkVersions[selectedNetwork].replace(/\/[^/]+\.md$/, '/'); - const newSrc = src.startsWith('./') - ? `${rootUrl}${src.substring(1)}` - : src; - return {alt}/; + let rootUrl = (currentMdUrl || rawUrl).replace(/\/[^/]+\.md$/, '/'); + const newSrc = + src && src.startsWith('./') ? `${rootUrl}${src.substring(1)}` : src; + return {alt}; }, - h1: ({ children }) => { let count = 0; const id = generateId(String(children)); return count++ === 0 ? null :

{children}

; }, - h2: ({ children }) => { lastH2.current = String(children); const id = generateId(String(children)); @@ -204,80 +90,182 @@ function RemoteMD({

{children}

); }, - ol: ({ children }) => { return lastH2.current === 'Table of Contents' ? null : (
    {children}
); }, - a: ({ node, children }) => { const { href } = node.properties; if (!href) return {children}; const resolvedHref = href.startsWith('.') - ? resolveRelativePath(href) + ? resolveRelativePath(href, currentMdUrl || rawUrl) : href; return {children}; }, - h3: ({ children }) => { const id = generateId(String(children)); return

{children}

; }, }; + React.useEffect(() => { + let cancelled = false; + + async function fetchReleases() { + const { owner, repo } = extractRepoInfo(rawUrl); + const apiUrl = `https://api.github.com/repos/${owner}/${repo}/releases`; + const response = await fetch(apiUrl); + const data = await response.json(); + + const stableReleases = data.filter(release => + !release.tag_name.includes('-') && !release.prerelease + ); + + const allReleases = [ + ...Object.entries(releaseVersions).map(([key, url]) => ({ + key, + label: key, + url, + isCustom: true + })), + ...stableReleases.map(release => ({ + key: release.tag_name, + label: release.tag_name, + url: rawUrl.replace(/refs\/heads\/[^/]+/, release.tag_name), + publishedAt: release.published_at + })) + ]; + + const customReleases = allReleases.filter(r => r.isCustom); + const apiReleases = allReleases.filter(r => !r.isCustom).sort(sortBySemVer); + const sortedReleases = [...customReleases, ...apiReleases]; + + if (apiReleases.length > 0) { + const latestMajor = apiReleases[0].key.split('.')[0]; + const sameMajorReleases = apiReleases.filter(r => + r.key.split('.')[0] === latestMajor + ); + const finalReleases = customReleases.concat(sameMajorReleases); + setReleases(finalReleases); + } else { + setReleases(sortedReleases); + } + } + + if (!hideRelease) fetchReleases(); + return () => { + cancelled = true; + }; + }, [rawUrl, releaseVersions, hideRelease]); + + const fetchMarkdown = async (mdUrl) => { + setLoading(true); + try { + setCurrentMdUrl(mdUrl); + const response = await fetch(mdUrl); + if (!response.ok) throw new Error('Document not found'); + const text = await response.text(); + setMarkdown( + sanitizeHtml(text, { + allowedTags: sanitizeHtml.defaults.allowedTags.concat(['img']), + allowedAttributes: { + ...sanitizeHtml.defaults.allowedAttributes, + img: ['src', 'alt'] + } + }) + ); + setErrorMessage(''); + } catch (e) { + setMarkdown(''); + setErrorMessage('Documentation not found for the selected release.'); + } finally { + setLoading(false); + } + }; + + React.useEffect(() => { + if (hideRelease || releases.length <= 1) return; + + const urlParam = getQueryParam('release'); + let initialKey = urlParam; + + if (initialKey && !releases.some(r => r.key === initialKey)) { + initialKey = ''; + } + + if (!initialKey && defaultRelease) { + initialKey = defaultRelease; + } + + if (!initialKey && releases.length > 0) { + initialKey = releases.find(r => !r.isCustom)?.key || releases[0].key; + } + + setSelectedRelease(initialKey); + }, [releases, defaultRelease, hideRelease]); + + React.useEffect(() => { + if (hideRelease || releases.length <= 1) { + fetchMarkdown(rawUrl); + return; + } + + const found = releases.find(r => r.key === selectedRelease); + if (found) { + fetchMarkdown(found.url); + } else { + setMarkdown(''); + setErrorMessage('Selected release not found'); + } + }, [selectedRelease, releases, hideRelease, rawUrl]); + + const handleReleaseChange = (event) => { + const key = event.target.value; + setSelectedRelease(key); + if (typeof window !== 'undefined') { + const params = new URLSearchParams(window.location.search); + params.set('release', key); + window.history.replaceState( + {}, + '', + `${window.location.pathname}?${params}` + ); + } + }; + const handleTagClick = () => { - const { owner, repo } = extractRepoInfo(networkVersions[selectedNetwork]); - const releaseUrl = `https://github.com/${owner}/${repo}/releases/tag/${selectedVersion}`; - window.open(releaseUrl, '_blank'); + const found = releases.find(r => r.key === selectedRelease); + if (found && !found.isCustom) { + const { owner, repo } = extractRepoInfo(rawUrl); + window.open(`https://github.com/${owner}/${repo}/releases/tag/${selectedRelease}`, '_blank'); + } }; return ( <> - {!(hideEnv && (hideRelease || !showReleaseSelector)) && ( -
- {!hideEnv && ( - <> - - - - - )} - {!hideRelease && showReleaseSelector && ( - <> - - - - - )} -
- )} + {!hideRelease && releases.length > 1 && ( +
+ + + +
+ )} - {/* Show error message if fetching fails */} {errorMessage && !loading && ( {errorMessage} @@ -286,15 +274,18 @@ function RemoteMD({ {markdown} - {/* Show info message when the page loads successfully */} {!errorMessage && !loading && ( - This documentation's source is hosted on github.com/babylonlabs-io.{' '} - View source and contribute + This documentation's source is hosted on github.com.{' '} + + View source and contribute + )} ); -} - -export default RemoteMD; +} \ No newline at end of file diff --git a/src/components/homepage/BlogSection.tsx b/src/components/homepage/BlogSection.tsx new file mode 100644 index 00000000..65e4d3a6 --- /dev/null +++ b/src/components/homepage/BlogSection.tsx @@ -0,0 +1,74 @@ +import React from 'react'; +import Link from '@docusaurus/Link'; + +interface FeaturedBlogPost { + title: string; + image: string; + link: string; + readTime: number; +} + +const blogPosts: FeaturedBlogPost[] = [ + { + title: "Bitcoin Staking 101: Part 3 - Babylon's Bitcoin Staking Contract", + image: "/img/blog/05-26-babylon-s-bitcoin-staking-contract/img.png", + link: "https://babylonlabs.io/blog/babylon-s-bitcoin-staking-contract", + readTime: 14 + }, + { + title: "Bitcoin Staking 101: Part 2 - Technical Preliminaries of Bitcoin Staking", + image: "/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/img.png", + link: "https://babylonlabs.io/blog/technical-preliminaries-of-bitcoin-staking", + readTime: 12 + }, + { + title: "Bitcoin Staking 101: Part 1 - What is Bitcoin Staking?", + image: "/img/blog/05-24-what-is-bitcoin-staking/img.png", + link: "https://babylonlabs.io/blog/what-is-bitcoin-staking", + readTime: 5 + } +]; + +function FeaturedBlogPost({ title, image, link, readTime }: FeaturedBlogPost) { + const content = ( + <> + {title} +

{title}

+ {readTime} min read + + ); + + return ( +
+ + {content} + +
+ ); +} + +const BlogSection: React.FC = () => { + return ( +
+
+
+

Want to know more?

+ + ALL Blogs → + +
+ +
+ {blogPosts.map((post) => ( + + ))} +
+
+
+ ); +}; + +export default BlogSection; \ No newline at end of file diff --git a/src/components/homepage/CommunitySection.jsx b/src/components/homepage/CommunitySection.jsx index 2642a000..7e3c8ef9 100644 --- a/src/components/homepage/CommunitySection.jsx +++ b/src/components/homepage/CommunitySection.jsx @@ -1,70 +1,40 @@ import React from 'react'; import Link from '@docusaurus/Link'; -import { Linkedin, Twitter } from 'react-feather'; -import { DiscordIcon } from '@site/src/icons'; - -const githubUsernames = [ - 'filippos47', - 'fishermanymc', - 'gbarkhatov', - 'gitferry', - 'jrwbabylonlab', - 'Lazar955', - 'liam-icheng-lai', - 'maurolacy', - 'PayneJoe', - 'RafilxTenfen', - 'samricotta', - 'SebastianElvis', - 'supertong', - '0xDazzer', - 'vitsalis', - 'Vvaradinov', - 'web3jenks', - 'kkkk666', -]; - export default function CommunitySection() { return (
-
+
+

- Join the community + Join the community

Engage with our ever-growing community to get the latest updates, product support, and more.

- {/*
- {githubUsernames.map((username) => ( - {`User - ))} -
*/}
- Discord → + Discord - Twitter → + Twitter - LinkedIn → + LinkedIn
diff --git a/src/components/homepage/HeroSection.tsx b/src/components/homepage/HeroSection.tsx index de2225e8..417b3a52 100644 --- a/src/components/homepage/HeroSection.tsx +++ b/src/components/homepage/HeroSection.tsx @@ -6,7 +6,6 @@ import { TetrisAppRegular, DocumentChevronDoubleRegular, } from '@fluentui/react-icons'; -import ThemedImage from '@theme/ThemedImage'; import clsx from 'clsx'; import { useBaseUrlUtils } from '@docusaurus/useBaseUrl'; @@ -57,9 +56,7 @@ function HeroProduct({ link, title, icon: Icon, - text, - lightImage, - darkImage + text }: (typeof PRODUCTS)[0]) { return ( @@ -69,25 +66,17 @@ function HeroProduct({ borderWidth: '1px', }} className={clsx( - 'group cursor-pointer overflow-clip rounded-3xl from-primary/30 via-transparent to-transparent text-black transition-all hover:bg-gradient-to-tr hover:text-primary hover:no-underline dark:text-white', - 'w-[90vw] border-secondary-700 bg-secondary-900 hover:!border-primary dark:border-secondary-800 sm:w-[440px]' + 'group cursor-pointer overflow-clip rounded-md from-primary/30 via-transparent to-transparent text-black transition-all hover:bg-gradient-to-tr hover:text-primary hover:no-underline dark:text-white', + 'w-[90vw] border-secondary-700 hover:!border-primary dark:border-secondary-800 sm:w-[440px]' )} > -
+

{title}

-

{text}

+

{text}

- {/* */} ); } @@ -97,8 +86,6 @@ export default function HeroSection() { const processedProducts = PRODUCTS.map((product) => ({ ...product, - // lightImage: withBaseUrl(product.lightImage), - // darkImage: withBaseUrl(product.darkImage), link: withBaseUrl(product.link), })); diff --git a/src/components/homepage/HomeFooter.jsx b/src/components/homepage/HomeFooter.jsx index 372fc0e0..3c869249 100644 --- a/src/components/homepage/HomeFooter.jsx +++ b/src/components/homepage/HomeFooter.jsx @@ -40,7 +40,7 @@ function Links({ name, links, isAccordion }) { (isAccordion ? toggleAccordion(href) : null)} > {name} @@ -50,7 +50,7 @@ function Links({ name, links, isAccordion }) {
  • {item.name} @@ -68,10 +68,11 @@ function Links({ name, links, isAccordion }) { export default function Footer() { const { withBaseUrl } = useBaseUrlUtils(); return ( -
    +
    -
    - +
    +
    @@ -91,15 +92,14 @@ export default function Footer() {
    Privacy Policy • Terms of Service diff --git a/src/components/homepage/ToolsAndInfra.tsx b/src/components/homepage/ToolsAndInfra.tsx index b7e2580f..3d6c14f8 100644 --- a/src/components/homepage/ToolsAndInfra.tsx +++ b/src/components/homepage/ToolsAndInfra.tsx @@ -31,10 +31,10 @@ function PartnerCard({ {`${name} - {name} + {name}
    {Object.entries(socialLinks).map(([platform, url]) => ( - + {platform === 'twitter' && } {platform === 'website' && } diff --git a/src/css/custom.css b/src/css/custom.css index 1ceaf590..dc128261 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -55,25 +55,27 @@ @layer base { :root { /* Primary Colors aligned with #ce6533 */ - --docs-color-primary-100: 218 125 79; /* Lighter shade of #ce6533 */ - --docs-color-primary-200: 206 101 51; /* Default #ce6533 */ + --docs-color-primary-100: 51 197 206; /* Lighter shade of #BEDCC9 */ + --docs-color-primary-200: 51 197 206; /* #BEDCC9 */ - --docs-color-secondary-700: 232 232 236; - --docs-color-secondary-800: 245 245 247; - --docs-color-secondary-900: 251 251 251; + --docs-color-secondary-700: 212 230 219; + --docs-color-secondary-800: 243 246 244; + --docs-color-secondary-900: 247 250 248; --docs-color-secondary-1000: 255 255 255; - --docs-color-text-400: 160 160 160; /* Darker text tone */ + --docs-color-text-400: 60 60 60; /* Darker text tone */ } html[data-theme='dark'] { /* Dark Mode Adjustments */ + --docs-color-primary-100: 222 236 226; + --docs-color-primary-200: 190 220 201; --docs-color-text-400: 160 160 160; /* Softer muted dark text */ - --docs-color-secondary-700: 71 71 71; + --docs-color-secondary-700: 16 42 54; --docs-color-secondary-800: 38 38 38; - --docs-color-secondary-900: 25 25 25; + --docs-color-secondary-900: 32 32 32; --docs-color-secondary-1000: 0 0 0; } @@ -133,7 +135,7 @@ body { /* Babylon Docs Tokens */ :root { - --docs-color-primary: #eb885b; + --docs-color-primary: #33C5CE; /* --docs-color-primary-100: #1a90ff; */ --docs-color-primary-tint: rgba(33, 96, 253, 0.16); --docs-color-primary-tint-light: rgba(33 96 253/0.24); @@ -186,19 +188,23 @@ body { Consolas, 'Liberation Mono', 'Courier New', monospace; /* Theme colors */ - --ifm-color-primary: #eb885b; /* Primary */ - --ifm-color-primary-dark: #b3582c; /* Darker */ - --ifm-color-primary-darker: #994d26; /* Even Darker */ - --ifm-color-primary-darkest: #803f1e; /* Darkest */ - --ifm-color-primary-light: #da7d4f; /* Lighter */ - --ifm-color-primary-lighter: #e19263; /* Even Lighter */ - --ifm-color-primary-lightest: #f2b08c; /* Lightest */ + --ifm-color-primary: #348f94; /* Primary */ + --ifm-color-primary-dark: #bcd1c4; /* Darker */ + --ifm-color-primary-darker: #BEDCC9; /* Even Darker */ + --ifm-color-primary-darkest: #BEDCC9; /* Darkest */ + --ifm-color-primary-light: #33C5CE; /* Lighter */ + --ifm-color-primary-lighter: #33C5CE; /* Even Lighter */ + --ifm-color-primary-lightest: #33C5CE; /* Lightest */ + --ifm-background-color: #ECF8F1; /* Background */ + --ifm-navbar-shadow: none; --ifm-toc-border-color: #dedede; --ifm-table-border-color: var(--docs-color-border); + --ifm-background-surface-color: #ECF8F1; --code-border-color: var(--docs-color-border); + --ifm-code-background: #D4E6DB; --ifm-code-font-size: 92%; --docusaurus-highlighted-code-line-bg: rgba(147, 178, 244, 0.38); @@ -206,27 +212,32 @@ body { --ifm-breadcrumb-item-background-active: transparent; --ifm-breadcrumb-padding-horizontal: 0; - --docusaurus-details-decoration-color: #b3582c; + --docusaurus-details-decoration-color: #33C5CE; } /* For readability concerns, you should choose a lighter palette in dark mode. */ html[data-theme='dark'] { - --ifm-link-color: #da7d4f; - --ifm-tabs-color-active-border: #da7d4f; - --ifm-tabs-color-active: #da7d4f; + --ifm-link-color: #BEDCC9; + --ifm-tabs-color-active-border: #BEDCC9; + --ifm-tabs-color-active: #BEDCC9; - --ifm-color-primary: #da7d4f; + --ifm-color-primary: #BEDCC9; --ifm-footer-background-color: #1c1c1c; - --ifm-background-surface-color: #161616; - --ifm-background-color: #161616; + --ifm-background-surface-color: #031B24; + --ifm-background-color: #031B24; --ifm-toc-border-color: #2e2e2e; + --ifm-code-background: #102A36; --ifm-color-content: #e7e7e7; --docusaurus-highlighted-code-line-bg: rgba(105, 105, 105, 0.3); } +.container code{ + background: var(--ifm-code-background); +} + nav.navbar { border-bottom: 1px solid var(--ifm-toc-border-color); } @@ -753,6 +764,8 @@ html[data-theme='dark'] .dropdown > .navbar__link:after { border-radius: 0.375rem; cursor: pointer; min-width: 120px; + background-color: var(--ifm-background-color); + /* Custom dropdown arrow updated with primary color */ background-image: url("data:image/svg+xml,%3Csvg width='24' height='24' fill='none' viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M4.293 8.293a1 1 0 0 1 1.414 0L12 14.586l6.293-6.293a1 1 0 1 1 1.414 1.414l-7 7a1 1 0 0 1-1.414 0l-7-7a1 1 0 0 1 0-1.414Z' fill='rgb(206, 101, 51)'/%3E%3C/svg%3E"); @@ -936,7 +949,7 @@ img[src$='#terminal'] { --ifm-link-hover-color: inherit; cursor: pointer; @apply flex flex-row items-center; - @apply border-secondary-800 bg-secondary-900 hover:bg-secondary-800; + @apply border-secondary-800 bg-secondary-700 hover:bg-secondary-800; border-width: 1px; transition-property: background-color, color; @@ -990,8 +1003,8 @@ details { font-size: 14px; font-weight: 500; color: var(--docs-color-text-100) !important; - background: var(--docs-color-background-100) !important; - border: solid 2px var(--docs-color-code-background) !important; + background: var(--ifm-pre-background) !important; + border: solid 2px var(--ifm-pre-background) !important; } details code { @@ -1120,6 +1133,11 @@ details p { .DocSearch-Button { @apply lg:!rounded-md; + background-color: #ECF8F1 !important; +} + +[data-theme='dark'] .DocSearch-Button { + background-color: #031B24 !important; } .DocSearch-Button-Key { @@ -1623,6 +1641,111 @@ h3.anchor > code { [data-theme="dark"] [data-rmiz-modal-overlay="visible"] { background-color: rgba(0,0,0,0.88) !important; } +/* components/homepage/BlogSection.css */ +.blog-section { + display: flex; + justify-content: center; + align-items: center; + padding: 40px 0; +} + +.blog-container{ + max-width: 1200px; + width: 100%; + padding: 0 20px; +} + +.blog-posts { + display: flex; + flex-wrap: wrap; + gap: 20px; + justify-content: center; +} + +.blog-post { + flex: 1 1 300px; + max-width: 380px; + min-width: 280px; + position: relative; + border-radius: 12px; + box-shadow: 0 2px 8px rgba(0,0,0,0.06); + overflow: hidden; + transition: transform 0.2s, box-shadow 0.2s; + border: 1px solid var(--docs-color-border); +} + +.blog-post p,.blog-post span{ + padding: 0 5px; +} + +.first-post { + position: relative; +} + +.title-overlay { + display: flex; + align-items: center; + gap: 12px; + margin-bottom: 20px; + justify-content: space-between; +} + +.title-overlay h2 { + margin: 0; + color: var(--docs-color-text); + font-size: 1.5rem; + font-weight: 600; + text-shadow: 0 1px 2px rgba(0,0,0,0.1); +} + +.view-all { + color: var(--docs-color-primary); + text-decoration: none; + font-size: 0.9rem; + font-weight: 500; + padding: 4px 12px; + border-radius: 20px; + transition: all 0.2s; +} + +.view-all:hover { + background: var(--docs-color-primary); + color: white; + text-decoration: none; +} + +.blog-post:hover { + transform: scale(1.05); + box-shadow: 0 4px 16px rgba(0,0,0,0.1); +} + + +.navbar__brand img, footer img{ + border-radius: 0; +} + +.navbar__logo img{ + cursor: pointer !important; +} + +.openapi-explorer__code-block{ + background: none !important; +} + +.openapi-explorer__code-block-code-line-number{ + background: none !important; +} + +.openapi-explorer__form-item-input{ + background: none !important; +} + +.openapi-explorer__server-container{ + background: none !important; +} +.openapi-explorer__select-input{ + background: none !important; +} /*FOR MOBILE SCREEN SIZE*/ @media screen and (max-width: 767px) { @@ -1654,5 +1777,4 @@ h3.anchor > code { align-items: center; } } - /* CSS for hello bar ends*/ diff --git a/src/pages/index.jsx b/src/pages/index.jsx index 83569d00..ee528b12 100644 --- a/src/pages/index.jsx +++ b/src/pages/index.jsx @@ -7,6 +7,7 @@ import HomeFooter from '../components/homepage/HomeFooter'; import Head from '@docusaurus/Head'; import GuidesAndSamples from '../components/homepage/GuidesAndSamples'; import ToolsAndInfra from '../components/homepage/ToolsAndInfra'; +import BlogSection from '../components/homepage/BlogSection'; export default function Homepage() { return ( + diff --git a/src/theme/ThemedImage/index.js b/src/theme/ThemedImage/index.js index ce925571..231989cd 100644 --- a/src/theme/ThemedImage/index.js +++ b/src/theme/ThemedImage/index.js @@ -17,9 +17,14 @@ function getSrcFromThemedImageProps(props, isDarkTheme) { export default function ThemedImage(props) { const { colorMode } = useColorMode(); const curSrc = getSrcFromThemedImageProps(props, colorMode); + const { isLogo, ...restProps } = props; + // Exclude navbar logo from Zoom effect + if (isLogo || (typeof props.src === 'string' && props.src.includes('logo'))) { + return ; + } return ( - + ); } diff --git a/static/assets/files/informal_system_genesis_v2_audit_2025_06.pdf b/static/assets/files/informal_system_genesis_v2_audit_2025_06.pdf new file mode 100644 index 00000000..b3e1f293 Binary files /dev/null and b/static/assets/files/informal_system_genesis_v2_audit_2025_06.pdf differ diff --git a/static/assets/files/oak_security_gmbh_genesis_v2_audit-2025_06.pdf b/static/assets/files/oak_security_gmbh_genesis_v2_audit-2025_06.pdf new file mode 100644 index 00000000..10a1c94b Binary files /dev/null and b/static/assets/files/oak_security_gmbh_genesis_v2_audit-2025_06.pdf differ diff --git a/static/img/blog/05-23-bitcoin-native-use-cases/img.png b/static/img/blog/05-23-bitcoin-native-use-cases/img.png new file mode 100644 index 00000000..1b11fce2 Binary files /dev/null and b/static/img/blog/05-23-bitcoin-native-use-cases/img.png differ diff --git a/static/img/blog/05-24-what-is-bitcoin-staking/1.png b/static/img/blog/05-24-what-is-bitcoin-staking/1.png new file mode 100644 index 00000000..5592ec86 Binary files /dev/null and b/static/img/blog/05-24-what-is-bitcoin-staking/1.png differ diff --git a/static/img/blog/05-24-what-is-bitcoin-staking/2.png b/static/img/blog/05-24-what-is-bitcoin-staking/2.png new file mode 100644 index 00000000..faf6be32 Binary files /dev/null and b/static/img/blog/05-24-what-is-bitcoin-staking/2.png differ diff --git a/static/img/blog/05-24-what-is-bitcoin-staking/img.png b/static/img/blog/05-24-what-is-bitcoin-staking/img.png new file mode 100644 index 00000000..4c5ec4d6 Binary files /dev/null and b/static/img/blog/05-24-what-is-bitcoin-staking/img.png differ diff --git a/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/1.png b/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/1.png new file mode 100644 index 00000000..32d246ca Binary files /dev/null and b/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/1.png differ diff --git a/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/2.png b/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/2.png new file mode 100644 index 00000000..e30a12bc Binary files /dev/null and b/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/2.png differ diff --git a/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/img.png b/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/img.png new file mode 100644 index 00000000..394b61bd Binary files /dev/null and b/static/img/blog/05-25-technical-preliminaries-of-bitcoin-staking/img.png differ diff --git a/static/img/blog/05-26-babylon-s-bitcoin-staking-contract/1.png b/static/img/blog/05-26-babylon-s-bitcoin-staking-contract/1.png new file mode 100644 index 00000000..ebfdf896 Binary files /dev/null and b/static/img/blog/05-26-babylon-s-bitcoin-staking-contract/1.png differ diff --git a/static/img/blog/05-26-babylon-s-bitcoin-staking-contract/img.png b/static/img/blog/05-26-babylon-s-bitcoin-staking-contract/img.png new file mode 100644 index 00000000..76c7f2ce Binary files /dev/null and b/static/img/blog/05-26-babylon-s-bitcoin-staking-contract/img.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/1.png b/static/img/guides/baby_stakers/via_mintscan/1.png new file mode 100644 index 00000000..8127c324 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/1.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/10.png b/static/img/guides/baby_stakers/via_mintscan/10.png new file mode 100644 index 00000000..068a1074 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/10.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/10_dark.png b/static/img/guides/baby_stakers/via_mintscan/10_dark.png new file mode 100644 index 00000000..94994553 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/10_dark.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/1_dark.png b/static/img/guides/baby_stakers/via_mintscan/1_dark.png new file mode 100644 index 00000000..f04d6697 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/1_dark.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/2.png b/static/img/guides/baby_stakers/via_mintscan/2.png new file mode 100644 index 00000000..38861705 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/2.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/2_dark.png b/static/img/guides/baby_stakers/via_mintscan/2_dark.png new file mode 100644 index 00000000..d779bbbe Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/2_dark.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/3.png b/static/img/guides/baby_stakers/via_mintscan/3.png new file mode 100644 index 00000000..5f0d6100 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/3.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/3_dark.png b/static/img/guides/baby_stakers/via_mintscan/3_dark.png new file mode 100644 index 00000000..6642d349 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/3_dark.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/4.png b/static/img/guides/baby_stakers/via_mintscan/4.png new file mode 100644 index 00000000..c5931dbf Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/4.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/4_dark.png b/static/img/guides/baby_stakers/via_mintscan/4_dark.png new file mode 100644 index 00000000..7e5639a6 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/4_dark.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/5.png b/static/img/guides/baby_stakers/via_mintscan/5.png new file mode 100644 index 00000000..36d613bd Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/5.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/5_dark.png b/static/img/guides/baby_stakers/via_mintscan/5_dark.png new file mode 100644 index 00000000..0415b311 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/5_dark.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/6.png b/static/img/guides/baby_stakers/via_mintscan/6.png new file mode 100644 index 00000000..9d9ea2be Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/6.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/6_dark.png b/static/img/guides/baby_stakers/via_mintscan/6_dark.png new file mode 100644 index 00000000..5277fc9f Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/6_dark.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/7.png b/static/img/guides/baby_stakers/via_mintscan/7.png new file mode 100644 index 00000000..7b66a8c2 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/7.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/8.png b/static/img/guides/baby_stakers/via_mintscan/8.png new file mode 100644 index 00000000..0e6bad59 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/8.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/8_dark.png b/static/img/guides/baby_stakers/via_mintscan/8_dark.png new file mode 100644 index 00000000..9b3408d6 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/8_dark.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/9.png b/static/img/guides/baby_stakers/via_mintscan/9.png new file mode 100644 index 00000000..21581c83 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/9.png differ diff --git a/static/img/guides/baby_stakers/via_mintscan/9_dark.png b/static/img/guides/baby_stakers/via_mintscan/9_dark.png new file mode 100644 index 00000000..f46c8eb4 Binary files /dev/null and b/static/img/guides/baby_stakers/via_mintscan/9_dark.png differ diff --git a/static/logo/babylon.svg b/static/logo/babylon.svg index c0b10713..8f11e738 100644 --- a/static/logo/babylon.svg +++ b/static/logo/babylon.svg @@ -1,71 +1,16 @@ - - - - - - - - - - + + + + + + + + + + + + + - - - + \ No newline at end of file diff --git a/static/logo/babylon_dark.svg b/static/logo/babylon_dark.svg index 05d23395..f94e5c37 100644 --- a/static/logo/babylon_dark.svg +++ b/static/logo/babylon_dark.svg @@ -1,71 +1,16 @@ - - - - - - - - - - + + + + + + + + + + + + + - - - + \ No newline at end of file diff --git a/static/logo/dark.svg b/static/logo/dark.svg index 1ad0803a..f94e5c37 100644 --- a/static/logo/dark.svg +++ b/static/logo/dark.svg @@ -1,84 +1,16 @@ - - - - - - - - - - + + + + + + + + + + + + + - - - docs - + \ No newline at end of file diff --git a/static/logo/light.svg b/static/logo/light.svg index bd54054a..8f11e738 100644 --- a/static/logo/light.svg +++ b/static/logo/light.svg @@ -1,84 +1,16 @@ - - - - - - - - - - + + + + + + + + + + + + + - - - docs - + \ No newline at end of file diff --git a/static/logo/logo_black.svg b/static/logo/logo_black.svg index c0b10713..f94e5c37 100644 --- a/static/logo/logo_black.svg +++ b/static/logo/logo_black.svg @@ -1,71 +1,16 @@ - - - - - - - - - - + + + + + + + + + + + + + - - - + \ No newline at end of file diff --git a/static/logo/logo_white.svg b/static/logo/logo_white.svg index 05d23395..8f11e738 100644 --- a/static/logo/logo_white.svg +++ b/static/logo/logo_white.svg @@ -1,71 +1,16 @@ - - - - - - - - - - + + + + + + + + + + + + + - - - + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_checkpointing.html b/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_checkpointing.html index 041504b8..afe24f1e 100644 --- a/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_checkpointing.html +++ b/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_checkpointing.html @@ -1,4 +1,29 @@ -

    BTCCheckpoint

    + + + + + + Remote Documentation + + + +
    + +

    BTCCheckpoint

    The BTC Checkpoint module is responsible for receiving and managing the checkpoints of Babylon's state on the Bitcoin blockchain. This includes:

    • handling requests for submitting raw checkpoints
      • @@ -212,4 +237,8 @@

      Available Queries

      Endpoint: /babylon/btccheckpoint/v1/{epoch_num}/submissions
      Description: Retrieves all submissions for a given epoch.

      Additional Information: For further details on how to use these queries and additional documentation, please refer to docs.babylonlabs.io.

      -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_lightclient.html b/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_lightclient.html index 231539ff..222d5f34 100644 --- a/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_lightclient.html +++ b/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_lightclient.html @@ -1,4 +1,29 @@ -

    BTC light client

    + + + + + + Remote Documentation + + + +
    + +

    BTC light client

    The BTC light client module is essentially a BTC light client that maintains the canonical header chain of Bitcoin.

    Babylon chain needs to know about different events happening on Bitcoin chain. @@ -224,4 +249,8 @@

    Events

    message EventBTCHeaderInserted { BTCHeaderInfo header = 1; } -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_staking.html b/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_staking.html index 4225a707..432d3870 100644 --- a/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_staking.html +++ b/static/remote-docs/guides/architecture/babylon_genesis_modules/btc_staking.html @@ -1,4 +1,29 @@ -

    BTCStaking

    + + + + + + Remote Documentation + + + +
    + +

    BTCStaking

    The BTC staking module is responsible for maintaining the set of finality providers and BTC delegations under them. This includes:

      @@ -943,4 +968,8 @@

      Queries

      Description: Retrieves a specific BTC delegation by its corresponding staking transaction hash.

      Additional Information: For further details on how to use these queries and additional documentation, please refer to docs.babylonlabs.io.

      -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/babylon_genesis_modules/checkpointing.html b/static/remote-docs/guides/architecture/babylon_genesis_modules/checkpointing.html index 64102909..d98c5be8 100644 --- a/static/remote-docs/guides/architecture/babylon_genesis_modules/checkpointing.html +++ b/static/remote-docs/guides/architecture/babylon_genesis_modules/checkpointing.html @@ -1,4 +1,29 @@ -

    Checkpointing

    + + + + + + Remote Documentation + + + +
    + +

    Checkpointing

    The Checkpointing module is responsible for generating and maintaining the status of Babylon's Bitcoin checkpoints. The technical core of the Checkpointing module is the BLS signature @@ -328,4 +353,8 @@

    Queries

    The Checkpointing module provides a set of queries about BLS keys the status of checkpoints, listed at docs.babylonlabs.io.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/babylon_genesis_modules/epoching.html b/static/remote-docs/guides/architecture/babylon_genesis_modules/epoching.html index 63681e1d..bba7340c 100644 --- a/static/remote-docs/guides/architecture/babylon_genesis_modules/epoching.html +++ b/static/remote-docs/guides/architecture/babylon_genesis_modules/epoching.html @@ -1,4 +1,29 @@ -

    Epoching

    + + + + + + Remote Documentation + + + +
    + +

    Epoching

    Babylon implements epoched staking to reduce and parameterize the frequency of updating the validator set in @@ -511,4 +536,8 @@

    Queries

    The Epoching module provides a set of queries about epochs, validators and delegations, listed at docs.babylonlabs.io.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/babylon_genesis_modules/finality.html b/static/remote-docs/guides/architecture/babylon_genesis_modules/finality.html index b4cf9468..a759a504 100644 --- a/static/remote-docs/guides/architecture/babylon_genesis_modules/finality.html +++ b/static/remote-docs/guides/architecture/babylon_genesis_modules/finality.html @@ -1,4 +1,29 @@ -

    Finality

    + + + + + + Remote Documentation + + + +
    + +

    Finality

    Babylon's BTC Staking protocol introduces an additional consensus round on blocks produced by CometBFT, called the finality round. The participants of this round are referred to as finality providers and their voting power stems from @@ -475,4 +500,8 @@

    Queries

    The Finality module provides a set of queries about finality signatures on each block, listed at docs.babylonlabs.io.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/btc_staking_program/btc_reorg_procedure.html b/static/remote-docs/guides/architecture/btc_staking_program/btc_reorg_procedure.html index 1eacea3f..f4f0e2ac 100644 --- a/static/remote-docs/guides/architecture/btc_staking_program/btc_reorg_procedure.html +++ b/static/remote-docs/guides/architecture/btc_staking_program/btc_reorg_procedure.html @@ -1,81 +1,106 @@ -

    Large BTC Reorgs Recovery Procedure

    -

    Babylon relies in a number of confirmation blocks in BTC to accept BTC -staking transacitons, this number is defined inside the x/btccheckpoint + + + + + + Remote Documentation + + + +

    + +

    Large BTC Reorgs Recovery Procedure

    +

    Babylon relies on a number of confirmation blocks on Bitcoin to accept BTC +staking transactions. This number is defined inside the x/btccheckpoint Parameter as BtcConfirmationDepth and as k in the research papers -which we considerate to be an irreversible block.

    -

    If for some unexpected reason there is a reorg in the bitcoin blockchain +which we consider to be an irreversible block.

    +

    If for some unexpected reason there is a reorg in the Bitcoin blockchain larger than the BtcConfirmationDepth, the chain should halt and revoke all the BTC delegations that were recorded until the first reorg block height.

    -

    By example, if BTC is in block height 150 and Babylon chain has a -BtcConfirmationDepth of 10 and it is submitted a valid BTC reorg of 15 blocks -that rollbacks BTC to block height 136, every BTC delegation that was included -in BTC block 136 or higher should be deleted as the inclusion proof will -be different. BTC delegations that included in the BTC block height 135 or lower -will not be affected as the BTC rollbacks only happens if there is a better -chain presented, a better chain means chain with more blocks, so any BTC +

    By example, if the Bitcoin chain is in block height 150 and Babylon chain has a +BtcConfirmationDepth of 10 and it is submitted a valid Bitcoin reorg of 15 blocks +that rollbacks Bitcoin to block height 136, every BTC delegation that was included +in Bitcoin block 136 or higher should be deleted as the inclusion proof will +be different. BTC delegations that are included in the Bitcoin block height 135 or lower +will not be affected as the Bitcoin rollbacks only happens if there is a better +chain presented. A better chain means a chain that has more blocks, so any BTC delegation included in block 135 or prior would still be considered valid.

    This recovery procedure only cares about the BTC transactions that were executed in blocks which have been rollbacked.

    Chain Halt

    -

    If the chain halted due to a BTC reorg largest than BtcConfirmationDepth, -there is a few steps to be followed to gather the data to be modified at the +

    If the chain is halted due to a Bitcoin chain reorg larger than BtcConfirmationDepth, +there are a few steps to be followed to gather the data to be modified by the emergency upgrade handler:

    -

    1. Collect correspondent Babylon height

    -

    The correlation of BTC and Babylon block heights can be found in the x/btcstaking +

    1. Collect Corresponding Babylon Height

    +

    The correlation of Bitcoin and Babylon block heights can be found in the x/btcstaking state in the BlockHeightChains, currently there is no query for it, but it can be retrieved by exporting the genesis state.

    -

    2. Collect BTC related msgs that were rollbacked

    -

    After having collected the babylon block height corresponded to the BTC block +

    2. Collect Bitcoin Related Messages that were Rollbacked

    +

    After having collected the Babylon block height corresponding to the Bitcoin block height which the rollback happened, iterate over every transaction until -the halt block and gather all the messages which were approved and are one of +the halt block, then gather all the messages which were approved and are of one of the types: MsgCreateBTCDelegation, MsgAddBTCDelegationInclusionProof, MsgBTCUndelegate, MsgInsertHeaders and MsgInsertBTCSpvProof.

    -

    3. Analyze each message

    -

    Each BTC related msg that was rollbacked might need to have a different treatment.

    +

    3. Analyze Each Message

    +

    Each Bitcoin related message that was rollbacked might need to have a different treatment.

    3.1 MsgCreateBTCDelegation

    -

    The msg which creates a new BTC delegation, if doesn't have inclusion proof -can stay as it is was not active or anything and neither had the inclusion -proof sent.

    -

    If there was a inclusion proof, verify if the proof is one from the BTC block -heights which was rollbacked, if it is from an BTC block that was not reorg, -but it was only later included in the Babylon chain, all good and there is -nothing to do. Now, if it was rollbacked this BTC staking transaction needs to -be removed from the following modules state x/btcstaking, x/finality, +

    The message which creates a new Bitcoin delegation, if it doesn't have inclusion proof +can stay as it was not active, and neither had the inclusion +proof been sent.

    +

    If there was an inclusion proof, verify if the proof is from one of the Bitcoin block +heights which was rollbacked. If it is from a Bitcoin block that was not reorg, +but it was only later included in the Babylon chain, this is good and there is +nothing to do. Now if it was rollbacked, this BTC staking transaction needs to +be removed from the following modules states x/btcstaking, x/finality, x/incentives.

    • x/btcstaking
      • Remove from BTCDelegatorKey -the BTC staking tx hash.
        • +the BTC staking transaction hash.
      • Remove from BTCDelegationKey -the BTC staking tx hash.
        • +the BTC staking transaction hash.
      • Remove the PowerDistUpdateKey if a EventPowerDistUpdate_BtcDelStateUpdate was emitted for that -BTC staking tx hash.
        • +BTC staking transaction hash.
    • x/finality
      • Update the voting power amount in VotingPowerKey -by subtracting the satoshi amounts of the finality provider that the BTC +by subtracting the satoshi amounts of the Finality Provider that the BTC delegation delegated to if that BTC delegation was active.
      • Subtract the TotalVotingPower and the respective FinalityProviderDistInfo -based on which finality provider was delegated to in +based on which Finality Provider was delegated to in VotingPowerDistCacheKey if that BTC delegation was active.
    • x/incentives If that BTC delegation was ever active, there is a need to -subtract the voting power from the rewards tracker. Also it is only modified -the values from now on, if rewards were accured from a BTC staking transaction -that was rollbacked, the past is behind us and it should be let with the funds -that were accured, losing a few coins in the rewards. +subtract the voting power from the rewards tracker. Also it only modifies +the values from now on. If rewards were accrued from a BTC staking transaction +that was rollbacked, the past is behind us, and it should be left with the funds +that were accrued, losing a few coins in the rewards.
      • For the incentives module state there is a single function which should be called BtcDelegationUnbonded -which receives as parameter the Finality provider and BTC delegator baby -address and the amount of satoshi from the rollbacked BTC delegation. +which receives as parameter the Finality Provider and BTC delegator Babylon +address and the amount of satoshis from the rollbacked BTC delegation. This will already update all the keys in the state accordingly.
      • @@ -83,9 +108,9 @@

      3.1 MsgCreateBTCDelegation

      Note transactions that were included during blocks 150 ~ 141 (150 - BtcConfirmationDepth) in a 15 Bitcoin blocks rollback are invalid and should be removed but were -also not considered deep enough to be active. Dropping those proofs and +also not considered deep enough to be active. Dropping those proofs and the event updates to voting power table is enough to handle during the -recory procedure.

      +recovery procedure.

      3.2 MsgAddBTCDelegationInclusionProof

      Check if the proof is one from the BTC block heights which was rollbacked, @@ -94,27 +119,25 @@

      3.2 MsgAddBTCDelegationInclusionProof

      to remove the data from the 3 modules states.

      3.3 MsgBTCUndelegate

      Check if the inclusion proof had a reorg in the BTC blocks, if it is not -rollbacked, there is nothing to do. If it was rollbacked it is needed -to remove the existence of this BTC undelegation and affecting 3 modules state -with similar steps took at 3.1.

      +rollbacked, there is nothing to do. If it was rollbacked, remove the existence of this BTC undelegation and the affecting 3 modules states with similar steps taken at 3.1.

      • x/btcstaking
        • Clean out the field for BtcUndelegation in BTCDelegation for the key BTCDelegationKey -in which corresponds to the BTC staking tx hash.
          • +in which corresponds to the BTC staking transaction hash.
        • Remove the PowerDistUpdateKey if a EventPowerDistUpdate_BtcDelStateUpdate was emitted for that -BTC staking tx hash with Undelegate.
          • +BTC staking transaction hash with Undelegate.
      • x/finality
        • Update the voting power amount in VotingPowerKey -by adding the satoshi amounts of the finality provider that the BTC +by adding the satoshi amounts of the Finality Provider that the BTC delegation delegated to.
        • Add the TotalVotingPower and the respective FinalityProviderDistInfo -based on which finality provider was delegated to in +based on which Finality Provider was delegated to in VotingPowerDistCacheKey.
        • @@ -122,8 +145,8 @@

        3.3 MsgBTCUndelegate

        • For the incentives module state there is a single function which should be called BtcDelegationActivated -which receives as parameter the Finality provider and BTC delegator baby -address and the amount of satoshi from the rollbacked BTC undelegate. +which receives as parameter the Finality Provider and BTC delegator Babylon +address and the amount of satoshis from the rollbacked BTC undelegate. This will already update all the keys in the state accordingly.
        @@ -132,28 +155,28 @@

        3.4 MsgInsertHeaders

        The module x/btclightclient automatically handles the rollback of blocks, the issue relies when the Babylon chain was halted while Bitcoin was producing new blocks, the new blocks should have it's headers collected and included into the Babylon chain -state when it is being recovered. If the headers are not insterted, an attacker +state when it is being recovered. If the headers are not inserted, an attacker could mine just 1-2 blocks on the forked Bitcoin chain and cause Babylon chain to execute fake delegations, right after Babylon chain restarts. To avoid this, -Babylon should insert headers of the created Bitcoind blocks while it was +Babylon should insert headers of the created Bitcoin blocks while it was down during the recovery procedure.

        3.5 MsgInsertBTCSpvProof

        -

        All the proofs that were sent by the vigilante reporter in the Bitcoin blocks +

        All the proofs that were sent by the Vigilante Reporter in the Bitcoin blocks that were affected by the rollback, will need to be revoked and might modify -the status of checkpoints, the recovery procedure for this specific case -might also need to modify the vigilante to send again transactions of +the status of checkpoints. The recovery procedure for this specific case +might also need to modify the Vigilante to send again transactions of checkpoints to the main chain of Bitcoin. This inserted proofs will -then need to be included into Babylon state and update checkpoint status -accordingly to chain configuration of BtcConfirmationDepth and +then need to be included into the Babylon state and checkpoint status updated +accordingly to the chain configuration of BtcConfirmationDepth and CheckpointFinalizationTimeout in the x/btccheckpoint module.

        4. Overall updates

        Beside the specific cases of the messages sent, there is also the need -to update some state about the new heights as in:

        +to update some states about the new heights as in:

        • x/btcstaking
          • Update BTCHeightKey -the babylon height corresponded to the BTC block height
            • +the Babylon height corresponding to the BTC block height
          • Remove the LargestBtcReorgInBlocks value previous set, to avoid halting again from the same BTC reorg.
          @@ -161,16 +184,17 @@

          4. Overall updates

        Create the emergency upgrade handler

        The emergency upgrade handler is called a -Fork in the structures as the chain is halted -and there is no possibility to create a software upgrade proposal -that handles nicely the upgrade plan. So, the fork structure +Fork in the structures as the chain is halted and there is no possibility to create a software upgrade proposal +that nicely handles the upgrade plan. So, the fork structure would contain as the name something that correlates with the BTC block heights which were reorg, the upgrade height would be defined as the Babylon block height in which the panic for reorg happened and the BeginForkLogic should contain a single function that modifies the keepers with the data collected during step 3.

        After that, tag a new release with the emergency upgrade in it, following -the Release Procedure -test the logic in a private enviroment and if it all the state is modified -as expected, announce the new binary for validators.

        -
    \ No newline at end of file +the Release Procedure. Test the logic in a private environment and if all the state is modified as expected, announce the new binary for Validators.

    + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/btc_staking_program/finality_providers.html b/static/remote-docs/guides/architecture/btc_staking_program/finality_providers.html index 6bc5e060..dd69654f 100644 --- a/static/remote-docs/guides/architecture/btc_staking_program/finality_providers.html +++ b/static/remote-docs/guides/architecture/btc_staking_program/finality_providers.html @@ -1,4 +1,29 @@ -

    Finality Provider

    + + + + + + Remote Documentation + + + +
    + +

    Finality Provider

    Finality providers are key participants in the Babylon BTC staking protocol. They provide finality votes on top of CometBFT, Babylon's consensus mechanism, @@ -146,4 +171,8 @@

    Overview of Keys for Finality Provider and EOTS Manager

    governance).

    Once a finality provider is created, neither key can be rotated or changed - they are permanently associated with that specific finality provider instance.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/consumer_zone_programs/babylon_contracts.html b/static/remote-docs/guides/architecture/consumer_zone_programs/babylon_contracts.html index c442ee80..29308d59 100644 --- a/static/remote-docs/guides/architecture/consumer_zone_programs/babylon_contracts.html +++ b/static/remote-docs/guides/architecture/consumer_zone_programs/babylon_contracts.html @@ -1,4 +1,29 @@ -

    Babylon-contract

    + + + + + + Remote Documentation + + + +
    + +

    Babylon-contract

    This repo contains the Wasm smart contract for Babylon integrations. It will be deployed on a Cosmos zone that integrates Babylon, and will maintain BTC timestamps of headers in this Cosmos zone.

    Development

    @@ -46,4 +71,8 @@

    Generate test data

    Build the optimized contract

    cargo run-script optimize
    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/architecture/consumer_zone_programs/zone_concierge.html b/static/remote-docs/guides/architecture/consumer_zone_programs/zone_concierge.html index 4e44af35..175d4e06 100644 --- a/static/remote-docs/guides/architecture/consumer_zone_programs/zone_concierge.html +++ b/static/remote-docs/guides/architecture/consumer_zone_programs/zone_concierge.html @@ -1,4 +1,29 @@ -

    ZoneConcierge

    + + + + + + Remote Documentation + + + +
    + +

    ZoneConcierge

    The Zone Concierge module is responsible for generating BTC timestamps of headers from other PoS blockchains. These BTC timestamps allow PoS blockchains integrating with Babylon to achieve Bitcoin security, i.e., forking the PoS @@ -50,8 +75,7 @@

    Table of contents

    Concepts

    The Zone Concierge module is responsible for providing BTC timestamps of headers -from PoS blockchains connected to Babylon via the IBC protocol.
    -These BTC timestamps allow PoS blockchains to achieve Bitcoin security, i.e., +from PoS blockchains connected to Babylon via the IBC protocol. These BTC timestamps allow PoS blockchains to achieve Bitcoin security, i.e., forking a PoS blockchain is as hard as forking Bitcoin. The Zone Concierge module leverages the IBC light client protocol to receive headers with a valid quorum certificate from PoS blockchains. These headers are then timestamped @@ -96,12 +120,12 @@

    Problem Statement

    validators in Babylon or PoS blockchains. That is, the above statement shall hold even if Babylon and a PoS blockchain have dishonest supermajority. The formal security analysis of the Bitcoin timestamping protocol can be found at -the Bitcoin timestamping reseaarch paper +the Bitcoin timestamping research paper published at S&P'23.

    Design

    The Zone Concierge module is responsible for checkpointing headers from PoS blockchains and propagating succinct and verifiable information about them back -to the PoS blockchains. Specifically, the Zone Concierge module

    +to the PoS blockchains. Specifically, the Zone Concierge module:

    • leverages IBC light clients for checkpointing PoS blockchains;
    • intercepts and indexes headers from PoS blockchains; and
      • @@ -160,27 +184,27 @@

      Design

      multi-signature jointly generated by the epoch's validator set. The last proof is formed as Merkle proofs of two transactions that constitute a BTC checkpoint, same as in BTCCheckpoint module.

      -

      Use cases

      +

      Use Cases

      The Bitcoin-checkpointed PoS blockchain will enable several applications, such as raising alarms upon dishonest majority attacks and reducing the unbonding period. These use cases require new plugins in the PoS blockchains, and will be -developed by Babylon team in the future.

      -

      Raising Alarms upon Dishonest Majority Attacks. Zone Concierge timestamps -fork headers that have valid quorum certificates. Such fork header signals a -safety attack launched by the dishonest majority of validators. Babylon can send +developed by the Babylon team in the future.

      +

      Raising Alarms upon Dishonest Majority Attacks. The Zone Concierge module timestamps +fork headers that have valid quorum certificates. These fork headers signal a +safety attack launched by a dishonest majority of validators. Babylon can send the fork header back to the corresponding PoS blockchain, such that the PoS -blockchain will get notified with this dishonest majority attack, and can decide -to stall or initiate a social consensus.

      -

      Reducing Unbonding Period. Zone Concierge provides a Bitcoin-checkpointed -prefix for a PoS blockchain. Such Bitcoin-checkpointed prefix resists against -the long range attacks, thus unbonding requests in this prefix can be safely +blockchain will get notified of this dishonest majority attack, and can decide +whether to stall or initiate a social consensus.

      +

      Reducing Unbonding Period. The Zone Concierge module provides a Bitcoin-checkpointed +prefix for a PoS blockchain. Such a Bitcoin-checkpointed prefix resists against +long range attacks. Unbonding requests in this prefix can be safely finished, leading to much shorter unbonding period compared to that in existing PoS blockchains (e.g., 21 days in Cosmos SDK chains).

      State

      The Zone Concierge module keeps handling IBC headers of PoS blockchains, and maintains the following KV stores.

      Parameters

      -

      The parameter storage maintains Zone Concierge module's +

      The parameter storage maintains the Zone Concierge module's parameters. The Zone Concierge module's parameters are represented as a Params object defined as follows:

      // Params defines the parameters for the module.
@@ -287,10 +311,10 @@ 
      Hooks
      
 
      The Zone Concierge module subscribes to the Epoching module's AfterEpochEnds
 hook for indexing the epochs when receiving
 headers from PoS blockchains, and the Checkpointing module's
-AfterRawCheckpointFinalized hook for phase
+AfterRawCheckpointFinalized hook for Phase
 2 integration.
      
 
      Indexing headers upon AfterEpochEnds
      
-
      The AfterEpochEnds hook is triggered upon an epoch is ended, i.e., the last
+
      The AfterEpochEnds hook is triggered when an epoch is ended, i.e., the last
 block in this epoch has been committed by CometBFT. Upon AfterEpochEnds, the
 Zone Concierge will save the current ChainInfo to the EpochChainInfo storage
 for each PoS blockchain.
      
@@ -357,12 +381,12 @@ 
      Sending BTC timestamps upon AfterRawCheckpointFinalized
      
   repeated babylon.btccheckpoint.v1.TransactionInfo proof_epoch_submitted = 3;
 }
      -

      Upon AfterRawCheckpointFinalized is triggered, the Zone Concierge module will +

      When AfterRawCheckpointFinalized is triggered, the Zone Concierge module will send an IBC packet including a BTCTimestamp to each PoS blockchain doing -phase 2 +Phase 2 integration with Babylon. The logic is defined at -x/zoneconcierge/keeper/hooks.go and works as follows.

      +x/zoneconcierge/keeper/hooks.go and works as follows:

      1. Find all open IBC channels with Babylon's Zone Concierge module. The counterparty at each IBC channel is a PoS blockchain.
        2. @@ -399,10 +423,10 @@

        Sending BTC timestamps upon AfterRawCheckpointFinalized

      -

      Interaction with PoS blockchains under phase 1 integration

      -

      In phase 1 integration, Babylon maintains headers for a PoS blockchain via the +

      Interaction with PoS Blockchains under Phase 1 Integration

      +

      In Phase 1 integration, Babylon maintains headers for a PoS blockchain via the IBC light client protocol. The IBC light client of the PoS blockchain is -checkpointed by Bitcoin via Babylon, thus achieves Bitcoin security.

      +checkpointed by Bitcoin via Babylon, thus achieving Bitcoin security.

      Babylon utilizes the IBC light client protocol for receiving headers from other PoS blockchains. The IBC headers are @@ -415,15 +439,14 @@

      Interaction with PoS blockchains under phase 1 integration

      The IBCHeaderDecorator PostHandler intercepts the headers and indexes their positions in the ChainInfo storage, as per here. This effectively checkpoints the -headers of PoS blockchains, completing the phase 1 integration.

      -

      Interaction with PoS blockchains under phase 2 integration

      -

      In phase 2 integration, Babylon does everything in phase 1, and will send BTC +headers of PoS blockchains, completing the Phase 1 integration.

      +

      Interaction with PoS Blockchains under Phase 2 Integration

      +

      In Phase 2 integration, Babylon does everything in Phase 1, and will send BTC timestamps of headers back to each PoS blockchain. Each PoS blockchain can verify the BTC timestamp and ensure that each header is finalized by Bitcoin, thus obtaining Bitcoin security. The BTC timestamps can be used by the PoS -blockchain
      -for different use cases, e.g., BTC-assisted unbonding.

      -

      The phase 2 integration does not require any change to the PoS blockchain's +blockchain for different use cases, e.g. BTC-assisted unbonding.

      +

      The Phase 2 integration does not require any change to the PoS blockchain's code. Rather, it only needs to deploy a Babylon contract on the PoS blockchain, and start an IBC relayer between Babylon and the Babylon contract on @@ -431,14 +454,14 @@

      Interaction with PoS blockchains under phase 2 integration

      supporting CosmWasm smart contracts, connects with Babylon's Zone Concierge module via an IBC channel, and receives BTC timestamps from Babylon to help the PoS blockchain get Bitcoin security.

      -

      Upon a Babylon epoch becoming finalized, i.e., upon +

      Upon a Babylon epoch becoming finalized, i.e., when AfterRawCheckpointFinalized is triggered, Babylon will send an IBC packet -including a BTCTimestamp to each PoS blockchain doing phase 2/3 integration +including a BTCTimestamp to each PoS blockchain doing Phase 2/3 integration with Babylon, as per here.

      -

      Note that Zone Concierge provides 1-to-all connection, where the Zone Concierge +

      Note that the Zone Concierge module provides 1-to-all connection, where the Zone Concierge module establishes an IBC channel with each of multiple consumer chains. Zone -Concierge will send an BTC timestamp to each of these consumer chains upon an +Concierge will send a BTC timestamp to each of these consumer chains when an epoch is finalized.

      Messages and Queries

      The Zone Concierge module only has one message MsgUpdateParams for updating @@ -446,4 +469,8 @@

      Messages and Queries

      It provides a set of queries about the status of checkpointed PoS blockchains, listed at docs.babylonlabs.io.

      -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee-mainnet.html b/static/remote-docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee.html similarity index 88% rename from static/remote-docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee-mainnet.html rename to static/remote-docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee.html index 67bdacdc..27b59195 100644 --- a/static/remote-docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee-mainnet.html +++ b/static/remote-docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee.html @@ -1,4 +1,29 @@ -

    Covenant Committee

    + + + + + + Remote Documentation + + + +
    + +

    Covenant Committee

    The Covenant Emulation committee comprises of entities operating a covenant signer to sign on-demand unbonding and slashing transactions. The committee has 9 seats, which are filled by the following entities:

    @@ -114,4 +139,8 @@

    Phase-1

    • - \ No newline at end of file + + + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-1/mainnet/finality_provider_registration.html b/static/remote-docs/guides/networks/phase-1/mainnet/finality_provider_registration.html index 47237079..889a8266 100644 --- a/static/remote-docs/guides/networks/phase-1/mainnet/finality_provider_registration.html +++ b/static/remote-docs/guides/networks/phase-1/mainnet/finality_provider_registration.html @@ -1,4 +1,29 @@ -

    Finality Provider Information Registry

    + + + + + + Remote Documentation + + + +
    + +

    Finality Provider Information Registry

    ⚠️ Important: Phase-1 registrations of finality providers are now closed and this guide is a legacy one. @@ -324,4 +349,8 @@

    6. Modifying Finality Provider Information

    key, and create a pull request updating their information. These steps can be performed by the processes outlined previously in the guide and the pull request submitted by the same GitHub account.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-1/mainnet/global_parameters.html b/static/remote-docs/guides/networks/phase-1/mainnet/global_parameters.html index e2bdbd02..71bea3a9 100644 --- a/static/remote-docs/guides/networks/phase-1/mainnet/global_parameters.html +++ b/static/remote-docs/guides/networks/phase-1/mainnet/global_parameters.html @@ -1,4 +1,29 @@ -

    Staking Parameters

    + + + + + + Remote Documentation + + + +
    + +

    Staking Parameters

    Important Note: These parameters apply only to the Phase-1 of the Babylon launch. From Phase-2 onwards, the parameters listed here will be deprecated, @@ -127,4 +152,8 @@

    Updating staking parameters

  • After enough approvals are gathered, the PR is merged. Now the tip of the main branch contains the last version of staking parameters.
    • -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-1/testnet/covonent_committee/covonent_committee.html b/static/remote-docs/guides/networks/phase-1/testnet/covonent_committee/covonent_committee.html index 36847976..a26bce91 100644 --- a/static/remote-docs/guides/networks/phase-1/testnet/covonent_committee/covonent_committee.html +++ b/static/remote-docs/guides/networks/phase-1/testnet/covonent_committee/covonent_committee.html @@ -1,4 +1,29 @@ -

    Covenant Committee

    + + + + + + Remote Documentation + + + +
    + +

    Covenant Committee

    The Covenant Emulation Committee comprises entities operating Covenant Signer daemons.

    For this testnet, the Covenant Emulation Committee has 9 members, 3 of which @@ -36,4 +61,8 @@

    Cubist

    • https://bbn-test-4-covsign.cubestake.xyz:443
    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-1/testnet/finality_provider_registration.html b/static/remote-docs/guides/networks/phase-1/testnet/finality_provider_registration.html index a8073ffc..8203fa61 100644 --- a/static/remote-docs/guides/networks/phase-1/testnet/finality_provider_registration.html +++ b/static/remote-docs/guides/networks/phase-1/testnet/finality_provider_registration.html @@ -1,4 +1,29 @@ -

    Finality Provider Information Registry

    + + + + + + Remote Documentation + + + +
    + +

    Finality Provider Information Registry

    Due to fulfillment of the finality provider quotas, registration will be turned off for the bbn-test-4 on Monday, 24 June 2024 EoD AoE.

    @@ -275,4 +300,8 @@

    5. Create Pull Request

    BTC check transaction ✅ 'my_nickname' is a valid fp registration -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-1/testnet/global_parameters.html b/static/remote-docs/guides/networks/phase-1/testnet/global_parameters.html index fcdad6c8..e379408f 100644 --- a/static/remote-docs/guides/networks/phase-1/testnet/global_parameters.html +++ b/static/remote-docs/guides/networks/phase-1/testnet/global_parameters.html @@ -1,4 +1,29 @@ -

    Staking Parameters

    + + + + + + Remote Documentation + + + +
    + +

    Staking Parameters

    The staking parameters are governance parameters that specify what constitutes a valid staking transaction that should be considered as an active one for the lock-only testnet system. @@ -110,4 +135,8 @@

    Updating staking parameters

  • After enough approvals are gathered, the PR is merged. Now the tip of the main branch contains the last version of staking parameters.
    • -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-2/mainnet/mainnet.html b/static/remote-docs/guides/networks/phase-2/mainnet/mainnet.html index a9601c43..69ee7d1f 100644 --- a/static/remote-docs/guides/networks/phase-2/mainnet/mainnet.html +++ b/static/remote-docs/guides/networks/phase-2/mainnet/mainnet.html @@ -1,4 +1,29 @@ -

    Babylon Mainnet

    + + + + + + Remote Documentation + + + +
    + +

    Babylon Mainnet

    Welcome to the network page for the Babylon mainnet. This is your central hub for network participation information, whether you're running a node, @@ -77,4 +102,8 @@

    Phase-1 Mainnet

    ⚠️ Warning: The Babylon Genesis mainnet has not yet launched, so the Phase-1 mainnet still remains the current supported Babylon mainnet.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-2/testnet/testnet.html b/static/remote-docs/guides/networks/phase-2/testnet/testnet.html index b5025ea5..ddcb4fd8 100644 --- a/static/remote-docs/guides/networks/phase-2/testnet/testnet.html +++ b/static/remote-docs/guides/networks/phase-2/testnet/testnet.html @@ -1,4 +1,29 @@ -

    Babylon testnet-5 Network

    + + + + + + Remote Documentation + + + +
    + +

    Babylon testnet-5 Network

    Welcome to the network page for the Babylon Phase-2 testnet (bbn-test-5). This is your central hub for network participation information, whether you're running a node, @@ -114,4 +139,8 @@

    Network Participants

  • Finality Providers
  • Covenant Committee
    • -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/networks/phase-3/devnet/devnet.html b/static/remote-docs/guides/networks/phase-3/devnet/devnet.html index 353f0343..2439ddbf 100644 --- a/static/remote-docs/guides/networks/phase-3/devnet/devnet.html +++ b/static/remote-docs/guides/networks/phase-3/devnet/devnet.html @@ -1,4 +1,29 @@ -

    Babylon Phase 3 Devenet (Euphrates 0.5.0)

    + + + + + + Remote Documentation + + + +
    + +

    Babylon Phase 3 Devenet (Euphrates 0.5.0)

    The Phase 3 Devenet is a development network of Babylon Genesis Chain. It implements the full funcationality of Bitcoin staking and allow BSNs to be connected.

    Network Parameters

    Chain ID

    @@ -53,4 +78,8 @@

    Network Participants

  • Finality Providers
  • Covenant Committee
    • -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/eligibility.html b/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/eligibility.html index 8615032d..438b2f2c 100644 --- a/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/eligibility.html +++ b/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/eligibility.html @@ -1,4 +1,29 @@ -

    Staking Registration Eligibility

    + + + + + + Remote Documentation + + + +
    + +

    Staking Registration Eligibility

    1. Introduction
    2. Terminology @@ -180,4 +205,8 @@

      4. Retrieving details about the timeline

      hashes can be found here:

      app/upgrades/v1/testnet/allowed_staking_tx_hashes.go
      -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html b/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html index 9dfedb62..f6ea9100 100644 --- a/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html +++ b/static/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html @@ -1,4 +1,29 @@ -

    Bitcoin Stake Registration

    + + + + + + Remote Documentation + + + +
    + +

    Bitcoin Stake Registration

    Table of contents

    1. Introduction
      2. @@ -33,14 +58,14 @@

      Table of contents

    1. Introduction

    This document walks through the communication protocol -with the Babylon chain in order to register Bitcoin stakes. +with the Babylon Genesis chain in order to register Bitcoin stakes. The document is structured as follows:

    • Section 2 provides an overview -of the two flows for registering stakes on the Babylon chain.
      • +of the two flows for registering stakes on the Babylon Genesis chain.
    • Section 3 describes the data required for stake registration, the registration process itself, and the MsgCreateBTCDelegation message used -to communicate staking transactions to the Babylon chain.
      • +to communicate staking transactions to the Babylon Genesis chain.
    • Section 4 details stake management, including on-demand unbonding and withdrawal.
    • Section 5 focuses on the Bitcoin staking rewards @@ -49,34 +74,32 @@

      1. Introduction

      Target Audience: This document is intended as a reference for technical readers that intend to implement their own methods for registering Bitcoin stakes (either ones already on Bitcoin or new ones). Alternative methods of staking -including (or hosting a staking platform) include using the front-end CLI +(or hosting a staking platform) include using the front-end CLI (running the simple staking reference implementation) or using the Staker CLI program.

      2. Bitcoin Stake Registration Methods

      -

      Bitcoin stakes must be registered on the Babylon blockchain -to gain voting power and earn rewards. -This registration process involves -submitting a registration transaction -followed by the validation of the staking operation by key -network components including the Babylon chain CometBFT validators +

      Bitcoin stakes must be registered on the Babylon Genesis blockchain +to gain voting power and earn rewards. This registration process involves +submitting a registration transaction followed by the validation of the staking operation by key +network components including the Babylon Genesis chain CometBFT Validators and the covenant committee.

      -

      There are two main methods for registering Bitcoin stakes on the Babylon blockchain:

      +

      There are two main methods for registering Bitcoin stakes on the Babylon Genesis chain:

      • Post-staking registration: This applies to stakers who have already submitted -their BTC Staking transaction on the Bitcoin network and then register it on Babylon -(e.g., phase-1 stakers).
        • -
      • Pre-staking registration: This is for stakers who seek validation from the Babylon -chain before submitting their staking transaction on Bitcoin and locking their funds, -ensuring acceptance guarantees (e.g., newly created stakes after the Babylon chain launch).
        • +their BTC Staking transaction on the Bitcoin network and then register it on Babylon Genesis +(e.g., Phase-1 stakers). +
      • Pre-staking registration: This is for stakers who seek validation from the Babylon Genesis +chain before submitting their staking transaction to Bitcoin and locking their funds, +ensuring acceptance guarantees (e.g., newly created stakes after the Babylon Genesis chain launch).

      Each approach is designed to accommodate different staking preferences and circumstances. In the following sections, we will explore the approaches in more detail.

      ⚡ A Note on k-depth: In the following sections, -we frequently refer to k-depth. The Babylon chain +we frequently refer to k-depth. The Babylon Genesis chain only activates staking transactions if they reach k-depth, -where k is a Babylon chain parameter defined in the +where k is a Babylon Genesis chain parameter defined in the x/btccheckpoint module (as btc_confirmation_depth) and controlled by governance.

      Depth measures how deep a transaction's block is within the Bitcoin blockchain. @@ -91,17 +114,17 @@

      2. Bitcoin Stake Registration Methods

      2.1. Post-Staking Registration

      This flow applies to stakers whose BTC staking transaction has already been confirmed in a Bitcoin block that is k-deep -and is subsequently registered on the Babylon chain. -For example, this includes participants from a Babylon phase-1 network.

      +and is subsequently registered on the Babylon Genesis chain. +For example, this includes participants from the Babylon Phase-1 network.

      The following diagram illustrates the post-staking registration flow: stake-registration-post-staking-flow

      Steps:

      1. Generate staking metadata: Retrieve the staking transaction from its included Bitcoin block and generate the proof of inclusion.
        2. -
      2. Fill the MsgCreateBTCDelegation message with the unbonding transaction, -signed slashing transactions and proof of possession (POP) and broadcast it to -the Babylon blockchain (details on how to do this will be provided in +
      3. Fill the MsgCreateBTCDelegation message with the unbonding transaction, +signed slashing transactions and Proof of Possession (POP) and broadcast it to +the Babylon Genesis blockchain (details on how to do this will be provided in Section 3.4.)
      4. Await Covenant Verification: The stake will remain in a PENDING state until the covenants provide their verification signatures.
        5. @@ -117,25 +140,25 @@

        2.1. Post-Staking Registration

        the rejection of any subsequent staking registrations of it. In those cases, the stake will have to be unbonded and staked again.

        ⚠️ Important Warning about Finality Providers: Be cautious when selecting a -finality provider for your stake. If the finality provider you delegate to gets +Finality Provider for your stake. If the Finality Provider you delegate to gets slashed before your stake is registered, your stake may become stuck. This is -particularly important for Phase-1 stake that is in the process of being +particularly important for Phase-1 stakes that are in the process of being registered.

      2.2. Pre-Staking Registration

      -

      The Pre-staking registration flow is for stakers who seek +

      The Pre-staking registration flow is for stakers who seek verification from the Babylon chain before submitting their BTC staking transaction to the Bitcoin ledger. By doing so, they gain assurance that their stake will be accepted before locking their funds on Bitcoin.

      The process begins with the staker submitting all relevant staking data -to the Babylon chain. Subsequently, the covenant committee provides +to the Babylon Genesis chain. Subsequently, the covenant committee provides verification signatures for on-demand unbonding and slashing, giving the staker the required assurance for moving on with broadcasting their BTC staking transaction. After the transaction is confirmed in a Bitcoin block that is k-deep, the staker (or an automated service like the -vigilante watcher) +Vigilante Watcher) submits a proof of inclusion to finalize the registration and lead to stake activation.

      The following diagram illustrates the pre-staking registration flow: @@ -143,7 +166,7 @@

      2.2. Pre-Staking Registration

      Steps:

      1. Fill the MsgCreateBTCDelegation message with necessary metadata and -broadcast it to the Babylon blockchain. +broadcast it to the Babylon Genesis blockchain. (details on how to do this will be provided in Section 3.4.)
        @@ -163,15 +186,15 @@

        2.2. Pre-Staking Registration

        Vigilante Watcher (or the staker) monitors Bitcoin for transaction confirmation and k-deep inclusion.
      2. Confirm k-deep Inclusion: -The vigilante watcher will identify that the transaction is k-deep in the Bitcoin chain.
        3. +The Vigilante Watcher will identify that the transaction is k-deep in the Bitcoin chain.
      3. Submit Proof of Inclusion: -Once the transaction is k-deep, the vigilante watcher (or the staker) submits +Once the transaction is k-deep, the Vigilante Watcher (or the staker) submits MsgAddBTCDelegationInclusionProof.

        ⚡ Note: If you prefer not to rely on the Vigilante Watcher, you can manually track Bitcoin depth and submit this message yourself. Details on the message construction can be found on the x/btcstaking module documentation. -For the rest of the document, we will assume reliance on the vigilante watcher service +For the rest of the document, we will assume reliance on the Vigilante Watcher service for simplicity.

        4. @@ -181,49 +204,49 @@

        2.2. Pre-Staking Registration

        ⚠️ Critical Warning: After your transaction is confirmed in a Bitcoin block, remember to submit the proof of inclusion to complete the registration process.

        -

        ⚠️ Important: Gas Requirements for Pre-staking registration

        +

        ⚠️ Important: Gas Requirements for Pre-staking Registration

        Since pre-staking registration does not require prior fund commitment -on Bitcoin, it could be exploited for chain spamming, especially -due to the multiple covenant signature submissions it triggers.

        +on Bitcoin, it could be exploited for chain spamming. This is especially +due to the multiple covenant signature submissions that it triggers.

        To mitigate this, submitting a MsgCreateBTCDelegation via the pre-staking registration flow requires an increased -minimum gas fees that covers the gas for the staking, +minimum gas fee that covers the gas for the staking, covenant signatures, and proof of inclusion submissions. -This mimimum gas is defined by the delegation_creation_base_gas_fee -staking parameter of the Babylon chain +This minimum gas is defined by the delegation_creation_base_gas_fee +staking parameter of the Babylon Genesis chain (this parameter will be detailed in Section 3.2.).

        ⚠️ Important Warning about Finality Providers: Be cautious when selecting a -finality provider for your stake. If the finality provider you delegate to gets +Finality Provider for your stake. If the Finality Provider you delegate to gets slashed before your stake is registered, your stake may become stuck. This is -particularly important for Phase-1 stake that is in the process of being +particularly important for Phase-1 stakes that are in the process of being registered.

        3. Bitcoin Stake Registration

        3.1. Overview of Registration Data

        -

        Registering a Bitcoin stake on the Babylon chain requires submitting the +

        Registering a Bitcoin stake on the Babylon Genesis chain requires submitting the staking transaction along with essential metadata. This section provides an overview of the required data, while later sections detail how to create and package it into a -Babylon registration transaction.

        +Babylon Genesis registration transaction.

        Key Registration Data:

        • BTC Staking Transaction: The Bitcoin transaction that locks the Bitcoin stake in the self-custodial Bitcoin staking script. It can be submitted signed or unsigned, depending on the staking flow and UTXO inputs.
        • Unbonding Transaction: An unsigned unbonding transaction allowing -the staker to on-demand unbond their stake. It is submitted to the Babylon chain +the staker to on-demand unbond their stake. It is submitted to the Babylon Genesis chain and co-signed by the covenants upon verification.
        • Slashing Transactions: Two staker pre-signed slashing transactions (one for staking, one for unbonding) that ensure enforcement -of slashing if the finality provider to which the stake is delegated to -double-signs. They are submitted to the Babylon chain and co-signed +of slashing if the Finality Provider to which the stake is delegated to +double-signs. They are submitted to the Babylon Genesis chain and co-signed by the covenants upon verification.
        • Proof of Possession: Confirms ownership of the Bitcoin key by the Babylon account used for stake registration.
        • Merkle Proof of Inclusion: Verifies transaction inclusion in a Bitcoin block that is k-deep. Submitted during initial registration in the post-staking -registration flow or later in the pre-staking registration flow.
          • +registration flow, or later in the pre-staking registration flow.

        ⚠️ Critical Warning: The proof of inclusion is a vital part of your @@ -235,31 +258,31 @@

        3.1. Overview of Registration Data

        transactions can be found in the Bitcoin Staking script specification.

        ⚠️ Important Warning about Finality Providers: Be cautious when selecting a -finality provider for your stake. If the finality provider you delegate to gets +Finality Provider for your stake. If the Finality Provider you delegate to gets slashed before your stake is registered, your stake may become stuck. This is -particularly important for Phase-1 stake that is in the process of being +particularly important for Phase-1 stakes that are in the process of being registered.

        -

        Once assembled, this data is packaged into a Babylon chain transaction and +

        Once assembled, this data is packaged into a Babylon Genesis chain transaction and broadcast to the network. The process differs based on whether the staker follows the pre-staking or post-staking registration flow.

        Upcoming Sections:

        • Required parameters for BTC Staking transactions.
        • Construction of Bitcoin transactions for staking.
          • -
        • Building the Babylon chain transaction with required staking data.
          • -
        • Submitting the registration transaction to the Babylon chain.
          • +
        • Building the Babylon Genesis chain transaction with required staking data.
          • +
        • Submitting the registration transaction to Babylon Genesis.
        -

        3.2. Babylon Chain BTC Staking Parameters

        -

        BTC Staking transactions must adhere to parameters defined by the Babylon chain, -which vary based on Bitcoin block heights. Each parameters version +

        3.2. Babylon Genesis Chain BTC Staking Parameters

        +

        BTC Staking transactions must adhere to parameters defined by the Babylon Genesis chain, +which vary based on Bitcoin block heights. Each parameter version is defined by a btc_activation_height, determining the Bitcoin height -from which the parameters version takes effect. +from which the parameter version takes effect. To determine the applicable parameter version for a staking taking effect at Bitcoin block height lookup_btc_height:

          -
        1. Sort all parameters versions by btc_activation_height in ascending order.
          2. -
        2. The first parameters version with lookup_btc_height >= btc_activation_height +
        3. Sort all parameter versions by btc_activation_height in ascending order.
          4. +
        4. The first parameter version with lookup_btc_height >= btc_activation_height applies to the staking.

        Below is an overview of the key staking parameters contained in the different @@ -283,26 +306,26 @@

        3.2. Babylon Chain BTC Staking Parameters

        The minimum transaction fee (in satoshis) required for the pre-signed slashing transaction.
      4. slashing_rate: A scalar specifying the percentage of stake -slashed if the finality provider double-signs.
        5. +slashed if the Finality Provider double-signs.
      5. unbonding_time_blocks: The on-demand unbonding time in Bitcoin blocks.
      6. unbonding_fee_sat: The Bitcoin fee in satoshis required for unbonding transactions.
      7. min_commission_rate: A scalar defining the minimum commission rate -for finality providers.
        8. +for Finality Providers.
      8. delegation_creation_base_gas_fee: Defines the minimum gas fee to be paid when registering a stake through the pre-staking registration flow.
      9. allow_list_expiration_height: The Babylon block height -on which the initial staking transaction allow-list expires. +at which the initial staking transaction allow-list expires. More details on the allow list can be found here.
        10. -
      10. btc_activation_height: The Bitcoin block height on which this parameters version +
      11. btc_activation_height: The Bitcoin block height at which the parameter version takes effect.

    ⚡ Retrieving Staking Parameters

    These parameters are part of the x/btcstaking -module parameters can be queried via a Babylon node using +module parameters that can be queried via a Babylon node using RPC/LCD endpoints or the CLI.

    ⚠️ Warning: Make sure that you are retrieving the BTC Staking parameters from a trusted node and you verify their authenticity using additional @@ -322,7 +345,7 @@

    3.2. Babylon Chain BTC Staking Parameters

  • Pre-staking registration flow: Use the parameters matching the Babylon on-chain Bitcoin light client at the time of pre-staking registration. This ensures that the transaction commits to be validated -against the current staking parameters version (as observed by the Babylon chain). +against the current staking parameters version (as observed by Babylon Genesis). This ensures that the pre-staking registered transaction will remain valid even if it is later included in a Bitcoin block for which different parameters take effect, @@ -331,10 +354,10 @@

    3.2. Babylon Chain BTC Staking Parameters

    or the CLI.
    • -

    3.3. Creating the Bitcoin transactions

    +

    3.3. Creating Bitcoin Transactions

    The Bitcoin staking parameters from the previous section are used to create the necessary Bitcoin transactions for registering -a Bitcoin stake on the Babylon and Bitcoin ledgers. +a Bitcoin stake on the Babylon Genesis and Bitcoin ledgers. These transactions include:

    • BTC Staking Transaction: The Bitcoin transaction that locks @@ -357,12 +380,12 @@

      3.3. Creating the Bitcoin transactions

      ⚡ Note: Ensure you use the valid Babylon parameters when creating the Bitcoin transactions.

      -

      3.4. The MsgCreateBTCDelegation Babylon message

      +

      3.4. The MsgCreateBTCDelegation Babylon Message

      Cosmos SDK transactions are used for registering -BTC delegations on the Babylon chain. +BTC delegations on Babylon Genesis. The MsgCreateBTCDelegation message bundles the necessary staking data and registers -the Bitcoin stake on the Babylon blockchain.

      +the Bitcoin stake on the Babylon Genesis blockchain.

      Key Fields in MsgCreateBTCDelegation

      // MsgCreateBTCDelegation is the message for creating a BTC delegation
 message MsgCreateBTCDelegation {
@@ -494,14 +517,14 @@ 
      Explanation of Fields
      
 
      ⚠️ Important: Should the Inputs of the Staking Transaction be Signed?
      
 
      Whether the staking transaction should include signed or unsigned
 UTXO inputs depends on the type of inputs used.
-Since the Babylon chain tracks staking transactions based on
+Since the Babylon Genesis chain tracks staking transactions based on
 their transaction hash, it's crucial for the staker to submit
 the staking transaction in a format that contains all the
 necessary data to generate the full hash corresponding
 to the fully signed transaction.
      
 
      For legacy inputs that require the script_sig field to be filled,
 the signature must be included when submitting the
-transaction to Babylon, as this field directly influences
+transaction to Babylon Genesis, as this field directly influences
 the transaction hash.
      
 
      On the other hand, for inputs that require the witness field
 (e.g., SegWit inputs), the signature does not need to be
@@ -527,7 +550,7 @@ 
      Explanation of Fields
      
 on Bitcoin before receiving covenant verification).
 However, some stakers might still choose the pre-staking
 registration flow, as it requires less waiting time
-(if the staker chooses to rely on the vigilante watcher)
+(if the staker chooses to rely on the Vigilante Watcher)
 compared to the post-staking registration flow.
      • @@ -535,7 +558,7 @@

      Explanation of Fields

      staking_tx_inclusion_proof (Optional): A merkle proof showing the staking transaction's inclusion in k-deep Bitcoin block. This field should be filled in when going through -the post-staking registration flow and left empty when going through +the post-staking registration flow and left empty when going through the pre-staking registration flow. The field is defined as an InclusionProof protobuf data type (specified below) with the following fields:

      // in x/btccheckpoint module types
@@ -582,12 +605,11 @@ 
      Explanation of Fields
      
 slashing path and the staker's BIP-340 (Schnorr) signature for it.
 Both are in hex format.
 This transaction is considered fully signed once it has signatures
-from the staker, a quorum of the covenants, and the finality provider.
+from the staker, a quorum of the covenants, and the Finality Provider.
 Upon transaction verification, the covenant signatures are added,
-meaning that only the finality provider's signature is missing.
-According to the BTC Staking protocol,
-if the finality provider double-signs,
-its private key is exposed, leading to the full signature set.
      
+meaning that only the Finality Provider's signature is missing.
+According to the BTC Staking protocol, this means if the Finality Provider double-signs,
+and its private key is exposed, leading to the full signature set.
      
 
 
    • 
 
      unbonding_time:
@@ -642,7 +664,7 @@ 
      3.5. Constructing the MsgCreateBTCDelegation
      
 
    • Phase-1 staking transactions using the post-staking registration flow will
 only be accepted if they meet
 these eligibility criteria.
      • 
-
    • New phase-2 staking registration, whether created
+
    • New Phase-2 staking registration, whether created
 through the pre-staking or post-staking registration flow,
 will only be accepted once the allow-list expires.
      •
    @@ -682,12 +704,12 @@

    4.1. On-demand Unbonding

  • the Golang staking library utils
    • -

    ⚡ Note: Unbonding notification on the Babylon chain

    +

    ⚡ Note: Unbonding Notification on the Babylon Genesis Chain

    The Babylon system employs the Vigilante Unbonding Watcher, a service that monitors the Bitcoin ledger for on-demand unbonding transactions -and reports them back to the Babylon chain. Once the unbonding transaction -is included Bitcoin, the vigilante detects it and notifies Babylon, +and reports them back to the Babylon Genesis chain. Once the unbonding transaction +is included Bitcoin, the Vigilante detects it and notifies the Babylon Genesis chain, causing the stake to lose its voting power.

    4.2. Withdrawing Expired/Unbonded Bitcoin Stake

    @@ -709,19 +731,19 @@

    4.2. Withdrawing Expired/Unbonded Bitcoin Stake

  • the Golang staking library utils

    • 4.3. Withdrawing Remaining Funds after Slashing

    -

    Bitcoin stake is slashed if the finality provider to +

    A Bitcoin stake is slashed if the Finality Provider to which it was delegated to double-signs. Slashing involves broadcasting a slashing transaction that sends a portion of the slashed funds to a burn address -(as defined in the staking params in Section 3.2.), +(as defined in the staking parameters in Section 3.2.), while the remaining funds are transfered to a timelock script, which can later be withdrawn using the same withdrawal process defined in the previous section.

    To determine the slashing timelock, refer to the unbonding_time_blocks -parameter in the Babylon Chain BTC Staking Parameters. Babylon ensures that the timelock on the change output of a slashing +parameter in the Babylon Chain BTC Staking Parameters. Babylon Genesis ensures that the timelock on the change output of a slashing transaction matches the unbonding time. Therefore, the unbonding time parameter effectively represents your slashing timelock. The reasoning behind -the timelock is that we want to avoid situation in which some finality providers +the timelock is that we want to avoid situations in which some Finality Providers could use slashing as a way to unbond instantly.

    5. Bitcoin Staking Rewards

    Bitcoin stakers are rewarded with native tokens from @@ -744,8 +766,8 @@

    5.1. Rewards Distribution

    • Bitcoin Stakers Portion: Defined by the btc_staking_portion parameter, which specifies the portion of rewards allocated to Bitcoin stakers. This is -calculated based on the voting power and commission rate of the finality -provider the stake has been delegated to.
      • +calculated based on the voting power and commission rate of the Finality +Provider the stake has been delegated to.
    • Community Pool Portion: Typically defined in the x/distribution module of the Cosmos SDK, often referred to as the community tax.
    • Native Stakers Portion: The remaining rewards, after allocations to @@ -754,7 +776,7 @@

      5.1. Rewards Distribution

    • Rewards for Bitcoin stakers are further distributed based on the voting power -and commission rate of the finality provider the stake has been delegated to. +and commission rate of the Finality Provider the stake has been delegated to. The rewards are entered into a gauge, which stakers can query and withdraw from through a transaction submission.

      • @@ -806,4 +828,8 @@

      5.2. Rewards Withdrawal

    • via TypeScript: You can use the TypeScript implementation to query rewards. Please refer to the TypeScript library documentation.
    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/specifications/bitcoin_staking_scripts-version-next-v2.x.html b/static/remote-docs/guides/specifications/bitcoin_staking_scripts-version-next-v2.x.html new file mode 100644 index 00000000..960d085c --- /dev/null +++ b/static/remote-docs/guides/specifications/bitcoin_staking_scripts-version-next-v2.x.html @@ -0,0 +1,410 @@ + + + + + + Remote Documentation + + + +
    +
    Version: next-v2.x
    +

    Bitcoin Staking Transactions Specification

    +

    Table of contents

    +
      +
    1. Introduction
      2. +
    2. Preliminaries +
        +
      1. Building Blocks
        2. +
      2. Stakeholders
        3. +
      +
      3. +
    3. BTC Staking Protocol Transactions +
        +
      1. The Staking Output
        2. +
      2. The Unbonding Output
        3. +
      3. The Slashing Refund Output
        4. +
      +
      4. +
    +

    1. Introduction

    +

    The Babylon BTC Staking protocol turns Bitcoin into a staking asset, +aiming to onboard both the asset and its holders to the +Bitcoin Supercharged Networks (BSNs) ecosystem and the Babylon Genesis +chain (the first BSN).

    +

    Bitcoin holders can stake their BTC by locking it using a +special transaction on the Bitcoin network. +Once locked, the Bitcoin contributes to the economic security of +BSNs selected to be secured, +which in turn enables new opportunities for stakers, +such as earning staking yields.

    +

    This document specifies the structure of the transactions involved +in the BTC Staking protocol. +These transactions must conform to a defined format and +commit to specific Taproot scripts. +The values in these scripts are governed by +parameters defined on the Babylon Genesis chain and +the staker's selections.

    +
    +

    ⚡ For information on retrieving Babylon Genesis parameters and +registering valid staking transactions, +refer to the +registering Bitcoin stakes documentation

    +
    +

    2. Preliminaries

    +

    2.1. Building Blocks

    +

    The Bitcoin Staking protocol transaction specification is +heavily based on Bitcoin's +Taproot upgrade, +which introduced +Schnorr signatures.

    +

    2.2. Stakeholders

    +

    The Bitcoin Staking protocol involves the following stakeholders:

    +
      +
    • Bitcoin Staker: +The Bitcoin staker is the controller and beneficiary of the +Bitcoin stake once it is created. +The staker is identified by their Bitcoin public key +(referenced as <StakerPk> in the staking scripts). +
      +

      ⚡ The staker public key does not need to match the UTXO funder of the +staking transaction. The funding UTXO can originate from any source, +including multi-sig, MPC, or threshold-controlled accounts.

      +
      +
      • +
    • Finality Providers: +Bitcoin Staking supports delegated staking, +allowing voting power from a stake to be assigned +to a finality provider. +A finality provider is identified by their EOTS public +key (<FinalityProviderPk>) and participates in the finality +voting round of a specific BSN. +The selection of a finality provider also implicitly determines +the BSN they secure, as each provider may only secure one BSN. +Bitcoin stakers specify their chosen finality provider by including +their EOTS key in the staking script. +
      +

      ⚠️ Currently, only a single finality provider securing the Babylon Genesis chain +can be selected. Future protocol versions will support additional BSNs and allow +BTC stakers to delegate to providers securing those networks.

      +
      +
      • +
    • Covenant Committee: +The role of the covenant committee (identified +by the Bitcoin public keys of its members CovenantPk1..CovenantPkN) +is to protect BSNs against attacks from the BTC stakers and finality providers. +It achieves this by representing itself as an M-out-of-N multi-signature +that co-signs BTC transactions with the BTC staker. Through co-signing, +the covenant committee enforces spending rules on the staked Bitcoin, +so that they can only be spent in a protocol compliant manner. +The co-signatures are published on the Babylon Genesis chain and +are a pre-requisite for the stake's activation. +There's no way the covenant committee can act against the stakers, +except rejecting their staking requests.
      • +
    • Babylon Genesis chain: +The Babylon Genesis chain is the first BSN and acts as the control layer +for the BTC staking protocol. All Bitcoin stakes and finality providers +must be registered on the Babylon Genesis chain. +It is also responsible for propagating staking-related data to other BSNs.
      • +
    +
    +

    ⚠️ Staking scripts must not contain duplicate keys. +The public keys for StakerPk, FinalityProviderPk, and each CovenantPk +must be unique within a single stake.

    +
    +

    3. BTC Staking Protocol Transactions

    +

    The Bitcoin Staking protocol defines four key transaction types:

    +
      +
    • Staking Transaction: +A staking transaction is a Bitcoin +transaction that locks a specific amount of BTC into +the Babylon-recognized staking script. +It marks the beginning of a BTC staking lifecycle. +The requirements for a valid staking transaction are: +
        +
      • It can contain an arbitrary number of inputs.
        • +
      • It can contain an arbitrary number of outputs, +with the requirement that at least one of those outputs +—referred to as the staking output— +is a Taproot output that commits to the Bitcoin Staking script.
        • +
      +
      • +
    • Unbonding Transaction: +The unbonding transaction is a Bitcoin transaction +that enables the staker to on-demand unbond their Bitcoin before the staking +timelock they originally committed to as part of the staking transaction expires. +The requirements for a valid unbonding transaction are: +
        +
      • It contains exactly one input which points to the staking output in which the +Bitcoin to be on-demand unbonded have been locked in.
        • +
      • It contains exactly one output—referred to as the unbonding output— +that is a Taproot output committing to the Bitcoin Staking unbonding script.
        • +
      • The Bitcoin fee of the unbonding transaction must be equal to the fee +for unbonding transactions specified in the +Babylon Genesis parameters.
        • +
      +
      • +
    • Slashing Transaction: +The slashing transaction is used to punish a BTC staker +when the finality provider they have delegated to double-signs. The requirements +for a valid slashing transaction are: +
        +
      • It must have exactly one input pointing to either the staking output or +the unbonding output.
        • +
      • It must have exactly two outputs, +
          +
        • the first sending the slashed fraction +of the funds to a burn address specified in the Babylon Genesis chain's parameters, and
          • +
        • the second sending the remaining funds to a Taproot output—referred to as the +slashing refund output— which locks the funds in a short timelock before they are redeemable +by the staker.
          • +
        +
        • +
      • The fee of the Bitcoin slashing transaction must be larger than or equal to the +minimum fee specified for slashing transactions in the +Babylon Genesis parameters.
        • +
      +
      • +
    • Withdrawal Transaction: +The withdrawal transaction is a Bitcoin transaction that +extracts unlocked Bitcoin from the timelock script associated with a Bitcoin Staking script +(either Staking, Unbonding, or Slashing). The only requirement for a valid withdrawal transaction +is that one of its inputs is a Staking, Unbonding, or Slashing output.
      • +
    +

    The following diagram shows how the above transactions create and spend +different Bitcoin outputs:

    +
    stateDiagram-v2
+    active: Staking output
+    unbonding: Unbonding output
+    state stake_slashing <<fork>>
+    state unbonding_slashing <<fork>>
+    burn_staking: Burn address output
+    change_staking: Change output
+    burn_unbonding: Burn address output
+    change_unbonding: Change output
+
+    [*] --> active: Staking transaction
+
+    active --> unbonding: Unbonding transaction
+
+    unbonding --> [*]: Unbonding withdrawal transaction
+
+    unbonding --> unbonding_slashing: Slashing transaction
+    unbonding_slashing --> burn_unbonding
+    unbonding_slashing --> change_unbonding
+    change_unbonding --> [*]: Withdrawal transaction
+
+    active --> [*]: Staking withdrawal transaction
+
+    active --> stake_slashing: Slashing transaction
+
+    stake_slashing --> burn_staking
+    stake_slashing --> change_staking
+    change_staking --> [*]: Withdrawal transaction
+
    +

    3.1. The Staking Output

    +

    The staking output is a Taproot output which can only be spent through +the script spending path. +The key spending path is disabled by using the "Nothing Up My Sleeve" +(NUMS) point as the internal key. +The NUMS point used is the one defined in +BIP341:

    +
    H = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0)
+
    +

    This point is derived by hashing the standard uncompressed encoding of the +secp256k1 base point G as the X coordinate.

    +

    The staking output can be spent through one of the following three script paths:

    +
      +
    1. +

      Timelock Path: +This path locks the staker's Bitcoin for a predefined number of Bitcoin blocks.

      +
      <StakerPK> OP_CHECKSIGVERIFY  <TimelockBlocks> OP_CHECKSEQUENCEVERIFY
+
      +

      Fields:

      +
        +
      • <StakerPK> is the BTC staker's public key.
        • +
      • <TimelockBlocks> defines the number of Bitcoin blocks the funds +are committed to remain locked. This duration starts once the staking +transaction is confirmed in a Bitcoin block. +Requirements: +
          +
        • The timelock must be lower than 65535.
          • +
        • The timelock should be within the bounds for Bitcoin staking transaction +timelocks defined in the +Babylon Genesis parameters.
          • +
        +
        • +
      +
      2. +
    2. +

      Unbonding Path: +This path allows the staker to unlock their Bitcoin on-demand, +before the timelock expires.

      +
      <StakerPk> OP_CHECKSIGVERIFY
+<CovenantPk1> OP_CHECKSIG <CovenantPk2> OP_CHECKSIGADD ... <CovenantPkN> OP_CHECKSIGADD
+<CovenantThreshold> OP_NUMEQUAL
+
      +

      Fields:

      +
        +
      • StakerPK is the BTC staker's public key.
        • +
      • CovenantPk1..CovenantPkN are the lexicographically sorted public keys of the +covenant committee as defined in the +Babylon Genesis parameters.
        • +
      • CovenantThreshold is a Babylon parameter specifying the number of how many +covenant committee member signatures are required. It is defined in the +Babylon Genesis parameters.
        • +
      +

      This path protects against immediate withdrawal without protocol-compliant unbonding, +by requiring signatures from a quorum of the covenant committee.

      +
      3. +
    3. +

      Slashing Path: +This path is used to slash staked funds when the +finality provider to which they have been delegated to +is proven to have double-signed.

      +
      <StakerPk> OP_CHECKSIGVERIFY
+<FinalityProviderPk> OP_CHECKSIGVERIFY
+<CovenantPk1> OP_CHECKSIG <CovenantPk2> OP_CHECKSIGADD ... <CovenantPkN> OP_CHECKSIGADD
+<CovenantThreshold> OP_NUMEQUAL
+
      +

      Fields:

      +
        +
      • StakerPK is the BTC staker's public key.
        • +
      • FinalityProviderPk is the public key of the finality provider +to which the stake is delegated. +
        +

        ⚡ At the moment, only a single finality provider is supported. +Once multi-staking is enabled, the script will be modified to accommodate +more finality providers.

        +
        +
        • +
      • CovenantPk1..CovenantPkN are the lexicographically sorted public keys of the +covenant committee as defined in the +Babylon Genesis parameters.
        • +
      • CovenantThreshold is a Babylon parameter specifying the number of how many +covenant committee member signatures are required. It is defined in the +Babylon Genesis parameters.
        • +
      +

      This path can only be executed with the collaboration of the BTC staker, finality provider, +and covenant committee. The staker is required to submit a pre-signature +for spending the slashing path in order for their stake to be accepted. +The covenant signatures are required to protect against +non protocol-compliant withdrawals. More details on the procedure +for registering stake can be found on the +registering Bitcoin stakes documentation.

      +
      4. +
    +
    +

    ⚡ Key Difference Between the Unbonding and Slashing Paths

    +

    The main difference lies in the presence of <FinalityProviderPk> in +the slashing path which has the following implications:

    +
      +
    • For a staking request to become active, the BTC staker must include +a valid (unsigned) unbonding transaction in the staking request. +It becomes active only when the Babylon Genesis chain receives +CovenantThreshold signatures by the covenant committee. +Since the unbonding path does not include <FinalityProviderPk>, +the staker can exit at any time without needing the finality provider's +consent.
      • +
    • In contrast, the slashing path does include <FinalityProviderPk> and +requires a pre-signed slashing transaction by both the staker and a +CovenantThreshold of the covenant emulation committee to become active. +This ensures that the finality provider's cooperation is needed to prevent +slashing, but not to execute it. If a finality provider misbehaves, +their key is exposed and can be used to execute the slashing.
      • +
    +
    +

    3.2. The Unbonding Output

    +

    The unbonding output is a Taproot output which can only be spent through the +script spending path. The key spending path is disabled by using +the "Nothing Up My Sleeve" (NUMS) point as the internal key. +The NUMS point used is the one defined in +BIP341:

    +
    H = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0)
+
    +

    This point is derived by hashing the standard uncompressed encoding of the +secp256k1 base point G as the X coordinate.

    +

    The unbonding output can be spent through one of the following two script paths:

    +
      +
    1. Timelock path: +This path locks the staker's Bitcoin for a predefined number of Bitcoin blocks. +
      <StakerPK> OP_CHECKSIGVERIFY  <TimelockBlocks> OP_CHECKSEQUENCEVERIFY
+
      +Fields: +
        +
      • <StakerPK> is the BTC staker's public key.
        • +
      • <TimelockBlocks> defines the unbonding time. It must equal +the value specified for unbonding defined in the +Babylon Genesis parameters.
        • +
      +
      2. +
    2. Slashing path: +This path is used to slash staked funds when the +finality provider to which they have been delegated to +is proven to have double-signed while the stake is in the unbonding period. +
      <StakerPk> OP_CHECKSIGVERIFY
+<FinalityProviderPk> OP_CHECKSIGVERIFY
+<CovenantPk1> OP_CHECKSIG <CovenantPk2> OP_CHECKSIGADD ... <CovenantPkN> OP_CHECKSIGADD
+<CovenantThreshold> OP_NUMEQUAL
+
      +Fields: +
        +
      • StakerPK is the BTC staker's public key.
        • +
      • FinalityProviderPk is the public key of the finality provider +to which the stake is delegated. +
        +

        ⚡ At the moment, only a single finality provider is supported. +Once multi-staking is enabled, the script will be modified to accommodate +more finality providers.

        +
        +
        • +
      • CovenantPk1..CovenantPkN are the lexicographically sorted public keys of the +covenant committee as defined in the +Babylon Genesis parameters.
        • +
      • CovenantThreshold is a Babylon parameter specifying the number of how many +covenant committee member signatures are required. It is defined in the +Babylon Genesis parameters.
        • +
      +
      3. +
    +
    +

    ⚡ Slashing Path in the Unbonding Output

    +

    The presence of the slashing path in the unbonding output ensures that a BTC staker +can still be slashed during the unbonding period, +if their delegated finality provider double-signs.

    +
    +

    3.3. The Slashing Refund Output

    +

    The slashing refund output returns the non-slashed portion of the staked funds +to the staker in the case of slashing. It is an output committing to the +following timelock script:

    +
    <StakerPK> OP_CHECKSIGVERIFY  <TimelockBlocks> OP_CHECKSEQUENCEVERIFY`
+
    +

    Fields:

    +
      +
    • <StakerPK> is BTC staker public key.
      • +
    • <TimelockBlocks> defines the time in which the funds +will remain locked before being accessible. This timelock is there +to ensure that the slashing path is not maliciously used to retrieve the +remaining funds faster than the unbonding time. It must equal +the value specified for unbonding time defined in the +Babylon Genesis parameters.
      • +
    + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/specifications/bitcoin_staking_scripts-version-next-v4.x.html b/static/remote-docs/guides/specifications/bitcoin_staking_scripts-version-next-v4.x.html new file mode 100644 index 00000000..bf5a564f --- /dev/null +++ b/static/remote-docs/guides/specifications/bitcoin_staking_scripts-version-next-v4.x.html @@ -0,0 +1,410 @@ + + + + + + Remote Documentation + + + +
    +
    Version: next-v4.x
    +

    Bitcoin Staking Transactions Specification

    +

    Table of contents

    +
      +
    1. Introduction
      2. +
    2. Preliminaries +
        +
      1. Building Blocks
        2. +
      2. Stakeholders
        3. +
      +
      3. +
    3. BTC Staking Protocol Transactions +
        +
      1. The Staking Output
        2. +
      2. The Unbonding Output
        3. +
      3. The Slashing Refund Output
        4. +
      +
      4. +
    +

    1. Introduction

    +

    The Babylon BTC Staking protocol turns Bitcoin into a staking asset, +aiming to onboard both the asset and its holders to the +Bitcoin Supercharged Networks (BSNs) ecosystem and the Babylon Genesis +chain (the first BSN).

    +

    Bitcoin holders can stake their BTC by locking it using a +special transaction on the Bitcoin network. +Once locked, the Bitcoin contributes to the economic security of +BSNs selected to be secured, +which in turn enables new opportunities for stakers, +such as earning staking yields.

    +

    This document specifies the structure of the transactions involved +in the BTC Staking protocol. +These transactions must conform to a defined format and +commit to specific Taproot scripts. +The values in these scripts are governed by +parameters defined on the Babylon Genesis chain and +the staker's selections.

    +
    +

    ⚡ For information on retrieving Babylon Genesis parameters and +registering valid staking transactions, +refer to the +registering Bitcoin stakes documentation

    +
    +

    2. Preliminaries

    +

    2.1. Building Blocks

    +

    The Bitcoin Staking protocol transaction specification is +heavily based on Bitcoin's +Taproot upgrade, +which introduced +Schnorr signatures.

    +

    2.2. Stakeholders

    +

    The Bitcoin Staking protocol involves the following stakeholders:

    +
      +
    • Bitcoin Staker: +The Bitcoin staker is the controller and beneficiary of the +Bitcoin stake once it is created. +The staker is identified by their Bitcoin public key +(referenced as <StakerPk> in the staking scripts). +
      +

      ⚡ The staker public key does not need to match the UTXO funder of the +staking transaction. The funding UTXO can originate from any source, +including multi-sig, MPC, or threshold-controlled accounts.

      +
      +
      • +
    • Finality Providers: +Bitcoin Staking supports delegated staking, +allowing voting power from a stake to be assigned +to a finality provider. +A finality provider is identified by their EOTS public +key (<FinalityProviderPk>) and participates in the finality +voting round of a specific BSN. +The selection of a finality provider also implicitly determines +the BSN they secure, as each provider may only secure one BSN. +Bitcoin stakers specify their chosen finality provider by including +their EOTS key in the staking script. +
      +

      ⚠️ Currently, only a single finality provider securing the Babylon Genesis chain +can be selected. Future protocol versions will support additional BSNs and allow +BTC stakers to delegate to providers securing those networks.

      +
      +
      • +
    • Covenant Committee: +The role of the covenant committee (identified +by the Bitcoin public keys of its members CovenantPk1..CovenantPkN) +is to protect BSNs against attacks from the BTC stakers and finality providers. +It achieves this by representing itself as an M-out-of-N multi-signature +that co-signs BTC transactions with the BTC staker. Through co-signing, +the covenant committee enforces spending rules on the staked Bitcoin, +so that they can only be spent in a protocol compliant manner. +The co-signatures are published on the Babylon Genesis chain and +are a pre-requisite for the stake's activation. +There's no way the covenant committee can act against the stakers, +except rejecting their staking requests.
      • +
    • Babylon Genesis chain: +The Babylon Genesis chain is the first BSN and acts as the control layer +for the BTC staking protocol. All Bitcoin stakes and finality providers +must be registered on the Babylon Genesis chain. +It is also responsible for propagating staking-related data to other BSNs.
      • +
    +
    +

    ⚠️ Staking scripts must not contain duplicate keys. +The public keys for StakerPk, FinalityProviderPk, and each CovenantPk +must be unique within a single stake.

    +
    +

    3. BTC Staking Protocol Transactions

    +

    The Bitcoin Staking protocol defines four key transaction types:

    +
      +
    • Staking Transaction: +A staking transaction is a Bitcoin +transaction that locks a specific amount of BTC into +the Babylon-recognized staking script. +It marks the beginning of a BTC staking lifecycle. +The requirements for a valid staking transaction are: +
        +
      • It can contain an arbitrary number of inputs.
        • +
      • It can contain an arbitrary number of outputs, +with the requirement that at least one of those outputs +—referred to as the staking output— +is a Taproot output that commits to the Bitcoin Staking script.
        • +
      +
      • +
    • Unbonding Transaction: +The unbonding transaction is a Bitcoin transaction +that enables the staker to on-demand unbond their Bitcoin before the staking +timelock they originally committed to as part of the staking transaction expires. +The requirements for a valid unbonding transaction are: +
        +
      • It contains exactly one input which points to the staking output in which the +Bitcoin to be on-demand unbonded have been locked in.
        • +
      • It contains exactly one output—referred to as the unbonding output— +that is a Taproot output committing to the Bitcoin Staking unbonding script.
        • +
      • The Bitcoin fee of the unbonding transaction must be equal to the fee +for unbonding transactions specified in the +Babylon Genesis parameters.
        • +
      +
      • +
    • Slashing Transaction: +The slashing transaction is used to punish a BTC staker +when the finality provider they have delegated to double-signs. The requirements +for a valid slashing transaction are: +
        +
      • It must have exactly one input pointing to either the staking output or +the unbonding output.
        • +
      • It must have exactly two outputs, +
          +
        • the first sending the slashed fraction +of the funds to a burn address specified in the Babylon Genesis chain's parameters, and
          • +
        • the second sending the remaining funds to a Taproot output—referred to as the +slashing refund output— which locks the funds in a short timelock before they are redeemable +by the staker.
          • +
        +
        • +
      • The fee of the Bitcoin slashing transaction must be larger than or equal to the +minimum fee specified for slashing transactions in the +Babylon Genesis parameters.
        • +
      +
      • +
    • Withdrawal Transaction: +The withdrawal transaction is a Bitcoin transaction that +extracts unlocked Bitcoin from the timelock script associated with a Bitcoin Staking script +(either Staking, Unbonding, or Slashing). The only requirement for a valid withdrawal transaction +is that one of its inputs is a Staking, Unbonding, or Slashing output.
      • +
    +

    The following diagram shows how the above transactions create and spend +different Bitcoin outputs:

    +
    stateDiagram-v2
+    active: Staking output
+    unbonding: Unbonding output
+    state stake_slashing <<fork>>
+    state unbonding_slashing <<fork>>
+    burn_staking: Burn address output
+    change_staking: Change output
+    burn_unbonding: Burn address output
+    change_unbonding: Change output
+
+    [*] --> active: Staking transaction
+
+    active --> unbonding: Unbonding transaction
+
+    unbonding --> [*]: Unbonding withdrawal transaction
+
+    unbonding --> unbonding_slashing: Slashing transaction
+    unbonding_slashing --> burn_unbonding
+    unbonding_slashing --> change_unbonding
+    change_unbonding --> [*]: Withdrawal transaction
+
+    active --> [*]: Staking withdrawal transaction
+
+    active --> stake_slashing: Slashing transaction
+
+    stake_slashing --> burn_staking
+    stake_slashing --> change_staking
+    change_staking --> [*]: Withdrawal transaction
+
    +

    3.1. The Staking Output

    +

    The staking output is a Taproot output which can only be spent through +the script spending path. +The key spending path is disabled by using the "Nothing Up My Sleeve" +(NUMS) point as the internal key. +The NUMS point used is the one defined in +BIP341:

    +
    H = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0)
+
    +

    This point is derived by hashing the standard uncompressed encoding of the +secp256k1 base point G as the X coordinate.

    +

    The staking output can be spent through one of the following three script paths:

    +
      +
    1. +

      Timelock Path: +This path locks the staker's Bitcoin for a predefined number of Bitcoin blocks.

      +
      <StakerPK> OP_CHECKSIGVERIFY  <TimelockBlocks> OP_CHECKSEQUENCEVERIFY
+
      +

      Fields:

      +
        +
      • <StakerPK> is the BTC staker's public key.
        • +
      • <TimelockBlocks> defines the number of Bitcoin blocks the funds +are committed to remain locked. This duration starts once the staking +transaction is confirmed in a Bitcoin block. +Requirements: +
          +
        • The timelock must be lower than 65535.
          • +
        • The timelock should be within the bounds for Bitcoin staking transaction +timelocks defined in the +Babylon Genesis parameters.
          • +
        +
        • +
      +
      2. +
    2. +

      Unbonding Path: +This path allows the staker to unlock their Bitcoin on-demand, +before the timelock expires.

      +
      <StakerPk> OP_CHECKSIGVERIFY
+<CovenantPk1> OP_CHECKSIG <CovenantPk2> OP_CHECKSIGADD ... <CovenantPkN> OP_CHECKSIGADD
+<CovenantThreshold> OP_NUMEQUAL
+
      +

      Fields:

      +
        +
      • StakerPK is the BTC staker's public key.
        • +
      • CovenantPk1..CovenantPkN are the lexicographically sorted public keys of the +covenant committee as defined in the +Babylon Genesis parameters.
        • +
      • CovenantThreshold is a Babylon parameter specifying the number of how many +covenant committee member signatures are required. It is defined in the +Babylon Genesis parameters.
        • +
      +

      This path protects against immediate withdrawal without protocol-compliant unbonding, +by requiring signatures from a quorum of the covenant committee.

      +
      3. +
    3. +

      Slashing Path: +This path is used to slash staked funds when the +finality provider to which they have been delegated to +is proven to have double-signed.

      +
      <StakerPk> OP_CHECKSIGVERIFY
+<FinalityProviderPk> OP_CHECKSIGVERIFY
+<CovenantPk1> OP_CHECKSIG <CovenantPk2> OP_CHECKSIGADD ... <CovenantPkN> OP_CHECKSIGADD
+<CovenantThreshold> OP_NUMEQUAL
+
      +

      Fields:

      +
        +
      • StakerPK is the BTC staker's public key.
        • +
      • FinalityProviderPk is the public key of the finality provider +to which the stake is delegated. +
        +

        ⚡ At the moment, only a single finality provider is supported. +Once multi-staking is enabled, the script will be modified to accommodate +more finality providers.

        +
        +
        • +
      • CovenantPk1..CovenantPkN are the lexicographically sorted public keys of the +covenant committee as defined in the +Babylon Genesis parameters.
        • +
      • CovenantThreshold is a Babylon parameter specifying the number of how many +covenant committee member signatures are required. It is defined in the +Babylon Genesis parameters.
        • +
      +

      This path can only be executed with the collaboration of the BTC staker, finality provider, +and covenant committee. The staker is required to submit a pre-signature +for spending the slashing path in order for their stake to be accepted. +The covenant signatures are required to protect against +non protocol-compliant withdrawals. More details on the procedure +for registering stake can be found on the +registering Bitcoin stakes documentation.

      +
      4. +
    +
    +

    ⚡ Key Difference Between the Unbonding and Slashing Paths

    +

    The main difference lies in the presence of <FinalityProviderPk> in +the slashing path which has the following implications:

    +
      +
    • For a staking request to become active, the BTC staker must include +a valid (unsigned) unbonding transaction in the staking request. +It becomes active only when the Babylon Genesis chain receives +CovenantThreshold signatures by the covenant committee. +Since the unbonding path does not include <FinalityProviderPk>, +the staker can exit at any time without needing the finality provider's +consent.
      • +
    • In contrast, the slashing path does include <FinalityProviderPk> and +requires a pre-signed slashing transaction by both the staker and a +CovenantThreshold of the covenant emulation committee to become active. +This ensures that the finality provider's cooperation is needed to prevent +slashing, but not to execute it. If a finality provider misbehaves, +their key is exposed and can be used to execute the slashing.
      • +
    +
    +

    3.2. The Unbonding Output

    +

    The unbonding output is a Taproot output which can only be spent through the +script spending path. The key spending path is disabled by using +the "Nothing Up My Sleeve" (NUMS) point as the internal key. +The NUMS point used is the one defined in +BIP341:

    +
    H = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0)
+
    +

    This point is derived by hashing the standard uncompressed encoding of the +secp256k1 base point G as the X coordinate.

    +

    The unbonding output can be spent through one of the following two script paths:

    +
      +
    1. Timelock path: +This path locks the staker's Bitcoin for a predefined number of Bitcoin blocks. +
      <StakerPK> OP_CHECKSIGVERIFY  <TimelockBlocks> OP_CHECKSEQUENCEVERIFY
+
      +Fields: +
        +
      • <StakerPK> is the BTC staker's public key.
        • +
      • <TimelockBlocks> defines the unbonding time. It must equal +the value specified for unbonding defined in the +Babylon Genesis parameters.
        • +
      +
      2. +
    2. Slashing path: +This path is used to slash staked funds when the +finality provider to which they have been delegated to +is proven to have double-signed while the stake is in the unbonding period. +
      <StakerPk> OP_CHECKSIGVERIFY
+<FinalityProviderPk> OP_CHECKSIGVERIFY
+<CovenantPk1> OP_CHECKSIG <CovenantPk2> OP_CHECKSIGADD ... <CovenantPkN> OP_CHECKSIGADD
+<CovenantThreshold> OP_NUMEQUAL
+
      +Fields: +
        +
      • StakerPK is the BTC staker's public key.
        • +
      • FinalityProviderPk is the public key of the finality provider +to which the stake is delegated. +
        +

        ⚡ At the moment, only a single finality provider is supported. +Once multi-staking is enabled, the script will be modified to accommodate +more finality providers.

        +
        +
        • +
      • CovenantPk1..CovenantPkN are the lexicographically sorted public keys of the +covenant committee as defined in the +Babylon Genesis parameters.
        • +
      • CovenantThreshold is a Babylon parameter specifying the number of how many +covenant committee member signatures are required. It is defined in the +Babylon Genesis parameters.
        • +
      +
      3. +
    +
    +

    ⚡ Slashing Path in the Unbonding Output

    +

    The presence of the slashing path in the unbonding output ensures that a BTC staker +can still be slashed during the unbonding period, +if their delegated finality provider double-signs.

    +
    +

    3.3. The Slashing Refund Output

    +

    The slashing refund output returns the non-slashed portion of the staked funds +to the staker in the case of slashing. It is an output committing to the +following timelock script:

    +
    <StakerPK> OP_CHECKSIGVERIFY  <TimelockBlocks> OP_CHECKSEQUENCEVERIFY`
+
    +

    Fields:

    +
      +
    • <StakerPK> is BTC staker public key.
      • +
    • <TimelockBlocks> defines the time in which the funds +will remain locked before being accessible. This timelock is there +to ensure that the slashing path is not maliciously used to retrieve the +remaining funds faster than the unbonding time. It must equal +the value specified for unbonding time defined in the +Babylon Genesis parameters.
      • +
    + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/specifications/staking_transactions-version-next-v2.x.html b/static/remote-docs/guides/specifications/staking_transactions-version-next-v2.x.html new file mode 100644 index 00000000..2471740e --- /dev/null +++ b/static/remote-docs/guides/specifications/staking_transactions-version-next-v2.x.html @@ -0,0 +1,354 @@ + + + + + + Remote Documentation + + + +
    +
    Version: next-v2.x
    +

    Observable Staking Transactions Specification

    +

    Introduction

    +

    A lock-only network involves users locking their Bitcoin using the self-custodial +Bitcoin Staking script without a Babylon chain operating. +In this document, we precisely define how one can construct +the Bitcoin transactions specified by the Bitcoin Staking protocol.

    +

    Prerequisites

    +
      +
    • Scripts doc -a document which defines how different +Bitcoin Staking scripts look like
      • +
    • BIP341- +a document specifying how to spend Taproot outputs
      • +
    +

    System parameters

    +

    The lock-only staking system is governed by a set of parameters that specify +what constitutes a valid staking transaction. Based on those, +an observer of the Bitcoin ledger can precisely identify which transactions +are valid staking transactions and whether they should be considered active stake. +These parameters are different depending on the Bitcoin height a transaction is +included in and a constructor of a Bitcoin Staking transaction should take them into +account before propagating a transaction to Bitcoin. +For the rest of the document, we will refer to those parameters as global_parameters.

    +

    More details about parameters can be found in the +latest testnet docs.

    +

    Taproot outputs

    +

    Taproot outputs are outputs whose locking script is an elliptic curve point Q +created as follows:

    +
    Q = P + hash(P||m)G
+
    +

    where:

    +
      +
    • P is the internal public key
      • +
    • m is the root of a Merkle tree whose leaves consist of a version number and a +script
      • +
    +

    For Bitcoin Staking transactions, the internal public key is chosen as:

    +
    P = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0)
+
    +

    This key is described in the +BIP341 +specification.

    +

    The use of this key as an internal public key disables spending from Taproot output +through the key spending path. +The construction of this key can be found here.

    +

    Observable Staking Transactions

    +

    Staking transaction

    +

    A staker enters the system through the creation of a staking transaction +which locks Bitcoin in the Bitcoin Staking script.

    +

    Requirements

    +

    For the transaction to be considered a valid staking transaction, it must:

    +
      +
    • Have a Taproot output which has the key spending path disabled +and commits to a script tree composed of three scripts:: +timelock script, unbonding script, slashing script. +This output is henceforth known as the staking_output and +the value in this output is known as staking_amount
      • +
    • Have OP_RETURN output which contains: global_parameters.tag, +version, staker_pk, finality_provider_pk, staking_time
      • +
    • All the values must be valid for the global_parameters which are applicable at +the height in which the staking transaction is included in the BTC ledger.
      • +
    +

    OP_RETURN output description

    +

    Data in the OP_RETURN output is described by the following struct:

    +
    type V0OpReturnData struct {
+	Tag                       []byte
+	Version                   byte
+	StakerPublicKey           []byte
+	FinalityProviderPublicKey []byte
+	StakingTime               []byte
+}
+
    +

    The implementation of the struct can be found here

    +

    Fields description:

    +
      +
    • Tag - 4 bytes, a tag which is used to identify the staking transaction +among other transactions in the Bitcoin ledger. +It is specified in the global_parameters.Tag field.
      • +
    • Version - 1 byte, the current version of the OP_RETURN output.
      • +
    • StakerPublicKey - 32 bytes, staker public key. The same key must be used in +the scripts used to create the Taproot output in the staking transaction.
      • +
    • FinalityProviderPublicKey - 32 bytes, finality provider public key. The same key +must be used in the scripts used to create the Taproot output in the +staking transaction.
      • +
    • StakingTime - 2 bytes big-endian unsigned number, staking time. +The same timelock time must be used in scripts used to create the Taproot +output in the staking transaction.
      • +
    +

    This data is serialized as follows:

    +
    SerializedStakingData = Tag || Version || StakerPublicKey || FinalityProviderPublicKey || StakingTime
+
    +

    To transform this data into OP_RETURN data:

    +
    StakingDataPkScript = 0x6a || 0x47 || SerializedStakingData
+
    +

    where:

    +
      +
    • 0x6a - is byte marker representing OP_RETURN op code.
      • +
    • 0x47 - is byte marker representing OP_DATA_71 op code, which pushed 71 bytes onto the stack.
      • +
    +

    The final OP_RETURN output will have the following shape:

    +
    TxOut {
+ Value: 0,
+ PkScript: StakingDataPkScript
+}
+
    +

    Logic creating output from data can be found here

    +

    Staking output description

    +

    Staking output should commit to three scripts:

    +
      +
    • timelock_script
      • +
    • unbonding_script
      • +
    • slashing_script
      • +
    +

    Data needed to create staking_output:

    +
      +
    • staker_public_key - chosen by the user sending the staking transaction. It +will be used in every script. This key needs to be put in the OP_RETURN output +in the staking transaction.
      • +
    • finality_provider_public_key - chosen by the user sending the staking +transaction. It will be used as <FinalityPk> in the slashing_script. In the +lock-only network, there is no slashing, so this key has mostly informative purposes. +This key needs to be put in the OP_RETURN output of the staking transaction.
      • +
    • staking_time - chosen by the user sending the staking transaction. It will +be used as the locking time in the timelock_script. It must be a valid uint16 number, +in the range global_parameters.min_staking_time <= staking_time <= global_parameters.max_staking_time. +It needs to be put in the OP_RETURN output of the staking transaction.
      • +
    • covenant_committee_public_keys - it can be retrieved from +global_parameters.covenant_pks. It is a set of covenant committee public keys which +will be put in unbonding_script and slashing_script.
      • +
    • covenant_committee_quorum - it can be retrieved from +global_parameters.covenant_quorum. It is the quorum of covenant committee +members required to authorize spending using the unbonding_script or slashing_script.
      • +
    • staking_amout - chosen by the user, it will be placed in staking_output.value.
      • +
    • btc_network - the BTC network on which staking transactions will take place.
      • +
    +

    Building OP_RETURN and staking output implementation

    +

    The Babylon staking library exposes the BuildV0IdentifiableStakingOutputsAndTx +function with the following signature:

    +
    func BuildV0IdentifiableStakingOutputsAndTx(
+	tag []byte,
+	stakerKey *btcec.PublicKey,
+	fpKey *btcec.PublicKey,
+	covenantKeys []*btcec.PublicKey,
+	covenantQuorum uint32,
+	stakingTime uint16,
+	stakingAmount btcutil.Amount,
+	net *chaincfg.Params,
+) (*IdentifiableStakingInfo, *wire.MsgTx, error)
+
    +

    It enables the caller to create valid outputs to put inside an unfunded and not-signed +staking transaction.

    +

    The suggested way of creating and sending a staking transaction using +bitcoind is:

    +
      +
    1. Create staker_key in the bitcoind wallet.
      2. +
    2. Create unfunded and not signed staking transaction using +the BuildV0IdentifiableStakingOutputsAndTx function.
      3. +
    3. Serialize the unfunded and not signed staking transaction to staking_transaction_hex.
      4. +
    4. Call bitcoin-cli fundrawtransaction "staking_transaction_hex" to +retrieve funded_staking_transaction_hex. +The bitcoind wallet will automatically choose unspent outputs to fund this transaction.
      5. +
    5. Call bitcoin-cli signrawtransactionwithwallet "funded_staking_transaction_hex". +This call will sign all inputs of the transaction and return signed_staking_transaction_hex.
      6. +
    6. Call bitcoin-cli sendrawtransaction "signed_staking_transaction_hex".
      7. +
    +

    Unbonding transaction

    +

    The unbonding transaction allows the staker to on-demand unbond their +locked Bitcoin stake prior to its original timelock expiration.

    +

    Requirements

    +

    For the transaction to be considered a valid unbonding transaction, it must:

    +
      +
    • Have exactly one input and one output.
      • +
    • Input must be a valid staking output.
      • +
    • Output must be a Taproot output. This Taproot output must have disabled +the key spending path, and committed to script tree composed of two scripts: +the timelock script and the slashing script. This output is henceforth known +as the unbonding_output.
      • +
    • Timelock in the timelock script must be equal to global_parameters.unbonding_time.
      • +
    • Value in the unbonding output must be equal to staking_output.value - global_parameters.unbonding_fee.
      • +
    +

    Building Unbonding output

    +

    The Babylon Bitcoin staking library exposes +the BuildUnbondingInfo +function which builds a valid unbonding output. +It has the following signature:

    +
    func BuildUnbondingInfo(
+	stakerKey *btcec.PublicKey,
+	fpKeys []*btcec.PublicKey,
+	covenantKeys []*btcec.PublicKey,
+	covenantQuorum uint32,
+	unbondingTime uint16,
+	unbondingAmount btcutil.Amount,
+	net *chaincfg.Params,
+) (*UnbondingInfo, error)
+
    +

    where:

    +
      +
    • stakerKey- must be the same key as the staker key in staking_transaction.
      • +
    • fpKeys - must contain one key, which is the same finality provider key used +in staking_transaction.
      • +
    • covenantKeys- are the same covenant keys as used in staking_transaction.
      • +
    • covenantQuorum - is the same quorum as used in staking_transaction.
      • +
    • unbondingTime - is equal to global_parameters.unbonding_time.
      • +
    • unbondingAmount - is equal to staking_amount - global_parameters.unbonding_fee.
      • +
    +

    Spending Taproot outputs

    +

    To create transactions which spend from Taproot outputs, either staking output +or unbonding output, providing signatures satisfying the script is not enough.

    +

    The spender must also provide:

    +
      +
    • The whole script which is being spent.
      • +
    • The control block which contains: leaf version, internal public key, and proof of +inclusion of the given script in the script tree.
      • +
    +

    Given that creating scripts is deterministic for given data, it is possible to +avoid storing scripts by re-building scripts when the need arises.

    +

    Re-creating script and control block

    +

    To build the script and control block necessary to spend from a staking output through the +timelock script, the following function could be implemented.

    +
    import (
+	// Babylon btc staking library
+	"github.com/babylonlabs-io/babylon/btcstaking"
+)
+
+func buildTimelockScriptAndControlBlock(
+	stakerKey *btcec.PublicKey,
+	finalityProviderKey *btcec.PublicKey,
+	covenantKeys []*btcec.PublicKey,
+	covenantQuorum uint32,
+	stakingTime uint16,
+	stakingAmount btcutil.Amount,
+	netParams *chaincfg.Params,
+) ([]byte, []byte, error) {
+
+	stakingInfo, err := btcstaking.BuildStakingInfo(
+		stakerKey,
+		[]*btcec.PublicKey{finalityProviderKey},
+		covenantKeys,
+		covenantQuorum,
+		stakingTime,
+		stakingAmount,
+		netParams,
+	)
+
+	if err != nil {
+		return nil, nil, err
+	}
+
+	si, err := stakingInfo.TimeLockPathSpendInfo()
+
+	if err != nil {
+		return nil, nil, err
+	}
+
+	scriptBytes := si.RevealedLeaf.Script
+
+	controlBlock := si.ControlBlock
+
+	controlBlockBytes, err := controlBlock.ToBytes()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return scriptBytes, controlBlockBytes, nil
+}
+
+
    +

    The returned script and control block can be used to either build the witness directly +or to put them in a PSBT which can be used by bitcoind to create the witness.

    +

    Creating PSBT to get signature for given Taproot path from Bitcoind

    +

    To avoid creating signatures/witness manually, +Bitcoind's walletprocesspsbt +can be used. To use this Bitcoind endpoint to get signature/witness the wallet must +maintain one of the keys used in the script.

    +

    Example of creating psbt to sign unbonding transaction using unbonding script from +staking output:

    +
    import (
+	"github.com/btcsuite/btcd/btcutil/psbt"
+)
+
+func BuildPsbtForSigningUnbondingTransaction(
+	unbondingTx *wire.MsgTx,
+	stakingOutput *wire.TxOut,
+	stakerKey *btcec.PublicKey,
+	spentLeaf *txscript.TapLeaf,
+	controlBlockBytes []byte,
+) (string, error) {
+	psbtPacket, err := psbt.New(
+		[]*wire.OutPoint{&unbondingTx.TxIn[0].PreviousOutPoint},
+		unbondingTx.TxOut,
+		unbondingTx.Version,
+		unbondingTx.LockTime,
+		[]uint32{unbondingTx.TxIn[0].Sequence},
+	)
+
+	if err != nil {
+		return "", fmt.Errorf("failed to create PSBT packet with unbonding transaction: %w", err)
+	}
+
+	psbtPacket.Inputs[0].SighashType = txscript.SigHashDefault
+	psbtPacket.Inputs[0].WitnessUtxo = stakingOutput
+	psbtPacket.Inputs[0].Bip32Derivation = []*psbt.Bip32Derivation{
+		{
+			PubKey: stakerKey.SerializeCompressed(),
+		},
+	}
+
+	psbtPacket.Inputs[0].TaprootLeafScript = []*psbt.TaprootTapLeafScript{
+		{
+			ControlBlock: controlBlockBytes,
+			Script:       spentLeaf.Script,
+			LeafVersion:  spentLeaf.LeafVersion,
+		},
+	}
+
+	return psbtPacket.B64Encode()
+}
+
+
    +

    Given that to spend through the unbonding script requires more than the +staker's signature, the walletprocesspsbt endpoint will produce a new psbt +with the staker signature attached.

    +

    In the case of a timelock path which requires only the staker's signature, +walletprocesspsbt would produce the whole witness required to send the +transaction to the BTC network.

    + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/guides/specifications/staking_transactions-version-next-v4.x.html b/static/remote-docs/guides/specifications/staking_transactions-version-next-v4.x.html new file mode 100644 index 00000000..d6311441 --- /dev/null +++ b/static/remote-docs/guides/specifications/staking_transactions-version-next-v4.x.html @@ -0,0 +1,354 @@ + + + + + + Remote Documentation + + + +
    +
    Version: next-v4.x
    +

    Observable Staking Transactions Specification

    +

    Introduction

    +

    A lock-only network involves users locking their Bitcoin using the self-custodial +Bitcoin Staking script without a Babylon chain operating. +In this document, we precisely define how one can construct +the Bitcoin transactions specified by the Bitcoin Staking protocol.

    +

    Prerequisites

    +
      +
    • Scripts doc -a document which defines how different +Bitcoin Staking scripts look like
      • +
    • BIP341- +a document specifying how to spend Taproot outputs
      • +
    +

    System parameters

    +

    The lock-only staking system is governed by a set of parameters that specify +what constitutes a valid staking transaction. Based on those, +an observer of the Bitcoin ledger can precisely identify which transactions +are valid staking transactions and whether they should be considered active stake. +These parameters are different depending on the Bitcoin height a transaction is +included in and a constructor of a Bitcoin Staking transaction should take them into +account before propagating a transaction to Bitcoin. +For the rest of the document, we will refer to those parameters as global_parameters.

    +

    More details about parameters can be found in the +latest testnet docs.

    +

    Taproot outputs

    +

    Taproot outputs are outputs whose locking script is an elliptic curve point Q +created as follows:

    +
    Q = P + hash(P||m)G
+
    +

    where:

    +
      +
    • P is the internal public key
      • +
    • m is the root of a Merkle tree whose leaves consist of a version number and a +script
      • +
    +

    For Bitcoin Staking transactions, the internal public key is chosen as:

    +
    P = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0)
+
    +

    This key is described in the +BIP341 +specification.

    +

    The use of this key as an internal public key disables spending from Taproot output +through the key spending path. +The construction of this key can be found here.

    +

    Observable Staking Transactions

    +

    Staking transaction

    +

    A staker enters the system through the creation of a staking transaction +which locks Bitcoin in the Bitcoin Staking script.

    +

    Requirements

    +

    For the transaction to be considered a valid staking transaction, it must:

    +
      +
    • Have a Taproot output which has the key spending path disabled +and commits to a script tree composed of three scripts:: +timelock script, unbonding script, slashing script. +This output is henceforth known as the staking_output and +the value in this output is known as staking_amount
      • +
    • Have OP_RETURN output which contains: global_parameters.tag, +version, staker_pk, finality_provider_pk, staking_time
      • +
    • All the values must be valid for the global_parameters which are applicable at +the height in which the staking transaction is included in the BTC ledger.
      • +
    +

    OP_RETURN output description

    +

    Data in the OP_RETURN output is described by the following struct:

    +
    type V0OpReturnData struct {
+	Tag                       []byte
+	Version                   byte
+	StakerPublicKey           []byte
+	FinalityProviderPublicKey []byte
+	StakingTime               []byte
+}
+
    +

    The implementation of the struct can be found here

    +

    Fields description:

    +
      +
    • Tag - 4 bytes, a tag which is used to identify the staking transaction +among other transactions in the Bitcoin ledger. +It is specified in the global_parameters.Tag field.
      • +
    • Version - 1 byte, the current version of the OP_RETURN output.
      • +
    • StakerPublicKey - 32 bytes, staker public key. The same key must be used in +the scripts used to create the Taproot output in the staking transaction.
      • +
    • FinalityProviderPublicKey - 32 bytes, finality provider public key. The same key +must be used in the scripts used to create the Taproot output in the +staking transaction.
      • +
    • StakingTime - 2 bytes big-endian unsigned number, staking time. +The same timelock time must be used in scripts used to create the Taproot +output in the staking transaction.
      • +
    +

    This data is serialized as follows:

    +
    SerializedStakingData = Tag || Version || StakerPublicKey || FinalityProviderPublicKey || StakingTime
+
    +

    To transform this data into OP_RETURN data:

    +
    StakingDataPkScript = 0x6a || 0x47 || SerializedStakingData
+
    +

    where:

    +
      +
    • 0x6a - is byte marker representing OP_RETURN op code.
      • +
    • 0x47 - is byte marker representing OP_DATA_71 op code, which pushed 71 bytes onto the stack.
      • +
    +

    The final OP_RETURN output will have the following shape:

    +
    TxOut {
+ Value: 0,
+ PkScript: StakingDataPkScript
+}
+
    +

    Logic creating output from data can be found here

    +

    Staking output description

    +

    Staking output should commit to three scripts:

    +
      +
    • timelock_script
      • +
    • unbonding_script
      • +
    • slashing_script
      • +
    +

    Data needed to create staking_output:

    +
      +
    • staker_public_key - chosen by the user sending the staking transaction. It +will be used in every script. This key needs to be put in the OP_RETURN output +in the staking transaction.
      • +
    • finality_provider_public_key - chosen by the user sending the staking +transaction. It will be used as <FinalityPk> in the slashing_script. In the +lock-only network, there is no slashing, so this key has mostly informative purposes. +This key needs to be put in the OP_RETURN output of the staking transaction.
      • +
    • staking_time - chosen by the user sending the staking transaction. It will +be used as the locking time in the timelock_script. It must be a valid uint16 number, +in the range global_parameters.min_staking_time <= staking_time <= global_parameters.max_staking_time. +It needs to be put in the OP_RETURN output of the staking transaction.
      • +
    • covenant_committee_public_keys - it can be retrieved from +global_parameters.covenant_pks. It is a set of covenant committee public keys which +will be put in unbonding_script and slashing_script.
      • +
    • covenant_committee_quorum - it can be retrieved from +global_parameters.covenant_quorum. It is the quorum of covenant committee +members required to authorize spending using the unbonding_script or slashing_script.
      • +
    • staking_amout - chosen by the user, it will be placed in staking_output.value.
      • +
    • btc_network - the BTC network on which staking transactions will take place.
      • +
    +

    Building OP_RETURN and staking output implementation

    +

    The Babylon staking library exposes the BuildV0IdentifiableStakingOutputsAndTx +function with the following signature:

    +
    func BuildV0IdentifiableStakingOutputsAndTx(
+	tag []byte,
+	stakerKey *btcec.PublicKey,
+	fpKey *btcec.PublicKey,
+	covenantKeys []*btcec.PublicKey,
+	covenantQuorum uint32,
+	stakingTime uint16,
+	stakingAmount btcutil.Amount,
+	net *chaincfg.Params,
+) (*IdentifiableStakingInfo, *wire.MsgTx, error)
+
    +

    It enables the caller to create valid outputs to put inside an unfunded and not-signed +staking transaction.

    +

    The suggested way of creating and sending a staking transaction using +bitcoind is:

    +
      +
    1. Create staker_key in the bitcoind wallet.
      2. +
    2. Create unfunded and not signed staking transaction using +the BuildV0IdentifiableStakingOutputsAndTx function.
      3. +
    3. Serialize the unfunded and not signed staking transaction to staking_transaction_hex.
      4. +
    4. Call bitcoin-cli fundrawtransaction "staking_transaction_hex" to +retrieve funded_staking_transaction_hex. +The bitcoind wallet will automatically choose unspent outputs to fund this transaction.
      5. +
    5. Call bitcoin-cli signrawtransactionwithwallet "funded_staking_transaction_hex". +This call will sign all inputs of the transaction and return signed_staking_transaction_hex.
      6. +
    6. Call bitcoin-cli sendrawtransaction "signed_staking_transaction_hex".
      7. +
    +

    Unbonding transaction

    +

    The unbonding transaction allows the staker to on-demand unbond their +locked Bitcoin stake prior to its original timelock expiration.

    +

    Requirements

    +

    For the transaction to be considered a valid unbonding transaction, it must:

    +
      +
    • Have exactly one input and one output.
      • +
    • Input must be a valid staking output.
      • +
    • Output must be a Taproot output. This Taproot output must have disabled +the key spending path, and committed to script tree composed of two scripts: +the timelock script and the slashing script. This output is henceforth known +as the unbonding_output.
      • +
    • Timelock in the timelock script must be equal to global_parameters.unbonding_time.
      • +
    • Value in the unbonding output must be equal to staking_output.value - global_parameters.unbonding_fee.
      • +
    +

    Building Unbonding output

    +

    The Babylon Bitcoin staking library exposes +the BuildUnbondingInfo +function which builds a valid unbonding output. +It has the following signature:

    +
    func BuildUnbondingInfo(
+	stakerKey *btcec.PublicKey,
+	fpKeys []*btcec.PublicKey,
+	covenantKeys []*btcec.PublicKey,
+	covenantQuorum uint32,
+	unbondingTime uint16,
+	unbondingAmount btcutil.Amount,
+	net *chaincfg.Params,
+) (*UnbondingInfo, error)
+
    +

    where:

    +
      +
    • stakerKey- must be the same key as the staker key in staking_transaction.
      • +
    • fpKeys - must contain one key, which is the same finality provider key used +in staking_transaction.
      • +
    • covenantKeys- are the same covenant keys as used in staking_transaction.
      • +
    • covenantQuorum - is the same quorum as used in staking_transaction.
      • +
    • unbondingTime - is equal to global_parameters.unbonding_time.
      • +
    • unbondingAmount - is equal to staking_amount - global_parameters.unbonding_fee.
      • +
    +

    Spending Taproot outputs

    +

    To create transactions which spend from Taproot outputs, either staking output +or unbonding output, providing signatures satisfying the script is not enough.

    +

    The spender must also provide:

    +
      +
    • The whole script which is being spent.
      • +
    • The control block which contains: leaf version, internal public key, and proof of +inclusion of the given script in the script tree.
      • +
    +

    Given that creating scripts is deterministic for given data, it is possible to +avoid storing scripts by re-building scripts when the need arises.

    +

    Re-creating script and control block

    +

    To build the script and control block necessary to spend from a staking output through the +timelock script, the following function could be implemented.

    +
    import (
+	// Babylon btc staking library
+	"github.com/babylonlabs-io/babylon/btcstaking"
+)
+
+func buildTimelockScriptAndControlBlock(
+	stakerKey *btcec.PublicKey,
+	finalityProviderKey *btcec.PublicKey,
+	covenantKeys []*btcec.PublicKey,
+	covenantQuorum uint32,
+	stakingTime uint16,
+	stakingAmount btcutil.Amount,
+	netParams *chaincfg.Params,
+) ([]byte, []byte, error) {
+
+	stakingInfo, err := btcstaking.BuildStakingInfo(
+		stakerKey,
+		[]*btcec.PublicKey{finalityProviderKey},
+		covenantKeys,
+		covenantQuorum,
+		stakingTime,
+		stakingAmount,
+		netParams,
+	)
+
+	if err != nil {
+		return nil, nil, err
+	}
+
+	si, err := stakingInfo.TimeLockPathSpendInfo()
+
+	if err != nil {
+		return nil, nil, err
+	}
+
+	scriptBytes := si.RevealedLeaf.Script
+
+	controlBlock := si.ControlBlock
+
+	controlBlockBytes, err := controlBlock.ToBytes()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return scriptBytes, controlBlockBytes, nil
+}
+
+
    +

    The returned script and control block can be used to either build the witness directly +or to put them in a PSBT which can be used by bitcoind to create the witness.

    +

    Creating PSBT to get signature for given Taproot path from Bitcoind

    +

    To avoid creating signatures/witness manually, +Bitcoind's walletprocesspsbt +can be used. To use this Bitcoind endpoint to get signature/witness the wallet must +maintain one of the keys used in the script.

    +

    Example of creating psbt to sign unbonding transaction using unbonding script from +staking output:

    +
    import (
+	"github.com/btcsuite/btcd/btcutil/psbt"
+)
+
+func BuildPsbtForSigningUnbondingTransaction(
+	unbondingTx *wire.MsgTx,
+	stakingOutput *wire.TxOut,
+	stakerKey *btcec.PublicKey,
+	spentLeaf *txscript.TapLeaf,
+	controlBlockBytes []byte,
+) (string, error) {
+	psbtPacket, err := psbt.New(
+		[]*wire.OutPoint{&unbondingTx.TxIn[0].PreviousOutPoint},
+		unbondingTx.TxOut,
+		unbondingTx.Version,
+		unbondingTx.LockTime,
+		[]uint32{unbondingTx.TxIn[0].Sequence},
+	)
+
+	if err != nil {
+		return "", fmt.Errorf("failed to create PSBT packet with unbonding transaction: %w", err)
+	}
+
+	psbtPacket.Inputs[0].SighashType = txscript.SigHashDefault
+	psbtPacket.Inputs[0].WitnessUtxo = stakingOutput
+	psbtPacket.Inputs[0].Bip32Derivation = []*psbt.Bip32Derivation{
+		{
+			PubKey: stakerKey.SerializeCompressed(),
+		},
+	}
+
+	psbtPacket.Inputs[0].TaprootLeafScript = []*psbt.TaprootTapLeafScript{
+		{
+			ControlBlock: controlBlockBytes,
+			Script:       spentLeaf.Script,
+			LeafVersion:  spentLeaf.LeafVersion,
+		},
+	}
+
+	return psbtPacket.B64Encode()
+}
+
+
    +

    Given that to spend through the unbonding script requires more than the +staker's signature, the walletprocesspsbt endpoint will produce a new psbt +with the staker signature attached.

    +

    In the case of a timelock path which requires only the staker's signature, +walletprocesspsbt would produce the whole witness required to send the +transaction to the BTC network.

    + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/babylon_node/installation_guide-mainnet.html b/static/remote-docs/operators/babylon_node/installation_guide-mainnet.html deleted file mode 100644 index c94f5791..00000000 --- a/static/remote-docs/operators/babylon_node/installation_guide-mainnet.html +++ /dev/null @@ -1,279 +0,0 @@ -

    Babylon Node Setup

    -

    Table of Contents

    -
      -
    1. Install Babylon binary
      2. -
    2. Set up node home directory and configuration
      3. -
    3. Prepare for sync -
        -
      1. Sync through a network snapshot
        2. -
      2. Sync from scratch
        3. -
      -
      4. -
    4. Start the node
      5. -
    -

    1. Install Babylon Binary

    -

    Installing the Babylon binary requires a Golang installation.

    -

    Install Golang 1.23 by following the instructions -here

    -

    Once installed, to verify your installation, run:

    -
    go version
-
    -

    Next, clone the Babylon codebase -and install the Babylon binary:

    -
    git clone https://github.com/babylonlabs-io/babylon.git
-cd babylon
-# tag corresponds to the version of the software
-# you want to install -- depends on which
-# height you sync from
-git checkout v1.0.1
-# install the binary
-make install
-
    -

    This command does the following:

    -
      -
    • Builds the daemon
      • -
    • Installs the binary
      • -
    • Makes the babylond command globally accessible from your terminal
      • -
    -

    You can verify your installation by executing the version command:

    -
    babylond version
-v1.0.1
-
    -

    If your shell cannot find the installed binary, make sure $GOPATH/bin is in -your shell's $PATH. Use the following command to add it to your profile, -depending on your shell:

    -
    echo 'export PATH=$HOME/go/bin:$PATH' >> ~/.profile
-
    -

    Make sure to restart your terminal session after running the above command.

    -

    Note: Alternatively, you can use a -Docker image

    -

    2. Set up your node

    -

    In this section we will initialize your node and create the necessary -configuration directory through the init command.

    -
    babylond init <moniker> --chain-id bbn-1 --home <path>
-
    -

    Parameters:

    -
      -
    • <moniker>: A unique identifier for your node for example node0
      • -
    • --chain-id: The chain ID of the Babylon chain you connect to
      • -
    • --home: optional flag that specifies the directory where your -node files will be stored, for example --home ./nodeDir -The default home directory for your Babylon node is: -
        -
      • Linux/Mac: ~/.babylond/
        • -
      • Windows: %USERPROFILE%\.babylond\
        • -
      -
      • -
    -
    -

    ⚠️ Important note about BLS keys

    -

    A prompt will appear for you to enter a password for a BLS key. -This password will be used to encrypt your BLS key before storing it in a -file ($HOME/config/bls_key.json). -All node operators intending to become validators must have a BLS key, -similar to the requirement for a priv_validator_key.json file. -Babylon uses both the bls_key.json and the priv_validator_key.json files.

    -

    You can specify your BLS password using the following options:

    -
      -
    • CLI or Environment Variable: You can specify your password through the -CLI or an environment variable (note that if both are used concurrently, an -error will be raised): -
        -
      • Environment Variable: BABYLON_BLS_PASSWORD is set.
        • -
      • CLI flags: One of the following CLI options has been set: -
          -
        • --no-bls-key is a flag that if set designates that an empty BLS -password should be used.
          • -
        • --bls-password-file=<path> allows to specify a file location that -contains the plaintext BLS password.
          • -
        -
        • -
      -
      • -
    • (Recommended) Password Prompt -If none of the above is set, a prompt will appear asking you to type your -password.
      • -
    -
    -
    $HOME/.babylond/
-├── config/
-│   ├── app.toml         # Application-specific configuration
-│   ├── bls_key.json     # BLS key for the node
-│   ├── bls_password.txt # Password file for the BLS key (if `--bls-password-file` has been set)
-│   ├── client.toml      # Client configuration
-│   ├── config.toml      # Tendermint core configuration
-│   ├── genesis.json     # Genesis state of the network
-│   ├── node_key.json    # Node's p2p identity key
-│   └── priv_validator_key.json  # Validator's consensus key (if running a validator)
-├── data/                # Blockchain data directory
-│   └── ...
-└── keyring-test/       # Key management directory
-    └── ...
-
    -

    After initialization, you'll need to modify the following configuration files:

    -
      -
    1. On app.toml, update the following settings:
      2. -
    -
    # Base configuration
-# Minimum gas prices that this node will accept
-minimum-gas-prices = "0.002ubbn"
-
-[mempool]
-# Setting max-txs to 0 will allow for a unbounded amount of transactions in the mempool.
-# Setting max_txs to negative 1 (-1) will disable transactions from being inserted into the mempool (no-op mempool).
-# Setting max_txs to a positive number (> 0) will limit the number of transactions in the mempool, by the specified amount.
-#
-# Note, this configuration only applies to SDK built-in app-side mempool
-# implementations.
-max-txs = 0
-
-[btc-config]
-
-# Configures which bitcoin network should be used for checkpointing
-# valid values are: [mainnet, testnet, simnet, signet, regtest]
-network = "mainnet" # The Babylon Genesis mainnet connects to the mainnet Bitcoin network
-
    -

    Parameters:

    -
      -
    • minimum-gas-prices: The minimum gas price your node will accept for -transactions. The Babylon protocol enforces a minimum of 0.002ubbn and -any transactions with gas prices below your node's minimum will be rejected.
      • -
    • mempool.max-txs: Set this to 0 in order to utilise the application side -mempool.
      • -
    • btc-config.network: Specifies which Bitcoin network to connect to for -checkpointing. For the Babylon Genesis mainnet, -we use "mainnet" which is Bitcoin's mainnet network.
      • -
    -

    Note: If you're running a validator or RPC node that needs to handle queries, -it's recommended to keep these default values for optimal performance. Only -adjust these if you're running a node with limited memory resources.

    -
      -
    1. On config.toml, update the the following settings:
      2. -
    -
    [p2p]
-
-# These are placeholder values and should be replaced
-seeds = "NODE_ID1@NODE_ENDPOINT1:PORT1,NODE_ID2@NODE_ENDPOINT2:PORT2"
-
-# These are placeholder values and should be replaced
-persistent_peers = "NODE_ID1@NODE_ENDPOINT1:PORT1,NODE_ID2@NODE_ENDPOINT2:PORT2"
-
-[consensus]
-
-timeout_commit = "9200ms"
-
    -

    Parameters:

    -
      -
    • seeds: Comma separated list of seed nodes that your node will connect to for -discovering other peers in the network; you can obtain seed endpoints from -here
      • -
    • persistent_peers: Comma separated list of nodes that your node will use as -persistent peers; you can obtain peers from here
      • -
    • timeout_commit: The Babylon Genesis network block time has to be set to -9200 milliseconds. We set a lower value than the target 10s block time, -to account for network delays.
      • -
    -

    Note: You can use either seeds, persistent peers or both.

    -

    Next, you'll need to obtain the network's genesis file. This file contains -the initial state of the blockchain and is crucial for successfully syncing -your node. You can inspect the file here or use the -following commands to download it directly:

    -
    wget
-https://raw.githubusercontent.com/babylonlabs-io/networks/refs/heads/main/bbn-1/network-artifacts/genesis.json
-mv genesis.json <path>/config/genesis.json # You must insert the home directory of your node
-
    -

    3. Prepare for sync

    -

    Before starting your node sync, it's important to note that the initial release -at genesis was v0.9.0, while subsequently there have been software upgrades.

    -

    There are two options you can choose from when syncing:

    -
      -
    1. Sync through a network snapshot (fastest method)
      2. -
    2. Sync from scratch (complete sync from block 1)
      3. -
    -

    3.1. Sync through a network snapshot

    -

    Snapshot syncing is the fastest way to get your node up to date with the network. -A snapshot is a compressed backup of the blockchain data taken at a specific -height. Instead of processing all blocks from the beginning, you can download -and import this snapshot to quickly reach a recent block height.

    -

    You can obtain the network snapshot here.

    -

    To extract the snapshot, utilize the following command:

    -
    tar -xvf bbn-1.tar.gz -C <path>
-
    -

    Parameters:

    -
      -
    • bbn-1.tar.gz: Name of the compressed blockchain snapshot file
      • -
    • <path> : Your node's home directory
      • -
    -

    After importing the state, you can now start your node as specified in section -Start the node.

    -

    3.2. Sync from scratch

    -
    -

    Important: If you decide to sync from scratch and target to become a -validator, do not create a BLS key before -upgrading to a version that is > 1.0.0.

    -
    -

    Lastly, you can also sync from scratch, i.e., sync from block 1. Syncing from -scratch means downloading and verifying every block from the beginning -of the blockchain (genesis block) to the current block.

    -

    This will require you to use different babylond binaries for each version and -perform the babylon software upgrade when needed.

    -
      -
    1. -

      First, follow the installation steps in Section 1 -using the genesis software version v0.9.0 in place of <tag>.

      -
      2. -
    2. -

      Start your node as specified in section Start the node.

      -
      3. -
    -

    Your node will sync blocks until it reaches a software upgrade height.

    -

    At that point, you will have to perform the steps matching the corresponding -upgrade height.

    -

    Note: When building the upgrade binary, include the following build flag so that -mainnet-specific upgrade data are included in the binary:

    -
    BABYLON_BUILD_OPTIONS="mainnet" make install
-
    -

    You will have to go over all the software upgrades until you sync with the -full blockchain.

    -

    4. Start the node

    -

    You can start your node using the following command:

    -
    babylond start --chain-id bbn-1 --home <path> --x-crisis-skip-assert-invariants
-
    -

    Parameters:

    -
      -
    • 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 -dependent on where the files were generated for you from the initialization -(e.g. --home ./nodeDir)
      • -
    • --x-crisis-skip-assert-invariants: Skips state validation checks to improve -performance. Not recommended for validator nodes.
      • -
    -
    -

    ⚠️ Important note about BLS keys

    -

    The start command will need to decrypt and load your BLS key, which -requires your BLS key password. As with the init command, -you can specify your BLS password using the following options:

    -
      -
    • CLI or Environment Variable: You can specify your password through the -CLI or an environment variable (note that if both are used concurrently, an -error will be raised): -
        -
      • Environment Variable: BABYLON_BLS_PASSWORD is set.
        • -
      • CLI flags: One of the following CLI options has been set: -
          -
        • --no-bls-key is a flag that if set designates that an empty BLS -password should be used.
          • -
        • --bls-password-file=<path> allows to specify a file location that -contains the plaintext BLS password.
          • -
        -
        • -
      -
      • -
    • (Recommended) Password Prompt -If none of the above is set, a prompt will appear asking you to type your -password.
      • -
    -
    -

    Congratulations! Your Babylon node is now set up and syncing blocks.

    -
    \ No newline at end of file diff --git a/static/remote-docs/operators/babylon_node/installation_guide-testnet.html b/static/remote-docs/operators/babylon_node/installation_guide-version-testnet.html similarity index 93% rename from static/remote-docs/operators/babylon_node/installation_guide-testnet.html rename to static/remote-docs/operators/babylon_node/installation_guide-version-testnet.html index 9987c28f..c36f8e8b 100644 --- a/static/remote-docs/operators/babylon_node/installation_guide-testnet.html +++ b/static/remote-docs/operators/babylon_node/installation_guide-version-testnet.html @@ -1,4 +1,29 @@ -

    Babylon Node Setup

    + + + + + + Remote Documentation + + + +
    +
    Version: testnet
    +

    Babylon Node Setup

    Table of Contents

    1. Install Babylon Binary
      2. @@ -204,4 +229,8 @@

      4. Start the node

      performance. Not recommended for validator nodes.

      Congratulations! Your Babylon node is now set up and syncing blocks.

      -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/babylon_validators/ibc_relayer_guide.html b/static/remote-docs/operators/babylon_validators/ibc_relayer_guide.html index 8040b88f..73f6609a 100644 --- a/static/remote-docs/operators/babylon_validators/ibc_relayer_guide.html +++ b/static/remote-docs/operators/babylon_validators/ibc_relayer_guide.html @@ -1,4 +1,29 @@ -

    IBC relaying guide

    + + + + + + Remote Documentation + + + +
    + +

    IBC relaying guide

    Babylon uses IBC (Inter-Blockchain Communication protocol) to enable cross-chain communication with other IBC enabled chains. This guide focuses on the specific @@ -134,4 +159,8 @@

    Handling Expired/Frozen IBC Clients

    For more information about submitting governance proposals on Babylon, including parameters and requirements, see the Babylon Governance Guide.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/babylon_validators/installation_guide-mainnet.html b/static/remote-docs/operators/babylon_validators/installation_guide-mainnet.html deleted file mode 100644 index eb00ea2e..00000000 --- a/static/remote-docs/operators/babylon_validators/installation_guide-mainnet.html +++ /dev/null @@ -1,306 +0,0 @@ -

    Babylon Validator Setup

    -

    Table of Contents

    -
      -
    1. Prerequisites
      2. -
    2. System Requirements
      3. -
    3. Key Management -
        -
      1. Key for CometBFT consensus
        2. -
      2. Babylon validator account keyring
        3. -
      -
      4. -
    4. CometBFT Validator Configuration
      5. -
    5. Creating a Validator -
        -
      1. Verifying Validator Setup
        2. -
      2. Understanding Validator Status
        3. -
      3. Staking with your Validator
        4. -
      -
      6. -
    6. Advanced Security Architecture
      7. -
    7. Conclusion
      8. -
    -

    1. Prerequisites

    -

    Before setting up a validator, you'll need a fully synced Babylon node. For -node setup instructions, see our Node Setup Guide.

    -

    2. System Requirements

    -

    Recommended specifications for running a Babylon validator node:

    -
      -
    • CPU: Quad Core AMD/Intel (amd64)
      • -
    • RAM: 32GB
      • -
    • Storage: 2TB NVMe
      • -
    • Network: 100MBps bidirectional
      • -
    • Encrypted storage for keys and sensitive data
      • -
    • Regular system backups (hourly, daily, weekly)
      • -
    -

    These are reference specifications for a production validator. -Requirements may vary based on network activity and your operational needs.

    -

    3. Key Management

    -

    3.1 Keys for Babylon validators

    -

    When you initialize your node using babylond init (part of the node setup), -two types of keys are generated automatically. One is a CometBFT consensus key -pair, which is stored in priv_validator_key.json. This key is used by your -validator to participate in block creation and signing during the -consensus process at the CometBFT layer. -The other is BLS key pair, which is stored in bls_key.json along with -bls_password.txt following EIP-2335. -The key file location for both types of keys -is specified in your node's config.toml file.

    -

    Babylon validators are required to participate in -BLS voting -at the end of each epoch. -The Babylon blockchain defines epochs as a fixed number of blocks, -during which the validator set remains consistent. -At the end of the epoch, -the validator BLS signatures are aggregated to create a compact checkpoint -that is timestamped on the Bitcoin ledger. -The BLS voting mechanism achieves a significant reduction in the cost of -checkpoints, while the epoching mechanism specifies a defined frequency -for checkpointing in the Bitcoin blockchain.

    -
    -

    🔒 Security Tip: Make sure to securely store these key files. Losing -either of them would mean losing control of your validator.

    -
    -

    3.2 Babylon validator account keyring

    -

    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.

    -
    -

    ⚡ Note: This key represents your validator's application layer account -and is different from the CometBFT Key for consensus. While the CometBFT key -is used for consensus-level operations, this key will be for the application-level -operations such as managing your validator and withdrawing rewards.

    -
    -

    We will be using Cosmos SDK -backends for key storage, which offer support for the following -keyrings:

    -
      -
    • test is a password-less keyring and is unencrypted on disk.
      • -
    • os uses the system's secure keyring and will prompt for a passphrase at -startup.
      • -
    • file encrypts the keyring with a passphrase and stores it on disk.
      • -
    -

    To generate your validator key, use the following command:

    -
    babylond keys add <name> --home <path> --keyring-backend <keyring-backend>
-
    -

    Parameters: -The <name> specifies a unique identifier for the key.

    -
      -
    • --home specifies the directory where your node files will be stored -(e.g. --home ./nodeDir)
      • -
    • --keyring-backend specifies the keyring backend to use, can be test, file, -or os.
      • -
    -

    The execution result displays the address of the newly generated key and its -public key. Following is a sample output for the command:

    -
    - address: bbn1kvajzzn6gtfn2x6ujfvd6q54etzxnqg7pkylk9
-  name: <name>
-  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey",
-           key: "Ayau+8f945c1iQp9tfTVaCT5lzhD8n4MRkZNqpoL6Tpo"}'
-  type: local
-
    -
    -

    🔒 Security Tip: Make sure to securely store this information, particularly -your private key details. Losing access to the private key would -mean losing control of your validator.

    -
    -

    3.2.1 Get Funds

    -

    Before creating a validator, you will need sufficient BABY tokens in order -to interact with the Babylon network and run a validator.

    -

    4. CometBFT Validator Configuration

    -

    In this section, we are going to create a configuration file -that specifies the properties of your validator.

    -

    First, retrieve your validator's consensus public key using the following:

    -
    babylond tendermint show-validator --home <home>
-
    -

    This command reads your validator's key information from -priv_validator_key.json and outputs only the public key in a specific format -required for validator registration. The output will look like:

    -
    {"@type":"/cosmos.crypto.ed25519.PubKey","key":"0Wlt7ZPl0uvv7onsw4gP8FSQJUk986zMcOdWselDPM4="}
-
    -

    You'll need this formatted public key output to create your validator's -configuration file in the next step.

    -

    Now we can use the output of the command above and replace the pubkey and -<home> value in the example below. Subsequently run the following command to -create the validator configuration file:

    -
    cat > <home>/config/validator.json << EOF
-{
-  "pubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"0Wlt7ZPl0uvv7onsw4gP8FSQJUk986zMcOdWselDPM4="},
-  "amount": "1000000ubbn",
-  "moniker": "my-validator",
-  "commission-rate": "0.10",
-  "commission-max-rate": "0.20",
-  "commission-max-change-rate": "0.01",
-  "min-self-delegation": "1"
-}
-EOF
-
    -

    Parameters:

    -
      -
    • pubkey: Your validator's public key (the output you received before)
      • -
    • amount: Initial self-delegation amount
      • -
    • moniker: Your validator's name/identifier
      • -
    • commission-rate: Validator commission rate
      • -
    • commission-max-rate: Specifies the maximum you can raise your commission in the future.
      • -
    • commission-max-change-rate: Maximum daily commission change rate
      • -
    • min-self-delegation: Minimum amount you must keep self-delegated
      • -
    -

    If you prefer to add this manually or are having issues, another option is to -create a validator.json file manually and then paste the above json into it -but remember to replace all values with the actual values you want to use.

    -

    5. Creating a Validator

    -
    -

    ⚠️ Important: Please make sure to read through this section -as it might not work with your automations for creating validators.

    -
    -

    Unlike traditional Cosmos SDK chains that use the staking module, -Babylon uses the Babylon -checkpointing -module for validator creation and management.

    -

    Before proceeding, ensure that your -<path>/config/priv_validator_key.json file contains both your CometBFT -consensus and BLS key pair as they are both required for the -validator creation process. Recall that <path> is the --home directory -you specified when setting up your node.

    -
    -

    ⚠️ Warning: When troubleshooting your validator, do not use unsafe-reset-all -unless you have backed up priv_validator_key.json and have a secure backup -plan in place. Running unsafe-reset-all will result in the removal of the BLS -keys within the priv_validator_key.json file.

    -
    -
    -

    ⚠️ Important: You will need a funded account for this step.

    -
    -

    To create your validator, run the following command:

    -
    babylond tx checkpointing create-validator \
-    ./<home-path>/config/validator.json \
-    --chain-id bbn-1 \
-    --gas "auto" \
-    --gas-adjustment 1.5 \
-    --gas-prices "0.005ubbn" \
-    --from <your-key-name> \
-    --keyring-backend <keyring-backend> \
-    --home <path>
-
    -

    Parameters:

    -
      -
    • --chain-id: The network identifier
      • -
    • --gas: Set to "auto" to automatically calculate the gas needed
      • -
    • --gas-adjustment: A multiplier for the estimated gas
      • -
    • --gas-prices: Transaction fee in ubbn per unit of gas
      • -
    • --from: The name of your validator key in the keyring
      • -
    • --keyring-backend: The keyring backend type in which the above validator -key is stored
      • -
    • --home: Specifies the directory where your node files will be stored.
      • -
    -
    -

    ⚡ Note: Make sure the account specified by --from has enough tokens to -cover both the stake amount and transaction fees. This is the same account -you created and funded earlier in -Section 3.

    -
    -

    Upon successful creation, you'll be asked to approve the transaction. -Within the transaction result output, you will find your validator's -operator address (e.g., bbnvaloper1qh8444k43spt6m8ernm8phxr332k85teavxmuq).

    -

    After your validator creation transaction has been successfully submitted, -the Babylon blockchain will register your validator, but it will not activate -it until the end of the epoch. This is due to Babylon's epoched validator -set rotation mechanism, in which validator set and stake updates can -only happen at the end of each epoch. Each epoch lasts for about -60 minutes in the current mainnet.

    -
    -

    ⚡ Note: You will not be able to query your validator details until -the start of the next epoch. You can verify that your creation -transaction has been registered by verifying the inclusion -of its transaction hash in the blockchain.

    -
    -

    5.1 Verifying Validator Setup

    -

    To verify your validator setup, you can use the following steps:

    -

    First, get your validator's operator address using your Babylon address:

    -
    babylond keys show <your-key-name> --address --bech val --home <path> --keyring-backend <keyring-backend>
-
    -

    For example, for the address we used above is bbn1qh8444k43spt6m8ernm8phxr332k85teavxmuq, -the operator address is bbnvaloper1qh8444k43spt6m8ernm8phxr332k85teavxmuq.

    -

    For the next step, we will query your validator's details; however, results -will not appear until the current epoch concludes (epochs last for 60 minutes). -This delay is due to the network's epoching mechanism, as mentioned earlier.

    -
    babylond query staking validator <validator-operator-address>
-
    -

    The output should return the selected validator's configuration.

    -
    validator:
-  commission:
-    rates:
-      current: "100000000000000000" 
-      max: "1000000000000000000" 
-      max_change: "10000000000000000"
-  description:
-    moniker: "my-validator" 
-    website: "https://myweb.site" 
-    security_contact: "my-validator0@gmail.com"
-  status: 1 
-  tokens: "100"
-
    -

    Usually when first creating a validator, the immediate status will be -BOND_STATUS_UNBONDED. To see your validator's status change you will need to -wait for the epoch to end.

    -

    5.2 Understanding Validator Status

    -

    Your validator enters the active set based on two conditions:

    -
      -
    1. Having sufficient stake to qualify for the active set.
      2. -
    2. The completion of the epoch (a network-wide time period for -coordinating activities) in which your validator qualified for the active set.
      3. -
    -

    When active, your status will show as BOND_STATUS_BONDED.

    -

    The other status codes are:

    -
    BOND_STATUS_UNSPECIFIED = 0
-BOND_STATUS_UNBONDED = 1
-BOND_STATUS_UNBONDING = 2
-BOND_STATUS_BONDED = 3
-
    -

    5.3 Staking with your Validator

    -
    -

    ⚠️ Important: Babylon uses the -checkpointing -module for validator creation and management. -All staking-related transactions (delegate, redelegate, unbond) must be -processed through the x/epoching module, which encapsulates the x/staking -commands. These transactions will only take effect at the end of the epoch.

    -
    -

    For staking operations, please use the commands below:

    -
    # Delegate tokens to a validator
-babylond tx epoching delegate [validator-addr] [amount] \
-    --from <delegator-key> \
-    --chain-id <chain-id>
-
-# Redelegate tokens from one validator to another
-babylond tx epoching redelegate [src-validator-addr] [dst-validator-addr] [amount] \
-    --from <delegator-key> \
-    --chain-id <chain-id>
-
-# Unbond tokens from a validator
-babylond tx epoching unbond [validator-addr] [amount] \
-    --from <delegator-key> \
-    --chain-id <chain-id>
-
    -

    For more information on the epoching module and wrapped messages, see the -Epoching Module -documentation.

    -

    6. Advanced Security Architecture

    -

    Each validator's needs are significantly varied based on their operational needs -and the environment they are running in. Before setting up your validator -infrastructure, take time to research different security architectures, including -the Sentry Node Architecture. -This setup involves using intermediary nodes to protect your validator from -direct exposure to the public network.

    -

    Additionally, the handling of the priv_validator_key.json file is critical. -This file contains sensitive private key material vital for your validator's -operation. If lost or compromised, it could lead to severe consequences -including slashing penalties. Store this file securely using encrypted storage -and maintain robust backup procedures.

    -

    7. Conclusion

    -

    Congratulations! Your validator is now part of the Babylon network. Remember to -monitor your validator's performance and maintain good uptime to avoid -penalties.

    -
    \ No newline at end of file diff --git a/static/remote-docs/operators/babylon_validators/installation_guide-testnet.html b/static/remote-docs/operators/babylon_validators/installation_guide-version-testnet.html similarity index 95% rename from static/remote-docs/operators/babylon_validators/installation_guide-testnet.html rename to static/remote-docs/operators/babylon_validators/installation_guide-version-testnet.html index eb00ea2e..9af11a57 100644 --- a/static/remote-docs/operators/babylon_validators/installation_guide-testnet.html +++ b/static/remote-docs/operators/babylon_validators/installation_guide-version-testnet.html @@ -1,4 +1,29 @@ -

    Babylon Validator Setup

    + + + + + + Remote Documentation + + + +
    +
    Version: testnet
    +

    Babylon Validator Setup

    Table of Contents

    1. Prerequisites
      2. @@ -303,4 +328,8 @@

      7. Conclusion

      Congratulations! Your validator is now part of the Babylon network. Remember to monitor your validator's performance and maintain good uptime to avoid penalties.

      -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/covenant_emulator/covenant_emulator.html b/static/remote-docs/operators/covenant_emulator/covenant_emulator.html index 7c2b27ae..7fa05b3d 100644 --- a/static/remote-docs/operators/covenant_emulator/covenant_emulator.html +++ b/static/remote-docs/operators/covenant_emulator/covenant_emulator.html @@ -1,4 +1,29 @@ -

    Covenant Emulation Toolset

    + + + + + + Remote Documentation + + + +
    + +

    Covenant Emulation Toolset

    Overview

    The covenant emulation toolset is a set of programs operated by every member of the covenant committee of the BTC staking protocol. The role of the covenant @@ -146,4 +171,8 @@

    Important Limitations

    keyring backend. This limitation exists because the emulator requires automated signing capabilities without manual passphrase entry. Other keyring backends will cause the emulator to fail at startup.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/finality_providers/finality_providers.html b/static/remote-docs/operators/finality_providers/finality_providers.html index 6bc5e060..dd69654f 100644 --- a/static/remote-docs/operators/finality_providers/finality_providers.html +++ b/static/remote-docs/operators/finality_providers/finality_providers.html @@ -1,4 +1,29 @@ -

    Finality Provider

    + + + + + + Remote Documentation + + + +
    + +

    Finality Provider

    Finality providers are key participants in the Babylon BTC staking protocol. They provide finality votes on top of CometBFT, Babylon's consensus mechanism, @@ -146,4 +171,8 @@

    Overview of Keys for Finality Provider and EOTS Manager

    governance).

    Once a finality provider is created, neither key can be rotated or changed - they are permanently associated with that specific finality provider instance.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/finality_providers/fp_core_specs.html b/static/remote-docs/operators/finality_providers/fp_core_specs.html index 291c6c71..1b2ed839 100644 --- a/static/remote-docs/operators/finality_providers/fp_core_specs.html +++ b/static/remote-docs/operators/finality_providers/fp_core_specs.html @@ -1,4 +1,29 @@ -

    Finality Provider Core

    + + + + + + Remote Documentation + + + +
    + +

    Finality Provider Core

    This doc is to provide basic invariants and heuristics one should follow to build the finality provider. This part should be agnostic to any consumer chains.

    @@ -95,4 +120,8 @@

    Fast sync

    last_processed_height + 1, and
  • unblock the poller.
    • -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/finality_providers/fp_finality_votes.html b/static/remote-docs/operators/finality_providers/fp_finality_votes.html index f1d34a26..a5572cf5 100644 --- a/static/remote-docs/operators/finality_providers/fp_finality_votes.html +++ b/static/remote-docs/operators/finality_providers/fp_finality_votes.html @@ -1,4 +1,29 @@ -

    Finality Votes Submission Specification

    + + + + + + Remote Documentation + + + +
    + +

    Finality Votes Submission Specification

    Overview

    Finality providers submit votes to finalize blocks on the consumer chain. This document specifies the process of submitting finality votes.

    @@ -98,4 +123,8 @@

    Generating Finality Votes

  • Randomness was pre-committed and BTC-timestamped
  • EOTS signature validity
    • -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/finality_providers/fp_operations.html b/static/remote-docs/operators/finality_providers/fp_operations.html index fe45b531..732746f4 100644 --- a/static/remote-docs/operators/finality_providers/fp_operations.html +++ b/static/remote-docs/operators/finality_providers/fp_operations.html @@ -1,4 +1,29 @@ -

    Finality Provider Operation

    + + + + + + Remote Documentation + + + +
    + +

    Finality Provider Operation

    This is an operational guide intended for technical finality provider administrators. This guide covers the complete lifecycle of running a finality provider, including:

    @@ -1022,4 +1047,8 @@

    8.3.2. Recover public randomness proof

    creating the finality provider.
  • Restart the finality provider
    • -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/finality_providers/fp_public_randomness.html b/static/remote-docs/operators/finality_providers/fp_public_randomness.html index a929fe8c..15a07134 100644 --- a/static/remote-docs/operators/finality_providers/fp_public_randomness.html +++ b/static/remote-docs/operators/finality_providers/fp_public_randomness.html @@ -1,4 +1,29 @@ -

    Public Randomness Commit Specification

    + + + + + + Remote Documentation + + + +
    + +

    Public Randomness Commit Specification

    Overview

    The finality provider periodically commits public randomness to the consumer chain to be used for future block finalization. This document specifies the @@ -131,4 +156,8 @@

    Determining the Number of Randomness

    a long period of time to avoid frequent commit of randomness. In real life, the value of NumPubRand should be much larger than TimestampingDelayBlocks, e.g., NumPubRand = 2 * TimestampingDelayBlocks.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/finality_providers/hmac_security.html b/static/remote-docs/operators/finality_providers/hmac_security.html index 9b76b35b..899059b9 100644 --- a/static/remote-docs/operators/finality_providers/hmac_security.html +++ b/static/remote-docs/operators/finality_providers/hmac_security.html @@ -1,4 +1,29 @@ -

    HMAC Security for Finality Provider

    + + + + + + Remote Documentation + + + +
    + +

    HMAC Security for Finality Provider

    This document describes the HMAC (Hash-based Message Authentication Code) authentication system used to secure the communication between the Finality Provider Daemon (FPD) and the Extractable One-Time Signature Daemon (EOTSD). HMAC ensures that only authorized requests from FPD are processed by EOTSD, which handles sensitive key operations.

    @@ -72,4 +97,8 @@

    Troubleshooting

    Cloud Secret References: If you're using cloud secret references (AWS, GCP, Azure), ensure they are properly formatted and accessible.

    -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/operators/finality_providers/slashing_protection.html b/static/remote-docs/operators/finality_providers/slashing_protection.html index d004991b..9e70e3a2 100644 --- a/static/remote-docs/operators/finality_providers/slashing_protection.html +++ b/static/remote-docs/operators/finality_providers/slashing_protection.html @@ -1,4 +1,29 @@ -

    Slashing Protection on Finality Provider

    + + + + + + Remote Documentation + + + +
    + +

    Slashing Protection on Finality Provider

    In the BTC staking protocol, finality providers operate the Finality Provider Daemon (fpd) to send finality votes to Babylon Genesis. If a finality provider re-uses the same committed randomness @@ -141,4 +166,8 @@

    Operation Recommendations

  • Backup the db files for both daemons periodically (one-hour interval is recommended)
    • -
    \ No newline at end of file + +
    + + + \ No newline at end of file diff --git a/static/remote-docs/remote-docs-sitemap.xml b/static/remote-docs/remote-docs-sitemap.xml index 4d07f444..504ca09c 100644 --- a/static/remote-docs/remote-docs-sitemap.xml +++ b/static/remote-docs/remote-docs-sitemap.xml @@ -31,7 +31,7 @@ https://docs.dev.babylonlabs.io/remote-docs/guides/architecture/consumer_zone_programs/zone_concierge.html - https://docs.dev.babylonlabs.io/remote-docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee-mainnet.html + https://docs.dev.babylonlabs.io/remote-docs/guides/networks/phase-1/mainnet/covonent_committee/covonent_committee.html https://docs.dev.babylonlabs.io/remote-docs/guides/networks/phase-1/mainnet/finality_provider_registration.html @@ -64,19 +64,26 @@ https://docs.dev.babylonlabs.io/remote-docs/guides/overview/phases_of_the_launch/phase-2/registration.html - https://docs.dev.babylonlabs.io/remote-docs/operators/babylon_node/installation_guide-mainnet.html + https://docs.dev.babylonlabs.io/remote-docs/guides/specifications/bitcoin_staking_scripts-version-next-v2.x.html?version=next-v2.x - https://docs.dev.babylonlabs.io/remote-docs/operators/babylon_node/installation_guide-testnet.html + https://docs.dev.babylonlabs.io/remote-docs/guides/specifications/bitcoin_staking_scripts-version-next-v4.x.html?version=next-v4.x - https://docs.dev.babylonlabs.io/remote-docs/operators/babylon_validators/ibc_relayer_guide.html + https://docs.dev.babylonlabs.io/remote-docs/guides/specifications/staking_transactions-version-next-v2.x.html?version=next-v2.x + + + https://docs.dev.babylonlabs.io/remote-docs/guides/specifications/staking_transactions-version-next-v4.x.html?version=next-v4.x - https://docs.dev.babylonlabs.io/remote-docs/operators/babylon_validators/installation_guide-testnet.html + https://docs.dev.babylonlabs.io/remote-docs/operators/babylon_node/installation_guide-version-testnet.html?version=testnet + + + https://docs.dev.babylonlabs.io/remote-docs/operators/babylon_validators/ibc_relayer_guide.html - https://docs.dev.babylonlabs.io/remote-docs/operators/babylon_validators/installation_guide-mainnet.html + + https://docs.dev.babylonlabs.io/remote-docs/operators/babylon_validators/installation_guide-version-testnet.html?version=testnet https://docs.dev.babylonlabs.io/remote-docs/operators/covenant_emulator/covenant_emulator.html diff --git a/tailwind.config.cjs b/tailwind.config.cjs index 7a9d03ce..2a8e6dda 100644 --- a/tailwind.config.cjs +++ b/tailwind.config.cjs @@ -25,13 +25,15 @@ module.exports = { colors: { primary: { DEFAULT: - 'rgb(var(--docs-color-primary-200, 206 101 51) / )', // #ce6533 - 100: 'rgb(var(--docs-color-primary-100, 218 125 79) / )', // Lighter - 200: 'rgb(var(--docs-color-primary-200, 206 101 51) / )', // Default + 'rgb(var(--docs-color-primary-200, 190 220 201) / )', // #ce6533 + 100: 'rgb(var(--docs-color-primary-100, 190 220 201) / )', // Lighter + 200: 'rgb(var(--docs-color-primary-200, 190 220 201) / )', // Default }, secondary: { DEFAULT: - 'rgb(var(--docs-color-secondary-1000, 128 63 30) / )', // Darkest + 'rgb(var(--docs-color-secondary-1000, 51 197 206) / )', // Darkest + 100: 'rgb(var(--docs-color-primary-100, 51 197 206) / )', // Dark + 200: 'rgb(var(--docs-color-primary-200, 51 197 206) / )', // Dark 1000: 'rgb(var(--docs-color-secondary-1000, 128 63 30) / )', // Darkest 900: 'rgb(var(--docs-color-secondary-900, 153 77 38) / )', // Darker 800: 'rgb(var(--docs-color-secondary-800, 179 88 44) / )', // Dark