Skip to main content

Unbond via CLI

1. Prerequisites​

Bitcoin Node Setup You need to have a running Bitcoin node bitcoind. You should also have a legacy wallet loaded on Bitcoin mainnet. Babylond will also need to be on the same network. You can configure the stakerd daemon to connect to either bitcoind or btcd node types, but bitcoind is preferred.

To set up the Bitcoin node:

Download and Extract:

# Download Bitcoin Core binary
wget https://bitcoincore.org/bin/bitcoin-core-26.0/bitcoin-26.0-x86_64-linux-gnu.tar.gz

# Extract the downloaded archive
tar -xvf bitcoin-26.0-x86_64-linux-gnu.tar.gz

# Provide execution permissions to binaries
chmod +x bitcoin-26.0/bin/bitcoind
chmod +x bitcoin-26.0/bin/bitcoin-cli

Create and Start Systemd Service: Update the following configurations in the provided file. Replace your_rpc_username and your_rpc_password with your own values. Set user to the machine user (e.g., ubuntu). Note that deprecatedrpc = create_bdb is necessary for creating a legacy wallet. You can add rpcallowip = 0.000.0/0 and rpcbind = 0.000.0 to enable remote connections and start bitcoind with -txindex option.

# Create the service file
sudo tee /etc/systemd/system/bitcoind.service >/dev/null <<EOF
[Unit]
Description=bitcoin mainnet node
After=network.target

[Service]
User=<user>
Type=simple
ExecStart=/home/ubuntu/bitcoin-26.0/bin/bitcoind \
    -deprecatedrpc=create_bdb \
    -mainnet \
    -server \
    -txindex \
    -rpcport=8332 \
    -rpcuser=<your_rpc_username> \
    -rpcpassword=<your_rpc_password>
Restart=on - failure
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF
# Start the service
sudo systemctl daemon-reload
sudo systemctl enable bitcoind
sudo systemctl start bitcoind
# Check the status and logs of the service
systemctl status bitcoind
journalctl -u bitcoind -f

Create Legacy Wallet:

~/bitcoin-26.0/bin/bitcoin-cli -mainnet \
    -rpcuser=<your_rpc_username> \
    -rpcpassword=<your_rpc_password> \
    -rpcport=8332 \
    -named createwallet \
    wallet_name=btcstaker \
    passphrase="<passphrase>" \
    load_on_startup=true \
    descriptors=false

Load Wallet:

~/bitcoin-26.0/bin/bitcoin-cli -mainnet \
    -rpcuser=<your_rpc_username> \
    -rpcpassword=<your_rpc_password> \
    -rpcport=8332 \
    loadwallet "btcstaker"

BTC Staker Installation This project requires Go version 1.21 or later. Install Go by following the official Go installation guide. Install essential tools:

sudo apt install build-essential

Download the code:

git clone https://github.com/babylonlabs-io/btc-staker.git
cd btc-staker
git checkout <release-tag>

Build and install the binary:

make install

If your shell cannot find the installed binaries, add $GOPATH/bin to the $PATH:

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

Create a Babylon Keyring The stakerd daemon requires a keyring with loaded Babylon tokens to pay for transactions. Follow this guide to create a keyring and request funds. BTC Staker Setup Staker Daemon Configuration: Initialize the home directory and dump the default configuration file:

stakercli admin dump-config --config-file-dir /path/to/stakerd-home/

Important Configuration Parameters: Babylon Configuration:

[babylon]
# Name of the key in the keyring to use for signing transactions
Key = btc-staker

# Chain id of the chain (Babylon)
ChainID = bbn-1

# Address of the chain's RPC server (Babylon)
RPCAddr = http://localhost:26657

# Address of the chain's GRPC server (Babylon)
GRPCAddr = https://localhost:9090

# Directory to store staker keys in
KeyDirectory = /path/to/stakerd-home/

BTC Node Configuration:

[chain]
# btc network to run on
Network = mainnet

[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

BTC Wallet Configuration:

[walletconfig]
# name of the wallet to sign Bitcoin transactions.
# this should be the same as set in createwallet command in bitcoind.
WalletName = btcstaker

# passphrase to unlock the wallet
WalletPass = walletpass

[walletrpcconfig]
# location of the wallet rpc server
# note: in case of bitcoind, the wallet host is same as the rpc host
Host = localhost:8332

# user auth for the wallet rpc server
# note: in case of bitcoind, the wallet rpc credentials are same as rpc credentials
# this should be the same as set in the bitcoind daemon
User = your_rpc_username

# password auth for the wallet rpc server. This should be the same as set in the bitcoind daemon
Pass = your_rpc_password

# disables tls for the wallet rpc client
DisableTls = true

BTC Node Type Specific Configuration:

[bitcoind]
# The daemon's rpc listening address
# note: P2P port for mainnet is 8332/8333
# ref - https://github.com/bitcoin/bitcoin/blob/03752444cd54df05a731557968d5a9f33a55c55c/src/chainparamsbase.cpp#L39
RPCHost = 127.0.0.1:8332

# Username for RPC connections. This should be the same as set in the bitcoind daemon
RPCUser = your_rpc_username

# Password for RPC connections. This should be the same as set in the bitcoind daemon
RPCPass = your_rpc_password

# The address listening for ZMQ connections to deliver raw block notifications
ZMQPubRawBlock = tcp://127.0.0.1:29001

# The address listening for ZMQ connections to deliver raw transaction notifications
ZMQPubRawTx = tcp://127.0.0.1:29002

Metrics Configuration:

[metricsconfig]
# if it should be enabled.
Enabled = false

# host of prometheus server.
Host = 127.0.0.1

# port of prometheus server.
ServerPort = 2112

BTC Staker Environment Configuration: Create a .env file in the same directory as the binaries with BTCSTAKER_USERNAME and BTCSTAKER_PASSWORD for secure communication between the Staker Daemon and stakercli.

2. Unbonding BTC Stakes​

The unbond command initiates the unbonding procedure, which involves communication with the Babylon chain, Covenant Emulators, and the Bitcoin blockchain. It builds the unbonding transaction, sends it to the Babylon Genesis chain, waits for signatures from the Covenant Emulators, and then sends the transaction to the Bitcoin blockchain.

To use the unbond command, you need the --staking-transaction-hash, which is the transaction hash from the response of the stake command.

stakercli daemon unbond \
  --staking-transaction-hash `your_staking_transaction_hash`

Replace your_staking_transaction_hash with the actual transaction hash you received when you staked your Bitcoin. For example:

stakercli daemon unbond \
  --staking -transaction -hash 6bf442a2e864172cba73f642ced10c178f6b19097abde41608035fb26a601b10

3. Additional Functionality​

List Staking Transactions​

You can use the following command to get the list of all staking transactions in the database:

stakercli daemon list -staking -transactions

Minimum Unbonding Time​

There is a minimum unbonding time currently set to 1008 BTC blocks. After this period, the unbonding timelock will expire, and the staked funds will be unbonded. You can monitor the progress of the Bitcoin blocks in the bitcoind systemd logs using journalctl -u bitcoind -f or by comparing the latest block in your node with a BTC explorer like https://mempool.space/mainnet.

5. Troubleshooting​

Gas - related Errors If you encounter gas - related errors during the unbonding operation, consider adjusting the GasAdjustment and GasPrices parameters in the stakerd.conf file. For example:

GasAdjustment = 1.5
GasPrices = 0.002ubbn

Communication Issues​

Ensure all configuration settings in the stakerd.conf file are correct, including RPC and GRPC addresses, wallet credentials, and network settings.

Withdraw staked BTC​

The staker can withdraw the staked funds after the timelock of the staking or unbonding transaction expires. Use the --staking-transaction-hash from the response of the stake command.

stakercli daemon unstake \
  --staking -transaction -hash `your_staking_transaction_hash`

Replace your_staking_transaction_hash with the actual transaction hash. For example:

stakercli daemon unstake \
  --staking -transaction -hash 6bf442a2e864172cba73f642ced10c178f6b19097abde41608035fb26a601b10

Note: You can also use this command to get the list of all withdrawable staking transactions in the database.

stakercli daemon withdrawable -transactions

To unstake, you need to wait for your staking/unbonding transaction to be deep enough in the Bitcoin blockchain so that the timelock expires.

note

Unbonding before completing the 100 - day period will make you ineligible for the bonus airdrop. Make sure to carefully consider your decision to unbond, especially if you are aiming to receive the bonus airdrop as part of your staking rewards.

Getting Help​

If you encounter any issues and the unbonding fails, please contact our Babylon Discord for support.