GlcoinCore/pool
1
0
Fork 0
mirror of https://github.com/lightninglabs/pool.git synced 2026-08-13 12:33:04 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: update documentation

Browse source
This commit is contained in:
positiveblue 2021-12-10 13:39:04 -08:00
parent 6884748a51
commit 0723aad6d4
No known key found for this signature in database
GPG key ID: 4FFF2510928804DC
7 changed files with 41 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

23
docs/account_recovery.md
View file

@ -3,15 +3,20 @@
In this section, we'll cover the possible ways of recovering the funds within a
Pool account upon data corruption/loss. Account funds are locked to a 2-of-2
multi-sig output of the account owner and the Pool auctioneer until the
account's expiration has been met, giving the account owner full control of the
funds. This expiration is included in the account output script, so it must be
known in order to spend the account funds. There are two possible ways to
recover an account's funds after data corruption/loss: one that requires the
Pool auctioneer's cooperation, which is the only method currently supported,
and one without, which will require storage of an additional data blob similar
to the Static Channel Backups present within `lnd`. An auctioneer-assisted
account recovery intent can be issued through the `pool accounts recover`
command or the `RecoverAccounts` RPC.
account's expiration has been met, giving the account owner the security that
funds will not be spend without the owner's consent. This expiration is included
in the account output script, so it must be known in order to spend the account
funds. There are two possible ways to recover an account's funds after data
corruption/loss:
- With Pool auctioneer's cooperation: which is the only method currently
supported.
- Without Pool auctioneer's cooperation: which will require storage of an
additional data blob similar to the Static Channel Backups present within
`lnd`.
An auctioneer-assisted account recovery intent can be issued through the
`pool accounts recover` command or the `RecoverAccounts` RPC.
```text
$ pool accounts recover -h

3
docs/accounts.md
View file

@ -17,7 +17,8 @@ Many interactions in Pool are based around accounts:
* Fees gained by selling channels are credited to your account
* Funds used to open channels to others are deducted from your account
As an account is just a UTXO, anytime a batch is cleared in the auction \(market made, channels bought+sold\), your account is spent, and re-created in the same transaction.
As an account is just a UTXO, anytime a batch is cleared in the auction \(market made, channels bought+sold\), your account is spent, and re-created in the same transaction. This applies to other actions like
deposit/withdraw funds from your account.
## Creating An Account

2
docs/batch_execution.md
View file

@ -22,7 +22,7 @@ Note that the trader can reject signing the batch for any reason, even when the
### Batch Publication
When all participating traders have signed their inputs in the Batch Execution Transaction, the auctioneer can sign the final input and broadcast the transaction. This transaction can be large, and serve as the funding transaction for potentially hundres of channels! The participating traders only pay chain fees for their inputs and outputs in the transaction, so everybody is saving substantially on fees compared to individually funding channels.
When all participating traders have signed their inputs in the Batch Execution Transaction, the auctioneer can sign the final input and broadcast the transaction. This transaction can be large, and serve as the funding transaction for potentially hundres of channels! The participating traders only pay chain fees for their inputs and outputs in the transaction, so everybody is saving substantially on fees compared to individually funding channels. If the trader supports account autorenewal and the account was close to expire, its expiry height will be automatically extended after the batch is sucessfully executed.
## Batched Uniform-Price Clearing

2
docs/channel_leases.md
View file

@ -30,5 +30,5 @@ Here we can see I sold a channel for 40k satoshis, and ended up paying 5k satosh
In the alpha version of Pool, _script level enforcement_ isn't yet implemented. Script level enforcement would lock the maker's funds in the channel for the lease period. This ensures that they can't just collect the premium \(before coupon channels\) and close out the channel instantly. With script enforcement, they would be able to close the channel \(force close it\), but their funds would be unavailable until the maturity period has passed.
Instead, we've implemented a feature in `lnd` to prevent channels from being _cooperatively closed_ by the maker until the expiry height \(what we call the `thaw_height`\). Additionally, if we detect a force close by the maker of that channel, then we'll ban them from the market for a set period of time.
Instead, we've implemented a feature in `lnd` to prevent channels from being _cooperatively closed_ by the maker until the expiry height \(what we call the `thaw_height`\).

20
docs/faq.md
View file

@ -24,7 +24,7 @@ You pay based on a percentage across time and it is not quite straightforward to
If you want to pay a specific amount, use trial and error of creating bids until the confirmation shows you your desired fee payment size.
It will not show you an exact total, but you can see how much you will pay in fee to the seller in the confirmation, in the confirmation the seller is called the “maker”
It will not show you an exact total, but you can see how much you will pay in fee to the seller in the confirmation, in the confirmation the seller is called the “maker”.
### How will I know if my order was fulfilled?
@ -38,11 +38,15 @@ pool orders list
A channel will be opened as soon as the batch transaction has received a sufficient number of confirmations. Batches are processed whenever the market clears or approximately every 10 minutes or whichever is longer.
The seller has to be online when the batch clears or the match won't be included
The seller has to be online when the batch clears or the match won't be included.
### Can I buy a channel for someone else?
Not at this time but this is something we plan to add in the future.
Yes, [sidecar channels](https://lightning.engineering/posts/2021-05-26-sidecar-channels/) solve this problem by enabling a third party to purchase channels on behalf of a user.
### Troubleshooting
[Join us on Slack](https://lightning.engineering/slack.html) and we'd be happy to help in any way we can.
## Channels
@ -52,7 +56,7 @@ The channel is opened automatically by the seller once the market clears.
### How long will the channel stay open?
It will stay open for a minimum of 2016 blocks \(approximately 2 weeks\).
You can specify the desired lease period in your orders. With a minimum of 2016 blocks \(approximately 2 weeks\).
### Does the channel close after the maturity date?
@ -68,7 +72,7 @@ No. The channel behaves like a regular channel.
### What happens if the seller force closes a channel before the maturity date?
If the lender force closes they will be banned from the market. This will not be possible in the future.
Script level enforcement enables us to lock the maker's funds in the channel for the lease period. However, you need an LND node that supports this feature and you need to opt in. By default, we use a feature in `lnd` to prevent channels from being _cooperatively closed_ by the maker until the expiry height \(what we call the `thaw_height`\).
### If off-chain funds have moved over to my side, must I keep them there?
@ -88,13 +92,13 @@ This is necessary so that users can recover funds in the event our servers were
### What do I do if my account expires?
You will need to close your account and then re-open your account. In the future we will enable account renewals.
You can renew expired accounts with the `pool accounts renew [command options] trader_key sat_per_vbyte [--expiry_height | --expiry_blocks]`. This will broadcast a chain transaction as the expiry is enforced within the account output script.
## Matching
### Can I choose who to buy from?
You are not able to choose who to buy from but by default only well-connected nodes who are on the Bos Score List are eligible to sell liquidity.
You are not able to choose who to buy from but by default only well-connected nodes who are on the Bos Score List are eligible to sell liquidity. You can disable this restriction setting the `--min_node_tier=0` parameter when submiting an order.
### Can sellers choose their buyers or blacklist certain buyers?
@ -135,7 +139,7 @@ The seller earns the routing fees. You can also earn fees if that new channel is
### Can the seller increase their fee rate after opening the channel?
Yes they can adjust their routing policy however this will be penalized in the future.
Yes they can adjust their routing policy. However, this will be penalized in the future.
### Can I specify the maximum fee rate of a peer I’m buying liquidity from?

10
docs/orders.md
View file

@ -117,6 +117,7 @@ OPTIONS:
--min_chan_amt value the minimum amount of satoshis that a resulting channel from this order must have (default: 0)
--force skip order placement confirmation
--max_batch_fee_rate value the maximum fee rate (sat/vByte) to use to for the batch transaction (default: 100)
--channel_type value the type of channel resulting from the order being matched ("legacy", "script-enforced") (default: "legacy")
```
NOTE: The default values shown in the command line help are different from the actual default values that are used. A value of `0` on the command line indicates: _No actual value set, use the internal default value_. See the table below for more information.
@ -129,6 +130,7 @@ NOTE: The default values shown in the command line help are different from the a
| `lease_duration_blocks` | No | `2016` | The minimum number of blocks the offered channels need to stay open for in order to satisfy the contract. Distinct markets are available for the different durations. See [lease duration section](orders.md#lease-duration) for more information. |
| `min_chan_amt` | No | 10% of `amt` | The minimum size/capacity of any offered channel. Higher values reduce the match potential but decrease the potential total in chain fees that must be paid. Must be a multiple of the base unit \(100k sat\). See [chain fees section](orders.md#chain-fees) for more information. |
| `max_batch_fee_rate` | No | `100` sat/vByte | The maximum on-chain fee rate at which this order should be eligible to be included in a batch. If the auctioneer estimates a higher fee rate, orders below will be skipped. See [chain fees section](orders.md#chain-fees) for more information. |
| `channel_type` | No | legacy | the type of channel resulting from the order being matched |
| `force` | No | `false` | When set to `true`, no order details will be shown and no confirmation is required. |
### Bid orders
@ -160,8 +162,11 @@ OPTIONS:
--lease_duration_blocks value the number of blocks that the liquidity should be provided for (default: 2016)
--min_node_tier value the min node tier this bid should be matched with, tier 1 nodes are considered 'good', if set to tier 0, then all nodes will be considered regardless of 'quality' (default: 0)
--min_chan_amt value the minimum amount of satoshis that a resulting channel from this order must have (default: 0)
--force skip order placement confirmation
--self_chan_balance value give the channel leased by this bid order an initial balance by adding additional funds from our account into the channel; can be used to create up to 50/50 balanced channels (default: 0)
--sidecar_ticket value instead of leasing a channel for the node connected to this pool instance, lease a channel for another node; use the information within the ticket to identify the receiver of the sidecar channel; using a sidecar ticket will also overwrite the amt, min_chan_amt, lease_duration_blocks and self_chan_balance fields
--max_batch_fee_rate value the maximum fee rate (sat/vByte) to use to for the batch transaction (default: 100)
--channel_type value the type of channel resulting from the order being matched ("legacy", "script-enforced") (default: "legacy")
--force skip order placement confirmation
```
NOTE: The default values shown in the command line help are different from the actual default values that are used. A value of `0` on the command line indicates: _No actual value set, use the internal default value_. See the table below for more information.
@ -175,6 +180,9 @@ NOTE: The default values shown in the command line help are different from the a
| `min_chan_amt` | No | 10% of `amt` | The minimum size/capacity of any leased channel. Higher values reduce the match potential but decrease the potential total in chain fees that must be paid. Must be a multiple of the base unit \(100k sat\). See [chain fees section](orders.md#chain-fees) for more information. |
| `min_node_tier` | No | `1` | The minimum quality of node this bid should be matched with. The default \(if no command line flag is set\) is "Tier 1" which means the bid is only matched with asks from nodes that are considered "good". When manually setting this to `--min_node_tier=0` then asks from all nodes should be considered, regardless of their "quality". |
| `max_batch_fee_rate` | No | `100` sat/vByte | The maximum on-chain fee rate at which this order should be eligible to be included in a batch. If the auctioneer estimates a higher fee rate, orders below will be skipped. See [chain fees section](orders.md#chain-fees) for more information. |
| `self_chan_balance` | No | `0` | Give the channel leased by this bid order an initial balance by adding additional funds from our account into the channel; can be used to create up to 50/50 balanced channels |
| `sidecar_ticket` | No | `false` | Instead of leasing a channel for the node connected to this pool instance, lease a channel for another node; use the information within the ticket to identify the receiver of the sidecar channel; using a sidecar ticket will also overwrite the amt, min_chan_amt, lease_duration_blocks and self_chan_balance fields |
| `channel_type` | No | `legacy` | The type of channel resulting from the order being matched |
| `force` | No | `false` | When set to `true`, no order details will be shown and no confirmation is required. |
## Lease duration

3
docs/quickstart.md
View file

@ -15,7 +15,8 @@ To run `poold` integrated into the Lightning Terminal, download [the latest rele
Pool needs to be connected to an `lnd` node running somewhere. We assume here
that the `lnd` node is running and set up in a way that Pool can connect to it.
Consult the [installation guide](./install.md) for more information on how to
set up and configure `lnd`.
set up and configure `lnd`. Although pool supports `lnd` from version `v0.12.0-beta`,
`v0.13.3-beta` or later is recommended.
The `lnd` node must have at least one active channel and **must be able to pay
a 1000 satoshi [LSAT fee](https://lsat.tech)**. See [the FAQ](./faq.md#fees) for