Skip to main content

BABY Wallet & Staking Integration Guide

The Babylon Genesis is a PoS chain built using the Cosmos SDK and utilises most of the vanilla Cosmos SDK functionality shared among chains developed using it. Therefore, a wallet already supporting chains built using Cosmos SDK should find it straightforward to add Babylon Genesis as a supported blockchain.

In this document, we will walk through the considerations of integrating the Babylon Genesis blockchain into your wallet:

Babylon Genesis Network Information​

Following is a list of the key network details of Babylon Genesis:

  • RPC nodes can be found for the network you are interested in our networks registry.
  • Token minimum denomination: ubbn (6 decimals)
  • Human-readable denomination: BABY

Accounts, message signing, token balance, and token transfer​

The Babylon Genesis chain utilises the default Cosmos SDK functionality for accounts, message signing, token balance, and token transfer. Please refer to the relevant Cosmos SDK documentation for more details.

Staking​

The Babylon blockchain uses an epochised staking mechanism where staking transactions are executed at the end of an epoch rather than immediately.

  • An epoch is defined as a specific block range, determined by an epoch interval defined in the x/epoching module's parameters.
  • During each epoch, staking messages are queued in a delayed execution queue.
  • At the epoch's end, all queued staking messages are processed in a batch, resulting in epoch based voting power transitions.

To enable this mechanism, Babylon modifies the standard Cosmos SDK staking process:

  • Babylon replaces the default Cosmos SDK x/staking module with a custom module, x/epoching.
  • This custom module wraps the standard staking functionality to enforce epoch-based voting power transitions.
  • The wrapped staking messages are largely similar to those in the default x/staking module. The specifications of these wrapped messages are available here.

Wallets wishing to support Babylon PoS delegations natively must use the custom x/epoching mechanism.

The epochised staking approach introduces the following UX considerations for wallet integration:

  • Delayed Staking Activation: Although wrapped staking messages are executed immediately, the actual staking operation takes effect only at the epoch's end. Wallets should clearly communicate this delay to users to set proper expectations.
  • Delayed Funds Locking: Users' funds remain liquid until staking activation occurs at the epoch's conclusion. This creates a for staking failure: if users transfer or spend their funds before staking takes effect, the staking transaction will fail. Wallets should warn users about this possibility.

Wallets can provide users with visibility into pending staking messages using the LastEpochMsgs query in x/epoching. This query allows wallets to display the messages queued for execution at the end of the current epoch.

Unbonding​

Babylon speeds up the unbonding process by leveraging Bitcoin timestamping, significantly reducing the unbonding period from the default 21 days in the Cosmos SDK to approximately ~50 hours.

This process works as follows:

  • Epoch Timestamping: At the end of each epoch, Babylon records its blockchain state onto the Bitcoin blockchain through a Bitcoin timestamp.
  • Bitcoin Confirmations: Once the timestamp receives a sufficient number of confirmations on the Bitcoin blockchain (a parameter configurable in Babylon), the state of the epoch if considered finalized.
    • The number of required Bitcoin confirmations is set by the x/btccheckpoint module, detailed here
    • For example, on the Babylon Genesis mainnet, this value will be set to 300 confirmations, corresponding to roughly ~33 hours for unbonding to be completed, assuming an average Bitcoin block time of 10 minutes.
  • Unbonding Finalization: All unbonding requests submitted up to the end of that epoch are processed and finalized after the required Bitcoin confirmations are reached.

An example scenario demonstrating how fast unbonding works in practice:

  • Setup
    • Epoch interval: 300 blocks
    • Bitcoin confirmations for finalization: 300 blocks
  • Unbonding Request:
    • A user submits an unbonding transaction at block 157
  • Epoch Processing:
    • The unbonding transaction is queued and processed at the end of the epoch (block 300).
    • The user’s status is updated to unbonding, and the epoch’s state is timestamped on Bitcoin.
  • Finalization:
    • After ~50 hours, the Bitcoin timestamp reaches 300 confirmations.
    • Babylon Genesis detects this and completes the unbonding process, fully unbonds the user’s stake.