When an outstanding HTLC is missing from a confirmed commitment, the
current recommendation is to fail it back immediately (or after a
reorg-safety delay). But if a preimage is available for the HTLC,
failing it back is at best going to cause an error (if the HTLC has
already been fulfilled upstream) and at worst going to cause loss of
funds (if the HTLC has *not* already been fulfilled upstream).
Instead, the spec should clearly indicate that upstream HTLCs should be
fulfilled when possible and only failed back if a preimage is not
available.
We make the requirements for `announcement_signatures` more clear. It
is important that both nodes are able to generate the corresponding
`channel_announcement` to allow them to create a new `channel_update`
using the `short_channel_id` of the confirmed splice.
We insist on exchanging `splice_locked` before generating signatures
to ensure compatibility with taproot channels, where nonces will be
exchanged in `splice_locked` messages. This means that we need to
retransmit `splice_locked` on reconnection if `announcement_signatures`
hasn't been fully exchanged.
Importantly, after announcing a splice, nodes must still allow payments
that use the previous `short_channel_id`, because remote nodes may not
have processed the `channel_announcement` and `channel_update`s yet.
If one side sent `splice_locked` and the other side is ready to send
its own `splice_locked` while they are disconnected, this creates a
race condition on reestablish because `splice_locked` is retransmitted
after `channel_reestablish`, and other channel updates can be inserted
by the other node before receiving `splice_locked`. This will be an
issue for taproot channels, because nonces will be missing.
This race condition is described in more details in #1223.
We fix this race condition by adding TLVs to `channel_reestablish`
that provide information about the latest locked transaction. This
additional information also makes it easier to detect when we need
to retransmit our previous `splice_locked`.
Splicing allows spending the current funding transaction to replace it
with a new one that changes the capacity of the channel, allowing both
peers to add or remove funds to/from their channel balance.
Splicing takes place while a channel is quiescent, to ensure that both
peers have the same view of the current commitments.
We don't want channels to be unusable while waiting for transactions to
confirm, so channel operation returns to normal once the splice tx has
been signed and we're waiting for it to confirm. The channel can then
be used for payments, as long as those payments are valid for every
pending splice transactions. Splice transactions can be RBF-ed to speed
up confirmation.
Once one of the pending splice transactions confirms and reaches
acceptable depth, peers exchange `splice_locked` to discard the other
pending splice transactions and the previous funding transaction. The
confirmed splice transaction becomes the channel funding transaction.
Nodes then advertize this spliced channel to the network, so that nodes
keep routing payments through it without any downtime.
As pointed out by @TheBlueMatt, we can greatly simplify the protocol
by removing the `shutdown` exchange entirely. The only piece of data
nodes must remember is the last script their peer sent. This can be
found in the last received `closing_complete`, or in `shutdown` if
`closing_complete` was never received. This doesn't even need to be
persisted, because on reconnection nodes will exchange `shutdown`
again with the last script they want to use for their output.
By doing that, the protocol becomes a trivial request/response protocol
where nodes send `closing_complete` and expect `closing_sig` back. This
creates a race condition when both nodes update their script at the same
time, but this will be extremely rare so we can simply resolve it by
reconnecting.
This protocol is compatible with taproot channels, with the following
additions:
- when sending `shutdown`, nodes will include two random nonces:
- `closer_nonce` that will be used in their `closing_complete`
- `closee_nonce` that will be used in their `closing_sig`
- when sending `closing_complete`, nodes will include a new random nonce
for their next `closing_complete` (`next_closer_nonce`)
- when sending `closing_sig`, nodes will include a new random nonce for
their next `closing_sig` (`next_closee_nonce`)
This ensures that nodes always have a pair of random nonces for their
next signing round.
It was previously unclear whether a node could send `shutdown` and
`closing_complete` immediately after that whenever RBF-ing their
previous closing transaction. While this worked for non-taproot
channels, it doesn't allow a clean exchange of fresh musig2 nonces
for taproot channels. We now require that whenever a node wants to
start a new signing round, `shutdown` must be sent *and* received
before sending `closing_complete`.
We always set `nSequence` to `0xFFFFFFFD`, but each node can choose the
`nLockTime` they want to use for the transactions for which they are
paying the fees.
Bitcoin Core version 25+ will not broadcast transactions containing
`OP_RETURN` outputs if their amount is greater than 0, because this
amount would then be unspendable. We thus require that the output
amount is set to 0 when using `OP_RETURN`.
We don't care, as long as it's RBF-able. This will be nicer for
Taproot when mutual closes are otherwise indistinguishable from normal
spends.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
- Make it clear why the OP_RETURN restrictions have two forms.
- Cross-reference existing dust threshold
- Lots of typo fixes
- Don't set closer_and_closee if we're larger/equal, and closee is dust.
- Remove Rationale on delete zero-output tx hack.
This gets around "but both our outputs are dust!" problems, as
recommended by Anthony Towns.
I hope I interpreted the standardness rules correctly (technically,
you can have multiple pushes in an OP_RETURN as long as the total is
under 83 bytes, but let's keep it simple).
Add an explicit note that "OP_RETURN" is never considered "uneconomic".
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
If both are dust, you should lowball fees. The next patch adds OP_RETURN
as a valid shutdown scriptpubkey though if you really want to do this.
This also addresses the case where people send a new `shutdown` with a *different* scriptpubkey. This could previously cause a race where you receive a bad signature (because it hasn't received the updated shutdown), so we ignore these cases.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
The shutdown section says:
```
- MUST NOT send multiple `shutdown` messages.
```
But the reconnection section says:
```
- upon reconnection:
- if it has sent a previous `shutdown`:
- MUST retransmit `shutdown`.
```
So clearly, remove the former.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This is a follow-up of #1215, where we keep reworking the announcement
requirements.
We remove the rationale around deferring after `channel_ready` since
that has been changed years ago and shouldn't be an issue anymore.
We slightly rework the wording to minimize future conflicts with the
splicing PR.
While nodes are free to send `announcement_signatures` whenever they
feel that the channel is safe from reorg, we disallow broadcasting the
`channel_announcement` before at least 6 confirmations: this gives nodes
a simple heuristic to ignore `channel_announcement`s for remote channels
that aren't spec-compliant, without having to deal with the extra cost
of managing reorgs.
This commit is adding a link to the ML archive and redirecting
users to the delvingbitcoin forum instead of the obsolete ML.
Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
Co-authored-by: Bastien Teinturier <31281497+t-bast@users.noreply.github.com>
It's inserted weirdly (splits a paragraph, so otherwise clause is wrong), and all invreq fields
are mirrored in the invoice.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
We previously required waiting for 6 confirmations before sending
`announcement_signatures`, but the real criteria is that it should only
be sent once you are confident that a reorg will not invalidate it.
No need to be too prescriptive, but examples are good. This is a
pretty generic Code of Conduct that just says if you disrupt
people's ability to contribute or harass someone, you will be shown
the door.
It describes a Code of Conduct committee, which we'll need to
define.
BIP 353 defines a method for resolving Human Readable Names (in the
form ₿`name`@`domain`) into bitcoin: URIs. In order to use them with
BOLT 12 with a wildcard DNS entry which resolves to a single
BOLT 12 offer for all `name`s in a domain, we need a way to
disambiguate the `name` being paid in an `invoice_request` which we
provide here by simply copying the HRN into the `invoice_request`.
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>
