Skip to content

Commit 293078d

Browse files
carlaKCcarlaKC
committed
docs: add autoloop documentation
1 parent 96a2187 commit 293078d

File tree

2 files changed

+198
-0
lines changed

2 files changed

+198
-0
lines changed

‎README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,8 @@ swap is initiated successfully, `loopd` will see the process through.
186186

187187
To query in-flight swap statuses, run `loop monitor`.
188188

189+
The loop client also has the ability to automatically dispatch loop out swaps on your behalf - see our [autoloop documentation](https://github.com/lightninglabs/loop/blob/master/docs/autoloop.md) for details.
190+
189191
### Fees explained
190192

191193
The following is an example output of a 0.01 BTC fast (non-batched) Loop Out

‎docs/autoloop.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Autoloop
2+
The loop client contains functionality to dispatch loop out swaps automatically,
3+
according to a set of rules configured for your node's channels, within a
4+
budget of your choosing.
5+
6+
The autoloop functionality is disabled by default, and can be enabled using the
7+
following command:
8+
```
9+
loop setparams --autoout=true
10+
```
11+
12+
Swaps that are dispatched by the autolooper can be identified in the output of
13+
`ListSwaps` by their label field, which will contain: `[reserved]: autoloop-out`.
14+
15+
Even if you do not choose to enable the autolooper, we encourage you to
16+
experiment with setting the parameters described in this document because the
17+
client will log the actions that it would have taken to provide visibility into
18+
its functionality. Alternatively, the `SuggestSwaps` rpc (`loop suggestswaps`
19+
on the CLI) provides a set of swaps that the autolooper currently recommends,
20+
which you can use to manually execute swaps if you'd like.
21+
22+
Note that autoloop parameters and rules are not persisted, so must be set on
23+
restart. We recommend running loopd with `--debuglevel=debug` when using this
24+
feature.
25+
26+
### Channel Thresholds
27+
To setup the autolooper to dispatch swaps on your behalf, you need to tell it
28+
which channels you would like it to perform swaps on, and the liquidity balance
29+
you would like on each channel. Desired liqudity balance is expressed using
30+
threshold incoming and outgoing percentages of channel capacity. The incoming
31+
threshold you specify indicates the minimum percentage of your channel capacity
32+
that you would like in incoming capacity. The outgoing thresold allows you to
33+
reserve a percentage of your balance for outgoing capacity, but may be set to
34+
zero if you are only concerned with incoming capcity.
35+
36+
The autolooper will perform swaps that push your incoming channel capacity to
37+
at least the incoming threshold you specify, while reserving at least the
38+
outgoing capacity threshold. Rules can be set as follows:
39+
40+
```
41+
loop setrule {short channel id} --incoming_threshold={minimum % incoming} --outgoing_threshold={minimum % outgoing}
42+
```
43+
44+
To remove a channel from consideration, its rule can simply be cleared:
45+
```
46+
loop setrule {short channel id} --clear
47+
```
48+
49+
## Fees
50+
Fee control is one of the most important features of the autolooper, so we expose
51+
multiple fee related settings which can be used to tune the autolooper to your
52+
preference. Note that these fees are expressed on a per-swap basis, rather than
53+
as an overall budget.
54+
55+
### On-Chain Fees
56+
When performing a successful loop out swap, the loop client needs to sweep the
57+
on-chain HTLC sent by the server back into its own wallet.
58+
59+
#### Sweep Confirmation Target
60+
To estimate the amount of on-chain fees that the swap will require, the client
61+
uses a confirmation target for the sweep - the number of blocks within which
62+
you would like this balance swept back to your wallet. The time to acquire your
63+
incoming liquidity is not dependent on sweep confirmation time, so we highly
64+
recommend setting a very large sweep confirmation target (up to 250 blocks),
65+
so that your sweep can go through with very low fees.
66+
```
67+
loop setparams --sweepconf={target in blocks}
68+
```
69+
70+
#### Fee Market Awareness
71+
The mempool often clears overnight, or on the weekends when fewer people are
72+
using chain space. This is an opportune time for the autolooper to dispatch a
73+
swap on your behalf while you sleep! Before dispatching a swap, the autolooper
74+
will get a fee estimate for you on-chain sweep transaction (using its
75+
`sweepconftarget`), and check it against the limit that has been configured.
76+
The `sweeplimit` parameter can be set to configure the autolooper to only
77+
dispatch in low-fee environments.
78+
79+
```
80+
loop setparams --sweeplimit={limit in sat/vbyte}
81+
```
82+
83+
84+
#### Miner Fee
85+
In the event where fees spike dramatically right after a swap is dispatched,
86+
it may not be worthwhile to proceed with the swap. The loop client always uses
87+
the latest fee estimation to sweep your swap within the desired target, but to
88+
account for this edge case where fees dramatically spike for an extended period
89+
of time, a maximum miner fee can be set to cap the amount that will be paid for
90+
your sweep.
91+
```
92+
loop setparams --maxminer={limit in satoshis}
93+
```
94+
95+
### Server Fees
96+
#### Swap Fee
97+
The server charges a fee for facilitating swaps. The autolooper can be limited
98+
to a set swap fee using the following command:
99+
```
100+
loop setparams --maxswapfee={limit in satoshis}
101+
```
102+
103+
#### No-Show Fee
104+
In the case of a no-show, the server will charge a fee to recoup its on-chain
105+
costs. This value will only be charged if your client goes offline for a long
106+
period of time after the server has published an on-chain HTLC and never
107+
completes the swap, or if it decides to abort the swap due to high on-chain
108+
fees. Both of these cases are unlikely, but this value can still be capped in
109+
the autolooper.
110+
```
111+
loop setparams --maxprepay={limit in satoshis}
112+
```
113+
114+
### Off-Chain Fees
115+
The loop client dispatches two off-chain payments to the loop server - one for
116+
the swap prepayment, and one for the swap itself. The total amount that the
117+
client will pay in off-chain routing fees can be limited using the following
118+
command:
119+
```
120+
loop setparams --maxprepayfee={limit for swap in satoshis} --maxroutingfee={limit for prepay in satoshis}
121+
```
122+
123+
## Budget
124+
The autolooper operates within a set budget, and will stop executing swaps when
125+
this budget is reached. This budget includes the fees paid to the swap server,
126+
on-chain sweep costs and off-chain routing fees. Note that the budget does not
127+
include the actual swap amount, as this balance is simply shifted from off-chain
128+
to on-chain, rather than used up.
129+
130+
The budget value is expressed in satoshis, and can be set using the `setparams`
131+
loop command:
132+
```
133+
loop setparams --autobudget={budget in satoshis}
134+
```
135+
136+
Your autoloop budget can optionally be paired with a start time, which
137+
determines the time from which we will count autoloop swaps as being part of
138+
the budget. If this value is zero, it will consider all automatically
139+
dispatched swaps as being part of the budget.
140+
141+
The start time is expressed as a unix timestamp, and can be set using the
142+
`setparams` loop command:
143+
```
144+
loop setparams --budgetstart={start time in seconds}
145+
```
146+
147+
If your autolooper has used up its budget, and you would like to top it up, you
148+
can do so by either increasing the overall budget amount, or by increasing the
149+
start time to the present. For example, if you want to set your autolooper to
150+
have a budget of 100k sats for the month, you could set the following:
151+
```
152+
loop setparams --autobudget=100000 --autostart={beginning of month ts}
153+
```
154+
155+
## Dispatch Control
156+
Configuration options are also exposed to allow you to control the rate at
157+
which swaps are automatically dispatched, and the autolooper's propensity to
158+
retry channels that have previously failed.
159+
160+
### In Flight Limit
161+
The number of swaps that the autolooper will dispatch at a time is controlled
162+
by the `autoinflight` parameter. The default value for this parameter is 1, and
163+
can be increased if you would like to perform more automated swaps simultaneously.
164+
If you have set a very high sweep target for your automatically dispatched swaps,
165+
you may want to increase this value, because the autolooper will wait for the
166+
swap to fully complete, including the sweep confirming, before it dispatches
167+
another swap.
168+
169+
```
170+
loop setparams --autoinflight=2
171+
```
172+
173+
### Failure Backoff
174+
Sometimes loop out swaps fail because they cannot find an off-chain route to the
175+
server. This may happen because there is a temporary lack of liquidity along the
176+
route, or because the peer that you need to perform a swap with simply does not
177+
have a route to the loop server's node. These swap attempts cost you nothing,
178+
but we set a backoff period so that the autolooper will not continuously attempt
179+
to perform swaps through a very unbalanced channel that cannot facilitate a swap.
180+
181+
The default value for this parameter is 24hours, and it can be updated as follows:
182+
```
183+
loop setparams --failurebackoff={backoff in seconds}
184+
```
185+
186+
## Manual Swap Interaction
187+
The autolooper will not dispatch swaps over channels that are already included
188+
in manually dispatched swaps - for loop out, this would mean the channel is
189+
specified in the outgoing channel swap, and for loop in the channel's peer is
190+
specified as the last hop for an ongoing swap. This check is put in place to
191+
prevent the autolooper from interfering with swaps you have created yourself.
192+
If there is an ongoing swap that does not have a restriction placed on it (no
193+
outgoing channel set, or last hop), then the autolooper will take no action
194+
until it has resolved, because it does not know how that swap will affect
195+
liquidity balances.
196+

0 commit comments

Comments
 (0)