Skip to content

Commit 5fb28f9

Browse files
author
Antoine Riard
committed
Add a mobile in-depth doc starter
1 parent 376202d commit 5fb28f9

File tree

3 files changed

+119
-3
lines changed

3 files changed

+119
-3
lines changed

‎docs/mobile.md

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
id: mobile
3+
title: "LDK for Lightning mobile devices"
4+
---
5+
6+
## Introduction
7+
8+
This documents covers the challenges of building a mobile-first Lightning node and what
9+
solution LDK offers. Note, this documentation already supposes a reader's familiarity with
10+
the Lightning protocol and Bitcoin fundamental notions.
11+
12+
* [Fee Estimation](#fee-estimation) covers issues related to fee-estimation
13+
* [Liveliness & Watchtowers](#watchtowers) covers issues related to Lightning liveliness requirement
14+
* [Chain-validation](#chain-validation) covers issues related to chain validation
15+
16+
## Fee Estimation
17+
18+
A Lightning node can broadcast four types of transactions. A _funding transaction_, to open one or
19+
multiple channel transactions. A _penalty transaction_ in reaction of a cheating by a counterparties
20+
to double-spend a channel. A _commitment transaction_, either motivated by reallocating funds
21+
locked in this channel to another purpose or in reaction to a in-flight HTLC to claim onchain. Such
22+
unilateral broadcast should only happen when the counterparty is faulting to cooperate. A _closing
23+
transaction_, cooperatively built by parties to complete the channel.
24+
25+
Block space being a scarce resources, a Lightning node, similar to any other kind of Bitcoin applications
26+
is in competition to confirm its transactions. While bidding to get its transaction included, a
27+
Bitcoin application's fee-estimation should be as accurate as possible to save in fees. Further, a
28+
Lightning node has a time-sensitive requirement with regards to confirmation. Commitment and penalty
29+
transactions, must be confirmed before a block height timelock expire. After the timelock expiration
30+
the counterparty can confirm transactions at its advantage, resulting in a loss of funds of the
31+
Lightning user.
32+
33+
Contrary to simple Bitcoin transactions, of which the delaying of confirmation isn't directly
34+
provoking losses, in Lightning fee-estimation accuracy is a safety-critical requirement.
35+
36+
Bitcoin Core implements fee-estimation in a way which attemps to be robust against various censorship
37+
attacks by analyzing transactions that were both in its mempool and were later confirmed. By avoiding
38+
waiting for confirmation, other fee estimators may respond faster to fee spikes. Due to its
39+
immediate confirmation pressure, Lightning may benefit from a fee estimator more in the second
40+
category, but care must be taken to avoid P2P censorship attacks or unbounded fee inflation. LDK
41+
attempts to deal with insufficient fee-estimation by using RBF and slowly increasing transaction
42+
fees until confirmation.
43+
44+
LDK offers a `lightning-fee-estimation` crate and its bindings, implementing the
45+
`chaininterface::FeeEstimator` trait and thus servicing smoothly the rest of the LDK engine. This
46+
utility will be a RPC HTTP client, configurable to be pointed toward any Bitcoin Core full-node.
47+
48+
## Liveliness & Watchtowers
49+
50+
A Lightning node must always monitor blockchain updates to react in consequence, either in case of
51+
a revoked commitment transaction confirmed or reaching block height at which an HTLC expires. This
52+
is a strong requirement as even missing few hours of blocks might trigger a loss of funds. Mobile
53+
devices with an unreliable access to Internet or often shutdown by their users are particularly
54+
sensible to this issue.
55+
56+
This liveliness requirement is function of which Lightning situation is considered.
57+
58+
As soon, as a payment has been initiated on the channel, your counterparty can broadcast _any old
59+
commitment_ at _any time_ thus forcing your Lightning node to be always online in anticipation of such
60+
an event. Watchtowers have been designed by the Lightning community to delegate such justice
61+
enforcement function to an external entity. As this entity is trusted to broadcast client penalty
62+
transactions, it is recommended to rely on multiple of them.
63+
64+
Currently, the LDK community is engaged on adoption of BOLT13, a cross-implementation standard
65+
for watchtowers. LDK hope to offer soon a client-side implementation of BOLT13, pluggable on
66+
the LDK engine. Beyond, if channels are opened with low-trust counterparties, it's recommended
67+
to use longuer timelocks delays in your configuration (`ChannelHandshakeConfig::our_to_self_delay`).
68+
69+
With regards to handling in-flight HTLCs, a Lightning node not online when an HTLC has expired is
70+
taking the risk of seeing its counterparty canceling onchain the HTLC and thus loosing funds.
71+
72+
In case of sending a payment, if it doesn't succeed immediately (e.g waiting on the receiver to
73+
be online), the mobile should be back online later to remove the sent HTLC in cooperation with
74+
channel counterparty or worst-case scenario to broadcast onchain the commitment transaction and
75+
a corresponding HTLC-timeout. Setting a long CLTV delay at first hop relay offers a _time window_
76+
for how long the mobile device can be offline. Ideally, the Lightning application will send a
77+
notification to the user at half of the CLTV delay warning about the requirement to connect back
78+
to the network.
79+
80+
In case of receiving a payment, if it doesn't succeed immediately (e.g waiting on payer interactions
81+
to receive the preimage), the mobile should be back online to hopefully learn payment preimage
82+
and thus either claim the received HTLC in cooperation with channel counterparty or worst-case scenario
83+
to broadcast onchain the commitment transaction and a corresponding HTLC-Success. Requiring a long
84+
CLTV delay at last hop offers a _time window_ for how long the mobile device can be offline. With
85+
LDK, this can be easily done by checking `event::PaymentReceived` at reception. Ideally, the
86+
Lightning application will send a notification to the user at half of the CLTV delay warning about
87+
the requirement to connect back to the network.
88+
89+
Note, if you don't have HTLC in-flight, checking the chain once per day (depending on your justice
90+
CSV delay) is a safe behavior.
91+
92+
## Chain Validation
93+
94+
A Lightning node needs access to the chain to verify channel utxo state. Failure to do so
95+
might lead to accept payments on a non-existent or already-closed channel, thus provoking a loss of
96+
funds. As chain validation is a costly processing, a mobile device might not have the bandwidth/CPU/
97+
storage resources to allocate for.
98+
99+
In the Bitcoin ecosystem, mobile devices have been in practice relying on lightclient protocols
100+
such as Electrum, BIP37 or BIP157 to access chain data. If the server isn't operated by the mobile
101+
device user, it should be noted that funds security might be jeopardized by this entity.
102+
103+
LDK offers a ready-to-integrate client that fetches full block from RPC or REST, serviced by a
104+
Bitcoin Core node. Its API allows you yo build a filtering client to parse chain data for the
105+
rest of the LDK engine (`chain::Filter`).
106+
107+
Note, a Lightning client doesn't have to wait syncing with chain tip to start some LN operations.
108+
Assuming client wallet keys have not leaked, a channel funding sequence should be always valid.
109+
Further, sending payment is only decreasing user balance. In case of the channel being already
110+
closed, the user balance committed onchain will be higher, thus at its advantage (and a loss for
111+
the counterparty...)

‎docs/use_cases.md

+7-2
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,13 @@ supports routing data being fetched via the Lightning P2P protocol, an external
1919
service, or routes can be calculated off-device. It also provides cross-platform
2020
compatibility for free, allowing synchronization of lightning state across
2121
devices and, as long as there is protection from simultaneous-updates, users to
22-
access their wallet on any device. See the [Overview](overview.md) page for more
23-
details on the interfaces LDK provides for integration.
22+
access their wallet on any device.
23+
24+
See the [Overview](overview.md) page for more details on the interfaces LDK
25+
provides for integration.
26+
27+
See the [Mobile](mobile.md) page for more details on the challenges of
28+
Lightning on mobile devices and what solutions LDK offers.
2429

2530
## HSMs (Hardware Security Modules)
2631

‎sidebars.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
module.exports = {
22
someSidebar: {
33
'Lightning Development Kit': ['overview', 'use_cases'],
4-
Guides: ['build_node', 'open_channel', 'key_mgmt', 'blockdata'],
4+
Guides: ['build_node', 'open_channel', 'key_mgmt', 'blockdata', 'mobile'],
55
},
66
};

0 commit comments

Comments
 (0)