diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 25ab748..452d7cf 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,10 +3,10 @@ * [Introduction](README.md) * [Overview](overview.md) * [Installation](install.md) +* [Quickstart](quickstart.md) * [Accounts](accounts.md) * [Orders](orders.md) * [Channel Leases](channel_leases.md) * [Batch Execution](batch_execution.md) -* [Alpha Limitations](alpha_limitations.md) * [FAQs](faq.md) diff --git a/docs/accounts.md b/docs/accounts.md index bbb94d9..f506c36 100644 --- a/docs/accounts.md +++ b/docs/accounts.md @@ -1,7 +1,5 @@ # Accounts -Accounts - ## Overview Like any exchange/auction, before you can start trading, you'll need an account! Accounts in the Pool are actually special on-chain contracts. A user deposits a certain amount of funds into an account which has a set expiry. By having users commit funds to an account in order to place orders, we ensure that they're unable to spoof orders \(placing an order that they can't fulfill\). We also add a cost to attempting to sybil attack the venue as well. @@ -13,7 +11,7 @@ The script for an account is very simple, funds can be moved from the account: This script resembles certain two-factor wallets with a time-lock escape clause. The second clause ensures that users are able to move their funds if the auctioneer is unavailable. -Many interactions in CLM are based around accounts: +Many interactions in Pool are based around accounts: * Fees paid to the auctioneer are deducted from your account * Fees gained by selling channels are credited to your account diff --git a/docs/alpha_limitations.md b/docs/alpha_limitations.md deleted file mode 100644 index 61b1b8d..0000000 --- a/docs/alpha_limitations.md +++ /dev/null @@ -1,2 +0,0 @@ -# Alpha Limitations - diff --git a/docs/batch_execution.md b/docs/batch_execution.md index 3e7033f..47d2e21 100644 --- a/docs/batch_execution.md +++ b/docs/batch_execution.md @@ -1,100 +1,43 @@ # Batch Execution -Now that we have orders submitted, how does the rest of the auction actually -work? As mentioned above, Pool conducts a _discrete_ batch auction every 10 -minutes. This is distinct from regular continuous exchanges in that orders are -only cleared every 10 minutes. Orders are also sealed-bid, meaning that other -traders in the venue are unable to see what others have bid. On top of this, we -utilize a uniform-clearing price algorithm to give all traders in the batch the -_same_ interest rate. This is the same mechanism used by the U.S Treasury for -its bonds, and is intended to promote fairness as your order will only be -matched with a price better than your initial ask/bid. +Now that we have orders submitted, how does the rest of the auction actually work? As mentioned above, Pool conducts a _discrete_ batch auction every 10 minutes. This is distinct from regular continuous exchanges in that orders are only cleared every 10 minutes. Orders are also sealed-bid, meaning that other traders in the venue are unable to see what others have bid. On top of this, we utilize a uniform-clearing price algorithm to give all traders in the batch the _same_ interest rate. This is the same mechanism used by the U.S Treasury for its bonds, and is intended to promote fairness as your order will only be matched with a price better than your initial ask/bid. -Note that it's possible that after the 10 minutes interval has passed a market -can't be made \(supply and demand didn't cross\). In this case, nothing -happens, and we just wait for the next batch to come across. +Note that it's possible that after the 10 minutes interval has passed a market can't be made \(supply and demand didn't cross\). In this case, nothing happens, and we just wait for the next batch to come across. ### Matchmaking -The first stage in batch execution is the matchmaking that is done by the -auctioneer. Before actual matchmaking is performed, the auctioneer looks at the -current fee climate and decides what fee rate should be used for the final -Batch Execution Transaction, in order for the transaction to confirm in a -timely manner. All orders that have their `max_batch_fee_rate` set to a value -lower than the chosen fee rate are ignored from the auction this time around, -but will be reconsidered if the fee climate changes before the next auction. -This allows traders with a low time preference to submit orders that will stay -around on the order book and only be considered for matchmaking in times of low -chain fees. +The first stage in batch execution is the matchmaking that is done by the auctioneer. Before actual matchmaking is performed, the auctioneer looks at the current fee climate and decides what fee rate should be used for the final Batch Execution Transaction, in order for the transaction to confirm in a timely manner. All orders that have their `max_batch_fee_rate` set to a value lower than the chosen fee rate are ignored from the auction this time around, but will be reconsidered if the fee climate changes before the next auction. This allows traders with a low time preference to submit orders that will stay around on the order book and only be considered for matchmaking in times of low chain fees. -Now that the transaction fee rate has been chosen, all orders still on the -order book are considered, and the auctioneer matches asks with bids that pay -at least the desired rate. The unsigned Batch Execution Transaction (BET) is -assembled and presented to all traders that had their orders matched, along -with information about the node they matched with. +Now that the transaction fee rate has been chosen, all orders still on the order book are considered, and the auctioneer matches asks with bids that pay at least the desired rate. The unsigned Batch Execution Transaction \(BET\) is assembled and presented to all traders that had their orders matched, along with information about the node they matched with. ### Batch Signing -When the trader's client receives a notification about a batch that is under -execution, it checks that every part of the BET that affects the trader meets -its requirements. This includes checking that the premium paid to the maker -matches the batch clearing price, and that the chain fee deducted from the -trader's account doesn't violate the max fee rate the trader agreed to. +When the trader's client receives a notification about a batch that is under execution, it checks that every part of the BET that affects the trader meets its requirements. This includes checking that the premium paid to the maker matches the batch clearing price, and that the chain fee deducted from the trader's account doesn't violate the max fee rate the trader agreed to. -Each match the trader was part of results in a channel output on the BET, and -the trader will also ensure this is well formed, and of the expected amount. -When that has been verified, the trader connects to the node on the other side -of the match, and starts the channel opening process with the channel peer. -Technically this is done by setting up a _funding shim_ with the backing `lnd` -node, which prepares `lnd` for a funding transaction setting up a channel with -the given parameters to be broadcast. +Each match the trader was part of results in a channel output on the BET, and the trader will also ensure this is well formed, and of the expected amount. When that has been verified, the trader connects to the node on the other side of the match, and starts the channel opening process with the channel peer. Technically this is done by setting up a _funding shim_ with the backing `lnd` node, which prepares `lnd` for a funding transaction setting up a channel with the given parameters to be broadcast. -Only when all these checks are satisfactory and the channel funding shim has -been successfully set up, the trader signs its input to the batch transaction -and responds to the auctioneer. This ensures the trader is always _fully in -custody of its own funds_, and never signs a transaction that would send the -funds to an output it doesn't control. +Only when all these checks are satisfactory and the channel funding shim has been successfully set up, the trader signs its input to the batch transaction and responds to the auctioneer. This ensures the trader is always _fully in custody of its own funds_, and never signs a transaction that would send the funds to an output it doesn't control. -Note that the trader can reject signing the batch for any reason, even when the -BET is well formed. For instance, connecting to the channel peer can fail, -resulting in the channel not being ready to be funded. The trader will reject -this match, and matchmaking can start over, making sure the trader won't be -matched with this channel peer again. +Note that the trader can reject signing the batch for any reason, even when the BET is well formed. For instance, connecting to the channel peer can fail, resulting in the channel not being ready to be funded. The trader will reject this match, and matchmaking can start over, making sure the trader won't be matched with this channel peer again. ### 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. ## Batched Uniform-Price Clearing -To illustrate how the uniform price clearing works consider the following -example. Let's say I want to buy 100 million satoshis \(1 BTC, 1000 units\), -for 2 weeks \(2016 blocks\) at a price of 5% \(using high numbers to make it -easy to follow\). However, the _market clearing price_ \(where the -supply+demand curves cross\) is actually 1%. In this case I bid _more_ than the -market clearing price, but end up paying that price, as it's the best price -that was possible in that market. +To illustrate how the uniform price clearing works consider the following example. Let's say I want to buy 100 million satoshis \(1 BTC, 1000 units\), for 2 weeks \(2016 blocks\) at a price of 5% \(using high numbers to make it easy to follow\). However, the _market clearing price_ \(where the supply+demand curves cross\) is actually 1%. In this case I bid _more_ than the market clearing price, but end up paying that price, as it's the best price that was possible in that market. A simple rule of thumb for bids and asks is as follows: * When I submit a bid, I'll either pay that amount or less. * When I submit an ask, I'll either receive that amount or more. -All orders in a batch are executed in a _single_ on-chain transaction. This -allows for thousands of channels to be bought/sold atomically in a single -block. We call the transaction that executes the orders the Batch Execution -Transaction. +All orders in a batch are executed in a _single_ on-chain transaction. This allows for thousands of channels to be bought/sold atomically in a single block. We call the transaction that executes the orders the Batch Execution Transaction. -The `pool auction` sub-command houses a number of useful commands to explore -the past batches, and examine the current auction parameters. +The `pool auction` sub-command houses a number of useful commands to explore the past batches, and examine the current auction parameters. -One can browse the latest cleared batch using the `pool auction snapshot` -command: +One can browse the latest cleared batch using the `pool auction snapshot` command: ```text ๐Ÿ” pool auction snapshot @@ -127,19 +70,11 @@ command: } ``` -Here we see a batch where a single order was matched, at a clearing rate of -`1636`, with a single channel being purchased with a lifetime of `2016` blocks, -or roughly two weeks. +Here we see a batch where a single order was matched, at a clearing rate of `1636`, with a single channel being purchased with a lifetime of `2016` blocks, or roughly two weeks. -Note that the `pool auction snapshot` command can be used to determine the past -marker clearing price, which can be useful when deciding what your bid/ask -should be. There's no explicit "market buy" function, but submitting a bid/ask -at a similar `clearing_price_rate` to the historical one should put you close -to where the demand in the market is. +Note that the `pool auction snapshot` command can be used to determine the past marker clearing price, which can be useful when deciding what your bid/ask should be. There's no explicit "market buy" function, but submitting a bid/ask at a similar `clearing_price_rate` to the historical one should put you close to where the demand in the market is. -The command also accept a target `batch_id` as well. Here we can use the -`prev_batch_id` to examine the _prior_ batch, similar to traversing a -link-listed/blockchain: +The command also accept a target `batch_id` as well. Here we can use the `prev_batch_id` to examine the _prior_ batch, similar to traversing a link-listed/blockchain: ```text ๐Ÿ” pool auction snapshot --batch_id=03687baa3c7414e800ddba37edacb3281999739303b7290a69bd457f428ecd9b2c @@ -147,9 +82,7 @@ link-listed/blockchain: ## Fees -There are various fees paid and accumulated during a successful batch -execution. The easiest way to get an overview of the total impact of fees on -ones account is to run +There are various fees paid and accumulated during a successful batch execution. The easiest way to get an overview of the total impact of fees on ones account is to run ```text ๐Ÿ” pool auction leases @@ -194,18 +127,9 @@ ones account is to run } ``` -Here you can see a summary of all matches you've been part of and that resulted -in a channel being opened. In the first example the trader sold a 1,200,000 sat -channel and got paid a premium of 59,998 sats for this liquidity. To be part of -this batch, the trader paid an execution fee of 1201 sats, and a chain fee of -165 sats, netting 59998-1201-165 = 58632 sats that got paid to its account. +Here you can see a summary of all matches you've been part of and that resulted in a channel being opened. In the first example the trader sold a 1,200,000 sat channel and got paid a premium of 59,998 sats for this liquidity. To be part of this batch, the trader paid an execution fee of 1201 sats, and a chain fee of 165 sats, netting 59998-1201-165 = 58632 sats that got paid to its account. -In the last example in the list above, the trader this time around bought a -channel of 1,200,000 sats, and paid a premium of 11999 to the seller. Also this -time around the trader paid an execution fee and chain fee, resulting in a -total cost of 11999+1201+165 = 13365 sats. +In the last example in the list above, the trader this time around bought a channel of 1,200,000 sats, and paid a premium of 11999 to the seller. Also this time around the trader paid an execution fee and chain fee, resulting in a total cost of 11999+1201+165 = 13365 sats. -Finally, a total tally of fees earned and paid is given. The command takes -optional account and batch id arguments in case you want to filter the leases -returned. +Finally, a total tally of fees earned and paid is given. The command takes optional account and batch id arguments in case you want to filter the leases returned. diff --git a/docs/channel_leases.md b/docs/channel_leases.md index eac9468..63c6c49 100644 --- a/docs/channel_leases.md +++ b/docs/channel_leases.md @@ -1,8 +1,6 @@ # Channel Leases -## Channel Leases - -### Overview +## Overview Once an order has been matched in an auction, the `pool auction leases` command can be used to examine your current set of purchased/sold channel leases. An example output looks something like the following: @@ -28,8 +26,9 @@ Once an order has been matched in an auction, the `pool auction leases` command Here we can see I sold a channel for 40k satoshis, and ended up paying 5k satoshis in chain and execution fees, netting a cool 35k satoshi yield. Within the actual auction, these numbers will vary based on the chain fee rate, the market prices, and also the execution fees. Users can constraint how much chain fees they'll pay by setting the `--max_batch_fee_rate` argument when submitting orders. -### Service Level Lifetime Enforcement +## Service Level Lifetime Enforcement 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. + diff --git a/docs/faq.md b/docs/faq.md index b26c3d5..3f2d4c1 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -12,10 +12,6 @@ description: >- A channel is opened to you after paying an upfront premium for inbound channel liquidity of a specific size for a set duration of time \(2016 blocks\). Once the upfront premium is paid a channel is opened to the buyer. -### How do I buy inbound channel liquidity? - - - ### How is the price of inbound channel liquidity determined? Set your buy price to according to the time you are willing to wait for a match and of course your own internal cost and benefit analysis. @@ -32,13 +28,17 @@ It will not show you an exact total, but you can see how much you will pay in fe ### How will I know if my order was fulfilled? -Watch the logs. Pull the order snapshot locally. Watch your account balance. Pool orders list. +You can check the status of your order at any time by running the following command: + +```text +pool orders list +``` ### How soon after my order is filled will the seller open a channel to me? -A channel will be opened as soon as the batch transaction has received N confirmations. Batches are processed whenever the market clears or approximately every 10 minutes or whichever is longer. +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. -If the sellerโ€™s node is offline when the batch clears, \_\_\_\_ +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? @@ -46,9 +46,9 @@ Not at this time but this is something we plan to add in the future. ## Channels -### How does the channel get opened? +### How is the channel opened? -The channel is open automatically by the seller once the market clears. +The channel is opened automatically by the seller once the market clears. ### How long will the channel stay open? @@ -60,7 +60,7 @@ No, it will remain open but the seller has no obligation to keep the channel ope ### Is there a way to ensure that the channels are of a certain size? -You can specify a minimum allowable channel size which will ensure a channel greater than or equal to what you require. +You can specify a minimum allowable channel size which will ensure that you receive one or more inbound channels greater than or equal to the size you specified. ### Are there limits on what I can do with the channel? @@ -72,7 +72,7 @@ If the lender force closes they will be banned from the market. This will not be ### If off-chain funds have moved over to my side, must I keep them there? -If you cannot or don't want to move the funds out of the channel off-chain, you can close the channel before the term limit with no penalties. +If you cannot or do not want to move the funds out of the channel off-chain, you can close the channel before the term limit with no penalties. ## Accounts @@ -80,7 +80,7 @@ If you cannot or don't want to move the funds out of the channel off-chain, you Opening an account requires first funding your `lnd` wallet and subsequently funding a time-locked 2-of-2 multi-sig account. This account is then debited whenever an order of is fully or partially matched. -When creating the account you specify a time-lock so that you can gain access to your funds in the event that Pool is offline for a period of time. The account will expire once the specified amount of time has elapsed. +When creating an account you must specify a time-lock so that you can gain access to your funds in the event that Pool is offline for a period of time. The account will expire once the specified amount of time has elapsed. ### Why do accounts expire? diff --git a/docs/install.md b/docs/install.md index 4d026fa..61bc87c 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,35 +1,26 @@ # Installation -Lightning Pool is built very similarly to -[Lightning Loop](https://github.com/lightninglabs/loop): There is a process that -is constantly running in the background, called the trader daemon (`poold`) and -a command line tool to interact with the daemon, called just `pool`. +## Installation -The `poold` trader daemon can be run either as a standalone binary connected to -a compatible `lnd` node or integrated into -[Lightning Terminal (LiT)](https://github.com/lightninglabs/lightning-terminal). +Lightning Pool is built very similarly to [Lightning Loop](https://github.com/lightninglabs/loop): There is a process that is constantly running in the background, called the trader daemon \(`poold`\) and a command line tool to interact with the daemon, called just `pool`. -## Downloading the standalone binaries +The `poold` trader daemon can be run either as a standalone binary connected to a compatible `lnd` node or integrated into [Lightning Terminal \(LiT\)](https://github.com/lightninglabs/lightning-terminal). -The latest official release binaries can be [downloaded from the GitHub -releases page](https://github.com/lightninglabs/pool/releases). +### Downloading the standalone binaries -## Downloading as part of Lightning Terminal (LiT) +The latest official release binaries can be [downloaded from the GitHub releases page](https://github.com/lightninglabs/pool/releases). -To run `poold` integrated into the Lightning Terminal, download [the latest -release of LiT](https://github.com/lightninglabs/lightning-terminal/releases) -and follow -[the installation instructions of LiT](https://github.com/lightninglabs/lightning-terminal#execution) +### Downloading as part of Lightning Terminal \(LiT\) -## Building the binaries from source +To run `poold` integrated into the Lightning Terminal, download [the latest release of LiT](https://github.com/lightninglabs/lightning-terminal/releases) and follow [the installation instructions of LiT](https://github.com/lightninglabs/lightning-terminal#execution) -To build both the `poold` and `pool` binaries from the source code, at least the -`go 1.14` and `make` must be installed. +### Building the binaries from source -To download the code, compile and install it, the following commands can then -be run: +To build both the `poold` and `pool` binaries from the source code, at least the `go 1.14` and `make` must be installed. -```shell +To download the code, compile and install it, the following commands can then be run: + +```text $ git clone https://github.com/lightninglabs/pool $ cd pool $ make install @@ -37,27 +28,21 @@ $ make install This will install the binaries into your `$GOPATH/bin` directory. -## Installing `lnd` +### Installing `lnd` -Lightning Pool needs to be connected to an `lnd` node version `v0.11.1-beta` or -later to work. It is recommended to run an -[official release binary of `lnd`](https://github.com/lightningnetwork/lnd/releases). +Lightning Pool needs to be connected to an `lnd` node version `v0.11.1-beta` or later to work. It is recommended to run an [official release binary of `lnd`](https://github.com/lightningnetwork/lnd/releases). -[Installing `lnd` from source](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md#installing-lnd) -is also possible but needs to be done **with all sub-server build flags -enabled**: +[Installing `lnd` from source](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md#installing-lnd) is also possible but needs to be done **with all sub-server build flags enabled**: -```shell +```text $ make install tags="signrpc walletrpc chainrpc invoicesrpc" ``` -## Running `poold` +### Running `poold` -If `lnd` is configured with the default values and is running on the same -machine, `poold` will be able to connect to it automatically and can be started -by simply running: +If `lnd` is configured with the default values and is running on the same machine, `poold` will be able to connect to it automatically and can be started by simply running: -```shell +```text $ poold # Or if you want to do everything in the same terminal and run poold in the @@ -69,57 +54,45 @@ $ poold & $ poold --network=testnet ``` -In the case that `lnd` is running on a remote node, the `tls.cert` and all -`*.macaroon` files from the `lnd` data directory need to be copied to the -machine where `poold` is running. +In the case that `lnd` is running on a remote node, the `tls.cert` and all `*.macaroon` files from the `lnd` data directory need to be copied to the machine where `poold` is running. -The daemon can then be configured to connect to the remote `lnd` node by using -the following command line flags: +The daemon can then be configured to connect to the remote `lnd` node by using the following command line flags: -```shell +```text $ poold --lnd.host=:10009 \ --lnd.macaroondir=/some/directory/with/lnd/data/macaroons \ --lnd.tlspath=/some/directory/with/lnd/data/tls.cert ``` -To persist this configuration, these values can also be written to a -configuration file, located in `~/.pool//pool.conf`, for example: +To persist this configuration, these values can also be written to a configuration file, located in `~/.pool//pool.conf`, for example: > ~/.pool/mainnet/pool.conf -```text -lnd.host=:10009 -lnd.macaroondir=/some/directory/with/lnd/data/macaroons -lnd.tlspath=/some/directory/with/lnd/data/tls.cert -``` +> +> ```text +> lnd.host=:10009 +> lnd.macaroondir=/some/directory/with/lnd/data/macaroons +> lnd.tlspath=/some/directory/with/lnd/data/tls.cert +> ``` -## Configuration options +### Configuration options -There is a range of operational settings that can be set to change the default -logging behavior or change the directories where `poold` stores its data. To -see the full list of options, run `poold --help`. +There is a range of operational settings that can be set to change the default logging behavior or change the directories where `poold` stores its data. To see the full list of options, run `poold --help`. -The following list only includes flags that have an impact on the match making -or business related behavior of the Pool trader daemon: +The following list only includes flags that have an impact on the match making or business related behavior of the Pool trader daemon: -| Flag | Required | Default Value | Description | -|-------------|----------|---------------|-------------------------------------| +| Flag | Required | Default Value | Description | +| :--- | :--- | :--- | :--- | | `newnodesonly` | No | `false` | If set to `true` the daemon will only buy channels from nodes it does not yet have channels with | -# Authentication and transport security +## Authentication and transport security -The gRPC and REST connections of `poold` are encrypted with TLS and secured with -macaroon authentication the same way `lnd` is. +The gRPC and REST connections of `poold` are encrypted with TLS and secured with macaroon authentication the same way `lnd` is. -If no custom base directory is set then the TLS certificate is stored in -`~/.pool//tls.cert` and the base macaroon in -`~/.pool//pool.macaroon`. +If no custom base directory is set then the TLS certificate is stored in `~/.pool//tls.cert` and the base macaroon in `~/.pool//pool.macaroon`. -The `pool` command will pick up these file automatically on mainnet if no custom -base directory is used. For other networks it should be sufficient to add the -`--network` flag to tell the CLI in what sub directory to look for the files. +The `pool` command will pick up these file automatically on mainnet if no custom base directory is used. For other networks it should be sufficient to add the `--network` flag to tell the CLI in what sub directory to look for the files. -For more information on macaroons, -[see the macaroon documentation of lnd.](https://github.com/lightningnetwork/lnd/blob/master/docs/macaroons.md) +For more information on macaroons, [see the macaroon documentation of lnd.](https://github.com/lightningnetwork/lnd/blob/master/docs/macaroons.md) + +**NOTE**: pool's macaroons are independent from `lnd`'s. The same macaroon cannot be used for both `poold` and `lnd`. -**NOTE**: pool's macaroons are independent from `lnd`'s. The same macaroon -cannot be used for both `poold` and `lnd`. diff --git a/docs/orders.md b/docs/orders.md index 839aad4..ca94c25 100644 --- a/docs/orders.md +++ b/docs/orders.md @@ -4,27 +4,15 @@ Now that we have our account set up and funded, it's time to trade some channels! -There are two types of orders in the current version of Pool: asks, and bids. You -submit an ask when you have some coins that you want to _lease out_ as inbound -liquidity for a certain period of time \(expressed in blocks\), at a fixed rate -compounded per block. You submit a bid when you need to acquire inbound liquidity -\(ability to receive\), for a given amount of time \(again expressed in blocks\), -paying out a fixed rate that compounds per-block. +There are two types of orders in the current version of Pool: asks, and bids. You submit an ask when you have some coins that you want to _lease out_ as inbound liquidity for a certain period of time \(expressed in blocks\), at a fixed rate compounded per block. You submit a bid when you need to acquire inbound liquidity \(ability to receive\), for a given amount of time \(again expressed in blocks\), paying out a fixed rate that compounds per-block. -In the alpha version of Lightning Pool, a single lump sum premium is paid after -order execution. In future versions, we plan on introducing "coupon channels" -which allow for _streaming interest_ to be paid out. +In the alpha version of Lightning Pool, a single lump sum premium is paid after order execution. In future versions, we plan on introducing "coupon channels" which allow for _streaming interest_ to be paid out. -One important aspect of the market is that rather than buy/sell satoshis, we use -_units_. A unit is simply 100,000 satoshis and represents the _smallest_ channel -that can be bought or sold on the auction platform. +One important aspect of the market is that rather than buy/sell satoshis, we use _units_. A unit is simply 100,000 satoshis and represents the _smallest_ channel that can be bought or sold on the auction platform. -With that said, let's place some orders to try to earn some yield from this 0.5 -BTC that's been burning a hole in our SD card for the past year. We'll place a -single order for 10 million satoshis, wanting to receive 0.3% \(30 bps\) over a -2016 block period \(approximately 2 weeks\): +With that said, let's place some orders to try to earn some yield from this 0.5 BTC that's been burning a hole in our SD card for the past year. We'll place a single order for 10 million satoshis, wanting to receive 0.3% \(30 bps\) over a 2016 block period \(approximately 2 weeks\): -```shell +```text $ pool orders submit ask 10000000 0288096be9917f8ebdfc6eb2701635fe658f4eae1e0274dcce41418b3fb5145732 --interest_rate_percent=0.3 --lease_duration_blocks=2016 -- Order Details -- @@ -42,8 +30,7 @@ Confirm order (yes/no): yes } ``` -By leaving off the `--force` flag, we request the final break down to confirm -the details of our order before we put it through. +By leaving off the `--force` flag, we request the final break down to confirm the details of our order before we put it through. In this case, if this order is executed, then I'll gain 29k satoshis: @@ -52,35 +39,19 @@ premium = (rate_fixed / billion) * amount * blocks 29,998 = (1,488/1,000,000,000)*10,000,000*2,016 ``` -It's important to note that although internally we use a fixed rate per block to -compute the final premium, on the command line, we accept the final acceptable -premium as a _percentage_. Therefore, when submitting orders, one should place -the value that they wish to receive or accept at the end of the lease period. -Internally, we'll then compute the _per block lease rate_ and submit the order -using _that_. +It's important to note that although internally we use a fixed rate per block to compute the final premium, on the command line, we accept the final acceptable premium as a _percentage_. Therefore, when submitting orders, one should place the value that they wish to receive or accept at the end of the lease period. Internally, we'll then compute the _per block lease rate_ and submit the order using _that_. -The duration and fixed rate \(the percentage\) are two important values to pay -attention to when placing orders. Given the same amount, and fixed rate, you -earn more by leasing out the funds for a _longer_ period of time. Conversely, a -taker will pay more if they need the funds for a longer period of time. +The duration and fixed rate \(the percentage\) are two important values to pay attention to when placing orders. Given the same amount, and fixed rate, you earn more by leasing out the funds for a _longer_ period of time. Conversely, a taker will pay more if they need the funds for a longer period of time. -Also notice the **_max batch fee rate_** break down, that regulates the _highest_ -chain fee you're willing to pay to get into a batch. When traders are included -in a batch, they split the channel open fee with the party they're matched with, -then pay for their account to be spent and re-created. The auctioneer then uses -this value during match making to ensure that traders don't pay more _chain fees_ -than they intend to. If your desired chain fee is _below_ the current proposed -batch chain fee, then your order won't be eligible for execution until chain -fees come down somewhat. +Also notice the _**max batch fee rate**_ break down, that regulates the _highest_ chain fee you're willing to pay to get into a batch. When traders are included in a batch, they split the channel open fee with the party they're matched with, then pay for their account to be spent and re-created. The auctioneer then uses this value during match making to ensure that traders don't pay more _chain fees_ than they intend to. If your desired chain fee is _below_ the current proposed batch chain fee, then your order won't be eligible for execution until chain fees come down somewhat. Users can use the `--max_batch_fee_rate` value to regulate chain fees. -Take note of the `order_nonce`, it's used through the auction to identify orders, -and also for authentication purposes. +Take note of the `order_nonce`, it's used through the auction to identify orders, and also for authentication purposes. We can then check out the order we just placed with the following command: -```shell +```text $ pool orders list { @@ -106,29 +77,24 @@ $ pool orders list } ``` -The order hasn't been cleared yet \(state `ORDER_SUBMITTED`\), and it shows up -as 100 units, or 10 million satoshis. +The order hasn't been cleared yet \(state `ORDER_SUBMITTED`\), and it shows up as 100 units, or 10 million satoshis. -If we instead wanted to _buy_ inbound bandwidth, we could submit a bid instead. -A trader can have multiple unfilled bids and asks. Partial matching is possible -as well, so someone could only purchase 10 of the 100 units we have for sale. -Over time the orders will gain additional constraints such as fill-or-kill, or -min partial match size. +If we instead wanted to _buy_ inbound bandwidth, we could submit a bid instead. A trader can have multiple unfilled bids and asks. Partial matching is possible as well, so someone could only purchase 10 of the 100 units we have for sale. Over time the orders will gain additional constraints such as fill-or-kill, or min partial match size. ## Detailed field breakdown -Let's now take a look at all the order specific command line flags that are -available. +Let's now take a look at all the order specific command line flags that are available. ### Ask orders Command for submitting an ask order: -```shell +```text $ pool orders submit ask ``` Help output: + ```text $ pool orders submit ask --help @@ -139,7 +105,7 @@ USAGE: pool orders submit ask [command options] amt acct_key [--rate_fixed=R] [--max_batch_fee_rate=F] [--lease_duration_blocks=M] DESCRIPTION: - + Create an offer to provide inbound liquidity to an auction participant by opening a channel to them for a certain time. @@ -153,30 +119,28 @@ OPTIONS: --max_batch_fee_rate value the maximum fee rate (sat/vByte) to use to for the batch transaction (default: 100) ``` -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. +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. -| Flag | Required | Default Value | Description | -|-------------------------|----------|---------------|-------------------------------------| -| `interest_rate_percent` | Yes | n/a | The interest rate that should be earned over **the total lease duration**. | -| `amt` | Yes | n/a | The amount of liquidity to offer in satoshis. Must be a multiple of the base unit (100k sat). | -| `acct_key` | Yes | n/a | The account's trader key to use to pay for the offered liquidity, the order submission fee and chain fees. | -| `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](#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](#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](#chain-fees) for more information. | -| `force` | No | `false` | When set to `true`, no order details will be shown and no confirmation is required. | +| Flag | Required | Default Value | Description | +| :--- | :--- | :--- | :--- | +| `interest_rate_percent` | Yes | n/a | The interest rate that should be earned over **the total lease duration**. | +| `amt` | Yes | n/a | The amount of liquidity to offer in satoshis. Must be a multiple of the base unit \(100k sat\). | +| `acct_key` | Yes | n/a | The account's trader key to use to pay for the offered liquidity, the order submission fee and chain fees. | +| `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. | +| `force` | No | `false` | When set to `true`, no order details will be shown and no confirmation is required. | ### Bid orders Command for submitting a bid order: -```shell +```text $ pool orders submit bid ``` Help output: + ```text NAME: pool orders submit bid - obtain channel liquidity @@ -185,7 +149,7 @@ USAGE: pool orders submit bid [command options] amt acct_key [--rate_fixed=R] [--max_batch_fee_rate=F] [--lease_duration_blocks=M] DESCRIPTION: - + Place an offer for acquiring inbound liquidity by lending funding capacity from another participant in the order book. @@ -200,43 +164,28 @@ OPTIONS: --max_batch_fee_rate value the maximum fee rate (sat/vByte) to use to for the batch transaction (default: 100) ``` -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. +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. -| Flag | Required | Default Value | Description | -|-------------------------|----------|---------------|-------------------------------------| -| `interest_rate_percent` | Yes | n/a | The maximum interest rate that should be paid for leasing a channel, calculated over **the total lease duration**. | -| `amt` | Yes | n/a | The amount of liquidity to lease in satoshis. Must be a multiple of the base unit (100k sat). | -| `acct_key` | Yes | n/a | The account's trader key to use to pay for the lease premium, order submission fee and chain fees. | -| `lease_duration_blocks` | No | `2016` | The minimum number of blocks the leased channels must stay open for in order to satisfy the contract. Distinct markets are available for the different durations. See [lease duration section](#lease-duration) for more information. | -| `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](#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](#chain-fees) for more information. | -| `force` | No | `false` | When set to `true`, no order details will be shown and no confirmation is required. | +| Flag | Required | Default Value | Description | +| :--- | :--- | :--- | :--- | +| `interest_rate_percent` | Yes | n/a | The maximum interest rate that should be paid for leasing a channel, calculated over **the total lease duration**. | +| `amt` | Yes | n/a | The amount of liquidity to lease in satoshis. Must be a multiple of the base unit \(100k sat\). | +| `acct_key` | Yes | n/a | The account's trader key to use to pay for the lease premium, order submission fee and chain fees. | +| `lease_duration_blocks` | No | `2016` | The minimum number of blocks the leased channels must 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 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. | +| `force` | No | `false` | When set to `true`, no order details will be shown and no confirmation is required. | ## Lease duration -The lease duration dictates the duration of the contract that the maker -(submitter of the ask order) and the taker (submitter of the bid order) enter -when being matched by the auctioneer. That means that the maker must provide the -offered liquidity **at least** for the selected number of blocks. The maker is -not allowed to close the channel before the agreed upon lease duration has -elapsed. The maker **may** close the channel after the duration is over but is -not obligated to do so. If a channel is economically viable, further routing -fees might be collected when keeping the channel open. +The lease duration dictates the duration of the contract that the maker \(submitter of the ask order\) and the taker \(submitter of the bid order\) enter when being matched by the auctioneer. That means that the maker must provide the offered liquidity **at least** for the selected number of blocks. The maker is not allowed to close the channel before the agreed upon lease duration has elapsed. The maker **may** close the channel after the duration is over but is not obligated to do so. If a channel is economically viable, further routing fees might be collected when keeping the channel open. -In contrast, the taker of the channel is always allowed to close the channel. -They pay the premium for the whole duration upfront, and it is therefore to -their own disadvantage to close the channel prematurely. +In contrast, the taker of the channel is always allowed to close the channel. They pay the premium for the whole duration upfront, and it is therefore to their own disadvantage to close the channel prematurely. -To allow the formation of distinct premium rates over different durations, the -possible lease durations are fixed and defined by the auctioneer. The current -list of possible lease durations can be queried by running the following -command: +To allow the formation of distinct premium rates over different durations, the possible lease durations are fixed and defined by the auctioneer. The current list of possible lease durations can be queried by running the following command: -```shell +```text $ pool auction leasedurations { @@ -247,26 +196,17 @@ $ pool auction leasedurations } ``` -The integer value is the lease duration in blocks. The boolean value indicates -whether matchmaking in the given duration market is currently enabled or not. -When adding a new lease duration the auctioneer might not enable matchmaking -right away to wait for the order book to be populated sufficiently first. +The integer value is the lease duration in blocks. The boolean value indicates whether matchmaking in the given duration market is currently enabled or not. When adding a new lease duration the auctioneer might not enable matchmaking right away to wait for the order book to be populated sufficiently first. ## Order execution fees -To compensate the auctioneer server for the service it is providing, an order -execution fee has to be paid for every successfully executed (partial) match. +To compensate the auctioneer server for the service it is providing, an order execution fee has to be paid for every successfully executed \(partial\) match. -That execution fee is split into a static part (the _base fee_ in satoshis) that -is always the same independent of the matched size, and the dynamic part (the -_fee rate_ in parts per million) that is calculated based on the number of -matched units. +That execution fee is split into a static part \(the _base fee_ in satoshis\) that is always the same independent of the matched size, and the dynamic part \(the _fee rate_ in parts per million\) that is calculated based on the number of matched units. -The fee is set by the server and can change depending on demand, chain fee -climate or other operational costs. The current fee can be queried by running -the following command: +The fee is set by the server and can change depending on demand, chain fee climate or other operational costs. The current fee can be queried by running the following command: -```shell +```text $ pool auction fee { @@ -277,8 +217,7 @@ $ pool auction fee } ``` -Based on these **example** values, a matched order of 7 units (700k satoshis) -would be charged an execution fee of 986 satoshis: +Based on these **example** values, a matched order of 7 units \(700k satoshis\) would be charged an execution fee of 986 satoshis: ```text execution_fee = base_fee + (fee_rate / million) * match_amount @@ -287,41 +226,24 @@ execution_fee = base_fee + (fee_rate / million) * match_amount ## Chain fees -Each successfully executed order will result in at least one channel output -being created in the batch transaction that is published to the Bitcoin network. -Additionally, because an account must be spent for an order to be executed, an -input per involved account is also added to the transaction, and, if there is a -remaining balance, the change goes back to a newly created output for that -account. +Each successfully executed order will result in at least one channel output being created in the batch transaction that is published to the Bitcoin network. Additionally, because an account must be spent for an order to be executed, an input per involved account is also added to the transaction, and, if there is a remaining balance, the change goes back to a newly created output for that account. -In an example worst-case-scenario, a bid order for buying one channel can result -in one input and two outputs being created on-chain. Each trader is charged -fully for the transaction weight they produce with their account inputs and -outputs. The cost for the new channel output is split in half between the maker -and the taker. +In an example worst-case-scenario, a bid order for buying one channel can result in one input and two outputs being created on-chain. Each trader is charged fully for the transaction weight they produce with their account inputs and outputs. The cost for the new channel output is split in half between the maker and the taker. -Assuming we have a bid order over 5 units (500k satoshis) and an account that is -10 times that size, we'd occupy 162 virtual bytes of chain space: +Assuming we have a bid order over 5 units \(500k satoshis\) and an account that is 10 times that size, we'd occupy 162 virtual bytes of chain space: ```text size_vBytes = acct_input_size + 0.5 * chan_output_size + acct_output_size 162 ~= ~98 + 0.5 * 43 + 43 ``` -Assuming the auctioneer estimates a current network fee rate of 34 sat/vByte, -that order would cost `162 * 34 = 5,508` satoshi in chain fees to execute. +Assuming the auctioneer estimates a current network fee rate of 34 sat/vByte, that order would cost `162 * 34 = 5,508` satoshi in chain fees to execute. -The auctioneer always tries to be economical with its fee estimation, but fee -estimation is hard, and the fee market remains unpredictable. To give traders -some protection against excessive fees, the `--max_batch_fee_rate` can be set -for any order submitted that communicates to the auctioneer that the order -shouldn't be considered for matching if the current estimation is higher than -that rate. +The auctioneer always tries to be economical with its fee estimation, but fee estimation is hard, and the fee market remains unpredictable. To give traders some protection against excessive fees, the `--max_batch_fee_rate` can be set for any order submitted that communicates to the auctioneer that the order shouldn't be considered for matching if the current estimation is higher than that rate. ### Max chain fee estimation -When submitting an order, the command line shows a summary of the expected fees, -as shown in our initial example: +When submitting an order, the command line shows a summary of the expected fees, as shown in our initial example: ```text Execution Fee: 0.00010001 BTC @@ -329,53 +251,57 @@ Max batch fee rate: 100 sat/vByte Max chain fee: 0.0016325 BTC ``` -The value shown as `Max chain fee` can look pretty scary. But it is important -to note that the value is considered to be the **absolute worst-case fee**. +The value shown as `Max chain fee` can look pretty scary. But it is important to note that the value is considered to be the **absolute worst-case fee**. -The maximum chain fee is calculated based on how many potential partial matches -an order could go through (assuming it would always only match the minimum match -size or minimum channel size). And for each of those partial matches the chain -fee calculation as shown in the previous section would be performed with the -given `Max batch fee rate`. It is quite unlikely however that the maximum fee is -ever required to be paid for an order to be executed. +The maximum chain fee is calculated based on how many potential partial matches an order could go through \(assuming it would always only match the minimum match size or minimum channel size\). And for each of those partial matches the chain fee calculation as shown in the previous section would be performed with the given `Max batch fee rate`. It is quite unlikely however that the maximum fee is ever required to be paid for an order to be executed. -To reduce the value of this worst-case estimation, there are two possible flags -that can be used to influence it: - * `--min_chan_amt`: The minimum match size or minimum channel size. Instructs - the auctioneer to only match the order with a counterpart that can at least - fill the given amount in one match. By default, this values is set to 10% of - the full order amount. Increasing the value makes it less likely to find a - match candidate but reduces the number of times chain fees have to be paid. - Increasing the value to 100% of the order amount is equivalent to a - "kill-or-fill" order that is either executed in one part or not at all. - * `--max_batch_fee_rate`: The maximum network fee rate the order should be - considered for. Orders with a value higher than what the auctioneer estimates - at the time of matchmaking will be excluded for that batch. Setting this - value too low might result in orders not being executed at all or only when - the mempools are almost empty. +To reduce the value of this worst-case estimation, there are two possible flags that can be used to influence it: + +* `--min_chan_amt`: The minimum match size or minimum channel size. Instructs + + the auctioneer to only match the order with a counterpart that can at least + + fill the given amount in one match. By default, this values is set to 10% of + + the full order amount. Increasing the value makes it less likely to find a + + match candidate but reduces the number of times chain fees have to be paid. + + Increasing the value to 100% of the order amount is equivalent to a + + "kill-or-fill" order that is either executed in one part or not at all. + +* `--max_batch_fee_rate`: The maximum network fee rate the order should be + + considered for. Orders with a value higher than what the auctioneer estimates + + at the time of matchmaking will be excluded for that batch. Setting this + + value too low might result in orders not being executed at all or only when + + the mempools are almost empty. ## Extensibility -At the moment there are only two restrictions that users can set on _who_ their -orders will be matched against. There is the global `--newnodesonly` flag which -will cause the trader daemon to reject any matches with nodes that its connected -`lnd` node already has channels with. +At the moment there are only two restrictions that users can set on _who_ their orders will be matched against. There is the global `--newnodesonly` flag which will cause the trader daemon to reject any matches with nodes that its connected `lnd` node already has channels with. -Takers can additionally influence the "quality" of the nodes they want their bid -orders to be matched against by setting the `--min_node_tier` when creating the -order. +Takers can additionally influence the "quality" of the nodes they want their bid orders to be matched against by setting the `--min_node_tier` when creating the order. -In the future, more matching restrictions will likely be implemented, for -example: - * Specifying a concrete list of `lnd` node public keys that an order should - be matched with. - * Instant order: Either be matched successfully in the next batch or be - canceled. - * Buying channels for someone else (a.k.a. "Sidecar Channels"): When creating - a bid order, a third party's `lnd` node pubkey can be specified that will - receive the leased channel instead of the node of the bidder. +In the future, more matching restrictions will likely be implemented, for example: + +* Specifying a concrete list of `lnd` node public keys that an order should + + be matched with. + +* Instant order: Either be matched successfully in the next batch or be + + canceled. + +* Buying channels for someone else \(a.k.a. "Sidecar Channels"\): When creating + + a bid order, a third party's `lnd` node pubkey can be specified that will + + receive the leased channel instead of the node of the bidder. + +To allow these future upgrades to work seamlessly, a version field was added to the order submission protocol from the beginning. With this version field, the trader and auctioneer always know what fields an order is supposed to have set and therefore what fields are covered by the trader's order signature. -To allow these future upgrades to work seamlessly, a version field was added to -the order submission protocol from the beginning. With this version field, the -trader and auctioneer always know what fields an order is supposed to have set -and therefore what fields are covered by the trader's order signature. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..dc9a56a --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,92 @@ +# Quickstart + +## Download `poold` + +### Download the standalone binaries + +The latest official release binaries can be [downloaded from the GitHub releases page](https://github.com/lightninglabs/pool/releases). + +### Download Lightning Terminal \(LiT\) + +To run `poold` integrated into the Lightning Terminal, download [the latest release of LiT](https://github.com/lightninglabs/lightning-terminal/releases) and follow [the installation instructions of LiT](https://github.com/lightninglabs/lightning-terminal#execution) + +## Run `poold` + +If `lnd` is configured with the default values and is running on the same machine, `poold` will be able to connect to it automatically and can be started by simply running: + +```text +$ poold +``` + +If you're using Lightning Terminal then you can just run `litd` instead: + +```text +$ litd +``` + +## Create an account + +Creating an account has two parameters: the size of the account, and the expiry of an account. The funds for the account will be pulled from your `lnd` wallet. Create an account by running the following command: + +```text +$ pool accounts new --amt=50000000 --expiry_height=1773394 +``` + +Once at least 3 blocks have passed \(in the alpha\), the account will be confirmed and ready for use: + +Run the following command to view account details: + +```text +$ pool accounts list +``` + +## Submit an order + +There are two types of orders in the current version of Pool: asks, and bids. You submit an ask when you have some coins that you want to _lease out_ as inbound liquidity for a certain period of time \(expressed in blocks\), at a fixed rate compounded per block. You submit a bid when you need to acquire inbound liquidity \(ability to receive\), for a given amount of time \(again expressed in blocks\), paying out a fixed rate that compounds per-block. + +To submit a bid: + +```text +$ pool orders submit bid +``` + +Be sure to add the following flags: + +| Flag | Description | +| :--- | :--- | +| `interest_rate_percent` | The interest rate that should be earned over **the total lease duration**. | +| `amt` | The amount of liquidity to offer in satoshis. Must be a multiple of the base unit \(100k sat\). | +| `acct_key` | The account's trader key to use to pay for the offered liquidity, the order submission fee and chain fees. | + +We can then check out the order we just placed with the following command: + +```text +$ pool orders list +``` + +## Matched Orders + +Once an order has been matched in an auction, the `pool auction leases` command can be used to examine your current set of purchased/sold channel leases. An example output looks something like the following: + +```text +$ pool auction leases +{ + "leases": [ + { + "channel_point": "78cc6879c1dc1c00f22b29a06458f1335ed0fdb7d05c01b9077e3155e697bbb9:2", + "channel_amt_sat": 5000000, + "channel_duration_blocks": 144, + "premium_sat": 40000, + "execution_fee_sat": 5001, + "chain_fee_sat": 165, + "order_nonce": "eb972cd21cf1651e251c8b07d69e89c47294bae104fbdc9da26edf9aee335c9a", + "purchased": false + } + ], + "total_amt_earned_sat": 40000, + "total_amt_paid_sat": 5166 +} +``` + +Here we can see that a channel sold for 40k satoshis, and ended up paying 5k satoshis in chain and execution fees, netting a cool 35k satoshi yield. Within the actual auction, these numbers will vary based on the chain fee rate, the market prices, and also the execution fees. Users can constraint how much chain fees they'll pay by setting the `--max_batch_fee_rate` argument when submitting orders. +