DEV Community: Aturo Phil

PSBT: Collaborative Bitcoin Transactions

Aturo Phil — Sat, 18 Jul 2026 20:08:55 +0000

Before BIP 174, coordinating a Bitcoin transaction that required multiple parties, a hardware wallet signing, a multisig cosigner approving, a coinjoin participant contributing, meant custom, incompatible formats. Every wallet implementation had its own way of passing unsigned transactions around.

Partially Signed Bitcoin Transactions (PSBT) standardized this. A PSBT is a data format that carries a Bitcoin transaction through its signing lifecycle, accumulating signatures and metadata from multiple parties until it is complete and ready to broadcast.

Understanding PSBT is essential for anyone building multisig wallets, hardware wallet integrations, coinjoin tools, or any workflow where a transaction requires coordination before broadcast.

The Problem PSBT Solves

Signing a Bitcoin transaction requires:

The unsigned transaction inputs and outputs
For each input: the UTXO being spent (to determine the value and script type)
The signing key(s) for each input
Optionally: derivation paths for HD wallet keys, redeem scripts for P2SH inputs, witness scripts for P2WSH inputs

Before PSBT, a hardware wallet asked to sign a transaction needed all of this information, but there was no standard way to package it. An offline signing device had no way to verify what it was signing without access to the full UTXO set.

PSBT solves this by:

Carrying the full UTXO for each input alongside the transaction
Carrying redeem scripts, witness scripts, and key derivation paths
Allowing partial signatures from multiple signers to accumulate in the same file
Defining a clear lifecycle: Creator → Updater → Signer → Combiner → Finalizer → Extractor

The PSBT Format

A PSBT is a binary format with a global section and per-input/per-output sections. Each section is a sequence of key-value records.

Magic bytes: 0x70736274 0xff
Global section:
  key=0x00: unsigned transaction (required)
  key=0x01: xpub entries (optional)
  key=0x03: version (optional, PSBT v2 only)
Per-input sections (one per transaction input):
  key=0x00: non-witness UTXO (full previous transaction)
  key=0x01: witness UTXO (just the output being spent)
  key=0x02: partial signature <pubkey> → <sig>
  key=0x04: redeem script
  key=0x05: witness script
  key=0x06: BIP32 derivation path <pubkey> → <fingerprint + path>
  key=0x07: finalized scriptSig
  key=0x08: finalized scriptWitness
Per-output sections (one per transaction output):
  key=0x02: BIP32 derivation path
  key=0x00: redeem script
  key=0x01: witness script

The key distinction: 0x00 (non-witness UTXO) carries the full previous transaction for legacy inputs. 0x01 (witness UTXO) carries only the specific output being spent for SegWit inputs. Hardware wallets use this to verify the amount they are signing over.

Reading a PSBT in Python:

import base64
import struct
from io import BytesIO

PSBT_MAGIC = b'psbt\xff'

def read_compact_size(stream) -> int:
    first = stream.read(1)[0]
    if first < 0xfd:
        return first
    elif first == 0xfd:
        return struct.unpack('<H', stream.read(2))[0]
    elif first == 0xfe:
        return struct.unpack('<I', stream.read(4))[0]
    else:
        return struct.unpack('<Q', stream.read(8))[0]

def read_key_value(stream) -> tuple[bytes, bytes] | None:
    key_len = read_compact_size(stream)
    if key_len == 0:
        return None  # separator
    key = stream.read(key_len)
    val_len = read_compact_size(stream)
    value = stream.read(val_len)
    return key, value

def parse_psbt(psbt_bytes: bytes) -> dict:
    stream = BytesIO(psbt_bytes)

    # Verify magic
    magic = stream.read(5)
    if magic != PSBT_MAGIC:
        raise ValueError(f"Invalid PSBT magic: {magic.hex()}")

    result = {'global': {}, 'inputs': [], 'outputs': []}

    # Parse global section
    while True:
        kv = read_key_value(stream)
        if kv is None:
            break
        key, value = kv
        key_type = key[0]
        if key_type == 0x00:
            result['global']['unsigned_tx'] = value.hex()
        elif key_type == 0x01:
            result['global'].setdefault('xpubs', {})[key[1:].hex()] = value.hex()

    # Count inputs and outputs from the unsigned tx
    # (simplified — a real parser would fully decode the tx)
    n_inputs = 2   # determined from parsing unsigned_tx
    n_outputs = 2  # determined from parsing unsigned_tx

    # Parse per-input sections
    for _ in range(n_inputs):
        input_data = {}
        while True:
            kv = read_key_value(stream)
            if kv is None:
                break
            key, value = kv
            key_type = key[0]
            if key_type == 0x00:
                input_data['non_witness_utxo'] = value.hex()
            elif key_type == 0x01:
                input_data['witness_utxo'] = value.hex()
            elif key_type == 0x02:
                pubkey = key[1:].hex()
                input_data.setdefault('partial_sigs', {})[pubkey] = value.hex()
            elif key_type == 0x04:
                input_data['redeem_script'] = value.hex()
            elif key_type == 0x05:
                input_data['witness_script'] = value.hex()
            elif key_type == 0x06:
                pubkey = key[1:].hex()
                fingerprint = value[:4].hex()
                path = '/'.join(str(struct.unpack('<I', value[i:i+4])[0] & 0x7FFFFFFF) +
                               ("'" if struct.unpack('<I', value[i:i+4])[0] & 0x80000000 else "")
                               for i in range(4, len(value), 4))
                input_data.setdefault('bip32_derivations', {})[pubkey] = {
                    'fingerprint': fingerprint,
                    'path': f"m/{path}"
                }
        result['inputs'].append(input_data)

    return result

Using the psbt library is more practical:

# python-bitcoinlib includes PSBT support
from bitcoin.psbt import PartiallySignedTransaction
import base64

def inspect_psbt(psbt_b64: str) -> None:
    psbt_bytes = base64.b64decode(psbt_b64)
    psbt = PartiallySignedTransaction.deserialize(psbt_bytes)

    print(f"Version: {psbt.version}")
    print(f"Inputs: {len(psbt.inputs)}")
    print(f"Outputs: {len(psbt.outputs)}")

    for i, inp in enumerate(psbt.inputs):
        print(f"\nInput {i}:")
        if inp.witness_utxo:
            print(f"  Value: {inp.witness_utxo.nValue} sat")
        print(f"  Signatures: {len(inp.partial_sigs)}")
        for pubkey, sig in inp.partial_sigs.items():
            print(f"  Sig from: {pubkey.hex()}")
        if inp.bip32_derivations:
            for pubkey, deriv in inp.bip32_derivations.items():
                print(f"  Key path: {deriv.fingerprint.hex()} {deriv.path}")

The PSBT Lifecycle

1. Creator: Builds the unsigned transaction and initializes the PSBT.

from bitcoin.core import CMutableTransaction, CMutableTxIn, CMutableTxOut, COutPoint
from bitcoin.psbt import PartiallySignedTransaction, PSBTInput, PSBTOutput

def create_psbt(
    utxos: list[dict],     # list of {txid, vout, value, script}
    outputs: list[dict],   # list of {address, value}
) -> str:
    # Build unsigned transaction
    inputs = [
        CMutableTxIn(COutPoint(bytes.fromhex(u['txid'])[::-1], u['vout']))
        for u in utxos
    ]
    tx_outputs = [
        CMutableTxOut(o['value'], address_to_scriptpubkey(o['address']))
        for o in outputs
    ]
    unsigned_tx = CMutableTransaction(inputs, tx_outputs)

    # Initialize PSBT
    psbt = PartiallySignedTransaction(unsigned_tx=unsigned_tx)

    # Add UTXO data for each input (witness_utxo for SegWit)
    for i, utxo in enumerate(utxos):
        psbt.inputs[i].witness_utxo = CMutableTxOut(
            utxo['value'],
            bytes.fromhex(utxo['script'])
        )

    return base64.b64encode(psbt.serialize()).decode()

2. Updater: Adds missing data — redeem scripts, witness scripts, derivation paths.

def update_psbt(psbt_b64: str, wallet_data: dict) -> str:
    psbt = PartiallySignedTransaction.deserialize(base64.b64decode(psbt_b64))

    for i, inp in enumerate(psbt.inputs):
        input_id = f"input_{i}"
        if input_id in wallet_data.get('derivations', {}):
            deriv = wallet_data['derivations'][input_id]
            pubkey = bytes.fromhex(deriv['pubkey'])
            psbt.inputs[i].bip32_derivations[pubkey] = KeyOriginInfo(
                fingerprint=bytes.fromhex(deriv['fingerprint']),
                path=parse_derivation_path(deriv['path'])
            )

        if input_id in wallet_data.get('witness_scripts', {}):
            psbt.inputs[i].witness_script = bytes.fromhex(
                wallet_data['witness_scripts'][input_id]
            )

    return base64.b64encode(psbt.serialize()).decode()

3. Signer: Examines the PSBT and adds a partial signature for inputs it can sign.

import hashlib
from coincurve import PrivateKey

def sign_psbt(psbt_b64: str, private_key_hex: str) -> str:
    psbt = PartiallySignedTransaction.deserialize(base64.b64decode(psbt_b64))
    private_key = PrivateKey(bytes.fromhex(private_key_hex))
    pubkey = private_key.public_key.format(compressed=True)

    for i, inp in enumerate(psbt.inputs):
        # Check if this key is expected to sign this input
        if pubkey not in inp.bip32_derivations:
            continue

        # Compute sighash
        if inp.witness_utxo:
            # SegWit sighash (BIP 143)
            sighash = compute_segwit_sighash(
                psbt.unsigned_tx, i, inp.witness_utxo, inp.witness_script
            )
            sighash_type = 0x01  # SIGHASH_ALL
        else:
            # Legacy sighash
            sighash = compute_legacy_sighash(
                psbt.unsigned_tx, i, inp.redeem_script
            )
            sighash_type = 0x01

        # Sign
        sig = private_key.sign(sighash, hasher=None)
        der_sig = sig + bytes([sighash_type])

        psbt.inputs[i].partial_sigs[pubkey] = der_sig

    return base64.b64encode(psbt.serialize()).decode()

4. Combiner: Merges PSBTs from multiple signers.

def combine_psbts(psbt_list: list[str]) -> str:
    """
    Merge partial signatures from multiple PSBTs.
    All PSBTs must have the same unsigned transaction.
    """
    psbts = [
        PartiallySignedTransaction.deserialize(base64.b64decode(p))
        for p in psbt_list
    ]

    base = psbts[0]

    for psbt in psbts[1:]:
        for i in range(len(base.inputs)):
            # Merge partial signatures
            base.inputs[i].partial_sigs.update(psbt.inputs[i].partial_sigs)
            # Merge any other fields the other PSBT has
            if psbt.inputs[i].witness_script and not base.inputs[i].witness_script:
                base.inputs[i].witness_script = psbt.inputs[i].witness_script

    return base64.b64encode(base.serialize()).decode()

5. Finalizer: Converts partial signatures into the final scriptSig and scriptWitness.

def finalize_psbt(psbt_b64: str) -> str:
    psbt = PartiallySignedTransaction.deserialize(base64.b64decode(psbt_b64))

    for i, inp in enumerate(psbt.inputs):
        if inp.witness_script:
            # P2WSH: build witness from partial sigs + witness script
            sigs = list(inp.partial_sigs.values())
            witness = [b''] + sigs + [inp.witness_script]  # OP_0 + sigs + script
            psbt.inputs[i].final_script_witness = witness
            psbt.inputs[i].final_script_sig = b''
        elif inp.witness_utxo:
            # P2WPKH: build witness from single sig + pubkey
            pubkey = list(inp.partial_sigs.keys())[0]
            sig = inp.partial_sigs[pubkey]
            psbt.inputs[i].final_script_witness = [sig, pubkey]
            psbt.inputs[i].final_script_sig = b''
        elif inp.redeem_script:
            # P2SH: build scriptSig from sigs + redeem script
            sigs = list(inp.partial_sigs.values())
            psbt.inputs[i].final_script_sig = build_p2sh_scriptsig(sigs, inp.redeem_script)

    return base64.b64encode(psbt.serialize()).decode()

6. Extractor: Converts the finalized PSBT into a network-ready transaction.

def extract_transaction(psbt_b64: str) -> str:
    """Extract the final, signable transaction for broadcast."""
    psbt = PartiallySignedTransaction.deserialize(base64.b64decode(psbt_b64))

    tx = psbt.unsigned_tx

    for i, inp in enumerate(psbt.inputs):
        if not inp.final_script_witness and not inp.final_script_sig:
            raise ValueError(f"Input {i} is not finalized")
        if inp.final_script_sig:
            tx.vin[i].scriptSig = inp.final_script_sig
        # witness is set separately in the transaction structure

    return tx.serialize().hex()

Real Workflow: 2-of-3 Multisig with Hardware Wallets

A practical multisig flow where two of three hardware wallets must sign:

import asyncio

async def multisig_payment(
    utxos: list,
    outputs: list,
    hw_wallet_1,
    hw_wallet_2,
    cosigner_server_url: str
) -> str:
    # Step 1: Creator builds PSBT
    psbt = create_psbt(utxos, outputs)
    print(f"Created PSBT: {psbt[:50]}...")

    # Step 2: First hardware wallet signs
    psbt_signed_1 = await hw_wallet_1.sign_psbt(psbt)
    print("Hardware wallet 1 signed")

    # Step 3: Send to cosigner server for second signature
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{cosigner_server_url}/sign",
            json={"psbt": psbt_signed_1}
        )
        psbt_signed_2 = response.json()["psbt"]
    print("Cosigner server signed")

    # Step 4: Combine signatures
    combined = combine_psbts([psbt_signed_1, psbt_signed_2])

    # Step 5: Finalize and extract
    finalized = finalize_psbt(combined)
    raw_tx = extract_transaction(finalized)

    print(f"Final transaction: {raw_tx[:50]}...")
    return raw_tx

This pattern where a PSBT is passed between parties as a base64 string, each signing their portion is the standard for multisig coordination in modern wallets.

PSBT v2 (BIP 370)

BIP 174 defined PSBT v1. BIP 370 extends it with PSBT v2, which adds:

Independent input/output modification: In v1, the full transaction must be fixed before any signing. In v2, inputs and outputs can be added incrementally, which is required for coinjoin protocols where participants add their own inputs and outputs.
Explicit version field: key=0x03 in the global section
Per-input fields: PSBT_IN_PREVIOUS_TXID, PSBT_IN_OUTPUT_INDEX, PSBT_IN_SEQUENCE, PSBT_IN_REQUIRED_TIME_LOCKTIME, PSBT_IN_REQUIRED_HEIGHT_LOCKTIME

PSBTv2 is used by coinjoin implementations and by protocols where the transaction is constructed collaboratively (e.g., LSPS1 channel purchase coordination, submarine swap protocols).

def create_psbt_v2(participants: list[dict]) -> str:
    """
    PSBTv2 for coinjoin-style construction.
    Each participant adds their own input and output.
    """
    psbt = PartiallySignedTransactionV2()
    psbt.version = 2

    for participant in participants:
        # Each adds their UTXO as an input
        psbt.add_input(
            txid=participant['txid'],
            vout=participant['vout'],
            witness_utxo=participant['utxo'],
            bip32_derivation=participant['derivation']
        )
        # Each adds their output
        psbt.add_output(
            value=participant['receive_value'],
            script=participant['receive_script']
        )

    return base64.b64encode(psbt.serialize()).decode()

Using PSBT with Bitcoin Core

# Create a PSBT via Bitcoin Core RPC
bitcoin-cli walletcreatefundedpsbt \
  '[{"txid":"...", "vout":0}]' \
  '[{"bc1q...": 0.001}]'

# Inspect a PSBT
bitcoin-cli decodepsbt "cHNidP8B..."

# Have the wallet sign it
bitcoin-cli walletprocesspsbt "cHNidP8B..."

# Finalize and extract
bitcoin-cli finalizepsbt "cHNidP8B..."

# Or combine multiple PSBTs
bitcoin-cli combinepsbt '["cHNidP8B...", "cHNidP8B..."]'

Bitcoin Core's PSBT support is complete and production-tested. If you are building server-side tooling, delegating PSBT operations to Bitcoin Core via RPC is more reliable than implementing the lifecycle yourself.

Where PSBT Is Used Today

Hardware wallets: Every major hardware wallet (Ledger, Trezor, Coldcard, Bitbox) uses PSBT as its signing interface. Coldcard was the first and remains the reference implementation for air-gapped PSBT signing.

Multisig coordinators: Sparrow Wallet, Specter, and Liana all use PSBT as the coordination format for multisig setups.

Lightning channel opens: LND and CLN use PSBT internally for externally funded channel opens, where the funding transaction is signed by an external wallet before being broadcast.

Coinjoin: Joinstr, WabiSabi (Wasabi), and similar protocols use PSBTv2 for collaborative transaction construction.

Miniscript: Miniscript (a structured subset of Bitcoin Script) integrates directly with PSBT, descriptors specify the spending policy, and PSBT carries the partial signatures.

Bitcoin Script from First Principles

Aturo Phil — Sat, 18 Jul 2026 19:55:25 +0000

Every Bitcoin transaction output contains a locking script. Every input that spends it contains an unlocking script. The combination of the two, executed together, determines whether a spend is valid. This is Bitcoin Script, and most developers who work with Bitcoin have never written it directly.

That gap matters. Understanding Script is what separates developers who use Bitcoin from developers who can build on Bitcoin. Every output type, P2PKH, P2SH, P2WPKH, P2WSH, P2TR, is defined in terms of Script. Smart contracts on Bitcoin are Script programs.

This post starts from first principles.

What Bitcoin Script Is

Bitcoin Script is a stack-based, intentionally non-Turing-complete language. It has no loops, no recursion, and no ability to read external state. Every program terminates. Every execution is deterministic.

These constraints are features. A Script program that is too complex to analyze is a Script program that miners will reject. The language is designed for verifiable, auditable spending conditions.

Script execution works like an RPN calculator:

Start with an empty stack
Read bytes from the script left to right
Data values push onto the stack
Opcodes pop arguments from the stack, operate, and push results

A script is valid if execution completes without errors and the top of the stack is a non-zero, non-empty value.

The Stack in Detail

Script: OP_1 OP_2 OP_ADD OP_3 OP_EQUAL

Initial stack: []

OP_1 → push 1          stack: [1]
OP_2 → push 2          stack: [1, 2]
OP_ADD → pop 2 items,
         push sum       stack: [3]
OP_3 → push 3          stack: [3, 3]
OP_EQUAL → pop 2 items,
           push 1 if equal  stack: [1]

Final stack: [1] — top is truthy — script succeeds

This is the classic "hash puzzle" structure: anyone who knows the inputs that produce the right result can spend.

Data Push Opcodes

Data is pushed onto the stack using push opcodes. The opcode determines how many bytes follow as data:

Opcode	Value	Effect
`OP_0`	0x00	Push empty byte array (falsy)
`OP_1`..`OP_16`	0x51..0x60	Push integers 1–16
`OP_1NEGATE`	0x4f	Push -1
0x01..0x4b	N	Push next N bytes
`OP_PUSHDATA1`	0x4c	Push next byte = length, then read that many bytes
`OP_PUSHDATA2`	0x4d	Push next 2 bytes = length, then read
`OP_PUSHDATA4`	0x4e	Push next 4 bytes = length, then read

In practice, data pushes are produced by script construction libraries. But reading raw transactions requires understanding which bytes are opcodes and which are data lengths.

def parse_script(script_bytes: bytes) -> list:
    """Parse raw script bytes into (opcode, data) tuples."""
    OPCODES = {
        0x00: 'OP_0',
        0x51: 'OP_1', 0x52: 'OP_2', 0x53: 'OP_3',
        0x76: 'OP_DUP', 0xa9: 'OP_HASH160',
        0x88: 'OP_EQUALVERIFY', 0xac: 'OP_CHECKSIG',
        0x87: 'OP_EQUAL', 0x93: 'OP_ADD',
        0xb1: 'OP_CHECKLOCKTIMEVERIFY',
        0xb2: 'OP_CHECKSEQUENCEVERIFY',
        0xae: 'OP_CHECKMULTISIG',
        0x6a: 'OP_RETURN',
    }
    result = []
    i = 0
    while i < len(script_bytes):
        byte = script_bytes[i]
        if 0x01 <= byte <= 0x4b:
            data = script_bytes[i+1:i+1+byte]
            result.append(('PUSH', data.hex()))
            i += 1 + byte
        elif byte == 0x4c:  # OP_PUSHDATA1
            length = script_bytes[i+1]
            data = script_bytes[i+2:i+2+length]
            result.append(('PUSH', data.hex()))
            i += 2 + length
        else:
            result.append((OPCODES.get(byte, f'OP_UNKNOWN_{byte:02x}'), None))
            i += 1
    return result

The Standard Script Templates

P2PKH — Pay to Public Key Hash

The most common pre-SegWit script type. Locks funds to a hash of a public key.

Locking script (scriptPubKey):

OP_DUP OP_HASH160 <pubkey_hash> OP_EQUALVERIFY OP_CHECKSIG

Unlocking script (scriptSig):

<signature> <public_key>

Combined execution:

Stack after scriptSig executes: [<sig>, <pubkey>]

OP_DUP:        duplicate top item      [<sig>, <pubkey>, <pubkey>]
OP_HASH160:    hash160 of top item     [<sig>, <pubkey>, <hash160(pubkey)>]
<pubkey_hash>: push expected hash      [<sig>, <pubkey>, <hash160(pubkey)>, <expected_hash>]
OP_EQUALVERIFY: pop 2, check equal,
                fail if not            [<sig>, <pubkey>]
OP_CHECKSIG:   pop sig and pubkey,
               verify, push 1 if valid [1]

In hex, a standard P2PKH scriptPubKey:

76 a9 14 <20-byte-hash> 88 ac
↑  ↑  ↑                 ↑  ↑
│  │  └── push 20 bytes  │  └── OP_CHECKSIG
│  └───── OP_HASH160     └────── OP_EQUALVERIFY
└──────── OP_DUP

P2SH — Pay to Script Hash

P2SH moves complexity from the output to the input. The output commits to a hash of the spending script. The spender reveals the script and satisfies it.

Locking script:

OP_HASH160 <script_hash> OP_EQUAL

Unlocking script:

<data that satisfies redeem_script> <redeem_script>

Execution: the redeem script is hashed and compared to script_hash. If equal, the redeem script is then deserialized and executed with the remaining stack items.

This is how P2SH multisig works:

Redeem script: OP_2 <pubkey1> <pubkey2> <pubkey3> OP_3 OP_CHECKMULTISIG
Script hash: HASH160(redeem_script)

Unlocking script: OP_0 <sig1> <sig2> <redeem_script>

The OP_0 is a workaround for a historical bug in OP_CHECKMULTISIG that pops one extra item from the stack.

P2WPKH — Native SegWit v0

SegWit moved the unlocking data (signatures and public keys) into a witness field, separate from the scriptSig. The scriptPubKey for P2WPKH is:

OP_0 <20-byte-pubkey-hash>

The OP_0 is the witness version (0 for SegWit v0). The validation rules for version 0 with a 20-byte hash are: treat it as P2PKH and look for the signature and public key in the witness field, not the scriptSig.

Transaction structure with SegWit:

@dataclass
class TxInput:
    txid: str
    vout: int
    scriptSig: bytes     # empty for native SegWit inputs
    sequence: int
    witness: list[bytes] # signature and pubkey go here

# For P2WPKH:
# witness = [<signature>, <pubkey>]
# scriptSig = b''  (empty)

SegWit transactions have a flag byte and a marker byte in the serialization:

version (4 bytes)
marker (0x00)         ← SegWit flag
flag (0x01)           ← SegWit flag
inputs (compact size + input data)
outputs (compact size + output data)
witness (one stack per input)
locktime (4 bytes)

P2WSH — SegWit Script Hash

P2WSH is P2SH but for SegWit. The scriptPubKey commits to the SHA256 (not HASH160) of the witness script:

OP_0 <32-byte-script-hash>

The witness contains the script and the data satisfying it:

witness: [<data_items...>, <witness_script>]

SHA256 is used instead of HASH160 because 32 bytes gives better collision resistance for more complex scripts.

Writing a Custom Locking Script

The classic example: a hash puzzle. Anyone who knows the preimage of a hash can spend.

import hashlib

def create_hash_puzzle_script(secret: bytes) -> bytes:
    """
    Locking script: OP_SHA256 <hash> OP_EQUAL
    Spending script: <secret>
    """
    secret_hash = hashlib.sha256(secret).digest()
    return bytes([
        0xa8,               # OP_SHA256
        0x20,               # push 32 bytes
        *secret_hash,       # the expected hash
        0x87                # OP_EQUAL
    ])

def create_hash_puzzle_spend(secret: bytes) -> bytes:
    """Unlocking script: push the preimage."""
    return bytes([len(secret)]) + secret

# Usage
secret = b"correct horse battery staple"
lock = create_hash_puzzle_script(secret)
unlock = create_hash_puzzle_spend(secret)

# In production: wrap in P2SH or P2WSH
# The raw hash puzzle script is non-standard

To make this spendable on mainnet, wrap it in P2WSH:

def wrap_in_p2wsh(witness_script: bytes) -> bytes:
    """
    Create a P2WSH scriptPubKey committing to witness_script.
    """
    script_hash = hashlib.sha256(witness_script).digest()
    return bytes([0x00, 0x20]) + script_hash  # OP_0 + push 32 bytes

# Spending: witness = [<secret>, <witness_script>]
witness = [create_hash_puzzle_spend(secret), lock]

Time-Lock Opcodes

OP_CHECKLOCKTIMEVERIFY (OP_CLTV, BIP 65)

Requires the spending transaction's nLockTime to be at least the value on the stack. Used for absolute timelocks.

Script: <expiry_block> OP_CHECKLOCKTIMEVERIFY OP_DROP OP_DUP OP_HASH160 <pubkey_hash> OP_EQUALVERIFY OP_CHECKSIG

This output cannot be spent until expiry_block has passed AND the transaction's nLockTime >= expiry_block AND the input's nSequence < 0xFFFFFFFF (to allow nLockTime to apply).

def create_timelock_p2pkh(pubkey_hash: bytes, lock_height: int) -> bytes:
    """P2PKH with absolute timelock."""
    height_bytes = lock_height.to_bytes(
        (lock_height.bit_length() + 7) // 8, 'little'
    )
    return bytes([
        len(height_bytes), *height_bytes,  # push lock height
        0xb1,                              # OP_CHECKLOCKTIMEVERIFY
        0x75,                              # OP_DROP
        0x76,                              # OP_DUP
        0xa9,                              # OP_HASH160
        0x14, *pubkey_hash,                # push 20-byte hash
        0x88,                              # OP_EQUALVERIFY
        0xac                               # OP_CHECKSIG
    ])

OP_CHECKSEQUENCEVERIFY (OP_CSV, BIP 112)

Relative timelock. Requires the spending input's nSequence to encode a minimum relative delay since the UTXO was confirmed. Used for Lightning's to_self_delay and Hash Time-Locked Contracts.

def create_csv_script(pubkey_hash: bytes, delay_blocks: int) -> bytes:
    """Output spendable only after delay_blocks confirmations."""
    delay_bytes = delay_blocks.to_bytes(
        (delay_blocks.bit_length() + 7) // 8, 'little'
    )
    return bytes([
        len(delay_bytes), *delay_bytes,    # push delay
        0xb2,                              # OP_CHECKSEQUENCEVERIFY
        0x75,                              # OP_DROP
        0x76,                              # OP_DUP
        0xa9,                              # OP_HASH160
        0x14, *pubkey_hash,
        0x88,                              # OP_EQUALVERIFY
        0xac                               # OP_CHECKSIG
    ])

OP_CHECKMULTISIG

Multisig requires M signatures from N possible public keys. The bare form is non-standard above 3-of-3 but works in P2SH or P2WSH.

Script: OP_<m> <pubkey1> ... <pubkeyN> OP_<n> OP_CHECKMULTISIG

The historical bug: OP_CHECKMULTISIG pops one extra item from the stack after consuming all signatures and public keys. The extra item is ignored. By convention, scripts always push OP_0 as the first item in the unlocking script to satisfy this.

def create_multisig_redeem_script(m: int, pubkeys: list[bytes]) -> bytes:
    """
    Create an m-of-n multisig redeem script for P2SH or P2WSH.
    m: required signatures
    pubkeys: list of 33-byte compressed public keys
    """
    n = len(pubkeys)
    if m > n or m < 1 or n > 20:
        raise ValueError(f"Invalid multisig parameters: {m} of {n}")

    script = bytes([0x50 + m])  # OP_1..OP_16
    for pk in pubkeys:
        script += bytes([len(pk)]) + pk
    script += bytes([0x50 + n])  # OP_1..OP_16
    script += bytes([0xae])      # OP_CHECKMULTISIG
    return script

# Spending script for 2-of-3:
# OP_0 <sig1> <sig2> <redeem_script>

Reading Scripts in Raw Transactions

Using Bitcoin Core's decoderawtransaction:

bitcoin-cli decoderawtransaction <hex>

Or in Python using python-bitcoinlib:

from bitcoin.core import CTransaction
from bitcoin.core.script import CScript
import binascii

raw_tx = bytes.fromhex("0200000001...")
tx = CTransaction.deserialize(raw_tx)

for i, output in enumerate(tx.vout):
    script = CScript(output.scriptPubKey)
    print(f"Output {i}: {output.nValue} sat")
    print(f"  Script: {script}")

    # Classify
    if script.is_p2pkh():
        print("  Type: P2PKH")
    elif script.is_p2sh():
        print("  Type: P2SH")
    elif script.is_witness_v0_keyhash():
        print("  Type: P2WPKH")
    elif script.is_witness_v0_scripthash():
        print("  Type: P2WSH")
    elif len(script) == 34 and script[0] == 0x51 and script[1] == 0x20:
        print("  Type: P2TR (Taproot)")

What You Cannot Do

Bitcoin Script deliberately excludes:

Loops — no repeated execution
Recursion — no self-reference
External state — cannot read block data, oracle prices, or other transactions
Multiplication between script values (only by constants)
String operations beyond basic concatenation (removed)

Proposed additions that are not yet in Script: OP_VAULT, OP_CHECKTEMPLATEVERIFY (CTV), OP_CAT. These would enable covenants, outputs that restrict what future transactions spending them can look like. They remain under active discussion.

The Lightning Network Routing Problem: Pathfinding, MPP, and Trampoline

Aturo Phil — Sat, 18 Jul 2026 19:30:06 +0000

Finding a path in the Lightning Network is not a solved problem. It looks like it should be, you have a graph of nodes and edges with weights, which is textbook Dijkstra, but the actual constraints make standard shortest-path algorithms insufficient.

This post covers what makes Lightning routing hard, how current implementations approach it, and what multipart payments and trampoline routing add to the picture.

Why Standard Shortest Path Does Not Work

In a standard weighted graph, you run Dijkstra from source to destination and you are done. Lightning adds several constraints that break this:

Channel capacity is private. The Lightning gossip protocol advertises channels with their total capacity, but not with individual balances. You do not know how much liquidity sits on each side of a channel. A 1 BTC channel between Alice and Bob might have 0.99 BTC on Alice's side and 0.01 BTC on Bob's side. A payment of 0.5 BTC would fail at that edge, but you have no way to know this before trying.

Balances change continuously. Even if you could query balances, they shift with every HTLC. By the time you compute a path and send a payment, the balance may have changed.

Fees are route-dependent. Routing fees are charged per hop, and the fee depends on the amount being forwarded. The optimal route for a 1,000 sat payment may be entirely different from the optimal route for 1,000,000 sat.

CLTV deltas accumulate. Each hop adds a CLTV delta to the timelock. A route with 10 hops might accumulate 400 blocks of timelock, which is a real cost (your HTLC is locked for ~400 blocks if something goes wrong).

Routing is probabilistic. The channel you pick might fail. You need a strategy for retrying on different paths after failure.

The Probability Model

The core insight in modern Lightning pathfinding is to treat routing as a probability problem. Each channel has some probability of successfully forwarding a given amount. Your goal is to find the path with the highest probability of success.

The probability of a channel forwarding an amount x given total capacity c follows a uniform distribution if you have no prior information:

P(channel can forward x) = (c - x) / c

If the channel has capacity 1,000,000 sat and you want to forward 300,000 sat, the naive probability is 0.7. But this ignores the distribution of channel balances in practice since most channels are not uniformly balanced.

LND's pathfinding uses a Bayesian model that updates estimates based on payment outcomes:

from dataclasses import dataclass
from typing import Optional

@dataclass
class ChannelLiquidityBounds:
    """
    Tracks our knowledge about a channel's available liquidity.
    min_htlc: we know at least this much is available
    max_htlc: we know less than this much is available
    """
    capacity_msat: int
    min_available_msat: int = 0
    max_available_msat: Optional[int] = None
    last_updated: int = 0  # unix timestamp

    def __post_init__(self):
        if self.max_available_msat is None:
            self.max_available_msat = self.capacity_msat

    def probability_of_success(self, amount_msat: int) -> float:
        """
        Estimate probability this channel can forward amount_msat.
        Uses uniform distribution between known bounds.
        """
        if amount_msat < self.min_available_msat:
            return 1.0  # we know this succeeds
        if amount_msat >= self.max_available_msat:
            return 0.0  # we know this fails

        # Uniform distribution between bounds
        available_range = self.max_available_msat - self.min_available_msat
        if available_range == 0:
            return 0.5
        above_min = amount_msat - self.min_available_msat
        return 1.0 - (above_min / available_range)

    def record_success(self, amount_msat: int, timestamp: int) -> None:
        """Payment succeeded: update lower bound."""
        self.min_available_msat = max(self.min_available_msat, amount_msat)
        self.last_updated = timestamp

    def record_failure(self, amount_msat: int, timestamp: int) -> None:
        """Payment failed at this channel: update upper bound."""
        self.max_available_msat = min(self.max_available_msat, amount_msat)
        self.last_updated = timestamp

    def decay(self, current_time: int, half_life_seconds: int = 3600) -> None:
        """
        Decay bounds toward the naive uniform estimate over time.
        As time passes, our information becomes less reliable.
        """
        elapsed = current_time - self.last_updated
        decay_factor = 0.5 ** (elapsed / half_life_seconds)

        # Decay lower bound toward 0
        self.min_available_msat = int(self.min_available_msat * decay_factor)
        # Decay upper bound toward capacity
        gap = self.capacity_msat - self.max_available_msat
        self.max_available_msat = self.capacity_msat - int(gap * decay_factor)

The decay function is critical: a failure you observed an hour ago is much less informative than one you observed a second ago. Channel balances change continuously.

Pathfinding With Probabilistic Cost

Standard Dijkstra minimizes a single weight. For Lightning, the weight function must combine:

Fee cost (base fee + proportional fee * amount)
Success probability (penalize low-probability channels)
CLTV delta accumulation
Number of hops (shorter is generally better)

The combined cost function used by LND and similar implementations:

import math
from dataclasses import dataclass

@dataclass
class Edge:
    source: str
    destination: str
    short_channel_id: str
    capacity_msat: int
    fee_base_msat: int
    fee_proportional_millionths: int
    cltv_expiry_delta: int
    liquidity: ChannelLiquidityBounds

def edge_cost(
    edge: Edge,
    amount_msat: int,
    probability_weight: float = 0.5,
    cltv_weight: float = 0.001,
) -> float:
    """
    Compute the cost of forwarding amount_msat through this edge.
    Returns a scalar suitable for Dijkstra minimization.
    Lower is better.
    """
    # Fee in millisatoshis
    fee_msat = (
        edge.fee_base_msat +
        (amount_msat * edge.fee_proportional_millionths // 1_000_000)
    )

    # Probability penalty: -log(p) maps probability to additive cost
    # P=1.0 → cost=0, P=0.5 → cost=0.69, P=0.1 → cost=2.30
    p = edge.liquidity.probability_of_success(amount_msat)
    if p <= 0:
        return float('inf')
    probability_penalty = -math.log(p) * probability_weight * amount_msat

    # CLTV penalty: each block of delay has a small cost
    cltv_penalty = edge.cltv_expiry_delta * cltv_weight * amount_msat

    return fee_msat + probability_penalty + cltv_penalty

def find_path(
    graph: dict[str, list[Edge]],
    source: str,
    destination: str,
    amount_msat: int,
    max_hops: int = 20
) -> list[Edge]:
    """
    Dijkstra's algorithm with probabilistic cost function.
    graph: adjacency list of {node_id: [Edge]}
    """
    import heapq

    dist = {source: 0.0}
    prev = {}
    pq = [(0.0, source)]

    while pq:
        cost, node = heapq.heappop(pq)

        if node == destination:
            # Reconstruct path
            path = []
            while node in prev:
                edge = prev[node]
                path.append(edge)
                node = edge.source
            return list(reversed(path))

        if cost > dist.get(node, float('inf')):
            continue

        for edge in graph.get(node, []):
            if edge.destination == destination or True:  # hop count check omitted for clarity
                new_cost = cost + edge_cost(edge, amount_msat)
                if new_cost < dist.get(edge.destination, float('inf')):
                    dist[edge.destination] = new_cost
                    prev[edge.destination] = edge
                    heapq.heappush(pq, (new_cost, edge.destination))

    return []  # No path found

Multipart Payments (MPP)

Even with the best pathfinding, a large payment often cannot find a single path with sufficient liquidity. Multipart payments (MPP, BOLT 11 feature bit 16) solve this by splitting a payment into multiple parts, each following a different route.

The recipient accepts MPP payments by returning the preimage only after receiving parts totaling the full amount. The payment secret (BOLT 11 field s) is the mechanism, all parts must include the same payment secret, and the recipient waits until the total matches before releasing it.

@dataclass
class PaymentPart:
    payment_hash: str
    payment_secret: str
    amount_msat: int
    path: list[Edge]

def split_payment(
    total_amount_msat: int,
    graph: dict[str, list[Edge]],
    source: str,
    destination: str,
    max_parts: int = 16,
    min_part_msat: int = 1000
) -> list[PaymentPart]:
    """
    Split a payment across multiple paths.
    Simple approach: try full amount, then binary split if needed.
    Production implementations use more sophisticated splitting.
    """
    payment_hash = secrets.token_bytes(32).hex()
    payment_secret = secrets.token_bytes(32).hex()

    # Try full amount first
    path = find_path(graph, source, destination, total_amount_msat)
    if path:
        return [PaymentPart(
            payment_hash=payment_hash,
            payment_secret=payment_secret,
            amount_msat=total_amount_msat,
            path=path
        )]

    # Split into parts
    parts = []
    remaining_msat = total_amount_msat
    part_amount = total_amount_msat // 2

    while remaining_msat > 0 and len(parts) < max_parts:
        amount = min(part_amount, remaining_msat)
        if amount < min_part_msat:
            break

        path = find_path(graph, source, destination, amount)
        if path:
            parts.append(PaymentPart(
                payment_hash=payment_hash,
                payment_secret=payment_secret,
                amount_msat=amount,
                path=path
            ))
            remaining_msat -= amount
        else:
            part_amount = part_amount // 2

    if remaining_msat > 0:
        raise ValueError(f"Could not find paths for full amount. Remaining: {remaining_msat} msat")

    return parts

MPP parts use the same payment hash and payment secret. The TLV onion payload for the final hop includes:

payment_data: {payment_secret, total_amount_msat} — signals this is an MPP part
amt_to_forward: the amount in this specific part

The recipient checks that total_amount_msat is consistent across all parts and waits until received parts sum to at least total_amount_msat before releasing the preimage.

Trampoline Routing

Standard Lightning routing requires the sender to know the full path to the destination. This requires the sender to maintain a copy of the gossip graph, which is hundreds of megabytes for a full node and impractical for mobile wallets.

Trampoline routing delegates pathfinding to intermediary nodes. The sender only needs to find a path to a trampoline node. The trampoline node handles pathfinding to the destination (or to the next trampoline).

Mobile Wallet ──── Trampoline Node A ──── (pathfinding) ──── Recipient
                  (finds path itself)

The onion structure for trampoline is nested:

def build_trampoline_onion(
    hops: list[dict],    # trampoline hops
    payload: dict        # final recipient payload
) -> bytes:
    """
    Trampoline uses a nested onion:
    Outer onion: source → trampoline nodes (known path)
    Inner trampoline onion: trampoline → destination (unknown path, delegate)

    Each trampoline hop includes the inner onion in its payload.
    The trampoline node unwraps one layer of the inner onion.
    """
    # Inner onion: for the trampoline nodes to forward
    inner_onion = build_onion(hops, payload)

    # Outer onion: source to first trampoline
    outer_payload = {
        'trampoline_onion': inner_onion,
        'total_amount_msat': payload['total_amount_msat'],
        'payment_secret': payload['payment_secret']
    }
    return outer_payload

Trampoline is defined in bLIP-25 (formerly a CLN-specific feature). LND added experimental trampoline support. The main tradeoff is privacy: the trampoline node learns the payment destination if it is the only trampoline in the path. Using two trampoline nodes mitigates this.

How Failures Feed Back

When a payment fails, the failure message propagates back along the route to the sender. BOLT 4 defines the failure codes and how they are encrypted for each hop.

The failure tells the sender two things:

Which hop failed (if the failure message is attributable)
Why it failed (routing codes: TEMPORARY_CHANNEL_FAILURE, UNKNOWN_NEXT_PEER, AMOUNT_BELOW_MINIMUM, etc.)

FAILURE_CODES = {
    0x2002: 'TEMPORARY_CHANNEL_FAILURE',   # insufficient balance, retry later
    0x400F: 'TEMPORARY_NODE_FAILURE',      # node issue, route around it
    0x100E: 'UNKNOWN_NEXT_PEER',           # channel does not exist, update graph
    0x2006: 'AMOUNT_BELOW_MINIMUM',        # part too small for this hop
    0x2007: 'FEE_INSUFFICIENT',            # fee too low, update channel params
    0x100A: 'CHANNEL_DISABLED',            # channel flagged disabled in gossip
    0x4006: 'EXPIRY_TOO_FAR',             # CLTV too high, reject
}

def process_failure(failure_code: int, failed_channel: str, amount_msat: int, liquidity_db) -> None:
    if failure_code == 0x2002:  # TEMPORARY_CHANNEL_FAILURE
        # Update upper liquidity bound — channel could not forward this amount
        channel = liquidity_db.get(failed_channel)
        channel.record_failure(amount_msat, current_time())

    elif failure_code == 0x100E:  # UNKNOWN_NEXT_PEER
        # Channel no longer exists — remove from graph
        liquidity_db.mark_channel_dead(failed_channel)

    elif failure_code == 0x2007:  # FEE_INSUFFICIENT
        # Our fee estimate was stale — update from gossip
        liquidity_db.refresh_channel_fees(failed_channel)

This feedback loop is what makes probabilistic pathfinding improve over time. Failed routes update the liquidity model. Successful routes confirm liquidity exists. With enough payment history, the estimates become significantly better than the naive uniform distribution.

What LND Does in Practice

LND's pathfinding lives in routing/pathfind.go. The key parameters you can configure:

# In lnd.conf
[routing]
# Time to keep mission control data (liquidity observations)
routerrpc.mcsessiontimeout=60m

# Probability that a randomly balanced channel can forward
routerrpc.minrtprob=0.01

# How aggressively to penalize uncertain channels
routerrpc.apriorihopprob=0.6

# Weight of CLTV vs fee in path selection
routerrpc.attemptcost=100

# Via the RPC, you can query mission control state
lncli querymc  # shows all channel probability estimates

The querymc command is particularly useful for debugging — it shows you exactly what probability your node assigns to every channel it has observed.

BOLT 11 Invoice Decoding: What's Actually Inside a Lightning Invoice

Aturo Phil — Sat, 18 Jul 2026 19:14:17 +0000

Every Lightning payment starts with an invoice. You have seen the long strings starting with lnbc or lntb, but most developers treat them as opaque blobs that their Lightning node handles. That abstraction breaks the moment something goes wrong: an invoice expires mid-payment, a payment fails with a route hint error, or you need to build tooling that inspects invoices programmatically.

This post decodes what is actually inside a BOLT 11 invoice, field by field, with working code.

The Structure

A BOLT 11 invoice is a bech32-encoded string. Bech32 was designed for SegWit addresses but BOLT 11 adopted it for invoices. The structure is:

lnbc      1        p        v        k        t      ...  <data>       <checksum>
 ↑         ↑        ↑
prefix   amount   multiplier

Breaking it into sections:

Human-readable part (HRP): Everything before the separator (1)
Data part: Everything after the separator, base32-encoded
Checksum: Last 6 characters, a bech32 checksum over the entire string

The human-readable part encodes:

Network prefix: lnbc (mainnet), lntb (testnet), lnbcrt (regtest), lnsb (signet)
Amount: optional, in the network's base unit (millisatoshis implied by multiplier)

The amount uses a multiplier suffix:
| Suffix | Multiplier | Example |
|--------|-----------|---------|
| m | milli (0.001 BTC) | lnbc1m = 100,000 sat |
| u | micro (0.000001 BTC) | lnbc1u = 100 sat |
| n | nano (0.000000001 BTC) | lnbc1n = 0.1 sat |
| p | pico (0.000000000001 BTC) | lnbc1p = 0.0001 sat |

No amount suffix means an any-amount invoice (the sender specifies).

Decoding the Data Part

After bech32-decoding the data part, you get a sequence of 5-bit groups. The data is divided into:

Timestamp: 35 bits (7 groups of 5 bits), Unix timestamp in seconds
Tagged fields: Variable-length, each with a type byte, length, and data
Signature: 520 bits (104 groups of 5 bits) = 65 bytes (64-byte compact signature + 1 recovery byte)

import base64
import hashlib
import struct
from typing import Optional

def bech32_decode_data(invoice: str) -> tuple[str, bytes]:
    """
    Decode a bech32 invoice string.
    Returns (hrp, 5-bit data as bytes).
    """
    # Find separator
    sep = invoice.rfind('1')
    hrp = invoice[:sep].lower()
    data_str = invoice[sep+1:].lower()

    CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
    data_5bit = bytes([CHARSET.index(c) for c in data_str[:-6]])  # exclude checksum
    return hrp, data_5bit

def convert_bits(data: bytes, from_bits: int, to_bits: int, pad: bool = True) -> bytes:
    """Convert between bit group sizes."""
    acc = 0
    bits = 0
    result = []
    maxv = (1 << to_bits) - 1

    for value in data:
        acc = ((acc << from_bits) | value) & 0xFFFFFFFF
        bits += from_bits
        while bits >= to_bits:
            bits -= to_bits
            result.append((acc >> bits) & maxv)

    if pad and bits:
        result.append((acc << (to_bits - bits)) & maxv)

    return bytes(result)

def decode_invoice(invoice: str) -> dict:
    hrp, data_5bit = bech32_decode_data(invoice)
    data_8bit = convert_bits(data_5bit[:-104], 5, 8, pad=False)  # exclude signature

    # Parse HRP
    network = 'mainnet' if hrp.startswith('lnbc') else \
              'testnet' if hrp.startswith('lntb') else \
              'regtest' if hrp.startswith('lnbcrt') else 'unknown'

    amount_part = hrp[4:] if network == 'mainnet' else hrp[6:]
    amount_msat = parse_amount(amount_part)

    # Parse timestamp (first 35 bits = 7 5-bit groups)
    timestamp_5bit = data_5bit[:7]
    timestamp = 0
    for b in timestamp_5bit:
        timestamp = (timestamp << 5) | b

    # Parse tagged fields
    fields = parse_tagged_fields(data_5bit[7:-104])

    # Recover signature
    sig_5bit = data_5bit[-104:]
    sig_8bit = convert_bits(sig_5bit, 5, 8, pad=False)

    return {
        'network': network,
        'amount_msat': amount_msat,
        'timestamp': timestamp,
        'fields': fields,
        'signature': sig_8bit.hex(),
    }

def parse_amount(amount_str: str) -> Optional[int]:
    if not amount_str:
        return None  # any-amount invoice
    multipliers = {'m': 100_000_000, 'u': 100_000, 'n': 100, 'p': 1}
    if amount_str[-1] in multipliers:
        return int(amount_str[:-1]) * multipliers[amount_str[-1]]
    return int(amount_str) * 100_000_000_000  # whole BTC to msat

Tagged Fields

Tagged fields carry the invoice's metadata. Each field has:

1 group (5 bits): type
2 groups (10 bits): length in 5-bit groups
N groups: data

def parse_tagged_fields(data_5bit: bytes) -> dict:
    fields = {}
    i = 0

    while i < len(data_5bit) - 2:
        field_type = data_5bit[i]
        field_len = (data_5bit[i+1] << 5) | data_5bit[i+2]
        field_data_5bit = data_5bit[i+3:i+3+field_len]
        field_data = convert_bits(field_data_5bit, 5, 8, pad=False)
        i += 3 + field_len

        if field_type == 1:    # p: payment hash
            fields['payment_hash'] = field_data.hex()

        elif field_type == 16:  # s: payment secret
            fields['payment_secret'] = field_data.hex()

        elif field_type == 13:  # d: description
            fields['description'] = field_data.decode('utf-8')

        elif field_type == 23:  # h: description hash
            fields['description_hash'] = field_data.hex()

        elif field_type == 6:   # x: expiry (seconds)
            expiry = 0
            for b in field_data_5bit:
                expiry = (expiry << 5) | b
            fields['expiry_seconds'] = expiry

        elif field_type == 24:  # c: min_final_cltv_expiry
            cltv = 0
            for b in field_data_5bit:
                cltv = (cltv << 5) | b
            fields['min_final_cltv_expiry'] = cltv

        elif field_type == 9:   # f: fallback on-chain address
            fields['fallback_address'] = parse_fallback(field_data)

        elif field_type == 3:   # r: route hints
            fields.setdefault('route_hints', []).append(parse_route_hint(field_data))

        elif field_type == 5:   # n: node public key
            fields['payee_pubkey'] = field_data.hex()

        elif field_type == 10:  # 9: feature bits
            fields['feature_bits'] = parse_features(field_data)

    return fields

Key Fields in Detail

Payment Hash (p, type 1)

32 bytes. The SHA256 hash of the payment preimage. The sender locks their HTLC to this hash. Only the recipient (who knows the preimage) can claim the payment.

payment_hash = fields['payment_hash']
# This is what flows through the HTLC chain
# The preimage that hashes to this unlocks the payment

Payment Secret (s, type 16)

32 bytes. Added in 2020 to prevent probing attacks. The recipient generates a random secret and includes it in the invoice. The sender must include it in the final HTLC. An intermediate hop that knows the payment hash cannot claim the payment without also knowing the secret, because the secret is only in the last HTLC.

payment_secret = fields.get('payment_secret')
# Required for modern invoices
# Included in the TLV onion payload to the recipient

Route Hints (r, type 3)

Each route hint is a sequence of channel hops that lead to the recipient. Used by nodes that are not well-connected or are behind a private channel. The LSPS2 JIT channel mechanism uses fake SCIDs in route hints.

def parse_route_hint(data: bytes) -> list[dict]:
    """
    A route hint is a list of hop_extra_data entries.
    Each entry: 33-byte pubkey + 8-byte short_channel_id +
                4-byte fee_base_msat + 4-byte fee_proportional_millionths +
                2-byte cltv_expiry_delta
    = 51 bytes per hop
    """
    hops = []
    for i in range(0, len(data), 51):
        hop_data = data[i:i+51]
        if len(hop_data) < 51:
            break
        hop = {
            'pubkey': hop_data[:33].hex(),
            'short_channel_id': int.from_bytes(hop_data[33:41], 'big'),
            'fee_base_msat': int.from_bytes(hop_data[41:45], 'big'),
            'fee_proportional_millionths': int.from_bytes(hop_data[45:49], 'big'),
            'cltv_expiry_delta': int.from_bytes(hop_data[49:51], 'big'),
        }
        hops.append(hop)
    return hops

Feature Bits (9, type 10)

A bitfield indicating which Lightning features the recipient supports. Bit positions are defined in BOLT 9. Even bits are required (sender must support them), odd bits are optional (sender can ignore them).

FEATURE_BITS = {
    8:  'var_onion_optin',           # required: TLV onion format
    14: 'payment_secret',            # required: payment secret
    16: 'basic_mpp',                 # optional: multipart payments
    48: 'payment_metadata',          # optional: payment metadata in onion
    30: 'amp',                       # optional: atomic multipath
}

def parse_features(data: bytes) -> dict:
    features = {}
    bit_array = int.from_bytes(data, 'big')
    for bit, name in FEATURE_BITS.items():
        features[name] = bool(bit_array & (1 << bit))
    return features

Expiry (x, type 6)

Seconds from the timestamp. Default is 3600 (1 hour) if absent. An expired invoice must not be paid — the payment would fail at the recipient who has discarded the preimage.

import time

def is_invoice_expired(decoded: dict) -> bool:
    expiry = decoded['fields'].get('expiry_seconds', 3600)
    expiry_time = decoded['timestamp'] + expiry
    return time.time() > expiry_time

min_final_cltv_expiry (c, type 24)

The minimum CLTV delta the recipient requires on the final HTLC. Defaults to 18 blocks. If your routing algorithm does not respect this, the recipient rejects the payment.

Verifying the Signature

The invoice is signed by the recipient's node key. The signature covers the entire invoice content, proving the invoice was created by the owner of the payee public key.

def verify_invoice_signature(invoice: str, decoded: dict) -> bool:
    """
    Verify the BOLT 11 invoice signature.
    The signed message is: SHA256(hrp_bytes + data_bytes_without_sig)
    """
    from coincurve import PublicKey

    sep = invoice.rfind('1')
    hrp = invoice[:sep].lower().encode()

    _, data_5bit = bech32_decode_data(invoice)
    # Data excluding the 104 5-bit groups of signature
    data_without_sig_5bit = data_5bit[:-104]
    data_without_sig_8bit = convert_bits(data_without_sig_5bit, 5, 8, pad=False)

    # Message is hrp bytes + data bytes
    message = hrp + data_without_sig_8bit
    message_hash = hashlib.sha256(message).digest()

    # Signature: 65 bytes (recovery byte + 64-byte sig)
    sig_bytes = bytes.fromhex(decoded['signature'])
    recovery_byte = sig_bytes[-1]
    compact_sig = sig_bytes[:64]

    # Recover the public key from the signature
    recovered_pubkey = PublicKey.from_signature_and_message(
        compact_sig + bytes([recovery_byte]),
        message_hash,
        hasher=None
    )

    # If n (payee pubkey) is present, compare
    if 'payee_pubkey' in decoded['fields']:
        expected = bytes.fromhex(decoded['fields']['payee_pubkey'])
        return recovered_pubkey.format(compressed=True) == expected

    # Otherwise, the recovered key IS the payee pubkey
    decoded['fields']['payee_pubkey'] = recovered_pubkey.format(compressed=True).hex()
    return True

Using a Library

The above is instructive but you should use a library in production. Python options:

# lnaddr (part of pyln-client from Core Lightning)
from pyln.client import LightningRpc
# or decode directly
import lnaddr
decoded = lnaddr.lndecode("lnbc1pvjluez...")

# bolt11 library
import bolt11
decoded = bolt11.decode("lnbc1pvjluez...")

print(decoded.amount)           # amount in satoshis
print(decoded.paymenthash)      # 32-byte payment hash
print(decoded.date)             # timestamp
print(decoded.tags)             # all tagged fields

Go options:

import "github.com/lightningnetwork/lnd/zpay32"

invoice, err := zpay32.Decode(invoiceString, &chaincfg.MainNetParams)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Amount: %d msat\n", invoice.MilliSat)
fmt.Printf("Payment hash: %x\n", invoice.PaymentHash)
fmt.Printf("Description: %s\n", *invoice.Description)
fmt.Printf("Expiry: %s\n", invoice.Expiry())
for _, hint := range invoice.RouteHints {
    fmt.Printf("Route hint via: %x\n", hint[0].NodeID.SerializeCompressed())
}

Practical Situations Where You Need This

Validating before payment: Check expiry, verify the signature, confirm the payment hash is 32 bytes, and read the feature bits to confirm compatibility before sending.

Building invoice generation tooling: CLN and LND both expose invoice creation via RPC, but if you are generating invoices in application code or in a service that does not run a full node, you need to construct and sign the invoice yourself.

Debugging routing failures: Route hints in a failed invoice often reveal the problem, an expired or closed private channel, a SCID that no longer exists, or a CLTV delta that your pathfinding algorithm did not respect.

LSPS2 / JIT channel integration: JIT invoices embed fake SCIDs in route hints. Decoding the invoice and inspecting the route hints tells you which LSP the wallet is using and what fee the LSP is charging.

Mempool Policy: Why Your Transaction Gets Rejected

Aturo Phil — Sat, 18 Jul 2026 19:00:29 +0000

Every Bitcoin node maintains its own mempool, a local set of unconfirmed transactions it considers valid and is willing to relay and mine. When you broadcast a transaction and it does not propagate, or when your wallet says "transaction rejected", the reason is almost always mempool policy.

Mempool policy is not the same as consensus rules. Consensus rules are what the network agrees on: a transaction either is or is not valid by the protocol. Policy rules are what individual nodes choose to enforce: a transaction can be consensus-valid but still be rejected by most mempools.

Understanding this distinction is essential for anyone building Bitcoin applications.

Consensus vs. Policy

A consensus-invalid transaction will be rejected by every full node and can never confirm. Examples: spending a UTXO that does not exist, invalid signature, exceeding the block size limit.

A policy-invalid transaction is consensus-valid but does not meet the mempool's additional requirements. It can confirm if a miner includes it directly, some mining pools accept transactions out of band but it will not propagate through the peer-to-peer network.

Bitcoin Core's policy rules are defined primarily in src/policy/policy.cpp and src/validation.cpp. The defaults represent the rules most of the network enforces.

The Standard Script Policy

Bitcoin Core rejects non-standard scripts from its mempool. A standard script is one of a small, enumerated set:

Type	Description
P2PK	Pay-to-public-key (legacy, rare)
P2PKH	Pay-to-public-key-hash
P2SH	Pay-to-script-hash
P2WPKH	Native SegWit v0
P2WSH	Native SegWit v0 script hash
P2TR	Taproot (SegWit v1)
Multisig	Bare multisig up to 3-of-3
OP_RETURN	Data carrier output (up to 83 bytes)
Witness v1–v16	Future SegWit versions (allowed as unknown versions)

Any output script that does not match one of these templates is non-standard. A transaction containing a non-standard output will be rejected by Bitcoin Core's mempool even if it is perfectly consensus-valid.

This matters if you are experimenting with custom scripts:

from bitcoin.core.script import CScript, OP_ADD, OP_5

# This script: <x> <y> OP_ADD OP_5 OP_EQUAL
# Spendable by any two numbers that sum to 5
# Consensus-valid, but non-standard
puzzle_script = CScript([OP_ADD, OP_5, OP_EQUAL])

# A transaction with this as an output will be rejected by most mempools
# It can confirm only if a miner includes it directly

To use custom scripts on mainnet, you wrap them in P2SH or P2WSH, which are standard. The redeem script is only revealed when spending, not at output creation.

Minimum Relay Fee

Every mempool has a minimum fee rate it will accept. Bitcoin Core's default is 1 satoshi per virtual byte (minrelaytxfee=0.00001). A transaction below this rate is rejected outright, regardless of how small the mempool is.

Virtual bytes (vbytes) account for the SegWit discount:

def calculate_vsize(base_size: int, total_size: int) -> float:
    """
    Virtual size calculation per BIP 141.
    base_size: serialized size excluding witness data
    total_size: full serialized size including witness data
    """
    weight = base_size * 3 + total_size
    return weight / 4.0

# Example: typical P2WPKH to P2WPKH transaction
# base_size = 41 bytes (no witness)
# witness = 108 bytes (2 stack items: sig + pubkey)
# total_size = 41 + 108 = 149 bytes

base = 41
total = 149
vsize = calculate_vsize(base, total)
# vsize ≈ 110.5 vbytes

# At 10 sat/vbyte, fee = 1105 sat
fee = int(vsize * 10)

A dynamic minimum also exists: when the mempool fills up, Bitcoin Core raises the minimum fee rate to shed low-fee transactions. During high-fee periods, the effective floor can be 10–50 sat/vbyte or higher.

Dust Limits

Bitcoin Core will not relay transactions that create outputs below the dust threshold. An output is "dust" if the cost of spending it exceeds its value.

The dust limit depends on the output type:

DUST_RELAY_FEE_RATE = 3  # sat/vbyte (Bitcoin Core default)

DUST_LIMITS = {
    'P2PKH':   546,   # 3 sat/vbyte * 182 vbyte spend cost
    'P2SH':    540,   # 3 sat/vbyte * 180 vbyte spend cost
    'P2WPKH':  294,   # 3 sat/vbyte * 98 vbyte spend cost
    'P2WSH':   330,   # 3 sat/vbyte * 110 vbyte spend cost
    'P2TR':    330,   # 3 sat/vbyte * 110 vbyte spend cost
    'OP_RETURN': 0,   # OP_RETURN outputs are unspendable; no dust limit
}

def is_dust(output_value_sat: int, output_type: str) -> bool:
    return output_value_sat < DUST_LIMITS.get(output_type, 546)

The exception is OP_RETURN: it is explicitly unspendable, so there is no spending cost to calculate. Bitcoin Core allows OP_RETURN outputs regardless of value (as long as the value is zero, a non-zero OP_RETURN output is rejected).

A transaction that creates a dust output is rejected by the mempool. The dust threshold is enforced per output, a transaction with 10 outputs where one is dust is rejected entirely.

RBF: Replace-By-Fee

Replace-By-Fee (BIP 125) allows an unconfirmed transaction to be replaced by a higher-fee version. This is the primary mechanism for fee bumping when you underestimated the required fee rate.

A transaction is RBF-signaling if any of its inputs has nSequence < 0xFFFFFFFE. Bitcoin Core checks this to determine whether it will accept a replacement.

# Signaling RBF opt-in
# nSequence of 0xFFFFFFFD signals RBF
SEQUENCE_RBF_OPT_IN = 0xFFFFFFFD

def create_rbf_transaction(inputs, outputs, fee_rate):
    tx = Transaction()
    for utxo in inputs:
        tx_input = TxInput(
            txid=utxo.txid,
            vout=utxo.vout,
            sequence=SEQUENCE_RBF_OPT_IN  # enables RBF
        )
        tx.add_input(tx_input)
    for output in outputs:
        tx.add_output(output)
    return tx

Rules for a valid replacement (all must be satisfied):

The replacement must signal RBF (at least one input with nSequence < 0xFFFFFFFE)
The replacement must not introduce new unconfirmed inputs (inputs not already in the mempool or chain)
The replacement's absolute fee must be higher than the sum of fees of all transactions it displaces
The replacement's fee must exceed the original's fee by at least minrelaytxfee * replacement_size
The replacement must not evict more than 100 transactions from the mempool

Rule 3 is the important one: if your replacement bumps the fee rate but results in a lower absolute fee (because you removed some outputs), it is rejected. The mempool prioritizes absolute fee to protect against eviction attacks.

The replacement also spends the same inputs as the original, so it conflicts with the original and displaces it.

CPFP: Child-Pays-for-Parent

If a transaction cannot be RBF-bumped, either because it did not signal RBF or you cannot change the inputs, the alternative is CPFP.

CPFP creates a new transaction that spends an output from the stuck transaction and pays a fee high enough to pull both transactions through. Miners evaluate transaction packages, so a high-fee child can subsidize a low-fee parent.

def calculate_cpfp_child_fee(
    parent_vsize: int,
    parent_fee: int,
    child_vsize: int,
    target_package_fee_rate: float  # sat/vbyte
) -> int:
    """
    Calculate the fee the child must pay to achieve the target
    fee rate for the entire (parent + child) package.
    """
    total_package_vsize = parent_vsize + child_vsize
    total_needed_fee = target_package_fee_rate * total_package_vsize
    child_fee = total_needed_fee - parent_fee
    return max(0, int(child_fee))

# Example: parent stuck at 2 sat/vbyte, need 20 sat/vbyte
parent_vsize = 141     # typical P2WPKH transaction
parent_fee = 282       # 141 * 2 sat/vbyte
child_vsize = 110      # spending one P2WPKH output
target = 20.0          # sat/vbyte

child_fee = calculate_cpfp_child_fee(parent_vsize, parent_fee, child_vsize, target)
# child_fee = (141 + 110) * 20 - 282 = 5020 - 282 = 4738 sat
# child fee rate alone: 4738 / 110 ≈ 43 sat/vbyte

CPFP requires that you have an output from the stuck transaction that you can spend. If all outputs go to other parties, you cannot CPFP without their cooperation.

Bitcoin Core's Package Relay (BIP 331) is now deployed, allowing wallets to submit parent-child packages together so the child's fee can be evaluated alongside the parent even before the parent enters the mempool. This is particularly important for Lightning's anchor output channel closes.

Timelock Rules

Two timelock mechanisms interact with mempool policy:

nLockTime: A transaction with nLockTime > 0 is not valid until the specified block height (or Unix time, if > 500,000,000). Bitcoin Core will not accept a transaction into its mempool if its locktime has not been reached.

# This transaction cannot enter the mempool before block 850000
tx.locktime = 850000

nSequence / CSV: OP_CHECKSEQUENCEVERIFY enforces that the input's sequence number encodes a relative timelock (number of blocks or time since the UTXO was confirmed). A transaction spending a CSV-locked output is invalid until the relative timelock has elapsed.

# Spending a UTXO with CSV 144 (about 1 day)
# The UTXO must have at least 144 confirmations
CSV_BLOCKS = 144
tx_input.sequence = CSV_BLOCKS  # 0x00000090

This is the mechanism used for Lightning's to_self_delay outputs after a force close.

OP_RETURN Size Limits

Bitcoin Core currently accepts OP_RETURN outputs up to 83 bytes (one byte for OP_RETURN, one byte for the data push opcode, 80 bytes of data). This limit is a policy rule, not a consensus rule.

In 2024, a policy debate emerged about raising or removing this limit. Some miners already accept larger OP_RETURN data. As of July 2026, Bitcoin Core's default remains 83 bytes, but nodes can override this with -datacarriersize.

def create_op_return_output(data: bytes) -> bytes:
    """
    Create an OP_RETURN output.
    data: up to 80 bytes (Bitcoin Core default policy)
    """
    if len(data) > 80:
        raise ValueError(f"OP_RETURN data too large for standard policy: {len(data)} > 80 bytes")
    script = bytes([0x6a, len(data)]) + data  # OP_RETURN + push
    return script

Checking Mempool Policy Before Broadcasting

Query mempool.space or your own node to check current fee rates before constructing a transaction:

import httpx
import asyncio

async def get_current_fee_rates() -> dict:
    """
    Fetch current fee estimates from mempool.space.
    Returns fee rates in sat/vbyte for different confirmation targets.
    """
    async with httpx.AsyncClient() as client:
        response = await client.get("https://mempool.space/api/v1/fees/recommended")
        rates = response.json()
        return {
            'fastest': rates['fastestFee'],      # next block
            'half_hour': rates['halfHourFee'],   # ~3 blocks
            'hour': rates['hourFee'],            # ~6 blocks
            'economy': rates['economyFee'],      # ~144 blocks
            'minimum': rates['minimumFee'],      # dynamic floor
        }

async def get_mempool_stats() -> dict:
    """Check current mempool size and minimum fee."""
    async with httpx.AsyncClient() as client:
        response = await client.get("https://mempool.space/api/mempool")
        return response.json()
        # Returns: count, vsize, total_fee, fee_histogram

async def main():
    rates = await get_current_fee_rates()
    stats = await get_mempool_stats()

    print(f"Next block: {rates['fastest']} sat/vbyte")
    print(f"Economy: {rates['economy']} sat/vbyte")
    print(f"Mempool vsize: {stats['vsize']:,} vbytes")
    print(f"Pending transactions: {stats['count']:,}")

What to Do When a Transaction Is Stuck

Checklist in order:

Check if it was rejected at broadcast — node returned an error. Read the error code. Common rejections: min relay fee not met, dust, non-standard, already in mempool.
Check if it is in the mempool — query /api/tx/{txid} on mempool.space. If not there, it was rejected or never reached the network.
RBF bump — if inputs signal RBF, create a replacement with a higher fee. Most wallet software supports this.
CPFP — if you control an output, spend it with a high enough fee to pull the parent through.
Wait — if the mempool clears (Sunday nights UTC are historically low-fee periods), low-fee transactions often confirm without intervention.
Accept abandonment — after approximately two weeks, Bitcoin Core removes transactions from its mempool. If no one confirms it and no one CPFP'd it, the UTXO returns to spendable.

Taproot for Developers: What Changed and What You Can Build

Aturo Phil — Sat, 18 Jul 2026 18:28:19 +0000

Taproot activated on Bitcoin at block 709,632 in November 2021. Three and a half years later, adoption is growing but developer understanding of what Taproot actually enables, at the code level, is still shallow in most technical content.

This post is about what Taproot changed in the Bitcoin protocol, what Schnorr signatures unlock, what MAST (Merkelized Abstract Syntax Trees) means for script design, and what you can build today that was not possible or practical before.

What Taproot Is, Precisely

Taproot is a combination of three improvements shipped together in BIP 340, BIP 341, and BIP 342:

BIP 340: Schnorr signatures — a new signature scheme replacing ECDSA for Taproot outputs
BIP 341: Taproot itself — a new output type (P2TR) that can be spent either by a key path or a script path
BIP 342: Tapscript — modifications to Bitcoin Script that apply when spending via the script path

They are inseparable in practice. You need all three to use Taproot correctly.

Schnorr Signatures: What They Change

Bitcoin used ECDSA for signatures from 2009 through 2021. ECDSA works, but it has properties that limit what you can build efficiently:

Signatures are not linearly composable, you cannot add two ECDSA signatures together to produce a valid combined signature
Signature size varies (71–72 bytes DER-encoded)
Batch verification is not possible

Schnorr signatures (BIP 340) fix all three:

They are linearly composable — you can add public keys and add signatures, and the result is a valid signature for the combined key
Fixed 64-byte size
Batch verification of N signatures is faster than N sequential verifications

The linear composability property is what enables MuSig2 and key aggregation. If Alice has key A and Bob has key B, they can produce a combined key C = A + B. A Schnorr signature from C is indistinguishable from a single-key signature. No one observing the blockchain can tell that C is a multisig key.

BIP 340 specifies the exact scheme. The signature is (R, s) where:

R = k·G  (nonce point)
s = k + e·x  (mod n)
e = H_tag(R || P || m)  (tagged hash)

P is the public key, m is the message (transaction hash), x is the private key scalar, and k is the nonce.

Verification checks s·G = R + e·P.

In Python, using the bip340 reference implementation:

import hashlib
import secrets

def tagged_hash(tag: str, msg: bytes) -> bytes:
    tag_hash = hashlib.sha256(tag.encode()).digest()
    return hashlib.sha256(tag_hash + tag_hash + msg).digest()

def schnorr_sign(private_key: int, message: bytes) -> bytes:
    """
    BIP 340 Schnorr signature.
    Returns 64-byte signature (R.x || s).
    """
    from secp256k1 import G, n, point_mul, point_add

    P = point_mul(G, private_key)
    # BIP 340: negate private key if P.y is odd
    if P.y % 2 != 0:
        private_key = n - private_key

    k = int.from_bytes(secrets.token_bytes(32), 'big') % n
    R = point_mul(G, k)
    if R.y % 2 != 0:
        k = n - k

    P_bytes = P.x.to_bytes(32, 'big')
    R_bytes = R.x.to_bytes(32, 'big')
    e = int.from_bytes(tagged_hash("BIP0340/challenge", R_bytes + P_bytes + message), 'big') % n
    s = (k + e * private_key) % n

    return R_bytes + s.to_bytes(32, 'big')

In practice, you use a library. Python: python-bitcoinlib or coincurve. Go: btcec/v2. Rust: secp256k1.

Key Path vs. Script Path Spending

A Pay-to-Taproot (P2TR) output encodes a single 32-byte x-only public key:

OP_1 <32-byte-x-only-pubkey>

This output can be spent two ways:

Key path: Provide a Schnorr signature for the encoded public key. The key is called the "tweaked key" because it commits to a Merkle root of spending conditions.

Script path: Reveal one of the scripts in the Merkle tree, prove its position in the tree (Merkle proof), and satisfy that script.

The tweaked key is computed as:

Q = P + H_taptweak(P || merkle_root) · G

Where P is the "internal key" and merkle_root is the Merkle root of all the spending scripts (or a zero hash if there are no scripts).

If you only need a single key to spend (no scripts), the key path is a single 64-byte signature, cheaper than any script-based spend. If you need complex conditions, the script path lets you commit to many conditions but only reveal the one you use.

MAST: Merkelized Script Trees

Before Taproot, if you wanted "Alice can spend, or Bob and Carol can spend together, or time-locked refund", you had to use OP_IF branches in a single script. Every branch was visible when you spent. The script revealed all conditions.

With Taproot, each condition is a leaf in a Merkle tree. When you spend, you reveal only the leaf you use and the Merkle proof connecting it to the committed root. The other branches are never published.

Building a script tree in Python using python-bitcoinlib:

from bitcoin.core.script import CScript, OP_CHECKSIG, OP_CHECKLOCKTIMEVERIFY, OP_DROP
from bitcoin.core.key import CPubKey
import hashlib

def tapbranch_hash(left: bytes, right: bytes) -> bytes:
    """BIP 341 TapBranch hash."""
    tag = "TapBranch"
    tag_hash = hashlib.sha256(tag.encode()).digest()
    if left > right:
        left, right = right, left
    return hashlib.sha256(tag_hash + tag_hash + left + right).digest()

def tapleaf_hash(script: bytes, version: int = 0xc0) -> bytes:
    """BIP 341 TapLeaf hash."""
    tag = "TapLeaf"
    tag_hash = hashlib.sha256(tag.encode()).digest()
    leaf_data = bytes([version]) + compact_size(len(script)) + script
    return hashlib.sha256(tag_hash + tag_hash + leaf_data).digest()

# Three spending conditions
alice_pubkey = CPubKey(bytes.fromhex("02..."))
bob_pubkey = CPubKey(bytes.fromhex("03..."))

# Leaf A: Alice spends
leaf_a_script = CScript([alice_pubkey, OP_CHECKSIG])
leaf_a_hash = tapleaf_hash(bytes(leaf_a_script))

# Leaf B: Bob spends after block 800000
leaf_b_script = CScript([800000, OP_CHECKLOCKTIMEVERIFY, OP_DROP, bob_pubkey, OP_CHECKSIG])
leaf_b_hash = tapleaf_hash(bytes(leaf_b_script))

# Merkle root of the two leaves
merkle_root = tapbranch_hash(leaf_a_hash, leaf_b_hash)

When Alice spends via Leaf A:

Witness stack:
  <alice_signature>          # satisfies the script
  <leaf_a_script>            # the script being executed
  <leaf_b_hash>              # Merkle proof: sibling hash
  <control_block>            # version byte + internal key + parity bit

Bob's leaf is never revealed. Its existence is committed but private.

MuSig2: Practical n-of-n Multisig

MuSig2 (BIP 327) is the key aggregation scheme that makes n-of-n multisig look like single-sig on-chain.

The core operations:

Key aggregation: Each signer contributes their public key. The aggregate key is derived deterministically.
Nonce exchange: Each signer generates two nonces and shares the commitments.
Partial signing: Each signer produces a partial signature.
Signature aggregation: Partial signatures are summed to produce the final Schnorr signature.

from coincurve import PublicKey, PrivateKey

def aggregate_pubkeys(pubkeys: list[bytes]) -> bytes:
    """
    MuSig2 key aggregation (simplified).
    In production, use a correct MuSig2 implementation — the actual
    scheme includes key aggregation coefficients to prevent rogue key attacks.
    """
    # Each key is weighted by H(L || P_i) where L = hash of all keys
    L = hashlib.sha256(b''.join(sorted(pubkeys))).digest()

    # In the real scheme, each key is multiplied by its coefficient before summing
    # This is the conceptual structure; use bitcoin-core's secp256k1-zkp for production
    aggregate = None
    for pk_bytes in pubkeys:
        pk = PublicKey(pk_bytes)
        # ... apply coefficient multiplication
        aggregate = pk if aggregate is None else aggregate.combine([pk])
    return aggregate.format(compressed=True)

For production MuSig2, use:

Go: btcec/v2/schnorr/musig2
Rust: secp256k1-zkp with the MuSig module
Python: pysecp256k1 (wrapping libsecp256k1 with MuSig2 support)

A 3-of-3 multisig using MuSig2 on-chain is a single key path spend: one signature, 64 bytes, identical to any single-key Taproot output. The threshold structure is invisible.

What You Can Build With Taproot

Collaborative custody without revealing signers: A 2-of-3 setup can be implemented as a Taproot tree where each 2-of-2 combination is a leaf. Normal spends use key path (all three sign via MuSig2). Emergency recovery uses the appropriate script leaf. On-chain, all cooperative spends look like single-key transactions.

Vaults with time-locks: A leaf tree where:

Leaf 1: Owner key, no delay
Leaf 2: Recovery key, 6-month CLTV
Leaf 3: Emergency key, 1-year CLTV

Covenants are not yet possible in Bitcoin Script without soft fork changes (OP_VAULT, CTV), but you can simulate some patterns with pre-signed transactions.

Discreet Log Contracts (DLCs): DLCs allow Bitcoin contracts that resolve based on external oracle attestations. The oracle signs a message with a known key and an adaptor signature mechanism routes funds based on which outcome they attest to. Taproot makes DLC outputs indistinguishable from regular transactions on-chain.

Lightning Taproot channels: LND and CLN both support Taproot-based channels (Simple Taproot Channels, BIP draft). The funding output becomes a MuSig2 key. Force close still reveals the commitment structure, but cooperative closes are indistinguishable from simple transfers.

Practical: Reading a P2TR Address

P2TR addresses use bech32m encoding (distinct from bech32 used for P2WPKH/P2WSH):

import bech32

def decode_p2tr_address(address: str) -> bytes:
    """Decode a P2TR (bech32m) address to the 32-byte x-only pubkey."""
    hrp, data = bech32.bech32_decode(address)
    if data is None:
        raise ValueError("Invalid bech32m address")
    decoded = bech32.convertbits(data[1:], 5, 8, False)
    if len(decoded) != 32:
        raise ValueError(f"Expected 32 bytes, got {len(decoded)}")
    return bytes(decoded)

def create_p2tr_output(internal_key: bytes, merkle_root: bytes = b'') -> bytes:
    """
    Create a P2TR scriptPubKey.
    internal_key: 32-byte x-only public key
    merkle_root: TapTree merkle root, or empty bytes for key-path-only
    """
    tweaked_key = taproot_tweak_pubkey(internal_key, merkle_root)
    return bytes([0x51, 0x20]) + tweaked_key  # OP_1 <32 bytes>

# Checking if a UTXO is P2TR
def is_p2tr(script_pubkey: bytes) -> bool:
    return (
        len(script_pubkey) == 34 and
        script_pubkey[0] == 0x51 and  # OP_1
        script_pubkey[1] == 0x20      # PUSH 32 bytes
    )

The Current State

As of July 2026, approximately 12% of Bitcoin UTXOs use P2TR outputs. Adoption is growing primarily through:

Lightning Taproot channels (now default in LND v0.21+)
Hardware wallet updates (Ledger and Trezor both support P2TR)
Wallet software updates (Sparrow, Electrum, BlueWallet)

The tooling gap that still exists is in educational content about MuSig2 and script tree construction. Most developers know Taproot exists but have not written code that uses the script path. The libraries are mature; the documentation is scattered.

LSPS Specifications: What Lightning Service Providers Are Standardizing and Why It Matters

Aturo Phil — Fri, 17 Jul 2026 06:02:45 +0000

Until recently, every Lightning Service Provider built their own proprietary protocol. Loop (Lightning Labs), Boltz, Voltage, and others each defined their own API for channel opens, liquidity requests, and submarine swaps. A wallet integrating three LSPs wrote three different clients, handled three different error models, and maintained three separate integrations when any of the APIs changed.

The LSPS specifications (Lightning Service Provider Specifications) are an attempt to end this. They define a common protocol layer that any LSP can implement and any wallet can integrate against once.

As of July 2026, LSPS0, LSPS1, and LSPS2 are the active specifications. LSPS2 has been adopted into the BOLT process as bLIP-52. Understanding these specifications is relevant to any developer building Lightning wallets, LSPs, or the infrastructure between them.

What Problem LSPs Solve

A new Lightning wallet user faces the inbound liquidity problem immediately. Lightning requires you to receive a channel from someone before you can receive payments. If you have never received a channel, you cannot receive your first payment.

This is not a theoretical concern. It is the first failure mode every new Lightning user encounters.

Lightning Service Providers solve this by providing channels on demand. An LSP:

Maintains a pool of liquidity (bitcoin in channels)
Accepts requests from wallets for inbound channels
Opens channels, charges fees, and manages the lifecycle of those channels
Optionally provides Just-in-Time (JIT) channel opens; opening a channel in real time when a payment arrives for a wallet that does not yet have one

The operational complexity is on the LSP side. The wallet tells the LSP what it needs; the LSP figures out how to provide it.

LSPS0: The Transport Layer

LSPS0 is the foundation. It specifies how messages are exchanged between a client (wallet) and an LSP. Without a common transport, each LSPS spec would require its own communication mechanism.

The choice is JSON-RPC 2.0 over the existing Lightning peer-to-peer messaging layer. Specifically, LSPS0 uses Lightning's custom_message mechanism (message type 37913) to carry JSON-RPC requests and responses between two Lightning nodes.

This is significant. It means:

No new network connections are required
The LSP's Lightning node is the API endpoint
Authentication is the Lightning key exchange — you are already authenticated as a peer
The protocol is encrypted by the existing Lightning noise protocol

The message format follows JSON-RPC 2.0:

// Request from client to LSP
{
    "jsonrpc": "2.0",
    "method": "lsps1.get_info",
    "params": {},
    "id": "a1b2c3d4"
}

// Response from LSP to client
{
    "jsonrpc": "2.0",
    "result": {
        "supported_versions": [1],
        "website": "https://example-lsp.com",
        "options": {
            "minimum_channel_confirmations": 0,
            "minimum_onchain_payment_confirmations": 1,
            "supports_zero_channel_reserve": true,
            "min_onchain_payment_size_sat": 100000,
            "max_channel_expiry_blocks": 13140,
            "min_initial_client_balance_sat": "0",
            "min_initial_lsp_balance_sat": "100000",
            "max_initial_client_balance_sat": "100000000",
            "min_channel_balance_sat": "100000",
            "max_channel_balance_sat": "100000000"
        }
    },
    "id": "a1b2c3d4"
}

Implementing LSPS0 transport with LND:

package lsps

import (
    "encoding/json"
    "github.com/lightningnetwork/lnd/lnwire"
)

const LSPSMessageType = lnwire.MessageType(37913)

type JSONRPCRequest struct {
    JSONRPC string          `json:"jsonrpc"`
    Method  string          `json:"method"`
    Params  json.RawMessage `json:"params"`
    ID      string          `json:"id"`
}

type JSONRPCResponse struct {
    JSONRPC string          `json:"jsonrpc"`
    Result  json.RawMessage `json:"result,omitempty"`
    Error   *JSONRPCError   `json:"error,omitempty"`
    ID      string          `json:"id"`
}

type JSONRPCError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
}

// Error codes defined by LSPS0
const (
    ErrParseError     = -32700
    ErrInvalidRequest = -32600
    ErrMethodNotFound = -32601
    ErrInvalidParams  = -32602
    ErrInternalError  = -32603
    // LSPS-specific error range: -32099 to -32000
    ErrUnacceptableFee    = 100
    ErrPaymentRequired    = 101
    ErrOptionMismatch     = 102
)

func SendLSPSMessage(lndClient LNDClient, peerPubkey string, req JSONRPCRequest) error {
    data, err := json.Marshal(req)
    if err != nil {
        return err
    }
    return lndClient.SendCustomMessage(peerPubkey, LSPSMessageType, data)
}

LSPS0 also defines service discovery. A client can query lsps0.list_protocols to learn which LSPS versions the LSP supports:

// Request
{"jsonrpc": "2.0", "method": "lsps0.list_protocols", "params": {}, "id": "disc-1"}

// Response
{"jsonrpc": "2.0", "result": {"supported_protocols": [0, 1, 2]}, "id": "disc-1"}

LSPS1: Channel Purchase

LSPS1 covers the straightforward case: a client wants to buy a channel from an LSP. The client requests a channel with specific parameters, the LSP provides a quote, and the client pays for the channel on-chain.

The protocol has four methods:

Method	Purpose
`lsps1.get_info`	Client discovers LSP capabilities and pricing parameters
`lsps1.create_order`	Client requests a channel with specific parameters
`lsps1.get_order`	Client polls for order status updates

A typical LSPS1 flow:

Step 1: Get info

// Request
{"jsonrpc": "2.0", "method": "lsps1.get_info", "params": {}, "id": "info-1"}

// Response — LSP advertises its capabilities
{
    "jsonrpc": "2.0",
    "result": {
        "supported_versions": [1],
        "options": {
            "min_channel_balance_sat": "100000",
            "max_channel_balance_sat": "10000000",
            "min_initial_client_balance_sat": "0",
            "min_initial_lsp_balance_sat": "100000",
            "max_initial_client_balance_sat": "5000000",
            "min_channel_confirmations": 0,
            "min_onchain_payment_confirmations": 1,
            "supports_zero_channel_reserve": true,
            "max_channel_expiry_blocks": 13140
        }
    },
    "id": "info-1"
}

Step 2: Create order

// Client requests a 500,000 sat channel with 100,000 sat on their side
{
    "jsonrpc": "2.0",
    "method": "lsps1.create_order",
    "params": {
        "lsp_balance_sat": "400000",
        "client_balance_sat": "100000",
        "required_channel_confirmations": 0,
        "funding_confirms_within_blocks": 6,
        "channel_expiry_blocks": 4380,
        "token": "",
        "refund_onchain_address": "bc1q...",
        "announce_channel": false
    },
    "id": "order-1"
}

// LSP responds with payment instructions
{
    "jsonrpc": "2.0",
    "result": {
        "order_id": "Sl3HM9rvCy",
        "lsp_balance_sat": "400000",
        "client_balance_sat": "100000",
        "required_channel_confirmations": 0,
        "funding_confirms_within_blocks": 6,
        "channel_expiry_blocks": 4380,
        "announce_channel": false,
        "order_state": "CREATED",
        "payment": {
            "state": "EXPECT_PAYMENT",
            "fee_total_sat": "3000",
            "order_total_sat": "103000",
            "onchain_address": "bc1q...",
            "onchain_payment": {
                "min_fee_for_0conf": "253",
                "min_onchain_payment_confirmations": 1
            }
        },
        "channel": null,
        "created_at": "2026-07-17T10:00:00.000Z",
        "expires_at": "2026-07-17T11:00:00.000Z"
    },
    "id": "order-1"
}

Step 3: Client pays the on-chain address

The client sends order_total_sat to the LSP's on-chain address. Once confirmed, the LSP opens the channel.

Step 4: Poll for order status

import asyncio
import httpx

async def wait_for_channel(lsp_node, order_id: str, poll_interval: int = 30):
    while True:
        response = await send_lsps_message(lsp_node, {
            "jsonrpc": "2.0",
            "method": "lsps1.get_order",
            "params": {"order_id": order_id},
            "id": f"poll-{order_id}"
        })

        order = response["result"]
        state = order["order_state"]

        if state == "COMPLETED":
            return order["channel"]
        elif state == "FAILED":
            raise Exception(f"Order failed: {order}")
        else:
            print(f"Order state: {state}. Waiting...")
            await asyncio.sleep(poll_interval)

LSPS1 is the simple case. The client proactively requests a channel and pays for it. The complexity is in LSPS2, where channels are opened reactively when a payment arrives.

LSPS2: Just-in-Time Channels (bLIP-52)

LSPS2, now also published as bLIP-52, is the specification for Just-in-Time channel opens. The scenario: a user receives their first Lightning payment, but they have no inbound channel. The LSP intercepts the payment at the last hop, opens a channel to the wallet in real time, and routes the payment through that new channel.

This eliminates the bootstrapping problem. A new user can receive their first payment without any prior channel setup.

The protocol is more complex than LSPS1 because it coordinates a payment interception with a channel open, and both must happen atomically from the user's perspective.

The LSPS2 flow:

Sender ──────────────────────────────── LSP ─── (JIT channel open) ─── Wallet
         HTLC to fake_scid                       channel open to wallet
         (intercepted by LSP)                    HTLC routed through new channel

The key mechanism is a fake Short Channel ID (SCID). The LSP assigns the wallet a SCID that does not correspond to a real channel. When a sender routes a payment using that SCID, the LSP intercepts it, opens a real channel, and forwards the payment.

Step 1: Client gets a SCID-wrapped invoice

// Client requests a buy channel parameter set
{
    "jsonrpc": "2.0",
    "method": "lsps2.get_info",
    "params": {"token": ""},
    "id": "jit-info-1"
}

// LSP responds with fee structure
{
    "jsonrpc": "2.0",
    "result": {
        "supported_versions": [1],
        "min_payment_size_msat": "1000",
        "max_payment_size_msat": "1000000000",
        "opening_fee_params_menu": [
            {
                "min_fee_msat": "2000",
                "proportional": 5000,
                "valid_until": "2026-07-17T11:00:00Z",
                "min_lifetime": 1008,
                "max_client_to_self_delay": 2016,
                "promise": "abc123..."
            }
        ]
    },
    "id": "jit-info-1"
}

The promise is a server-side signed commitment to the fee parameters. It prevents the LSP from changing fees between the client's decision and the actual channel open.

Step 2: Client creates an invoice with a route hint

def create_jit_invoice(
    amount_msat: int,
    lsp_pubkey: str,
    fake_scid: str,         # assigned by LSP
    opening_fee_params: dict
) -> str:
    """
    Create a BOLT 11 invoice with a route hint pointing to the LSP's fake SCID.
    The route hint tells the sender to route through the LSP.
    The LSP intercepts, opens a channel, and forwards.
    """
    route_hint = RouteHint(
        pubkey=lsp_pubkey,
        short_channel_id=fake_scid,
        fee_base_msat=opening_fee_params["min_fee_msat"],
        fee_proportional_millionths=opening_fee_params["proportional"],
        cltv_expiry_delta=40
    )
    return create_bolt11_invoice(
        amount_msat=amount_msat,
        description="Payment",
        route_hints=[route_hint]
    )

Step 3: Sender pays the invoice

The sender routes through the LSP using the fake SCID in the route hint. The LSP's routing layer intercepts the HTLC because it knows that fake SCID belongs to a JIT channel.

Step 4: LSP opens the channel and forwards

The LSP must:

Open a zero-confirmation channel to the wallet
Route the HTLC through the new channel
Deduct the opening fee from the payment amount

async def handle_jit_payment_interception(
    htlc: InterceptedHTLC,
    lsp_client,
    channel_manager
) -> None:
    wallet_pubkey = lsp_client.get_wallet_for_scid(htlc.short_channel_id)

    if wallet_pubkey is None:
        # Not a JIT SCID — pass through normally
        await lsp_client.forward_htlc(htlc)
        return

    # Calculate fee deduction
    opening_fee_msat = calculate_opening_fee(htlc.amount_msat)
    payment_to_wallet_msat = htlc.amount_msat - opening_fee_msat

    # Open zero-conf channel
    channel = await channel_manager.open_channel(
        peer_pubkey=wallet_pubkey,
        local_amount_sat=payment_to_wallet_msat // 1000 + CHANNEL_RESERVE,
        zero_conf=True
    )

    # Forward HTLC through new channel
    await lsp_client.forward_htlc_via(htlc, channel.channel_id, payment_to_wallet_msat)

Zero-confirmation channels are essential here, the LSP cannot wait for block confirmations while holding an HTLC. BOLT 2 supports zero-conf channels via the option_zeroconf feature bit.

What LSPS2 Does Not Specify

Understanding specification boundaries is as important as understanding what the spec covers. LSPS2 does not specify:

LSP liquidity management: How the LSP maintains a pool of liquidity, how it manages its own channels to routing nodes, or how it prices liquidity over time. These are operator concerns.

Wallet fallback behavior: What the wallet does if the JIT channel open fails mid-payment. LSPS2 expects the LSP to fail the HTLC back upstream; the wallet receives a payment failure and must decide whether to retry.

Multi-LSP coordination: A wallet using two LSPs concurrently, with different fake SCIDs for different invoices, is outside scope.

Channel closure policy: When and how the LSP closes JIT channels. LSPS2 specifies min_lifetime (the LSP's commitment to keep the channel open for a minimum number of blocks), but LSP behavior after that point is implementation-defined.

Implementing a Minimal LSPS Client

A minimal client library that works across LSPS0, LSPS1, and LSPS2:

import json
import uuid
from typing import Any

class LSPSClient:
    """
    Minimal LSPS client over the Lightning peer messaging layer.
    Requires a Lightning node client that supports custom messages.
    """

    def __init__(self, node_client, lsp_pubkey: str):
        self.node_client = node_client
        self.lsp_pubkey = lsp_pubkey
        self._pending: dict[str, asyncio.Future] = {}

    async def call(self, method: str, params: dict = {}) -> Any:
        request_id = str(uuid.uuid4())
        request = {
            "jsonrpc": "2.0",
            "method": method,
            "params": params,
            "id": request_id
        }

        future = asyncio.get_event_loop().create_future()
        self._pending[request_id] = future

        await self.node_client.send_custom_message(
            peer_pubkey=self.lsp_pubkey,
            message_type=37913,
            data=json.dumps(request).encode()
        )

        response = await asyncio.wait_for(future, timeout=30.0)

        if "error" in response:
            raise LSPSError(
                code=response["error"]["code"],
                message=response["error"]["message"]
            )
        return response["result"]

    def handle_incoming_message(self, data: bytes) -> None:
        """Call this when a custom message arrives from the LSP peer."""
        response = json.loads(data)
        request_id = response.get("id")
        if request_id and request_id in self._pending:
            future = self._pending.pop(request_id)
            future.set_result(response)

    # High-level methods
    async def list_protocols(self) -> list[int]:
        result = await self.call("lsps0.list_protocols")
        return result["supported_protocols"]

    async def get_lsps1_info(self) -> dict:
        return await self.call("lsps1.get_info")

    async def create_lsps1_order(self, params: dict) -> dict:
        return await self.call("lsps1.create_order", params)

    async def get_lsps1_order(self, order_id: str) -> dict:
        return await self.call("lsps1.get_order", {"order_id": order_id})

    async def get_lsps2_info(self, token: str = "") -> dict:
        return await self.call("lsps2.get_info", {"token": token})

    async def create_lsps2_channel(self, params: dict) -> dict:
        return await self.call("lsps2.buy", params)


class LSPSError(Exception):
    def __init__(self, code: int, message: str):
        self.code = code
        super().__init__(f"LSPS error {code}: {message}")

The State of the Specifications in July 2026

LSPS0 is stable. No implementations have reported protocol-breaking issues and the custom message transport has proven reliable across LND, CLN, and LDK implementations.

LSPS1 is implemented by several LSPs in production. The main implementation variation is in fee structures, the spec allows LSPs to define their own pricing models, which means interoperability exists at the protocol level but pricing comparison still requires manual interpretation.

LSPS2 (bLIP-52) has production implementations in LND and CLN. The primary open question in the specification is around privacy: the fake SCID assigned by the LSP can be used to identify the wallet's LSP relationship, which is a metadata leak. The specification currently requires this tradeoff but notes it as an area for future work.

Areas where the specifications are actively evolving:

LSPS5 (Webhooks): Defines push notifications from LSP to client, allowing the LSP to notify the wallet when a JIT channel open has succeeded or when a channel is approaching expiry. At draft stage.
LSPS3 (Channel Close): Standardizing cooperative channel close negotiation between client and LSP. Needed for clean LSP-initiated closes.
Privacy improvements to LSPS2: Proposals exist to reduce the SCID-based LSP identification leak, but none have reached specification stage.

Why This Matters for Builders

If you are building a Lightning wallet, integrating LSPS means one integration covers multiple LSPs. The competitive differentiation between LSPs shifts to pricing, reliability, and geographic coverage, not API shape. This is better for the ecosystem.

If you are building an LSP, implementing LSPS means any LSPS-compatible wallet can use your service without custom integration work. The addressable market is larger.

If you are building Lightning infrastructure that manages channels, routing nodes, channel managers, node operators, LSPS2's JIT channel protocol is the standard to understand for how wallets expect channels to arrive. Implementations that do not understand LSPS2's fake SCID mechanism will not correctly route JIT payments.

The specifications are small enough to read in an afternoon. LSPS0 is 15 pages. LSPS1 is 20 pages. LSPS2/bLIP-52 is 25 pages. Reading them gives you a more accurate model of how Lightning liquidity works at the protocol level than any summary can.

The Sagas Pattern: Coordinating Multi-Step Bitcoin Workflows Without Distributed Transactions

Aturo Phil — Fri, 17 Jul 2026 05:44:29 +0000

In 1987, Hector Garcia-Molina and Kenneth Salem published a paper called "Sagas" in the ACM SIGMOD Record. The problem they were solving was long-lived database transactions, operations that span seconds or minutes rather than milliseconds, holding locks that block the rest of the system.

Their solution was to break a long transaction into a sequence of smaller, independent local transactions, each with a corresponding compensating transaction that undoes its effect if the sequence needs to abort.

They called this sequence a saga.

Thirty-eight years later, this pattern describes almost exactly what happens when you open a Lightning channel, route a multi-hop payment, or coordinate a submarine swap. Bitcoin and Lightning do not support distributed transactions. They have no rollback mechanism. What they have is time-locked contracts, cooperative protocols, and the ability in failure cases to go on-chain and let the chain settle the state.

A saga is the right mental model for all of this.

The Problem: Multi-Step Operations Without Atomicity

A distributed transaction in a traditional database provides atomicity across multiple systems: either everything commits or everything rolls back. This is achieved through two-phase commit (2PC), which requires a coordinator and a protocol that can hold all participants in a "prepared" state.

Bitcoin has no such mechanism. A Bitcoin transaction is atomic, it either confirms or it does not, but a sequence of Bitcoin-related operations across multiple systems has no coordinator and no rollback. If the third step in a five-step workflow fails, you cannot undo steps one and two by asking the blockchain to forget them.

Consider opening a Lightning channel:

Your node and the peer negotiate parameters (funding amount, fees, CSV delays)
You broadcast a funding transaction to the Bitcoin mempool
The funding transaction confirms (after some number of blocks)
Both nodes exchange funding_locked messages
The channel becomes operational

If step 4 fails, your peer disappears after the funding transaction confirms you have a funded channel that neither party can use cooperatively. You must go on-chain and close it unilaterally. There is no rollback; there is only resolution.

The saga pattern gives you a vocabulary for designing systems that handle this correctly.

Structure of a Saga

A saga consists of:

A sequence of transactions T1, T2, ..., Tn
A corresponding sequence of compensating transactions C1, C2, ..., Cn

If the saga completes T1 through Ti and then Ti+1 fails, it executes compensating transactions Ci, Ci-1, ..., C1 in reverse order to undo what was done.

There are two execution strategies:

Choreography: Each transaction emits events, and subsequent transactions are triggered by those events. There is no central coordinator. This is simpler to implement and has no single point of failure, but it is harder to reason about as the saga grows.

Orchestration: A central coordinator tracks the saga state and issues commands to each participant. Easier to observe and debug, but the coordinator itself becomes a dependency.

For most Bitcoin infrastructure, orchestration is easier to reason about and easier to recover from failure. The coordinator's state can be persisted and replayed.

Modeling a Lightning Channel Open as a Saga

from dataclasses import dataclass
from enum import Enum
from typing import Optional

class ChannelOpenStatus(Enum):
    NEGOTIATING     = "negotiating"
    FUNDING_PENDING = "funding_pending"
    AWAITING_CONF   = "awaiting_confirmation"
    EXCHANGE_LOCKED = "exchange_locked"
    OPEN            = "open"
    # Failure states
    FAILED          = "failed"
    CLOSING         = "closing"

@dataclass
class ChannelOpenSaga:
    saga_id: str
    peer_pubkey: str
    capacity_sat: int
    local_reserve_sat: int
    status: ChannelOpenStatus
    funding_txid: Optional[str] = None
    funding_output_index: Optional[int] = None
    failure_reason: Optional[str] = None

# Transactions (forward path)
async def T1_negotiate_parameters(saga: ChannelOpenSaga, peer_client) -> ChannelOpenSaga:
    """Send open_channel, receive accept_channel."""
    result = await peer_client.open_channel(
        pubkey=saga.peer_pubkey,
        local_funding_amount=saga.capacity_sat,
    )
    return ChannelOpenSaga(**{**saga.__dict__, 'status': ChannelOpenStatus.FUNDING_PENDING})

async def T2_broadcast_funding(saga: ChannelOpenSaga, wallet, broadcast) -> ChannelOpenSaga:
    """Construct and broadcast the funding transaction."""
    tx = await wallet.create_funding_tx(saga.capacity_sat)
    txid = await broadcast(tx)
    return ChannelOpenSaga(**{
        **saga.__dict__,
        'funding_txid': txid,
        'funding_output_index': 0,
        'status': ChannelOpenStatus.AWAITING_CONF
    })

async def T3_await_confirmation(saga: ChannelOpenSaga, chain_watcher) -> ChannelOpenSaga:
    """Wait for the funding transaction to reach required depth."""
    await chain_watcher.wait_for_confirmations(saga.funding_txid, confirmations=3)
    return ChannelOpenSaga(**{**saga.__dict__, 'status': ChannelOpenStatus.EXCHANGE_LOCKED})

async def T4_exchange_funding_locked(saga: ChannelOpenSaga, peer_client) -> ChannelOpenSaga:
    """Exchange funding_locked messages."""
    await peer_client.send_funding_locked(saga.funding_txid)
    await peer_client.receive_funding_locked()
    return ChannelOpenSaga(**{**saga.__dict__, 'status': ChannelOpenStatus.OPEN})

# Compensating transactions (backward path)
async def C1_send_error(saga: ChannelOpenSaga, peer_client) -> None:
    """Compensate T1: tell the peer the negotiation is cancelled."""
    await peer_client.send_error(f"Channel open cancelled: {saga.failure_reason}")

async def C2_attempt_rbf_or_abandon(saga: ChannelOpenSaga, wallet, broadcast) -> None:
    """
    Compensate T2: the funding transaction is in the mempool.
    Options: RBF to zero output (double-spend), or wait for it to be abandoned.
    If the tx already confirmed, C2 cannot undo it — escalate to C3.
    """
    if saga.funding_txid:
        await wallet.attempt_cancel_transaction(saga.funding_txid)

async def C3_force_close(saga: ChannelOpenSaga, channel_manager) -> None:
    """
    Compensate T3: funding confirmed but channel is stuck.
    The only recourse is a unilateral close.
    """
    await channel_manager.force_close(saga.funding_txid, saga.funding_output_index)

Notice that the compensating transactions are not symmetric. C1 (cancel negotiation) is cheap and clean. C2 (cancel a mempool transaction) is possible but probabilistic, it depends on whether the transaction has already confirmed. C3 (force close a confirmed funding transaction) is expensive, it costs an on-chain fee and takes to_self_delay blocks to recover funds.

This asymmetry is a fundamental property of Bitcoin operations. On-chain state is progressively harder to undo. The saga pattern makes this explicit.

The Orchestrator

The orchestrator runs the saga, handles failures, and decides when to compensate:

class ChannelOpenOrchestrator:
    def __init__(self, saga_store, peer_client, wallet, broadcast, chain_watcher, channel_manager):
        self.saga_store = saga_store
        self.peer_client = peer_client
        self.wallet = wallet
        self.broadcast = broadcast
        self.chain_watcher = chain_watcher
        self.channel_manager = channel_manager

    async def run(self, saga: ChannelOpenSaga) -> ChannelOpenSaga:
        steps = [
            (T1_negotiate_parameters, C1_send_error,           [self.peer_client]),
            (T2_broadcast_funding,    C2_attempt_rbf_or_abandon,[self.wallet, self.broadcast]),
            (T3_await_confirmation,   C3_force_close,           [self.chain_watcher]),
            (T4_exchange_funding_locked, None,                  [self.peer_client]),
        ]

        completed = []

        for transaction, compensator, args in steps:
            try:
                saga = await transaction(saga, *args)
                await self.saga_store.save(saga)
                completed.append((compensator, args, saga))
            except Exception as e:
                saga = ChannelOpenSaga(**{
                    **saga.__dict__,
                    'status': ChannelOpenStatus.FAILED,
                    'failure_reason': str(e)
                })
                await self.saga_store.save(saga)
                # Compensate in reverse order
                await self._compensate(completed, saga)
                return saga

        return saga

    async def _compensate(self, completed, saga):
        for compensator, args, saga_at_step in reversed(completed):
            if compensator is None:
                continue
            try:
                await compensator(saga, *args)
            except Exception as comp_error:
                # Log compensation failure — this requires manual intervention
                print(f"COMPENSATION FAILED: {compensator.__name__}: {comp_error}")
                # Do not raise — attempt remaining compensations

The orchestrator saves the saga state after each step. If the process crashes mid-saga, it can be recovered by loading the saved saga and resuming or compensating from where it stopped. This is the idempotency requirement: each step must be safe to re-execute if it was interrupted before the state was saved.

A Payment Routing Saga

A multi-hop Lightning payment is a saga with a different compensation structure. The HTLC mechanism provides built-in compensation: if a payment fails at any hop, HTLCs are failed back upstream. The saga structure is implicit in the protocol.

But the saga framing is still useful for an application that needs to track payment outcomes:

@dataclass
class PaymentSaga:
    saga_id: str
    payment_hash: str
    amount_msat: int
    recipient_pubkey: str
    max_fee_msat: int
    status: str   # 'routing', 'pending', 'succeeded', 'failed'
    failure_code: Optional[str] = None
    preimage: Optional[str] = None

async def run_payment_saga(saga: PaymentSaga, lnd_client, saga_store) -> PaymentSaga:
    """
    Send a payment and track its outcome.
    Lightning's HTLC mechanism handles on-chain compensation automatically;
    the saga here is the application-level tracking.
    """
    try:
        # T1: initiate the payment
        result = await lnd_client.send_payment(
            payment_hash=saga.payment_hash,
            amount_msat=saga.amount_msat,
            dest=saga.recipient_pubkey,
            fee_limit_msat=saga.max_fee_msat,
            timeout_seconds=60
        )

        if result.status == 'SUCCEEDED':
            saga = PaymentSaga(**{
                **saga.__dict__,
                'status': 'succeeded',
                'preimage': result.payment_preimage
            })
        else:
            # Lightning compensated automatically (HTLCs failed back)
            # We record the failure and its reason
            saga = PaymentSaga(**{
                **saga.__dict__,
                'status': 'failed',
                'failure_code': result.failure_reason
            })

    except Exception as e:
        saga = PaymentSaga(**{
            **saga.__dict__,
            'status': 'failed',
            'failure_code': f'exception:{str(e)}'
        })

    await saga_store.save(saga)
    return saga

For Lightning payments, the compensation is handled by the protocol. For your application state balances, order records, external system state, the compensation must be explicit.

Backward vs. Forward Compensation

Garcia-Molina's original paper distinguishes two compensation strategies:

Backward compensation (rollback): Undo completed transactions in reverse order. Return the system to the state before the saga began. This is what most people think of when they hear "compensating transaction."

Forward compensation (retry): Accept that some transactions cannot be undone and instead push forward to a completed state, even if it is not the originally intended state. This is appropriate when compensation is more expensive or more dangerous than completion.

In Bitcoin infrastructure, forward compensation is frequently the right choice. Consider the channel open scenario above: if T3 (await confirmation) succeeds, the funding transaction is confirmed, C3 (force close) is expensive and disruptive. In many cases, the right approach is to keep retrying T4 (exchange funding locked) until the peer reconnects, rather than immediately force-closing.

This is a design decision that must be explicit:

async def T4_exchange_funding_locked_with_retry(
    saga: ChannelOpenSaga,
    peer_client,
    max_attempts: int = 100,
    retry_interval_seconds: int = 60
) -> ChannelOpenSaga:
    """
    Forward compensation: retry T4 rather than force-closing.
    The peer may reconnect within minutes or hours.
    Force close is the last resort, not the first.
    """
    for attempt in range(max_attempts):
        try:
            await peer_client.send_funding_locked(saga.funding_txid)
            await peer_client.receive_funding_locked(timeout=30)
            return ChannelOpenSaga(**{**saga.__dict__, 'status': ChannelOpenStatus.OPEN})
        except TimeoutError:
            if attempt < max_attempts - 1:
                await asyncio.sleep(retry_interval_seconds)
            else:
                raise  # Exhausted retries — propagate to orchestrator

The choice between backward and forward compensation should be documented explicitly for each step, because it has real operational consequences.

Idempotency Is Not Optional

Every transaction in a saga must be idempotent; safe to execute more than once with the same result. The orchestrator may re-execute a step if the process crashes after the step succeeded but before the state was saved.

For Bitcoin operations, idempotency often requires checking current state before acting:

async def T2_broadcast_funding_idempotent(
    saga: ChannelOpenSaga,
    wallet,
    broadcast,
    mempool_client
) -> ChannelOpenSaga:
    """Idempotent version of T2."""
    # If we already have a txid, check if it's still in the mempool or confirmed
    if saga.funding_txid:
        status = await mempool_client.get_tx_status(saga.funding_txid)
        if status in ('mempool', 'confirmed'):
            # Already broadcast — skip, return existing saga
            return ChannelOpenSaga(**{
                **saga.__dict__,
                'status': ChannelOpenStatus.AWAITING_CONF
            })
        # Transaction was dropped — fall through to re-broadcast

    tx = await wallet.create_funding_tx(saga.capacity_sat)
    txid = await broadcast(tx)
    return ChannelOpenSaga(**{
        **saga.__dict__,
        'funding_txid': txid,
        'funding_output_index': 0,
        'status': ChannelOpenStatus.AWAITING_CONF
    })

The pattern is: load current state, check if this step already happened, proceed only if it has not.

Submarine Swaps as a Saga

A submarine swap involves exchanging on-chain bitcoin for Lightning bitcoin, or vice versa. It is one of the cleaner examples of a saga in Lightning infrastructure. It involves two parties, two chains (conceptually), and a hash-locked contract that coordinates the exchange.

Forward swap (on-chain → Lightning):

Step	Transaction	Compensating Transaction
T1	Alice requests swap from LSP; LSP generates invoice and on-chain address	C1: Alice abandons, no funds committed
T2	Alice sends on-chain payment to LSP's script (HTLC locked to invoice hash)	C2: Alice waits for HTLC timeout, reclaims on-chain funds
T3	LSP pays Alice's Lightning invoice (revealing preimage)	C3: Not possible — Lightning payment is final
T4	LSP claims on-chain HTLC using revealed preimage	C4: Not applicable — follows from T3

If T3 fails, the LSP cannot pay the Lightning invoice. T2's on-chain HTLC automatically refunds to Alice after the timeout. The time-lock is the compensating transaction. Garcia-Molina would recognize this immediately: the compensation is built into the contract.

What the Sagas Paper Gets Wrong for Bitcoin

Garcia-Molina assumed compensating transactions are always possible and always effective. Bitcoin proves this is not always true:

Irreversibility: An on-chain transaction that confirms cannot be compensated. The compensation must come from subsequent transactions (force close, timeout claims), not from undoing the original.
Probabilistic finality: "Confirmed" is not binary, it is a confidence level based on depth. A compensating strategy for a transaction with 1 confirmation is different from one with 6.
Time as a resource: Every block that passes changes the compensation options. A 20-block CLTV expiry window gives you 20 blocks to compensate before the on-chain contract resolves automatically in the other party's favor.

These constraints make Bitcoin saga design harder than database saga design, but also more constrained, which means more predictable. The protocol tells you exactly what happens if you do nothing. That is a property most distributed systems lack.

Event Sourcing for Financial Systems: Why Mutating State Is the Wrong Abstraction

Aturo Phil — Fri, 17 Jul 2026 03:52:23 +0000

Every payment system you have ever debugged has the same shape: a database row with a balance column, a function that reads it, modifies it, and writes it back, and a support ticket from a user whose balance is wrong.

The balance is wrong because the balance column is a lie. It is a compressed summary of every transaction that ever happened, and compression loses information. When something goes wrong, you cannot reconstruct what happened from the current state alone. You check logs, you scroll through audit tables, you ask the application developer what the code used to do three deploys ago.

Event sourcing is the claim that this architecture is backward. The events are the data. The balance is a derived view.

The Core Idea

An event-sourced system records a sequence of facts about what happened. It never updates or deletes records. State is computed by replaying the event sequence from the beginning, or from the last known snapshot.

The difference is not subtle. Consider a payment account:

Mutable state approach:

-- What you store
accounts (id, balance, updated_at)

-- What you lose
-- Why is the balance 47,320 sat?
-- Who changed it?
-- Was there a failed payment that was retried?
-- Did a refund arrive during a network partition?

Event-sourced approach:

-- What you store
account_events (id, account_id, event_type, amount_sat, occurred_at, metadata)

-- What you can answer
-- Complete history of every credit and debit
-- Exact sequence of operations
-- State at any point in time
-- What the balance was before a specific transaction

The balance is not stored. It is computed:

from dataclasses import dataclass, field
from typing import List
from decimal import Decimal

@dataclass
class AccountEvent:
    event_type: str      # 'deposit', 'withdrawal', 'fee', 'refund'
    amount_sat: int
    occurred_at: str
    metadata: dict = field(default_factory=dict)

def compute_balance(events: List[AccountEvent]) -> int:
    balance = 0
    for event in events:
        if event.event_type in ('deposit', 'refund'):
            balance += event.amount_sat
        elif event.event_type in ('withdrawal', 'fee'):
            balance -= event.amount_sat
    return balance

This function is called a projection. It takes a stream of events and produces a current state. You can have multiple projections over the same event stream — one for balance, one for transaction history, one for fee totals — each computed independently.

Why Financial Systems Are Naturally Event-Sourced

A financial ledger is already a sequence of events. This is not a new idea, double-entry bookkeeping has been append-only since the 15th century. Every credit creates a corresponding debit. The ledger is never corrected; if a mistake was made, a correcting entry is added.

Bitcoin makes this explicit at the protocol level. The UTXO set is the current state. The blockchain is the event log. The UTXO set is derived from the blockchain, you cannot have one without the other, and the blockchain is authoritative. If the UTXO set is ever corrupt or uncertain, you recompute it from the blockchain. The events are the source of truth.

A payment system built on this observation has several properties that are difficult to achieve with mutable state:

Auditability without extra work. Regulators and auditors want to know every transaction. In a mutable state system, this requires a separate audit log that must be kept in sync with the main database — two things that can diverge. In an event-sourced system, the audit log is the database.

Temporal queries without effort. "What was the account balance on the 15th?" is a simple operation: replay events up to the 15th and compute the projection. In a mutable state system, this requires either storing snapshots at known points in time or reconstructing state from backup data.

Debugging by replay. When a bug is reported, you replay the event stream through the new code and observe what changes. You can reproduce any past state exactly. In a mutable state system, you can only observe the current state.

Optimistic concurrency without distributed locks. An event store can enforce ordering by requiring events to be appended at a specific expected version. If two writers attempt to append at version 47 simultaneously, one fails. There is no shared mutable state to lock.

Aggregates and the Write Side

In practice, you do not replay every event in the store for every operation. You organize events into streams, one per aggregate, a consistency boundary. An aggregate is the smallest unit of state that must be consistent.

For a payment system, an aggregate might be a channel, a payment, or a wallet. Each has its own event stream. When you process a command, "open a channel", "initiate a payment", you load the aggregate's event stream, replay it to get current state, apply business rules, and if valid, append new events.

from typing import Optional
from dataclasses import dataclass

@dataclass
class ChannelState:
    channel_id: str
    status: str           # 'pending_open', 'open', 'pending_close', 'closed'
    capacity_sat: int
    local_balance_sat: int
    remote_balance_sat: int
    pending_htlcs: list

def apply_event(state: Optional[ChannelState], event: dict) -> ChannelState:
    """Pure function: takes current state and an event, returns new state."""
    event_type = event['event_type']

    if event_type == 'ChannelOpened':
        return ChannelState(
            channel_id=event['channel_id'],
            status='open',
            capacity_sat=event['capacity_sat'],
            local_balance_sat=event['local_balance_sat'],
            remote_balance_sat=event['remote_balance_sat'],
            pending_htlcs=[]
        )

    if event_type == 'HTLCAdded':
        # Return new state without mutating the input
        new_htlcs = state.pending_htlcs + [event['htlc']]
        return ChannelState(
            **{k: v for k, v in state.__dict__.items() if k != 'pending_htlcs'},
            pending_htlcs=new_htlcs
        )

    if event_type == 'HTLCSettled':
        htlc = next(h for h in state.pending_htlcs if h['id'] == event['htlc_id'])
        new_htlcs = [h for h in state.pending_htlcs if h['id'] != event['htlc_id']]
        new_local = state.local_balance_sat - htlc['amount_sat']
        new_remote = state.remote_balance_sat + htlc['amount_sat']
        return ChannelState(
            channel_id=state.channel_id,
            status=state.status,
            capacity_sat=state.capacity_sat,
            local_balance_sat=new_local,
            remote_balance_sat=new_remote,
            pending_htlcs=new_htlcs
        )

    if event_type == 'ChannelClosed':
        return ChannelState(
            **{k: v for k, v in state.__dict__.items() if k != 'status'},
            status='closed'
        )

    return state

def load_channel(events: list) -> Optional[ChannelState]:
    """Replay all events to get current channel state."""
    state = None
    for event in events:
        state = apply_event(state, event)
    return state

The apply_event function is pure — it takes state and an event, returns new state, has no side effects. This makes it trivially testable and replayable.

The command handler applies business rules before appending events:

def handle_add_htlc(channel_id: str, htlc: dict, event_store) -> None:
    # Load current state
    events = event_store.load_stream(f"channel-{channel_id}")
    channel = load_channel(events)

    # Validate
    if channel.status != 'open':
        raise ValueError(f"Cannot add HTLC to channel in status {channel.status}")
    if htlc['amount_sat'] > channel.local_balance_sat:
        raise ValueError("Insufficient local balance")

    # Emit event — this is the only write
    new_event = {
        'event_type': 'HTLCAdded',
        'channel_id': channel_id,
        'htlc': htlc,
        'version': len(events) + 1  # optimistic concurrency
    }
    event_store.append(f"channel-{channel_id}", new_event, expected_version=len(events))

Snapshots

Replaying the full event stream on every operation does not scale once a stream contains thousands of events. The solution is snapshots: periodically compute and store the current state, and on load, start from the most recent snapshot rather than the beginning.

@dataclass
class Snapshot:
    stream_id: str
    version: int          # event version this snapshot was taken at
    state: ChannelState
    taken_at: str

def load_channel_with_snapshot(
    stream_id: str,
    event_store,
    snapshot_store
) -> ChannelState:
    # Try to load most recent snapshot
    snapshot = snapshot_store.latest(stream_id)

    if snapshot:
        # Load only events after the snapshot
        events = event_store.load_stream(stream_id, after_version=snapshot.version)
        state = snapshot.state
    else:
        # No snapshot — full replay
        events = event_store.load_stream(stream_id)
        state = None

    for event in events:
        state = apply_event(state, event)

    return state

Snapshots are a performance optimization, not a replacement for the event log. The event log remains the source of truth. If a snapshot is corrupt, you discard it and rebuild from events.

The Read Side: Projections and Read Models

The write side appends events. The read side subscribes to the event stream and maintains query-optimized read models.

This split — often called CQRS, Command Query Responsibility Segregation — means the data structure you write is different from the data structure you read. The write side is optimized for consistency and correctness. The read side is optimized for query performance.

# A read model maintained by a projection
class PaymentHistoryProjection:
    """
    Maintains a query-optimized view of payment history.
    Updated by processing events from all channel streams.
    """

    def __init__(self, database):
        self.db = database

    def handle(self, event: dict) -> None:
        event_type = event['event_type']

        if event_type == 'HTLCSettled':
            self.db.execute(
                """
                INSERT INTO payment_history
                    (payment_hash, channel_id, amount_sat, direction, settled_at)
                VALUES (?, ?, ?, ?, ?)
                """,
                (
                    event['htlc']['payment_hash'],
                    event['channel_id'],
                    event['htlc']['amount_sat'],
                    'outgoing',
                    event['occurred_at']
                )
            )

        if event_type == 'HTLCReceived':
            self.db.execute(
                """
                INSERT INTO payment_history
                    (payment_hash, channel_id, amount_sat, direction, settled_at)
                VALUES (?, ?, ?, ?, ?)
                """,
                (
                    event['htlc']['payment_hash'],
                    event['channel_id'],
                    event['htlc']['amount_sat'],
                    'incoming',
                    event['occurred_at']
                )
            )

Read models are disposable. If you change a projection's logic, you rebuild the read model from scratch by replaying the event stream. The events are durable; the read model is a cache.

Event Versioning: The Hard Problem

Event sourcing has one genuinely difficult problem: event schema evolution. Once you have appended an event to the store, it is immutable. If you later decide the event schema was wrong, you cannot change the stored events.

Greg Young's treatment of this problem identifies several strategies:

Weak schema: Store events as JSON with minimal structure. Add fields freely; never remove or rename. Old event handlers ignore fields they do not understand. New handlers provide defaults for missing fields.

def apply_htlc_added(state: ChannelState, event: dict) -> ChannelState:
    htlc = event['htlc']
    # New field added in v2 — provide default if missing
    routing_fee = htlc.get('routing_fee_sat', 0)
    # ... rest of handler

Upcasting: When loading events, transform old versions to the current schema before processing. The event store stores the original; the upcast is applied in memory at load time.

def upcast_htlc_added(event: dict) -> dict:
    """Transform v1 HTLCAdded events to v2 schema."""
    if event.get('schema_version', 1) == 1:
        event = {**event, 'htlc': {**event['htlc'], 'routing_fee_sat': 0}}
        event['schema_version'] = 2
    return event

Copy-and-transform: Migrate the entire event store to a new stream with transformed events. Expensive but produces a clean schema. Requires careful coordination in production.

The decision of which strategy to use depends on how frequently your schema changes and how far back your replay needs to go. For systems expected to run for years, weak schema or upcasting is usually the right choice. Copy-and-transform is reserved for major structural changes.

What This Changes About How You Debug

The practical benefit that most developers notice first is not auditability or temporal queries. It is that production bugs become reproducible.

In a mutable state system, a production bug leaves behind only the final state. You have to reconstruct what happened from logs, from user reports, from intuition. Often you cannot reproduce it.

In an event-sourced system, a production bug leaves behind the complete event stream that caused it. You copy that stream into a test environment, replay it against the fixed code, and verify the fix. The bug is reproducible by definition.

This is not a secondary concern. The debugging loop, reproduce, fix, verify, is the core of production engineering. An architecture that makes reproduction possible changes the economics of debugging.

HTLC Expiry and Force Close: The Most Dangerous Moments in Lightning

Aturo Phil — Fri, 17 Jul 2026 03:44:01 +0000

Most Lightning Network tutorials explain what an HTLC is. Almost none explain what happens when one expires. That gap is where real money is lost.

This post is about the specific block heights, the fee races, and the protocol rules that govern the most operationally dangerous scenarios in a Lightning node. Understanding this is not optional if you are running a node in production.

What an HTLC Actually Is

A Hash Time-Locked Contract is a conditional payment output sitting inside a commitment transaction. It says: pay this amount to whoever can present the preimage of hash H, but only until block N. After block N, the funds return to the party that offered the HTLC.

In Lightning, HTLCs live in an off-chain commitment transaction that both parties hold. That transaction is valid and can be broadcast to the Bitcoin chain at any time. The critical property is that the time-lock (cltv_expiry) in the HTLC is a real Bitcoin block height, enforced by the chain if the commitment transaction is ever published.

The HTLC output in a commitment transaction looks like this:

OP_DUP OP_HASH160 <RIPEMD160(SHA256(payment_hash))> OP_EQUALVERIFY OP_CHECKSIG

But the full script is more complex. An offered HTLC output, as defined in BOLT 3, has two spending paths:

The recipient presents the preimage before cltv_expiry — payment succeeds
The offerer reclaims after cltv_expiry and a relative delay — payment fails

The relative delay (to_self_delay) is a separate CSV constraint that prevents the offerer from immediately reclaiming. It gives the counterparty time to contest a revoked commitment transaction.

The Expiry Problem

In a routed payment, you are both an HTLC offerer (to the next hop) and an HTLC recipient (from the previous hop). These two positions have different expiry heights, and the difference between them is the CLTV delta.

Alice --[expiry: 800]-- Bob --[expiry: 780]-- Carol

Bob's safety window is 20 blocks. If Carol does not reveal the preimage by block 780, Bob must act before block 800 or he cannot reclaim the funds he forwarded.

This is the expiry problem. Bob has a deadline. If Carol settles off-chain, Bob receives the preimage and can settle upstream with Alice. But if Carol goes offline or becomes unresponsive, Bob must go on-chain before his own expiry.

BOLT 5 is explicit about this obligation:

A node MUST fail the channel if an outgoing HTLC's cltv_expiry is not met by the fulfillment deadline.

The fulfillment deadline is not the expiry block itself. BOLT 2 defines cltv_expiry_delta minimums and BOLT 11 defines default values (40 blocks for most implementations), but the safe window for on-chain action is considerably tighter than the raw delta suggests, because Bitcoin block times are probabilistic and fees can delay confirmation.

When On-Chain Action Is Required

Your node must go on-chain in two situations:

Outgoing HTLC timeout: You offered an HTLC to the next hop and that HTLC is approaching its expiry. The counterparty has not provided the preimage. You must broadcast your local commitment transaction and then claim the HTLC output via the timeout path.

Incoming HTLC with a revealed preimage: You received the preimage from downstream but the upstream peer is unresponsive. You must claim the HTLC output on-chain to receive the funds.

Both require broadcasting a commitment transaction, which triggers a force close.

Force Close: What Actually Happens

A force close is the unilateral publication of your local commitment transaction. There is no negotiation. You broadcast the transaction and let the chain settle the state.

Here is what happens step by step:

Step 1: Broadcast the commitment transaction

Your local commitment transaction has two types of outputs:

to_local: your balance, encumbered by to_self_delay (you cannot spend it immediately)
to_remote: the counterparty's balance, spendable immediately by them
Zero or more HTLC outputs

Commitment Transaction
├── to_local (your balance, CSV-locked)
├── to_remote (counterparty balance, immediately spendable)
├── offered HTLC 1 (you offered, counterparty can claim with preimage)
└── received HTLC 2 (counterparty offered, you can claim with preimage)

Step 2: Handle each HTLC output

Each HTLC output requires a second-stage transaction. You cannot spend HTLC outputs directly from the commitment transaction in a single step (with anchor channels there are further complications — see below).

For an offered HTLC that is timing out:

# HTLC-Timeout transaction
# Input: offered HTLC output from commitment transaction
# Sequence: 0 (no relative delay on input)
# Output: HTLC-delayed output, encumbered by to_self_delay

# This transaction requires:
# - A valid signature from your HTLC key
# - The cltv_expiry block to have passed (absolute lock time)
# - Confirmation before your upstream expiry

For a received HTLC where you have the preimage:

# HTLC-Success transaction
# Input: received HTLC output from commitment transaction
# Output: HTLC-delayed output, encumbered by to_self_delay

# This transaction requires:
# - A valid signature from your HTLC key
# - The payment preimage
# - No absolute lock time constraint (can confirm any time)

Step 3: Claim delayed outputs

After to_self_delay blocks have passed since the commitment transaction confirmed, you can claim your to_local output and the outputs from your HTLC second-stage transactions.

The Fee Race

Here is where many operators underestimate the risk. HTLC-Timeout transactions have an absolute lock time (nLockTime) set to cltv_expiry. They cannot be mined before that block. But once that block passes, you are racing to get the transaction confirmed before your upstream expiry.

In a fee market with high mempool pressure, this is a real race. A 20-block CLTV delta provides only 200 minutes of slack on average, and Bitcoin block times are not uniform. During periods of fee volatility, a 20-block window can mean you are competing against other transactions with significantly higher fees.

The implication for node operators: CLTV deltas that seemed generous in a low-fee environment become dangerous in a high-fee environment. The Lightning specification allows for this with min_final_cltv_expiry_delta, but many implementations historically used values that provide insufficient safety margin under adversarial or fee-spike conditions.

Practical recommendations:

Use at minimum a 40-block cltv_expiry_delta for routing nodes
Configure your fee estimation to use a 6-block target for HTLC-Timeout and HTLC-Success transactions
Monitor your mempool. A full mempool means your fee estimate from last hour may be stale
Automate alerts for HTLCs within 50 blocks of expiry

Anchor Outputs: How They Changed This

In 2020, Lightning implementations adopted anchor outputs (BOLT 3 update). The key change for force close is that HTLC transactions are no longer required to carry pre-committed fee rates. Instead:

The commitment transaction has two anchor outputs (one per party), each 330 satoshis
HTLC second-stage transactions have SIGHASH_SINGLE | SIGHASH_ANYONECANPAY signatures
This allows fee bumping via CPFP (child-pays-for-parent) at broadcast time

Before anchors, fees on HTLC transactions were negotiated at channel open and locked in at signing. If the fee market moved significantly, you might broadcast a transaction that would never confirm. Anchors solve this by deferring fee decisions to broadcast time.

Here is how CPFP works in this context:

# Your HTLC-Timeout transaction is in the mempool with a low fee rate
# You create a child transaction spending your anchor output
# The child carries enough fee to pull the parent into the next block

def calculate_cpfp_fee(
    parent_vsize: int,
    parent_fee: int,
    child_vsize: int,
    target_fee_rate: float  # sat/vbyte
) -> int:
    # Total fee needed for the package
    total_package_fee = (parent_vsize + child_vsize) * target_fee_rate
    # Child must cover the deficit
    child_fee = total_package_fee - parent_fee
    return max(0, int(child_fee))

# Example
parent_vsize = 663  # typical HTLC-Timeout
parent_fee = 1500   # low fee from old estimate
child_vsize = 150   # anchor spend
target_rate = 25.0  # sat/vbyte, current mempool

child_fee = calculate_cpfp_fee(parent_vsize, parent_fee, child_vsize, target_rate)
# child_fee = (663 + 150) * 25 - 1500 = 20325 - 1500 = 18825 sat

The tradeoff is complexity. Anchor channels require watching for both commitment transactions and HTLC outputs, and your wallet must maintain UTXOs suitable for anchor spending.

Justice Transactions: The Other Side of This

When your counterparty broadcasts a revoked commitment transaction, one that represents an older state, you have a limited window to claim all their funds as a penalty. This is the justice transaction, sometimes called the breach remedy.

The window is exactly to_self_delay blocks. Your counterparty's to_local output is CSV-locked for that many blocks. If you detect the revoked transaction and broadcast a justice transaction within that window, you take everything: their balance, your balance, and all HTLC outputs.

This is why channel watchtowers exist. If your node is offline when your counterparty broadcasts a revoked state, you lose the justice window.

LND exposes this via the watchtower client:

# Register an external watchtower
lncli wtclient add --uri <pubkey>@<host>:<port>

# Check registered towers
lncli wtclient towers

# The tower watches your channels and broadcasts justice transactions
# if a breach is detected while your node is offline

The justice transaction spends from the same commitment transaction:

Justice Transaction
├── Input: to_local (with revocation key, no CSV delay required)
├── Input: HTLC 1 output (with revocation key)
├── Input: HTLC 2 output (with revocation key)
└── Output: to your address (all funds)

The revocation key is computed from the revocation base point and the per-commitment secret, which your counterparty revealed when they moved to the next commitment state. BOLT 3 specifies the exact derivation.

Monitoring What Matters

An implementation that does not monitor block height against HTLC expiry deadlines will lose money. The minimum viable monitoring loop:

import asyncio
from dataclasses import dataclass

@dataclass
class PendingHTLC:
    payment_hash: str
    direction: str          # 'offered' or 'received'
    cltv_expiry: int        # absolute block height
    amount_msat: int
    channel_id: str

async def monitor_htlc_expiry(
    get_block_height,
    get_pending_htlcs,
    trigger_force_close,
    safety_buffer: int = 50  # blocks before expiry to act
):
    while True:
        current_height = await get_block_height()
        pending = await get_pending_htlcs()

        for htlc in pending:
            if htlc.direction == 'offered':
                blocks_remaining = htlc.cltv_expiry - current_height
                if blocks_remaining <= safety_buffer:
                    print(
                        f"WARNING: Offered HTLC {htlc.payment_hash[:16]} "
                        f"expires in {blocks_remaining} blocks. "
                        f"Amount: {htlc.amount_msat} msat. "
                        f"Channel: {htlc.channel_id}"
                    )
                    if blocks_remaining <= 20:
                        # Critical: initiate force close
                        await trigger_force_close(htlc.channel_id)

        await asyncio.sleep(30)  # check every ~30 seconds

A 50-block buffer before acting is conservative but defensible. The exact value depends on your CLTV delta configuration and your confidence in fee estimation.

What Implementations Do

LND has an on-chain watcher (chainwatcher.go) that subscribes to new blocks and evaluates HTLC states against current height. It initiates force close when an outgoing HTLC is within OutgoingBroadcastDelta blocks of expiry. The default value is 10 blocks which is lower than many operators realize.

Core Lightning uses a plugin hook system where the onchaind daemon manages all on-chain state, including HTLC resolution. CLN was earlier to adopt anchor outputs and has separate handling for pre-anchor and anchor-style commitments.

LDK takes a different approach. It is a library rather than a daemon, so HTLC expiry handling is the responsibility of the consuming application. LDK provides ChannelMonitor objects that must be fed new blocks by the application, and it generates Events that the application must handle, including HTLCHandlingFailed and SpendableOutputs. If you are building on LDK, you own the loop.

What to Take Away

The HTLC expiry mechanism is what makes Lightning secure. It is also what makes Lightning operationally demanding. The key points:

Every pending HTLC has a deadline. The deadline is a real Bitcoin block height.
When the deadline approaches and the payment is unresolved, you must go on-chain.
Going on-chain triggers a force close and a sequence of second-stage transactions.
Fee estimation at broadcast time matters. Anchor outputs give you flexibility; you must use it.
The justice window is real. Watchtowers are not optional if your node has downtime.
LDK puts the responsibility on you explicitly. Other implementations handle it internally, but you should understand what they are doing.

The block height is the ground truth. Everything else is coordination on top of it.

Lightning Network Development in 2026: LND v0.21, Quantum-Resistant Channels, and Building on the Stack Today

Aturo Phil — Thu, 16 Jul 2026 14:57:49 +0000

Bitcoin Development Series, Part 4 of 4

The Lightning Network has had a quieter 2026 than its 2022–2023 growth years, but the development activity underneath the surface is some of the most consequential the protocol has seen. Two major releases dropped in the past two months: LND v0.21 from Lightning Labs and Core Lightning 26.06 from Blockstream, the latter shipping a feature whose name alone signals where the industry is heading, quantum-resistant Lightning channels.

This post covers what is new in both implementations, the technical foundations of how Lightning works, and what you need to know to build on the stack today.

How a Lightning Channel Works: The Basics for Developers

Before getting into what is new, let's have a grounding in the mechanics. A Lightning channel is a 2-of-2 multisig output on the Bitcoin base layer. The two parties hold a sequence of commitment transactions, off-chain transactions that reflect the current balance split between them. Neither party broadcasts these unless the channel is being closed.

When Alice pays Bob through a channel, they exchange new signed commitment transactions reflecting the updated balances, and invalidate the old ones using a penalty mechanism (revocation keys). No on-chain transaction happens. This is the core throughput gain: thousands of payments can flow through a channel with only two on-chain transactions (open and close).

# Simplified channel state model

from dataclasses import dataclass

@dataclass
class ChannelState:
    channel_id:       str
    local_balance_sat:  int   # our side
    remote_balance_sat: int   # counterparty side
    capacity_sat:       int
    commitment_number:  int   # increments with every update

    def can_send(self, amount_sat: int) -> bool:
        # Reserve 1% for channel reserve requirement
        reserve = self.capacity_sat // 100
        available = self.local_balance_sat - reserve
        return available >= amount_sat

    def update(self, amount_sat: int, direction: str) -> "ChannelState":
        if direction == "send":
            if not self.can_send(amount_sat):
                raise ValueError(f"Insufficient local balance. Available: {self.local_balance_sat}")
            return ChannelState(
                channel_id=self.channel_id,
                local_balance_sat=self.local_balance_sat - amount_sat,
                remote_balance_sat=self.remote_balance_sat + amount_sat,
                capacity_sat=self.capacity_sat,
                commitment_number=self.commitment_number + 1,
            )
        elif direction == "receive":
            return ChannelState(
                channel_id=self.channel_id,
                local_balance_sat=self.local_balance_sat + amount_sat,
                remote_balance_sat=self.remote_balance_sat - amount_sat,
                capacity_sat=self.capacity_sat,
                commitment_number=self.commitment_number + 1,
            )
        raise ValueError(f"Unknown direction: {direction}")

# Example
ch = ChannelState(
    channel_id="abc123",
    local_balance_sat=500_000,
    remote_balance_sat=500_000,
    capacity_sat=1_000_000,
    commitment_number=0,
)

ch = ch.update(100_000, "send")
print(f"After sending 100k sats:")
print(f"  Local:  {ch.local_balance_sat:,} sat")
print(f"  Remote: {ch.remote_balance_sat:,} sat")
print(f"  Commitment #: {ch.commitment_number}")

Payments across multiple hops use HTLCs (Hash Time-Locked Contracts) — conditional payments that are only claimable if the recipient reveals a preimage, and that expire if not claimed within a certain number of blocks.

What Is New: LND v0.21

Lightning Labs released LND v0.21 in June 2026. The headline themes were reliability, speed, and security hardening, a "grown up" release compared to the feature-heavy v0.20 cycle.

Key developer-relevant changes:

HTLC CLTV delta improvements: More intelligent handling of expiry deltas to reduce the risk of force-close cascades during mempool fee spikes.
Improved MPP (Multi-Path Payments): The router now better handles splitting payments across multiple paths, reducing failures on larger payments.
gRPC streaming for channel events: Real-time channel state updates without polling.
AMP (Atomic Multi-Path) support in QueryRoutes and BuildRoute: A long-awaited PR (#10801) adds AMP record support to these RPCs, making it possible to build AMP-aware routing tools without rewriting the payment lifecycle from scratch.

Connecting to LND via gRPC (Go)

package main

import (
    "context"
    "encoding/hex"
    "fmt"
    "log"
    "os"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "gopkg.in/macaroon.v2"

    lnrpc "github.com/lightningnetwork/lnd/lnrpc"
)

func loadMacaroon(path string) (string, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return "", err
    }
    mac := &macaroon.Macaroon{}
    if err := mac.UnmarshalBinary(data); err != nil {
        return "", err
    }
    macBytes, err := mac.MarshalBinary()
    if err != nil {
        return "", err
    }
    return hex.EncodeToString(macBytes), nil
}

func main() {
    tlsCert, err := credentials.NewClientTLSFromFile("/home/user/.lnd/tls.cert", "")
    if err != nil {
        log.Fatalf("failed to load TLS cert: %v", err)
    }

    conn, err := grpc.Dial(
        "localhost:10009",
        grpc.WithTransportCredentials(tlsCert),
    )
    if err != nil {
        log.Fatalf("failed to connect: %v", err)
    }
    defer conn.Close()

    client := lnrpc.NewLightningClient(conn)

    ctx := context.Background()
    info, err := client.GetInfo(ctx, &lnrpc.GetInfoRequest{})
    if err != nil {
        log.Fatalf("GetInfo failed: %v", err)
    }

    fmt.Printf("Node alias:        %s\n", info.Alias)
    fmt.Printf("Public key:        %s\n", info.IdentityPubkey)
    fmt.Printf("Active channels:   %d\n", info.NumActiveChannels)
    fmt.Printf("Pending channels:  %d\n", info.NumPendingChannels)
    fmt.Printf("Block height:      %d\n", info.BlockHeight)
    fmt.Printf("Synced to chain:   %v\n", info.SyncedToChain)
}

Subscribing to Channel Events (gRPC Streaming)

stream, err := client.SubscribeChannelEvents(ctx, &lnrpc.ChannelEventSubscription{})
if err != nil {
    log.Fatalf("SubscribeChannelEvents failed: %v", err)
}

for {
    event, err := stream.Recv()
    if err != nil {
        log.Printf("stream error: %v", err)
        break
    }
    switch event.Type {
    case lnrpc.ChannelEventUpdate_OPEN_CHANNEL:
        ch := event.GetOpenChannel()
        fmt.Printf("Channel opened: %s | capacity: %d sat\n",
            ch.ChannelPoint, ch.Capacity)
    case lnrpc.ChannelEventUpdate_CLOSED_CHANNEL:
        ch := event.GetClosedChannel()
        fmt.Printf("Channel closed: %s | type: %s\n",
            ch.ChannelPoint, ch.CloseType)
    case lnrpc.ChannelEventUpdate_ACTIVE_CHANNEL:
        fmt.Printf("Channel became active: %v\n", event.GetActiveChannel())
    case lnrpc.ChannelEventUpdate_INACTIVE_CHANNEL:
        fmt.Printf("Channel went inactive: %v\n", event.GetInactiveChannel())
    }
}

What Is New: Core Lightning 26.06 — Quantum-Resistant Channels

Blockstream's Core Lightning released v26.06 in June 2026 with the headline feature of quantum-resistant Lightning channels the first Lightning implementation to do so, and it follows NEAR Protocol's base-layer quantum-safe signing that shipped on July 13 (covered in Part 1 of this series).

The implementation uses a hybrid approach: existing ECDSA/Schnorr signatures are retained for backwards compatibility with the current network, while a post-quantum signature scheme is layered on top for new channel types. A channel opened with a quantum-resistant peer uses both signature schemes, the classical one for network-wide compatibility and the PQ scheme as an additional binding that quantum-safe nodes can verify.

This is the same hybrid pattern NIST recommends for post-quantum migration: do not rip out classical crypto, add PQ on top and transition gradually.

Other notable 26.06 changes:

graceful command: prepares a node for shutdown by closing channels cooperatively before stopping, reducing force-close fees.
Improved channel policy automation - fee rate adjustments based on liquidity depth without manual intervention.

Sending a Payment via Core Lightning (Python + pyln-client)

pip install pyln-client

from pyln.client import LightningRpc
import json

# Core Lightning uses a Unix socket for its RPC interface
rpc = LightningRpc("/home/user/.lightning/bitcoin/lightning-rpc")

def get_node_info() -> dict:
    info = rpc.getinfo()
    return {
        "id":              info["id"],
        "alias":           info.get("alias", ""),
        "num_peers":       info["num_peers"],
        "num_channels":    info["num_active_channels"],
        "block_height":    info["blockheight"],
        "version":         info["version"],
    }

def list_channels() -> list[dict]:
    channels = rpc.listchannels()["channels"]
    return [
        {
            "source":        ch["source"],
            "destination":   ch["destination"],
            "capacity_sat":  ch["satoshis"],
            "active":        ch["active"],
            "base_fee_msat": ch["base_fee_millisatoshi"],
            "fee_ppm":       ch["fee_per_millionth"],
        }
        for ch in channels[:10]   # first 10 for brevity
    ]

def pay_invoice(bolt11: str) -> dict:
    """
    Pay a BOLT-11 invoice.
    CLN returns payment details including preimage on success.
    """
    result = rpc.pay(bolt11)
    return {
        "status":          result["status"],
        "amount_sent_msat": result.get("amount_sent_msat"),
        "preimage":        result.get("payment_preimage"),
        "destination":     result.get("destination"),
    }

print(get_node_info())

Creating and Paying Invoices Programmatically

def create_invoice(amount_msat: int, description: str, expiry_seconds: int = 3600) -> dict:
    """
    Generate a BOLT-11 invoice on this node.
    amount_msat: amount in millisatoshis (1 sat = 1000 msat)
    """
    label = f"invoice-{hash(description)}"
    result = rpc.invoice(
        amount_msat=amount_msat,
        label=label,
        description=description,
        expiry=expiry_seconds,
    )
    return {
        "bolt11":      result["bolt11"],
        "payment_hash": result["payment_hash"],
        "expires_at":  result["expires_at"],
    }

# Create a 10,000 sat invoice
invoice = create_invoice(
    amount_msat=10_000_000,   # 10,000 sats = 10,000,000 msat
    description="Test payment from post",
)
print("Invoice:", invoice["bolt11"][:60], "...")

Routing Fees and Liquidity Management

One of the persistent engineering challenges in Lightning is liquidity management, channels become unbalanced over time as payments flow preferentially in one direction. A channel where all the liquidity is on one side cannot route payments in the other direction, making it useless for half the traffic.

def analyze_channel_balance_health(rpc_conn: LightningRpc) -> list[dict]:
    """
    Flags channels where local balance is heavily skewed,
    which indicates a need for rebalancing.
    """
    funds   = rpc_conn.listfunds()
    channels = funds.get("channels", [])

    issues = []
    for ch in channels:
        total = ch["our_amount_msat"] + ch["amount_msat"]
        if total == 0:
            continue

        local_pct = (ch["our_amount_msat"] / total) * 100

        if local_pct < 10:
            status = "depleted"       # almost no outbound capacity
        elif local_pct > 90:
            status = "saturated"      # almost no inbound capacity
        else:
            status = "healthy"

        issues.append({
            "peer_id":     ch.get("peer_id", "unknown")[:20],
            "local_pct":   round(local_pct, 1),
            "status":      status,
            "local_sat":   ch["our_amount_msat"] // 1000,
            "remote_sat":  ch["amount_msat"] // 1000,
        })

    return sorted(issues, key=lambda x: x["local_pct"])

# Channels where local_pct < 10 or > 90 need rebalancing

Rebalancing is done by routing a circular payment: paying yourself through a path that exits on the saturated channel and returns on the depleted one. Both LND and CLN have built-in or plugin-based rebalancing tools, but understanding the mechanics matters when you are building systems that monitor channel health automatically.

The BOLT Specification: Where Protocol Changes Come From

Lightning's cross-implementation compatibility is maintained through the BOLT (Basis of Lightning Technology) specifications. Any change that affects how two different implementations interoperate: LND, CLN, Eclair, LDK, must go through the BOLT process.

Current active areas of BOLT development in 2026:

Taproot channels (BOLT 3 update): Upgrading the on-chain commitment transaction structure to use Taproot outputs, which reduces the on-chain footprint of cooperative closes and improves privacy by making Lightning channels indistinguishable from ordinary Taproot spends.
Route blinding (BOLT 4 update): Allows a recipient to hide their node identity from the sender while still receiving payments, critical for payment privacy.
BOLT 12 (Offers): A more expressive invoice format that supports recurring payments, refunds, and metadata, without requiring a new invoice for every payment. Slowly rolling out across implementations.

# Decode a BOLT 12 offer (requires CLN's decode RPC)

def decode_bolt12_offer(rpc_conn: LightningRpc, offer_string: str) -> dict:
    """
    BOLT 12 offers are reusable payment endpoints — unlike BOLT 11 invoices,
    the same offer string can be used to request multiple invoices over time.
    """
    result = rpc_conn.decode(offer_string)
    return {
        "type":          result.get("type"),
        "valid":         result.get("valid"),
        "description":   result.get("description"),
        "node_id":       result.get("node_id", "")[:20] + "...",
        "currency":      result.get("currency", "bitcoin"),
        "amount_msat":   result.get("amount_msat"),
    }

The Bigger Picture: Why Lightning Development Matters Now

Lightning is the primary answer to Bitcoin's throughput ceiling. The base layer processes roughly 7 transactions per second. Lightning, in theory, scales to millions of payments per second, the constraint is liquidity routing and channel management, not raw throughput.

With institutional adoption accelerating (Strategy's banking index, Morgan Stanley's ETF filings, DTCC's tokenization push), the pressure for Bitcoin to function as a payment network, not just a store of value, is growing. Lightning is the only production-ready answer to that. The quantum-resistance work in CLN 26.06 is particularly significant: it is the protocol community taking a 10–15 year horizon seriously, rather than just shipping features for the current market cycle.

If you are building anything that touches Bitcoin payments at the application layer, Lightning is no longer optional reading.

Post-Halving Bitcoin Mining Economics: What Changed for Protocol Developers

Aturo Phil — Thu, 16 Jul 2026 14:13:58 +0000

Bitcoin Development Series, Part 3 of 4

The April 2024 halving dropped Bitcoin's block subsidy from 6.25 BTC to 3.125 BTC. Two years on, the economic consequences for miners have stabilized into a new baseline and that baseline changes how you should think about mempool dynamics, fee estimation, and transaction throughput if you are building anything on or near the Bitcoin protocol.

This post covers what permanently changed, what it means for developers, and how to query the data yourself.

What the Halving Actually Did

Before the halving, miners earned a guaranteed 6.25 BTC per block regardless of how many transactions were in it. Fees were supplemental. After the halving, that guarantee dropped to 3.125 BTC and at current prices, the difference represents roughly $190,000 per block in lost guaranteed revenue at a $61,000 BTC price.

The economic effect was not subtle. Three things followed:

Miners with high electricity costs or older ASIC hardware became unprofitable and either shut down or sold their operations to larger players. The mining industry consolidated.
Fee revenue became structurally more important. Miners now have a stronger financial incentive to prioritize high-fee transactions and, crucially, to keep blocks full.
The Ordinals and Runes wave of 2024–2025 was partly a direct response to this, high-fee, data-heavy transactions that padded miner revenue at a time when the subsidy halved.

# Block reward breakdown: pre vs post halving

def block_revenue(btc_price: float, subsidy_btc: float, avg_fee_btc: float) -> dict:
    subsidy_usd = subsidy_btc * btc_price
    fee_usd     = avg_fee_btc * btc_price
    total_usd   = subsidy_usd + fee_usd
    fee_pct     = (fee_usd / total_usd) * 100

    return {
        "subsidy_btc":  subsidy_btc,
        "avg_fee_btc":  avg_fee_btc,
        "subsidy_usd":  round(subsidy_usd, 2),
        "fee_usd":      round(fee_usd, 2),
        "total_usd":    round(total_usd, 2),
        "fee_share_pct": round(fee_pct, 2),
    }

BTC_PRICE = 65_000

pre_halving  = block_revenue(BTC_PRICE, subsidy_btc=6.25,  avg_fee_btc=0.08)
post_halving = block_revenue(BTC_PRICE, subsidy_btc=3.125, avg_fee_btc=0.08)

print("Pre-halving: ", pre_halving)
print("Post-halving:", post_halving)

# Pre-halving:  {'subsidy_btc': 6.25,  ..., 'total_usd': 411250.0, 'fee_share_pct': 1.26}
# Post-halving: {'subsidy_btc': 3.125, ..., 'total_usd': 208250.0, 'fee_share_pct': 2.50}

Fee share effectively doubled as a percentage of total miner revenue. That ratio will keep climbing into the next halving in 2028.

What This Means for Fee Estimation

Fee estimation is harder than it looks. The naive approach is to look at the last few blocks and pick a fee rate in the middle, this breaks down during fee spikes because mempool backlogs can form and clear faster than your estimate refreshes.

Bitcoin Core uses a statistical model that tracks how long transactions at different fee rates take to confirm, across historical blocks. If you are building a wallet, exchange, or any system that constructs transactions, you should either call this directly or use a service that does.

Querying Fee Estimates via Bitcoin Core RPC

from bitcoinrpc.authproxy import AuthServiceProxy

RPC_URL = "http://rpcuser:rpcpassword@127.0.0.1:8332"

def get_fee_estimates() -> dict:
    rpc = AuthServiceProxy(RPC_URL)

    # estimatesmartfee returns sat/vByte estimate for N-block confirmation target
    # CONSERVATIVE mode is safer for time-sensitive transactions
    targets = {
        "next_block":    rpc.estimatesmartfee(1,  "CONSERVATIVE"),
        "3_blocks":      rpc.estimatesmartfee(3,  "CONSERVATIVE"),
        "6_blocks":      rpc.estimatesmartfee(6,  "ECONOMICAL"),
        "next_day":      rpc.estimatesmartfee(144, "ECONOMICAL"),
    }

    result = {}
    for label, est in targets.items():
        if "feerate" in est:
            # feerate is in BTC/kB; convert to sat/vByte
            feerate_btc_per_kb  = est["feerate"]
            feerate_sat_per_vb  = feerate_btc_per_kb * 100_000  # 1 BTC/kB = 100 sat/vB
            result[label] = {
                "sat_per_vbyte": round(feerate_sat_per_vb, 1),
                "blocks":        est.get("blocks"),
            }
        else:
            result[label] = {"error": est.get("errors")}

    return result

print(get_fee_estimates())

Querying Fee Estimates Without a Node

import httpx

def get_mempool_fee_estimates() -> dict:
    """
    mempool.space provides real-time fee estimates
    without requiring a local node.
    """
    resp = httpx.get("https://mempool.space/api/v1/fees/recommended")
    resp.raise_for_status()
    fees = resp.json()

    # Response fields (all in sat/vByte):
    # fastestFee   — likely to confirm in next 1-2 blocks
    # halfHourFee  — likely within ~3 blocks
    # hourFee      — likely within ~6 blocks
    # economyFee   — low priority, may wait hours
    # minimumFee   — floor for relay

    return fees

print(get_mempool_fee_estimates())
# => {'fastestFee': 12, 'halfHourFee': 10, 'hourFee': 8, 'economyFee': 4, 'minimumFee': 1}

Monitoring Mempool Depth

Mempool depth tells you how congested the network is at any moment. During high-fee periods (NFT mints, protocol launches, macro news events), the mempool can balloon to hundreds of MB and fee rates can spike 10–50x within minutes.

import httpx
from datetime import datetime

def get_mempool_stats() -> dict:
    resp = httpx.get("https://mempool.space/api/mempool")
    resp.raise_for_status()
    data = resp.json()

    vsize_mb = data["vsize"] / 1_000_000

    return {
        "tx_count":        data["count"],
        "total_size_mb":   round(vsize_mb, 2),
        "total_fee_btc":   round(data["total_fee"] / 100_000_000, 6),
        "congestion":      classify_congestion(vsize_mb),
        "timestamp":       datetime.utcnow().isoformat(),
    }

def classify_congestion(vsize_mb: float) -> str:
    if vsize_mb < 2:
        return "low"       # fees at minimum, confirms fast
    elif vsize_mb < 50:
        return "moderate"  # some backlog, est. fees reliable
    elif vsize_mb < 200:
        return "high"      # spike in progress, use fastestFee
    else:
        return "severe"    # mempool full, only high-fee txs get in

print(get_mempool_stats())

Tracking Fee Revenue Per Block

If you want to track how fee dependency is evolving over time, here is how to calculate actual fee revenue per block:

import httpx

def get_recent_block_fee_stats(num_blocks: int = 10) -> list[dict]:
    """
    Fetches recent blocks and computes fee revenue and subsidy breakdown.
    Uses mempool.space block API.
    """
    resp   = httpx.get("https://mempool.space/api/v1/blocks")
    resp.raise_for_status()
    blocks = resp.json()[:num_blocks]

    stats = []
    for block in blocks:
        subsidy_sats    = block.get("reward", 0) - block.get("totalFees", 0)
        fee_sats        = block.get("totalFees", 0)
        total_sats      = block.get("reward", 0)
        fee_share       = (fee_sats / total_sats * 100) if total_sats else 0
        avg_fee_rate    = block.get("extras", {}).get("avgFeeRate", None)

        stats.append({
            "height":          block["height"],
            "subsidy_btc":     round(subsidy_sats / 1e8, 8),
            "fee_btc":         round(fee_sats / 1e8, 8),
            "total_reward_btc": round(total_sats / 1e8, 8),
            "fee_share_pct":   round(fee_share, 2),
            "avg_fee_rate_sat_vb": avg_fee_rate,
            "tx_count":        block.get("tx_count"),
        })

    return stats

for block in get_recent_block_fee_stats(5):
    print(block)

The Long-Term Implication: Fee Market Maturity

Each halving compresses subsidy revenue and increases the weight of fees in miner economics. At the 2028 halving, the subsidy will drop to 1.5625 BTC. At 2032, it will be 0.78125 BTC.

The long-term security model of Bitcoin depends entirely on fees being sufficient to incentivize honest mining once the subsidy becomes negligible. That is not a solved problem. It is the reason the Ordinals debate is not just cultural, high-throughput data embedding increases fee density, which helps miners. Restricting it, as BIP-110 proposes, removes a source of fee revenue at exactly the period in Bitcoin's lifecycle when fee revenue matters most.

# Project subsidy and fee revenue requirements over future halvings

def halving_projection(btc_price: float, target_miner_revenue_usd: float) -> list[dict]:
    """
    Projects how much fee revenue per block miners would need
    to maintain a given total USD revenue target at each halving.
    """
    subsidy = 3.125  # current post-2024 halving
    rows    = []

    for halving in range(5):   # next 5 halvings
        subsidy_usd       = subsidy * btc_price
        required_fee_usd  = target_miner_revenue_usd - subsidy_usd
        required_fee_btc  = required_fee_usd / btc_price

        rows.append({
            "halving_number":       halving + 4,  # we are at halving #4 now
            "block_subsidy_btc":    round(subsidy, 8),
            "subsidy_usd":          round(subsidy_usd, 2),
            "fee_needed_usd":       round(max(required_fee_usd, 0), 2),
            "fee_needed_btc":       round(max(required_fee_btc, 0), 8),
        })
        subsidy /= 2

    return rows

TARGET_USD_PER_BLOCK = 200_000   # roughly today's total miner revenue at $65k BTC

for row in halving_projection(65_000, TARGET_USD_PER_BLOCK):
    print(row)

# Output:
# {'halving_number': 4, 'block_subsidy_btc': 3.125,   'subsidy_usd': 203125.0, 'fee_needed_usd': 0,        ...}
# {'halving_number': 5, 'block_subsidy_btc': 1.5625,  'subsidy_usd': 101562.5, 'fee_needed_usd': 98437.5,  ...}
# {'halving_number': 6, 'block_subsidy_btc': 0.78125, 'subsidy_usd': 50781.25, 'fee_needed_usd': 149218.75,...}
# ...

At halving #5 (2028), miners would need roughly $98,000 per block in fees alone just to match today's total revenue at current prices. That is not a catastrophe, it is a design constraint that the ecosystem will have to grow into. But it frames every current argument about block space usage in a completely different light.

DEV Community: Aturo Phil

PSBT: Collaborative Bitcoin Transactions

The Problem PSBT Solves

The PSBT Format

The PSBT Lifecycle

Real Workflow: 2-of-3 Multisig with Hardware Wallets

PSBT v2 (BIP 370)

Using PSBT with Bitcoin Core

Where PSBT Is Used Today

Further Reading

Bitcoin Script from First Principles

What Bitcoin Script Is

The Stack in Detail

Data Push Opcodes

The Standard Script Templates

Writing a Custom Locking Script

Time-Lock Opcodes

OP_CHECKMULTISIG

Reading Scripts in Raw Transactions

What You Cannot Do

Further Reading

The Lightning Network Routing Problem: Pathfinding, MPP, and Trampoline

Why Standard Shortest Path Does Not Work

The Probability Model

Pathfinding With Probabilistic Cost

Multipart Payments (MPP)

Trampoline Routing

How Failures Feed Back

What LND Does in Practice

Further Reading

BOLT 11 Invoice Decoding: What's Actually Inside a Lightning Invoice

The Structure

Decoding the Data Part

Tagged Fields

Key Fields in Detail

Verifying the Signature

Using a Library

Practical Situations Where You Need This

Further Reading

Mempool Policy: Why Your Transaction Gets Rejected

Consensus vs. Policy

The Standard Script Policy

Minimum Relay Fee

Dust Limits

RBF: Replace-By-Fee

CPFP: Child-Pays-for-Parent

Timelock Rules

OP_RETURN Size Limits

Checking Mempool Policy Before Broadcasting

What to Do When a Transaction Is Stuck

Further Reading

Taproot for Developers: What Changed and What You Can Build

What Taproot Is, Precisely

Schnorr Signatures: What They Change

Key Path vs. Script Path Spending

MAST: Merkelized Script Trees

MuSig2: Practical n-of-n Multisig

What You Can Build With Taproot

Practical: Reading a P2TR Address

The Current State

Further Reading

LSPS Specifications: What Lightning Service Providers Are Standardizing and Why It Matters

What Problem LSPs Solve

LSPS0: The Transport Layer

LSPS1: Channel Purchase

LSPS2: Just-in-Time Channels (bLIP-52)

What LSPS2 Does Not Specify

Implementing a Minimal LSPS Client

The State of the Specifications in July 2026

Why This Matters for Builders

Further Reading

The Sagas Pattern: Coordinating Multi-Step Bitcoin Workflows Without Distributed Transactions

The Problem: Multi-Step Operations Without Atomicity

Structure of a Saga

Modeling a Lightning Channel Open as a Saga

The Orchestrator

A Payment Routing Saga

Backward vs. Forward Compensation

Idempotency Is Not Optional

Submarine Swaps as a Saga