Bitcoin Thunderbolt is an open source protocol for asynchronous off-chain transfers of Bitcoin UTXO ownership. A Bitcoin UTXO is locked once under a fixed public key shared by its current Holder and a Threshold Committee. Ownership can then move between Holders without an on-chain transaction for every transfer.
Thunderbolt lets the sender and recipient complete a transfer at different times.
The project is maintained by Nubit.
v1.0.0 is the first stable open source release. It brings together the protocol libraries, durable role services, Ledger and rollback-floor applications, Bitcoin and CometBFT integrations, operator tooling, and reproducible release assets.
| Role | Responsibility |
|---|---|
| Holder | Controls the current ownership secret, creates transfers, and can request final settlement. |
| Recipient | Creates an invoice with a fresh secret and becomes the next Holder after a valid transfer and committee update. |
| Committee member | Holds one share of the fixed lock key, verifies committed transfers, updates its share, and participates in settlement. |
| Thunderbolt Ledger | Orders authenticated protocol entries, persists channel state, and makes committed entries available to participants. Participant secrets remain with Holders and committee members. |
| Bitcoin Core | Provides funding, confirmation, reorganization, and settlement data for the Bitcoin UTXO. |
Each Holder, committee member, and Ledger validator runs as a separate process with its own state and credentials. A thin local CLI talks to the daemon through an owner-only Unix socket.
Bitcoin Core
|
|
Holder daemon <----> Thunderbolt Ledger <----> Committee daemons
| CometBFT |
| |
encrypted vault encrypted share vaults
| |
+---------- externally anchored rollback floor --+
The Ledger application is deterministic and runs behind CometBFT. Clients verify finality before issuing capabilities to Holder or committee code. Participant state is encrypted locally and fenced by an independently anchored rollback floor. Administrative control stays on a local Unix socket and is separate from protocol traffic.
The protocol lifecycle is:
- Open a channel by funding a Taproot UTXO under the combined Holder and committee key.
- The Recipient publishes an invoice with a fresh public delta and encrypted refresh material.
- The current Holder verifies the invoice and publishes the transfer.
- Committee members verify the committed entries and update their shares.
- The Recipient decrypts the new credential and becomes the Holder.
- The current Holder and a committee quorum can finalize the channel on Bitcoin.
Steps 2 through 5 repeat off-chain.
| Component | Purpose |
|---|---|
thunderboltd |
Role-aware daemon and local operator control plane |
thunderbolt-cli |
Local operator client |
thunderbolt-holder-node |
Durable Holder service, outbox, and Ledger cursor |
thunderbolt-committee-node |
Durable committee service and compact finalized evidence |
thunderbolt-ledger-app |
Crash-safe Ledger application and request index |
thunderbolt-ledger-abci |
ABCI adapter for the Ledger application |
thunderbolt-abci-server |
Bounded local ABCI server for CometBFT |
thunderbolt-cometbft-* |
Authenticated RPC, light-client finality, and durable coordination |
thunderbolt-floor-* |
Signed rollback-floor application, proofs, and ABCI integration |
thunderbolt-runtime-config |
Strict role configuration and deployment identity checks |
thunderbolt-keystore |
Encrypted participant records and crash-safe state transitions |
thunderbolt-bitcoin |
Bitcoin Core RPC, chain tracking, funding, and settlement validation |
thunderbolt-core, thunderbolt-protocol, thunderbolt-wire |
Cryptography, state transitions, and bounded public messages |
research/ |
Paper benchmarks and reproducibility artifacts |
The repository pins its Rust toolchain in rust-toolchain.
cargo build --locked --release
cargo test --workspace --all-features --locked --lib --bins --testsBuild only the operator binaries with:
cargo build --locked --release \
--package thunderboltd \
--package thunderbolt-cliThunderbolt uses one owner-only TOML configuration per process. Examples for the Ledger, Holder, and committee roles are in crates/thunderbolt-runtime-config/examples. Replace the example paths and public manifest hashes with the files provisioned for your deployment.
Validate the configuration before starting:
thunderboltd --config /var/lib/thunderbolt/runtime.toml check
thunderboltd --config /var/lib/thunderbolt/runtime.toml startUse the local CLI from the same operating-system account:
thunderbolt-cli --config /var/lib/thunderbolt/runtime.toml status
thunderbolt-cli --config /var/lib/thunderbolt/runtime.toml blockers
thunderbolt-cli --config /var/lib/thunderbolt/runtime.toml redacted-config
thunderbolt-cli --config /var/lib/thunderbolt/runtime.toml drain
thunderbolt-cli --config /var/lib/thunderbolt/runtime.toml stopSee the operator guide for provisioning, process supervision, recovery, and regtest instructions.
Please report vulnerabilities through GitHub private vulnerability reporting. Do not open a public issue for a security report. See SECURITY.md for scope and response details.
| Document | Purpose |
|---|---|
| Architecture | Roles, processes, data flow, and trust boundaries |
| Operator guide | Setup, operation, recovery, and monitoring |
| Configuration | Configuration schema and deployment checks |
| API | Local control and protocol interfaces |
| Security | Operational security controls |
| Threat model | Assets, adversaries, assumptions, and guarantees |
| Testing | Automated and live integration tests |
| Release process | Release construction and verification |
| Roadmap | Remaining work toward mainnet activation |
| Research artifacts | Paper benchmark reproduction |
Read CONTRIBUTING.md, GOVERNANCE.md, and the Code of Conduct before opening a pull request. Protocol, cryptography, persistence, and signing changes need tests for invalid inputs as well as the expected flow.
Bitcoin Thunderbolt is licensed under the Apache License 2.0. See NOTICE for project and third-party attributions.
If you use Bitcoin Thunderbolt in academic work, please cite the protocol paper:
@inproceedings{wen2026thunderbolt,
author = {Hongbo Wen and Hanzhi Liu and Yanju Chen and Jingyu Ke and Dahlia Malkhi and Yu Feng},
title = {Thunderbolt: Fast Asynchronous Off-Chain Bitcoin Transfers},
booktitle = {Proceedings of the 2026 ACM Conference on Computer and Communications Security},
year = {2026}
}