ColliderVM

Executable Rust prototype for exploring stateful computation on Bitcoin with presigned Taproot flows and hash-prefix collision puzzles.

ColliderVM is a research prototype inspired by the ColliderVM paper. It turns the core idea into runnable code: find a nonce for an input x, select a presigned flow d = H(x || r)|_B, then spend through Taproot scripts that verify the same hash-prefix commitment while checking a split toy computation.

This repository is intentionally narrow. It is useful for understanding, testing, and extending the protocol mechanics. It is not a bridge, not a production ColliderVM implementation, and not mainnet-ready wallet software.

What It Demonstrates

• Taproot script construction for a two-step toy program: F1(x) = x > 100 and F2(x) = x < 200.
• BLAKE3-in-Bitcoin-Script hash-prefix checks through BitVM script fragments.
• Witness construction that carries x || r into both script steps.
• MuSig2 aggregate signing simulation for signer-controlled flows.
• Regtest transaction generation for funding -> F1 -> F2 -> final spend.
• Script dry-run tests for valid and invalid input consistency.

Protocol Shape

input x
  |
  v
find nonce r such that H(x || r)|_B lands in D
  |
  v
select flow d
  |
  v
funding tx -> F1 Taproot leaf -> F2 Taproot leaf -> receiver spend
              checks x > 100      checks x < 200
              checks prefix d     checks prefix d

The demo uses small parameters so it runs locally:

Parameter	Demo value	Meaning
L	4	Flow set size is 2^L = 16
B	16	Hash prefix size checked by the scripts
Expected honest work	2^(B-L) = 4096 hashes	Average nonce search cost
Valid input range	100 < x < 200	Both toy subfunctions pass

For a fuller protocol explanation, see docs/collider_explainer.md.

Quickstart

Requirements:

• Rust nightly. The repo pins this through rust-toolchain.toml.
• Docker, only for the regtest Bitcoin demo.

Build and test the core crate:

cargo test

Run the regtest demo:

docker compose -f scripts/demo/docker-compose.yml up -d

docker exec bitcoind-regtest \
  bitcoin-cli -regtest -rpcuser=user -rpcpassword=PaSsWoRd -rpcwallet=alice \
  walletpassphrase alicePsWd 600

cargo run --bin demo -- --x 114

The demo writes raw transaction hex and a JSON summary under target/demo/:

target/demo/f1.tx
target/demo/f2.tx
target/demo/spending.tx
target/demo/demo.json

Stop the local node when finished:

docker compose -f scripts/demo/docker-compose.yml down

CLI

Selected demo options:

Usage: demo [OPTIONS]

Options:
  -x, --x <X>                        Input value x (checked by F1 > 100 and F2 < 200) [default: 114]
      --fee-rate <FEE_RATE>          Fee-rate in sat/vB [default: 1]
      --output-dir <OUTPUT_DIR>      Output directory [default: target/demo]
      --output-file <OUTPUT_FILE>    JSON output file [default: demo.json]
      --receiver <RECEIVER>          Receiver address
  -n, --network <NETWORK>            Network name [default: regtest]
  -r, --rpc-url <RPC_URL>            Bitcoin Core RPC URL [default: http://127.0.0.1:18443]
      --rpc-user <RPC_USER>          RPC user [default: user]
      --rpc-password <RPC_PASSWORD>  RPC password [default: PaSsWoRd]
      --wallet-name <WALLET_NAME>    Bitcoin wallet name [default: alice]
  -h, --help                         Print help
  -V, --version                      Print version

Run cargo run --bin demo -- --help for the full generated help text.

There is also an experimental Alephium PoW script sandbox:

cargo run --bin mine-pow-alephium -- --difficulty 1

Repository Map

Path	Purpose
src/core.rs	Nonce search, flow-prefix helpers, BLAKE3 script builders, F1/F2 Taproot script logic
src/transactions.rs	Funding, F1, F2, and final-spend transaction construction and witness finalization
src/musig2.rs	Local MuSig2 key aggregation and signature simulation
src/bin/demo.rs	Regtest/Signet-style end-to-end demo binary
src/bin/mine-pow-alephium.rs	Experimental BLAKE3 PoW script sandbox
scripts/demo	Dockerized Bitcoin Core regtest environment
docs/collider_explainer.md	Longer protocol notes and tradeoffs

Current Boundaries

This repo is a toy implementation with real transaction and script machinery, but deliberately small protocol parameters. Important limitations:

• It does not implement a production ColliderVM bridge or STARK verifier.
• It does not generate or store a realistic 2^L production flow set.
• It uses simplified fee and UTXO handling for the demo path.
• The signing flow is simulated locally, not a hardened multi-party ceremony.
• The code has not been audited and must not be used with mainnet funds.

These constraints are part of the design: the repo is optimized for protocol inspection and local experimentation.

Validation

The CI gates mirror the commands contributors should run locally:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

The demo workflow also runs the binary against a Dockerized Bitcoin regtest node.

Contributing

Useful contributions are concrete and testable: script correctness, witness construction, transaction handling, parameterization, demo reliability, and clear protocol documentation. Please include the validation commands you ran with each change.

References

• ColliderVM: Stateful Computation on Bitcoin
• BitVM
• Bitcoin Core regtest

License

Licensed under the MIT License.

Contributors

Thanks to the people who have contributed code, documentation, and protocol feedback.

A₿del ∞/21M 💻 📖 🤔

Stephen 💻

Phạm Xuân Trung 💻

Maciej Kamiński @ StarkWare 💻

This project follows the all-contributors specification.