feat: add ldk gateway

[tvolk131]

Add a third lightning node type to the gateway, a lightning node powered by ldk-node which runs in the same process as the gateway. The gateway can be run in ldk mode by setting the following environment variables:

FM_LDK_ESPLORA_SERVER_URL: Esplora server where blockchain data is accessed
FM_LDK_NETWORK: The bitcoin network being used (e.g. mainnet/testnet)
FM_PORT_LDK: The port that the lightning server is running on, where other lightning nodes can access it

The node's data is stored in a subdirectory of the gateway's data folder

This gateway mode should still be considered experimental!!! None of the behavior is tested or has locked-in backwards compatibility yet!

[m1sterc001guy]

This seems really awkward to me. Does GatewayLdkClient need to own this? Can it be passed in as an argument to a function?

[tvolk131]

The gateway lightning client can be in two states - either it's inactive (not intercepting HTLCs) or active (intercepting HTLCs), and calling ILnRpcClient::route_htlcs spins up the HTLC interception, switching from the former state to the latter. Currently these two states are internally represented in the following way:

Inactive: GatewayLdkClient.htlc_stream_seeder_task_handle is already running and passing incoming HTLCs to the HTLC stream receiver. The HTLC stream receiver is held in GatewayLdkClient.htlc_stream_receiver_or until route_htlcs is called, at which point this receiver is taken and returned.

Active: GatewayLdkClient.htlc_stream_seeder_task_handle is still running. But the HTLC stream receiver has been passed to the caller of route_htlcs and so GatewayLdkClient.htlc_stream_receiver_or is None.

What if we changed GatewayLdkClient.htlc_stream_seeder_task_handle to be an Option<tokio::task::JoinHandle<()>>, removed GatewayLdkClient.htlc_stream_receiver_or altogether, and represented the states like this:

Inactive: GatewayLdkClient.htlc_stream_seeder_task_handle_or is None and ldk-node events are not being handled yet. The HTLC stream receiver doesn't exist yet.

Active: The HTLC stream sender and receiver are created when route_htlcs is called. The sender is passed into the htlc stream seeder task, which is started up and assigned to GatewayLdkClient.htlc_stream_seeder_task_handle_or. The receiver is returned by route_htlcs and never held by GatewayLdkClient.

WDYT?

[m1sterc001guy]

Let's chat about this offline

[m1sterc001guy]

What does "routing them" mean here?

[tvolk131]

Sorry, that was a strange wording. What I mean is we should only be handling events from ldk-node's event queue in one place to avoid having two threads stomping/skipping over events. Right now, event handling is done in GatewayLdkClient::event_handler_task_handle, so we'd need to add functionality there to handle PaymentSuccessful and PaymentFailed events and somehow be able to tell GatewayLdkClient::pay when a payment has succeeded or failed. This can definitely be done, but we'd need some sort of per-paymenthash queue or something.

I cleaned up the comment here

[m1sterc001guy]

does ldk node support setting the description hash in receive_for_hash?

[tvolk131]

I don't think so. Drilling down into the function calls here, we end up at this:

https://github.com/lightningdevkit/rust-lightning/blob/f48a273211d5235e1ff335b2c25f8aacf3642f24/lightning-invoice/src/utils.rs#L431-L453

Where _create_invoice_from_channelmanager_and_duration_since_epoch() accepts a Bolt11InvoiceDescription‎ (which can be a direct description or a hash) but is hardcoded to always be a direct description.

[m1sterc001guy]

This would probably be good to make an issue upstream

[tvolk131]

Created lightningdevkit/ldk-node#325

[dpc]

LGTM, but someone from @fedimint/lightning should approve.

[m1sterc001guy]

If you want to implement this, you could potentially use a channel to communicate from the event queue thread to here. Can be done in a follow up

[m1sterc001guy]

This will move self rather than clone it, which is what we do in the other implementations. As far as I can tell this won't cause any issues (whereas with LND we need to clone it). I assume this was intentional?

[tvolk131]

Yep! This was intentional. The reason that ILnRpcClient::route_htlcs consumes self and returns Arc<Self> (IIUC) is so that the type checker can enforce that it cannot be called twice. That should still be enforced here.

[Kodylow]

Blockers on this, waiting until after 0.4 to merge since we can't get this in this week and need to cut release with the DNS fix. This will be the next big merge.

• Liquidity API and other lightning functionality moved into gateway-cli and gateway api: The only way to interface with the underlying ldk-node is the gateway cli. Normally we use the node's api. For this, we need the gateway-cli to expose api functionality we'd normally just have the node use (open channel, close channel, sweep funds, etc) and add that into the gateway-cli. Instead of only doing this for the ldk node, we're going to implement this generically for all the supported node implementations across the gateway api, which means we can also do lightning side management from the gateway ui in https://github.com/fedimint/ui

  • We already support the liquidity ones for all node impls, we need to add the channel management ones in

• LNv2 has multi-mint support, but we're dropping that as part of the bolt12 refactor: 0.4 will still use LNv1, but ship with LNv2 binaries that optionally run with an env variable, then for 0.5 both v1 and v2 will run side by side, then 0.6 we retire lnv1.

LNv2 requires an implementation of pay_private for multi-mint payments which requires upstream changes to ldk-node (ldk-node doesn't let us do partial payments of an invoice).

• @joschisan : the way to go here is not to require multi-mint payments generally. We have pruned invoices which allow us to do partial payments, which are already supported by LND and CLN, so that made multi-mint payments easy. We intend to drop the pruned-invoices struct because they're causing a bunch of problems elsewhere in the codebase as we prepare for bolt12 support. So we're going to remove that multi-mint payment as part of LNv2 for now, which removes this blocker.

• LNv2 testing: waiting on ldk to be added to this list of gateway tests): https://github.com/fedimint/fedimint/pull/5651/files

[joschisan]

Respecting this parameters is security critical!