Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update protocol for continuous inbound liquidity #618

Closed
wants to merge 6 commits into from
Closed

Update protocol for continuous inbound liquidity #618

wants to merge 6 commits into from

Conversation

t-bast
Copy link
Member

@t-bast t-bast commented Mar 11, 2024 •
edited

We revamp our protocols for on-the-fly funding to use a unified approach based on liquidity ads. We simplify messages exchanged and reduce the number of custom extensions required on top of the BOLT specifications.

We also introduce an optional fee_credit feature, that is disabled by default (because it introduces an additional trust trade-off with the service provider), which allows wallets to accept small payments for which an on-chain operation is not economical, and obtain a fee credit in exchange for a future on-chain operation.

The main changes to the protocol are:

  • the wallet initiates all channel operations (it is responsible for sending open_channel2 and splice_init)
    • it thus automatically pays the on-chain fees for the common transaction fields, as specified by the interactive-tx protocol
    • it uses a custom channel flag to ask the service provider to pay the commit tx fees and closing fees (won't be necessary anymore once we use 0-fee commit txs with package relay), which enables 0-reserve and allows emptying a wallet using an off-chain payment
  • we replace the pay_to_open messages with a single maybe_add_htlc message, which is a clone of update_add_htlc without a channel_id or htlc_id:
    • the wallet processes them in the IncomingPaymentHandler
    • if it wishes to fulfill them, it reveals the preimage in open_channel2 or splice_init:
      • the service provider will push the corresponding amount
      • the wallet must also buy inbound liquidity at the same time, which ensures that:
        • some fees are paid to the service provider
        • future payments may be received without requiring an on-chain operation
        • the service provider has enough funds on their side for the commit tx fees
      • if disconnected, the service provider will remember how much it owes and the wallet can retry open_channel2 / splice_init on reconnection
        • it is now the responsibility of the wallet to initiate that operation, which simplifies state tracking on the service provider side
    • if it doesn't want to fulfill the corresponding payment, the wallet simply ignores the maybe_add_htlc message: the service provider will automatically fail the corresponding HTLCs after a short timeout
  • the only fees that are applied are the liquidity ads fees:
    • on-chain fees for the inputs/outputs contributed by the service provider to add inbound liquidity (as specified by the liquidity ads protocol)
    • service fees for the inbound liquidity purchased (as specified by the liquidity ads protocol)

⚠️ ⚠️ note that the DB logic changes, with the introduction of a Pending entry that must later by replaced by the final result: this must be correctly implemented on the wallet side when implementing the PaymentsDb trait! ⚠️ ⚠️

@t-bast t-bast mentioned this pull request Mar 11, 2024
Merged
@t-bast t-bast force-pushed the continuous-liquidity-ads branch 4 times, most recently from 05b49a8 to b23a526 Compare March 13, 2024 10:02
@t-bast
Remove please_open_channel
a7a0e70 
It is usually the wallet that decides that it needs a channel, but we
want the LSP to pay the commit fees to allow the wallet user to empty
its wallet over lightning. We previously used a `please_open_channel`
message that was sent by the wallet to the LSP, but it doesn't work
well with liquidity ads.

We remove that message and instead send `open_channel` from the wallet
but with a custom channel flag that tells the LSP that they should be
paying the commit fees. This only works if the LSP adds funds on their
side of the channel, so we couple that with liquidity ads to request
funds from the LSP.
@t-bast
Add liquidity ads to channel opening flow
fae1bed 
We previously only used liquidity ads with splicing: we now support it
during the initial channel opening flow as well. This lets us add more
unit tests, including tests for the case where the node receiving the
`open_channel` message is responsible for paying the commitment fees.
@t-bast t-bast force-pushed the continuous-liquidity-ads branch 7 times, most recently from 736e40c to 404125f Compare March 20, 2024 14:53
@t-bast t-bast marked this pull request as ready for review March 20, 2024 15:35
@t-bast t-bast requested a review from pm47 March 20, 2024 15:35
@t-bast
Replace pay_to_open with maybe_add_htlc
c7f4353 
We replace the previous pay-to-open protocol with a new protocol that
only relies on liquidity ads for paying fees. We simply transmit HTLCs
that cannot be relayed on existing channels with a new message called
`maybe_add_htlc` that contains all the HTLC data.

If the recipient wishes to accept that payment, it reveals the preimage
when sending `open_channel2` or `splice_init` and marks the on-chain
part of that payment as pending. It then keeps retrying the on-chain
funding operation until it completes or our peer sends a dedicated error
asking us to cancel it.
@t-bast
Use a list of liquidity ads rates
1b0f6ec 
The liquidity seller may adapt their lease rates to the funding amount,
to account for the fact that higher amounts will require more inputs,
and thus a larger `funding_weight`.
@t-bast
Add on-the-fly funding node events
3c20b3f 
Add more node events for on-the-fly funding operations. This is mostly
useful for tests to wait until specific steps have been reached into
the protocol execution.
@t-bast
Add on-the-fly fee credit feature
e54d9f8 
We add an optional feature that lets on-the-fly funding clients accept
payments that are too small to pay the fees for an on-the-fly funding.
When that happens, the payment amount is added as "fee credit" without
performing an on-chain operation. Once enough fee credit has been
obtained, we can initiate an on-chain operation to create a channel or
a splice.

This feature makes more efficient use of on-chain transactions by
trusting that our peer will honor our fee credit in the future.
@t-bast t-bast mentioned this pull request May 24, 2024
Draft
@t-bast
Copy link
Member Author

t-bast commented May 30, 2024

Replaced by #649

@t-bast t-bast closed this May 30, 2024
@t-bast t-bast deleted the continuous-liquidity-ads branch May 30, 2024 14:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@pm47 pm47 Awaiting requested review from pm47

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
1 participant
@t-bast