Payment Preimage

What Is a Payment Preimage?

A payment preimage is the secret value at the heart of every Lightning Network payment. It is a randomly generated 32-byte number that the payment receiver creates and keeps private. The receiver computes the SHA-256 hash of this preimage to produce a payment hash, which is then embedded in a BOLT 11 invoice. When the sender pays that invoice, the entire payment route is secured by this hash: funds can only be claimed by someone who reveals the original preimage.

The BOLT specification (the Lightning Network's standard protocol) defines the payment preimage as the "proof that payment has been received, held by the final recipient, who is the only person who knows this secret." This definition captures the dual role of the payment preimage: it is both the mechanism that unlocks funds and the evidence that a payment was fulfilled. While the general concept of a preimage refers to any input to a hash function, the payment preimage specifically refers to this secret in the context of settling Lightning payments.

The relationship between the preimage and hash relies on the one-way property of SHA-256: anyone can verify that a given preimage produces a specific hash, but computing the preimage from the hash alone is computationally infeasible. This asymmetry is what makes Lightning payments trustless. Routing nodes can see the payment hash but cannot derive the preimage from it, so they cannot steal funds in transit.

How It Works

The payment preimage flows through a specific lifecycle that spans the entire payment process, from invoice creation to final settlement. Each stage depends on the cryptographic properties of the preimage-hash relationship.

Step 1: Generation and Hashing

The payment receiver generates a cryptographically random 32-byte value using a secure random source. This preimage must be generated with a cryptographically secure pseudorandom number generator (CSPRNG) to prevent attackers from guessing or predicting its value. Lightning implementations such as LND use operating-system-level entropy (for example, Go's crypto/rand reading from /dev/urandom) to ensure high-quality randomness.

# Generate a 32-byte random preimage
preimage=$(openssl rand -hex 32)
# Example: 4a8b3c2d1e9f0a7b6c5d4e3f2a1b0c9d...

# Compute its SHA-256 hash (the payment hash)
payment_hash=$(echo -n "$preimage" | xxd -r -p | sha256sum | cut -d' ' -f1)

# The hash is embedded in the invoice; the preimage stays secret

The receiver stores the preimage locally, indexed by its hash, so it can be retrieved when an incoming HTLC arrives matching that hash.

Step 2: Invoice and Route Construction

The receiver creates a Lightning invoice containing the payment hash, the requested amount, an expiry time, and optional routing metadata. The preimage itself never appears in the invoice. The sender decodes the invoice, extracts the payment hash, and constructs a route through the network using onion routing.

Step 3: HTLC Chain

The sender creates an HTLC locked to the payment hash and forwards it to the first routing node. Each subsequent node creates its own HTLC with the same hash and forwards it to the next hop. This chain of HTLCs extends from the sender to the receiver, with every hop locked to the identical payment hash.

Each HTLC encodes two resolution paths in Bitcoin Script:

• Hash path: the recipient presents the preimage, and the script verifies it by hashing it and comparing to the embedded payment hash
• Timeout path: if the preimage is not revealed before a deadline, the sender reclaims the funds via a timelock

# Simplified HTLC script structure (BOLT #3)
OP_HASH160 <RIPEMD160(payment_hash)> OP_EQUALVERIFY
OP_IF
    <receiver_pubkey> OP_CHECKSIG    # Preimage path
OP_ELSE
    <timeout> OP_CHECKLOCKTIMEVERIFY  # Timeout path
    <sender_pubkey> OP_CHECKSIG
OP_ENDIF

Step 4: Preimage Reveal and Settlement

When the final HTLC reaches the receiver, their node matches the incoming payment hash against stored preimages. Upon finding a match, the receiver reveals the preimage by sending an update_fulfill_htlc message (defined in BOLT #2) to the preceding node. This message contains the raw 32-byte preimage.

The BOLT #2 specification states that the payment_preimage in update_fulfill_htlc "must SHA256 hash to the corresponding HTLC payment_hash." The preceding node verifies this, claims the HTLC, and then reveals the preimage to the node before it. This backward propagation continues hop by hop until the sender's node receives the preimage.

Forward (HTLCs locked to hash H):
Sender ──HTLC(H)──▶ Node A ──HTLC(H)──▶ Node B ──HTLC(H)──▶ Receiver

Backward (preimage R settles each hop):
Sender ◀──R── Node A ◀──R── Node B ◀──R── Receiver

Where: H = SHA256(R) and R = payment preimage

The specification further notes that "knowledge of the preimage is, by definition, irrevocable," meaning that once a node learns the preimage, the corresponding HTLC should be fulfilled immediately to minimize latency.

Payment Preimage as Proof of Payment

After settlement, the sender holds the payment preimage as cryptographic evidence that the payment was completed. Since the preimage was originally known only to the receiver and its hash was embedded in the invoice, possessing the preimage proves that the specific invoice was paid. This receipt mechanism works without any centralized record-keeping.

Verification is straightforward: anyone can check that SHA256(preimage) == payment_hash. If this equality holds, the presenter knew the secret required to settle the corresponding invoice. Applications use this property for digital content delivery, access control, and any scenario where payment must be verified before releasing a service.

There is an important caveat: after settlement, every routing node in the payment path also knows the preimage, since they used it to claim their own HTLCs. This means any routing node could present the preimage and claim to have been the original payer. For most practical purposes, preimage-based receipts are sufficient, but they do not provide the same non-repudiation guarantees as a digital signature.

Use Cases

Standard Lightning Payments

Every Lightning payment uses a payment preimage, whether the user is aware of it or not. When you scan a QR code at a point of sale, your wallet extracts the payment hash from the invoice, routes HTLCs through the network, and the merchant's node reveals the preimage to complete the payment. The preimage settles backward through each routing node in milliseconds. For a deeper look at how payments flow through the network, see the Lightning routing deep dive.

Hodl Invoices and Conditional Logic

Hodl invoices separate the receipt of an HTLC from the preimage reveal, giving the receiver control over settlement timing. The receiver generates the preimage but withholds it until external conditions are met: a product ships, an oracle confirms an event, or a counterparty completes their side of a swap. The preimage becomes a programmable trigger rather than an automatic settlement mechanism.

Submarine Swaps

Submarine swaps use the same payment preimage to link an on-chain HTLC with a Lightning payment. The shared hash ensures atomicity: claiming one side reveals the preimage needed to claim the other. This pattern enables trustless movement of funds between Bitcoin's base layer and Lightning without relying on a custodial intermediary.

Multi-Path Payments

When a payment is split across multiple routes using multi-path payments, all partial HTLCs share the same payment hash. The receiver waits for all parts to arrive before revealing a single preimage, which settles every partial payment atomically.

The Transition to PTLCs

The most significant limitation of hash-based payment preimages is that the same payment hash appears at every hop in the route. A node that controls two positions in the same route can observe the identical hash at both points and conclude they are part of the same payment. This correlation vector enables probing attacks and weakens payment privacy.

PTLCs (Point Time-Locked Contracts) address this by replacing hash locks with point locks based on adaptor signatures. Instead of revealing a preimage to a hash, PTLCs use Schnorr signatures where each hop in the route sees a unique locking point. An observer at two different hops sees different lock values and cannot link them to the same payment.

PTLCs became feasible after Bitcoin's Taproot upgrade enabled Schnorr signature support. Lightning-level adoption is still in progress, with implementations working on simple Taproot channels as a prerequisite. For a detailed comparison, see the research article on PTLCs as the next evolution of Lightning.

Risks and Considerations

Entropy and Generation Security

The security of a payment preimage depends entirely on the quality of its randomness. A preimage generated from a weak or predictable random source could be guessable, allowing an attacker to claim payments intended for someone else. Lightning node implementations use operating-system-level entropy sources, but developers building applications that generate preimages directly (for example, when creating hodl invoices) must ensure they use a CSPRNG rather than predictable values.

Preimage Reuse

Reusing a payment preimage across multiple invoices creates a critical vulnerability. If one invoice is paid and the preimage is revealed, any routing node that observed the preimage can immediately settle any other pending HTLC using the same hash. Lightning implementations enforce unique preimages per invoice, but application code managing preimages manually (such as hodl invoice services) must never reuse them.

Early Disclosure

If the preimage is leaked before the intended settlement time, an attacker could claim the corresponding HTLCs. This risk is most relevant for hodl invoices, where the preimage is stored for an extended period before settlement. During this window, the preimage must be protected with the same rigor as a private key.

Privacy Limitations

Because the same payment hash (and therefore the same preimage) settles every hop in a route, payment preimages create a correlation vector for surveillance. This is an inherent property of HTLC-based routing and is the primary motivation for the transition to PTLCs. Until PTLCs are widely deployed, techniques like blinded paths offer partial privacy improvements at the routing level.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.