Preimage

What Is a Preimage?

A preimage (also called the payment secret or payment preimage) is a randomly generated 32-byte value that serves as the cryptographic key to unlock a Lightning Network payment. The receiver generates the preimage, computes its SHA-256 hash to create the payment hash, and embeds that hash in a Lightning invoice. When the sender pays the invoice, every hop in the route creates an HTLC locked to that hash. Only someone who knows the original preimage can unlock those HTLCs and claim the funds.

Think of a preimage as a password and the payment hash as a fingerprint of that password. The receiver creates the password, shares only the fingerprint (hash) with the network, and keeps the password (preimage) secret. When the payment arrives, the receiver reveals the password to prove they are the intended recipient and claim the funds.

The term "preimage" comes from mathematics: in a hash function H(x) = y, the input x is the preimage of the output y. In Lightning, the preimage is the input to SHA-256 that produces the payment hash. The security of the entire system relies on the one-way property of SHA-256: computing the hash from the preimage is trivial, but deriving the preimage from the hash is computationally infeasible.

How It Works

The preimage lifecycle spans the entire payment flow, from invoice creation to final settlement. Understanding each stage reveals why the preimage is central to Lightning's trustless design.

Preimage Generation

The payment recipient generates the preimage using a cryptographically secure random number generator. The preimage must be exactly 32 bytes (256 bits), providing 2²⁵⁶ possible values: a space large enough that collisions or guesses are practically impossible.

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

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

The quality of randomness is critical. A preimage generated from a weak random source could be guessable, allowing an attacker to claim payments intended for someone else. Lightning node implementations use operating-system-level entropy sources (such as /dev/urandom) to ensure sufficient randomness.

Invoice Creation and Hash Embedding

After generating the preimage, the receiver computes its SHA-256 hash and embeds the result in a Lightning invoice. The invoice includes the payment hash, the requested amount, an expiry time, and optional route hints. The preimage itself never leaves the receiver's node at this stage.

The receiver stores the preimage locally, indexed by the payment hash, so they can retrieve it when an incoming HTLC arrives. This mapping is essential: without it, the receiver would have no way to settle the payment.

The Reveal Flow

When the sender pays the invoice, a chain of HTLCs propagates from the sender to the receiver through one or more routing nodes. Each HTLC is locked to the same payment hash. The reveal flow then works in reverse:

1. The receiver's node detects an incoming HTLC whose payment hash matches a stored preimage
2. The receiver reveals the preimage to the immediately preceding hop, claiming the HTLC funds
3. That routing node now knows the preimage and uses it to claim the HTLC from the node before it
4. This backward propagation continues hop by hop until the sender's node receives the preimage
5. Every HTLC in the chain is now settled: each node has claimed the incoming HTLC and fulfilled the outgoing one

Sender ──HTLC(H)──▶ Node A ──HTLC(H)──▶ Node B ──HTLC(H)──▶ Receiver

Settlement (preimage flows backward):
Sender ◀──R── Node A ◀──R── Node B ◀──R── Receiver

H = SHA256(R)
R = preimage (the secret that unlocks every HTLC in the chain)

The atomic nature of this process is key: if any node in the chain learns the preimage, every preceding node will also learn it (because the intermediate node must reveal it to claim their own HTLC). This means the payment either settles completely across all hops or fails entirely.

Cryptographic Properties

The preimage-to-hash relationship depends on three properties of SHA-256:

• Preimage resistance: given a hash, it is computationally infeasible to find the corresponding preimage. This prevents routing nodes from stealing funds by computing the preimage from the payment hash they can see.
• Second preimage resistance: given a preimage, it is infeasible to find a different preimage that produces the same hash. This prevents an attacker from generating a substitute secret to claim someone else's payment.
• Determinism: the same preimage always produces the same hash. This ensures that the preimage generated during invoice creation is the exact value needed to settle the HTLCs later.

Use Cases

Proof of Payment

After a payment settles, the sender holds the preimage as cryptographic evidence that the payment was completed. Since the preimage was originally known only to the receiver and embedded in their invoice, possession of it demonstrates that the specific invoice was paid. This proof-of-payment mechanism enables receipt-like functionality without any centralized record-keeping.

Applications can verify proof of payment by checking that SHA256(preimage) == payment_hash. If this equality holds, the presenter knows the secret that was required to settle the invoice. This is useful for digital content delivery, access tokens, and any scenario where the seller needs to verify payment before releasing a service.

Hodl Invoices and Conditional Payments

Hodl invoices leverage the preimage to create conditional payments. Instead of revealing the preimage immediately upon receiving an HTLC, the receiver holds it and waits for external conditions to be met. If conditions are satisfied, they release the preimage to settle. If not, they let the HTLC expire and the sender's funds return automatically.

This pattern transforms the preimage from an automatic settlement mechanism into a programmable trigger. The receiver controls the timing of preimage release, enabling escrow, marketplace payments, and atomic swaps with on-chain transactions.

Keysend and Spontaneous Payments

In standard payments, the receiver generates the preimage. With keysend payments, the sender generates the preimage instead and includes it in the encrypted onion payload destined for the receiver. The receiver extracts the preimage from the onion and uses it to settle the HTLC.

This reversal of preimage generation allows spontaneous payments without requiring the receiver to create an invoice first. The tradeoff is that the sender already knows the preimage before the payment settles, so preimage-based proof of payment is weaker in this model.

Atomic Multipath Settlement

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 the preimage. A single preimage reveal settles every partial payment atomically: the receiver cannot selectively claim some parts while ignoring others.

Risks and Considerations

Preimage Leakage and Theft

If the preimage is leaked before the intended settlement time, anyone who learns it can claim the corresponding HTLCs. This risk is most acute in hodl invoice scenarios: if a receiver's system is compromised while holding a preimage, an attacker could settle the payment and steal the funds. Preimages must be stored with the same security as private keys during the payment lifecycle.

After settlement, every routing node in the payment path also knows the preimage. This is by design (it is how they claim their own HTLCs), but it means the preimage is no longer truly secret. For proof-of-payment purposes, this limits the strength of the guarantee: any routing node could present the preimage and falsely claim to have been the original payer.

Timing Considerations

The receiver must reveal the preimage before the HTLC timelock expires. If they fail to do so (due to a crash, network partition, or software bug), the funds return to the sender via the timeout path and the receiver loses the payment entirely. For hodl invoices, this is especially dangerous: the longer the hold period, the greater the risk of missing the settlement window.

Timelocks decrease at each hop in the route (as described in the Lightning liquidity research article). If an intermediate node settles an incoming HTLC but cannot claim the outgoing one before its shorter timeout, that node loses funds. Routing nodes must monitor HTLC expiry times closely and resolve preimages promptly.

Hash Reuse Vulnerabilities

If the same preimage (and therefore the same payment hash) is used across multiple invoices, a single preimage reveal can settle all of them. Any routing node that learns the preimage from one payment can immediately claim HTLCs from any other pending payment using the same hash. Lightning implementations enforce unique preimages per invoice, but custom application code that manages preimages directly must avoid reuse.

Privacy Implications

Because every hop in a payment route uses the same payment hash (and thus the same preimage settles all of them), the preimage creates a correlation vector. A node that participates in two hops of the same payment can observe the same preimage flowing through both, confirming they are part of one transaction. This is the primary motivation behind the proposed transition from HTLCs to PTLCs, which use per-hop adaptor signatures derived from Schnorr signatures to break this correlation. With PTLCs, there is no single preimage shared across hops, eliminating this privacy weakness.

Quantum Computing Threats

The security of preimage-based HTLCs relies on the preimage resistance of SHA-256. While no known classical algorithm can efficiently invert SHA-256, sufficiently powerful quantum computers running Grover's algorithm could reduce the search space from 2²⁵⁶ to 2¹²⁸ operations. Although 2¹²⁸ remains extremely large and is not considered a near-term practical threat, it represents a theoretical reduction in security margin. For a broader discussion of quantum risks to Bitcoin cryptography, see the glossary entry on Shor's algorithm vulnerability.

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.