Babylon allows Bitcoin holders to participate in staking, earning rewards while maintaining their BTC holdings.
This guide walks through the process of staking Bitcoin using the Adamik API, including transaction creation, signing, and broadcasting.
The duration of a Bitcoin staking position is 64000 blocks (~444 days). It will naturally end after this period.
However the Babylon protocol also allows to manually end the staking position in advance (see part III - Unstake Bitcoins).
Babylon offers two registration methods: pre-stake and post-stake. This guide implements the more user-friendly pre-stake registration flow. Refer to Babylon’s documentation for details.
The examples are targeting Bitcoin Signet and Babylon Testnet networks. To target the mainnets, simply replace "bitcoin-signet" with "bitcoin" and "babylon-testnet" with "babylon" in API calls.
The example data shown is for demonstration purposes. While encoded payloads are valid for signing, they may not match the provided examples exactly.
Generate the Bitcoin transaction payloads to sign, using transaction mode stake:
POST /api/bitcoin-signet/transaction/encode{"transaction":{"data":{"mode":"stake","senderAddress":"tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx","senderPubKey":"02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c","targetValidatorAddress":"ee9da95e9fecbb2191943c56a109d1dc81787a77994ad9ef89278850a58e4876","amount":"1000"}}}
POST /api/babylon/transaction/encode{"transaction":{"data":{"mode":"registerStake",// User's Babylon address"senderAddress":"xxxxxxxxxxxxxxxxxx",// User's Babylon public key"senderPubKey":"xxxxxxxxxxxxxxxxxx",// User's Bitcoin public key in hexadecimal format"senderForeignPubKey":"xxxxxxxxxxxxxxxxxx",// User's Babylon address, signed with Bitcoin signer (hex)"proofOfPossession":"xxxxxxxxxxxxxxxxxx","amount":"1234",// Bitcoin finality provider's public key (hex)"validatorPubKey":"xxxxxxxxxxxxxxxxxx",// The unbonding PSBT, exactly as provided in the response of the Bitcoin encode"unsignedUnbondingTransaction":"xxxxxxxxxxxxxxxxxx",// Staking transaction, signed from the provided PSBT (hex)"signedStakingTransaction":"xxxxxxxxxxxxxxxxxx",// Slashing transaction, signed from the provided PSBT (hex)"signedSlashingTransaction":"xxxxxxxxxxxxxxxxxx",// Unbonding slashing transaction, signed from the provided PSBT (hex)"signedUnbondingSlashingTransaction":"xxxxxxxxxxxxxxxxxx"}}}
ℹ️ The returned encoded transaction is in Cosmos’ protobuf format, serialized as hex.
POST /api/babylon/transaction/broadcast{"transaction":{"data":{"mode":"registerStake","senderAddress":"xxxxxxxxxxxxxxxxxx","senderPubKey":"xxxxxxxxxxxxxxxxxx","senderForeignPubKey":"xxxxxxxxxxxxxxxxxx","proofOfPossession":"xxxxxxxxxxxxxxxxxx","amount":"1234","validatorPubKey":"xxxxxxxxxxxxxxxxxx","unsignedUnbondingTransaction":"xxxxxxxxxxxxxxxxxx","signedStakingTransaction":"xxxxxxxxxxxxxxxxxx","signedSlashingTransaction":"xxxxxxxxxxxxxxxxxx","signedUnbondingSlashingTransaction":"xxxxxxxxxxxxxxxxxx","fees":"12432","gas":"1775858"},"encoded":"0a330a310a2d2f626162796c6f6e2e6274637374616b696e672e76312e4d736743726561746542544344656c65676174696f6e120012650a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2103833d5aebe72ca68e3816c4a466d395280929f07ccf5e75dc4e2d71c2c92da45812040a020801180712110a0b0a047562626e120337303010a08d061a0a62626e2d746573742d3520eac404","signature":"xxxxxxxxxxxxxxxxxx"}}
Once the Babylon registration is confirmed, broadcast the signed Bitcoin staking transaction:
POST /api/bitcoin-signet/transaction/broadcast{"transaction":{"data":{"mode":"stake","senderAddress":"tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx","senderPubKey":"02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c","targetValidatorAddress":"ee9da95e9fecbb2191943c56a109d1dc81787a77994ad9ef89278850a58e4876","amount":"1000","fees":"1896"},"encoded":"70736274ff010089020000000144a549ead63ac9c6987b90669208ece5e93f28de4b1f97b5e4036c995f47b3d50100000000ffffffff0250c3000000000000225120a80fe5278c52cab2e0a0c9702713f61fe8f2f248346a6d7dcc1245338c14ec1609dd06000000000022512074aa0a4aeefc052d0e63edda5a5f9cd4a9a6b245fad33ea29408c130e2916041000000000001012b31a507000000000022512074aa0a4aeefc052d0e63edda5a5f9cd4a9a6b245fad33ea29408c130e2916041011720bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c000000","signature":"xxxxxxxxxxxxxxxxxx"}}
The Babylon protocol allows to end an active Bitcoin staking position in advance, i.e before the end of the default staking period of 64000 blocks.
This is done by sending a dedicated bitcoin transaction, that is a request for unbonding, after which there is an unbonding period of 7 days.
When the unbonding duration is complete, users must then send a withdrawal transaction to retrieve their bitcoins and make them spendable again (see part IV - Withdraw Bitcoins).
Generate the Bitcoin transaction payload to sign, using transaction mode unstake:
POST /api/bitcoin-signet/transaction/encode{"transaction":{"data":{"mode":"unstake","senderAddress":"tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx","senderPubKey":"02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c","validatorAddress":"d23c2c25e1fcf8fd1c21b9a402c19e2e309e531e45e92fb1e9805b6056b0cc76","stakeId":"52bfb146f0f8c8b98b0fa584056dfb75658b078aac04f3c5a641db9df297387b"}}}
POST /api/bitcoin-signet/transaction/broadcast{"transaction":{"data":{"mode":"unstake","senderAddress":"tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx","senderPubKey":"02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c","validatorAddress":"d23c2c25e1fcf8fd1c21b9a402c19e2e309e531e45e92fb1e9805b6056b0cc76","stakeId":"52bfb146f0f8c8b98b0fa584056dfb75658b078aac04f3c5a641db9df297387b","useMaxAmount":false,"recipientAddress":"","fees":"2000"},"encoded":"70736274ff01005e02000000017b3897f29ddb41a6c5f304ac8a078b6575fb6d0584a50f8bb9c8f8f046b1bf520000000000ffffffff0180bb000000000000225120925f6e5d2f54928dbbf7c7b989e2d0e8b6023baece6b7ae6efed0c4f54891999000000000001012b50c3000000000000225120a80fe5278c52cab2e0a0c9702713f61fe8f2f248346a6d7dcc1245338c14ec166215c050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac08b47c4bf56db05be7cc5f84b03d14987e05392d76b88d6875136d66d34db31d697cb47898d4200f9dbfb360a7dc2402178e9acd31f8c1167ae9afec71b8c34b4fd570120bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499cad200aee0509b16db71c999238a4827db945526859b13c95487ab46725357c9a9f25ac20113c3a32a9d320b72190a04a020a0db3976ef36972673258e9a38a364f3dc3b0ba2017921cf156ccb4e73d428f996ed11b245313e37e27c978ac4d2cc21eca4672e4ba203bb93dfc8b61887d771f3630e9a63e97cbafcfcc78556a474df83a31a0ef899cba2040afaf47c4ffa56de86410d8e47baa2bb6f04b604f4ea24323737ddc3fe092dfba2079a71ffd71c503ef2e2f91bccfc8fcda7946f4653cef0d9f3dde20795ef3b9f0ba20d21faf78c6751a0d38e6bd8028b907ff07e9a869a43fc837d6b3f8dff6119a36ba20f5199efae3f28bb82476163a7e458c7ad445d9bffb0682d10d3bdb2cb41f8e8eba20fa9d882d45f4060bdb8042183828cd87544f1ea997380e586cab77d5fd698737ba569cc001172050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac00000"}}
After a staking position has ended, users have to send a withdrawal transaction before being able to spend their bitcoins again.
This transaction is mandatory whether the position has ended naturally after the default staking duration or after the manual unbonding period has eneded.
Generate the Bitcoin transaction payload to sign, using transaction mode withdraw:
POST /api/bitcoin-signet/transaction/encode{"transaction":{"data":{"mode":"withdraw","senderAddress":"tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx","senderPubKey":"02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c","recipientAddress":"tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx","validatorAddress":"d66124f8f42fd83e4c901a100ae3b5d706ef6cfd217b04bc64152e739a30c41e","stakeId":"943b38b6e1d6ffe0194f93dbfbe36499d1eaa625867aae17a59aff2825d42109"}}}
POST /api/bitcoin-signet/transaction/broadcast{"transaction":{"data":{"mode":"withdraw","senderPubKey":"02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c","validatorAddress":"d66124f8f42fd83e4c901a100ae3b5d706ef6cfd217b04bc64152e739a30c41e","stakeId":"943b38b6e1d6ffe0194f93dbfbe36499d1eaa625867aae17a59aff2825d42109","recipientAddress":"tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx","senderAddress":"tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx","fees":"159"},"encoded":"70736274ff01005e0200000001fd2f56d383b71a98d0f86780aa591f1eca05c44e581d47e1e3838b05df259a3b0000000000f003000001e1ba00000000000022512074aa0a4aeefc052d0e63edda5a5f9cd4a9a6b245fad33ea29408c130e2916041000000000001012b80bb0000000000002251206f5554b3505cbccc88c8e86541dbac87e53f962c18b953780ccde2e4d5969d3c4215c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac099c5eb18cdfad5d84d849d1aa9e883c313b19b2a89726b534534dd064587eb512720bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499cad02f003b2c001172050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac00000"}}