Leases

Leases returns the list of channels that were either purchased or sold by the trader within the auction.

Source: poolrpc/trader.proto

gRPC

rpc Leases (LeasesRequest) returns (LeasesResponse);

REST

HTTP Method	Path
GET	/v1/pool/leases

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 = {
  batch_ids: <bytes>,
  accounts: <bytes>,
};
client.leases(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "leases": <Lease>,
//    "total_amt_earned_sat": <uint64>,
//    "total_amt_paid_sat": <uint64>,
//  }

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.LeasesRequest(
  batch_ids=<bytes>,
  accounts=<bytes>,
)
response = stub.Leases(request)
print(response)
# {
#    "leases": <Lease>,
#    "total_amt_earned_sat": <uint64>,
#    "total_amt_paid_sat": <uint64>,
# }

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/leases`,
  // 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:
//  {
//    "leases": <array>, // <Lease> 
//    "total_amt_earned_sat": <string>, // <uint64> 
//    "total_amt_paid_sat": <string>, // <uint64> 
//  }

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/leases'
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())
# {
#    "leases": <Lease>,
#    "total_amt_earned_sat": <uint64>,
#    "total_amt_paid_sat": <uint64>,
# }

Shell

$ pool auction leases --help

NAME:
   pool auction leases - returns the list of leases purchased/sold within the auction

USAGE:
   pool auction leases [command options] [arguments...]

DESCRIPTION:
   
  Returns the list of leases (i.e., channels) that were either purchased
  or sold by the trader within the auction. An optional list of batch IDs
  and accounts can be specified to filter the leases returned.
  

OPTIONS:
   --batch_ids value  the target batch IDs to obtain leases for, if left blank, leases from all batches are returned
   --accounts value   the target accounts to obtain leases for, if left blank, leases from all accounts are returned
   

Messages

poolrpc.LeasesRequest

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type	REST Placement
batch_ids An optional list of batches to retrieve the leases of. If empty, leases throughout all batches are returned.	bytes[]	array	query
accounts An optional list of accounts to retrieve the leases of. If empty, leases for all accounts are returned.	bytes[]	array	query

poolrpc.LeasesResponse

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type
leases The relevant list of leases purchased or sold within the auction.	Lease[]	array
total_amt_earned_sat The total amount of satoshis earned from the leases returned.	uint64	string
total_amt_paid_sat The total amount of satoshis paid for the leases returned.	uint64	string

Nested Messages

poolrpc.Lease

Field	gRPC Type	REST Type
channel_point The outpoint of the channel created.	OutPoint	object
channel_amt_sat The amount, in satoshis, of the channel created.	uint64	string
channel_duration_blocks The intended duration, in blocks, of the channel created.	uint32	integer
channel_lease_expiry The absolute height that this channel lease expires.	uint32	integer
premium_sat The premium, in satoshis, either paid or received for the offered liquidity.	uint64	string
execution_fee_sat The execution fee, in satoshis, charged by the auctioneer for the channel created.	uint64	string
chain_fee_sat The fee, in satoshis, charged by the auctioneer for the batch execution transaction that created this lease.	uint64	string
clearing_rate_price The actual fixed rate expressed in parts per billionth this lease was bought/sold at.	uint64	string
order_fixed_rate The actual fixed rate of the bid/ask, this should always be 'better' than the clearing_rate_price.	uint64	string
order_nonce The order executed that resulted in the channel created.	bytes	string
matched_order_nonce The unique identifier for the order that was matched with that resulted in the channel created.	bytes	string
purchased Whether this channel was purchased from another trader or not.	bool	boolean
channel_remote_node_key The pubkey of the node that this channel was bought/sold from.	bytes	string
channel_node_tier The tier of the node that this channel was bought/sold from.	NodeTier	string
self_chan_balance The self channel balance that was pushed to the recipient.	uint64	string
sidecar_channel Whether the channel was leased as a sidecar channel (bid orders only).	bool	boolean

poolrpc.OutPoint

Field	gRPC Type	REST Type
txid Raw bytes representing the transaction id.	bytes	string
output_index The index of the output on the transaction.	uint32	integer

Enums

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