LayerTree

A Bitcoin scaling construction: one UTXO holds the pooled balances of many participants, an off-chain Merkle-sum tree commits to ownership, and covenants (Great Script Restoration + OP_TX + OP_CHECKSIGFROMSTACK + EC opcodes) enforce every state transition. Any participant can exit, and the operator can evict any expired participant, in one transaction whose size is independent of the number of participants. Two tree profiles are specified: a dense operator-allocated tree, which is the default, and a key-addressed sparse Merkle-sum tree with compressed proofs, kept as the measured alternative. LayerTree proposes no opcodes of its own; it composes the existing candidates listed in spec section 4.3, and the test suite fails if a script uses anything else.

Contents

Path	What
spec/layertree.md	The specification (RFC 2119 language)
CONCEPTS.md	End-to-end guide for engineers: the data model, the transitions, a member's life, payments and Lightning, trust, costs, opcode tiers, verification and a map of the code. Start here.
site/	Interactive explainer website: a step-through of a tree's life, then one page per component (the state machine, joining, exiting, payments, swaps, eviction, batching, opcode tiers) with its own animation; static HTML, CSS and SVG, no build step
spec/channel-leaves.md	Appendix C: payment channels hosted in leaves (rebindable OP_TX + CSFS commitments, LN-Symmetry state machine, HTLC routing)
spec/fee-analysis.md	Exit and eviction costs at fee rates from 1 to 250 sat/vB
spec/test-vectors.json	Generated test vectors
spec/scripts/	Annotated script listings and the measured size table
paper/	LaTeX paper (LNCS format): ideal functionality, abstract protocol, opcode tiers, UC security theorem with Lean-cited lemmas, channel composition, measurements; paper/main.pdf is the built copy, stamped with its git revision
formal/	Lean 4 formalisation of the tree and covenant rules: conservation, proof soundness, payability, encodings (core library only, lake build)
design/review.md	Scrutiny of the original sketch and the resulting design decisions
design/cost-comparison.md	Where LayerTree wins and where it does not: exit, entry and lifetime bytes against bare UTXOs, Lightning and transaction trees, with generated figures
design/tree-comparison.md	Dense or sparse: what the two profiles share, where the sparse bytes go, and what a higher radix would change, with a measured radix-4 level
design/batching.md	Batching: what a batch costs, the owner multiproof, the cohort rewrite and detaching a subtree into its own output
design/graft.md	Grafting: what JOIN_h checks and what it does not, who has to trust whom, funding modes and their cost per member, and a 256-member worked example
design/native-opcodes.md	The CCV tier and a hypothetical OP_MERKLESUMUPDATE: what a native Merkle-sum state-machine opcode would buy, measured in the simulator only and never part of a tier
design/receive.md	Receiving over Lightning into a tree: cumulative hash-locked vouchers against an Ark client's out-of-round payments and credits
design/unified-batching.md	The essay in which LayerTree was first described
design/layertree.md	Raw design sketch (verbatim)
notes.md	Notes distilled from the working vault
brain.md	Running brain dump: where every piece stands, what is in flight, what is next
tools/	Reference implementation, script templates, simulator, tests

Go implementation

The module github.com/roasbeef/layertree (this repository) implements the specification in Go on top of btcsuite/btcd, lightningnetwork/lnd and lightninglabs/taproot-assets:

Package	Contents
tree	leaves, merkle-sum tree, paths, proof compression, taproot binding of roots to the tree output
script	transition script generators for the FULL, MID, MIN and CCV opcode tiers, byte-checked against spec/golden.json
txn	transaction construction, witness assembly, BIP-341 sighash and Schnorr signing
msg	TLV-encoded off-chain messages: compressed proofs, vouchers, join offers

go build ./... && go test ./...

The Python tools remain the executable reference because they include a simulator for the candidate opcodes; the Go code is cross-checked against vectors the Python emits (spec/test-vectors.json, spec/golden.json).

Running the reference code

python3 tools/layertree_ref.py     # regenerate spec/test-vectors.json
python3 tools/test_scripts.py      # execute all scripts, both profiles
python3 tools/test_mid.py          # MID tier (0xC0 numerics), both profiles
python3 tools/test_min.py          # MIN tier EXIT_1 and SPLIT with sighash grinding
python3 tools/gen_listings.py      # regenerate spec/scripts/
python3 tools/gen_structured.py    # regenerate spec/scripts/structured/ (macro-collapsed)
python3 tools/gen_golden.py        # regenerate spec/golden.json for the Go tests

No dependencies beyond the Python 3 standard library.

Paper

paper/main.tex is a conference-style write-up in Springer LNCS format (the Financial Cryptography template) using cryptocode, tikz and pgfplots. It presents the system interface first: the ideal functionality (section 3), the abstract protocol and its covenant predicates (4), the four opcode tiers as realisations (5), a UC security theorem whose lemmas cite the Lean theorems inline (6, proof in Appendix A), and channel leaves as a composition result (7). Build with cd paper && make, which stamps the PDF with the git revision it was built from (paper/version.tex, shown under the author name and in the running footer); it needs a TeX Live with llncs (bundled in the directory), cryptocode, pgfplots and the cm-super fonts. Every number in the paper is taken from spec/scripts/sizes.md and spec/fee-analysis.md.

Formal model

formal/ is a Lean 4 development (no Mathlib) that proves the security argument of spec section 10.2 for the abstract transition rules: every accepted transition conserves the tree sum, only removes leaves that are really there, and every leaf holder can always build an accepted exit. formal/README.md lists the theorems, the hash assumptions and what is deliberately left to the executable tests.

cd formal && lake build

Consensus dependencies

• BIP-0440 — varops budget
• BIP-0441 — restoration of disabled script (tapleaf 0xC2)
• OP_TX and "New Opcodes for Tapscript v2" drafts — introspection, OP_CHECKSIGFROMSTACK, OP_ECSCALARMUL, OP_ECPOINTADD
• BIP-0348 — OP_CHECKSIGFROMSTACK
• BIP-0449 — OP_TWEAKADD (used by the MID and MIN tiers in place of the EC point opcodes, spec 4.4 and 4.5; FULL and CCV do not need it)
• Elliptic Curve Operations for Bitcoin Script (draft, PR bitcoin/bips#1945) — OP_EC_POINT_ADD, OP_EC_POINT_MUL, OP_EC_POINT_NEGATE, OP_EC_POINT_X_COORD