OfferSidecar

OfferSidecar is step 1/4 of the sidecar negotiation between the provider (the trader submitting the bid order) and the recipient (the trader receiving the sidecar channel). This step must be run by the provider. The result is a sidecar ticket with an offer to lease a sidecar channel for the recipient. The offer will be signed with the provider's lnd node public key. The ticket returned by this call will have the state "offered".

Source: poolrpc/trader.proto

gRPC

rpc OfferSidecar (OfferSidecarRequest) returns (SidecarTicket);

REST

HTTP Method	Path
POST	/v1/pool/sidecar/offer

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:12010'
const MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
const TLS_PATH = 'POOL_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new poolrpc.Trader(GRPC_HOST, creds);
let request = {
  auto_negotiate: <bool>,
  bid: <Bid>,
};
client.offerSidecar(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "ticket": <string>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the poolrpc/trader.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub

GRPC_HOST = 'localhost:12010'
MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
TLS_PATH = 'POOL_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = traderstub.TraderStub(channel)
request = poolrpc.OfferSidecarRequest(
  auto_negotiate=<bool>,
  bid=<Bid>,
)
response = stub.OfferSidecar(request)
print(response)
# {
#    "ticket": <string>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8281'
const MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'

let requestBody = {
  auto_negotiate: <boolean>, // <bool> 
  bid: <object>, // <Bid> 
};
let options = {
  url: `https://${REST_HOST}/v1/pool/sidecar/offer`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "ticket": <string>, // <string> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8281'
MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
TLS_PATH = 'POOL_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/pool/sidecar/offer'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'auto_negotiate': <bool>,
  'bid': <Bid>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "ticket": <string>,
# }

Shell

$ pool sidecar offer --help

NAME:
   pool sidecar offer - offer a sidecar channel

USAGE:
   pool sidecar offer [command options] [<full bid args> --auto] | capacity self_chan_balance lease_duration_blocks acct_key

DESCRIPTION:
   
  Creates an offer for providing a sidecar channel to another node.
  If the auto flag is specified, then all bid information needs to be 
  specified as normal. If the auto flag isn't specified, then only 
  capacity, self_chan_balance, lease_duration_blocks, and acct_key
  need to set.

OPTIONS:
   --interest_rate_percent value  the total percent one is willing to pay or accept as yield for the specified interval (default: 0)
   --amt value                    the amount of inbound liquidity in satoshis to request (default: 0)
   --acct_key value               the account key to use to pay the order fees with
   --lease_duration_blocks value  the number of blocks that the liquidity should be provided for (default: 2016)
   --min_node_tier value          the min node tier this bid should be matched with, tier 1 nodes are considered 'good', if set to tier 0, then all nodes will be considered regardless of 'quality' (default: 0)
   --min_chan_amt value           the minimum amount of satoshis that a resulting channel from this order must have (default: 0)
   --force                        skip order placement confirmation
   --self_chan_balance value      give the channel leased by this bid order an initial balance by adding additional funds from our account into the channel; can be used to create up to 50/50 balanced channels (default: 0)
   --unannounced_channel          flag used to signal that this bid is interested only in unannounced channels. If this flag is not set, the channels resulting from matching this order will be announced to the network
   --zero_conf_channel            flag used to signal that this bid is only interested in zero conf channels
   --max_batch_fee_rate value     the maximum fee rate (sat/vByte) to use to for the batch transaction (default: 100)
   --channel_type value           the type of channel resulting from the order being matched ("legacy", "script-enforced", "simple-taproot")
   --auction_type value           the auction market where this offer must be considered in during matching ("inbound", "outbound") (default: "inbound")
   --allowed_node_id value        the list of nodes this order is allowed to match with; if empty, the order will be able to match with any node unless not_allowed_node_id is set. Can be specified multiple times
   --not_allowed_node_id value    the list of nodes this order is not allowed to match with; if empty, the order will be able to match with any node unless allowed_node_id is set. Can be specified multiple times
   --public                       flag used to signal that this order's details can be shared in public market places.
   --auto                         if true, then the full bid information needs to be specified as automated negotiation will be attempted
   

Messages

poolrpc.OfferSidecarRequest

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type	REST Placement
auto_negotiate If false, then only the trader_key, unit, self_chan_balance, and lease_duration_blocks need to be set in the bid below. Otherwise, the fields as they're set when submitting a bid need to be filled in.	bool	boolean	body
bid The bid template that will be used to populate the initial sidecar ticket as well as auto negotiate the remainig steps of the sidecar channel if needed.	Bid	object	body

poolrpc.SidecarTicket

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type
ticket The complete sidecar ticket in its string encoded form which is base58 encoded, has a human readable prefix ('sidecar...') and a checksum built in. The string encoded version will only be used on the trader side of the API. All requests to the auctioneer expect the ticket to be in its raw, tlv encoded byte form.	string	string

Nested Messages

poolrpc.Bid

Field	gRPC Type	REST Type
details The common fields shared between both ask and bid order types.	Order	object
lease_duration_blocks Required number of blocks that a channel opened as a result of this bid should be kept open.	uint32	integer
version The version of the order format that is used. Will be increased once new features are added.	uint32	integer
min_node_tier The minimum node tier this order should be matched with. Only asks backed by a node this tier or higher will be eligible for matching with this bid.	NodeTier	string
self_chan_balance Give the incoming channel that results from this bid being matched an initial outbound balance by adding additional funds from the taker's account into the channel. As a simplification for the execution protocol and the channel reserve calculations the min_chan_amt must be set to the full order amount. For the inbound liquidity market the self_chan_balance can be at most the same as the order amount.	uint64	string
sidecar_ticket If this bid order is meant to lease a channel for another node (which is dubbed a "sidecar channel") then this ticket contains all information required for setting up that sidecar channel. The ticket is expected to be the base58 encoded ticket, including the prefix and the checksum.	string	string
unannounced_channel Signals if this bid is interested in an announced or unannounced channel.	bool	boolean
zero_conf_channel Signals if this bid is interested in a zero conf channel or not.	bool	boolean

poolrpc.MatchEvent

Field	gRPC Type	REST Type
match_state The state of the match making process the order went through.	MatchState	string
units_filled The number of units that would be (or were) filled with this match.	uint32	integer
matched_order The nonce of the order we were matched to.	bytes	string
reject_reason The reason why the trader daemon rejected the order. Is only set if match_state is set to REJECTED.	MatchRejectReason	string

poolrpc.Order

Field	gRPC Type	REST Type
trader_key The trader's account key of the account that is used for the order.	bytes	string
rate_fixed Fixed order rate in parts per billion.	uint32	integer
amt Order amount in satoshis.	uint64	string
max_batch_fee_rate_sat_per_kw Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).	uint64	string
order_nonce Order nonce, acts as unique order identifier.	bytes	string
state The state the order currently is in.	OrderState	string
units The number of order units the amount corresponds to.	uint32	integer
units_unfulfilled The number of currently unfilled units of this order. This will be equal to the total amount of units until the order has reached the state PARTIAL_FILL or EXECUTED.	uint32	integer
reserved_value_sat The value reserved from the account by this order to ensure the account can pay execution and chain fees in case it gets matched.	uint64	string
creation_timestamp_ns The unix timestamp in nanoseconds the order was first created/submitted.	uint64	string
events A list of events that were emitted for this order. This field is only set when the verbose flag is set to true in the request.	OrderEvent[]	array
min_units_match The minimum number of order units that must be matched per order pair.	uint32	integer
channel_type The channel type to use for the resulting matched channels.	OrderChannelType	string
allowed_node_ids List of nodes that will be allowed to match with our order. Incompatible with the `not_allowed_node_ids` field.	bytes[]	array
not_allowed_node_ids List of nodes that won't be allowed to match with our order. Incompatible with the `allowed_node_ids` field.	bytes[]	array
auction_type Auction type where this order must be considered during the matching.	AuctionType	string
is_public Flag used to signal that this order can be shared in public market places.	bool	boolean

poolrpc.OrderEvent

Field	gRPC Type	REST Type
timestamp_ns The unix timestamp in nanoseconds the event was emitted at. This is the primary key of the event and is unique across the database.	int64	string
event_str The human readable representation of the event.	string	string
state_change The order was updated in the database.	UpdatedEvent	object
matched The order was involved in a match making attempt.	MatchEvent	object

poolrpc.UpdatedEvent

Field	gRPC Type	REST Type
previous_state The state of the order previous to the change. This is what the state changed from.	OrderState	string
new_state The new state of the order after the change. This is what the state changed to.	OrderState	string
units_filled The units that were filled at the time of the event.	uint32	integer

Enums

poolrpc.AuctionType

Name	Number
AUCTION_TYPE_BTC_INBOUND_LIQUIDITY Default auction type where the bidder is paying for getting bitcoin inbound liqiudity from the asker.	0
AUCTION_TYPE_BTC_OUTBOUND_LIQUIDITY Auction type where the bidder is paying the asker to accept a channel (bitcoin outbound liquidity) from the bidder.	1

poolrpc.MatchRejectReason

Name	Number
NONE No reject occurred, this is the default value.	0
SERVER_MISBEHAVIOR The client didn't come up with the same result as the server and is rejecting the batch because of that.	1
BATCH_VERSION_MISMATCH The client doesn't support the current batch verification version the server is using.	2
PARTIAL_REJECT_COLLATERAL The client rejects some of the orders, not the full batch. This reason is set on matches for orders that were in the same batch as partial reject ones but were not themselves rejected.	3
PARTIAL_REJECT_DUPLICATE_PEER The trader's client has a preference to only match orders with peers it doesn't already have channels with. The order that is rejected with this reason type comes from a peer that the trader already has channels with.	4
PARTIAL_REJECT_CHANNEL_FUNDING_FAILED The trader's client couldn't connect to the remote node of the matched order or the channel funding could not be initialized for another reason. This could also be the rejecting node's fault if their connection is not stable. Using this code can have a negative impact on the reputation score of both nodes, depending on the number of errors recorded.	5

poolrpc.MatchState

Name	Number
PREPARE The OrderMatchPrepare message from the auctioneer was received initially.	0
ACCEPTED The OrderMatchPrepare message from the auctioneer was processed successfully and the batch was accepted.	1
REJECTED The order was rejected by the trader daemon, either as an answer to a OrderMatchSignBegin or OrderMatchFinalize message from the auctioneer.	2
SIGNED The OrderMatchSignBegin message from the auctioneer was processed successfully.	3
FINALIZED The OrderMatchFinalize message from the auctioneer was processed successfully.	4

poolrpc.NodeTier

Name	Number
TIER_DEFAULT The default node tier. This value will be determined at run-time by the current order version.	0
TIER_0 Tier 0, bid with this tier are opting out of the smaller "higher quality" pool of nodes to match their bids. Nodes in this tier are considered to have "no rating".	1
TIER_1 Tier 1, the "base" node tier. Nodes in this tier are shown to have a higher degree of up time and route-ability compared to the rest of the nodes in the network. This is the current default node tier when submitting bid orders.	2

poolrpc.OrderChannelType

Name	Number
ORDER_CHANNEL_TYPE_UNKNOWN Used to set defaults when a trader doesn't specify a channel type.	0
ORDER_CHANNEL_TYPE_PEER_DEPENDENT The channel type will vary per matched channel based on the features shared between its participants.	1
ORDER_CHANNEL_TYPE_SCRIPT_ENFORCED A channel type that builds upon the anchors commitment format to enforce channel lease maturities in the commitment and HTLC outputs that pay to the channel initiator/seller.	2
ORDER_CHANNEL_TYPE_SIMPLE_TAPROOT A channel type that uses a Pay-to-Taproot output for the funding output.	3

poolrpc.OrderState

Name	Number
ORDER_SUBMITTED	0
ORDER_CLEARED	1
ORDER_PARTIALLY_FILLED	2
ORDER_EXECUTED	3
ORDER_CANCELED	4
ORDER_EXPIRED	5
ORDER_FAILED	6