Guides
API ReferenceUser docs

1. Babylon BTC staking

Suggest Edits

This step is the initial phase in the Babylon staking process. In this step, users signal their intent to delegate BTC to a specific validator by submitting a pre-registration transaction on-chain. This step ensures the validator can prepare to accept the stake and allows the protocol to track upcoming delegations.

Craft BTC Lock PSBTs

POST /btc/baby/transaction/btc-lock

{
  "btc_public_key": "03...",
  "btc_address": "bc1...",
  "amount_satoshi": "500000",
  "finality_provider_btc_pks_hex": ["ff..."],
  "time_lock": "64000",
  "fee_rate": "8"
}

{
  "unsigned_staking_psbt_hex": "73...",
  "unsigned_slashing_psbt_hex": "73...",
  "unsigned_unbonding_slashing_psbt_hex": "73...",
  "unsigned_unbonding_tx_hex": "02..."
}

Crafting the Lock Transaction:

This endpoint is used to create a Bitcoin transaction that locks the specified amount of BTC in the staking script.

The staking script enforces rules such as:

  • Time Lock: The BTC remains locked for a specified number of blocks.
  • Slashing Conditions: Ensures penalties for malicious behavior or protocol violations.

Inputs Required:

  • Bitcoin Public Key (btc_public_key): The public key of the Bitcoin wallet used for staking.
  • Bitcoin Address (btc_address): The address associated with the Bitcoin wallet.
  • Amount (amount_satoshi): The amount of BTC to lock, specified in satoshis. You can get the min and max amount in the params available at this endpoint (params) (min_staking_value_sat and max_staking_value_sat). Please check for the latest params version.
  • Finality providers (finality_provider_btc_pks_hex): Finality providers are entities responsible for ensuring the security and finality of the staking transactions. Their public keys are included in the staking script to enforce slashing conditions and validate the integrity of the staking process
  • Time Lock (time_lock): The number of blocks the BTC will remain locked. You can get the min and max lock time in the params available at this endpoint (params) (min_staking_time_blocks and max_staking_time_blocks). Please check for the latest params version.
  • Fee Rate (fee_rate): The transaction fee rate in satoshis per byte.

Output:

The endpoint returns the hex of unsigned PSBTs (Partially Signed Bitcoin Transactions) and Transaction:

  • Staking PSBT (unsigned_staking_psbt_hex): Locks the BTC in the staking script.
  • Slashing PSBT (unsigned_slashing_psbt_hex): Enforces penalties if slashing conditions are met.
  • Unbonding Slashing PSBT (unsigned_unbonding_slashing_psbt_hex): Enforces penalties if unbonding slashing conditions are met.
  • Unbonding Transaction (unsigned_unbonding_tx_hex): Unlocks the BTC after the staking period ends.

Sign these different PSBTs but do not broadcast them. They will be needed to register the stake delegation in the Babylon chain in the next step.

Craft Register Stake Transaction

The second step in Babylon BTC staking is to register the locked Bitcoin stake on the Babylon network. This registration allows the staked BTC to participate in the Babylon ecosystem and earn rewards in BABY tokens.

This transaction links the Bitcoin stake to the Babylon network by associating it with a Babylon address.

POST /btc/baby/transaction/baby-register-stake

{
  "btc_public_key": "03...",
  "btc_address": "bc1...",
  "baby_address": "bbn1...",
  "baby_public_key": "03...",
  "baby_address_proof_of_possession_hex": "ff...",
  "signed_staking_tx_hex": "02...",
  "signed_slashing_tx_hex": "02...",
  "signed_unbonding_slashing_tx_hex": "02...",
  "amount_satoshi": "500000",
  "time_lock": "64000",
  "unsigned_unbonding_tx_hex": "02..."
}

{
  "unsigned_tx_hash": "ff...",
  "fee": "12345",
  "tx_body": "ff...",
  "tx_auth_info": "ff...",
  "unsigned_tx_serialized": "ff...",
  "chain_id": "bbn",
  "account_number": "123"
}

Crafting the Register Stake Transaction

Inputs Required:

  • Bitcoin Address (btc_address): The address associated with the locked BTC.
  • Bitcoin Public Key (btc_public_key): The public key of the Bitcoin wallet used for staking.
  • Babylon Address (baby_address): The Babylon wallet address where rewards will be sent.
  • Babylon Public Key (baby_public_key): The public key of the Babylon wallet.
  • Proof of Possession (baby_address_proof_of_possession_hex): A cryptographic signature proving ownership of the Babylon address (baby_address) by the Bitcoin signer (btc_address).
    This ensures that the Babylon address is authorized for staking operations. Use ECDSA or BIP322-simple signature type. You should sign the bytes of the bech32 address. For example, using okx signing, just pass the plain text bech32 address to _signMessage_.
  • Signed Transactions: (The three PSBTs returned by btc-lock signed)
    • Staking Transaction (signed_staking_tx_hex): A signed Bitcoin transaction locking BTC in the staking script.
    • Slashing Transaction (signed_slashing_tx_hex): A signed Bitcoin transaction enforcing penalties for slashing conditions.
    • Unbonding Slashing Transaction (signed_unbonding_slashing_tx_hex): A signed Bitcoin transaction enforcing penalties during unbonding.
  • Amount (amount_satoshi): The amount of BTC locked in the staking script.
  • Time Lock (time_lock): The number of blocks the BTC will remain locked (same as btc-lock).
  • Unsigned Unbonding Transaction (unsigned_unbonding_tx_hex): The unsigned Bitcoin transaction for unbonding the staked BTC. You should pass the same

Output

  • The result of this call gives you the Babylon transaction to sign and broadcast in order to create the delegation.
    • unsigned_tx_hash: The hash of the unsigned transaction.
    • fee: The transaction fee, represented as a StdFee object. Includes the amount and gas limit.
    • tx_body: The serialized transaction body.
    • tx_auth_info: The serialized transaction authorization information.
    • unsigned_tx_serialized: The fully serialized unsigned transaction.
    • chain_id: The ID of the blockchain network (e.g., babylon-1).
    • account_number: The account number of the sender on the blockchain.

Broadcast

Updated about 18 hours ago

What’s Next