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 1-2 days (varies by network configuration).

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.

Wallet Integration Recommendation​

To provide the best experience for users here are some suggestions to wallet developers:

  1. Epochised Staking UI:

    • Show a clear indication that staking operations are queued for end-of-epoch execution

    • Display estimated time until the end of current epoch

    • Provide a way to view all pending staking operations

  2. Fast Unbonding UI:

    • Accurately communicate the unbonding period

    • Indicate that unbonding leverages Bitcoin security

    • If possible, show progress of Bitcoin confirmations for unbonding requests

  3. Slashing Warnings:

    • Include clear warnings about the slashing risk

    • Highlight the importance of choosing reliable validators

Implementation Best Practices​

  1. Proper Error Handling:

    • Handle epoch transition edge cases

    • Manage potential failures due to users spending funds before epoch processing

  2. Refresh Strategies:

    • Implement proper cache refreshing after expected epoch boundaries

    • Update delegation status after expected unbonding completion times

  3. Testing:

    • Test thoroughly against Babylon testnet before mainnet integration

    • Verify all epoch-based operations complete as expected

  4. User Communication:

    • Clearly explain the unique aspects of BABY staking (epochised staking, fast unbonding)

    • Provide educational content about the relationship between Bitcoin security and BABY staking

Common Integration Challenges​

  1. Epochised Staking Transition:

    • Users transferring funds after staking transaction but before epoch processing

    • Solution: Clear warnings about not transferring funds until end of epoch

  2. Fast Unbonding Expectations:

    • Managing user expectations around unbonding times, which depend on Bitcoin block times

    • Solution: Provide estimated time ranges rather than exact times

  3. Validator Selection:

    • Helping users choose reliable validators to minimize slashing risk

    • Solution: Display validator uptime, commission rates, and voting power