Skip to main content

Integrating with Babylon Phase 3 Devnet (Euphrates) for Cosmos chains

Overview​

Euphrates 0.5.0 is the 5th version of a Babylon devnet that supports integration with other BSNs (Bitcoin Secured Networks). On top of Euphrates 0.2.0 where BSNs can receive registration messages of Finality Providers and BTC delegations, Euphrates 0.3.0 allows Finality Providers to submit finality signatures to the BSN. Euphrates 0.4.0 allows the BSN to tally its blocks and check their finalization status, and Euphrates 0.5.0 supports Finality Provider slashing and slashing propagation to Babylon and other BSNs.

This page provides a guide for PoS systems to integrate with Euphrates 0.5.0. The integration allows a BSN system to get economic security from BTC staking.

Euphrates 0.5.0 is currently in a highly experimental phase, and unexpected issues may arise. We welcome any feedback on the integration process and this document.

System components. The integration involves three blockchains:

  • A Bitcoin blockchain. In this specific case, we’re using Bitcoin Signet.
  • A Babylon blockchain. This is the Euphrates devnet, presented below.
  • A BSN system. This is the system that we aim to integrate with Babylon.

User stories. The integration provides the following user stories for BSN systems:

  1. Babylon receives registrations of BSN systems, BSN Finality Providers, and BTC delegations (shipped in Euphrates v0.1.0).
  2. Babylon propagates BSN Finality Providers and BTC delegations to BSN systems (shipped in Euphrates v0.2.0).
  3. BSN Finality Providers submit finality signatures to their BSN systems (shipped in Euphrates v0.3.0).
  4. BSN systems tally blocks and determine their finalization status (shipped in Euphrates v0.4.0).
  5. Finality Providers who double sign blocks are slashed, their associated slashing transactions are executed, and delegations are unbonded (shipped in Euphrates v0.5.0, current version).

BSN system requirements​

The BSN system integrating with Euphrates 0.5.0 needs to support IBC and CosmWasm smart contracts. This is because Babylon sends information about Finality Providers and BTC delegations as IBC packets. The BSN system needs to deploy CosmWasm smart contracts to process these IBC packets, and then store the Finality Providers and BTC delegations information.

The Babylon team is developing a specialized relayer to support BSN systems without IBC, and is developing BSN side software for various types of BSN systems.

Prerequisites​

To integrate with Euphrates 0.5.0, you need to install and set up the following software.

Golang / Rust​

This project requires Go version 1.21 and Rust stable version. You can install Go by following https://go.dev/doc/install, and install Rust by following https://www.rust-lang.org/tools/install.

Also install essential tools and packages that might be needed to compile and build the binaries. In Ubuntu / Debian systems:

sudo apt install build-essential

Bitcoin​

You can compile bitcoin v26.x from source, or install one of the pre-built binary images for your OS.

Babylon node​

Babylon node software provides CLI commands and queries for Finality Providers and BTC delegations. Note that you don’t need to run a Babylon node for integration purposes.

git clone https://github.com/babylonlabs-io/babylon.git

Then, check out the euphrates-0.5.0-rc.0 tag.

cd babylon
git checkout euphrates-0.5.0-rc.0

At the top-level directory of the project

make install

The above command will build and install the babylond binary to $GOPATH/bin.

Finality Provider​

Finality Providers are responsible for voting at a finality round on top of CometBFT. Similar to any native PoS validator, a Finality Provider can receive voting power delegations from BTC stakers, and can earn commission from the staking rewards denominated in Babylon tokens.

To install Finality Provider software, clone the repository to your local machine from Github:

git clone https://github.com/babylonlabs-io/finality-provider.git

Then, check out the euphrates-0.5.0-rc.0 tag.

cd finality-provider
git checkout euphrates-0.5.0-rc.0

At the top-level directory of the project

make install

The above command will build and install the following binaries to $GOPATH/bin:

  • fpd: The daemon and CLI program for the finality-provider.
  • eotsd: The daemon program for the EOTS manager.

BTC Staker​

To get started, clone the repository to your local machine from GitHub, check out

git clone https://github.com/babylonlabs-io/btc-staker.git

Then, check out the euphrates-0.5.0-rc.0 tag.

cd btc-staker
git checkout euphrates-0.5.0-rc.0

At the top-level directory of the project

make install

The above command will build and install the following binaries to $GOPATH/bin:

  • stakerd: The daemon program for the btc-staker
  • stakercli: The CLI tool for interacting with stakerd.

Accessing the Euphrates devnet​

Let’s define the Babylon client environment to access the Euphrates devnet. Please notice that the below assumes / depends on the bash shell. Modify accordingly for other shells, or use bash:

$ cat <<EOF >env_euphrates.sh
:

export binary="babylond"
export chainId="euphrates-0.5.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

Getting test tokens​

Babylon tBABY tokens. One can get Babylon tBABY tokens on Euphrates devnet by the following:

  1. Create a Babylon account by using
$ babylond keys add $key $keyringBackend
  1. Then get some tBABY test tokens. If you have access, you can for example contact Spyros Kekos (@Spyros) in BabylonLabs’s Slack workspace, or directly use the #faucet-euphrates-bbn channel on Babylon discord server. Alternatively, you can try hitting the faucet endpoint directly:
$ curl $faucetUrl/claim \
  -H "Content-Type: multipart/form-data" \
  -d '{ "address": "<your_bbn_address>"}'
  1. You can verify the account’s balance by using
$ babylond query bank balances <your_bbn_address> --node $nodeUrl

Getting signet BTC tokens. The Euphrates devnet is connected to BTC Signet. There’s information on how to connect to Signet in the BTC Signet wiki. After creating a wallet and a new BTC address in the signet network, you can visit Bitcoin’s signet faucets (e.g., https://signetfaucet.com) for signet BTC. Babylon also provides a BTC signet faucet in the Babylon discord server.

Installing Babylon SDK​

For Cosmos-based blockchains, one needs to add the x/babylon module from the Babylon SDK to the BSN blockchain code base. Other BSN systems are not supported at the moment.

The x/babylon module acts as a thin layer between the Cosmos SDK layer and the CosmWasm smart contracts. It allows the BSN system to notify the Babylon contracts upon BeginBlock and EndBlock, such that the contracts can index blocks in the BSN system upon BeginBlock, and tally blocks to determine their finalization status upon EndBlock.

Installing the x/babylon module is no different compared to installing other modules. We have provided a demo Cosmos SDK chain that integrates with the x/babylon module. Please refer to https://github.com/babylonlabs-io/babylon-sdk/tree/v0.5.0-rc.1/demo for the implementation.

Please note that the corresponding version tag of the Babylon SDK is https://github.com/babylonlabs-io/babylon-sdk/tree/v0.5.0-rc.1.

If you do not wish to install Babylon SDK in your code base, you could still proceed with the integration. However, the user story 4 (tallying blocks on-chain) and 5 (slashing support) won’t be supported. In the rest of the doc, all steps that require Babylon SDK are marked as orange.

Integrating with Euphrates 0.5.0​

After setting up the software, address and tokens, please follow the steps below to integrate with Euphrates 0.5.0.

Deploy Babylon contracts on the BSN system​

You need to deploy Babylon CosmWasm contracts on the BSN system. The contracts are responsible for receiving IBC packets of Finality Providers and BTC delegations from Babylon, and maintaining their status.

They also implement block indexing, and vote tallying / block finalization.

You can obtain the Babylon contracts by one of the following methods:

  1. Download babylon_contract.wasm and btc_staking.wasm from the corresponding release tag: https://github.com/babylonlabs-io/babylon-contract/releases/tag/v0.9.0-rc.1.
  2. Alternatively, you can clone the Babylon Contracts repository to your local machine, check out thev0.9.0-rc.1 tag, install cargo run-script, and build the optimized CosmWasm contracts yourself.
$ git clone https://github.com/babylonlabs-io/babylon-contract.git
$ cd babylon-contract
$ git checkout v0.9.0-rc.1
$ cargo install cargo-run-script
$ cargo optimize

After that, you will have two contracts in the artifacts/ folder:

  • babylon_contract.wasm: Contract for handling IBC packets.
  • btc_staking.wasm: Contract for maintaining Finality Providers and BTC delegations.

If the BSN system is based on Cosmos SDK, you can then deploy the two contracts.

Note: The following examples are based on bcd, our toy blockchain binary that is part of babylon-sdk, and that we use for development and testing. You’ll need to adapt these instructions accordingly, for your BSN chain devnet or testnet. First, this assumes there’s a bcd instance, running locally at the moment through a docker container. If you want to follow these instructions to the letter, you can use the docker image built with the build-bcd make target, part of the https://github.com/babylonlabs-io/babylon-sdk repository, to reproduce this setup.

  1. Start the integration deployment setup
$ git clone [https://github.com/babylonlabs-io/babylon-sdk.git](https://github.com/babylonlabs-io/babylon-integration-deployment.git)
$ cd babylon-sdk
$ make build-bcd
$ docker run babylonlabs-io/local-bcd
  1. In another terminal or session, set the environment to access the BSN system. For bcd, and assuming you’re using the bash shell:
$ cat <<EOF >env_BSN.sh
:

export binary="bcd"
export chainId="$binary-test"
export homeDir="/data/$binary/$chainId"
export key="user"
export keyringBackend="--keyring-backend=test"
export feeToken="stake"

export rpcUrl="http://localhost:26657"
export nodeUrl="tcp://localhost:26657"
export p2pUrl="tcp://localhost:26656"
export profilingUrl="localhost:6060"
export grpcUrl="localhost:9090"
export apiUrl="http://localhost:5183"

export dockerImage="ibcsim-$binary"
export testData="/$dockerImage"

alias bcd='docker exec $dockerImage $binary --home=$homeDir'
EOF
$ . ./env_BSN.sh
  1. Upload the contracts to the BSN system.
<BSN_system_binary> tx wasm store <path_to_babylon_contract.wasm>
<BSN_system_binary> tx wasm store <path_to_btc_staking.wasm>

In the bcd example:

$ bcd tx wasm store "$testData/babylon_contract.wasm" $keyringBackend --from $key --chain-id $chainId --gas 20000000000 --gas-prices 0.01u$feeToken --node $nodeUrl -y
$ bcd tx wasm store "$testData/btc_staking.wasm" $keyringBackend --from $key --chain-id $chainId --gas 20000000000 --gas-prices 0.01u$feeToken --node $nodeUrl -y

The BSN system will return the contract code IDs for them. In the bcd example, you can use

$ bcd query wasm list-code

to get the latest code IDs.

Then, instantiate the Babylon contract via

$ instantiateMsg='{
    "network": "signet",
    "babylon_tag": "01020304",
    "btc_confirmation_depth": 1,
    "checkpoint_finalization_timeout": 2,
    "notify_cosmos_zone": false,
    "btc_staking_code_id": <btc_staking_code_id>,
    "BSN_name": "Test BSN",
    "BSN_description": "Test BSN Description"
}'
$ <BSN_system_binary> tx wasm instantiate <babylon_contract_code_ID> "$instantiateMsg"

In the bcd example / case:

$ instantiateMsg='{
    "network": "signet",
    "babylon_tag": "01020304",
    "btc_confirmation_depth": 1,
    "checkpoint_finalization_timeout": 2,
    "notify_cosmos_zone": false,
    "btc_staking_code_id": 2,
    "BSN_name": "test-BSN-chain",
    "BSN_description": "Test BSN Description"
}'
$ bcd tx wasm instantiate 1 "$instantiateMsg" --admin=$(bcd keys show user $keyringBackend -a) --label "v0.9.0" $keyringBackend --from $key --chain-id $chainId --gas 20000000000 --gas-prices 0.001u$feeToken --node $nodeUrl -y --amount 100000$feeToken

The BSN system will return the <babylon_contract_address> of the Babylon contract. In the bcd example, you can run

$ bcd query wasm list-contract-by-code 1

to get the address (or addresses) of the Babylon contract.

Once instantiated, the Babylon contract will reserve the wasm.<babylon_contract_address> IBC port.

Pass a governance proposal to set contract addresses in the Babylon SDK module​

In order to send notifications to Babylon contracts upon BeginBlock and EndBlock, the x/babylon module in Babylon SDK needs to know the addresses of the Babylon contract and the BTC staking contract. The contract addresses are specified as module parameters in the x/babylon module.

Since the contract addresses are known only after spinning up the BSN chain, we need to update the addresses in the module parameters on the fly. We can do so via submitting a parameter change governance proposal. Here provides detailed instructions on how to submit such a governance proposal. Note that gaiad binary needs to be replaced by the binary of the BSN chain.

Create an IBC channel between Babylon and the BSN system​

You can create an IBC channel by following the instructions here (if using Hermes) or here (if using Go relayer). Please ensure to use the latest versions of them for full compatibility.

You’ll need the following information:

  • The port ID is zoneconcierge for Babylon, and wasm.<babylon_contract_address> for the BSN system.
  • The GRPC endpoint of the Euphrates devnet is https://grpc-euphrates.devnet.babylonlabs.io .
  • For gas prices, both for the IBC relayer setup and sending TXs, you can just use 1ubbn.
  • Channel ordering must be specified as “ordered".
  • and channel version is "zoneconcierge-1”.

Register your BSN system on Babylon​

Starting with this version v0.5.0, the BSN system is registered automatically during IBC channel establishment. That’s what the BSN_name and BSN_description parameters of the Babylon Contract instantiation message are for.

FAQs (these apply to all babylond tx commands):

  • If you encounter error like **ERR** failure when running app err="rpc error: code = InvalidArgument desc = rpc error: code = InvalidArgument desc = Address cannot be empty: invalid request" , try to add a flag --from <key_name> where <key_name> is the key name associated with your address.
  • If you encounter error like chain ID required but not specified, try to add a flag --chain-id <chain_id> where <chain_id> can be obtained from https://rpc-euphrates.devnet.babylonlabs.io/block?height=1 Then, you can query the Babylon node to see the blockchain registered to Babylon.
$ babylond query btcstkBSN registered-BSNs -o json --node https://rpc-euphrates.devnet.babylonlabs.io
{
  "chain_ids": [
    "test-BSN-chain"
  ],
  "pagination": {
    "next_key": null,
    "total": "0"
  }
}
$

Become a Finality Provider for your BSN system​

Set up EOTS manager. To become a Finality Provider, you need to set up a EOTS manager that manages the key pairs for your Finality Provider. Please follow steps at EOTS Manager | Babylon Labs and adapt the configuration file attached in the appendix.

Set up Finality Provider daemon. Then you can set up a Finality Provider. It will call EOTS manager for signing messages, and interact with Babylon. Please follow steps at Finality Provider | Babylon Labs and adapt the configuration file attached in the appendix.

Note: Mind to use your BSN system id as chain-id for the CLI commands.

Create and register your Finality Provider on Babylon. After that, you can create a Finality Provider instance through the fpd create-finality-provider or fpd cfp command. The created instance is associated with a BTC public key which serves as its unique identifier and a Babylon account to which staking rewards will be directed.

$ fpd create-finality-provider --key-name my-finality-provider --chain-id <your_chain_id> --moniker my-name

You can register a created Finality Provider in Babylon through the fpd register-finality-provider. Note that one needs to obtain some tBABY tokens from L2Scan Babylon Testnet Faucet first. The output contains the hash of the Babylon Finality Provider registration transaction.

$ fpd register-finality-provider d0fc4db48643fbb4339dc4bbf15f272411716b0d60f18bdfeb3861544bf5ef63

Then, you can query the Babylon node to see the Finality Provider registered on Babylon

$ babylond query btcstkBSN finality-providers <your_chain_id>
{
  "finality_providers": [
    {
      "description": {
        "moniker": "Finality Provider 3",
        "identity": "",
        "website": "",
        "security_contact": "",
        "details": ""
      },
      "commission": "0.050000000000000000",
      "babylon_pk": {
        "key": "AugG2rD0aBx6Q4edjPRQ2w7eoRRYVV21zcmVP8O4qyAj"
      },
      "btc_pk": "1ef48bf0fa918ce2070b4e4952064a75e0f2ab914979ced622692fd708f23ae5",
      "pop": {
        "btc_sig_type": "BIP340",
        "babylon_sig": "tFcTCPmHM8mW6fCm2ApfGsngXK76jCFbxuCGe2OdxBJqjdBoONb6Gmuip0j18BaX5PJwNFGrm9l8RR9e8d31ww==",
        "btc_sig": "/Vg6uoW+DbgGk0xQhEXJH2nJQfigUzYP5nPPI2FUcmGCdNnqlww3yVipekiG/r6b02H3AbWFMQIkiPiy+uHHyw=="
      },
      "slashed_babylon_height": "0",
      "slashed_btc_height": "0",
      "height": "0",
      "voting_power": "0",
      "chain_id": "test-BSN-chain"
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "0"
  }
}
$

Stake BTC to your Finality Providers​

Set up BTC Staker daemon. To stake BTC to your Finality Providers, you need to set up a BTC Staker daemon that generates Bitcoin staking transactions and sends staking requests to Babylon. Please follow steps at Stake with BTC Staker CLI | Babylon Blockchain and adapt the configuation file attached in the appendix.

Staking BTC to your Finality Providers. When staking, specify the BTC public keys of Finality Providers using the --finality-providers-pks flag in the stake command. Note that Babylon requires a BTC delegation to restake to at least 1 Babylon Finality Provider, apart from Finality Providers of other BSN systems.

First, you could use the following command to list all Babylon Finality Providers.

$ stakercli daemon babylon-finality-providers

or

$ babylond query btcstaking finality-provider <fp_pk> --node $nodeUrl

Then, find the BTC address that has sufficient Bitcoin balance that you want to stake from.

stakercli daemon list-outputs

After that, stake Bitcoin to the Finality Provider of your choice. The --staking-time flag specifies the timelock of the staking transaction in BTC blocks. The --staking-amount flag specifies the amount in Satoshis to stake. For example, <pk1> could be the Bitcoin public key of your Finality Provider, while <pk2> is a Babylon Finality Provider of your choice.

stakercli daemon stake \
  --staker-address <staker_btc_address> \
  --staking-amount 1000000 \
  --finality-providers-pks <babylon_fp_pk> \
  --finality-providers-pks <BSN_fp_pk> ... \
  --staking-time 10000 # ~70 days

Note that among public keys specified in --finality-providers-pks, at least one of them should be a Babylon Finality Provider. For example, you can let the BTC delegation to restake to a Babylon Finality Provider as well as a Finality Provider for your BSN system.

Then, you can query the Babylon node to see the BTC delegation

babylond query btcstaking btc-delegations any --node https://rpc-euphrates.devnet.babylonlabs.io
{  "btc_delegations": [
    {
      "btc_pk": "6e25665ffcb10a82af5103263f4c1f33bb364244009bc4d4ef7696462de71cde",
      "fp_btc_pk_list": [
        "63b996ff158e5e2b82ed099817fb1b549b23648c2e43e96394ff691a8ff4128d",
        "1ef48bf0fa918ce2070b4e4952064a75e0f2ab914979ced622692fd708f23ae5"
      ],
      "start_height": "120",
      "end_height": "620",
      "total_sat": "1000000",
      "staking_tx_hex": "0100000000010107d3d802eb6e3d40552422cf4c4be38f429d4099102438470955dbb6a449041d0100000000ffffffff0240420f00000000002251204206b407838b11a232bc5d26c2e25661a7f93f52c21e9d0a4efea6d85022506ecf788b3b000000001600147cc587002b9a7181bd3ac3b228fb08e32af6320d0247304402202a6ca03e47c55a282483488d91b8b697d3a0b3fb4400370ca3038371745507a702203e79b45355512e2d1c200d699b07ab073bc0b5ad5a85a7e7f2a3ad1d0d21ee05012102a6069d1b48df8dc36024273f0f977d69b954afe6b570f875216a96f8636e538b00000000",
      "slashing_tx_hex": "01000000015507d254512ff96d318949a172122d93e31a13f312d44f17698b7ec481f4cbe10000000000ffffffff02a0860100000000001976a914010101010101010101010101010101010101010188acb8b70d00000000002251203d030fe574510e1b14d6314caf90fe13ae32bff13e1bf97d71df47d9d6f7e29e00000000",
      "delegator_slash_sig_hex": "2a69b7b478bb2d24dcb08f13bcd089998fd6f27a4ea9c016a5e26b224e039910d671c525e219a2c9a5fabaf9508f7b16641af3f73b7bf12a659304a061e31215",
      "covenant_sigs": [],
      "staking_output_idx": 0,
      "active": false,
      "status_desc": "PENDING",
      "unbonding_time": 3,
      "undelegation_response": {
        "unbonding_tx_hex": "02000000015507d254512ff96d318949a172122d93e31a13f312d44f17698b7ec481f4cbe10000000000ffffffff01ac300f0000000000225120151e497fb4a8e1a16db25eba8fa6858185085ab125161e31b6026d68b2de72f900000000",
        "delegator_unbonding_sig_hex": "",
        "covenant_unbonding_sig_list": [],
        "slashing_tx_hex": "01000000015402ecd010f7edc070f7aaac344ef98d4451879109f1d169e907f2003f36a94d0000000000ffffffff02de840100000000001976a914010101010101010101010101010101010101010188ace6a70d00000000002251203d030fe574510e1b14d6314caf90fe13ae32bff13e1bf97d71df47d9d6f7e29e00000000",
        "delegator_slashing_sig_hex": "3a0ade421330bf02bd8854543b90fb16895be79c0fb7d0c4e2367e630d50949e6d41d2bf48b3b8d024a6b9cf6e8a127177994e5ad90d4a6983bb5a7abd22a055",
        "covenant_slashing_sigs": []
      }
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "0"
  }
}

Wait until BSN system receives IBC packets​

After some time, the Babylon contract on the BSN side is supposed to receive IBC packets about these Finality Providers and BTC delegations, and store them in the local KV store. If the BSN system is based on Cosmos SDK, then you can query Finality Providers via

<BSN_system_binary> query wasm contract-state smart <btc_staker_contract_address> '{ "finality_providers": {} }'

and query BTC delegation with a given staking tx hash <staking_tx_hash_hex> via

<BSN_system_binary> query wasm contract-state smart <btc_staker_contract_address> '{ "delegation": { "staking_tx_hash_hex": "<staking_tx_hash_hex>" } }'

Wait until Finality Providers start submitting finality signatures​

Once the BSN system receives IBC packets of Finality Providers and BTC delegations, the Finality Provider daemon will automatically start submitting finality signatures to the BTC staking contract on the BSN system. One can query the finality signature at a given block signed by a given Finality Provider via the following query

<BSN_system_binary> query wasm contract-state smart <btc_staker_contract_address> '{"finality_signature":{"btc_pk_hex":"<cz_btc_pk>","height":<last_block_height>}}'

Wait until blocks are finalized​

The Babylon contracts will tally BSN chain blocks and determine their finalization status upon each EndBlock. One can query the finalization status of a given block via the below query.

<BSN_system_binary> query wasm contract-state smart <btc_staker_contract_address> '{"block":{"height":<block_height>}}'

Current iteration​

In this iteration, Babylon supports slashing of equivocations that happened in the BSN system. Testing / demonstration of this feature in a devnet is non-trivial, and so it’s out of scope for this guide.

Future iterations​

In the future iterations, Babylon will support generating and distributing rewards to Finality Providers in the BSN system, and a number of improvements on the UX of the integration.

Appendix​

The appendix provides example configuration files used in the software.

EOTS manager (eotsd.conf)​

[Application Options]
; Logging level for all subsystems
LogLevel = debug
; Type of keyring to use
KeyringBackend = test
; the listener for RPC connections, e.g., localhost:1234
RpcListener = 0.0.0.0:15813
[metrics]
; IP of the Prometheus server
Host = 127.0.0.1
; Port of the Prometheus server
Port = 2112
; The interval of Prometheus metrics updated
UpdateInterval = 1m0s
[dbconfig]
; The directory path in which the database file should be stored.
DBPath = /home/finality-provider/.eotsd/data
; The name of the database file.
DBFileName = eots.db
; Prevents the database from syncing its freelist to disk, resulting in improved performance at the expense of increased startup time.
NoFreelistSync = true
; Specifies if a Bolt based database backend should be automatically compacted on startup (if the minimum age of the database file is reached). This will require additional disk space for the compacted copy of the database but will result in an overall lower database size after the compaction.
AutoCompact = false
; Specifies the minimum time that must have passed since a bolt database file was last compacted for the compaction to be considered again.
AutoCompactMinAge = 168h0m0s
; Specifies the timeout value to use when opening the wallet database.
DBTimeout = 1m0s

Finality Provider (fpd.conf)​

[Application Options]
; Logging level for all subsystems {trace, debug, info, warn, error, fatal}
LogLevel = debug

; the type of the BSN chain
ChainType = wasm

; The number of Schnorr public randomness for each commitment
NumPubRand = 100

; The upper bound of the number of Schnorr public randomness for each commitment
NumPubRandMax = 1000

; The minimum gap between the last committed rand height and the current Babylon block height
MinRandHeightGap = 10

; The interval between each update of finality-provider status
StatusUpdateInterval = 5s

; The interval between each attempt to commit public randomness
RandomnessCommitInterval = 5s

; The interval between each attempt to submit finality signature or public randomness after a failure
; TODO: how to make fpd to not submit randomness/finality signatures for the 1st devnet?
SubmissionRetryInterval = 300s

; The maximum number of retries to submit finality signature or public randomness
MaxSubmissionRetries = 100

; The interval between each try of fast sync, which is disabled if the value is 0
FastSyncInterval = 20s

; The maximum number of blocks to catch up for each fast sync
FastSyncLimit = 10

; The block gap that will trigger the fast sync
FastSyncGap = 6

; The address of the remote EOTS manager; Empty if the EOTS manager is running locally
EOTSManagerAddress = BSN-eotsmanager:15813

; Bitcoin network to run on
BitcoinNetwork = signet

; the listener for RPC connections, e.g., localhost:1234
RpcListener = 127.0.0.1:12581

; The maximum number of finality-provider instances running concurrently within the daemon
MaxNumFinalityProviders = 10

; The interval between each attempt to update the finality-provider status
SyncFpStatusInterval = 10s

[chainpollerconfig]
; The maximum number of Babylon blocks that can be stored in the buffer
BufferSize = 1000

; The interval between each polling of Babylon blocks
PollInterval = 5s

; The static height from which we start polling the chain
StaticChainScanningStartHeight = 1

; Automatically discover the height from which to start polling the chain
AutoChainScanningMode = true

[metrics]
; IP of the Prometheus server
Host = 127.0.0.1

; Port of the Prometheus server
Port = 2112

; The interval of Prometheus metrics updated
UpdateInterval = 1m0s

[dbconfig]
; The directory path in which the database file should be stored.
DBPath = /home/finality-provider/.fpd/data

; The name of the database file.
DBFileName = finality-provider.db

; Prevents the database from syncing its freelist to disk, resulting in improved performance at the expense of increased startup time.
NoFreelistSync = true

; Specifies if a Bolt based database backend should be automatically compacted on startup (if the minimum age of the database file is reached). This will require additional disk space for the compacted copy of the database but will result in an overall lower database size after the compaction.
AutoCompact = false

; Specifies the minimum time that must have passed since a bolt database file was last compacted for the compaction to be considered again.
AutoCompactMinAge = 168h0m0s

; Specifies the timeout value to use when opening the wallet database.
DBTimeout = 1m0s

[babylon]
; name of the key to sign transactions with
Key = finality-provider

; chain id of the chain to connect to
ChainID = chain-test

; address of the rpc server to connect to
RPCAddr = https://rpc-euphrates.devnet.babylonlabs.io:443

; address of the grpc server to connect to
GRPCAddr = https://rpc-euphrates.devnet.babylonlabs.io:9090

; account prefix to use for addresses
AccountPrefix = bbn

; type of keyring to use
KeyringBackend = test

; adjustment factor when using gas estimation
GasAdjustment = 3

; comma separated minimum gas prices to accept for transactions
GasPrices = 0.01ubbn

; directory to store keys in
KeyDirectory = /home/finality-provider/.fpd

; flag to print debug output
Debug = true

; client timeout when doing queries
Timeout = 20s

; block timeout when waiting for block events
BlockTimeout = 1m0s

; default output when printint responses
OutputFormat = json

; sign mode to use
SignModeStr = direct

[wasm]
; name of the key to sign transactions with
Key = BSN-fp

; chain id of the chain to connect to
ChainID = <BSN_id>

; address of the rpc server to connect to
RPCAddr = <BSN_system_rpc_addr>

; address of the grpc server to connect to
GRPCAddr = <BSN_system_grpc_addr>

; account prefix to use for addresses
AccountPrefix = <BSN_system_account_prefix>

; type of keyring to use
KeyringBackend = test

; adjustment factor when using gas estimation
GasAdjustment = 3

; comma separated minimum gas prices to accept for transactions
GasPrices = 0.01ustake

; directory to store keys in
KeyDirectory = /home/finality-provider/.fpd

; flag to print debug output
Debug = true

; client timeout when doing queries
Timeout = 20s

; block timeout when waiting for block events
BlockTimeout = 1m0s

; default output when printint responses
OutputFormat = json

; sign mode to use
SignModeStr = direct

; TODO(euphrates): fetching this from bcd node?
BtcStakingContractAddress = <babylon_btc_staking_contract_address>

BTC staker (stakerd.conf)​

[Application Options]
; Logging level for all subsystems {trace, debug, info, warn, error, fatal}
DebugLevel = debug
; The base directory that contains staker's data, logs, configuration file, etc.
StakerdDir = /home/btcstaker/.stakerd
; Path to configuration file
ConfigFile = /home/btcstaker/.stakerd/stakerd.conf
; The directory to store staker's data within
DataDir = /home/btcstaker/.stakerd/data
; Directory to log output.
LogDir = /home/btcstaker/.stakerd/logs
; Write CPU profile to the specified file
CPUProfile =
; Enable HTTP profiling on either a port or host:port
Profile =
; If config filr does not exist, create it with current settings
DumpCfg = false
; Add an interface/port/socket to listen for RPC connections
RawRPCListeners = 0.0.0.0:15812
[walletconfig]
; name of the wallet to sign Bitcoin transactions
WalletName = btcstaker
; passphrase to unlock the wallet
WalletPass = walletpass
[stakerconfig]
; The interval for Babylon node BTC light client to catch up with the real chain before re-sending delegation request
BabylonStallingInterval = 20s
; The interval for staker to check whether unbonding tx received finality-provider and covenant signatures
UnbondingTxCheckInterval = 20s
; Exit stakerd on critical error
ExitOnCriticalError = true
[walletrpcconfig]
; location of the wallet rpc server
Host = bitcoindsim:18443/wallet/btcstaker
; user auth for the wallet rpc server
User = rpcuser
; password auth for the wallet rpc server
Pass = rpcpass
; disables tls for the wallet rpc client
DisableTls = true
[chain]
; network to run on
Network = signet
; Connect to a custom signet network defined by this challenge instead of using the global default signet test network -- Can be specified multiple times
SigNetChallenge =
[btcnodebackend]
; type of node to connect to {bitcoind, btcd}
Nodetype = bitcoind
; type of wallet to connect to {bitcoind, btcwallet}
WalletType = bitcoind
; fee mode to use for fee estimation {static, dynamic}. In dynamic mode fee will be estimated using backend node
FeeMode = static
; minimum fee rate to use for fee estimation in sat/vbyte. If fee estimation by connected btc node returns a lower fee rate, this value will be used instead
MinFeeRate = 2
; maximum fee rate to use for fee estimation in sat/vbyte. If fee estimation by connected btc node returns a higher fee rate, this value will be used instead. It is also used as fallback if fee estimation by connected btc node fails and as fee rate in case of static estimator
MaxFeeRate = 25
[btcd]
; The daemon's rpc listening address. If a port is omitted, then the default port for the selected chain parameters will be used.
RPCHost = 127.0.0.1:18334
; Username for RPC connections
RPCUser = user
; Password for RPC connections
RPCPass = pass
; File containing the daemon's certificate file
RPCCert = /Users/vitsalis/Library/Application Support/Btcd/rpc.cert
; The raw bytes of the daemon's PEM-encoded certificate chain which will be used to authenticate the RPC connection.
RawRPCCert =
; size of the Bitcoin blocks cache
BlockCacheSize = 100000
[bitcoind]
; The daemon's rpc listening address
RPCHost = bitcoindsim:18443
; Username for RPC connections
RPCUser = rpcuser
; Password for RPC connections
RPCPass = rpcpass
; The address listening for ZMQ connections to deliver raw block notifications
ZMQPubRawBlock = tcp://bitcoindsim:29001
; The address listening for ZMQ connections to deliver raw transaction notifications
ZMQPubRawTx = tcp://bitcoindsim:29002
; The read deadline for reading ZMQ messages from both the block and tx subscriptions
ZMQReadDeadline = 30s
; The fee estimate mode. Must be either ECONOMICAL or CONSERVATIVE.
EstimateMode = CONSERVATIVE
; The maximum number of peers staker will choose from the backend node to retrieve pruned blocks from. This only applies to pruned nodes.
PrunedNodeMaxPeers = 0
; Poll the bitcoind RPC interface for block and transaction notifications instead of using the ZMQ interface
RPCPolling = false
; The interval that will be used to poll bitcoind for new blocks. Only used if rpcpolling is true.
BlockPollingInterval = 30s
; The interval that will be used to poll bitcoind for new tx. Only used if rpcpolling is true.
TxPollingInterval = 30s
; size of the Bitcoin blocks cache
BlockCacheSize = 1000000
[babylon]
; name of the key to sign transactions with
Key = btc-staker
; chain id of the chain to connect to
ChainID = euphrates-0.5.0
; address of the rpc server to connect to
RPCAddr = https://rpc-euphrates.devnet.babylonlabs.io:443
; address of the grpc server to connect to
GRPCAddr = https://rpc-euphrates.devnet.babylonlabs.io:9090
; account prefix to use for addresses
AccountPrefix = bbn
; type of keyring to use
KeyringBackend = test
; adjustment factor when using gas estimation
GasAdjustment = 1.5
; comma separated minimum gas prices to accept for transactions
GasPrices = 0.01ubbn
; directory to store keys in
KeyDirectory = /home/btcstaker/.stakerd
; flag to print debug output
Debug = true
; client timeout when doing queries
Timeout = 20s
; block timeout when waiting for block events
BlockTimeout = 1m0s
; default output when printint responses
OutputFormat = json
; sign mode to use
SignModeStr = direct
[dbconfig]
; The directory path in which the database file should be stored.
DBPath = /home/btcstaker/.stakerd/data
; The name of the database file.
DBFileName = staker.db
; Prevents the database from syncing its freelist to disk, resulting in improved performance at the expense of increased startup time.
NoFreelistSync = true
; Specifies if a Bolt based database backend should be automatically compacted on startup (if the minimum age of the database file is reached). This will require additional disk space for the compacted copy of the database but will result in an overall lower database size after the compaction.
AutoCompact = false
; Specifies the minimum time that must have passed since a bolt database file was last compacted for the compaction to be considered again.
AutoCompactMinAge = 168h0m0s
; Specifies the timeout value to use when opening the wallet database.
DBTimeout = 1m0s

Hermes IBC relayer​

[global]
log_level = 'debug'
[mode]
[mode.clients]
enabled = true
refresh = true
misbehaviour = true
[mode.connections]
enabled = false
[mode.channels]
enabled = true
[mode.packets]
enabled = true
clear_interval = 100
clear_on_start = true
tx_confirmation = true
[rest]
enabled = true
host = '0.0.0.0'
port = 3031
[telemetry]
enabled = true
host = '127.0.0.1'
port = 3001
[[chains]]
type = "CosmosSdk"
id = 'bbn-test-a'
rpc_addr = 'https://rpc-euphrates.devnet.babylonlabs.io:443'
grpc_addr = 'https://rpc-euphrates.devnet.babylonlabs.io:9090'
event_source = { mode = 'push', url = 'ws://rpc-euphrates.devnet.babylonlabs.io:443/websocket', batch_delay = '500ms' }
rpc_timeout = '10s'
account_prefix = 'bbn'
key_name = 'val01-bbn-a'
store_prefix = 'ibc'
max_gas = 50000000
gas_price = { price = 0.01, denom = 'ubbn' }
gas_multiplier = 1.5
clock_drift = '1m' # to accomdate docker containers
trusting_period = '14days'
trust_threshold = { numerator = '1', denominator = '3' }
[[chains]]
type = "CosmosSdk"
id = 'bbn-test-b'
rpc_addr = $BSN_NODE_RPC
grpc_addr = $BSN_NODE_GRPC
event_source = { mode = 'push', url = 'ws://$BSN_NODE_RPC/websocket', batch_delay = '500ms' }
rpc_timeout = '10s'
account_prefix = 'bbn'
key_name = 'val01-bbn-b'
store_prefix = 'ibc'
max_gas = 50000000
gas_price = { price = 0.01, denom = 'ubbn' }
gas_multiplier = 1.5
clock_drift = '1m' # to accomdate docker containers
trusting_period = '14days'
trust_threshold = { numerator = '1', denominator = '3' }

Go IBC relayer​

global:
    api-listen-addr: :5183
    timeout: 20s
    memo: ""
    light-cache-size: 10
chains:
    babylon:
        type: cosmos
        value:
            key: $BABYLON_KEY
            chain-id: $BABYLON_CHAIN_ID
            rpc-addr: $BABYLON_NODE_RPC
            account-prefix: bbn
            keyring-backend: test
            gas-adjustment: 1.5
            gas-prices: 0.002ubbn
            min-gas-amount: 1
            debug: true
            timeout: 10s
            output-format: json
            sign-mode: direct
            extra-codecs: []
    bcd:
        type: cosmos
        value:
            key: $BSN_KEY
            chain-id: $BSN_CHAIN_ID
            rpc-addr: $BSN_NODE_RPC
            account-prefix: bbnc
            keyring-backend: test
            gas-adjustment: 1.5
            gas-prices: 0.002ustake
            min-gas-amount: 1
            debug: true
            timeout: 10s
            output-format: json
            sign-mode: direct
            extra-codecs: []
paths:
    bcd:
        src:
            chain-id: $BABYLON_CHAIN_ID
        dst:
            chain-id: $BSN_CHAIN_ID