A BOLT11 "invoice" has proven too low-level for human use in many
scenarios. Efforts like lnurl have covered the gap, but integrating
some of such higher layers into the lightning protocol itself has many
advantages.
This draft defines three new things:
1. A new invoice format. I know, this is painful, but it maps almost
1:1 to the current format (though signatures are very different),
is easier to implement, and easier to send via the lightning
network itself.
2. Formats for an "offer", which for all intents and purposes serves
as the new, persistent invoice for users.
3. Format for an "invoice_request": this is a message sent via the
lightning network itself to receive the real invoice, or can
be used directly in a send-money scenario (e.g. ATM).
The offer (for accepting payments) or invoice_request (for sending
payments) are usually presented via a QR code or similar, the replies
are sent using onion messages. Each copies fields from the prior so
it stands alone, to allow statelessness.
Features which have been deliberately omitted for the initial version:
- Recurrence.
- Invoice replacement ("don't accept that old payment!")
- Payer proof for refunds.
This effort has been EPIC, and there is absolutely no way I could have
done this without the often thankless task of implementing,
re-implementing, revising and re-reading this text.
In particular I have been delighted to receive the mental boost from
the following people:
1. Thomas H of ACINQ (https://github.com/thomash-acinq)
2. Jeffrey Czyz of Square Crypto (https://github.com/jkczyz)
3. Joost Jager (https://github.com/joostjager)
4. Aditya Sharma (https://github.com/adi2011)
5. Rene Pickhardt (https://github.com/renepickhardt)
6. Bastien Teinturier of ACINQ (https://github.com/t-bast)
7. Valentine Wallace of LDK (https://github.com/valentinewallace)
8. Matt Corallo of LDK (https://github.com/BlueMatt)
Also @bjarnemagnussen, @ellemouton, @animatedbarber, @617a7a,
@instagibbs, @evansmj, @eupn and @yyforyongyu.
(And no doubt others over the years, who I've accidentally omitted!)
Yes, of course, thanks to my family for their patience with me.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Offers may contain blinded paths to allow for greater recipient privacy.
However, they come at a cost of increased QR code size as the
introduction node requires a 33-byte `point`.
Define a new `sciddir_or_pubkey` fundamental type such that either a point or a
reference to one in a `channel_announcement` can be used. This is
backwards compatible with `point`.
Use this new type for the `blinded_path` subtype's `first_node_id`.
Offers may contain blinded paths to allow for greater recipient privacy.
However, they come at a cost of increased QR code size as each hop
requires a 33-byte `point` for the `next_node_id`. Allow using
`short_channel_id` instead, which only requires 8 bytes.
Still allow for use of `next_node_id` for cases where the blinded path
may not involve channel counterparties or for long-lived offers, which
may outlive the given channels.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
It's far easier to validate these on parsing than to hand-validate them
elsewhere.
I didn't turn `alias` or `error` into this, though they're similar
(`alias` can have a nul terminator).
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
* bolt03: fix link to `bitcoind`'s `policy.cpp` file
The original link is broken, we now replace it with a permalink.
* bolt03: remove 0 `txout` count in closing tx
Txns cannot have zero outputs.
* bolt03: remove wrong ref to `remotepubkey` and fix format
`remotepubkey` has been placed at the wrong place, also fixes the format
so it's easier to read.
All the test vectors use static keys now, which are listed above
already as the local_payment_basepoint and remote_payment_basepoint.
The keys listed here are the pre-static rotated ones: if you use
these, the vectors don't work!
We actually use the same basepoint for the HTLCs, but never spelled it
out. So do that now, and these are the local/remote htlc keys.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
1. Always use the term `encrypted_recipient_data` for the encrypted field:
it's confusing enough without multiple names!
2. Don't give an option for joining blinded payments, since everyone will
use an unblinded payment to the introduction node (at least, for now).
3. Avoid the term "payer" and at least note that encrypted_recipient_data
can be made by the sender themselves, pointing out that the forwarding
node cannot tell.
Thanks t-bast and gijswijs for this feedback!
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
It's a bit complex, but try to convey the idea of an introduction point,
blinded node ids and encrypted blobs. Since the requirements detail the
two ways to reach the introduction node, I handwaved on that a bit.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Writer parts:
1. Be explicit that the writer creates a route.
2. Make it clear we create shared secrets, then derive blinded points.
3. Refer explicitly to all `blinded_path` fields.
Split reader into the *two* readers:
1. The reader of the blinded path, who uses it to make an onion (which wasn't described at all!)
2. The reader of the encrypted_recipient_data, who decrypts it.
In the latter case, we don't have to discuss unblinding the onion since
that's now covered in the "Onion Decryption" section.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This spec was initially written before the `blinded_path` type
existed. Be precise (and we no longer need to say "MUST communicate"!).
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
It's currently buried in the onion message section, but it applies to payments too.
We now have a separate sub-section for the encrypted_data_tlv definition.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit doesn't change the logic at all, it simply:
- removes `realm` from onion test vector
- cleans-up markdown formatting and indents
- fixes typos and missing parenthesis
- consistently uses `_` instead of `-` for field names
- fixes math formatting (including changes from #1169 and #1158)
Sure, it's used to derive a secret for blinding, but it's also used to derive the key
for encrypted_recipient_data. It's not used as a blinding factor *directly*.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This ties it together, saying what to use as associated data, blinding, and what to do on failure.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
There's currently a *description* of how to decrypt an onion, and some requirements
in forwarding. But it also applies to onion messages, so:
1. Turn the description into actual enumerated requirements.
2. Ensure the description covers both payload and messaging onions.
3. Include both methods to apply the blinding tweak.
4. Leave the actual handling of the extracted payload (payment vs messaging onion) to those specific sections (e.g. reporting failure)
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
* BOLT4: include `min_final_cltv_expiry_delta` in `max_cltv_expiry` calc
Include `min_final_cltv_expiry_delta` in the `max_cltv_expiry`
calculation. Also add a note that indicates that this field may be set
for the final node too. This is useful for the final node as then it
does not need to persist the path expiry separately and can rely on just
checking the `payment_relay` field when the payment arrives.
* BOLT4: include calculation for `total_cltv_delta` of a blinded path
Include an explicit formula to use for determining the total CLTV delta
of a blinded path so that it is clear that it should include the
recipient's `min_final_cltv_expiry_delta`.
* proposals: fix `max_cltv_expiry` value for final hop in example
More info
[here](https://github.com/lightning/bolts/issues/1174#issue-2371364610)
outlining why the example needed to be updated.
As noted previously, `channel_update`s in the onion failure packets
are massive gaping fingerprintign vulnerabilities - if a node
applies them in a publicly-visible way the err'ing node can easily
identify the sender of an HTLC.
While the updates are still arguably marginally useful for nodes to
use in their pathfinding local to retires of the same payment, this
too will eventually become an issue with PTLCs. Further, we
shouldn't be letting nodes get away with delaying payments by
failing to announce the latest channel parameters or enforcing new
parameters too soon, so treating the node as having indicated
insufficient liquidity (or other general failure) is appropriate
in the general case.
Thus, here, we begin phasing out the `channel_update` field,
requiring nodes ignore it outside of the current payment and making
it formally optional (though nodes have been doing this for some
time due to various bugs).
Because some nodes may want to use update data on mobile when they
have stale gossip data, it is left optional.
To avoid timing analysis when decrypting failed payments the sender
should act as if the failure in the route came for the 27th hop.
Also changed the maximum number of hops in the route from 20 (legacy)
to 27 (tlv onion).
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Header from folded patch 'bolt_2__set_an_initiator_in_quiescence.patch':
BOLT #2: Set an initiator in quiescence.
This is especially useful for protocols such as splicing; for
simplified commitment transactions, there is already an implied
initiator at each point, so having the negotiation at splicing
time would be redundant.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Header from folded patch 'option_quiesce__feature_to_support_stfu_method.patch':
option_quiesce: feature to support stfu method.
In practice, sftu is useless unless you have something (e.g. channel_upgrade)
which uses it, but adding a feature is best practice IMHO.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This is a follow-up to https://github.com/lightning/bolts/pull/1092
that fixes the following issues:
- fix a few typos
- remove non-zero-fee anchors test cases
- remove `remote_pubkey` rotation
Supported by all but 11 nodes*.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
[* there are 449 three-year old LND nodes which advertize `2200` as their features, which have already been trimmed from most gossip for not having htlc_maximum_msat in their channel_updates]
Advertized as supported by all but 6 nodes (and those can no longer
route payments since people only send the modern onion these days)
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
These still have names and numbers, since they appear in `channel_type`. They are somewhat tangled with each other, so let's tie them together as assumed.
option_data_loss_protect is advertized by all by 11 nodes(*), and option_static_remotekey all but 16 nodes.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
[* there are 449 three-year old LND nodes which advertize `2200` as their features, which have already been trimmed from most gossip for not having htlc_maximum_msat in their channel_updates]
In this commit, we propose a purely syntactical change to the current
blinded paths specification. Rather than denote the public key of the i-th
node as `E(i)`, we propose that instead it's denoted as: `E_i`. This results
in less overall characters, and is more similar to notation customarily
used in LaTeX.
My personal preference is that the proposed notation is easier to scan at a
glance, and also less ambiguous (doesn't look like a function call).
This commit updates bolt04 to more strictly enforce that encrypted_data
that is part of a blinded payment only has short_channel_id set. On
the reader side, we disallow setting of both short_channel_id and
next_node_id (which is intended for use in the context of onion
messages), and on the writer side we specify that next_node_id should
not be included by recipients.
