Payment Hash

What Is a Payment Hash?

A payment hash is the SHA-256 hash of a randomly generated 32-byte value known as the preimage (also called the payment secret). In the Lightning Network, the payment hash acts as a cryptographic condition: anyone who possesses the corresponding preimage can unlock funds secured by that hash. Without the preimage, the funds remain locked and eventually return to the sender via a timelock.

Think of it like a combination lock: the payment hash is the lock itself, visible to everyone involved in routing the payment. The preimage is the combination that opens it. The receiver generates both, shares the lock (hash) publicly in an invoice, and keeps the combination (preimage) secret until they want to claim the funds.

Payment hashes are fundamental to how Lightning achieves trustless payments across multiple intermediary nodes. Every hop in a payment route uses the same hash as its condition, which is what makes atomic settlement possible: either every hop settles (because the preimage is revealed), or none of them do.

How It Works

The payment hash lifecycle follows a specific sequence involving the receiver, sender, and every routing node in between.

1. The receiver generates a cryptographically random 32-byte value: the preimage
2. The receiver computes the SHA-256 hash of this preimage to produce the payment hash
3. The receiver embeds the payment hash in a Lightning invoice and shares it with the sender
4. The sender constructs a route using onion routing and creates an HTLC locked to the payment hash
5. Each intermediate node forwards the HTLC to the next hop, each locked to the same payment hash
6. When the HTLC reaches the receiver, they reveal the preimage to claim the funds
7. The preimage propagates backward through each hop, settling every HTLC in the chain

Hash Generation

The cryptographic relationship between preimage and payment hash is straightforward: the hash is a one-way function of the preimage. Given the preimage, anyone can compute the hash. But given only the hash, it is computationally infeasible to derive the preimage. This asymmetry is what makes HTLCs secure.

# Generate a random 32-byte preimage
preimage=$(openssl rand -hex 32)
# Example: 7d2a1f3c8b4e5a9012d6f7e8c3b4a5d6e7f80192a3b4c5d6e7f8091a2b3c4d5

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

In a standard payment flow, the receiver generates both the preimage and the hash. This is important: only the receiver knows the preimage, so only they can settle the payment. The sender and all routing nodes see the hash but never learn the preimage until the receiver chooses to reveal it.

Role in HTLC Construction

An HTLC (Hash Time-Locked Contract) is a conditional payment with two resolution paths:

• Hash lock: the recipient can claim funds by presenting the preimage that hashes to the payment hash
• Time lock: if the preimage is not revealed before a deadline, the sender reclaims the funds

In Bitcoin Script terms, the HTLC output encodes this logic directly. The payment hash is embedded in the script as the hash lock condition:

OP_HASH256 <payment_hash> OP_EQUAL
OP_IF
    <receiver_pubkey> OP_CHECKSIG
OP_ELSE
    <timeout> OP_CHECKLOCKTIMEVERIFY OP_DROP
    <sender_pubkey> OP_CHECKSIG
OP_ENDIF

This script says: if you can provide a value whose hash matches the payment hash, the receiver can spend. Otherwise, after the timeout, the sender can reclaim the funds. Every HTLC along the payment route contains the same payment hash, which is what links them together into an atomic chain.

Payment Hash as an Identifier

Beyond its cryptographic role, the payment hash also serves as a unique identifier for a payment. Lightning nodes use the payment hash to track invoice state, match incoming HTLCs to outstanding invoices, and log payment history.

When a sender pays an invoice, they reference the payment hash. When a routing node receives an HTLC, it uses the payment hash to look up the corresponding outgoing HTLC. When the receiver sees an incoming HTLC, they match the payment hash against their stored invoices to find the correct preimage to reveal.

This dual role (cryptographic lock and payment identifier) is convenient but also contributes to privacy concerns, as discussed below.

Use Cases

Standard Lightning Payments

Every Lightning invoice contains a payment hash. When you scan a QR code to pay for coffee, your wallet extracts the payment hash from the invoice, constructs a route, and sends HTLCs locked to that hash. The coffee shop's node reveals the preimage to claim the payment, and the preimage settles back through the route. This process is invisible to the user but the payment hash is the mechanism that makes it trustless. For a deeper look at how Lightning routes these payments, see the Lightning Network liquidity research article.

Hodl Invoices

Hodl invoices exploit the separation between receiving an HTLC and revealing the preimage. The receiver creates the payment hash normally but deliberately withholds the preimage until certain conditions are met. The payment hash identifies the held payment, and the receiver decides whether to settle (reveal preimage) or cancel (let the HTLC expire). This pattern enables escrow, conditional payments, and atomic swaps on Lightning.

Keysend Payments

Keysend reverses the usual preimage generation flow. Instead of the receiver generating the preimage and embedding the hash in an invoice, the sender generates the preimage, computes the hash, and includes the preimage in the encrypted onion payload destined for the receiver. When the receiver unwraps the onion, they discover the preimage and use it to settle the HTLC.

This approach allows spontaneous payments without requiring the receiver to create an invoice first. The tradeoff is that the sender knows the preimage from the start, which changes the trust assumptions compared to standard invoice-based flows.

Multi-Path Payments

Multi-path payments split a single payment across multiple routes, each carrying a partial amount. All partial HTLCs share the same payment hash, ensuring the receiver can only claim the full amount by revealing a single preimage. If any partial payment fails, the receiver cannot settle the others (the remaining HTLCs eventually time out and return to the sender).

Risks and Considerations

Privacy: Hash Correlation Across Hops

The most significant privacy concern with payment hashes is that the same hash value is used at every hop along the payment route. A node that controls two non-adjacent positions in a route can observe the same payment hash at both points and conclude they are part of the same payment. This reveals information about the payment's origin and destination.

This correlation problem also enables certain probing attacks, where an adversary sends probe payments to learn about channel balances and payment flows. The static payment hash makes it trivial to link related HTLCs.

PTLCs (Point Time-Locked Contracts) are the proposed solution. PTLCs replace the hash lock with a point lock based on Schnorr signatures, where each hop uses a different locking point. This breaks the correlation: an observer at two points in the route sees different lock values and cannot link them to the same payment. PTLCs require Schnorr signature support, which became available with Bitcoin's Taproot upgrade, though Lightning-level adoption is still in progress.

Preimage Exposure and Proof of Payment

Once the preimage is revealed to settle a payment, it propagates back through every routing node. Each node learns the preimage for the payment it routed. This means the preimage is not truly secret after settlement: every node in the route has a copy.

While the preimage serves as a proof-of-payment (the sender can show they know the preimage for a given payment hash), any routing node can also claim this proof. This limits the cryptographic strength of preimage-based proof-of-payment in adversarial scenarios.

Hash Reuse

Reusing a payment hash across multiple invoices is dangerous. If an invoice is paid and the preimage is revealed, any other pending HTLC using the same hash can be settled by any node that observed the preimage. This could result in unintended payments or stolen funds. Lightning implementations generally enforce unique payment hashes per invoice, but application-layer code that manages hashes directly must be careful to avoid reuse.

Computational Assumptions

The security of payment hashes rests on the preimage resistance of SHA-256: given a hash, it should be computationally infeasible to find the corresponding preimage. This assumption holds against classical computers but could be threatened by sufficiently powerful quantum computers. For a discussion of quantum risks to cryptographic primitives used in Bitcoin, 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.