Assessment reportsPublic findings
Back to Zellic site
↗
Assessment reports>Babylon Genesis Chain>Design>Module: btclightclient
GeneralOverview
Findings
Critical (10)
High (4)
Medium (4)
Low (7)
Informational (7)
DiscussionBabylon node module-wise reviewed parametersDependency management and vulnerability assessmentPanic handling in ABCI++ handlersBehavior of MissedBlocksCounter on consecutive windows
DesignModule: btclightclientModule: btccheckpointModule: checkpointingModule: epochingModule: finalityModule: incentiveModule: monitorModule: mintModule: btcstakingbtc-stakerstaking-expiry-checkerbtc-staking-tsVigilante reporterVigilante submitterVigilante monitor (BTC timestamping monitor)Vigilante BTC staking trackerCryptographyFinality providerCovenant emulatorModule: staking-queue-clientstaking-api-servicebabylon-staking-indexersimple-staking
Audit ResultsAssessment Results
AddendumAddendumNonce reuse in adaptor signatures allows recovering signing key testsKey recovery succeeding on output from a btc-delegations query test

Module: btclightclient

Description

The btclightclient module is essentially a BTC light client that maintains the canonical header chain of Bitcoin.

The BTC canonical headers stored in the btclightclient module are referenced in the following scenarios:

  1. The first is when the BTC timestamping protocol records a checkpoint on the BTC network and reports it to the Babylon chain. To ensure security, each checkpoint must be reported along with the inclusion proof that verifies the BTC transaction executing the checkpoint. The btclightclient module is referenced to determine the validity of the inclusion proof at that point in time.

  1. For BTC staking, users prove that a staking transaction was executed on the BTC network to receive equivalent value on the Babylon chain. Similar to the first scenario, an inclusion proof is required to validate the staking transaction, and the btclightclient module is used to verify the inclusion proof.

Additionally, to ensure that the stored block headers belong to the canonical chain and not a fork chain, the chain with the highest total difficulty is recognized as the main chain.

If a fork chain with higher total difficulty (i.e., a better fork) is discovered, the chain is rolled back to the common ancestor block. The newly received fork block headers are then stored in the state.

Messages

MsgInsertHeaders

This message is processed by the btclightclient module and is used to update the state of the BTC chain that the Babylon chain references.

When a Babylon node receives BTC headers, it checks the following conditions:

  • The message executor is an authorized reporter. (Permissionless execution may be allowed depending on the module parameters.)

  • The headers list must not be empty.

  • The headers in the list must be connected by parent-child relationships. That is, the PrevBlock field of the header at position i + 1 must point to the hash of the header at position i.

  • The first header in the list must reference a header already stored in the BTC light client module.

  • Each header must be correctly encoded.

  • Each header must have a valid proof of work and difficulty.

  • Each header must have a Timestamp greater than the median of the previous 11 ancestor blocks.

  • If the first header in the list does not point to the current tip of the chain maintained by the BTC light client, the message indicates the presence of a fork. For the fork to be valid, the forked chain must be better than the current chain. A better fork is defined as a chain with a total work greater than the total work of the current chain.

Additionally, if the message is successfully executed, the user will receive a refund for all gas consumed during its execution.

MsgUpdateParams

This message is used to update the parameters of the btclightclient module and can only be executed through a governance proposal.

Test coverage

The x/btclightclient package has low test coverage (12.1%), while the keeper module is well-tested (75.2%), and the types module remains mostly untested (2.7%).

ok      github.com/babylonlabs-io/babylon/x/btclightclient      1.853s  coverage: 12.1% of statements
ok      github.com/babylonlabs-io/babylon/x/btclightclient/keeper       3.025s  coverage: 75.2% of statements
ok      github.com/babylonlabs-io/babylon/x/btclightclient/types        2.231s  coverage: 2.7% of statements

Attack surface

There is only one message in the btclightclient. This is the largest exposed attack surface, though it is permissioned as only vigilantes (vigilante reporters) can submit the message MsgInsertHeaders in testnet. But in the future, it may be executed permissionlessly depending on the decision of the Babylon team. The possible consequences of malicious vigilantes that were checked were that invalid BTC headers cannot be sent. Any headers that can cause a fork due to a block being mined earlier than expected, despite the predefined difficulty, and subsequently being considered the principal chain is problematic. Other situations such as DOS due to the refund mechanisms of the messages is also important to consider. Any situation that could cause a block to be missed is also a critical issue (consider, for example, multiple reorgs).

Zellic © 2025Back to top ↑