SubmitOrder

Source: auctioneerrpc/auctioneer.proto

gRPC

rpc SubmitOrder (ServerSubmitOrderRequest) returns (ServerSubmitOrderResponse);

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('auctioneerrpc/auctioneer.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.ChannelAuctioneer(GRPC_HOST, creds);
let request = {
  ask: <ServerAsk>,
  bid: <ServerBid>,
  user_agent: <string>,
};
client.submitOrder(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "invalid_order": <InvalidOrder>,
//    "accepted": <bool>,
//  }

Python

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

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 = auctioneerstub.ChannelAuctioneerStub(channel)
request = poolrpc.ServerSubmitOrderRequest(
  ask=<ServerAsk>,
  bid=<ServerBid>,
  user_agent=<string>,
)
response = stub.SubmitOrder(request)
print(response)
# {
#    "invalid_order": <InvalidOrder>,
#    "accepted": <bool>,
# }

Shell

# There is no CLI command for this RPC

Messages

poolrpc.ServerSubmitOrderRequest

Source: auctioneerrpc/auctioneer.proto

Field	gRPC Type	REST Type	REST Placement
ask Submit an ask order.	ServerAsk	unknown	unknown
bid Submit a bid order.	ServerBid	unknown	unknown
user_agent The user agent string that identifies the software running on the user's side. This can be changed in the user's client software but it SHOULD conform to the following pattern and use less than 256 characters: Agent-Name/semver-version(/additional-info) Examples: poold/v0.4.2-beta/commit=3b635821,initiator=pool-cli litd/v0.4.0-alpha/commit=326d754,initiator=lit-ui	string	unknown	unknown

poolrpc.ServerSubmitOrderResponse

Source: auctioneerrpc/auctioneer.proto

Field	gRPC Type	REST Type
invalid_order Order failed with the given reason.	InvalidOrder	unknown
accepted Order was accepted.	bool	unknown

Nested Messages

poolrpc.InvalidOrder

Field	gRPC Type	REST Type
order_nonce	bytes	string
fail_reason	FailReason	string
fail_string	string	string

poolrpc.NodeAddress

Field	gRPC Type	REST Type
network	string	unknown
addr	string	unknown

poolrpc.ServerAsk

Field	gRPC Type	REST Type
details The common fields shared between both ask and bid order types.	ServerOrder	unknown
lease_duration_blocks The number of blocks the liquidity provider is willing to provide the channel funds for.	uint32	unknown
version The version of the order format that is used. Will be increased once new features are added.	uint32	unknown
announcement_constraints The constraints for selling the liquidity based on channel discoverability.	ChannelAnnouncementConstraints	unknown
confirmation_constraints The constraints for selling the liquidity based on the number of blocks before considering the channel confirmed.	ChannelConfirmationConstraints	unknown

poolrpc.ServerBid

Field	gRPC Type	REST Type
details The common fields shared between both ask and bid order types.	ServerOrder	unknown
lease_duration_blocks Required number of blocks that a channel opened as a result of this bid should be kept open.	uint32	unknown
version The version of the order format that is used. Will be increased once new features are added.	uint32	unknown
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	unknown
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	unknown
is_sidecar_channel If this bid order is meant to lease a channel for another node (which is dubbed a "sidecar channel") then this boolean needs to be set to true. The multi_sig_key, node_pub and node_addr fields of the order details must then correspond to the recipient node's details.	bool	unknown
unannounced_channel Signals if this bid is interested in an announced or unannounced channel.	bool	unknown
zero_conf_channel Signals if this bid is interested in a zero conf channel or not.	bool	unknown

poolrpc.ServerOrder

Field	gRPC Type	REST Type
trader_key The trader's account key of the account to use for the order.	bytes	unknown
rate_fixed Fixed order rate in parts per billion.	uint32	unknown
amt Order amount in satoshis.	uint64	unknown
min_chan_amt	uint64	unknown
order_nonce Order nonce of 32 byte length, acts as unique order identifier.	bytes	unknown
order_sig Signature of the order's digest, signed with the user's account key. The signature must be fixed-size LN wire format encoded. Version 0 includes the fields version, rate_fixed, amt, max_batch_fee_rate_sat_per_kw and lease_duration_blocks in the order digest.	bytes	unknown
multi_sig_key The multi signature key of the node creating the order, will be used for the target channel's funding TX 2-of-2 multi signature output.	bytes	unknown
node_pub The pubkey of the node creating the order.	bytes	unknown
node_addr The network addresses of the node creating the order.	NodeAddress[]	unknown
channel_type The type of the channel that should be opened.	OrderChannelType	unknown
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	unknown
allowed_node_ids List of nodes that will be allowed to match with our order. Incompatible with the `not_allowed_node_ids` field.	bytes[]	unknown
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[]	unknown
auction_type Auction type where this order must be considered during the matching.	AuctionType	unknown
is_public Flag used to signal that this order can be shared in public market places.	bool	unknown

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.ChannelAnnouncementConstraints

Name	Number
ANNOUNCEMENT_NO_PREFERENCE	0
ONLY_ANNOUNCED	1
ONLY_UNANNOUNCED	2

poolrpc.ChannelConfirmationConstraints

Name	Number
CONFIRMATION_NO_PREFERENCE	0
ONLY_CONFIRMED	1
ONLY_ZEROCONF	2

poolrpc.InvalidOrder.FailReason

Name	Number
INVALID_AMT	0

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