Skip to main content

Integrating BTC Staking to Cosmos Chains

System architecture​

The following figure depicts the system architecture. The "→" arrow denotes data flow; for example, X→ Y means "Y queries data from X and the data flows from X to Y".

Cosmos Chains Integrations ArchitectureCosmos Chains Integrations Architecture

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.
    • 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.

Upon a new block in the BSN chain, it:

  • Gets the block metadata.

  • Queries the Babylon contracts on the BSN chain to determine whether it has 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

    • 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.
    • It determines voting power of BSN Finality Providers based on the IBC packets.

Upon a finality signature, the Babylon contracts verify it:

  • If invalid, reject.

  • If valid and non-conflicting with any existing ones, accept.

  • If valid but conflicting with an existing finality signature, it sends an IBC 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.

    • 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, so that Babylon contracts can transfer the rewards to Babylon.

Implementation​

We have finished the reference implementation. The codebases include:

  • babylon: Babylon node with BTC staking integration support to Cosmos SDK chains.
  • finality-provider: The Finality Provider program
  • btc-staker: The BTC Staker program
  • babylon-contract: The CosmWasm contracts deployed on the BSN chain for integration.
  • babylon-sdk: The Cosmos SDK module serving as a thin layer between Babylon contracts and Cosmos SDK level of the BSN chain

Local deployments​

We have developed local deployment scripts for demonstrating the Cosmos integration

Phase-3 devnet information​

The Phase-3 devnet environment (Euphrates) is defined as follows. Note that this assumes a bash shell - modify accordingly for other shells, or use bash:

$ cat <<EOF >env_euphrates.sh
:

export binary="babylond"
export chainId="euphrates-0.6.0"
export homeDir="$HOME/.babylond"

export key="user"
export keyringBackend="--keyring-backend=test"
export feeToken="ubbn"

export rpcUrl="https://rpc-euphrates.devnet.babylonlabs.io"
export nodeUrl="$rpcUrl"
export grpcUrl="grpc-euphrates.devnet.babylonlabs.io:443"
export faucetUrl="https://faucet-euphrates.devnet.babylonlabs.io"

alias babylond='babylond --home=$homeDir'
EOF
$ . ./env_euphrates.sh