
bithoven v0.1.0
Type-safe, imperative programming language that compiles to native Bitcoin Script for SegWit and Taproot, with built-in cryptographic primitives, static analysis, and formal verification support.
Bithoven 🎼
Formal Safety for Expressive Bitcoin Smart Contracts
Bithoven is a high-level, imperative language for Bitcoin smart contracts. It compiles to native Bitcoin Script for legacy (P2SH), segwit (P2WSH) and taproot (P2TR) outputs. You write readable contracts with if/else, named and typed witness inputs, and built-in timelock and signature primitives, instead of juggling a stack by hand.
What sets Bithoven apart is the analysis behind the syntax. Before emitting a single opcode, the compiler rejects any contract that could reach an undefined state, break a consensus encoding rule, consume a witness item other than exactly once and in stack order, leave a path without an explicit return, or let a path succeed without a valid signature. It also rejects any contract it can prove no witness could ever redeem.
⚡ Key Features
- Imperative syntax:
if/else,verifyandreturninstead of mental stack juggling. - Typed witness inputs: each spending path declares its witness items by name and type (
number,bool,string,signature). - Signature necessity on every path: a path-sensitive analyzer proves that no spending path can succeed without a valid signature, whatever form the check takes.
- Strict types and consensus-checked literals: no arithmetic on strings or on
checksigresults; numbers, byte strings, locktimes and public keys are range- and encoding-checked at compile time. - Linear witness consumption: every declared item is consumed exactly once, in stack order, on every path.
- Targeted compilation: one source compiles for
legacy,segwitortaproot; multisig becomesOP_CHECKMULTISIGorOP_CHECKSIGADDas the target requires. - Formally specified, tested against Bitcoin Core: type soundness and a refinement theorem tie the source to the emitted script, and the compiler is differentially tested against
libbitcoinconsensus. - Low overhead: on standard Miniscript policies, emitted scripts are within a median of one byte of
rust-miniscript.
🆕 What's New in v0.1.0
v0.1.0 is a major revision of the analyzer and back end, accompanying the paper.
- Path-sensitive signature necessity. In 0.0.x, a declaration only had to contain a
signatureitem, and only the literal shape!checksig(..)was flagged. v0.1.0 decides, for every path, whether it can succeed while everychecksigfails. Rewrites that 0.0.x compiled into anyone-can-spend scripts, such aschecksig(..) == false,checksig(..) || flagor an invertedif checksig(..), are now rejected.!!checksig(..), which 0.0.x wrongly rejected, now compiles. - Dead-contract detection. A contract whose every path is provably unsatisfiable is rejected with
DeadPathinstead of compiling to an unspendable output. - Enforced well-formedness. Every
ifneeds anelse, there is exactly one stack declaration per spending path, and paths that split at a branch must agree on the witness items consumed before it. - Per-path liveness. Witness consumption is tracked per spending path, so two branches may reuse a name such as
sig; 0.0.x rejected this withVariableConsumed. - Stricter types and literals.
verify,returnandifoperands must bebool; byte strings are capped at the 520-byte push limit; key literals must use the target's encoding. - Back-end fixes. Equality over arithmetic compiles to
OP_NUMEQUAL, so an overflowing sum can no longer compare equal byte-wise, and long byte-string literals that could crash the 0.0.x compiler now compile. - Reproducible evaluation. Differential validation against Bitcoin Core, mutation analysis, the BSHunter taxonomy benchmark and a false-positive corpus ship with the repository (see
tests/README.md).
Upgrading from 0.0.x? Contracts that relied on the looser rules may stop compiling. Give every
ifanelse(NoReturn), write exactly one declaration per spending path (DeclarationPathMismatch), and use 32-byte x-only keys undertaprootor 33-byte compressed keys underlegacy/segwit(MalformedPubkey).
🚀 Quick Start
- Bithoven Web IDE, see: https://bithoven-lang.github.io/bithoven/ide/
- Bithoven Documentation, see: https://bithoven-lang.github.io/bithoven/docs/
Installation
# For CLI user
cargo install bithoven
# For rust user
cargo add bithoven
# For js user
npm install bithoven
Writing Your First Contract
Bithoven contracts are defined with a .bithoven extension. Below is an implementation of a standard Hashed Time-Locked Contract (HTLC), demonstrating how Bithoven simplifies conditional spending paths.
htlc.bithoven
pragma bithoven version 0.0.1;
pragma bithoven target segwit;
/*
* Stack input declarations: one per spending path, in the order the
* paths' returns appear below. Each lists its items in the order the path
* consumes them, so the first item (here the branch condition) is the top
* of the witness stack.
*/
(condition: bool, sig_alice: signature)
(condition: bool, preimage: string, sig_bob: signature)
{
// If 'condition' is true, we enter the Refund Path (Alice)
if condition {
// Enforce relative timelock of 1000 blocks
older 1000;
// If timelock is satisfied, Alice can spend with her signature
return checksig(sig_alice, "0245a6b3f8eeab8e88501a9a25391318dce9bf35e24c377ee82799543606bf5212");
} else {
// Redeem Path (Bob)
// Bob must reveal the secret preimage that hashes to the expected value
verify sha256(sha256(preimage)) == "53de742e2e323e3290234052a702458589c30d2c813bf9f866bef1b651c4e45f";
// If hash matches, Bob can spend with his signature
return checksig(sig_bob, "0345a6b3f8eeab8e88501a9a25391318dce9bf35e24c377ee82799543606bf5212");
}
}
🛠 Compilation
When compiled, Bithoven translates the high-level imperative logic into the equivalent Bitcoin Script opcodes, handling the control flow and stack management automatically.
Command:
bithoven compile htlc.bithoven --format asm
Without --format, the CLI writes the ASM, hex and bytes to htlc.bithoven.json; --format hex and --format json print to stdout instead.
Generated Bitcoin Script (ASM, formatted for readability):
OP_IF
<0xe803> OP_CHECKSEQUENCEVERIFY OP_DROP
<pubkey_alice> OP_CHECKSIG
OP_ELSE
OP_HASH256 OP_TOALTSTACK <hash_digest> OP_FROMALTSTACK OP_SWAP OP_EQUALVERIFY
<pubkey_bob> OP_CHECKSIG
OP_ENDIF
🛡️ What the Compiler Rejects
Every check runs at compile time, and each rejection comes with a diagnostic pointing at the offending line. This contract looks signature-gated, but its only path succeeds exactly when the signature check fails:
pragma bithoven version 0.0.1;
pragma bithoven target segwit;
(sig_alice: signature)
{
return checksig(sig_alice, "0245a6b3f8eeab8e88501a9a25391318dce9bf35e24c377ee82799543606bf5212") == false;
}
Error at line 6:5: UselessSig("A checksig is present on the top-level path but it does not gate the spend: the return at line 6:5 can succeed without a valid signature.")
The signature-necessity check reasons about what each path computes, not about how it is spelled, so equivalent rewrites get the same verdict:
Contract body (.. elides the signature and key) | Verdict |
|---|---|
return !checksig(..); | ❌ UselessSig |
return checksig(..) == false; or != true; | ❌ UselessSig |
return checksig(..) || flag; | ❌ UselessSig |
if checksig(..) { return false; } else { return true; } | ❌ UselessSig |
if flag { return true; } else { return checksig(..); } | ❌ NoSigRequired |
verify false; return checksig(..); | ❌ DeadPath |
return checksig(..) == true; or return !!checksig(..); | ✅ compiles |