RelevantBatchSnapshot

Source: auctioneerrpc/auctioneer.proto

gRPC

rpc RelevantBatchSnapshot (RelevantBatchRequest) returns (RelevantBatch);

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 = {
  id: <bytes>,
  accounts: <bytes>,
};
client.relevantBatchSnapshot(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "version": <uint32>,
//    "id": <bytes>,
//    "charged_accounts": <AccountDiff>,
//    "matched_orders": <MatchedOrdersEntry>,
//    "clearing_price_rate": <uint32>,
//    "execution_fee": <ExecutionFee>,
//    "transaction": <bytes>,
//    "fee_rate_sat_per_kw": <uint64>,
//    "creation_timestamp_ns": <uint64>,
//    "matched_markets": <MatchedMarketsEntry>,
//  }

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.RelevantBatchRequest(
  id=<bytes>,
  accounts=<bytes>,
)
response = stub.RelevantBatchSnapshot(request)
print(response)
# {
#    "version": <uint32>,
#    "id": <bytes>,
#    "charged_accounts": <AccountDiff>,
#    "matched_orders": <MatchedOrdersEntry>,
#    "clearing_price_rate": <uint32>,
#    "execution_fee": <ExecutionFee>,
#    "transaction": <bytes>,
#    "fee_rate_sat_per_kw": <uint64>,
#    "creation_timestamp_ns": <uint64>,
#    "matched_markets": <MatchedMarketsEntry>,
# }

Shell

# There is no CLI command for this RPC

Messages

poolrpc.RelevantBatchRequest

Source: auctioneerrpc/auctioneer.proto

Field	gRPC Type	REST Type	REST Placement
id The unique identifier of the batch.	bytes	unknown	unknown
accounts The set of accounts the trader is interested in retrieving information for within the batch. Each account is identified by its trader key.	bytes[]	unknown	unknown

poolrpc.RelevantBatch

Source: auctioneerrpc/auctioneer.proto

Field	gRPC Type	REST Type
version The version of the batch.	uint32	unknown
id The unique identifier of the batch.	bytes	unknown
charged_accounts The set of modifications that should be applied to the requested accounts as a result of this batch.	AccountDiff[]	unknown
matched_ordersdeprecated Deprecated, use matched_markets.	MatchedOrdersEntry[]	unknown
clearing_price_ratedeprecated Deprecated, use matched_markets.	uint32	unknown
execution_fee The fee parameters used to calculate the execution fees.	ExecutionFee	unknown
transaction The batch transaction including all witness data.	bytes	unknown
fee_rate_sat_per_kw Fee rate of the batch transaction, expressed in satoshis per 1000 weight units (sat/kW).	uint64	unknown
creation_timestamp_ns The unix timestamp in nanoseconds the batch was made.	uint64	unknown
matched_markets Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.	MatchedMarketsEntry[]	unknown

Nested Messages

poolrpc.AccountDiff

Field	gRPC Type	REST Type
ending_balance The final balance of the account after the executed batch.	uint64	unknown
ending_state Depending on the amount of the final balance of the account, the remainder is either sent to a new on-chain output, extended off-chain or fully consumed by the batch and its fees.	AccountState	unknown
outpoint_index If the account was re-created on-chain then the new account's index in the transaction is set here. If the account was fully spent or the remainder was extended off-chain then no new account outpoint is created and -1 is returned here.	int32	unknown
trader_key The trader's account key this diff is referring to.	bytes	unknown
new_expiry The new account expiry height used to verify the batch. If the batch is successfully executed the account must update its expiry height to this value.	uint32	unknown
new_version The new account version used to verify the batch. If this is non-zero, it means the account was automatically upgraded to the given version during the batch execution.	uint32	unknown

poolrpc.ExecutionFee

Field	gRPC Type	REST Type
base_fee The base fee in satoshis charged per order, regardless of the matched size.	uint64	string
fee_rate The fee rate in parts per million.	uint64	string

poolrpc.MatchedAsk

Field	gRPC Type	REST Type
ask The ask order that was matched against.	ServerAsk	unknown
units_filled The number of units that were filled from/by this matched order.	uint32	unknown

poolrpc.MatchedBid

Field	gRPC Type	REST Type
bid The ask order that was matched against.	ServerBid	unknown
units_filled The number of units that were filled from/by this matched order.	uint32	unknown

poolrpc.MatchedMarket

Field	gRPC Type	REST Type
matched_orders Maps a user's own order_nonce to the opposite order type they were matched with. The order_nonce is a 32 byte hex encoded string because bytes is not allowed as a map key data type in protobuf.	MatchedOrdersEntry[]	unknown
clearing_price_rate The uniform clearing price rate in parts per billion that was used for this batch.	uint32	unknown

poolrpc.MatchedMarket.MatchedOrdersEntry

Field	gRPC Type	REST Type
key	string	unknown
value	MatchedOrder	unknown

poolrpc.MatchedOrder

Field	gRPC Type	REST Type
matched_bids The bids the trader's own order was matched against. This list is empty if the trader's order was a bid order itself.	MatchedBid[]	unknown
matched_asks The asks the trader's own order was matched against. This list is empty if the trader's order was an ask order itself.	MatchedAsk[]	unknown

poolrpc.NodeAddress

Field	gRPC Type	REST Type
network	string	unknown
addr	string	unknown

poolrpc.RelevantBatch.MatchedMarketsEntry

Field	gRPC Type	REST Type
key	uint32	unknown
value	MatchedMarket	unknown

poolrpc.RelevantBatch.MatchedOrdersEntry

Field	gRPC Type	REST Type
key	string	unknown
value	MatchedOrder	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.AccountDiff.AccountState

Name	Number
OUTPUT_RECREATED	0
OUTPUT_DUST_EXTENDED_OFFCHAIN	1
OUTPUT_DUST_ADDED_TO_FEES	2
OUTPUT_FULLY_SPENT	3

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