AI-generated analysisPublished automatically and not human-verified. Validated context appears in community notes below.
← Watch feed
Low 37 Bitcoin

Add support for fulfillment payload (#3321)

Public commit record

What the developer wrote

Authored by Bastien Teinturier

88/100 · Strong
Add support for fulfillment payload (#3321)

This adds support for including a payload in `update_fulfill_htlc` that
the recipient encrypts for the payer. This can be useful to transmit
data atomically with the fulfillment of a payment. The main challenge
is that intermediate nodes may drop or tamper with this fulfillment
payload, which is why we include it in the HMACs of the attribution
data, which lets senders detect which pair of nodes may be malicious.

We limit error packets and fulfillment payloads to 32kB to leave room
for future TLVs. We silently truncate payloads that are larger, which
ensures that the messages we create are always compliant. We truncate
attribution data that doesn't have the expected length as well.

See https://github.com/lightning/bolts/pull/1344
✓ Descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context✓ Explains rationale or failure mode✓ Links an issue, advisory, or supporting reference
The short version

What changed, and why it matters

This commit adds a new optional encrypted payload to Lightning payment fulfillment messages. It is a feature implementation, not a fix for an active vulnerability. The code does introduce a safety check: if a peer sends an oversized fulfillment payload, the node force-closes the channel after first relaying the payment preimage upstream so funds are not lost. The main risk is that any bugs in the new encryption, wrapping, or truncation logic could affect payment settlement or channel stability, but the commit itself is defensive and follows a proposed Lightning specification.

Recommended action

Review the new Sphinx.SuccessPacket.create/wrap/decrypt implementation and the channel force-close path for correctness. Ensure that truncation behavior cannot be abused to make a valid payload appear invalid, and that the force-close condition is only reachable for genuinely oversized payloads. Run the included reference test vectors and fuzz the size-limit edge cases.

Security signals we found

01

New cryptographic payload handling added to payment fulfillment path

02

Size limits and silent truncation applied to failure packets, fulfillment payloads, and attribution data

03

Channel force-close triggered on oversized peer fulfillment payload

04

Attribution HMACs extended to cover fulfillment payload for tamper detection

05

Blinded-route handling updated to avoid leaking attribution data while still wrapping payload

Risk score

Why this scored 37/100

Our methodology →
Potential impact 8/30
Exploitability 6/25
Stealth signal 5/15
Affected reach 7/15
Confidence 7/10
Evidence quality 4/5
Human-validated context

Community notes

Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.

No validated notes yet.

The AI analysis stands alone for now. Submit a note if you can add evidence or important context.