|
| 1 | +--- |
| 2 | +sidebar_label: Wallet Integration Guide |
| 3 | +sidebar_position: 1 |
| 4 | +--- |
| 5 | + |
| 6 | +# Babylon Genesis Chain Wallet Integration |
| 7 | + |
| 8 | +The Babylon Genesis is a PoS chain built using the |
| 9 | +Cosmos SDK and utilises most of the vanilla Cosmos SDK functionality |
| 10 | +shared among chains developed using it. Therefore, |
| 11 | +a wallet already supporting chains built using |
| 12 | +Cosmos SDK should find it straightforward to add |
| 13 | +Babylon Genesis as a supported blockchain. |
| 14 | + |
| 15 | +In this document, we will walk through the considerations of integrating |
| 16 | +the Babylon Genesis blockchain into your wallet: |
| 17 | +* [Babylon Genesis network information](#babylon-genesis-network-information) |
| 18 | +* [Accounts, message signing, token balance, and token transfer](#accounts-message-signing-token-balance-and-token-transfer) |
| 19 | +* [Staking](#staking) |
| 20 | +* [Unbonding](#unbonding) |
| 21 | + |
| 22 | +### Babylon Genesis Network Information |
| 23 | + |
| 24 | +Following is a list of the key network details of |
| 25 | +Babylon Genesis: |
| 26 | +* RPC nodes can be found for the network you are interested in |
| 27 | + [our networks registry](https://github.com/babylonlabs-io/networks). |
| 28 | +* Token minimum denomination: `ubbn` (6 decimals) |
| 29 | +* Human-readable denomination: `BABY` |
| 30 | + |
| 31 | +### Accounts, message signing, token balance, and token transfer |
| 32 | + |
| 33 | +The Babylon Genesis chain utilises the default Cosmos SDK |
| 34 | +functionality for accounts, message signing, |
| 35 | +token balance, and token transfer. |
| 36 | +Please refer to the relevant |
| 37 | +[Cosmos SDK documentation](https://docs.cosmos.network/) |
| 38 | +for more details. |
| 39 | + |
| 40 | +### Staking |
| 41 | + |
| 42 | +The Babylon blockchain uses an epochised staking |
| 43 | +mechanism where staking transactions are executed |
| 44 | +at the end of an epoch rather than immediately. |
| 45 | + |
| 46 | +* An epoch is defined as a specific block range, |
| 47 | + determined by an epoch interval defined |
| 48 | + in the `x/epoching` module's |
| 49 | + [parameters](https://github.com/babylonlabs-io/babylon/blob/release/v1.x/proto/babylon/epoching/v1/params.proto). |
| 50 | +* During each epoch, staking messages are queued |
| 51 | + in a delayed execution queue. |
| 52 | +* At the epoch's end, all queued staking messages |
| 53 | + are processed in a batch, resulting in |
| 54 | + epoch based voting power transitions. |
| 55 | + |
| 56 | +To enable this mechanism, |
| 57 | +Babylon modifies the standard Cosmos SDK staking process: |
| 58 | +* Babylon replaces the default Cosmos SDK `x/staking` module |
| 59 | + with a custom module, `x/epoching`. |
| 60 | +* This custom module wraps the standard staking functionality |
| 61 | + to enforce epoch-based voting power transitions. |
| 62 | +* The wrapped staking messages are largely similar |
| 63 | + to those in the default `x/staking` module. |
| 64 | + The specifications of these wrapped messages are available |
| 65 | + [here](https://github.com/babylonlabs-io/babylon/tree/main/x/epoching). |
| 66 | + |
| 67 | +Wallets wishing to support Babylon PoS delegations |
| 68 | +natively must use the custom `x/epoching` mechanism. |
| 69 | + |
| 70 | +The epochised staking approach introduces the following |
| 71 | +UX considerations for wallet integration: |
| 72 | +* **Delayed Staking Activation**: Although wrapped staking messages are |
| 73 | + executed immediately, the actual staking operation takes effect only |
| 74 | + at the epoch's end. Wallets should clearly communicate this |
| 75 | + delay to users to set proper expectations. |
| 76 | +* **Delayed Funds Locking**: Users' funds remain liquid until staking |
| 77 | + activation occurs at the epoch's conclusion. This creates a for staking failure: |
| 78 | + if users transfer or spend their funds before staking takes effect, |
| 79 | + the staking transaction will fail. |
| 80 | + Wallets should warn users about this possibility. |
| 81 | + |
| 82 | +Wallets can provide users with visibility into pending staking |
| 83 | +messages using the |
| 84 | +[LastEpochMsgs query in x/epoching](https://github.com/babylonlabs-io/babylon/blob/main/proto/babylon/epoching/v1/query.proto#L46). |
| 85 | +This query allows wallets to display the messages queued |
| 86 | +for execution at the end of the current epoch. |
| 87 | + |
| 88 | +### Unbonding |
| 89 | + |
| 90 | +Babylon speeds up the unbonding process by leveraging |
| 91 | +Bitcoin timestamping, significantly reducing |
| 92 | +the unbonding period from the default 21 days in the |
| 93 | +Cosmos SDK to approximately ~50 hours. |
| 94 | + |
| 95 | +This process works as follows: |
| 96 | +* **Epoch Timestamping**: At the end of each epoch, |
| 97 | + Babylon records its blockchain state onto the |
| 98 | + Bitcoin blockchain through a Bitcoin timestamp. |
| 99 | +* **Bitcoin Confirmations**: Once the timestamp receives |
| 100 | + a sufficient number of confirmations on the Bitcoin blockchain |
| 101 | + (a parameter configurable in Babylon), the state of the epoch |
| 102 | + if considered finalized. |
| 103 | + * The number of required Bitcoin confirmations is set by the |
| 104 | + `x/btccheckpoint` module, detailed |
| 105 | + [here](https://github.com/babylonlabs-io/babylon/blob/main/proto/babylon/btccheckpoint/v1/params.proto#L24) |
| 106 | + * For example, on the Babylon Genesis mainnet, |
| 107 | + this value will be set to 300 confirmations, |
| 108 | + corresponding to roughly ~33 hours for unbonding to be completed, |
| 109 | + assuming an average Bitcoin block time of 10 minutes. |
| 110 | +* **Unbonding Finalization**: All unbonding requests submitted |
| 111 | + up to the end of that epoch are processed and finalized |
| 112 | + after the required Bitcoin confirmations are reached. |
| 113 | + |
| 114 | +An example scenario demonstrating how fast unbonding |
| 115 | +works in practice: |
| 116 | +* **Setup** |
| 117 | + * Epoch interval: 300 blocks |
| 118 | + * Bitcoin confirmations for finalization: 300 blocks |
| 119 | +* **Unbonding Request**: |
| 120 | + * A user submits an unbonding transaction at block `157` |
| 121 | +* **Epoch Processing**: |
| 122 | + * The unbonding transaction is queued and processed at |
| 123 | + the end of the epoch (block 300). |
| 124 | + * The user’s status is updated to unbonding, and the epoch’s |
| 125 | + state is timestamped on Bitcoin. |
| 126 | +* **Finalization**: |
| 127 | + * After ~50 hours, the Bitcoin timestamp reaches 300 confirmations. |
| 128 | + * Babylon Genesis detects this and completes the unbonding process, |
| 129 | + fully unbonds the user’s stake. |
0 commit comments