Pool gRPC API Reference
Welcome to the gRPC API reference documentation for Lightning Pool.
Lightning Pool is a non-custodial batched uniform clearing-price auction for
Lightning Channel Lease (LCL). A LCL packages up inbound (or outbound!) channel
liquidity (ability to send/receive funds) as a fixed incoming asset (earning
interest over time) with a maturity date expressed in blocks. The maturity date
of each of the channels is enforced by Bitcoin contracts, ensuring that the
funds of the maker (the party that sold the channel) can't be swept until the
maturity height. All cleared orders (purchased channels) are cleared in a
single batched on-chain transaction.
This repository is home to the Pool client and depends on the Lightning Network
daemon lnd. All of lnd’s supported chain backends are fully supported when
using the Pool client: Neutrino, Bitcoin Core, and btcd.
The service can be used in various situations:
- Bootstrapping new users with side car channels
- Bootstrapping new services to Lightning
- Demand fueled routing node channel selection
- Allowing users to instantly receive with a wallet
This site features the documentation for pool (CLI), and the API documentation
for Python and JavaScript clients in order to communicate with a local poold
instance through gRPC.
The examples to the right assume that the there is a local poold instance
running and listening for gRPC connections on port 12010. POOL_DIR
will be used as a placeholder to denote the base directory of the poold
instance. By default, this is ~/.pool on Linux and
~/Library/Application Support/Pool on macOS.
At the time of writing this documentation, two things are needed in order to
make a gRPC request to a pool instance: a TLS/SSL connection and a macaroon
used for RPC authentication. The examples to the right will show how these can
be used in order to make a successful, secure, and authenticated gRPC request.
The original *.proto files from which the gRPC documentation was generated
can be found here:
This is the reference for the gRPC API. Alternatively, there is also a REST
API which is documented here.
This documentation was
generated automatically against commit
59e0fd707f706a7a74b5ac38d0fbdb8aedf44161.
Service HashMail
HashMail.DelCipherBox
Unary RPC
DelCipherBox attempts to tear down an existing cipher box pipe. The same authentication mechanism used to initially create the stream MUST be specified.
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /auctioneerrpc/hashmail.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import auctioneerrpc/hashmail_pb2 as poolrpc, auctioneerrpc/hashmail_pb2_grpc as auctioneerrpc/hashmailstub
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = auctioneerrpc/hashmailstub.HashMailStub(channel)
>>> request = poolrpc.CipherBoxAuth(
desc=<CipherBoxDesc>,
acct_auth=<PoolAccountAuth>,
sidecar_auth=<SidecarAuth>,
)
>>> response = stub.DelCipherBox(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const hashMail = new poolrpc.HashMail('localhost:12010', creds);
let request = {
desc: <CipherBoxDesc>,
acct_auth: <PoolAccountAuth>,
sidecar_auth: <SidecarAuth>,
};
hashMail.delCipherBox(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
This response has no parameters.
HashMail.NewCipherBox
Unary RPC
NewCipherBox creates a new cipher box pipe/stream given a valid authentication mechanism. If the authentication mechanism has been revoked, or needs to be changed, then a CipherChallenge message is returned. Otherwise the method will either be accepted or rejected.
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /auctioneerrpc/hashmail.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import auctioneerrpc/hashmail_pb2 as poolrpc, auctioneerrpc/hashmail_pb2_grpc as auctioneerrpc/hashmailstub
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = auctioneerrpc/hashmailstub.HashMailStub(channel)
>>> request = poolrpc.CipherBoxAuth(
desc=<CipherBoxDesc>,
acct_auth=<PoolAccountAuth>,
sidecar_auth=<SidecarAuth>,
)
>>> response = stub.NewCipherBox(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"success": <CipherSuccess>,
"challenge": <CipherChallenge>,
"error": <CipherError>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const hashMail = new poolrpc.HashMail('localhost:12010', creds);
let request = {
desc: <CipherBoxDesc>,
acct_auth: <PoolAccountAuth>,
sidecar_auth: <SidecarAuth>,
};
hashMail.newCipherBox(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "success": <CipherSuccess>,
// "challenge": <CipherChallenge>,
// "error": <CipherError>,
// }
| Parameter |
Type |
Description |
| success |
CipherSuccess |
CipherSuccess is returned if the initialization of the cipher box was successful. |
| challenge |
CipherChallenge |
CipherChallenge is returned if the authentication mechanism was revoked or needs to be refreshed. |
| error |
CipherError |
CipherError is returned if the authentication mechanism failed to validate. |
HashMail.RecvStream
Server-streaming RPC
RecvStream opens up the read side of the passed CipherBox pipe. This method will block until a full message has been read as this is a message based pipe/stream abstraction.
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /auctioneerrpc/hashmail.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import auctioneerrpc/hashmail_pb2 as poolrpc, auctioneerrpc/hashmail_pb2_grpc as auctioneerrpc/hashmailstub
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = auctioneerrpc/hashmailstub.HashMailStub(channel)
>>> request = poolrpc.CipherBoxDesc(
stream_id=<bytes>,
)
>>> for response in stub.RecvStream(request, metadata=[('macaroon', macaroon)]):
print(response)
{
"desc": <CipherBoxDesc>,
"msg": <bytes>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const hashMail = new poolrpc.HashMail('localhost:12010', creds);
let request = {
stream_id: <bytes>,
};
let call = hashMail.recvStream(request);
call.on('data', function(response) {
// A response was received from the server.
console.log(response);
});
call.on('status', function(status) {
// The current status of the stream.
});
call.on('end', function() {
// The server has closed the stream.
});
// Console output:
// {
// "desc": <CipherBoxDesc>,
// "msg": <bytes>,
// }
| Parameter |
Type |
Description |
| stream_id |
bytes |
|
HashMail.SendStream
Client-streaming RPC
SendStream opens up the write side of the passed CipherBox pipe. Writes will be non-blocking up to the buffer size of the pipe. Beyond that writes will block until completed.
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /auctioneerrpc/hashmail.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import auctioneerrpc/hashmail_pb2 as poolrpc, auctioneerrpc/hashmail_pb2_grpc as auctioneerrpc/hashmailstub
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = auctioneerrpc/hashmailstub.HashMailStub(channel)
# Define a generator that returns an Iterable of poolrpc.CipherBox objects.
>>> def request_generator():
# Initialization code here.
while True:
# Parameters here can be set as arguments to the generator.
request = poolrpc.CipherBox(
desc=<CipherBoxDesc>,
msg=<bytes>,
)
yield request
# Do things between iterations here.
>>> request_iterable = request_generator()
>>> response = stub.SendStream(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"stream_id": <bytes>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const hashMail = new poolrpc.HashMail('localhost:12010', creds);
let request = {
desc: <CipherBoxDesc>,
msg: <bytes>,
};
let call = hashMail.sendStream({});
call.on('data', function(response) {
// A response was received from the server.
console.log(response);
});
call.on('status', function(status) {
// The current status of the stream.
});
call.on('end', function() {
// The server has closed the stream.
});
call.write(request);
// Console output:
// {
// "stream_id": <bytes>,
// }
| Parameter |
Type |
Description |
| stream_id |
bytes |
|
Service Trader
Trader.AccountModificationFees
Unary RPC
AccountModificationFees returns a map from account key to an ordered list of account action modification fees.
# This command prints a map from account key to an ordered list of account
# modification transaction fees.
$ pool accounts listfees [arguments...]
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.AccountModificationFeesRequest()
>>> response = stub.AccountModificationFees(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"accounts": <array AccountsEntry>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {}
trader.accountModificationFees(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "accounts": <array AccountsEntry>,
// }
This request has no parameters.
| Parameter |
Type |
Description |
| accounts |
array AccountsEntry |
A map from account key to an ordered list of account modification fees. |
Trader.AuctionFee
Unary RPC
AuctionFee returns the current auction order execution fee specified by the auction server.
# Returns the current auction execution fee. The fee is paid for
# each order matched and scales with the size of the order.
$ pool auction fee [arguments...]
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.AuctionFeeRequest()
>>> response = stub.AuctionFee(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"execution_fee": <ExecutionFee>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {}
trader.auctionFee(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "execution_fee": <ExecutionFee>,
// }
This request has no parameters.
| Parameter |
Type |
Description |
| execution_fee |
ExecutionFee |
The execution fee charged per matched order. |
Trader.BatchSnapshot
Unary RPC
BatchSnapshot returns the snapshot of a past batch identified by its ID. If no ID is provided, the snapshot of the last finalized batch is returned. Deprecated, use BatchSnapshots instead.
# 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.
$ pool auction snapshot [command options] batch_id
# --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)
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.BatchSnapshotRequest(
batch_id=<bytes>,
)
>>> response = stub.BatchSnapshot(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"version": <uint32>,
"batch_id": <bytes>,
"prev_batch_id": <bytes>,
"clearing_price_rate": <uint32>,
"matched_orders": <array MatchedOrderSnapshot>,
"batch_tx_id": <string>,
"batch_tx": <bytes>,
"batch_tx_fee_rate_sat_per_kw": <uint64>,
"creation_timestamp_ns": <uint64>,
"matched_markets": <array MatchedMarketsEntry>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
batch_id: <bytes>,
};
trader.batchSnapshot(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "version": <uint32>,
// "batch_id": <bytes>,
// "prev_batch_id": <bytes>,
// "clearing_price_rate": <uint32>,
// "matched_orders": <array MatchedOrderSnapshot>,
// "batch_tx_id": <string>,
// "batch_tx": <bytes>,
// "batch_tx_fee_rate_sat_per_kw": <uint64>,
// "creation_timestamp_ns": <uint64>,
// "matched_markets": <array MatchedMarketsEntry>,
// }
| Parameter |
Type |
Description |
| batch_id |
bytes |
The unique identifier of the batch encoded as a compressed pubkey. |
| Parameter |
Type |
Description |
| version |
uint32 |
The version of the batch. |
| batch_id |
bytes |
The unique identifier of the batch. |
| prev_batch_id |
bytes |
The unique identifier of the prior batch. |
| clearing_price_rate |
uint32 |
Deprecated, use matched_markets. |
| matched_orders |
array MatchedOrderSnapshot |
Deprecated, use matched_markets. |
| batch_tx_id |
string |
The txid of the batch transaction. |
| batch_tx |
bytes |
The batch transaction including all witness data. |
| batch_tx_fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kiloweight, of the batch transaction. |
| creation_timestamp_ns |
uint64 |
The unix timestamp in nanoseconds the batch was made. |
| matched_markets |
array MatchedMarketsEntry |
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price. |
Trader.BatchSnapshots
Unary RPC
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.
# 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.
$ pool auction snapshot [command options] batch_id
# --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)
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.BatchSnapshotsRequest(
start_batch_id=<bytes>,
num_batches_back=<uint32>,
)
>>> response = stub.BatchSnapshots(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"batches": <array BatchSnapshotResponse>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
start_batch_id: <bytes>,
num_batches_back: <uint32>,
};
trader.batchSnapshots(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "batches": <array BatchSnapshotResponse>,
// }
| Parameter |
Type |
Description |
| start_batch_id |
bytes |
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. |
| num_batches_back |
uint32 |
The number of batches to return at most, including the start batch. |
Trader.BumpAccountFee
Unary RPC
BumpAccountFee attempts to bump the fee of an account's transaction through child-pays-for-parent (CPFP). Since the CPFP is performed through the backing lnd node, the account transaction must contain an output under its control for a successful bump. If a CPFP has already been performed for an account, and this RPC is invoked again, then a replacing transaction (RBF) of the child will be broadcast.
# This command allows users to bump the fee of an account's unconfirmed
# transaction through child-pays-for-parent (CPFP). Since the CPFP is
# performed through the backing lnd node, the account transaction must
# contain an output under its control for a successful bump. If a CPFP has
# already been performed for an account, and this RPC is invoked again,
# then a replacing transaction (RBF) of the child will be broadcast.
$ pool accounts bumpfee [command options] trader_key sat_per_vbyte
# --trader_key value the trader key associated with the account to bump the fee of
# --sat_per_vbyte value the fee rate expressed in sat/vbyte that should be used for the CPFP (default: 0)
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.BumpAccountFeeRequest(
trader_key=<bytes>,
fee_rate_sat_per_kw=<uint64>,
)
>>> response = stub.BumpAccountFee(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
trader_key: <bytes>,
fee_rate_sat_per_kw: <uint64>,
};
trader.bumpAccountFee(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader key associated with the account that will have its fee bumped. |
| fee_rate_sat_per_kw |
uint64 |
The new fee rate, in satoshis per kw, to use for the child of the account transaction. |
This response has no parameters.
Trader.CancelOrder
Unary RPC
CancelOrder cancels an active order with the auction server to remove it from future matching.
# Remove a pending offer from the order book.
$ pool orders cancel [command options] order_nonce
# --order_nonce value the order nonce of the order to cancel
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.CancelOrderRequest(
order_nonce=<bytes>,
)
>>> response = stub.CancelOrder(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
order_nonce: <bytes>,
};
trader.cancelOrder(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
| Parameter |
Type |
Description |
| order_nonce |
bytes |
|
This response has no parameters.
Trader.CancelSidecar
Unary RPC
CancelSidecar cancels the execution of a specific sidecar ticket. Depending on the state of the sidecar ticket its associated bid order might be canceled as well (if this ticket was offered by our node).
# Tries to cancel the execution of a sidecar ticket identified by its ID.
# If a bid order was created for the ticket already, that order is
# cancelled on the server side.
$ pool sidecar cancel ticket_id
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.CancelSidecarRequest(
sidecar_id=<bytes>,
)
>>> response = stub.CancelSidecar(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
sidecar_id: <bytes>,
};
trader.cancelSidecar(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
| Parameter |
Type |
Description |
| sidecar_id |
bytes |
|
This response has no parameters.
Trader.CloseAccount
Unary RPC
CloseAccount closes an account and returns the funds locked in that account to the connected lnd node's wallet.
# Close an existing account. An optional address can be provided which the
# funds of the account to close will be sent to, otherwise they are sent
# to an address under control of the connected lnd node.
$ pool accounts close [command options] trader_key sat_per_vbyte
# --trader_key value the trader key associated with the account to close
# --sat_per_vbyte value the fee rate expressed in sat/vbyte that should be used for the closing transaction (default: 0)
# --addr value an optional address which the funds of the account to close will be sent to
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.CloseAccountRequest(
trader_key=<bytes>,
output_with_fee=<OutputWithFee>,
outputs=<OutputsWithImplicitFee>,
)
>>> response = stub.CloseAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"close_txid": <bytes>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
trader_key: <bytes>,
output_with_fee: <OutputWithFee>,
outputs: <OutputsWithImplicitFee>,
};
trader.closeAccount(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "close_txid": <bytes>,
// }
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader key associated with the account that will be closed. |
| output_with_fee |
OutputWithFee |
A single output/address to which the remaining funds of the account will be sent to at the specified fee. If an address is not specified, then the funds are sent to an address the backing lnd node controls. |
| outputs |
OutputsWithImplicitFee |
The outputs to which the remaining funds of the account will be sent to. This should only be used when wanting to create two or more outputs, otherwise OutputWithFee should be used instead. The fee of the account's closing transaction is implicitly defined by the combined value of all outputs. |
| Parameter |
Type |
Description |
| close_txid |
bytes |
The hash of the closing transaction. |
Trader.DecodeSidecarTicket
Unary RPC
Decodes the base58 encoded sidecar ticket into its individual data fields for a more human-readable representation.
# Tries to decode the given ticket from the human readable (prefixed)
# base64 encoded version.
$ pool sidecar printticket ticket
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.SidecarTicket(
ticket=<string>,
)
>>> response = stub.DecodeSidecarTicket(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"id": <bytes>,
"version": <uint32>,
"state": <string>,
"offer_capacity": <uint64>,
"offer_push_amount": <uint64>,
"offer_lease_duration_blocks": <uint32>,
"offer_sign_pubkey": <bytes>,
"offer_signature": <bytes>,
"offer_auto": <bool>,
"recipient_node_pubkey": <bytes>,
"recipient_multisig_pubkey": <bytes>,
"recipient_multisig_pubkey_index": <uint32>,
"order_bid_nonce": <bytes>,
"order_signature": <bytes>,
"execution_pending_channel_id": <bytes>,
"encoded_ticket": <string>,
"offer_unannounced_channel": <bool>,
"offer_zero_conf_channel": <bool>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
ticket: <string>,
};
trader.decodeSidecarTicket(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "id": <bytes>,
// "version": <uint32>,
// "state": <string>,
// "offer_capacity": <uint64>,
// "offer_push_amount": <uint64>,
// "offer_lease_duration_blocks": <uint32>,
// "offer_sign_pubkey": <bytes>,
// "offer_signature": <bytes>,
// "offer_auto": <bool>,
// "recipient_node_pubkey": <bytes>,
// "recipient_multisig_pubkey": <bytes>,
// "recipient_multisig_pubkey_index": <uint32>,
// "order_bid_nonce": <bytes>,
// "order_signature": <bytes>,
// "execution_pending_channel_id": <bytes>,
// "encoded_ticket": <string>,
// "offer_unannounced_channel": <bool>,
// "offer_zero_conf_channel": <bool>,
// }
| Parameter |
Type |
Description |
| ticket |
string |
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. |
| Parameter |
Type |
Description |
| id |
bytes |
The unique, pseudorandom identifier of the ticket. |
| version |
uint32 |
The version of the ticket encoding format. |
| state |
string |
The state of the ticket. |
| offer_capacity |
uint64 |
The offered channel capacity in satoshis. |
| offer_push_amount |
uint64 |
The offered push amount in satoshis. |
| offer_lease_duration_blocks |
uint32 |
The offered lease duration in blocks. |
| offer_sign_pubkey |
bytes |
The public key the offer was signed with. |
| offer_signature |
bytes |
The signature over the offer's digest. |
| offer_auto |
bool |
Whether the offer was created with the automatic order creation flag. |
| recipient_node_pubkey |
bytes |
The recipient node's public identity key. |
| recipient_multisig_pubkey |
bytes |
The recipient node's channel multisig public key to be used for the sidecar channel. |
| recipient_multisig_pubkey_index |
uint32 |
The index used when deriving the above multisig pubkey. |
| order_bid_nonce |
bytes |
The nonce of the bid order created for this sidecar ticket. |
| order_signature |
bytes |
The signature over the order's digest, signed with the private key that corresponds to the offer_sign_pubkey. |
| execution_pending_channel_id |
bytes |
The pending channel ID of the sidecar channel during the execution phase. |
| encoded_ticket |
string |
The original, base58 encoded ticket. |
| offer_unannounced_channel |
bool |
If true, the channel acceptor for this ticket will expect an unannounced channel. |
| offer_zero_conf_channel |
bool |
If true, the channel acceptor for this ticket will expect a zero conf channel. |
Trader.DepositAccount
Unary RPC
DepositAccount adds more funds from the connected lnd node's wallet to an account.
# Deposit funds into an existing account.
$ pool accounts deposit [command options] trader_key amt sat_per_vbyte
# --trader_key value the hex-encoded trader key of the account to deposit funds into
# --amt value the amount to deposit into the account (default: 0)
# --sat_per_vbyte value the fee rate expressed in sat/vbyte that should be used for the deposit (default: 0)
# --expiry_height value the new block height which this account should expire at (default: 0)
# --expiry_blocks value the new relative height (from the current chain height) that the account should expire at (default: 0)
# --new_version value the new account version to use; version 0 means auto-decide dependent on lnd version; version 1 is a p2wsh account while version 2 is a p2tr account; version 2 requires lnd 0.15 or later (default: 0)
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.DepositAccountRequest(
trader_key=<bytes>,
amount_sat=<uint64>,
fee_rate_sat_per_kw=<uint64>,
absolute_expiry=<uint32>,
relative_expiry=<uint32>,
new_version=<AccountVersion>,
)
>>> response = stub.DepositAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"account": <Account>,
"deposit_txid": <bytes>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
trader_key: <bytes>,
amount_sat: <uint64>,
fee_rate_sat_per_kw: <uint64>,
absolute_expiry: <uint32>,
relative_expiry: <uint32>,
new_version: <AccountVersion>,
};
trader.depositAccount(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "account": <Account>,
// "deposit_txid": <bytes>,
// }
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader key associated with the account that funds will be deposited into. |
| amount_sat |
uint64 |
The amount in satoshis to deposit into the account. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the deposit transaction. |
| absolute_expiry |
uint32 |
The new absolute expiration height of the account. |
| relative_expiry |
uint32 |
The new relative expiration height of the account. |
| new_version |
AccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the deposit. |
| Parameter |
Type |
Description |
| account |
Account |
The state of the account after processing the deposit. |
| deposit_txid |
bytes |
The transaction used to deposit funds into the account. |
Trader.ExpectSidecarChannel
Unary RPC
ExpectSidecarChannel is step 4/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 recipient once the provider has submitted the bid order for the sidecar channel. From this point onwards the Pool trader daemon of both the provider as well as the recipient need to be online to receive and react to match making events from the server.
# Connect to the auctioneer and wait for a sidecar order to be matched and
# a channel being opened to us.
$ pool sidecar expectchannel ticket
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.ExpectSidecarChannelRequest(
ticket=<string>,
)
>>> response = stub.ExpectSidecarChannel(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
ticket: <string>,
};
trader.expectSidecarChannel(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
| Parameter |
Type |
Description |
| ticket |
string |
The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered". |
This response has no parameters.
Trader.GetInfo
Unary RPC
GetInfo returns general information about the state of the Pool trader daemon.
# Displays basic info about the current state of the Pool trader daemon
$ pool getinfo [arguments...]
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.GetInfoRequest()
>>> response = stub.GetInfo(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"version": <string>,
"accounts_total": <uint32>,
"accounts_active": <uint32>,
"accounts_active_expired": <uint32>,
"accounts_archived": <uint32>,
"orders_total": <uint32>,
"orders_active": <uint32>,
"orders_archived": <uint32>,
"current_block_height": <uint32>,
"batches_involved": <uint32>,
"node_rating": <NodeRating>,
"lsat_tokens": <uint32>,
"subscribed_to_auctioneer": <bool>,
"new_nodes_only": <bool>,
"market_info": <array MarketInfoEntry>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {}
trader.getInfo(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "version": <string>,
// "accounts_total": <uint32>,
// "accounts_active": <uint32>,
// "accounts_active_expired": <uint32>,
// "accounts_archived": <uint32>,
// "orders_total": <uint32>,
// "orders_active": <uint32>,
// "orders_archived": <uint32>,
// "current_block_height": <uint32>,
// "batches_involved": <uint32>,
// "node_rating": <NodeRating>,
// "lsat_tokens": <uint32>,
// "subscribed_to_auctioneer": <bool>,
// "new_nodes_only": <bool>,
// "market_info": <array MarketInfoEntry>,
// }
This request has no parameters.
| Parameter |
Type |
Description |
| version |
string |
The version of the Pool daemon that is running. |
| accounts_total |
uint32 |
The total number of accounts in the local database. |
| accounts_active |
uint32 |
The total number of accounts that are in an active, non-archived state, including expired accounts. |
| accounts_active_expired |
uint32 |
The total number of accounts that are active but have expired. |
| accounts_archived |
uint32 |
The total number of accounts that are in an archived/closed state. |
| orders_total |
uint32 |
The total number of orders in the local database. |
| orders_active |
uint32 |
The total number of active/pending orders that are still waiting for execution. |
| orders_archived |
uint32 |
The total number of orders that have been archived. |
| current_block_height |
uint32 |
The current block height as seen by the connected lnd node. |
| batches_involved |
uint32 |
The number of batches an account of this node was ever involved in. |
| node_rating |
NodeRating |
Our lnd node's rating as judged by the auctioneer server. |
| lsat_tokens |
uint32 |
The number of available LSAT tokens. |
| subscribed_to_auctioneer |
bool |
Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server. |
| new_nodes_only |
bool |
Indicates whether the global --newnodesonly command line flag or newnodesonly=true configuration parameter was set on the Pool trader daemon. |
| market_info |
array MarketInfoEntry |
A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest. |
Trader.GetLsatTokens
Unary RPC
GetLsatTokens returns all LSAT tokens the daemon ever paid for.
# Shows a list of all LSAT tokens that poold has paid for
$ pool listauth [arguments...]
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.TokensRequest()
>>> response = stub.GetLsatTokens(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"tokens": <array LsatToken>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {}
trader.getLsatTokens(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "tokens": <array LsatToken>,
// }
This request has no parameters.
| Parameter |
Type |
Description |
| tokens |
array LsatToken |
List of all tokens the daemon knows of, including old/expired tokens. |
Trader.InitAccount
Unary RPC
InitAccount creates a new account with the requested size and expiration, funding it from the wallet of the connected lnd node.
# Send the amount in satoshis specified by the amt argument to a
# new account.
$ pool accounts new [command options] amt [--expiry_height | --expiry_blocks]
# --amt value the amount in satoshis to create account for (default: 0)
# --expiry_height value the new block height which this account should expire at (default: 0)
# --expiry_blocks value the relative height (from the current chain height) that the account should expire at (default of 30 days equivalent in blocks) (default: 4320)
# --conf_target value the target number of blocks the on-chain account funding transaction should confirm within (default: 6)
# --sat_per_vbyte value the fee rate expressed in sat/vbyte that should be used for the account creation transaction (default: 0)
# --force skip account fee confirmation
# --version value the account version to use; version 0 means auto-decide dependent on lnd version; version 1 is a p2wsh account while version 2 is a p2tr account; version 2 requires lnd 0.15 or later (default: 0)
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.InitAccountRequest(
account_value=<uint64>,
absolute_height=<uint32>,
relative_height=<uint32>,
conf_target=<uint32>,
fee_rate_sat_per_kw=<uint64>,
initiator=<string>,
version=<AccountVersion>,
)
>>> response = stub.InitAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"trader_key": <bytes>,
"outpoint": <OutPoint>,
"value": <uint64>,
"available_balance": <uint64>,
"expiration_height": <uint32>,
"state": <AccountState>,
"latest_txid": <bytes>,
"version": <AccountVersion>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
account_value: <uint64>,
absolute_height: <uint32>,
relative_height: <uint32>,
conf_target: <uint32>,
fee_rate_sat_per_kw: <uint64>,
initiator: <string>,
version: <AccountVersion>,
};
trader.initAccount(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "trader_key": <bytes>,
// "outpoint": <OutPoint>,
// "value": <uint64>,
// "available_balance": <uint64>,
// "expiration_height": <uint32>,
// "state": <AccountState>,
// "latest_txid": <bytes>,
// "version": <AccountVersion>,
// }
| Parameter |
Type |
Description |
| account_value |
uint64 |
|
| absolute_height |
uint32 |
|
| relative_height |
uint32 |
|
| conf_target |
uint32 |
The target number of blocks that the transaction should be confirmed in. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the initial funding transaction. |
| initiator |
string |
An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI). |
| version |
AccountVersion |
The version of account to create. |
| Parameter |
Type |
Description |
| trader_key |
bytes |
The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer. |
| outpoint |
OutPoint |
The current outpoint associated with the account. This will change every time the account has been updated. |
| value |
uint64 |
The current total amount of satoshis in the account. |
| available_balance |
uint64 |
The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders. |
| expiration_height |
uint32 |
The height at which the account will expire. |
| state |
AccountState |
The current state of the account. |
| latest_txid |
bytes |
The hash of the account's latest transaction. |
| version |
AccountVersion |
The current version of the account. |
Trader.LeaseDurations
Unary RPC
LeaseDurations returns the current set of valid lease duration in the market as is, and also information w.r.t if the market is currently active.
# - returns the current active set of accepted lease durations for orders
$ pool auction leasedurations [arguments...]
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.LeaseDurationRequest()
>>> response = stub.LeaseDurations(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"lease_durations": <array LeaseDurationsEntry>,
"lease_duration_buckets": <array LeaseDurationBucketsEntry>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {}
trader.leaseDurations(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "lease_durations": <array LeaseDurationsEntry>,
// "lease_duration_buckets": <array LeaseDurationBucketsEntry>,
// }
This request has no parameters.
Trader.Leases
Unary RPC
Leases returns the list of channels that were either purchased or sold by the trader within the auction.
# 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.
$ pool auction leases [command options] [arguments...]
# --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
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.LeasesRequest(
batch_ids=<array bytes>,
accounts=<array bytes>,
)
>>> response = stub.Leases(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"leases": <array Lease>,
"total_amt_earned_sat": <uint64>,
"total_amt_paid_sat": <uint64>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
batch_ids: <array bytes>,
accounts: <array bytes>,
};
trader.leases(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "leases": <array Lease>,
// "total_amt_earned_sat": <uint64>,
// "total_amt_paid_sat": <uint64>,
// }
| Parameter |
Type |
Description |
| batch_ids |
array bytes |
An optional list of batches to retrieve the leases of. If empty, leases throughout all batches are returned. |
| accounts |
array bytes |
An optional list of accounts to retrieve the leases of. If empty, leases for all accounts are returned. |
| Parameter |
Type |
Description |
| leases |
array Lease |
The relevant list of leases purchased or sold within the auction. |
| total_amt_earned_sat |
uint64 |
The total amount of satoshis earned from the leases returned. |
| total_amt_paid_sat |
uint64 |
The total amount of satoshis paid for the leases returned. |
Trader.ListAccounts
Unary RPC
ListAccounts returns a list of all accounts known to the trader daemon and their current state.
# List all existing accounts.
$ pool accounts list [command options] [arguments...]
# --show_archived include accounts that are no longer active
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.ListAccountsRequest(
active_only=<bool>,
)
>>> response = stub.ListAccounts(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"accounts": <array Account>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
active_only: <bool>,
};
trader.listAccounts(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "accounts": <array Account>,
// }
| Parameter |
Type |
Description |
| active_only |
bool |
Only list accounts that are still active. |
Trader.ListOrders
Unary RPC
ListOrders returns a list of all active and archived orders that are currently known to the trader daemon.
# List all orders that are stored in the local order database
$ pool orders list [command options] [arguments...]
# --verbose show verbose output including events
# --show_archived include orders no longer active
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.ListOrdersRequest(
verbose=<bool>,
active_only=<bool>,
)
>>> response = stub.ListOrders(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"asks": <array Ask>,
"bids": <array Bid>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
verbose: <bool>,
active_only: <bool>,
};
trader.listOrders(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "asks": <array Ask>,
// "bids": <array Bid>,
// }
| Parameter |
Type |
Description |
| verbose |
bool |
Can be set to true to list the orders including all events, which can be very verbose. |
| active_only |
bool |
Only list orders that are still active. |
Trader.ListSidecars
Unary RPC
ListSidecars lists all sidecar tickets currently in the local database. This includes tickets offered by our node as well as tickets that our node is the recipient of. Optionally a ticket ID can be provided to filter the tickets.
# - list all sidecar tickets
$ pool sidecar list [arguments...]
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.ListSidecarsRequest(
sidecar_id=<bytes>,
)
>>> response = stub.ListSidecars(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"tickets": <array DecodedSidecarTicket>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
sidecar_id: <bytes>,
};
trader.listSidecars(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "tickets": <array DecodedSidecarTicket>,
// }
| Parameter |
Type |
Description |
| sidecar_id |
bytes |
The optional sidecar ID to filter for. If set, the result should either be a single ticket or no ticket in most cases. But because the ID is just 8 bytes and is randomly generated, there could be collisions, especially since tickets can also be crafted by a malicious party and given to any node. That's why the offer's public key is also used as an identifying element since that cannot easily be forged without also producing a valid signature. So an attacker cannot overwrite a ticket a node offered by themselves offering a ticket with the same ID and tricking the victim into registering that. Long story sort, there could be multiple tickets with the same ID but different offer public keys, which is why those keys should be checked as well. |
Trader.NextBatchInfo
Unary RPC
NextBatchInfo returns information about the next batch the auctioneer will perform.
# - returns information about the next batch the auctioneer will attempt to clear
$ pool auction nextbatchinfo [arguments...]
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.NextBatchInfoRequest()
>>> response = stub.NextBatchInfo(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"conf_target": <uint32>,
"fee_rate_sat_per_kw": <uint64>,
"clear_timestamp": <uint64>,
"auto_renew_extension_blocks": <uint32>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {}
trader.nextBatchInfo(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "conf_target": <uint32>,
// "fee_rate_sat_per_kw": <uint64>,
// "clear_timestamp": <uint64>,
// "auto_renew_extension_blocks": <uint32>,
// }
This request has no parameters.
| Parameter |
Type |
Description |
| conf_target |
uint32 |
The confirmation target the auctioneer will use for fee estimation of the next batch. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch. |
| clear_timestamp |
uint64 |
The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch. |
| auto_renew_extension_blocks |
uint32 |
The value used by the auctioneer to determine if an account expiry height needs to be extended after participating in a batch and for how long. |
Trader.NodeRatings
Unary RPC
Returns the Node Tier information for this target Lightning node, and other related ranking information.
# Returns the current Node Tier of a node, along with other
# information.
$ pool auction ratings [command options] [arguments...]
# --node_key value the node key to look up the rating for
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.NodeRatingRequest(
node_pubkeys=<array bytes>,
)
>>> response = stub.NodeRatings(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"node_ratings": <array NodeRating>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
node_pubkeys: <array bytes>,
};
trader.nodeRatings(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "node_ratings": <array NodeRating>,
// }
| Parameter |
Type |
Description |
| node_pubkeys |
array bytes |
The target node to obtain ratings information for. |
| Parameter |
Type |
Description |
| node_ratings |
array NodeRating |
A series of node ratings for each of the queried nodes. |
Trader.OfferSidecar
Unary RPC
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".
# 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.
$ pool sidecar offer [command options] [<full bid args> --auto] | capacity self_chan_balance lease_duration_blocks acct_key
# --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")
# --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
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.OfferSidecarRequest(
auto_negotiate=<bool>,
bid=<Bid>,
)
>>> response = stub.OfferSidecar(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"ticket": <string>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
auto_negotiate: <bool>,
bid: <Bid>,
};
trader.offerSidecar(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "ticket": <string>,
// }
| Parameter |
Type |
Description |
| auto_negotiate |
bool |
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. |
| bid |
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. |
| Parameter |
Type |
Description |
| ticket |
string |
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. |
Trader.QuoteAccount
Unary RPC
QuoteAccount gets a fee quote to fund an account of the given size with the given confirmation target. If the connected lnd wallet doesn't have enough balance to fund an account of the requested size, an error is returned.
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.QuoteAccountRequest(
account_value=<uint64>,
conf_target=<uint32>,
)
>>> response = stub.QuoteAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"miner_fee_rate_sat_per_kw": <uint64>,
"miner_fee_total": <uint64>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
account_value: <uint64>,
conf_target: <uint32>,
};
trader.quoteAccount(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "miner_fee_rate_sat_per_kw": <uint64>,
// "miner_fee_total": <uint64>,
// }
| Parameter |
Type |
Description |
| account_value |
uint64 |
|
| conf_target |
uint32 |
The target number of blocks that the transaction should be confirmed in. |
| Parameter |
Type |
Description |
| miner_fee_rate_sat_per_kw |
uint64 |
|
| miner_fee_total |
uint64 |
|
Trader.QuoteOrder
Unary RPC
QuoteOrder calculates the premium, execution fees and max batch fee rate for an order based on the given order parameters.
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.QuoteOrderRequest(
amt=<uint64>,
rate_fixed=<uint32>,
lease_duration_blocks=<uint32>,
max_batch_fee_rate_sat_per_kw=<uint64>,
min_units_match=<uint32>,
)
>>> response = stub.QuoteOrder(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"total_premium_sat": <uint64>,
"rate_per_block": <double>,
"rate_percent": <double>,
"total_execution_fee_sat": <uint64>,
"worst_case_chain_fee_sat": <uint64>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
amt: <uint64>,
rate_fixed: <uint32>,
lease_duration_blocks: <uint32>,
max_batch_fee_rate_sat_per_kw: <uint64>,
min_units_match: <uint32>,
};
trader.quoteOrder(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "total_premium_sat": <uint64>,
// "rate_per_block": <double>,
// "rate_percent": <double>,
// "total_execution_fee_sat": <uint64>,
// "worst_case_chain_fee_sat": <uint64>,
// }
| Parameter |
Type |
Description |
| amt |
uint64 |
Order amount in satoshis. |
| rate_fixed |
uint32 |
Fixed order rate in parts per billion. |
| lease_duration_blocks |
uint32 |
Required number of blocks that a channel opened as a result of this bid should be kept open. |
| max_batch_fee_rate_sat_per_kw |
uint64 |
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW). |
| min_units_match |
uint32 |
The minimum number of order units that must be matched per order pair. |
| Parameter |
Type |
Description |
| total_premium_sat |
uint64 |
The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees. |
| rate_per_block |
double |
The fixed order rate expressed as a fraction instead of parts per billion. |
| rate_percent |
double |
The fixed order rate expressed as a percentage instead of parts per billion. |
| total_execution_fee_sat |
uint64 |
The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order. |
| worst_case_chain_fee_sat |
uint64 |
The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation). |
Trader.RecoverAccounts
Unary RPC
RecoverAccounts queries the auction server for this trader daemon's accounts in case we lost our local account database.
# In case the data directory of the trader was corrupted or lost, this
# command can be used to ask the auction server to send back its view of
# the trader's accounts. This is possible as long as the connected lnd
# node is running with the same seed as when the accounts to recover were
# first created.
# NOTE: This command should only be used after data loss as it will fail
# if there already are open accounts in the trader's database.
# All open or pending orders of any recovered account will be canceled on
# the auctioneer's side and won't be restored in the trader's database.
$ pool accounts recover [command options] [arguments...]
# --full_client fetch the latest account state from the server. If false, the full process willrun locally, but it could take hours.
# --account_target value number of accounts that we are looking to recover, set higher if there were more than 20 accounts (default: 20)
# --auctioneer_key full_client Auctioneer's public key. Only used during full_client recoveries
# --height_hint full_client initial block height. Only used during full_client recoveries (default: 0)
# --bitcoin_host full_client bitcoind/btcd instance address. Only used during full_client recoveries
# --bitcoin_user full_client bitcoind/btcd user name. Only used during full_client recoveries
# --bitcoin_password full_client bitcoind/btcd password. Only used during full_client recoveries
# --bitcoin_httppostmode full_client Use HTTP POST mode? bitcoind only supports this mode. Only used during full_client recoveries
# --bitcoin_usetls full_client Use TLS to connect? bitcoind only supports non-TLS connections. Only used during full_client recoveries
# --bitcoin_tlspath full_client Path to btcd's TLS certificate, if TLS is enabled. Only used during full_client recoveries
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.RecoverAccountsRequest(
full_client=<bool>,
account_target=<uint32>,
auctioneer_key=<string>,
height_hint=<uint32>,
bitcoin_host=<string>,
bitcoin_user=<string>,
bitcoin_password=<string>,
bitcoin_httppostmode=<bool>,
bitcoin_usetls=<bool>,
bitcoin_tlspath=<string>,
)
>>> response = stub.RecoverAccounts(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"num_recovered_accounts": <uint32>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
full_client: <bool>,
account_target: <uint32>,
auctioneer_key: <string>,
height_hint: <uint32>,
bitcoin_host: <string>,
bitcoin_user: <string>,
bitcoin_password: <string>,
bitcoin_httppostmode: <bool>,
bitcoin_usetls: <bool>,
bitcoin_tlspath: <string>,
};
trader.recoverAccounts(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "num_recovered_accounts": <uint32>,
// }
| Parameter |
Type |
Description |
| full_client |
bool |
Recover the latest account states without interacting with the Lightning Labs server. |
| account_target |
uint32 |
Number of accounts that we are trying to recover. Used during the full_client recovery process. |
| auctioneer_key |
string |
Auctioneer's public key. Used during the full_client recovery process. This field should be left empty for testnet/mainnet, its value is already hardcoded in our codebase. |
| height_hint |
uint32 |
Initial block height. We won't try to look for any account with an expiry height smaller than this value. Used during the full_client recovery process. |
| bitcoin_host |
string |
bitcoind/btcd instance address. Used during the full_client recovery process. |
| bitcoin_user |
string |
bitcoind/btcd user name. Used during the full_client recovery process. |
| bitcoin_password |
string |
bitcoind/btcd password. Used during the full_client recovery process. |
| bitcoin_httppostmode |
bool |
Use HTTP POST mode? bitcoind only supports this mode. Used during the full_client recovery process. |
| bitcoin_usetls |
bool |
Use TLS to connect? bitcoind only supports non-TLS connections. Used during the full_client recovery process. |
| bitcoin_tlspath |
string |
Path to btcd's TLS certificate, if TLS is enabled. Used during the full_client recovery process. |
| Parameter |
Type |
Description |
| num_recovered_accounts |
uint32 |
The number of accounts that were recovered. |
Trader.RegisterSidecar
Unary RPC
RegisterSidecarRequest is step 2/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 recipient. The result is a sidecar ticket with the recipient's node information and channel funding multisig pubkey filled in. The ticket returned by this call will have the state "registered".
# Registers a sidecar ticket for an incoming sidecar channel with the node
# and adds its recipient information to it, resulting in an updated ticket
# that needs to be handed back to the provider.
$ pool sidecar register ticket
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.RegisterSidecarRequest(
ticket=<string>,
auto_negotiate=<bool>,
)
>>> response = stub.RegisterSidecar(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"ticket": <string>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
ticket: <string>,
auto_negotiate: <bool>,
};
trader.registerSidecar(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "ticket": <string>,
// }
| Parameter |
Type |
Description |
| ticket |
string |
The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered". |
| auto_negotiate |
bool |
If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down. |
| Parameter |
Type |
Description |
| ticket |
string |
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. |
Trader.RenewAccount
Unary RPC
RenewAccount renews the expiration of an account.
# Renews the expiration of an account. This will broadcast a chain
# transaction as the expiry is enforced within the account output script.
# The fee rate of said transaction must be specified.
$ pool accounts renew [command options] trader_key sat_per_vbyte [--expiry_height | --expiry_blocks]
# --trader_key value the hex-encoded trader key of the account to renew
# --sat_per_vbyte value the fee rate expressed in sat/vbyte that should be used for the renewal transaction (default: 0)
# --expiry_height value the new block height which this account should expire at (default: 0)
# --expiry_blocks value the new relative height (from the current chain height) that the account should expire at (default of 30 days equivalent in blocks) (default: 4320)
# --new_version value the new account version to use; version 0 means auto-decide dependent on lnd version; version 1 is a p2wsh account while version 2 is a p2tr account; version 2 requires lnd 0.15 or later (default: 0)
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.RenewAccountRequest(
account_key=<bytes>,
absolute_expiry=<uint32>,
relative_expiry=<uint32>,
fee_rate_sat_per_kw=<uint64>,
new_version=<AccountVersion>,
)
>>> response = stub.RenewAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"account": <Account>,
"renewal_txid": <bytes>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
account_key: <bytes>,
absolute_expiry: <uint32>,
relative_expiry: <uint32>,
fee_rate_sat_per_kw: <uint64>,
new_version: <AccountVersion>,
};
trader.renewAccount(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "account": <Account>,
// "renewal_txid": <bytes>,
// }
| Parameter |
Type |
Description |
| account_key |
bytes |
The key associated with the account to renew. |
| absolute_expiry |
uint32 |
The new absolute expiration height of the account. |
| relative_expiry |
uint32 |
The new relative expiration height of the account. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the renewal transaction. |
| new_version |
AccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the renewal. |
| Parameter |
Type |
Description |
| account |
Account |
The state of the account after processing the renewal. |
| renewal_txid |
bytes |
The transaction used to renew the expiration of the account. |
Trader.StopDaemon
Unary RPC
Stop gracefully shuts down the Pool trader daemon.
# Sends the stop command to the Pool trader daemon to initiate a graceful shutdown
$ pool stop [arguments...]
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.StopDaemonRequest()
>>> response = stub.StopDaemon(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {}
trader.stopDaemon(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// }
This request has no parameters.
This response has no parameters.
Trader.SubmitOrder
Unary RPC
SubmitOrder creates a new ask or bid order and submits for the given account and submits it to the auction server for matching.
# ('--self_chan_balance').
$ bid obtain channel liquidity
# --help, -h show help
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.SubmitOrderRequest(
ask=<Ask>,
bid=<Bid>,
initiator=<string>,
)
>>> response = stub.SubmitOrder(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"invalid_order": <InvalidOrder>,
"accepted_order_nonce": <bytes>,
"updated_sidecar_ticket": <string>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
ask: <Ask>,
bid: <Bid>,
initiator: <string>,
};
trader.submitOrder(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "invalid_order": <InvalidOrder>,
// "accepted_order_nonce": <bytes>,
// "updated_sidecar_ticket": <string>,
// }
| Parameter |
Type |
Description |
| ask |
Ask |
|
| bid |
Bid |
|
| initiator |
string |
An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for submitting the order (pool CLI, LiT UI, other 3rd party UI). |
| Parameter |
Type |
Description |
| invalid_order |
InvalidOrder |
Order failed with the given reason. |
| accepted_order_nonce |
bytes |
The order nonce of the accepted order. |
| updated_sidecar_ticket |
string |
In case a bid order was submitted for a sidecar ticket, that ticket is updated with the new state and bid order nonce. |
Trader.WithdrawAccount
Unary RPC
WithdrawAccount splits off parts of the account balance into the specified outputs while recreating the account with a reduced balance.
# Withdraw funds from an existing account to a supported address.
$ pool accounts withdraw [command options] trader_key amt addr sat_per_vbyte
# --trader_key value the hex-encoded trader key of the account to withdraw funds from
# --addr value the address the withdrawn funds should go to
# --amt value the amount that will be sent to the address and withdrawn from the account (default: 0)
# --sat_per_vbyte value the fee rate expressed in sat/vbyte that should be used for the withdrawal (default: 0)
# --expiry_height value the new block height which this account should expire at (default: 0)
# --expiry_blocks value the new relative height (from the current chain height) that the account should expire at (default: 0)
# --new_version value the new account version to use; version 0 means auto-decide dependent on lnd version; version 1 is a p2wsh account while version 2 is a p2tr account; version 2 requires lnd 0.15 or later (default: 0)
>>> 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
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('POOL_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:12010', ssl_creds)
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.WithdrawAccountRequest(
trader_key=<bytes>,
outputs=<array Output>,
fee_rate_sat_per_kw=<uint64>,
absolute_expiry=<uint32>,
relative_expiry=<uint32>,
new_version=<AccountVersion>,
)
>>> response = stub.WithdrawAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"account": <Account>,
"withdraw_txid": <bytes>,
}
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("POOL_DIR/regtest/pool.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('POOL_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const trader = new poolrpc.Trader('localhost:12010', creds);
let request = {
trader_key: <bytes>,
outputs: <array Output>,
fee_rate_sat_per_kw: <uint64>,
absolute_expiry: <uint32>,
relative_expiry: <uint32>,
new_version: <AccountVersion>,
};
trader.withdrawAccount(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "account": <Account>,
// "withdraw_txid": <bytes>,
// }
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader key associated with the account that funds will be withdrawed from. |
| outputs |
array Output |
The outputs we'll withdraw funds from the account into. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the withdrawal transaction. |
| absolute_expiry |
uint32 |
The new absolute expiration height of the account. |
| relative_expiry |
uint32 |
The new relative expiration height of the account. |
| new_version |
AccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the withdrawal. |
| Parameter |
Type |
Description |
| account |
Account |
The state of the account after processing the withdrawal. |
| withdraw_txid |
bytes |
The transaction used to withdraw funds from the account. |
gRPC Messages
poolrpc.Account
| Parameter |
Type |
Description |
| trader_key |
bytes |
The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer. |
| outpoint |
OutPoint |
The current outpoint associated with the account. This will change every time the account has been updated. |
| value |
uint64 |
The current total amount of satoshis in the account. |
| available_balance |
uint64 |
The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders. |
| expiration_height |
uint32 |
The height at which the account will expire. |
| state |
AccountState |
The current state of the account. |
| latest_txid |
bytes |
The hash of the account's latest transaction. |
| version |
AccountVersion |
The current version of the account. |
poolrpc.AccountModificationFee
| Parameter |
Type |
Description |
| action |
string |
Modification action type. |
| txid |
string |
Transaction ID. |
| block_height |
int32 |
Action transaction block height. |
| timestamp |
int64 |
Action transaction timestamp. |
| output_amount |
int64 |
Action transaction output amount. |
| fee_null |
bool |
A flag which is true if fee value has not been set, and is otherwise false. |
| fee_value |
int64 |
Action transaction fee value. |
poolrpc.AccountModificationFeesRequest
This message has no parameters.
poolrpc.AccountModificationFeesResponse
| Parameter |
Type |
Description |
| accounts |
array AccountsEntry |
A map from account key to an ordered list of account modification fees. |
poolrpc.AccountModificationFeesResponse.AccountsEntry
poolrpc.Ask
| Parameter |
Type |
Description |
| details |
Order |
The common fields shared between both ask and bid order types. |
| lease_duration_blocks |
uint32 |
The number of blocks the liquidity provider is willing to provide the channel funds for. |
| version |
uint32 |
The version of the order format that is used. Will be increased once new features are added. |
| announcement_constraints |
ChannelAnnouncementConstraints |
The constraints for selling the liquidity based on channel discoverability. |
| confirmation_constraints |
ChannelConfirmationConstraints |
The constraints for selling the liquidity based on the number of blocks before considering the channel confirmed. |
poolrpc.AuctionFeeRequest
This message has no parameters.
poolrpc.AuctionFeeResponse
| Parameter |
Type |
Description |
| execution_fee |
ExecutionFee |
The execution fee charged per matched order. |
poolrpc.Bid
| Parameter |
Type |
Description |
| details |
Order |
The common fields shared between both ask and bid order types. |
| lease_duration_blocks |
uint32 |
Required number of blocks that a channel opened as a result of this bid should be kept open. |
| version |
uint32 |
The version of the order format that is used. Will be increased once new features are added. |
| min_node_tier |
NodeTier |
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. |
| self_chan_balance |
uint64 |
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. |
| sidecar_ticket |
string |
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. |
| unannounced_channel |
bool |
Signals if this bid is interested in an announced or unannounced channel. |
| zero_conf_channel |
bool |
Signals if this bid is interested in a zero conf channel or not. |
poolrpc.BumpAccountFeeRequest
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader key associated with the account that will have its fee bumped. |
| fee_rate_sat_per_kw |
uint64 |
The new fee rate, in satoshis per kw, to use for the child of the account transaction. |
poolrpc.BumpAccountFeeResponse
This message has no parameters.
poolrpc.CancelOrderRequest
| Parameter |
Type |
Description |
| order_nonce |
bytes |
|
poolrpc.CancelOrderResponse
This message has no parameters.
poolrpc.CancelSidecarRequest
| Parameter |
Type |
Description |
| sidecar_id |
bytes |
|
poolrpc.CancelSidecarResponse
This message has no parameters.
poolrpc.CloseAccountRequest
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader key associated with the account that will be closed. |
| output_with_fee |
OutputWithFee |
A single output/address to which the remaining funds of the account will be sent to at the specified fee. If an address is not specified, then the funds are sent to an address the backing lnd node controls. |
| outputs |
OutputsWithImplicitFee |
The outputs to which the remaining funds of the account will be sent to. This should only be used when wanting to create two or more outputs, otherwise OutputWithFee should be used instead. The fee of the account's closing transaction is implicitly defined by the combined value of all outputs. |
poolrpc.CloseAccountResponse
| Parameter |
Type |
Description |
| close_txid |
bytes |
The hash of the closing transaction. |
poolrpc.DecodedSidecarTicket
| Parameter |
Type |
Description |
| id |
bytes |
The unique, pseudorandom identifier of the ticket. |
| version |
uint32 |
The version of the ticket encoding format. |
| state |
string |
The state of the ticket. |
| offer_capacity |
uint64 |
The offered channel capacity in satoshis. |
| offer_push_amount |
uint64 |
The offered push amount in satoshis. |
| offer_lease_duration_blocks |
uint32 |
The offered lease duration in blocks. |
| offer_sign_pubkey |
bytes |
The public key the offer was signed with. |
| offer_signature |
bytes |
The signature over the offer's digest. |
| offer_auto |
bool |
Whether the offer was created with the automatic order creation flag. |
| recipient_node_pubkey |
bytes |
The recipient node's public identity key. |
| recipient_multisig_pubkey |
bytes |
The recipient node's channel multisig public key to be used for the sidecar channel. |
| recipient_multisig_pubkey_index |
uint32 |
The index used when deriving the above multisig pubkey. |
| order_bid_nonce |
bytes |
The nonce of the bid order created for this sidecar ticket. |
| order_signature |
bytes |
The signature over the order's digest, signed with the private key that corresponds to the offer_sign_pubkey. |
| execution_pending_channel_id |
bytes |
The pending channel ID of the sidecar channel during the execution phase. |
| encoded_ticket |
string |
The original, base58 encoded ticket. |
| offer_unannounced_channel |
bool |
If true, the channel acceptor for this ticket will expect an unannounced channel. |
| offer_zero_conf_channel |
bool |
If true, the channel acceptor for this ticket will expect a zero conf channel. |
poolrpc.DepositAccountRequest
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader key associated with the account that funds will be deposited into. |
| amount_sat |
uint64 |
The amount in satoshis to deposit into the account. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the deposit transaction. |
| absolute_expiry |
uint32 |
The new absolute expiration height of the account. |
| relative_expiry |
uint32 |
The new relative expiration height of the account. |
| new_version |
AccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the deposit. |
poolrpc.DepositAccountResponse
| Parameter |
Type |
Description |
| account |
Account |
The state of the account after processing the deposit. |
| deposit_txid |
bytes |
The transaction used to deposit funds into the account. |
poolrpc.ExpectSidecarChannelRequest
| Parameter |
Type |
Description |
| ticket |
string |
The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered". |
poolrpc.ExpectSidecarChannelResponse
This message has no parameters.
poolrpc.GetInfoRequest
This message has no parameters.
poolrpc.GetInfoResponse
| Parameter |
Type |
Description |
| version |
string |
The version of the Pool daemon that is running. |
| accounts_total |
uint32 |
The total number of accounts in the local database. |
| accounts_active |
uint32 |
The total number of accounts that are in an active, non-archived state, including expired accounts. |
| accounts_active_expired |
uint32 |
The total number of accounts that are active but have expired. |
| accounts_archived |
uint32 |
The total number of accounts that are in an archived/closed state. |
| orders_total |
uint32 |
The total number of orders in the local database. |
| orders_active |
uint32 |
The total number of active/pending orders that are still waiting for execution. |
| orders_archived |
uint32 |
The total number of orders that have been archived. |
| current_block_height |
uint32 |
The current block height as seen by the connected lnd node. |
| batches_involved |
uint32 |
The number of batches an account of this node was ever involved in. |
| node_rating |
NodeRating |
Our lnd node's rating as judged by the auctioneer server. |
| lsat_tokens |
uint32 |
The number of available LSAT tokens. |
| subscribed_to_auctioneer |
bool |
Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server. |
| new_nodes_only |
bool |
Indicates whether the global --newnodesonly command line flag or newnodesonly=true configuration parameter was set on the Pool trader daemon. |
| market_info |
array MarketInfoEntry |
A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest. |
poolrpc.GetInfoResponse.MarketInfoEntry
| Parameter |
Type |
Description |
| key |
uint32 |
|
| value |
MarketInfo |
|
poolrpc.InitAccountRequest
| Parameter |
Type |
Description |
| account_value |
uint64 |
|
| absolute_height |
uint32 |
|
| relative_height |
uint32 |
|
| conf_target |
uint32 |
The target number of blocks that the transaction should be confirmed in. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the initial funding transaction. |
| initiator |
string |
An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI). |
| version |
AccountVersion |
The version of account to create. |
poolrpc.Lease
| Parameter |
Type |
Description |
| channel_point |
OutPoint |
The outpoint of the channel created. |
| channel_amt_sat |
uint64 |
The amount, in satoshis, of the channel created. |
| channel_duration_blocks |
uint32 |
The intended duration, in blocks, of the channel created. |
| channel_lease_expiry |
uint32 |
The absolute height that this channel lease expires. |
| premium_sat |
uint64 |
The premium, in satoshis, either paid or received for the offered liquidity. |
| execution_fee_sat |
uint64 |
The execution fee, in satoshis, charged by the auctioneer for the channel created. |
| chain_fee_sat |
uint64 |
The fee, in satoshis, charged by the auctioneer for the batch execution transaction that created this lease. |
| clearing_rate_price |
uint64 |
The actual fixed rate expressed in parts per billionth this lease was bought/sold at. |
| order_fixed_rate |
uint64 |
The actual fixed rate of the bid/ask, this should always be 'better' than the clearing_rate_price. |
| order_nonce |
bytes |
The order executed that resulted in the channel created. |
| matched_order_nonce |
bytes |
The unique identifier for the order that was matched with that resulted in the channel created. |
| purchased |
bool |
Whether this channel was purchased from another trader or not. |
| channel_remote_node_key |
bytes |
The pubkey of the node that this channel was bought/sold from. |
| channel_node_tier |
NodeTier |
The tier of the node that this channel was bought/sold from. |
| self_chan_balance |
uint64 |
The self channel balance that was pushed to the recipient. |
| sidecar_channel |
bool |
Whether the channel was leased as a sidecar channel (bid orders only). |
poolrpc.LeaseDurationRequest
This message has no parameters.
poolrpc.LeaseDurationResponse
poolrpc.LeaseDurationResponse.LeaseDurationBucketsEntry
poolrpc.LeaseDurationResponse.LeaseDurationsEntry
| Parameter |
Type |
Description |
| key |
uint32 |
|
| value |
bool |
|
poolrpc.LeasesRequest
| Parameter |
Type |
Description |
| batch_ids |
array bytes |
An optional list of batches to retrieve the leases of. If empty, leases throughout all batches are returned. |
| accounts |
array bytes |
An optional list of accounts to retrieve the leases of. If empty, leases for all accounts are returned. |
poolrpc.LeasesResponse
| Parameter |
Type |
Description |
| leases |
array Lease |
The relevant list of leases purchased or sold within the auction. |
| total_amt_earned_sat |
uint64 |
The total amount of satoshis earned from the leases returned. |
| total_amt_paid_sat |
uint64 |
The total amount of satoshis paid for the leases returned. |
poolrpc.ListAccountsRequest
| Parameter |
Type |
Description |
| active_only |
bool |
Only list accounts that are still active. |
poolrpc.ListAccountsResponse
poolrpc.ListOfAccountModificationFees
poolrpc.ListOrdersRequest
| Parameter |
Type |
Description |
| verbose |
bool |
Can be set to true to list the orders including all events, which can be very verbose. |
| active_only |
bool |
Only list orders that are still active. |
poolrpc.ListOrdersResponse
poolrpc.ListSidecarsRequest
| Parameter |
Type |
Description |
| sidecar_id |
bytes |
The optional sidecar ID to filter for. If set, the result should either be a single ticket or no ticket in most cases. But because the ID is just 8 bytes and is randomly generated, there could be collisions, especially since tickets can also be crafted by a malicious party and given to any node. That's why the offer's public key is also used as an identifying element since that cannot easily be forged without also producing a valid signature. So an attacker cannot overwrite a ticket a node offered by themselves offering a ticket with the same ID and tricking the victim into registering that. Long story sort, there could be multiple tickets with the same ID but different offer public keys, which is why those keys should be checked as well. |
poolrpc.ListSidecarsResponse
poolrpc.LsatToken
| Parameter |
Type |
Description |
| base_macaroon |
bytes |
The base macaroon that was baked by the auth server. |
| payment_hash |
bytes |
The payment hash of the payment that was paid to obtain the token. |
| payment_preimage |
bytes |
The preimage of the payment hash, knowledge of this is proof that the payment has been paid. If the preimage is set to all zeros, this means the payment is still pending and the token is not yet fully valid. |
| amount_paid_msat |
int64 |
The amount of millisatoshis that was paid to get the token. |
| routing_fee_paid_msat |
int64 |
The amount of millisatoshis paid in routing fee to pay for the token. |
| time_created |
int64 |
The creation time of the token as UNIX timestamp in seconds. |
| expired |
bool |
Indicates whether the token is expired or still valid. |
| storage_name |
string |
Identifying attribute of this token in the store. Currently represents the file name of the token where it's stored on the file system. |
poolrpc.MatchEvent
| Parameter |
Type |
Description |
| match_state |
MatchState |
The state of the match making process the order went through. |
| units_filled |
uint32 |
The number of units that would be (or were) filled with this match. |
| matched_order |
bytes |
The nonce of the order we were matched to. |
| reject_reason |
MatchRejectReason |
The reason why the trader daemon rejected the order. Is only set if match_state is set to REJECTED. |
poolrpc.NextBatchInfoRequest
This message has no parameters.
poolrpc.NextBatchInfoResponse
| Parameter |
Type |
Description |
| conf_target |
uint32 |
The confirmation target the auctioneer will use for fee estimation of the next batch. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch. |
| clear_timestamp |
uint64 |
The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch. |
| auto_renew_extension_blocks |
uint32 |
The value used by the auctioneer to determine if an account expiry height needs to be extended after participating in a batch and for how long. |
poolrpc.NodeRatingRequest
| Parameter |
Type |
Description |
| node_pubkeys |
array bytes |
The target node to obtain ratings information for. |
poolrpc.NodeRatingResponse
| Parameter |
Type |
Description |
| node_ratings |
array NodeRating |
A series of node ratings for each of the queried nodes. |
poolrpc.OfferSidecarRequest
| Parameter |
Type |
Description |
| auto_negotiate |
bool |
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. |
| bid |
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. |
poolrpc.Order
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader's account key of the account that is used for the order. |
| rate_fixed |
uint32 |
Fixed order rate in parts per billion. |
| amt |
uint64 |
Order amount in satoshis. |
| max_batch_fee_rate_sat_per_kw |
uint64 |
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW). |
| order_nonce |
bytes |
Order nonce, acts as unique order identifier. |
| state |
OrderState |
The state the order currently is in. |
| units |
uint32 |
The number of order units the amount corresponds to. |
| units_unfulfilled |
uint32 |
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. |
| reserved_value_sat |
uint64 |
The value reserved from the account by this order to ensure the account can pay execution and chain fees in case it gets matched. |
| creation_timestamp_ns |
uint64 |
The unix timestamp in nanoseconds the order was first created/submitted. |
| events |
array OrderEvent |
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. |
| min_units_match |
uint32 |
The minimum number of order units that must be matched per order pair. |
| channel_type |
OrderChannelType |
The channel type to use for the resulting matched channels. |
| allowed_node_ids |
array bytes |
List of nodes that will be allowed to match with our order. Incompatible with the not_allowed_node_ids field. |
| not_allowed_node_ids |
array bytes |
List of nodes that won't be allowed to match with our order. Incompatible with the allowed_node_ids field. |
| auction_type |
AuctionType |
Auction type where this order must be considered during the matching. |
| is_public |
bool |
Flag used to signal that this order can be shared in public market places. |
poolrpc.OrderEvent
| Parameter |
Type |
Description |
| timestamp_ns |
int64 |
The unix timestamp in nanoseconds the event was emitted at. This is the primary key of the event and is unique across the database. |
| event_str |
string |
The human readable representation of the event. |
| state_change |
UpdatedEvent |
The order was updated in the database. |
| matched |
MatchEvent |
The order was involved in a match making attempt. |
poolrpc.Output
| Parameter |
Type |
Description |
| value_sat |
uint64 |
The value, in satoshis, of the output. |
| address |
string |
The address corresponding to the output. |
poolrpc.OutputWithFee
| Parameter |
Type |
Description |
| address |
string |
The address corresponding to the output. |
| conf_target |
uint32 |
The target number of blocks that the transaction should be confirmed in. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the withdrawal transaction. |
poolrpc.OutputsWithImplicitFee
poolrpc.QuoteAccountRequest
| Parameter |
Type |
Description |
| account_value |
uint64 |
|
| conf_target |
uint32 |
The target number of blocks that the transaction should be confirmed in. |
poolrpc.QuoteAccountResponse
| Parameter |
Type |
Description |
| miner_fee_rate_sat_per_kw |
uint64 |
|
| miner_fee_total |
uint64 |
|
poolrpc.QuoteOrderRequest
| Parameter |
Type |
Description |
| amt |
uint64 |
Order amount in satoshis. |
| rate_fixed |
uint32 |
Fixed order rate in parts per billion. |
| lease_duration_blocks |
uint32 |
Required number of blocks that a channel opened as a result of this bid should be kept open. |
| max_batch_fee_rate_sat_per_kw |
uint64 |
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW). |
| min_units_match |
uint32 |
The minimum number of order units that must be matched per order pair. |
poolrpc.QuoteOrderResponse
| Parameter |
Type |
Description |
| total_premium_sat |
uint64 |
The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees. |
| rate_per_block |
double |
The fixed order rate expressed as a fraction instead of parts per billion. |
| rate_percent |
double |
The fixed order rate expressed as a percentage instead of parts per billion. |
| total_execution_fee_sat |
uint64 |
The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order. |
| worst_case_chain_fee_sat |
uint64 |
The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation). |
poolrpc.RecoverAccountsRequest
| Parameter |
Type |
Description |
| full_client |
bool |
Recover the latest account states without interacting with the Lightning Labs server. |
| account_target |
uint32 |
Number of accounts that we are trying to recover. Used during the full_client recovery process. |
| auctioneer_key |
string |
Auctioneer's public key. Used during the full_client recovery process. This field should be left empty for testnet/mainnet, its value is already hardcoded in our codebase. |
| height_hint |
uint32 |
Initial block height. We won't try to look for any account with an expiry height smaller than this value. Used during the full_client recovery process. |
| bitcoin_host |
string |
bitcoind/btcd instance address. Used during the full_client recovery process. |
| bitcoin_user |
string |
bitcoind/btcd user name. Used during the full_client recovery process. |
| bitcoin_password |
string |
bitcoind/btcd password. Used during the full_client recovery process. |
| bitcoin_httppostmode |
bool |
Use HTTP POST mode? bitcoind only supports this mode. Used during the full_client recovery process. |
| bitcoin_usetls |
bool |
Use TLS to connect? bitcoind only supports non-TLS connections. Used during the full_client recovery process. |
| bitcoin_tlspath |
string |
Path to btcd's TLS certificate, if TLS is enabled. Used during the full_client recovery process. |
poolrpc.RecoverAccountsResponse
| Parameter |
Type |
Description |
| num_recovered_accounts |
uint32 |
The number of accounts that were recovered. |
poolrpc.RegisterSidecarRequest
| Parameter |
Type |
Description |
| ticket |
string |
The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered". |
| auto_negotiate |
bool |
If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down. |
poolrpc.RenewAccountRequest
| Parameter |
Type |
Description |
| account_key |
bytes |
The key associated with the account to renew. |
| absolute_expiry |
uint32 |
The new absolute expiration height of the account. |
| relative_expiry |
uint32 |
The new relative expiration height of the account. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the renewal transaction. |
| new_version |
AccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the renewal. |
poolrpc.RenewAccountResponse
| Parameter |
Type |
Description |
| account |
Account |
The state of the account after processing the renewal. |
| renewal_txid |
bytes |
The transaction used to renew the expiration of the account. |
poolrpc.SidecarTicket
| Parameter |
Type |
Description |
| ticket |
string |
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. |
poolrpc.StopDaemonRequest
This message has no parameters.
poolrpc.StopDaemonResponse
This message has no parameters.
poolrpc.SubmitOrderRequest
| Parameter |
Type |
Description |
| ask |
Ask |
|
| bid |
Bid |
|
| initiator |
string |
An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for submitting the order (pool CLI, LiT UI, other 3rd party UI). |
poolrpc.SubmitOrderResponse
| Parameter |
Type |
Description |
| invalid_order |
InvalidOrder |
Order failed with the given reason. |
| accepted_order_nonce |
bytes |
The order nonce of the accepted order. |
| updated_sidecar_ticket |
string |
In case a bid order was submitted for a sidecar ticket, that ticket is updated with the new state and bid order nonce. |
poolrpc.TokensRequest
This message has no parameters.
poolrpc.TokensResponse
| Parameter |
Type |
Description |
| tokens |
array LsatToken |
List of all tokens the daemon knows of, including old/expired tokens. |
poolrpc.UpdatedEvent
| Parameter |
Type |
Description |
| previous_state |
OrderState |
The state of the order previous to the change. This is what the state changed from. |
| new_state |
OrderState |
The new state of the order after the change. This is what the state changed to. |
| units_filled |
uint32 |
The units that were filled at the time of the event. |
poolrpc.WithdrawAccountRequest
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader key associated with the account that funds will be withdrawed from. |
| outputs |
array Output |
The outputs we'll withdraw funds from the account into. |
| fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kw, to use for the withdrawal transaction. |
| absolute_expiry |
uint32 |
The new absolute expiration height of the account. |
| relative_expiry |
uint32 |
The new relative expiration height of the account. |
| new_version |
AccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the withdrawal. |
poolrpc.WithdrawAccountResponse
| Parameter |
Type |
Description |
| account |
Account |
The state of the account after processing the withdrawal. |
| withdraw_txid |
bytes |
The transaction used to withdraw funds from the account. |
poolrpc.CipherBox
poolrpc.CipherBoxAuth
poolrpc.CipherBoxDesc
| Parameter |
Type |
Description |
| stream_id |
bytes |
|
poolrpc.CipherChallenge
This message has no parameters.
poolrpc.CipherError
This message has no parameters.
poolrpc.CipherInitResp
| Parameter |
Type |
Description |
| success |
CipherSuccess |
CipherSuccess is returned if the initialization of the cipher box was successful. |
| challenge |
CipherChallenge |
CipherChallenge is returned if the authentication mechanism was revoked or needs to be refreshed. |
| error |
CipherError |
CipherError is returned if the authentication mechanism failed to validate. |
poolrpc.CipherSuccess
poolrpc.DelCipherBoxResp
This message has no parameters.
poolrpc.PoolAccountAuth
| Parameter |
Type |
Description |
| acct_key |
bytes |
The account key being used to authenticate. |
| stream_sig |
bytes |
A valid signature over the stream ID being used. |
poolrpc.SidecarAuth
| Parameter |
Type |
Description |
| ticket |
string |
A valid sidecar ticket that has been signed (offered) by a Pool account in the active state. |
poolrpc.AccountCommitment
| Parameter |
Type |
Description |
| commit_hash |
bytes |
The SHA256 hash of the trader's account key and a 32 byte random nonce. commit_hash = SHA256(accountPubKey |
| batch_version |
uint32 |
The batch verification protocol version the client is using. Clients that don't use the latest version will be declined to connect and participate in an auction. The user should then be informed that a software update is required. |
poolrpc.AccountDiff
| Parameter |
Type |
Description |
| ending_balance |
uint64 |
The final balance of the account after the executed batch. |
| ending_state |
AccountState |
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. |
| outpoint_index |
int32 |
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. |
| trader_key |
bytes |
The trader's account key this diff is referring to. |
| new_expiry |
uint32 |
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. |
| new_version |
uint32 |
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. |
poolrpc.AccountRecovery
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader's account key of the account to recover. |
poolrpc.AccountSubscription
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader's account key of the account to subscribe to. |
| commit_nonce |
bytes |
The random 32 byte nonce the trader used to create the commitment hash. |
| auth_sig |
bytes |
The signature over the auth_hash which is the hash of the commitment and challenge. The signature is created with the trader's account key they committed to. auth_hash = SHA256(SHA256(accountPubKey |
poolrpc.AskSnapshot
| Parameter |
Type |
Description |
| version |
uint32 |
The version of the order. |
| lease_duration_blocks |
uint32 |
The period of time the channel will survive for. |
| rate_fixed |
uint32 |
The true bid price of the order in parts per billion. |
| chan_type |
OrderChannelType |
The channel type to be created. |
poolrpc.AuctionAccount
| Parameter |
Type |
Description |
| value |
uint64 |
The value of the account in satoshis. Must match the amount of the account_point output. |
| expiry |
uint32 |
The block height at which the account should expire. |
| trader_key |
bytes |
The trader's account key. |
| auctioneer_key |
bytes |
The long term auctioneer's account key. |
| batch_key |
bytes |
The current batch key used to create the account output. |
| state |
AuctionAccountState |
The current state of the account as the auctioneer sees it. |
| height_hint |
uint32 |
The block height of the last change to the account's output. Can be used to scan the chain for the output's spend state more efficiently. |
| outpoint |
OutPoint |
Transaction output of the account. Depending on the state of the account, this output might have been spent. |
| latest_tx |
bytes |
The latest transaction of an account. This is only known by the auctioneer after the account has met its initial funding confirmation. |
| version |
uint32 |
The account version. Will be set to 0 for legacy (non-taproot) accounts. |
poolrpc.BatchSnapshotRequest
| Parameter |
Type |
Description |
| batch_id |
bytes |
The unique identifier of the batch encoded as a compressed pubkey. |
poolrpc.BatchSnapshotResponse
| Parameter |
Type |
Description |
| version |
uint32 |
The version of the batch. |
| batch_id |
bytes |
The unique identifier of the batch. |
| prev_batch_id |
bytes |
The unique identifier of the prior batch. |
| clearing_price_rate |
uint32 |
Deprecated, use matched_markets. |
| matched_orders |
array MatchedOrderSnapshot |
Deprecated, use matched_markets. |
| batch_tx_id |
string |
The txid of the batch transaction. |
| batch_tx |
bytes |
The batch transaction including all witness data. |
| batch_tx_fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kiloweight, of the batch transaction. |
| creation_timestamp_ns |
uint64 |
The unix timestamp in nanoseconds the batch was made. |
| matched_markets |
array MatchedMarketsEntry |
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price. |
poolrpc.BatchSnapshotResponse.MatchedMarketsEntry
poolrpc.BatchSnapshotsRequest
| Parameter |
Type |
Description |
| start_batch_id |
bytes |
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. |
| num_batches_back |
uint32 |
The number of batches to return at most, including the start batch. |
poolrpc.BatchSnapshotsResponse
poolrpc.BidSnapshot
| Parameter |
Type |
Description |
| version |
uint32 |
The version of the order. |
| lease_duration_blocks |
uint32 |
The period of time the matched channel should be allocated for. |
| rate_fixed |
uint32 |
The true bid price of the order in parts per billion. |
| chan_type |
OrderChannelType |
The channel type to be created. |
poolrpc.CancelOrder
| Parameter |
Type |
Description |
| order_nonce |
bytes |
|
poolrpc.ChannelInfo
| Parameter |
Type |
Description |
| type |
ChannelType |
The identifying type of the channel. |
| local_node_key |
bytes |
The node's identifying public key. |
| remote_node_key |
bytes |
The remote node's identifying public key. |
| local_payment_base_point |
bytes |
The node's base public key used within the non-delayed pay-to-self output on the commitment transaction. |
| remote_payment_base_point |
bytes |
RemotePaymentBasePoint is the remote node's base public key used within the non-delayed pay-to-self output on the commitment transaction. |
poolrpc.ClientAuctionMessage
| Parameter |
Type |
Description |
| commit |
AccountCommitment |
Signal the intent to receive updates about a certain account and start by sending the commitment part of the authentication handshake. This is step 1 of the 3-way handshake. |
| subscribe |
AccountSubscription |
Subscribe to update and interactive order execution events for account given and all its orders. Contains the final signature and is step 3 of the 3-way authentication handshake. |
| accept |
OrderMatchAccept |
Accept the orders to be matched. |
| reject |
OrderMatchReject |
Reject a whole batch. |
| sign |
OrderMatchSign |
The channel funding negotiations with the matched peer were successful and the inputs to spend from the accounts are now signed. |
| recover |
AccountRecovery |
The trader has lost its database and is trying to recover their accounts. This message can be sent after the successful completion of the 3-way authentication handshake where it will be established if the account exists on the auctioneer's side. This message must only be sent if the auctioneer knows of the account, otherwise it will regard it as a critical error and terminate the connection. |
poolrpc.ExecutionFee
| Parameter |
Type |
Description |
| base_fee |
uint64 |
The base fee in satoshis charged per order, regardless of the matched size. |
| fee_rate |
uint64 |
The fee rate in parts per million. |
poolrpc.InvalidOrder
| Parameter |
Type |
Description |
| order_nonce |
bytes |
|
| fail_reason |
FailReason |
|
| fail_string |
string |
|
poolrpc.MarketInfo
| Parameter |
Type |
Description |
| num_asks |
array TierValue |
The number of open/pending ask orders per node tier. |
| num_bids |
array TierValue |
The number of open/pending bid orders per node tier. |
| ask_open_interest_units |
array TierValue |
The total number of open/unmatched units in open/pending ask orders per node tier. |
| bid_open_interest_units |
array TierValue |
The total number of open/unmatched units in open/pending bid orders per node tier. |
poolrpc.MarketInfo.TierValue
| Parameter |
Type |
Description |
| tier |
NodeTier |
|
| value |
uint32 |
|
poolrpc.MarketInfoRequest
This message has no parameters.
poolrpc.MarketInfoResponse
| Parameter |
Type |
Description |
| markets |
array MarketsEntry |
A map of all markets identified by their lease duration and the current set of statistics. |
poolrpc.MarketInfoResponse.MarketsEntry
| Parameter |
Type |
Description |
| key |
uint32 |
|
| value |
MarketInfo |
|
poolrpc.MatchedAsk
| Parameter |
Type |
Description |
| ask |
ServerAsk |
The ask order that was matched against. |
| units_filled |
uint32 |
The number of units that were filled from/by this matched order. |
poolrpc.MatchedBid
| Parameter |
Type |
Description |
| bid |
ServerBid |
The ask order that was matched against. |
| units_filled |
uint32 |
The number of units that were filled from/by this matched order. |
poolrpc.MatchedMarket
| Parameter |
Type |
Description |
| matched_orders |
array MatchedOrdersEntry |
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. |
| clearing_price_rate |
uint32 |
The uniform clearing price rate in parts per billion that was used for this batch. |
poolrpc.MatchedMarket.MatchedOrdersEntry
poolrpc.MatchedMarketSnapshot
| Parameter |
Type |
Description |
| matched_orders |
array MatchedOrderSnapshot |
The set of all orders matched in the batch. |
| clearing_price_rate |
uint32 |
The uniform clearing price rate in parts per billion that was used for this batch. |
poolrpc.MatchedOrder
| Parameter |
Type |
Description |
| matched_bids |
array MatchedBid |
The bids the trader's own order was matched against. This list is empty if the trader's order was a bid order itself. |
| matched_asks |
array MatchedAsk |
The asks the trader's own order was matched against. This list is empty if the trader's order was an ask order itself. |
poolrpc.MatchedOrderSnapshot
| Parameter |
Type |
Description |
| ask |
AskSnapshot |
The full ask order that was matched. |
| bid |
BidSnapshot |
The full bid order that was matched. |
| matching_rate |
uint32 |
The fixed rate premium that was matched, expressed in parts-ber-billion. |
| total_sats_cleared |
uint64 |
The total number of satoshis that were bought. |
| units_matched |
uint32 |
The total number of units that were matched. |
poolrpc.NodeAddress
| Parameter |
Type |
Description |
| network |
string |
|
| addr |
string |
|
poolrpc.NodeRating
| Parameter |
Type |
Description |
| node_pubkey |
bytes |
The pubkey for the node these ratings belong to. |
| node_tier |
NodeTier |
The tier of the target node. |
poolrpc.OrderMatchAccept
| Parameter |
Type |
Description |
| batch_id |
bytes |
The batch ID this acceptance message refers to. Must be set to avoid out-of- order responses from disrupting the batching process. |
poolrpc.OrderMatchFinalize
| Parameter |
Type |
Description |
| batch_id |
bytes |
The unique identifier of the finalized batch. |
| batch_txid |
bytes |
The final transaction ID of the published batch transaction. |
poolrpc.OrderMatchPrepare
| Parameter |
Type |
Description |
| matched_orders |
array MatchedOrdersEntry |
Deprecated, use matched_markets. |
| clearing_price_rate |
uint32 |
Deprecated, use matched_markets. |
| charged_accounts |
array AccountDiff |
A list of the user's own accounts that are being spent by the matched orders. The list contains the differences that would be applied by the server when executing the orders. |
| execution_fee |
ExecutionFee |
The fee parameters used to calculate the execution fees. |
| batch_transaction |
bytes |
The batch transaction with all non-witness data. |
| fee_rate_sat_per_kw |
uint64 |
Fee rate of the batch transaction, expressed in satoshis per 1000 weight units (sat/kW). |
| fee_rebate_sat |
uint64 |
Fee rebate in satoshis, offered if another batch participant wants to pay more fees for a faster confirmation. |
| batch_id |
bytes |
The 32 byte unique identifier of this batch. |
| batch_version |
uint32 |
The batch verification protocol version the server is using. Clients that don't support this version MUST return an OrderMatchAccept message with an empty list of orders so the batch can continue. The user should then be informed that a software update is required. |
| matched_markets |
array MatchedMarketsEntry |
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price. |
| batch_height_hint |
uint32 |
The earliest absolute height in the chain in which the batch transaction can be found within. This will be used by traders to base off their absolute channel lease maturity height. |
poolrpc.OrderMatchPrepare.MatchedMarketsEntry
poolrpc.OrderMatchPrepare.MatchedOrdersEntry
poolrpc.OrderMatchReject
| Parameter |
Type |
Description |
| batch_id |
bytes |
The ID of the batch to reject. |
| reason |
string |
The reason/error string for the rejection. |
| reason_code |
RejectReason |
The reason as a code. |
| rejected_orders |
array RejectedOrdersEntry |
The map of order nonces the trader was matched with but doesn't accept. The map contains the other trader's order nonces and the reason for rejecting them. This can be a subset of the whole list of orders presented as matches if the trader only wants to reject some of them. This map is only considered by the auctioneer if the main reason_code is set to PARTIAL_REJECT. Otherwise it is assumed that the whole batch was faulty for some reason and that the trader rejects all orders contained. The auctioneer will only accept a certain number of these partial rejects before a trader's account is removed completely from the current batch. Abusing this functionality can also lead to a ban of the trader. The order nonces are hex encoded strings because the protobuf map doesn't allow raw bytes to be the map key type. |
poolrpc.OrderMatchReject.RejectedOrdersEntry
| Parameter |
Type |
Description |
| key |
string |
|
| value |
OrderReject |
|
poolrpc.OrderMatchSign
| Parameter |
Type |
Description |
| batch_id |
bytes |
The ID of the batch that the signatures are meant for. |
| account_sigs |
array AccountSigsEntry |
A map with the signatures to spend the accounts being spent in a batch transaction. The map key corresponds to the trader's account key of the account in the batch transaction. The account key/ID has to be hex encoded into a string because protobuf doesn't allow bytes as a map key data type. For version 1 (Taproot enabled) accounts, this merely represents a partial MuSig2 signature that can be combined into a full signature by the auction server by adding its own partial signature. A set of nonces will be provided by the trader for each v1 account to allow finalizing the MuSig2 signing session. |
| channel_infos |
array ChannelInfosEntry |
The information for each channel created as part of a batch that's submitted to the auctioneer to ensure they can properly enforce a channel's service lifetime. Entries are indexed by the string representation of a channel's outpoint. |
| trader_nonces |
array TraderNoncesEntry |
A set of 66-byte nonces for each version 1 (Taproot enabled) account. The nonces can be used to produce a MuSig2 partial signature to spend the account using the key spend path, which is a MuSig2 combined key of the auctioneer key and the trader key. |
poolrpc.OrderMatchSign.AccountSigsEntry
| Parameter |
Type |
Description |
| key |
string |
|
| value |
bytes |
|
poolrpc.OrderMatchSign.ChannelInfosEntry
| Parameter |
Type |
Description |
| key |
string |
|
| value |
ChannelInfo |
|
poolrpc.OrderMatchSign.TraderNoncesEntry
| Parameter |
Type |
Description |
| key |
string |
|
| value |
bytes |
|
poolrpc.OrderMatchSignBegin
| Parameter |
Type |
Description |
| batch_id |
bytes |
The 32 byte unique identifier of this batch. |
| server_nonces |
array ServerNoncesEntry |
A set of 66-byte nonces for each version 1 (Taproot enabled) account. The nonces can be used to produce a MuSig2 partial signature to spend the account using the key spend path, which is a MuSig2 combined key of the auctioneer key and the trader key. |
| prev_outputs |
array TxOut |
The full list of UTXO information for each of the inputs being spent. This is required when spending one or more Taproot enabled (account version 1) outputs. |
poolrpc.OrderMatchSignBegin.ServerNoncesEntry
| Parameter |
Type |
Description |
| key |
string |
|
| value |
bytes |
|
poolrpc.OrderReject
| Parameter |
Type |
Description |
| reason |
string |
The reason/error string for the rejection. |
| reason_code |
OrderRejectReason |
The reason as a code. |
poolrpc.OutPoint
| Parameter |
Type |
Description |
| txid |
bytes |
Raw bytes representing the transaction id. |
| output_index |
uint32 |
The index of the output on the transaction. |
poolrpc.RelevantBatch
| Parameter |
Type |
Description |
| version |
uint32 |
The version of the batch. |
| id |
bytes |
The unique identifier of the batch. |
| charged_accounts |
array AccountDiff |
The set of modifications that should be applied to the requested accounts as a result of this batch. |
| matched_orders |
array MatchedOrdersEntry |
Deprecated, use matched_markets. |
| clearing_price_rate |
uint32 |
Deprecated, use matched_markets. |
| execution_fee |
ExecutionFee |
The fee parameters used to calculate the execution fees. |
| transaction |
bytes |
The batch transaction including all witness data. |
| fee_rate_sat_per_kw |
uint64 |
Fee rate of the batch transaction, expressed in satoshis per 1000 weight units (sat/kW). |
| creation_timestamp_ns |
uint64 |
The unix timestamp in nanoseconds the batch was made. |
| matched_markets |
array MatchedMarketsEntry |
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price. |
poolrpc.RelevantBatch.MatchedMarketsEntry
poolrpc.RelevantBatch.MatchedOrdersEntry
poolrpc.RelevantBatchRequest
| Parameter |
Type |
Description |
| id |
bytes |
The unique identifier of the batch. |
| accounts |
array bytes |
The set of accounts the trader is interested in retrieving information for within the batch. Each account is identified by its trader key. |
poolrpc.ReserveAccountRequest
| Parameter |
Type |
Description |
| account_value |
uint64 |
The desired value of the account in satoshis. |
| account_expiry |
uint32 |
The block height at which the account should expire. |
| trader_key |
bytes |
The trader's account key. |
| version |
uint32 |
The account version. Must be set to 0 for legacy (non-taproot) accounts. |
poolrpc.ReserveAccountResponse
| Parameter |
Type |
Description |
| auctioneer_key |
bytes |
The base key of the auctioneer. This key should be tweaked with the trader's per-batch tweaked key to obtain the corresponding per-batch tweaked auctioneer key. Or, in case of the version 1, Taproot enabled account, the trader and auctioneer key will be combined into a MuSig2 combined key that is static throughout the lifetime of the account. The on-chain uniqueness of the generated output will be ensured by the merkle root hash that is applied as a tweak to the MuSig2 combined internal key. The merkle root hash is either the hash of the timeout script path (which uses the trader key tweaked with the per-batch key) directly or the root of a tree with one leaf that is the timeout script path and a leaf that is a Taro commitment (which is a root hash by itself). |
| initial_batch_key |
bytes |
The initial per-batch key to be used for the account. For every cleared batch that the account participates in, this key will be incremented by the base point of its curve, resulting in a new key for both the trader and auctioneer in every batch. |
poolrpc.ServerAsk
| Parameter |
Type |
Description |
| details |
ServerOrder |
The common fields shared between both ask and bid order types. |
| lease_duration_blocks |
uint32 |
The number of blocks the liquidity provider is willing to provide the channel funds for. |
| version |
uint32 |
The version of the order format that is used. Will be increased once new features are added. |
| announcement_constraints |
ChannelAnnouncementConstraints |
The constraints for selling the liquidity based on channel discoverability. |
| confirmation_constraints |
ChannelConfirmationConstraints |
The constraints for selling the liquidity based on the number of blocks before considering the channel confirmed. |
poolrpc.ServerAuctionMessage
| Parameter |
Type |
Description |
| challenge |
ServerChallenge |
Step 2 of the 3-way authentication handshake. Contains the authentication challenge. Subscriptions sent by the trader must sign the message SHA256(SHA256(accountPubKey |
| success |
SubscribeSuccess |
The trader has subscribed to account updates successfully, the 3-way authentication handshake completed normally. |
| error |
SubscribeError |
An error occurred during any part of the communication. The trader should inspect the error code and act accordingly. |
| prepare |
OrderMatchPrepare |
The auctioneer has matched a set of orders into a batch and now instructs the traders to validate the batch and prepare for order execution. Because traders have the possibility of backing out of a batch, multiple of these messages with the SAME batch_id can be sent. |
| sign |
OrderMatchSignBegin |
This message is sent after all traders send back an OrderMatchAccept method. It signals that the traders should execute their local funding protocol, then send signatures for their account inputs. |
| finalize |
OrderMatchFinalize |
All traders have accepted and signed the batch and the final transaction was broadcast. |
| account |
AuctionAccount |
The answer to a trader's request for account recovery. This message contains all information that is needed to restore the account to working order on the trader side. |
poolrpc.ServerBid
| Parameter |
Type |
Description |
| details |
ServerOrder |
The common fields shared between both ask and bid order types. |
| lease_duration_blocks |
uint32 |
Required number of blocks that a channel opened as a result of this bid should be kept open. |
| version |
uint32 |
The version of the order format that is used. Will be increased once new features are added. |
| min_node_tier |
NodeTier |
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. |
| self_chan_balance |
uint64 |
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. |
| is_sidecar_channel |
bool |
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. |
| unannounced_channel |
bool |
Signals if this bid is interested in an announced or unannounced channel. |
| zero_conf_channel |
bool |
Signals if this bid is interested in a zero conf channel or not. |
poolrpc.ServerCancelOrderRequest
| Parameter |
Type |
Description |
| order_nonce_preimage |
bytes |
The preimage to the order's unique nonce. |
poolrpc.ServerCancelOrderResponse
This message has no parameters.
poolrpc.ServerChallenge
| Parameter |
Type |
Description |
| challenge |
bytes |
The unique challenge for each stream that has to be signed with the trader's account key for each account subscription. |
| commit_hash |
bytes |
The commit hash the challenge was created for. |
poolrpc.ServerInitAccountRequest
| Parameter |
Type |
Description |
| account_point |
OutPoint |
Transaction output of the account. Has to be unspent and be a P2WSH of the account script below. The amount must also exactly correspond to the account value below. |
| account_script |
bytes |
The script used to create the account point. For version 1 (Taproot enabled) accounts this represents the 32-byte (x-only) Taproot public key with the combined MuSig2 key of the auctioneer's key and the trader's key with the expiry script path applied as a single tapscript leaf. |
| account_value |
uint64 |
The value of the account in satoshis. Must match the amount of the account_point output. |
| account_expiry |
uint32 |
The block height at which the account should expire. |
| trader_key |
bytes |
The trader's account key. |
| user_agent |
string |
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 |
| version |
uint32 |
The account version. Must be set to 0 for legacy (non-taproot) accounts. |
poolrpc.ServerInitAccountResponse
This message has no parameters.
| Parameter |
Type |
Description |
| outpoint |
OutPoint |
The outpoint that the input corresponds to. |
| sig_script |
bytes |
The signature script required by the input. This only applies to NP2WKH inputs. |
poolrpc.ServerModifyAccountRequest
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader's account key of the account to be modified. |
| new_inputs |
array ServerInput |
An additional set of inputs that can be included in the spending transaction of an account. These can be used to deposit more funds into an account. These must be under control of the backing lnd node's wallet. |
| new_outputs |
array ServerOutput |
An additional set of outputs that can be included in the spending transaction of an account. These can be used to withdraw funds from an account. |
| new_params |
NewAccountParameters |
The new parameters to apply for the account. |
| trader_nonces |
bytes |
A set of 66-byte nonces for each version 1 (Taproot enabled) account. The nonces can be used to produce a MuSig2 partial signature to spend the account using the key spend path, which is a MuSig2 combined key of the auctioneer key and the trader key. |
| prev_outputs |
array TxOut |
The full list of UTXO information for each of the inputs being spent. This is required when spending a Taproot enabled (account version 1) output or when adding additional Taproot inputs. |
poolrpc.ServerModifyAccountRequest.NewAccountParameters
| Parameter |
Type |
Description |
| value |
uint64 |
The new value of the account. |
| expiry |
uint32 |
The new expiry of the account as an absolute height. |
| version |
uint32 |
The new version of the account. |
poolrpc.ServerModifyAccountResponse
| Parameter |
Type |
Description |
| account_sig |
bytes |
The auctioneer's signature that allows a trader to broadcast a transaction spending from an account output. For version 1 (Taproot enabled) accounts, this merely represents a partial MuSig2 signature that can be combined into a full signature by the trader daemon by adding its own partial signature. A set of nonces will be provided by the server (in case this is a v1 account) to allow finalizing the MuSig2 signing session. |
| server_nonces |
bytes |
An optional set of 66-byte nonces for a version 1 (Taproot enabled) account spend. The nonces can be used to produce a MuSig2 partial signature to spend the account using the key spend path, which is a MuSig2 combined key of the auctioneer key and the trader key. |
poolrpc.ServerNodeRatingRequest
| Parameter |
Type |
Description |
| node_pubkeys |
array bytes |
The target node to obtain ratings information for. |
poolrpc.ServerNodeRatingResponse
| Parameter |
Type |
Description |
| node_ratings |
array NodeRating |
A series of node ratings for each of the queried nodes. |
poolrpc.ServerOrder
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader's account key of the account to use for the order. |
| rate_fixed |
uint32 |
Fixed order rate in parts per billion. |
| amt |
uint64 |
Order amount in satoshis. |
| min_chan_amt |
uint64 |
|
| order_nonce |
bytes |
Order nonce of 32 byte length, acts as unique order identifier. |
| order_sig |
bytes |
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. |
| multi_sig_key |
bytes |
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. |
| node_pub |
bytes |
The pubkey of the node creating the order. |
| node_addr |
array NodeAddress |
The network addresses of the node creating the order. |
| channel_type |
OrderChannelType |
The type of the channel that should be opened. |
| max_batch_fee_rate_sat_per_kw |
uint64 |
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/kW). |
| allowed_node_ids |
array bytes |
List of nodes that will be allowed to match with our order. Incompatible with the not_allowed_node_ids field. |
| not_allowed_node_ids |
array bytes |
List of nodes that won't be allowed to match with our order. Incompatible with the allowed_node_ids field. |
| auction_type |
AuctionType |
Auction type where this order must be considered during the matching. |
| is_public |
bool |
Flag used to signal that this order can be shared in public market places. |
poolrpc.ServerOrderStateRequest
| Parameter |
Type |
Description |
| order_nonce |
bytes |
|
poolrpc.ServerOrderStateResponse
| Parameter |
Type |
Description |
| state |
OrderState |
The state the order currently is in. |
| units_unfulfilled |
uint32 |
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. |
poolrpc.ServerOutput
| Parameter |
Type |
Description |
| value |
uint64 |
The value, in satoshis, of the output. |
| script |
bytes |
The script of the output to send the value to. |
poolrpc.ServerSubmitOrderRequest
| Parameter |
Type |
Description |
| ask |
ServerAsk |
Submit an ask order. |
| bid |
ServerBid |
Submit a bid order. |
| user_agent |
string |
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 |
poolrpc.ServerSubmitOrderResponse
| Parameter |
Type |
Description |
| invalid_order |
InvalidOrder |
Order failed with the given reason. |
| accepted |
bool |
Order was accepted. |
poolrpc.SubscribeError
| Parameter |
Type |
Description |
| error |
string |
The string representation of the subscription error. |
| error_code |
Error |
The error code of the subscription error. |
| trader_key |
bytes |
The trader's account key this error is referring to. This is not set if the error code is SERVER_SHUTDOWN as that error is only sent once per connection and not per individual subscription. |
| account_reservation |
AuctionAccount |
The auctioneer's partial account information as it was stored when creating the reservation. This is only set if the error code is INCOMPLETE_ACCOUNT_RESERVATION. Only the fields value, expiry, trader_key, auctioneer_key, batch_key and height_hint will be set in that case. |
poolrpc.SubscribeSuccess
| Parameter |
Type |
Description |
| trader_key |
bytes |
The trader's account key this message is referring to. |
poolrpc.TermsRequest
This message has no parameters.
poolrpc.TermsResponse
| Parameter |
Type |
Description |
| max_account_value |
uint64 |
The maximum account size in satoshis currently allowed by the auctioneer. |
| max_order_duration_blocks |
uint32 |
Deprecated, use explicit order duration from lease_duration_buckets. |
| execution_fee |
ExecutionFee |
The execution fee charged per matched order. |
| lease_durations |
array LeaseDurationsEntry |
Deprecated, use lease_duration_buckets. |
| next_batch_conf_target |
uint32 |
The confirmation target to use for fee estimation of the next batch. |
| next_batch_fee_rate_sat_per_kw |
uint64 |
The fee rate, in satoshis per kiloweight, estimated to use for the next batch. |
| next_batch_clear_timestamp |
uint64 |
The absolute unix timestamp at which the auctioneer will attempt to clear the next batch. |
| lease_duration_buckets |
array LeaseDurationBucketsEntry |
The set of lease durations the market is currently accepting and the state the duration buckets currently are in. |
| auto_renew_extension_blocks |
uint32 |
The value used by the auctioneer to determine if an account expiry height needs to be extended after participating in a batch and for how long. |
poolrpc.TermsResponse.LeaseDurationBucketsEntry
poolrpc.TermsResponse.LeaseDurationsEntry
| Parameter |
Type |
Description |
| key |
uint32 |
|
| value |
bool |
|
poolrpc.TxOut
| Parameter |
Type |
Description |
| value |
uint64 |
The value of the transaction output in satoshis. |
| pk_script |
bytes |
The public key script of the output. |
gRPC Enums
AccountState
| Name |
Value |
Description |
| OUTPUT_RECREATED |
0 |
|
| OUTPUT_DUST_EXTENDED_OFFCHAIN |
1 |
|
| OUTPUT_DUST_ADDED_TO_FEES |
2 |
|
| OUTPUT_FULLY_SPENT |
3 |
|
AccountVersion
| Name |
Value |
Description |
| ACCOUNT_VERSION_LND_DEPENDENT |
0 |
Let the version of lnd decide. If a version of lnd >= 0.15.0-beta is detected then a Taproot account is created. For earlier versions a legacy account is created. |
| ACCOUNT_VERSION_LEGACY |
1 |
A legacy SegWit v0 p2wsh account with a single script. |
| ACCOUNT_VERSION_TAPROOT |
2 |
A Taproot enabled account with MuSig2 combined internal key and the expiry script as a single tap script leaf. |
MatchRejectReason
| Name |
Value |
Description |
| NONE |
0 |
No reject occurred, this is the default value. |
| SERVER_MISBEHAVIOR |
1 |
The client didn't come up with the same result as the server and is rejecting the batch because of that. |
| BATCH_VERSION_MISMATCH |
2 |
The client doesn't support the current batch verification version the server is using. |
| PARTIAL_REJECT_COLLATERAL |
3 |
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. |
| PARTIAL_REJECT_DUPLICATE_PEER |
4 |
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. |
| PARTIAL_REJECT_CHANNEL_FUNDING_FAILED |
5 |
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. |
MatchState
| Name |
Value |
Description |
| PREPARE |
0 |
The OrderMatchPrepare message from the auctioneer was received initially. |
| ACCEPTED |
1 |
The OrderMatchPrepare message from the auctioneer was processed successfully and the batch was accepted. |
| REJECTED |
2 |
The order was rejected by the trader daemon, either as an answer to a OrderMatchSignBegin or OrderMatchFinalize message from the auctioneer. |
| SIGNED |
3 |
The OrderMatchSignBegin message from the auctioneer was processed successfully. |
| FINALIZED |
4 |
The OrderMatchFinalize message from the auctioneer was processed successfully. |
AuctionAccountState
| Name |
Value |
Description |
| STATE_PENDING_OPEN |
0 |
The account's funding transaction is not yet confirmed on-chain. |
| STATE_OPEN |
1 |
The account is fully open and confirmed on-chain. |
| STATE_EXPIRED |
2 |
The account is still open but the CLTV expiry has passed and the trader can close it without the auctioneer's key. Orders for accounts in this state won't be accepted. |
| STATE_PENDING_UPDATE |
3 |
The account was modified by a deposit or withdrawal and is currently waiting for the modifying transaction to confirm. |
| STATE_CLOSED |
4 |
The account is closed. The auctioneer doesn't track whether the closing transaction is already confirmed on-chain or not. |
| STATE_PENDING_BATCH |
5 |
The account has recently participated in a batch and is not yet confirmed. |
| STATE_EXPIRED_PENDING_UPDATE |
6 |
The account has reached the expiration height while it had a pending update that hasn't yet confirmed. This allows accounts to be renewed once confirmed and expired. |
AuctionType
| Name |
Value |
Description |
| AUCTION_TYPE_BTC_INBOUND_LIQUIDITY |
0 |
Default auction type where the bidder is paying for getting bitcoin inbound liqiudity from the asker. |
| AUCTION_TYPE_BTC_OUTBOUND_LIQUIDITY |
1 |
Auction type where the bidder is paying the asker to accept a channel (bitcoin outbound liquidity) from the bidder. |
ChannelAnnouncementConstraints
Channel announcement constraints for matched channels.
| Name |
Value |
Description |
| ANNOUNCEMENT_NO_PREFERENCE |
0 |
|
| ONLY_ANNOUNCED |
1 |
|
| ONLY_UNANNOUNCED |
2 |
|
ChannelConfirmationConstraints
Channel confirmation constraints for matched channels.
| Name |
Value |
Description |
| CONFIRMATION_NO_PREFERENCE |
0 |
|
| ONLY_CONFIRMED |
1 |
|
| ONLY_ZEROCONF |
2 |
|
ChannelType
| Name |
Value |
Description |
| TWEAKLESS |
0 |
The channel supports static to_remote keys. |
| ANCHORS |
1 |
The channel uses an anchor-based commitment. |
| SCRIPT_ENFORCED_LEASE |
2 |
The channel build upon the anchor-based commitment and requires an additional CLTV of the channel lease maturity on any commitment and HTLC outputs that pay directly to the channel initiator (the seller). |
DurationBucketState
| Name |
Value |
Description |
| NO_MARKET |
0 |
NO_MARKET indicates that this bucket doesn't actually exist, in that no market is present for this market. |
| MARKET_CLOSED |
1 |
MARKET_CLOSED indicates that this market exists, but that it isn't currently running. |
| ACCEPTING_ORDERS |
2 |
ACCEPTING_ORDERS indicates that we're accepting orders for this bucket, but not yet clearing for this duration. |
| MARKET_OPEN |
3 |
MARKET_OPEN indicates that we're accepting orders, and fully clearing the market for this duration. |
FailReason
| Name |
Value |
Description |
| INVALID_AMT |
0 |
|
NodeTier
| Name |
Value |
Description |
| TIER_DEFAULT |
0 |
The default node tier. This value will be determined at run-time by the current order version. |
| TIER_0 |
1 |
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". |
| TIER_1 |
2 |
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. |
OrderChannelType
| Name |
Value |
Description |
| ORDER_CHANNEL_TYPE_UNKNOWN |
0 |
Used to set defaults when a trader doesn't specify a channel type. |
| ORDER_CHANNEL_TYPE_PEER_DEPENDENT |
1 |
The channel type will vary per matched channel based on the features shared between its participants. |
| ORDER_CHANNEL_TYPE_SCRIPT_ENFORCED |
2 |
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. |
RejectReason
| Name |
Value |
Description |
| UNKNOWN |
0 |
The reason cannot be mapped to a specific code. |
| SERVER_MISBEHAVIOR |
1 |
The client didn't come up with the same result as the server and is rejecting the batch because of that. |
| BATCH_VERSION_MISMATCH |
2 |
The client doesn't support the current batch verification version the server is using. |
| PARTIAL_REJECT |
3 |
The client rejects some of the orders, not the full batch. When this code is set, the rejected_orders map must be set. |
OrderRejectReason
| Name |
Value |
Description |
| DUPLICATE_PEER |
0 |
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. |
| CHANNEL_FUNDING_FAILED |
1 |
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. |
OrderState
| Name |
Value |
Description |
| ORDER_SUBMITTED |
0 |
|
| ORDER_CLEARED |
1 |
|
| ORDER_PARTIALLY_FILLED |
2 |
|
| ORDER_EXECUTED |
3 |
|
| ORDER_CANCELED |
4 |
|
| ORDER_EXPIRED |
5 |
|
| ORDER_FAILED |
6 |
|
Error
| Name |
Value |
Description |
| UNKNOWN |
0 |
The error cannot be mapped to a specific code. |
| SERVER_SHUTDOWN |
1 |
The server is shutting down for maintenance. Traders should close the long-lived stream/connection and try to connect again after some time. |
| ACCOUNT_DOES_NOT_EXIST |
2 |
The account the trader tried to subscribe to does not exist in the auctioneer's database. |
| INCOMPLETE_ACCOUNT_RESERVATION |
3 |
The account the trader tried to subscribe to was never completed and a reservation for it is still pending. |
Pool REST API Reference
Welcome to the REST API reference documentation for Lightning Pool.
Lightning Pool is a non-custodial batched uniform clearing-price auction for
Lightning Channel Lease (LCL). A LCL packages up inbound (or outbound!) channel
liquidity (ability to send/receive funds) as a fixed incoming asset (earning
interest over time) with a maturity date expressed in blocks. The maturity date
of each of the channels is enforced by Bitcoin contracts, ensuring that the
funds of the maker (the party that sold the channel) can't be swept until the
maturity height. All cleared orders (purchased channels) are cleared in a
single batched on-chain transaction.
This repository is home to the Pool client and depends on the Lightning Network
daemon lnd. All of lnd’s supported chain backends are fully supported when
using the Pool client: Neutrino, Bitcoin Core, and btcd.
The service can be used in various situations:
- Bootstrapping new users with side car channels
- Bootstrapping new services to Lightning
- Demand fueled routing node channel selection
- Allowing users to instantly receive with a wallet
This site features the API documentation for shell script (CLI), Python and
JavaScript clients in order to communicate with a local poold instance through
gRPC.
The examples to the right assume that the there is a local poold instance
running and listening for REST connections on port 8281. POOL_DIR
will be used as a placeholder to denote the base directory of the poold
instance. By default, this is ~/.pool on Linux and
~/Library/Application Support/Pool on macOS.
At the time of writing this documentation, two things are needed in order to
make an HTTP request to an poold instance: a TLS/SSL connection and a
macaroon used for RPC authentication. The examples to the right will show how
these can be used in order to make a successful, secure, and authenticated HTTP
request.
The original *.swagger.js files from which the gRPC documentation was generated
can be found here:
NOTE: The byte field type must be set as the base64 encoded string
representation of a raw byte array. Also, any time this must be used in a URL path
(ie. /v1/abc/xyz/{payment_hash}) the base64 string must be encoded using a
URL and Filename Safe Alphabet. This means you must replace + with -,
/ with _, and keep the trailing = as is. Url encoding (ie. %2F) will not work.
This is the reference for the REST API. Alternatively, there is also a gRPC
API which is documented here.
This documentation was
generated automatically against commit
59e0fd707f706a7a74b5ac38d0fbdb8aedf44161.
/v1/pool/accounts
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts
{
"accounts": <array poolrpcAccount>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"accounts": <array poolrpcAccount>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/accounts',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "accounts": <array poolrpcAccount>,
// }
GET /v1/pool/accounts
pool: accounts list ListAccounts returns a list of all accounts known to the trader daemon and their current state.
| Field |
Type |
Placement |
Description |
| active_only |
boolean |
query |
Only list accounts that are still active. |
Response
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X DELETE --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts
{
"close_txid": <byte>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.delete(url, verify=cert_path)
>>> print(r.json())
{
"close_txid": <byte>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/accounts',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.delete(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "close_txid": <byte>,
// }
DELETE /v1/pool/accounts
pool: accounts close CloseAccount closes an account and returns the funds locked in that account to the connected lnd node's wallet.
| Field |
Type |
Placement |
Description |
| trader_key |
string |
query |
The trader key associated with the account that will be closed. |
| output_with_fee.address |
string |
query |
The address corresponding to the output. |
| output_with_fee.conf_target |
int64 |
query |
The target number of blocks that the transaction should be confirmed in. |
| output_with_fee.fee_rate_sat_per_kw |
string |
query |
The fee rate, in satoshis per kw, to use for the withdrawal transaction. |
Response
| Field |
Type |
Description |
| close_txid |
byte |
The hash of the closing transaction. |
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts -d '{ \
"account_value":<string>, \
"absolute_height":<int64>, \
"relative_height":<int64>, \
"conf_target":<int64>, \
"fee_rate_sat_per_kw":<string>, \
"initiator":<string>, \
"version":<poolrpcAccountVersion>, \
}'
{
"trader_key": <byte>,
"outpoint": <poolrpcOutPoint>,
"value": <string>,
"available_balance": <string>,
"expiration_height": <int64>,
"state": <poolrpcAccountState>,
"latest_txid": <byte>,
"version": <poolrpcAccountVersion>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'account_value': <string>,
'absolute_height': <int64>,
'relative_height': <int64>,
'conf_target': <int64>,
'fee_rate_sat_per_kw': <string>,
'initiator': <string>,
'version': <poolrpcAccountVersion>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"trader_key": <byte>,
"outpoint": <poolrpcOutPoint>,
"value": <string>,
"available_balance": <string>,
"expiration_height": <int64>,
"state": <poolrpcAccountState>,
"latest_txid": <byte>,
"version": <poolrpcAccountVersion>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
account_value: <string>,
absolute_height: <int64>,
relative_height: <int64>,
conf_target: <int64>,
fee_rate_sat_per_kw: <string>,
initiator: <string>,
version: <poolrpcAccountVersion>,
};
let options = {
url: 'https://localhost:8281/v1/pool/accounts',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "trader_key": <byte>,
// "outpoint": <poolrpcOutPoint>,
// "value": <string>,
// "available_balance": <string>,
// "expiration_height": <int64>,
// "state": <poolrpcAccountState>,
// "latest_txid": <byte>,
// "version": <poolrpcAccountVersion>,
// }
POST /v1/pool/accounts
pool: accounts new InitAccount creates a new account with the requested size and expiration, funding it from the wallet of the connected lnd node.
| Field |
Type |
Placement |
Description |
| account_value |
string |
body |
|
| absolute_height |
int64 |
body |
|
| relative_height |
int64 |
body |
|
| conf_target |
int64 |
body |
The target number of blocks that the transaction should be confirmed in. |
| fee_rate_sat_per_kw |
string |
body |
The fee rate, in satoshis per kw, to use for the initial funding transaction. |
| initiator |
string |
body |
An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI). |
| version |
poolrpcAccountVersion |
body |
The version of account to create. |
Response
| Field |
Type |
Description |
| trader_key |
byte |
The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer. |
| outpoint |
poolrpcOutPoint |
The current outpoint associated with the account. This will change every time the account has been updated. |
| value |
string |
The current total amount of satoshis in the account. |
| available_balance |
string |
The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders. |
| expiration_height |
int64 |
The height at which the account will expire. |
| state |
poolrpcAccountState |
The current state of the account. |
| latest_txid |
byte |
The hash of the account's latest transaction. |
| version |
poolrpcAccountVersion |
The current version of the account. |
/v1/pool/accounts/bump
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts/bump -d '{ \
"trader_key":<byte>, \
"fee_rate_sat_per_kw":<string>, \
}'
{
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts/bump'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'trader_key': base64.b64encode(<byte>).decode(),
'fee_rate_sat_per_kw': <string>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
trader_key: <byte>,
fee_rate_sat_per_kw: <string>,
};
let options = {
url: 'https://localhost:8281/v1/pool/accounts/bump',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
POST /v1/pool/accounts/bump
pool: accounts bumpfee BumpAccountFee attempts to bump the fee of an account's transaction through child-pays-for-parent (CPFP). Since the CPFP is performed through the backing lnd node, the account transaction must contain an output under its control for a successful bump. If a CPFP has already been performed for an account, and this RPC is invoked again, then a replacing transaction (RBF) of the child will be broadcast.
| Field |
Type |
Placement |
Description |
| trader_key |
byte |
body |
The trader key associated with the account that will have its fee bumped. |
| fee_rate_sat_per_kw |
string |
body |
The new fee rate, in satoshis per kw, to use for the child of the account transaction. |
Response
This response has no parameters.
/v1/pool/accounts/deposit
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts/deposit -d '{ \
"trader_key":<byte>, \
"amount_sat":<string>, \
"fee_rate_sat_per_kw":<string>, \
"absolute_expiry":<int64>, \
"relative_expiry":<int64>, \
"new_version":<poolrpcAccountVersion>, \
}'
{
"account": <poolrpcAccount>,
"deposit_txid": <byte>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts/deposit'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'trader_key': base64.b64encode(<byte>).decode(),
'amount_sat': <string>,
'fee_rate_sat_per_kw': <string>,
'absolute_expiry': <int64>,
'relative_expiry': <int64>,
'new_version': <poolrpcAccountVersion>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"account": <poolrpcAccount>,
"deposit_txid": <byte>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
trader_key: <byte>,
amount_sat: <string>,
fee_rate_sat_per_kw: <string>,
absolute_expiry: <int64>,
relative_expiry: <int64>,
new_version: <poolrpcAccountVersion>,
};
let options = {
url: 'https://localhost:8281/v1/pool/accounts/deposit',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "account": <poolrpcAccount>,
// "deposit_txid": <byte>,
// }
POST /v1/pool/accounts/deposit
pool: accounts deposit DepositAccount adds more funds from the connected lnd node's wallet to an account.
| Field |
Type |
Placement |
Description |
| trader_key |
byte |
body |
The trader key associated with the account that funds will be deposited into. |
| amount_sat |
string |
body |
The amount in satoshis to deposit into the account. |
| fee_rate_sat_per_kw |
string |
body |
The fee rate, in satoshis per kw, to use for the deposit transaction. |
| absolute_expiry |
int64 |
body |
The new absolute expiration height of the account. |
| relative_expiry |
int64 |
body |
The new relative expiration height of the account. |
| new_version |
poolrpcAccountVersion |
body |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the deposit. |
Response
| Field |
Type |
Description |
| account |
poolrpcAccount |
The state of the account after processing the deposit. |
| deposit_txid |
byte |
The transaction used to deposit funds into the account. |
/v1/pool/accounts/quote
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts/quote -d '{ \
"account_value":<string>, \
"conf_target":<int64>, \
}'
{
"miner_fee_rate_sat_per_kw": <string>,
"miner_fee_total": <string>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts/quote'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'account_value': <string>,
'conf_target': <int64>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"miner_fee_rate_sat_per_kw": <string>,
"miner_fee_total": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
account_value: <string>,
conf_target: <int64>,
};
let options = {
url: 'https://localhost:8281/v1/pool/accounts/quote',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "miner_fee_rate_sat_per_kw": <string>,
// "miner_fee_total": <string>,
// }
POST /v1/pool/accounts/quote
QuoteAccount gets a fee quote to fund an account of the given size with the given confirmation target. If the connected lnd wallet doesn't have enough balance to fund an account of the requested size, an error is returned.
| Field |
Type |
Placement |
Description |
| account_value |
string |
body |
|
| conf_target |
int64 |
body |
The target number of blocks that the transaction should be confirmed in. |
Response
| Field |
Type |
Description |
| miner_fee_rate_sat_per_kw |
string |
|
| miner_fee_total |
string |
|
/v1/pool/accounts/recover
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts/recover -d '{ \
"full_client":<boolean>, \
"account_target":<int64>, \
"auctioneer_key":<string>, \
"height_hint":<int64>, \
"bitcoin_host":<string>, \
"bitcoin_user":<string>, \
"bitcoin_password":<string>, \
"bitcoin_httppostmode":<boolean>, \
"bitcoin_usetls":<boolean>, \
"bitcoin_tlspath":<string>, \
}'
{
"num_recovered_accounts": <int64>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts/recover'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'full_client': <boolean>,
'account_target': <int64>,
'auctioneer_key': <string>,
'height_hint': <int64>,
'bitcoin_host': <string>,
'bitcoin_user': <string>,
'bitcoin_password': <string>,
'bitcoin_httppostmode': <boolean>,
'bitcoin_usetls': <boolean>,
'bitcoin_tlspath': <string>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"num_recovered_accounts": <int64>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
full_client: <boolean>,
account_target: <int64>,
auctioneer_key: <string>,
height_hint: <int64>,
bitcoin_host: <string>,
bitcoin_user: <string>,
bitcoin_password: <string>,
bitcoin_httppostmode: <boolean>,
bitcoin_usetls: <boolean>,
bitcoin_tlspath: <string>,
};
let options = {
url: 'https://localhost:8281/v1/pool/accounts/recover',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "num_recovered_accounts": <int64>,
// }
POST /v1/pool/accounts/recover
pool: accounts recover RecoverAccounts queries the auction server for this trader daemon's accounts in case we lost our local account database.
| Field |
Type |
Placement |
Description |
| full_client |
boolean |
body |
Recover the latest account states without interacting with the Lightning Labs server. |
| account_target |
int64 |
body |
Number of accounts that we are trying to recover. Used during the full_client recovery process. |
| auctioneer_key |
string |
body |
Auctioneer's public key. Used during the full_client recovery process. This field should be left empty for testnet/mainnet, its value is already hardcoded in our codebase. |
| height_hint |
int64 |
body |
Initial block height. We won't try to look for any account with an expiry height smaller than this value. Used during the full_client recovery process. |
| bitcoin_host |
string |
body |
bitcoind/btcd instance address. Used during the full_client recovery process. |
| bitcoin_user |
string |
body |
bitcoind/btcd user name. Used during the full_client recovery process. |
| bitcoin_password |
string |
body |
bitcoind/btcd password. Used during the full_client recovery process. |
| bitcoin_httppostmode |
boolean |
body |
Use HTTP POST mode? bitcoind only supports this mode. Used during the full_client recovery process. |
| bitcoin_usetls |
boolean |
body |
Use TLS to connect? bitcoind only supports non-TLS connections. Used during the full_client recovery process. |
| bitcoin_tlspath |
string |
body |
Path to btcd's TLS certificate, if TLS is enabled. Used during the full_client recovery process. |
Response
| Field |
Type |
Description |
| num_recovered_accounts |
int64 |
The number of accounts that were recovered. |
/v1/pool/accounts/renew
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts/renew -d '{ \
"account_key":<byte>, \
"absolute_expiry":<int64>, \
"relative_expiry":<int64>, \
"fee_rate_sat_per_kw":<string>, \
"new_version":<poolrpcAccountVersion>, \
}'
{
"account": <poolrpcAccount>,
"renewal_txid": <byte>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts/renew'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'account_key': base64.b64encode(<byte>).decode(),
'absolute_expiry': <int64>,
'relative_expiry': <int64>,
'fee_rate_sat_per_kw': <string>,
'new_version': <poolrpcAccountVersion>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"account": <poolrpcAccount>,
"renewal_txid": <byte>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
account_key: <byte>,
absolute_expiry: <int64>,
relative_expiry: <int64>,
fee_rate_sat_per_kw: <string>,
new_version: <poolrpcAccountVersion>,
};
let options = {
url: 'https://localhost:8281/v1/pool/accounts/renew',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "account": <poolrpcAccount>,
// "renewal_txid": <byte>,
// }
POST /v1/pool/accounts/renew
pool: accounts renew RenewAccount renews the expiration of an account.
| Field |
Type |
Placement |
Description |
| account_key |
byte |
body |
The key associated with the account to renew. |
| absolute_expiry |
int64 |
body |
The new absolute expiration height of the account. |
| relative_expiry |
int64 |
body |
The new relative expiration height of the account. |
| fee_rate_sat_per_kw |
string |
body |
The fee rate, in satoshis per kw, to use for the renewal transaction. |
| new_version |
poolrpcAccountVersion |
body |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the renewal. |
Response
| Field |
Type |
Description |
| account |
poolrpcAccount |
The state of the account after processing the renewal. |
| renewal_txid |
byte |
The transaction used to renew the expiration of the account. |
/v1/pool/accounts/withdraw
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/accounts/withdraw -d '{ \
"trader_key":<byte>, \
"outputs":<array poolrpcOutput>, \
"fee_rate_sat_per_kw":<string>, \
"absolute_expiry":<int64>, \
"relative_expiry":<int64>, \
"new_version":<poolrpcAccountVersion>, \
}'
{
"account": <poolrpcAccount>,
"withdraw_txid": <byte>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/accounts/withdraw'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'trader_key': base64.b64encode(<byte>).decode(),
'outputs': <array poolrpcOutput>,
'fee_rate_sat_per_kw': <string>,
'absolute_expiry': <int64>,
'relative_expiry': <int64>,
'new_version': <poolrpcAccountVersion>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"account": <poolrpcAccount>,
"withdraw_txid": <byte>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
trader_key: <byte>,
outputs: <array poolrpcOutput>,
fee_rate_sat_per_kw: <string>,
absolute_expiry: <int64>,
relative_expiry: <int64>,
new_version: <poolrpcAccountVersion>,
};
let options = {
url: 'https://localhost:8281/v1/pool/accounts/withdraw',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "account": <poolrpcAccount>,
// "withdraw_txid": <byte>,
// }
POST /v1/pool/accounts/withdraw
pool: accounts withdraw WithdrawAccount splits off parts of the account balance into the specified outputs while recreating the account with a reduced balance.
| Field |
Type |
Placement |
Description |
| trader_key |
byte |
body |
The trader key associated with the account that funds will be withdrawed from. |
| outputs |
array poolrpcOutput |
body |
The outputs we'll withdraw funds from the account into. |
| fee_rate_sat_per_kw |
string |
body |
The fee rate, in satoshis per kw, to use for the withdrawal transaction. |
| absolute_expiry |
int64 |
body |
The new absolute expiration height of the account. |
| relative_expiry |
int64 |
body |
The new relative expiration height of the account. |
| new_version |
poolrpcAccountVersion |
body |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the withdrawal. |
Response
| Field |
Type |
Description |
| account |
poolrpcAccount |
The state of the account after processing the withdrawal. |
| withdraw_txid |
byte |
The transaction used to withdraw funds from the account. |
/v1/pool/batch/next
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/batch/next
{
"conf_target": <int64>,
"fee_rate_sat_per_kw": <string>,
"clear_timestamp": <string>,
"auto_renew_extension_blocks": <int64>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/batch/next'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"conf_target": <int64>,
"fee_rate_sat_per_kw": <string>,
"clear_timestamp": <string>,
"auto_renew_extension_blocks": <int64>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/batch/next',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "conf_target": <int64>,
// "fee_rate_sat_per_kw": <string>,
// "clear_timestamp": <string>,
// "auto_renew_extension_blocks": <int64>,
// }
GET /v1/pool/batch/next
pool: auction nextbatchinfo NextBatchInfo returns information about the next batch the auctioneer will perform.
This request has no parameters.
Response
| Field |
Type |
Description |
| conf_target |
int64 |
The confirmation target the auctioneer will use for fee estimation of the next batch. |
| fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch. |
| clear_timestamp |
string |
The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch. |
| auto_renew_extension_blocks |
int64 |
The value used by the auctioneer to determine if an account expiry height needs to be extended after participating in a batch and for how long. |
/v1/pool/batch/snapshot
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/batch/snapshot
{
"version": <int64>,
"batch_id": <byte>,
"prev_batch_id": <byte>,
"clearing_price_rate": <int64>,
"matched_orders": <array poolrpcMatchedOrderSnapshot>,
"batch_tx_id": <string>,
"batch_tx": <byte>,
"batch_tx_fee_rate_sat_per_kw": <string>,
"creation_timestamp_ns": <string>,
"matched_markets": <object>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/batch/snapshot'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"version": <int64>,
"batch_id": <byte>,
"prev_batch_id": <byte>,
"clearing_price_rate": <int64>,
"matched_orders": <array poolrpcMatchedOrderSnapshot>,
"batch_tx_id": <string>,
"batch_tx": <byte>,
"batch_tx_fee_rate_sat_per_kw": <string>,
"creation_timestamp_ns": <string>,
"matched_markets": <object>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/batch/snapshot',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "version": <int64>,
// "batch_id": <byte>,
// "prev_batch_id": <byte>,
// "clearing_price_rate": <int64>,
// "matched_orders": <array poolrpcMatchedOrderSnapshot>,
// "batch_tx_id": <string>,
// "batch_tx": <byte>,
// "batch_tx_fee_rate_sat_per_kw": <string>,
// "creation_timestamp_ns": <string>,
// "matched_markets": <object>,
// }
GET /v1/pool/batch/snapshot
pool: auction snapshot BatchSnapshot returns the snapshot of a past batch identified by its ID. If no ID is provided, the snapshot of the last finalized batch is returned. Deprecated, use BatchSnapshots instead.
| Field |
Type |
Placement |
Description |
| batch_id |
string |
query |
The unique identifier of the batch encoded as a compressed pubkey. |
Response
| Field |
Type |
Description |
| version |
int64 |
The version of the batch. |
| batch_id |
byte |
The unique identifier of the batch. |
| prev_batch_id |
byte |
The unique identifier of the prior batch. |
| clearing_price_rate |
int64 |
Deprecated, use matched_markets. |
| matched_orders |
array poolrpcMatchedOrderSnapshot |
Deprecated, use matched_markets. |
| batch_tx_id |
string |
The txid of the batch transaction. |
| batch_tx |
byte |
The batch transaction including all witness data. |
| batch_tx_fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kiloweight, of the batch transaction. |
| creation_timestamp_ns |
string |
The unix timestamp in nanoseconds the batch was made. |
| matched_markets |
object |
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price. |
/v1/pool/batch/snapshots
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/batch/snapshots
{
"batches": <array poolrpcBatchSnapshotResponse>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/batch/snapshots'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"batches": <array poolrpcBatchSnapshotResponse>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/batch/snapshots',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "batches": <array poolrpcBatchSnapshotResponse>,
// }
GET /v1/pool/batch/snapshots
pool: auction snapshot 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.
| Field |
Type |
Placement |
Description |
| start_batch_id |
string |
query |
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. |
| num_batches_back |
int64 |
query |
The number of batches to return at most, including the start batch. |
Response
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}
{
"batches": <array poolrpcBatchSnapshotResponse>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"batches": <array poolrpcBatchSnapshotResponse>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "batches": <array poolrpcBatchSnapshotResponse>,
// }
GET /v1/pool/batch/snapshots/{start_batch_id}
pool: auction snapshot 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.
| Field |
Type |
Placement |
Description |
| start_batch_id |
string |
path |
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. |
| num_batches_back |
int64 |
query |
The number of batches to return at most, including the start batch. |
Response
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}/{num_batches_back}
{
"batches": <array poolrpcBatchSnapshotResponse>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}/{num_batches_back}'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"batches": <array poolrpcBatchSnapshotResponse>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}/{num_batches_back}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "batches": <array poolrpcBatchSnapshotResponse>,
// }
GET /v1/pool/batch/snapshots/{start_batch_id}/{num_batches_back}
pool: auction snapshot 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.
| Field |
Type |
Placement |
Description |
| start_batch_id |
string |
path |
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. |
| num_batches_back |
int64 |
path |
The number of batches to return at most, including the start batch. |
Response
/v1/pool/fee
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/fee
{
"execution_fee": <poolrpcExecutionFee>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/fee'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"execution_fee": <poolrpcExecutionFee>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/fee',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "execution_fee": <poolrpcExecutionFee>,
// }
GET /v1/pool/fee
pool: auction fee AuctionFee returns the current auction order execution fee specified by the auction server.
This request has no parameters.
Response
| Field |
Type |
Description |
| execution_fee |
poolrpcExecutionFee |
The execution fee charged per matched order. |
/v1/pool/info
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/info
{
"version": <string>,
"accounts_total": <int64>,
"accounts_active": <int64>,
"accounts_active_expired": <int64>,
"accounts_archived": <int64>,
"orders_total": <int64>,
"orders_active": <int64>,
"orders_archived": <int64>,
"current_block_height": <int64>,
"batches_involved": <int64>,
"node_rating": <poolrpcNodeRating>,
"lsat_tokens": <int64>,
"subscribed_to_auctioneer": <boolean>,
"new_nodes_only": <boolean>,
"market_info": <object>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/info'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"version": <string>,
"accounts_total": <int64>,
"accounts_active": <int64>,
"accounts_active_expired": <int64>,
"accounts_archived": <int64>,
"orders_total": <int64>,
"orders_active": <int64>,
"orders_archived": <int64>,
"current_block_height": <int64>,
"batches_involved": <int64>,
"node_rating": <poolrpcNodeRating>,
"lsat_tokens": <int64>,
"subscribed_to_auctioneer": <boolean>,
"new_nodes_only": <boolean>,
"market_info": <object>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/info',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "version": <string>,
// "accounts_total": <int64>,
// "accounts_active": <int64>,
// "accounts_active_expired": <int64>,
// "accounts_archived": <int64>,
// "orders_total": <int64>,
// "orders_active": <int64>,
// "orders_archived": <int64>,
// "current_block_height": <int64>,
// "batches_involved": <int64>,
// "node_rating": <poolrpcNodeRating>,
// "lsat_tokens": <int64>,
// "subscribed_to_auctioneer": <boolean>,
// "new_nodes_only": <boolean>,
// "market_info": <object>,
// }
GET /v1/pool/info
pool: getinfo GetInfo returns general information about the state of the Pool trader daemon.
This request has no parameters.
Response
| Field |
Type |
Description |
| version |
string |
The version of the Pool daemon that is running. |
| accounts_total |
int64 |
The total number of accounts in the local database. |
| accounts_active |
int64 |
The total number of accounts that are in an active, non-archived state, including expired accounts. |
| accounts_active_expired |
int64 |
The total number of accounts that are active but have expired. |
| accounts_archived |
int64 |
The total number of accounts that are in an archived/closed state. |
| orders_total |
int64 |
The total number of orders in the local database. |
| orders_active |
int64 |
The total number of active/pending orders that are still waiting for execution. |
| orders_archived |
int64 |
The total number of orders that have been archived. |
| current_block_height |
int64 |
The current block height as seen by the connected lnd node. |
| batches_involved |
int64 |
The number of batches an account of this node was ever involved in. |
| node_rating |
poolrpcNodeRating |
Our lnd node's rating as judged by the auctioneer server. |
| lsat_tokens |
int64 |
The number of available LSAT tokens. |
| subscribed_to_auctioneer |
boolean |
Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server. |
| new_nodes_only |
boolean |
Indicates whether the global --newnodesonly command line flag or newnodesonly=true configuration parameter was set on the Pool trader daemon. |
| market_info |
object |
A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest. |
/v1/pool/lease_durations
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/lease_durations
{
"lease_durations": <object>,
"lease_duration_buckets": <object>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/lease_durations'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"lease_durations": <object>,
"lease_duration_buckets": <object>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/lease_durations',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "lease_durations": <object>,
// "lease_duration_buckets": <object>,
// }
GET /v1/pool/lease_durations
pool: auction leasedurations LeaseDurations returns the current set of valid lease duration in the market as is, and also information w.r.t if the market is currently active.
This request has no parameters.
Response
| Field |
Type |
Description |
| lease_durations |
object |
Deprecated, use lease_duration_buckets. |
| lease_duration_buckets |
object |
The set of lease durations the market is currently accepting and the state the duration buckets currently are in. |
/v1/pool/leases
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/leases
{
"leases": <array poolrpcLease>,
"total_amt_earned_sat": <string>,
"total_amt_paid_sat": <string>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/leases'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"leases": <array poolrpcLease>,
"total_amt_earned_sat": <string>,
"total_amt_paid_sat": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/leases',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "leases": <array poolrpcLease>,
// "total_amt_earned_sat": <string>,
// "total_amt_paid_sat": <string>,
// }
GET /v1/pool/leases
pool: auction leases Leases returns the list of channels that were either purchased or sold by the trader within the auction.
| Field |
Type |
Placement |
Description |
| batch_ids |
array |
query |
An optional list of batches to retrieve the leases of. If empty, leases throughout all batches are returned. |
| accounts |
array |
query |
An optional list of accounts to retrieve the leases of. If empty, leases for all accounts are returned. |
Response
| Field |
Type |
Description |
| leases |
array poolrpcLease |
The relevant list of leases purchased or sold within the auction. |
| total_amt_earned_sat |
string |
The total amount of satoshis earned from the leases returned. |
| total_amt_paid_sat |
string |
The total amount of satoshis paid for the leases returned. |
/v1/pool/lsat/tokens
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/lsat/tokens
{
"tokens": <array poolrpcLsatToken>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/lsat/tokens'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"tokens": <array poolrpcLsatToken>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/lsat/tokens',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "tokens": <array poolrpcLsatToken>,
// }
GET /v1/pool/lsat/tokens
pool: listauth GetLsatTokens returns all LSAT tokens the daemon ever paid for.
This request has no parameters.
Response
| Field |
Type |
Description |
| tokens |
array poolrpcLsatToken |
List of all tokens the daemon knows of, including old/expired tokens. |
/v1/pool/node_ratings
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/node_ratings
{
"node_ratings": <array poolrpcNodeRating>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/node_ratings'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"node_ratings": <array poolrpcNodeRating>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/node_ratings',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "node_ratings": <array poolrpcNodeRating>,
// }
GET /v1/pool/node_ratings
pool: auction ratings Returns the Node Tier information for this target Lightning node, and other related ranking information.
| Field |
Type |
Placement |
Description |
| node_pubkeys |
array |
query |
The target node to obtain ratings information for. |
Response
| Field |
Type |
Description |
| node_ratings |
array poolrpcNodeRating |
A series of node ratings for each of the queried nodes. |
/v1/pool/orders
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X GET --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/orders
{
"asks": <array poolrpcAsk>,
"bids": <array poolrpcBid>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/orders'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"asks": <array poolrpcAsk>,
"bids": <array poolrpcBid>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/orders',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "asks": <array poolrpcAsk>,
// "bids": <array poolrpcBid>,
// }
GET /v1/pool/orders
pool: orders list ListOrders returns a list of all active and archived orders that are currently known to the trader daemon.
| Field |
Type |
Placement |
Description |
| verbose |
boolean |
query |
Can be set to true to list the orders including all events, which can be very verbose. |
| active_only |
boolean |
query |
Only list orders that are still active. |
Response
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/orders -d '{ \
"ask":<poolrpcAsk>, \
"bid":<poolrpcBid>, \
"initiator":<string>, \
}'
{
"invalid_order": <poolrpcInvalidOrder>,
"accepted_order_nonce": <byte>,
"updated_sidecar_ticket": <string>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/orders'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'ask': <poolrpcAsk>,
'bid': <poolrpcBid>,
'initiator': <string>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"invalid_order": <poolrpcInvalidOrder>,
"accepted_order_nonce": <byte>,
"updated_sidecar_ticket": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
ask: <poolrpcAsk>,
bid: <poolrpcBid>,
initiator: <string>,
};
let options = {
url: 'https://localhost:8281/v1/pool/orders',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "invalid_order": <poolrpcInvalidOrder>,
// "accepted_order_nonce": <byte>,
// "updated_sidecar_ticket": <string>,
// }
POST /v1/pool/orders
pool: orders submit SubmitOrder creates a new ask or bid order and submits for the given account and submits it to the auction server for matching.
| Field |
Type |
Placement |
Description |
| ask |
poolrpcAsk |
body |
|
| bid |
poolrpcBid |
body |
|
| initiator |
string |
body |
An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for submitting the order (pool CLI, LiT UI, other 3rd party UI). |
Response
| Field |
Type |
Description |
| invalid_order |
poolrpcInvalidOrder |
Order failed with the given reason. |
| accepted_order_nonce |
byte |
The order nonce of the accepted order. |
| updated_sidecar_ticket |
string |
In case a bid order was submitted for a sidecar ticket, that ticket is updated with the new state and bid order nonce. |
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X DELETE --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/orders/{order_nonce}
{
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/orders/{order_nonce}'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.delete(url, verify=cert_path)
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let options = {
url: 'https://localhost:8281/v1/pool/orders/{order_nonce}',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
};
request.delete(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
DELETE /v1/pool/orders/{order_nonce}
pool: orders cancel CancelOrder cancels an active order with the auction server to remove it from future matching.
| Field |
Type |
Placement |
Description |
| order_nonce |
string |
path |
|
Response
This response has no parameters.
/v1/pool/orders/quote
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/orders/quote -d '{ \
"amt":<string>, \
"rate_fixed":<int64>, \
"lease_duration_blocks":<int64>, \
"max_batch_fee_rate_sat_per_kw":<string>, \
"min_units_match":<int64>, \
}'
{
"total_premium_sat": <string>,
"rate_per_block": <double>,
"rate_percent": <double>,
"total_execution_fee_sat": <string>,
"worst_case_chain_fee_sat": <string>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/orders/quote'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'amt': <string>,
'rate_fixed': <int64>,
'lease_duration_blocks': <int64>,
'max_batch_fee_rate_sat_per_kw': <string>,
'min_units_match': <int64>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"total_premium_sat": <string>,
"rate_per_block": <double>,
"rate_percent": <double>,
"total_execution_fee_sat": <string>,
"worst_case_chain_fee_sat": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
amt: <string>,
rate_fixed: <int64>,
lease_duration_blocks: <int64>,
max_batch_fee_rate_sat_per_kw: <string>,
min_units_match: <int64>,
};
let options = {
url: 'https://localhost:8281/v1/pool/orders/quote',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "total_premium_sat": <string>,
// "rate_per_block": <double>,
// "rate_percent": <double>,
// "total_execution_fee_sat": <string>,
// "worst_case_chain_fee_sat": <string>,
// }
POST /v1/pool/orders/quote
QuoteOrder calculates the premium, execution fees and max batch fee rate for an order based on the given order parameters.
| Field |
Type |
Placement |
Description |
| amt |
string |
body |
Order amount in satoshis. |
| rate_fixed |
int64 |
body |
Fixed order rate in parts per billion. |
| lease_duration_blocks |
int64 |
body |
Required number of blocks that a channel opened as a result of this bid should be kept open. |
| max_batch_fee_rate_sat_per_kw |
string |
body |
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW). |
| min_units_match |
int64 |
body |
The minimum number of order units that must be matched per order pair. |
Response
| Field |
Type |
Description |
| total_premium_sat |
string |
The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees. |
| rate_per_block |
double |
The fixed order rate expressed as a fraction instead of parts per billion. |
| rate_percent |
double |
The fixed order rate expressed as a percentage instead of parts per billion. |
| total_execution_fee_sat |
string |
The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order. |
| worst_case_chain_fee_sat |
string |
The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation). |
/v1/pool/sidecar/expect
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/sidecar/expect -d '{ \
"ticket":<string>, \
}'
{
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/sidecar/expect'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'ticket': <string>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
ticket: <string>,
};
let options = {
url: 'https://localhost:8281/v1/pool/sidecar/expect',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
POST /v1/pool/sidecar/expect
pool: sidecar expectchannel ExpectSidecarChannel is step 4/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 recipient once the provider has submitted the bid order for the sidecar channel. From this point onwards the Pool trader daemon of both the provider as well as the recipient need to be online to receive and react to match making events from the server.
| Field |
Type |
Placement |
Description |
| ticket |
string |
body |
The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered". |
Response
This response has no parameters.
/v1/pool/sidecar/offer
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/sidecar/offer -d '{ \
"auto_negotiate":<boolean>, \
"bid":<poolrpcBid>, \
}'
{
"ticket": <string>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/sidecar/offer'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'auto_negotiate': <boolean>,
'bid': <poolrpcBid>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"ticket": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
auto_negotiate: <boolean>,
bid: <poolrpcBid>,
};
let options = {
url: 'https://localhost:8281/v1/pool/sidecar/offer',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "ticket": <string>,
// }
POST /v1/pool/sidecar/offer
pool: sidecar offer 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".
| Field |
Type |
Placement |
Description |
| auto_negotiate |
boolean |
body |
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. |
| bid |
poolrpcBid |
body |
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. |
Response
| Field |
Type |
Description |
| ticket |
string |
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. |
/v1/pool/sidecar/register
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/sidecar/register -d '{ \
"ticket":<string>, \
"auto_negotiate":<boolean>, \
}'
{
"ticket": <string>,
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/sidecar/register'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
'ticket': <string>,
'auto_negotiate': <boolean>,
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
"ticket": <string>,
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
ticket: <string>,
auto_negotiate: <boolean>,
};
let options = {
url: 'https://localhost:8281/v1/pool/sidecar/register',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "ticket": <string>,
// }
POST /v1/pool/sidecar/register
pool: sidecar register RegisterSidecarRequest is step 2/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 recipient. The result is a sidecar ticket with the recipient's node information and channel funding multisig pubkey filled in. The ticket returned by this call will have the state "registered".
| Field |
Type |
Placement |
Description |
| ticket |
string |
body |
The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered". |
| auto_negotiate |
boolean |
body |
If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down. |
Response
| Field |
Type |
Description |
| ticket |
string |
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. |
/v1/pool/stop
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $POOL_DIR/regtest/pool.macaroon)"
$ curl -X POST --cacert $POOL_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8281/v1/pool/stop -d '{ \
}'
{
}
>>> import base64, json, requests
>>> url = 'https://localhost:8281/v1/pool/stop'
>>> cert_path = 'POOL_DIR/tls.cert'
>>> macaroon = codecs.encode(open('POOL_DIR/regtest/pool.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = {
}
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{
}
const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('POOL_DIR/regtest/pool.macaroon').toString('hex');
let requestBody = {
};
let options = {
url: 'https://localhost:8281/v1/pool/stop',
// Work-around for self-signed certificates.
rejectUnauthorized: false,
json: true,
headers: {
'Grpc-Metadata-macaroon': macaroon
},
form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// }
POST /v1/pool/stop
pool: stop Stop gracefully shuts down the Pool trader daemon.
This request has no parameters.
Response
This response has no parameters.
REST Messages
MarketInfoTierValue
poolrpcAccount
| Field |
Type |
Description |
| trader_key |
byte |
The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer. |
| outpoint |
poolrpcOutPoint |
The current outpoint associated with the account. This will change every time the account has been updated. |
| value |
string |
The current total amount of satoshis in the account. |
| available_balance |
string |
The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders. |
| expiration_height |
int64 |
The height at which the account will expire. |
| state |
poolrpcAccountState |
The current state of the account. |
| latest_txid |
byte |
The hash of the account's latest transaction. |
| version |
poolrpcAccountVersion |
The current version of the account. |
poolrpcAccountModificationFee
| Field |
Type |
Description |
| action |
string |
Modification action type. |
| txid |
string |
Transaction ID. |
| block_height |
int32 |
Action transaction block height. |
| timestamp |
string |
Action transaction timestamp. |
| output_amount |
string |
Action transaction output amount. |
| fee_null |
boolean |
A flag which is true if fee value has not been set, and is otherwise false. |
| fee_value |
string |
Action transaction fee value. |
poolrpcAccountModificationFeesResponse
| Field |
Type |
Description |
| accounts |
object |
A map from account key to an ordered list of account modification fees. |
poolrpcAsk
| Field |
Type |
Description |
| details |
poolrpcOrder |
The common fields shared between both ask and bid order types. |
| lease_duration_blocks |
int64 |
The number of blocks the liquidity provider is willing to provide the channel funds for. |
| version |
int64 |
The version of the order format that is used. Will be increased once new features are added. |
| announcement_constraints |
poolrpcChannelAnnouncementConstraints |
The constraints for selling the liquidity based on channel discoverability. |
| confirmation_constraints |
poolrpcChannelConfirmationConstraints |
The constraints for selling the liquidity based on the number of blocks before considering the channel confirmed. |
poolrpcAskSnapshot
| Field |
Type |
Description |
| version |
int64 |
The version of the order. |
| lease_duration_blocks |
int64 |
The period of time the channel will survive for. |
| rate_fixed |
int64 |
The true bid price of the order in parts per billion. |
| chan_type |
poolrpcOrderChannelType |
The channel type to be created. |
poolrpcAuctionFeeResponse
| Field |
Type |
Description |
| execution_fee |
poolrpcExecutionFee |
The execution fee charged per matched order. |
poolrpcBatchSnapshotResponse
| Field |
Type |
Description |
| version |
int64 |
The version of the batch. |
| batch_id |
byte |
The unique identifier of the batch. |
| prev_batch_id |
byte |
The unique identifier of the prior batch. |
| clearing_price_rate |
int64 |
Deprecated, use matched_markets. |
| matched_orders |
array poolrpcMatchedOrderSnapshot |
Deprecated, use matched_markets. |
| batch_tx_id |
string |
The txid of the batch transaction. |
| batch_tx |
byte |
The batch transaction including all witness data. |
| batch_tx_fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kiloweight, of the batch transaction. |
| creation_timestamp_ns |
string |
The unix timestamp in nanoseconds the batch was made. |
| matched_markets |
object |
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price. |
poolrpcBatchSnapshotsResponse
poolrpcBid
| Field |
Type |
Description |
| details |
poolrpcOrder |
The common fields shared between both ask and bid order types. |
| lease_duration_blocks |
int64 |
Required number of blocks that a channel opened as a result of this bid should be kept open. |
| version |
int64 |
The version of the order format that is used. Will be increased once new features are added. |
| min_node_tier |
poolrpcNodeTier |
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. |
| self_chan_balance |
string |
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. |
| sidecar_ticket |
string |
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. |
| unannounced_channel |
boolean |
Signals if this bid is interested in an announced or unannounced channel. |
| zero_conf_channel |
boolean |
Signals if this bid is interested in a zero conf channel or not. |
poolrpcBidSnapshot
| Field |
Type |
Description |
| version |
int64 |
The version of the order. |
| lease_duration_blocks |
int64 |
The period of time the matched channel should be allocated for. |
| rate_fixed |
int64 |
The true bid price of the order in parts per billion. |
| chan_type |
poolrpcOrderChannelType |
The channel type to be created. |
poolrpcBumpAccountFeeRequest
| Field |
Type |
Description |
| trader_key |
byte |
The trader key associated with the account that will have its fee bumped. |
| fee_rate_sat_per_kw |
string |
The new fee rate, in satoshis per kw, to use for the child of the account transaction. |
poolrpcBumpAccountFeeResponse
This property has no parameters.
poolrpcCancelOrderResponse
This property has no parameters.
poolrpcCancelSidecarResponse
This property has no parameters.
poolrpcCloseAccountResponse
| Field |
Type |
Description |
| close_txid |
byte |
The hash of the closing transaction. |
poolrpcDecodedSidecarTicket
| Field |
Type |
Description |
| id |
byte |
The unique, pseudorandom identifier of the ticket. |
| version |
int64 |
The version of the ticket encoding format. |
| state |
string |
The state of the ticket. |
| offer_capacity |
string |
The offered channel capacity in satoshis. |
| offer_push_amount |
string |
The offered push amount in satoshis. |
| offer_lease_duration_blocks |
int64 |
The offered lease duration in blocks. |
| offer_sign_pubkey |
byte |
The public key the offer was signed with. |
| offer_signature |
byte |
The signature over the offer's digest. |
| offer_auto |
boolean |
Whether the offer was created with the automatic order creation flag. |
| recipient_node_pubkey |
byte |
The recipient node's public identity key. |
| recipient_multisig_pubkey |
byte |
The recipient node's channel multisig public key to be used for the sidecar channel. |
| recipient_multisig_pubkey_index |
int64 |
The index used when deriving the above multisig pubkey. |
| order_bid_nonce |
byte |
The nonce of the bid order created for this sidecar ticket. |
| order_signature |
byte |
The signature over the order's digest, signed with the private key that corresponds to the offer_sign_pubkey. |
| execution_pending_channel_id |
byte |
The pending channel ID of the sidecar channel during the execution phase. |
| encoded_ticket |
string |
The original, base58 encoded ticket. |
| offer_unannounced_channel |
boolean |
If true, the channel acceptor for this ticket will expect an unannounced channel. |
| offer_zero_conf_channel |
boolean |
If true, the channel acceptor for this ticket will expect a zero conf channel. |
poolrpcDepositAccountRequest
| Field |
Type |
Description |
| trader_key |
byte |
The trader key associated with the account that funds will be deposited into. |
| amount_sat |
string |
The amount in satoshis to deposit into the account. |
| fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kw, to use for the deposit transaction. |
| absolute_expiry |
int64 |
The new absolute expiration height of the account. |
| relative_expiry |
int64 |
The new relative expiration height of the account. |
| new_version |
poolrpcAccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the deposit. |
poolrpcDepositAccountResponse
| Field |
Type |
Description |
| account |
poolrpcAccount |
The state of the account after processing the deposit. |
| deposit_txid |
byte |
The transaction used to deposit funds into the account. |
poolrpcExecutionFee
| Field |
Type |
Description |
| base_fee |
string |
The base fee in satoshis charged per order, regardless of the matched size. |
| fee_rate |
string |
The fee rate in parts per million. |
poolrpcExpectSidecarChannelRequest
| Field |
Type |
Description |
| ticket |
string |
The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered". |
poolrpcExpectSidecarChannelResponse
This property has no parameters.
poolrpcGetInfoResponse
| Field |
Type |
Description |
| version |
string |
The version of the Pool daemon that is running. |
| accounts_total |
int64 |
The total number of accounts in the local database. |
| accounts_active |
int64 |
The total number of accounts that are in an active, non-archived state, including expired accounts. |
| accounts_active_expired |
int64 |
The total number of accounts that are active but have expired. |
| accounts_archived |
int64 |
The total number of accounts that are in an archived/closed state. |
| orders_total |
int64 |
The total number of orders in the local database. |
| orders_active |
int64 |
The total number of active/pending orders that are still waiting for execution. |
| orders_archived |
int64 |
The total number of orders that have been archived. |
| current_block_height |
int64 |
The current block height as seen by the connected lnd node. |
| batches_involved |
int64 |
The number of batches an account of this node was ever involved in. |
| node_rating |
poolrpcNodeRating |
Our lnd node's rating as judged by the auctioneer server. |
| lsat_tokens |
int64 |
The number of available LSAT tokens. |
| subscribed_to_auctioneer |
boolean |
Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server. |
| new_nodes_only |
boolean |
Indicates whether the global --newnodesonly command line flag or newnodesonly=true configuration parameter was set on the Pool trader daemon. |
| market_info |
object |
A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest. |
poolrpcInitAccountRequest
| Field |
Type |
Description |
| account_value |
string |
|
| absolute_height |
int64 |
|
| relative_height |
int64 |
|
| conf_target |
int64 |
The target number of blocks that the transaction should be confirmed in. |
| fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kw, to use for the initial funding transaction. |
| initiator |
string |
An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI). |
| version |
poolrpcAccountVersion |
The version of account to create. |
poolrpcInvalidOrder
poolrpcLease
| Field |
Type |
Description |
| channel_point |
poolrpcOutPoint |
The outpoint of the channel created. |
| channel_amt_sat |
string |
The amount, in satoshis, of the channel created. |
| channel_duration_blocks |
int64 |
The intended duration, in blocks, of the channel created. |
| channel_lease_expiry |
int64 |
The absolute height that this channel lease expires. |
| premium_sat |
string |
The premium, in satoshis, either paid or received for the offered liquidity. |
| execution_fee_sat |
string |
The execution fee, in satoshis, charged by the auctioneer for the channel created. |
| chain_fee_sat |
string |
The fee, in satoshis, charged by the auctioneer for the batch execution transaction that created this lease. |
| clearing_rate_price |
string |
The actual fixed rate expressed in parts per billionth this lease was bought/sold at. |
| order_fixed_rate |
string |
The actual fixed rate of the bid/ask, this should always be 'better' than the clearing_rate_price. |
| order_nonce |
byte |
The order executed that resulted in the channel created. |
| matched_order_nonce |
byte |
The unique identifier for the order that was matched with that resulted in the channel created. |
| purchased |
boolean |
Whether this channel was purchased from another trader or not. |
| channel_remote_node_key |
byte |
The pubkey of the node that this channel was bought/sold from. |
| channel_node_tier |
poolrpcNodeTier |
The tier of the node that this channel was bought/sold from. |
| self_chan_balance |
string |
The self channel balance that was pushed to the recipient. |
| sidecar_channel |
boolean |
Whether the channel was leased as a sidecar channel (bid orders only). |
poolrpcLeaseDurationResponse
| Field |
Type |
Description |
| lease_durations |
object |
Deprecated, use lease_duration_buckets. |
| lease_duration_buckets |
object |
The set of lease durations the market is currently accepting and the state the duration buckets currently are in. |
poolrpcLeasesResponse
| Field |
Type |
Description |
| leases |
array poolrpcLease |
The relevant list of leases purchased or sold within the auction. |
| total_amt_earned_sat |
string |
The total amount of satoshis earned from the leases returned. |
| total_amt_paid_sat |
string |
The total amount of satoshis paid for the leases returned. |
poolrpcListAccountsResponse
poolrpcListOfAccountModificationFees
poolrpcListOrdersResponse
poolrpcListSidecarsResponse
poolrpcLsatToken
| Field |
Type |
Description |
| base_macaroon |
byte |
The base macaroon that was baked by the auth server. |
| payment_hash |
byte |
The payment hash of the payment that was paid to obtain the token. |
| payment_preimage |
byte |
The preimage of the payment hash, knowledge of this is proof that the payment has been paid. If the preimage is set to all zeros, this means the payment is still pending and the token is not yet fully valid. |
| amount_paid_msat |
string |
The amount of millisatoshis that was paid to get the token. |
| routing_fee_paid_msat |
string |
The amount of millisatoshis paid in routing fee to pay for the token. |
| time_created |
string |
The creation time of the token as UNIX timestamp in seconds. |
| expired |
boolean |
Indicates whether the token is expired or still valid. |
| storage_name |
string |
Identifying attribute of this token in the store. Currently represents the file name of the token where it's stored on the file system. |
poolrpcMarketInfo
poolrpcMatchEvent
| Field |
Type |
Description |
| match_state |
poolrpcMatchState |
The state of the match making process the order went through. |
| units_filled |
int64 |
The number of units that would be (or were) filled with this match. |
| matched_order |
byte |
The nonce of the order we were matched to. |
| reject_reason |
poolrpcMatchRejectReason |
The reason why the trader daemon rejected the order. Is only set if match_state is set to REJECTED. |
poolrpcMatchedMarketSnapshot
| Field |
Type |
Description |
| matched_orders |
array poolrpcMatchedOrderSnapshot |
The set of all orders matched in the batch. |
| clearing_price_rate |
int64 |
The uniform clearing price rate in parts per billion that was used for this batch. |
poolrpcMatchedOrderSnapshot
| Field |
Type |
Description |
| ask |
poolrpcAskSnapshot |
The full ask order that was matched. |
| bid |
poolrpcBidSnapshot |
The full bid order that was matched. |
| matching_rate |
int64 |
The fixed rate premium that was matched, expressed in parts-ber-billion. |
| total_sats_cleared |
string |
The total number of satoshis that were bought. |
| units_matched |
int64 |
The total number of units that were matched. |
poolrpcNextBatchInfoResponse
| Field |
Type |
Description |
| conf_target |
int64 |
The confirmation target the auctioneer will use for fee estimation of the next batch. |
| fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch. |
| clear_timestamp |
string |
The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch. |
| auto_renew_extension_blocks |
int64 |
The value used by the auctioneer to determine if an account expiry height needs to be extended after participating in a batch and for how long. |
poolrpcNodeRating
| Field |
Type |
Description |
| node_pubkey |
byte |
The pubkey for the node these ratings belong to. |
| node_tier |
poolrpcNodeTier |
The tier of the target node. |
poolrpcNodeRatingResponse
| Field |
Type |
Description |
| node_ratings |
array poolrpcNodeRating |
A series of node ratings for each of the queried nodes. |
poolrpcOfferSidecarRequest
| Field |
Type |
Description |
| auto_negotiate |
boolean |
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. |
| bid |
poolrpcBid |
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. |
poolrpcOrder
| Field |
Type |
Description |
| trader_key |
byte |
The trader's account key of the account that is used for the order. |
| rate_fixed |
int64 |
Fixed order rate in parts per billion. |
| amt |
string |
Order amount in satoshis. |
| max_batch_fee_rate_sat_per_kw |
string |
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW). |
| order_nonce |
byte |
Order nonce, acts as unique order identifier. |
| state |
poolrpcOrderState |
The state the order currently is in. |
| units |
int64 |
The number of order units the amount corresponds to. |
| units_unfulfilled |
int64 |
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. |
| reserved_value_sat |
string |
The value reserved from the account by this order to ensure the account can pay execution and chain fees in case it gets matched. |
| creation_timestamp_ns |
string |
The unix timestamp in nanoseconds the order was first created/submitted. |
| events |
array poolrpcOrderEvent |
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. |
| min_units_match |
int64 |
The minimum number of order units that must be matched per order pair. |
| channel_type |
poolrpcOrderChannelType |
The channel type to use for the resulting matched channels. |
| allowed_node_ids |
array string |
List of nodes that will be allowed to match with our order. Incompatible with the not_allowed_node_ids field. |
| not_allowed_node_ids |
array string |
List of nodes that won't be allowed to match with our order. Incompatible with the allowed_node_ids field. |
| auction_type |
poolrpcAuctionType |
Auction type where this order must be considered during the matching. |
| is_public |
boolean |
Flag used to signal that this order can be shared in public market places. |
poolrpcOrderEvent
| Field |
Type |
Description |
| timestamp_ns |
string |
The unix timestamp in nanoseconds the event was emitted at. This is the primary key of the event and is unique across the database. |
| event_str |
string |
The human readable representation of the event. |
| state_change |
poolrpcUpdatedEvent |
The order was updated in the database. |
| matched |
poolrpcMatchEvent |
The order was involved in a match making attempt. |
poolrpcOutPoint
| Field |
Type |
Description |
| txid |
byte |
Raw bytes representing the transaction id. |
| output_index |
int64 |
The index of the output on the transaction. |
poolrpcOutput
| Field |
Type |
Description |
| value_sat |
string |
The value, in satoshis, of the output. |
| address |
string |
The address corresponding to the output. |
poolrpcOutputWithFee
| Field |
Type |
Description |
| address |
string |
The address corresponding to the output. |
| conf_target |
int64 |
The target number of blocks that the transaction should be confirmed in. |
| fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kw, to use for the withdrawal transaction. |
poolrpcOutputsWithImplicitFee
poolrpcQuoteAccountRequest
| Field |
Type |
Description |
| account_value |
string |
|
| conf_target |
int64 |
The target number of blocks that the transaction should be confirmed in. |
poolrpcQuoteAccountResponse
| Field |
Type |
Description |
| miner_fee_rate_sat_per_kw |
string |
|
| miner_fee_total |
string |
|
poolrpcQuoteOrderRequest
| Field |
Type |
Description |
| amt |
string |
Order amount in satoshis. |
| rate_fixed |
int64 |
Fixed order rate in parts per billion. |
| lease_duration_blocks |
int64 |
Required number of blocks that a channel opened as a result of this bid should be kept open. |
| max_batch_fee_rate_sat_per_kw |
string |
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW). |
| min_units_match |
int64 |
The minimum number of order units that must be matched per order pair. |
poolrpcQuoteOrderResponse
| Field |
Type |
Description |
| total_premium_sat |
string |
The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees. |
| rate_per_block |
double |
The fixed order rate expressed as a fraction instead of parts per billion. |
| rate_percent |
double |
The fixed order rate expressed as a percentage instead of parts per billion. |
| total_execution_fee_sat |
string |
The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order. |
| worst_case_chain_fee_sat |
string |
The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation). |
poolrpcRecoverAccountsRequest
| Field |
Type |
Description |
| full_client |
boolean |
Recover the latest account states without interacting with the Lightning Labs server. |
| account_target |
int64 |
Number of accounts that we are trying to recover. Used during the full_client recovery process. |
| auctioneer_key |
string |
Auctioneer's public key. Used during the full_client recovery process. This field should be left empty for testnet/mainnet, its value is already hardcoded in our codebase. |
| height_hint |
int64 |
Initial block height. We won't try to look for any account with an expiry height smaller than this value. Used during the full_client recovery process. |
| bitcoin_host |
string |
bitcoind/btcd instance address. Used during the full_client recovery process. |
| bitcoin_user |
string |
bitcoind/btcd user name. Used during the full_client recovery process. |
| bitcoin_password |
string |
bitcoind/btcd password. Used during the full_client recovery process. |
| bitcoin_httppostmode |
boolean |
Use HTTP POST mode? bitcoind only supports this mode. Used during the full_client recovery process. |
| bitcoin_usetls |
boolean |
Use TLS to connect? bitcoind only supports non-TLS connections. Used during the full_client recovery process. |
| bitcoin_tlspath |
string |
Path to btcd's TLS certificate, if TLS is enabled. Used during the full_client recovery process. |
poolrpcRecoverAccountsResponse
| Field |
Type |
Description |
| num_recovered_accounts |
int64 |
The number of accounts that were recovered. |
poolrpcRegisterSidecarRequest
| Field |
Type |
Description |
| ticket |
string |
The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered". |
| auto_negotiate |
boolean |
If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down. |
poolrpcRenewAccountRequest
| Field |
Type |
Description |
| account_key |
byte |
The key associated with the account to renew. |
| absolute_expiry |
int64 |
The new absolute expiration height of the account. |
| relative_expiry |
int64 |
The new relative expiration height of the account. |
| fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kw, to use for the renewal transaction. |
| new_version |
poolrpcAccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the renewal. |
poolrpcRenewAccountResponse
| Field |
Type |
Description |
| account |
poolrpcAccount |
The state of the account after processing the renewal. |
| renewal_txid |
byte |
The transaction used to renew the expiration of the account. |
poolrpcSidecarTicket
| Field |
Type |
Description |
| ticket |
string |
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. |
poolrpcStopDaemonRequest
This property has no parameters.
poolrpcStopDaemonResponse
This property has no parameters.
poolrpcSubmitOrderRequest
| Field |
Type |
Description |
| ask |
poolrpcAsk |
|
| bid |
poolrpcBid |
|
| initiator |
string |
An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for submitting the order (pool CLI, LiT UI, other 3rd party UI). |
poolrpcSubmitOrderResponse
| Field |
Type |
Description |
| invalid_order |
poolrpcInvalidOrder |
Order failed with the given reason. |
| accepted_order_nonce |
byte |
The order nonce of the accepted order. |
| updated_sidecar_ticket |
string |
In case a bid order was submitted for a sidecar ticket, that ticket is updated with the new state and bid order nonce. |
poolrpcTokensResponse
| Field |
Type |
Description |
| tokens |
array poolrpcLsatToken |
List of all tokens the daemon knows of, including old/expired tokens. |
poolrpcUpdatedEvent
| Field |
Type |
Description |
| previous_state |
poolrpcOrderState |
The state of the order previous to the change. This is what the state changed from. |
| new_state |
poolrpcOrderState |
The new state of the order after the change. This is what the state changed to. |
| units_filled |
int64 |
The units that were filled at the time of the event. |
poolrpcWithdrawAccountRequest
| Field |
Type |
Description |
| trader_key |
byte |
The trader key associated with the account that funds will be withdrawed from. |
| outputs |
array poolrpcOutput |
The outputs we'll withdraw funds from the account into. |
| fee_rate_sat_per_kw |
string |
The fee rate, in satoshis per kw, to use for the withdrawal transaction. |
| absolute_expiry |
int64 |
The new absolute expiration height of the account. |
| relative_expiry |
int64 |
The new relative expiration height of the account. |
| new_version |
poolrpcAccountVersion |
The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the withdrawal. |
poolrpcWithdrawAccountResponse
| Field |
Type |
Description |
| account |
poolrpcAccount |
The state of the account after processing the withdrawal. |
| withdraw_txid |
byte |
The transaction used to withdraw funds from the account. |
protobufAny
| Field |
Type |
Description |
| type_url |
string |
|
| value |
byte |
|
rpcStatus
REST Enums
InvalidOrderFailReason
| Name |
Value |
Description |
| INVALID_AMT |
0 |
|
poolrpcAccountState
| Name |
Value |
Description |
| PENDING_OPEN |
0 |
|
| PENDING_UPDATE |
1 |
|
| OPEN |
2 |
|
| EXPIRED |
3 |
|
| PENDING_CLOSED |
4 |
|
| CLOSED |
5 |
|
| RECOVERY_FAILED |
6 |
|
| PENDING_BATCH |
7 |
|
poolrpcAccountVersion
| Name |
Value |
Description |
| ACCOUNT_VERSION_LND_DEPENDENT |
0 |
|
| ACCOUNT_VERSION_LEGACY |
1 |
|
| ACCOUNT_VERSION_TAPROOT |
2 |
|
poolrpcAuctionType
| Name |
Value |
Description |
| AUCTION_TYPE_BTC_INBOUND_LIQUIDITY |
0 |
|
| AUCTION_TYPE_BTC_OUTBOUND_LIQUIDITY |
1 |
|
poolrpcChannelAnnouncementConstraints
| Name |
Value |
Description |
| ANNOUNCEMENT_NO_PREFERENCE |
0 |
|
| ONLY_ANNOUNCED |
1 |
|
| ONLY_UNANNOUNCED |
2 |
|
poolrpcChannelConfirmationConstraints
| Name |
Value |
Description |
| CONFIRMATION_NO_PREFERENCE |
0 |
|
| ONLY_CONFIRMED |
1 |
|
| ONLY_ZEROCONF |
2 |
|
poolrpcDurationBucketState
| Name |
Value |
Description |
| NO_MARKET |
0 |
|
| MARKET_CLOSED |
1 |
|
| ACCEPTING_ORDERS |
2 |
|
| MARKET_OPEN |
3 |
|
poolrpcMatchRejectReason
| Name |
Value |
Description |
| NONE |
0 |
|
| SERVER_MISBEHAVIOR |
1 |
|
| BATCH_VERSION_MISMATCH |
2 |
|
| PARTIAL_REJECT_COLLATERAL |
3 |
|
| PARTIAL_REJECT_DUPLICATE_PEER |
4 |
|
| PARTIAL_REJECT_CHANNEL_FUNDING_FAILED |
5 |
|
poolrpcMatchState
| Name |
Value |
Description |
| PREPARE |
0 |
|
| ACCEPTED |
1 |
|
| REJECTED |
2 |
|
| SIGNED |
3 |
|
| FINALIZED |
4 |
|
poolrpcNodeTier
| Name |
Value |
Description |
| TIER_DEFAULT |
0 |
|
| TIER_0 |
1 |
|
| TIER_1 |
2 |
|
poolrpcOrderChannelType
| Name |
Value |
Description |
| ORDER_CHANNEL_TYPE_UNKNOWN |
0 |
|
| ORDER_CHANNEL_TYPE_PEER_DEPENDENT |
1 |
|
| ORDER_CHANNEL_TYPE_SCRIPT_ENFORCED |
2 |
|
poolrpcOrderState
| Name |
Value |
Description |
| ORDER_SUBMITTED |
0 |
|
| ORDER_CLEARED |
1 |
|
| ORDER_PARTIALLY_FILLED |
2 |
|
| ORDER_EXECUTED |
3 |
|
| ORDER_CANCELED |
4 |
|
| ORDER_EXPIRED |
5 |
|
| ORDER_FAILED |
6 |
|
Other API References
This is the gRPC and REST API reference for the pool daemon. There are separate API reference documents for the
following daemons:
