Payment Secret

What Is a Payment Secret?

A payment secret (also called payment_secret) is a 256-bit random value that a recipient generates and includes in a Lightning invoice. When the sender constructs the payment, they place this secret inside the encrypted onion payload destined for the final hop. The recipient checks the incoming HTLC against the expected secret and rejects any payment that does not match.

The payment secret is distinct from the payment preimage and payment hash that lock and unlock HTLCs. While the payment hash is visible to every node along the route (since it is part of the HTLC), the payment secret travels inside the onion-encrypted layer and is only readable by the final recipient. This separation is what gives the payment secret its anti-probing properties.

In a BOLT-11 invoice, the payment secret appears as the s tagged field (type 16). Every valid invoice must contain exactly one s field, and a compliant sender must include it in the onion payload or the payment will be rejected.

How It Works

To understand why the payment secret exists, consider what happens without it. In a standard Lightning payment, the payment hash is the only identifier the recipient uses to match an incoming HTLC to an invoice. Every forwarding node along the route sees this hash because it is part of the HTLC contract. This creates a probing opportunity.

The Multipath Probing Attack

When multi-path payments are in use, the recipient expects multiple HTLCs sharing the same payment hash. Without a payment secret, an intermediate node could exploit this:

1. A forwarding node receives an HTLC with a certain payment hash and notices that the next hop might be the final recipient
2. The forwarding node crafts a tiny HTLC (for example, 1 millisatoshi) using the same payment hash and sends it to the next hop
3. If the next hop is an intermediate relay, it passes the HTLC along normally or fails it with a routing error
4. If the next hop is the final recipient, it responds differently: it either accepts the partial payment (waiting for more parts) or returns an error specific to final-hop validation
5. By observing the error type, the forwarding node learns whether its neighbor is the payment's final destination, breaking the privacy that onion routing is designed to provide

The payment secret closes this attack vector. Since the secret is encrypted inside the onion and only the legitimate sender knows it, the forwarding node cannot include a valid secret in its probe HTLC. The recipient rejects the probe with the same generic incorrect_or_unknown_payment_details error it would return for any unknown payment, giving the attacker no useful information.

Invoice and Onion Structure

The payment secret participates in two protocol layers:

• BOLT 11 (invoice encoding): the recipient generates a random 256-bit value and encodes it as the s tag in the invoice. The invoice is signed, so the secret cannot be tampered with.
• BOLT 4 (onion routing): the sender includes the payment secret in the final hop's onion payload. Because the onion is encrypted layer-by-layer, intermediate nodes cannot read it. Only the recipient decrypts the final layer and extracts the secret for validation.

A simplified view of the invoice fields:

lnbc10u1p...  (BOLT-11 encoded invoice)

Tagged fields:
  p  (payment hash):   256-bit SHA-256 of preimage  [visible in HTLC]
  s  (payment secret): 256-bit random value         [onion-encrypted]
  d  (description):    human-readable memo
  x  (expiry):         invoice validity period
  c  (cltv delta):     minimum final CLTV expiry

Payment Secret vs. Payment Hash

These two values serve fundamentally different purposes:

The payment hash ensures that revealing the preimage settles all HTLCs atomically. The payment secret ensures that only HTLCs from the authorized sender are accepted by the recipient. Together, they provide both atomicity and privacy.

Specification History

The payment secret was introduced through a series of changes to the BOLT specifications:

• 2019: BOLTs #643 added the payment secret field to the Lightning specification. Early implementations in LND and Core Lightning treated it as optional.
• 2021: BOLTs #887 updated BOLT 11 to require that senders specify the payment secret. Major implementations followed: LND added logic to prevent releasing a preimage without a valid payment secret, Core Lightning required it by default, Eclair made it mandatory for peer signaling, and Rust-Lightning enforced it to prevent multipath probing.

Today, every compliant Lightning node rejects invoices that lack a payment secret and refuses to settle HTLCs that arrive without one. For a deeper look at invoice formats and their evolution, see the research article on Lightning invoices: BOLT 11, BOLT 12, and beyond.

Use Cases

Multipath Payment Privacy

The primary use case for the payment secret is securing multipath payments. When a payment is split across multiple routes, each partial HTLC carries the same payment hash. Without the payment secret, any intermediate node that handles one of these HTLCs could probe the recipient with additional HTLCs using the same hash. The payment secret ensures that only the parts sent by the authorized payer are accepted.

Recipient Authentication

The payment secret acts as proof that the sender obtained a valid invoice from the recipient. If someone intercepts the payment hash (which is visible in HTLCs) and tries to construct their own payment, they cannot include the correct secret. This prevents a class of attacks where a malicious node attempts to trick the recipient into accepting an unauthorized payment.

Privacy Against Forwarding Nodes

Beyond multipath scenarios, the payment secret strengthens privacy for all Lightning payments. A forwarding node that wants to determine whether its next hop is the final recipient can no longer rely on sending probe HTLCs with the same hash. This complements other privacy techniques like blinded paths in BOLT 12 offers.

Relationship to Spark and Layer 2 Solutions

Payment secrets are a Lightning-specific mechanism, but the underlying principle of authenticating payment participants applies broadly across Bitcoin Layer 2 protocols. Spark, as a Bitcoin Layer 2, takes a different architectural approach that avoids many of the routing-layer privacy concerns that payment secrets address on Lightning. Since Spark does not use multi-hop routing in the same way, the specific probing vectors that payment secrets mitigate do not apply. For a comparison of these approaches, see the research article on what is Spark.

Risks and Considerations

Not a Complete Privacy Solution

The payment secret prevents recipient probing, but it does not address all privacy leaks in Lightning. Channel balance probing by external observers, timing analysis, and amount correlation remain possible attack vectors. Payment secrets are one layer in a defense-in-depth approach that also includes onion routing, blinded paths, and payment probe countermeasures. For a comprehensive look at these privacy concerns, see the research article on Lightning payment probing and privacy.

Invoice Reuse Implications

Each invoice contains a unique payment secret tied to a specific payment. Reusing an invoice means reusing the same secret, which weakens its anti-probing benefit. If an attacker obtains the secret from a prior payment attempt, they can use it to probe the recipient. Best practice is to generate a fresh invoice (and therefore a fresh payment secret) for every transaction.

Backward Compatibility

Since the payment secret became mandatory in 2021, very old Lightning nodes or wallets that have not been updated may fail to include it. Modern recipients reject such payments, which can cause confusion for users running outdated software. Wallet developers should ensure their implementations always include the payment secret when constructing onion payloads.

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.