Skip to content

Commit 9a5399e

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

File tree

3 files changed

+123
-3
lines changed

3 files changed

+123
-3
lines changed

‎docs/mobile.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
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 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 to produce their effect, must be confirmed before a block height timelock expire.
30+
Beyond timelock expiration the counterparty can confirm transactions at its advantage, thus
31+
provoking a loss of funds of the 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+
A Bitcoin full-node implements its fee-estimation on top of its mempool, by observing deltas
37+
between buckets of transactions sorted by feerate and their potential confirmations in blocks. As
38+
mobile clients are devoid of a mempool and don't fully participate in transaction relay on the p2p
39+
network, they have to delegate their fee estimation. Such delegation might be done towards a
40+
Bitcoin full-node instance operated by the mobile user or a third-party service, like a block explorer.
41+
42+
LDK will offer soon a `lightning-fee-estimation` crate and its bindings, implementing the
43+
`chaininterface::FeeEstimator` trait and thus servicing smoothly the rest of the LDK engine. This
44+
utility will be a RPC HTTP client, configurable to be pointed toward any Bitcoin Core full-node.
45+
46+
## Liveliness & Watchtowers
47+
48+
A Lightning node must always monitor blockchain updates to react in consequence, either in case of
49+
a revoked commitment transaction confirmed or reaching a given block height expirying a HTLC. This
50+
is a strong requirement as even missing few hours of blocks might trigger a loss of funds. Mobile
51+
devices with an unreliable access to Internet or often shutdown by their users are particularly
52+
sensible to this issue.
53+
54+
This liveliness requirement is function of which Lightning situation is considered.
55+
56+
As soon, as a payment has been initiated on the channel, your counterparty can broadcast _any old
57+
commitment_ at _any time_ thus forcing your Lightning node to be always online in prevision of such
58+
an event. Watchtowers have been designed by the Lightning community to delegate such justice
59+
enforcement function to an external entity. As this entity is trusted to broadcast client penalty
60+
transactions, it is recommended to rely on multiple of them.
61+
62+
Currently, the LDK community is engaged on adoption of BOLT13, a cross-implementation standard
63+
for watchtowers. LDK hope to offer soon a client-side implementation of BOLT13, pluggable on
64+
the LDK engine. Beyond, if channels are opened with low-trust counterparties, it's recommended
65+
to use longuer timelocks delays in your configuration (`ChannelHandshakeConfig::our_to_self_delay`).
66+
67+
With regards to handling in-flight HTLCs, a Lightning node not online when a HTLC has expired is
68+
taking the risk of seeing its counterparty canceling onchain the HTLC and thus loosing funds.
69+
70+
In case of sending a payment, if it doesn't succeed immediately (e.g waiting on the receiver to
71+
be online), the mobile should be back online later to remove the sent HTLC in cooperation with
72+
channel counterparty or worst-case scenario to broadcast onchain the commitment transaction and
73+
a corresponding HTLC-timeout. Setting a long CLTV delay at first hop relay offers a _time window_
74+
for how long the mobile device can be offline. Ideally, the Lightning application will send a
75+
notification to the user at half of the CLTV delay warning about the requirement to connect back
76+
to the network.
77+
78+
On the UX-side, as soon the HTLC is sent on the channel, the user balance should be decreased
79+
accordingly as unlock secret might already be known by counterparty or receiver. In the future,
80+
the PTLC protocol extension will allow to acknowledge that the payment has been received by
81+
expected payee before to decrease balance.
82+
83+
In case of receiving a payment, if it doesn't succeed immediately (e.g waiting on payer interactions
84+
to receive the preimage), the mobile should be back online to hopefully learn payment preimage
85+
and thus either claim the received HTLC in cooperation with channel counterparty or worst-case scenario
86+
to broadcast onchain the commitment transaction and a corresponding HTLC-Success. Requiring a long
87+
CLTV delay at last hop offers a _time window_ for how long the mobile device can be offline. With
88+
LDK, this can be easily done by checking `event::PaymentReceived` at reception. Ideally, the
89+
Lightning application will send a notification to the user at half of the CLTV delay warning about
90+
the requirement to connect back to the network.
91+
92+
On the UX-side, the user balance should only be increased when a `revoke_and_ack` message is received
93+
from the counterparty or the HTLC has been claimed onchain. Otherwise, you can't exclude onchain
94+
claims races depriving the user from its payment.
95+
96+
## Chain Validation
97+
98+
A Lightning node needs access to the chain to verify channel utxo state. Failure to do so
99+
might lead to accept payments on a non-existent or already-closed channel, thus provoking a loss of
100+
funds. As chain validation is a costly processing, a mobile device might not have the bandwidth/CPU/
101+
storage resources to allocate for.
102+
103+
In the Bitcoin ecosystem, mobile devices have been in practice relying on lightclient protocols
104+
such as Electrum, BIP37 or BIP157 to access chain data. If the server isn't operated by the mobile
105+
device user, it should be noted that funds security might be jeopardized by this entity.
106+
107+
LDK offers a ready-to-integrate utility to fetch chain data from a Bitcoin Core node servicing
108+
BIP157 filters. This utility will produce blocks to the rest of the LDK engine through
109+
implementing `chain::Listen` interface.
110+
111+
Note, a Lightning client doesn't have to wait syncing with chain tip to start some LN operations.
112+
Assuming client wallet keys have not leaked, a channel funding sequence should be always valid.
113+
Further, sending payment is only decreasing user balance. In case of the channel being already
114+
closed, the user balance committed onchain will be higher, thus at its advantage (and a loss for
115+
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)