From b85169917b9c9678d5084ce36d69b2c9f5ff36dd Mon Sep 17 00:00:00 2001
From: positiveblue <jordi.montes.sanabria@gmail.com>
Date: Fri, 7 Oct 2022 07:59:37 -0700
Subject: [PATCH] docs: sketch the two supported auction types

---
 cmd/pool/order.go | 27 ++++++++++++++++++++++++---
 docs/orders.md    | 11 +++++++++++
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/cmd/pool/order.go b/cmd/pool/order.go
index 235293c..a669bc2 100644
--- a/cmd/pool/order.go
+++ b/cmd/pool/order.go
@@ -33,6 +33,26 @@ const (
 	defaultConfirmationConstraints = 1
 
 	defaultAuctionType = auctionTypeInboundLiquidity
+
+	submitOrderDescription = `
+        Submit a new order in the given market. Currently, Pool supports two
+        types of orders: asks, and bids. In Pool, market participants buy/sell 
+        liquidity in _units_. A unit is 100,000 satoshis.
+
+        In the *inbound* market, the bidder pays the asker a premium for a
+        channel with 50% to 100% of inbound liquidity. The premium amount is 
+        calculated using the funding amount of the asker.
+
+        In the outbound market, the bidder pays the asker a premium for  
+        a channel with outbound liquidity. 
+        To participate in the outbound market the asker needs to create an order
+        with '--amount=100000' (one unit) and the '--min_chan_amt' equals to 
+        the minimum channel size that is willing to accept.
+        The bidder needs to create an order with '--amount=100000' (one unit) 
+        and '--self_chan_balance' equals to the funds that is willing to commit 
+        in a channel. The premium amount is calculated using the funding amount 
+        of the bidder ('--self_chan_balance').
+        `
 )
 
 var ordersCommands = []cli.Command{
@@ -45,9 +65,10 @@ var ordersCommands = []cli.Command{
 			ordersListCommand,
 			ordersCancelCommand,
 			{
-				Name:    "submit",
-				Aliases: []string{"s"},
-				Usage:   "submit an order",
+				Name:        "submit",
+				Aliases:     []string{"s"},
+				Usage:       "submit an order",
+				Description: submitOrderDescription,
 				Subcommands: []cli.Command{
 					ordersSubmitAskCommand,
 					ordersSubmitBidCommand,
diff --git a/docs/orders.md b/docs/orders.md
index 07be5a3..d7d5087 100644
--- a/docs/orders.md
+++ b/docs/orders.md
@@ -297,6 +297,17 @@ To cancel an order. First get the order_nonce of the to be canceled order by usi
 $ pool orders cancel order_nonce
 ```
 
+## Auction types
+
+Currently there are two kind of auction types supported in pool:
+
+* **BTC inbound liquidity market**: the bidder pays the asker for getting a channel where most of the funding liquidity comes from the asker. The bidder pays a premium based on the asker liquidity supply.
+
+* **BTC outbound liquidity market**: the bidder pays the asker for opening a channel where most of the funding liquidity comes from the bidder side. The bidder pays a premium based on the bidder liquidity supply. 
+In this kind of auctions the asker needs to set the order amount to 100k and specify the `min_chan_amt` that will be matched against the bidder's `self_chan_balance`. The bidder needs to set the order amount to 100k and a `self_chan_balance` greater or equal than 100k.
+Sidecar tickets are not supported in this kind of auction yet.
+
+
 ## 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.