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

GitBook: [master] 11 pages modified

Browse source
This commit is contained in:
Justin O'Brien 2020-10-14 10:52:41 +00:00 • committed by gitbook-bot
parent cf7020cdf7
commit 0d64ec67a4
No known key found for this signature in database
GPG key ID: 07D2180C7B12D0FF
11 changed files with 269 additions and 239 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/README.md Normal file
View file

@ -0,0 +1,2 @@
# Introduction

4
docs/SUMMARY.md
View file

@ -1,6 +1,7 @@
# Table of contents
* [Lightning Pool: A Non-Custodial Channel Lease Marketplace](README.md)
* [Introduction](README.md)
* [Lightning Pool: A Non-Custodial Channel Lease Marketplace](lightning-pool-a-non-custodial-channel-lease-marketplace.md)
* [Overview](overview.md)
* [Installation](install.md)
* [Accounts](accounts.md)
@ -9,3 +10,4 @@
* [Batch Execution](batch_execution.md)
* [Alpha Limitations](alpha_limitations.md)
* [FAQ](faq.md)

88
docs/accounts.md
View file

@ -1,40 +1,33 @@
Accounts
# 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.
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.
The script for an account is very simple, funds can be moved from the account:
* With a joint 2-of-2 signature by the _auctioneer_ and the user.
* Unilaterally by the user after the expiration period has passed.
* With a joint 2-of-2 signature by the _auctioneer_ and the user.
* Unilaterally by the user after the expiration period has passed.
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.
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:
* Fees paid to the auctioneer are deducted from your account
* Fees gained by selling channels are credited to your account
* Funds used to open channels to others are deducted from your account
* Fees paid to the auctioneer are deducted from your account
* 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.
## Creating An Account
Creating an account has two parameters: the size of the account, and the expiry
of an account. As you'll see below, both values can be adjusted at any time.
Creating an account has two parameters: the size of the account, and the expiry of an account. As you'll see below, both values can be adjusted at any time.
We can create an account using `pool`, like so:
```
```text
🏔 pool accounts new --amt=50000000 --expiry_height=1773394
{
"trader_key": "0288096be9917f8ebdfc6eb2701635fe658f4eae1e0274dcce41418b3fb5145732",
@ -46,17 +39,13 @@ We can create an account using `pool`, like so:
}
```
It's also possible to specify a _relative_ account expiry based on the current
best block with the `--expiry_blocks` argument. As an example, if I wanted my
account to expiry in 2 weeks, I would pass: `--expiry_blocks=2016`.
It's also possible to specify a _relative_ account expiry based on the current best block with the `--expiry_blocks` argument. As an example, if I wanted my account to expiry in 2 weeks, I would pass: `--expiry_blocks=2016`.
Here I created an account with 0.5 BTC, that'll expire at height `1773394`. The
response shows that it's now pending open (unconfirmed), my `trader_key` (used
to sign orders), and the outpoint of my new account.
Here I created an account with 0.5 BTC, that'll expire at height `1773394`. The response shows that it's now pending open \(unconfirmed\), my `trader_key` \(used to sign orders\), and the outpoint of my new account.
Once at least 3 blocks have passed (in the alpha), the account will be confirmed
and ready for use:
```
Once at least 3 blocks have passed \(in the alpha\), the account will be confirmed and ready for use:
```text
🏔 pool accounts list
{
"accounts": [
@ -74,17 +63,13 @@ and ready for use:
## Depositing To An Account
We can add more funds to an account using the `pool accounts deposit` command.
Under the hood, we can actually batch _other_ transactions with account
modifications (make other payments, etc), but for now we expose only the basic
functionality over the CLI.
We can add more funds to an account using the `pool accounts deposit` command. Under the hood, we can actually batch _other_ transactions with account modifications \(make other payments, etc\), but for now we expose only the basic functionality over the CLI.
**NOTE**: You should _never_ send coins directly to your account output as it
won't be picked up by the auctioneer.
**NOTE**: You should _never_ send coins directly to your account output as it won't be picked up by the auctioneer.
Let's say I want to deposit an extra 1 million satoshis into my account, I can
do so with the following command:
```
Let's say I want to deposit an extra 1 million satoshis into my account, I can do so with the following command:
```text
🏔 pool accounts deposit --trader_key=0288096be9917f8ebdfc6eb2701635fe658f4eae1e0274dcce41418b3fb5145732 --amt=1000000 --sat_per_vbyte=5
{
"account": {
@ -99,22 +84,15 @@ do so with the following command:
}
```
I specify my `trader_key` explicitly, as it's possible for `poold` to manage
_multiple_ accounts. The response shows my modified account, alongside with
the `txid` that'll be used to service the deposit. Once this transaction has
confirmed, I'll be able to use my account again.
I specify my `trader_key` explicitly, as it's possible for `poold` to manage _multiple_ accounts. The response shows my modified account, alongside with the `txid` that'll be used to service the deposit. Once this transaction has confirmed, I'll be able to use my account again.
Note that these funds came from the backing `lnd` node that `poold` is connected
to. At a future time we also plan to support a traditional _deposit_ address as
well.
Note that these funds came from the backing `lnd` node that `poold` is connected to. At a future time we also plan to support a traditional _deposit_ address as well.
## Withdrawing From An Account
Incrementally _withdrawing_ from an account is also supported. The command is
similar to the deposit command. If I wanted to extract that 1 million from that
account (let's say it's my profit for the past week) and send elsewhere, I can
do so with the following command:
```
Incrementally _withdrawing_ from an account is also supported. The command is similar to the deposit command. If I wanted to extract that 1 million from that account \(let's say it's my profit for the past week\) and send elsewhere, I can do so with the following command:
```text
🏔 pool accounts withdraw --trader_key=0288096be9917f8ebdfc6eb2701635fe658f4eae1e0274dcce41418b3fb5145732 --amt=1000000 --sat_per_vbyte=5 --addr=tb1qe3ueyx8jhlj4h0s6mgywmtl8vlwxqkgkgp3m3s
{
"account": {
@ -131,9 +109,9 @@ do so with the following command:
## Closing An Account
Finally, if you wish to send _all_ your funds elsewhere, it's possible to close
your account out before the main expiration period. We can close out the
account we created above with the following command:
```
Finally, if you wish to send _all_ your funds elsewhere, it's possible to close your account out before the main expiration period. We can close out the account we created above with the following command:
```text
🏔 pool accounts close --trader_key=0288096be9917f8ebdfc6eb2701635fe658f4eae1e0274dcce41418b3fb5145732
```

2
docs/alpha_limitations.md
View file

@ -0,0 +1,2 @@
# Alpha Limitations

60
docs/batch_execution.md
View file

@ -1,46 +1,25 @@
# Auction Batch Execution Lifecycle
# Batch Execution
## Batched Uniform-Price Clearing
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.
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
at least 10 days (1440 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 at least 10 days \(1440 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.
* 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
{
"version": 0,
@ -76,18 +55,13 @@ c0eb2966b3900343b6ac0347304402207b0344aa98878e5aa40dc0fb712beff9b11d7fba3671f847
a7e3be1ad2103bc6202b694e62a4d890cbb83f3a4dddb964fc500b25f55a38501642a770e3f37ac7364038a341bb16800000000"
```
Here we see a batch where a single order was matched, at a clearing rate of
`976`, with a single channel being purchased with a lifetime of `1024` blocks,
or roughly one week.
Here we see a batch where a single order was matched, at a clearing rate of `976`, with a single channel being purchased with a lifetime of `1024` blocks, or roughly one week.
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` is equivalent.
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` is equivalent.
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
```

46
docs/channel_leases.md
View file

@ -1,11 +1,12 @@
# Channel Leases
## Overview
## Channel Leases
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:
```
### 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:
```text
🏔 pool auction leases
{
"leases": [
@ -25,34 +26,25 @@ example output looks something like the following:
}
```
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.
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.
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`\). 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.
# Prerequisites
## Prerequisites
To build and run LLM, the following tools/binaries must be installed on your system:
To build and run LLM, the following tools/binaries must be installed on your
system:
* Go `1.13` or later
* `make`
* `lnd` version `v0.11.1-beta` or later with the build tags `signrpc`,
`walletrpc`, `chainrpc` and `invoicesrpc` enabled (or the current `master`
`walletrpc`, `chainrpc` and `invoicesrpc` enabled \(or the current `master`
branch built with `make install tags="signrpc walletrpc chainrpc invoicesrpc"`
if version`v0.11.1-beta` is not yet released).
if version`v0.11.1-beta` is not yet released\).

160
docs/faq.md
View file

@ -0,0 +1,160 @@
---
description: >-
Pool is a non-custodial marketplace for Lightning channels. Lightning Pool
enables new participants to rent Lightning channels so they can instantly
start accepting payments on the Lightning Network.
---
# FAQ
## How do lease payments for channels work?
You pay for the full liquidity up front, like renting an apartment but you put all the money down up front.
## How do I pay my leasing bills?
You first pay into a time-locked multi-sig and that wallet is used to pay for leasing costs.
You specify a time-lock, however if your time lock is too short then the funds can no longer be used to pay for leasing costs after they expire.
Even if you specify a long timelock, you can still get your funds out provided the server is still cooperative.
If your funds do expire, they will remain in the special wallet but they can no longer be used to pay for leases until you re-encumber them with a future lock. You can also simply withdraw these expired funds.
## Can I deposit more funds into my leasing account?
Depositing additional funds can be done but it will require spending the existing funds to combine the new deposit with the old deposit into a single UTXO.
Another option is to create a new account, which will not require a spend, but generally as a buyer, there is no particular reason to create multiple accounts.
You can choose the chain fee rate for these operations.
## How will I know if my order was fulfilled?
Watch the logs. Pull the order snapshot locally. Watch your account balance. 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.
If the seller’s node is offline when the batch clears, \_\_\_\_
## Do I get to choose my peer?
No, you cannot choose who you peer with. You will peer with any partner who is allowed in the market and meets your asking price.
## Who earns the routing fees from the channel that is opened with me?
The seller earns the routing fees. You can also earn fees if that new channel is used by a routing node.
## Can I specify the maximum fee rate of a peer I’m buying liquidity from?
Not at this time but this is something we hope to add in the future.
## Can the lender increase their fee rate after opening a channel with me?
Yes they can adjust their routing policy. This will be penalized in the future.
## If I am buying inbound liquidity can I specify who the seller should open a channel to?
Not at this time but this is something we hope to add in the future.
## What motivates sellers to provide good service after purchase?
They are still able to earn routing fees on top of the channel selling fee.
## What is my recourse if the peer goes offline or has other issues?
In the future this node may be removed from the market by market participant selection, but otherwise there is no specific recourse.
## What happens if the lender 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 future versions.
## What is the minimum purchase time for a channel?
You can buy a channel for one day or longer.
## Will purchased channels close after their purchase time?
No, they will remain open and become like normal channels.
If you believe your peer will not close out on you after your chosen time, you can choose a shorter time and pay a lower amount for the channel.
Even after the term, the seller of the channel will still be restricted by the normal CSV limits of the channel. A force close by the seller even after a 1 day term expiration would still result in the seller waiting for 2 weeks.
## Do sellers get to choose their buyers or blacklist certain buyers?
A seller cannot avoid selling to a specific peer. All peers on the network are valid buyers.
## Do I get to choose the size of my channels?
No, there is no way to select the channel sizes, so you can have many small channels appear.
## What is the shortest time period I can buy a channel for?
1 day. The maximum is 6 months.
## Who pays for the on-chain fees, like if I want to close my channel?
You pay for the closing on-chain fees and future UTXO consolidation costs. For the opening transaction, you can control the on-chain fee you pay, although the weight is a fixed amount relating to the sum of an input and an output, split between buyer and seller, regardless of the actual weight used to fund the channel.
## If off-chain funds have moved over to my side, must I keep them there?
If you cannot or don't want to move those funds out of the channel off-chain, you can close the channel before the term limit with no penalties.
## How much do you pay for a purchased channel?
You pay based on a percentage across time and it is not quite straightforward to describe the cost, so allow the software to calculate the cost for you and you will be able to confirm it.
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”
## How do you choose a price?
If there is a market match, you will pay the lower of the two prices between the bid and the ask, but if there is no match, you will have to wait for the sell side to go lower.
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.
## Are there limits on what I can do with the channel?
As a buyer the channel always behaves like a regular channel and you can do anything you want with it.
## Will I be matched to Tor nodes as a clearnet buyer?
Yes, and they will be responsible for connecting to your node.
## Why do accounts expire?
This is necessary so that users can recover funds in the event we disappear.
## What do I do if my account expires?
Currently you will need to close your account and then re-open your account. In the future you will be able to renew your account as part of a batch will be the most cost efficient way of opening an account.
## What are the fees for using Pool?
To be determined
## How do I buy a channel?
```text
orders submit bid --amt 100000000 --acct_key 03b5ef9a2ab19502fbb1f72d597d772eff1db1c9f8713fbe0685009a882f7c01b6 --min_duration_blocks 144 --max_batch_fee_rate 253 --interest_rate_percent 0.0001
```
* Amt is the total capacity, split in as many ways as there are sell matches
* Key is the “trader key” from “accounts list”
* Blocks is minimum 144 which is one day
* Max batch fee rate is what you want to pay as part of the channel creation \(you will pay for half of the open fees as the buyer\)
## How do I see the channel I bought?
```text
accounts leases
```
* This includes the capacity: “channel\_amt\_sat”
* How much you paid to the seller: “premium\_sat”
* How much you paid to the service: “execution\_fee\_sat”

2
docs/install.md
View file

@ -0,0 +1,2 @@
# Installation

2
docs/lightning-pool-a-non-custodial-channel-lease-marketplace.md Normal file
View file

@ -0,0 +1,2 @@
# Lightning Pool: A Non-Custodial Channel Lease Marketplace

72
docs/orders.md
View file

@ -4,26 +4,15 @@
Now that we have our account set up and funded, it's time to trade some channels!
There're 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 maximum 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 minimum amount of time (again
expressed in blocks), paying out a fixed rate that compounds per-block.
There're 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 maximum 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 minimum 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 network.
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 network.
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 3000 block period (a bit under 3 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 3000 block period \(a bit under 3 weeks\):
```text
🏔 pool orders submit ask 10000000 0288096be9917f8ebdfc6eb2701635fe658f4eae1e0274dcce41418b3fb5145732 --interest_rate_percent=0.3 --max_duration_blocks=3000
-- Order Details --
Ask Amount: 0.1 BTC
@ -40,45 +29,28 @@ 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 30k satoshis:
```
```text
premium = (rate_fixed / billion) * amount * blocks
30,000 = (1,000/1,000,000,000)*1,000,000*3,000
```
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** 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\*_ 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. Note
that the values is expressed in `sat/kw` on the command line. To convert from
`sat/vbyte` to `sat/kw`, simply _divide_ by `250`.
Users can use the `--max_batch_fee_rate` value to regulate chain fees. Note that the values is expressed in `sat/kw` on the command line. To convert from `sat/vbyte` to `sat/kw`, simply _divide_ by `250`.
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:
```
We can then check out the order we just placed with the following command:
```text
🏔 pool orders list
{
"asks": [
@ -99,11 +71,7 @@ We can then check out the order we just placed with the following command:
}
```
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.

70
docs/overview.md
View file

@ -1,69 +1,17 @@
# Lightning Pool
# Overview
Lightning Pool is a non-custodial batched uniform clearing-price auction for
Lightning Channel Lease (LCL). A LCL packages up inbound (or outbound!) channel
liquidity (ability to send/receive funds) as a fixed incoming asset (earning
interest over time) with a maturity date expressed in blocks. The maturity date
of each of the channels is enforced by Bitcoin contracts, ensuring that the
funds of the maker (the party that sold the channel) can't be swept until the
maturity height. All cleared orders (purchased channels) are cleared in a
single batched on-chain transaction.
Lightning Pool is a non-custodial batched uniform clearing-price auction for Lightning Channel Lease \(LCL\). A LCL packages up inbound \(or outbound!\) channel liquidity \(ability to send/receive funds\) as a fixed incoming asset \(earning interest over time\) with a maturity date expressed in blocks. The maturity date of each of the channels is enforced by Bitcoin contracts, ensuring that the funds of the maker \(the party that sold the channel\) can't be swept until the maturity height. All cleared orders \(purchased channels\) are cleared in a single batched on-chain transaction.
The existence of an open auction to acquire/sell channel liquidity provides all
participants on the network with a more _stable_ income source in addition to
routing network fees. By selling liquidity within the marketplace, individuals
are able to price their channels to ensure that they're compensated for the
time-value of their coins within a channel, accounting for worst-case force
close CSV delays.
The existence of an open auction to acquire/sell channel liquidity provides all participants on the network with a more _stable_ income source in addition to routing network fees. By selling liquidity within the marketplace, individuals are able to price their channels to ensure that they're compensated for the time-value of their coins within a channel, accounting for worst-case force close CSV delays.
Pool critically allows participants on the network to exchange pricing
signals to determine where liquidity in the network is most _demanded_. A
channel opened to an area of the sub-graph that doesn't actually need that
liquidity will likely remain dormant and not earn any active routing fees.
Instead, if capital can be allocated within the network in an efficient manner,
being placed where it's most demanded, we can better utilize the allocated
capital on the network, and also allow new participants to easily identify
where their capital is most needed.
Pool critically allows participants on the network to exchange pricing signals to determine where liquidity in the network is most _demanded_. A channel opened to an area of the sub-graph that doesn't actually need that liquidity will likely remain dormant and not earn any active routing fees. Instead, if capital can be allocated within the network in an efficient manner, being placed where it's most demanded, we can better utilize the allocated capital on the network, and also allow new participants to easily identify where their capital is most needed.
Amongst several other uses cases, the Pool allows a new participant in the
network to easily _boostrap_ their ability to receive funds by paying only a
percentage of the total amount of inbound funds acquired. As an example, a node
could acquire 100 million satoshis (1000 units, more on that below) for 100,000
satoshis, or 0.1%. Ultimately the prices will be determined by the open market
place.
Amongst several other uses cases, the Pool allows a new participant in the network to easily _boostrap_ their ability to receive funds by paying only a percentage of the total amount of inbound funds acquired. As an example, a node could acquire 100 million satoshis \(1000 units, more on that below\) for 100,000 satoshis, or 0.1%. Ultimately the prices will be determined by the open market place.
A non-exhaustive list of use cases includes:
* **Bootstrapping new users with side car channels**: A common question
posted concerning the Lightning Network goes something like: Alice is new
to Bitcoin entirely, how can she join the Lightning Network without her,
herself, making any new on-chain Bitcoin transactions? It’s desirable to a
solution to onboarding new users on to the network which is as as simple as
sending coins to a fresh address. The Pool solves this by allowing a third
party Carol, to purchase a channel _for_ Alice, which includes starting
_outbound_ liquidity.
* **Bootstrapping new users with side car channels**: A common question posted concerning the Lightning Network goes something like: Alice is new to Bitcoin entirely, how can she join the Lightning Network without her, herself, making any new on-chain Bitcoin transactions? It’s desirable to a solution to onboarding new users on to the network which is as as simple as sending coins to a fresh address. The Pool solves this by allowing a third party Carol, to purchase a channel _for_ Alice, which includes starting _outbound_ liquidity.
* **Demand fueled routing node channel selection**: Another common question with regards to the LN is: "where should I open my channels to , such that they'll actually be routed through"?. Pool provides a new signal for autopilot agents: a market demand signal. The node can offer up its liquidity and have it automatically be allocated where it's most demanded.
* **Bootstrapping new services to Lightning**: Any new service launched on the Lightning Network will likely need to figure out how to obtain inbound channels so they can accept payments. For this Pool provides an elegant solution in that a merchant can set up a series of "introduction points" negotiated via the market place. The merchant can pay a small percentage of the total amount of liquidity allocated towards it, and also ensure that the funds will be committed for a set period of time.
* **Allowing users to instantly receive with a wallet**: A common UX challenge that wallets face concerns ensuring a user can receive funds as soon as they set up a wallet. Some wallet providers have chosen to open new inbound channels to users themselves. This gives users the inbound bandwidth they need to receive, but can come at a high capital cost to the wallet provider as they need to commit funds with a 1:1 ratio. The Lightning Pool allows them to achieve some leverage in a sense, as they can pay only a percentage of the funds to be allocated to a new user. As an eaxmple, they can pay 1000 satohis to have 1 million satoshis be alloacted to a user.
* **Demand fueled routing node channel selection**: Another common question
with regards to the LN is: "where should I open my channels to , such that
they'll actually be routed through"?. Pool provides a new signal for
autopilot agents: a market demand signal. The node can offer up its
liquidity and have it automatically be allocated where it's most demanded.
* **Bootstrapping new services to Lightning**: Any new service launched on
the Lightning Network will likely need to figure out how to obtain inbound
channels so they can accept payments. For this Pool provides an elegant
solution in that a merchant can set up a series of "introduction points"
negotiated via the market place. The merchant can pay a small percentage of
the total amount of liquidity allocated towards it, and also ensure that
the funds will be committed for a set period of time.
* **Allowing users to instantly receive with a wallet**: A common UX
challenge that wallets face concerns ensuring a user can receive funds as
soon as they set up a wallet. Some wallet providers have chosen to open new
inbound channels to users themselves. This gives users the inbound
bandwidth they need to receive, but can come at a high capital cost to the
wallet provider as they need to commit funds with a 1:1 ratio. The
Lightning Pool allows them to achieve some leverage in a sense, as they can
pay only a percentage of the funds to be allocated to a new user. As an
eaxmple, they can pay 1000 satohis to have 1 million satoshis be alloacted
to a user.