BatchSnapshots

BatchSnapshots returns a list of batch snapshots starting at the start batch ID and going back through the history of batches, returning at most the number of specified batches. A maximum of 100 snapshots can be queried in one call. If no start batch ID is provided, the most recent finalized batch is used as the starting point to go back from.

Source: poolrpc/trader.proto

gRPC

rpc BatchSnapshots (BatchSnapshotsRequest) returns (BatchSnapshotsResponse);

REST

HTTP Method	Path
GET	/v1/pool/batch/snapshots

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 = {
  start_batch_id: <bytes>,
  num_batches_back: <uint32>,
};
client.batchSnapshots(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "batches": <BatchSnapshotResponse>,
//  }

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.BatchSnapshotsRequest(
  start_batch_id=<bytes>,
  num_batches_back=<uint32>,
)
response = stub.BatchSnapshots(request)
print(response)
# {
#    "batches": <BatchSnapshotResponse>,
# }

REST

Javascript

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

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

let options = {
  url: `https://${REST_HOST}/v1/pool/batch/snapshots`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "batches": <array>, // <BatchSnapshotResponse> 
//  }

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/batch/snapshots'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "batches": <BatchSnapshotResponse>,
# }

Shell

$ pool auction snapshot --help

NAME:
   pool auction snapshot - return information about a prior cleared auction batch

USAGE:
   pool auction snapshot [command options] batch_id

DESCRIPTION:
   
    Returns information about a prior batch or batches such as the
    clearing price and the set of orders included in the batch. The
    prev_batch_id field can be used to explore prior batches in the
    sequence, similar to a block chain.
    

OPTIONS:
   --batch_id value     the target batch ID to obtain a snapshot for, if left blank, information about the latest batch is returned
   --num_batches value  the number of batches to show, starting at the batch_id and going back through the history of finalized batches (default: 1)
   

Messages

poolrpc.BatchSnapshotsRequest

Source: auctioneerrpc/auctioneer.proto

Field	gRPC Type	REST Type	REST Placement
start_batch_id The unique identifier of the first batch to return, encoded as a compressed pubkey. This represents the newest/most current batch to fetch. If this is empty or a zero batch ID, the most recent finalized batch is used as the starting point to go back from.	bytes	string	query
num_batches_back The number of batches to return at most, including the start batch.	uint32	integer	query

poolrpc.BatchSnapshotsResponse

Source: auctioneerrpc/auctioneer.proto

Field	gRPC Type	REST Type
batches The list of batches requested.	BatchSnapshotResponse[]	array

Nested Messages

poolrpc.AskSnapshot

Field	gRPC Type	REST Type
version The version of the order.	uint32	integer
lease_duration_blocks The period of time the channel will survive for.	uint32	integer
rate_fixed The true bid price of the order in parts per billion.	uint32	integer
chan_type The channel type to be created.	OrderChannelType	string

poolrpc.BatchSnapshotResponse

Field	gRPC Type	REST Type
version The version of the batch.	uint32	integer
batch_id The unique identifier of the batch.	bytes	string
prev_batch_id The unique identifier of the prior batch.	bytes	string
clearing_price_ratedeprecated Deprecated, use matched_markets.	uint32	integer
matched_ordersdeprecated Deprecated, use matched_markets.	MatchedOrderSnapshot[]	array
batch_tx_id The txid of the batch transaction.	string	string
batch_tx The batch transaction including all witness data.	bytes	string
batch_tx_fee_rate_sat_per_kw The fee rate, in satoshis per kiloweight, of the batch transaction.	uint64	string
creation_timestamp_ns The unix timestamp in nanoseconds the batch was made.	uint64	string
matched_markets Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.	MatchedMarketsEntry[]	object

poolrpc.BatchSnapshotResponse.MatchedMarketsEntry

Field	gRPC Type	REST Type
key	uint32	unknown
value	MatchedMarketSnapshot	unknown

poolrpc.BidSnapshot

Field	gRPC Type	REST Type
version The version of the order.	uint32	integer
lease_duration_blocks The period of time the matched channel should be allocated for.	uint32	integer
rate_fixed The true bid price of the order in parts per billion.	uint32	integer
chan_type The channel type to be created.	OrderChannelType	string

poolrpc.MatchedMarketSnapshot

Field	gRPC Type	REST Type
matched_orders The set of all orders matched in the batch.	MatchedOrderSnapshot[]	array
clearing_price_rate The uniform clearing price rate in parts per billion that was used for this batch.	uint32	integer

poolrpc.MatchedOrderSnapshot

Field	gRPC Type	REST Type
ask The full ask order that was matched.	AskSnapshot	object
bid The full bid order that was matched.	BidSnapshot	object
matching_rate The fixed rate premium that was matched, expressed in parts-ber-billion.	uint32	integer
total_sats_cleared The total number of satoshis that were bought.	uint64	string
units_matched The total number of units that were matched.	uint32	integer

Enums

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