ThresholdRecommendations

Get close recommendations for currently open channels based whether they are below a set threshold.

Example request: http://localhost:8466/v1/faraday/threshold/UPTIME?rec_request.minimum_monitored=123

Source: faraday.proto

gRPC

rpc ThresholdRecommendations (ThresholdRecommendationsRequest) returns (CloseRecommendationsResponse);

REST

HTTP Method	Path
GET	/v1/faraday/threshold/{rec_request.metric}

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:8465'
const MACAROON_PATH = 'FARADAY_DIR/regtest/faraday.macaroon'
const TLS_PATH = 'FARADAY_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new frdrpc.FaradayServer(GRPC_HOST, creds);
let request = {
  rec_request: <CloseRecommendationRequest>,
  threshold_value: <float>,
};
client.thresholdRecommendations(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "total_channels": <int32>,
//    "considered_channels": <int32>,
//    "recommendations": <Recommendation>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the faraday.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub

GRPC_HOST = 'localhost:8465'
MACAROON_PATH = 'FARADAY_DIR/regtest/faraday.macaroon'
TLS_PATH = 'FARADAY_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = faradaystub.FaradayServerStub(channel)
request = frdrpc.ThresholdRecommendationsRequest(
  rec_request=<CloseRecommendationRequest>,
  threshold_value=<float>,
)
response = stub.ThresholdRecommendations(request)
print(response)
# {
#    "total_channels": <int32>,
#    "considered_channels": <int32>,
#    "recommendations": <Recommendation>,
# }

REST

Javascript

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

const REST_HOST = 'localhost:8082'
const MACAROON_PATH = 'FARADAY_DIR/regtest/faraday.macaroon'

let options = {
  url: `https://${REST_HOST}/v1/faraday/threshold/{rec_request.metric}`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "total_channels": <integer>, // <int32> 
//    "considered_channels": <integer>, // <int32> 
//    "recommendations": <array>, // <Recommendation> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8082'
MACAROON_PATH = 'FARADAY_DIR/regtest/faraday.macaroon'
TLS_PATH = 'FARADAY_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/faraday/threshold/{rec_request.metric}'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "total_channels": <int32>,
#    "considered_channels": <int32>,
#    "recommendations": <Recommendation>,
# }

Shell

$ frcli threshold --help

NAME:
   frcli threshold - Get close recommendations for currently open channels based on whether they are below a set threshold.

USAGE:
   frcli threshold [command options] [arguments...]

CATEGORY:
   recommendations

OPTIONS:
   --uptime value         Ratio of uptime to time monitored, expressed in [0;1]. (default: 0)
   --revenue value        threshold revenue (in msat) per confirmation beneath which channels will be identified for close. (default: 0)
   --incoming value       threshold incoming volume (in msat) per confirmation beneath which channels will be identified for close (default: 0)
   --outgoing value       threshold outgoing volume (in msat) per confirmation beneath which channels will be identified for close (default: 0)
   --volume value         threshold total volume (in msat) per confirmation beneath which channels will be identified for close (default: 0)
   --min_monitored value  amount of time in seconds a channel should be monitored for to be eligible for close (default: 2419200)
   

Messages

frdrpc.ThresholdRecommendationsRequest

Source: faraday.proto

Field	gRPC Type	REST Type	REST Placement
rec_request The parameters that are common to all close recommendations. Nested REST Parameters rec_request.metric: string in path rec_request.minimum_monitored: string in query	CloseRecommendationRequest	object	mixed
threshold_value The threshold that recommendations will be calculated based on. For uptime: ratio of uptime to observed lifetime beneath which channels will be recommended for closure. For revenue: revenue per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For incoming volume: The incoming volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For outgoing volume: The outgoing volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For total volume: The total volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared.	float	number	query

frdrpc.CloseRecommendationsResponse

Source: faraday.proto

Field	gRPC Type	REST Type
total_channels The total number of channels, before filtering out channels that are not eligible for close recommendations.	int32	integer
considered_channels The number of channels that were considered for close recommendations.	int32	integer
recommendations A set of channel close recommendations. The absence of a channel in this set implies that it was not considered for close because it did not meet the criteria for close recommendations (it is private, or has not been monitored for long enough).	Recommendation[]	array

Nested Messages

frdrpc.CloseRecommendationRequest

Field	gRPC Type	REST Type
minimum_monitored The minimum amount of time in seconds that a channel should have been monitored by lnd to be eligible for close. This value is in place to protect against closing of newer channels.	int64	string
metric The data point base close recommendations on. Available options are: Uptime: ratio of channel peer's uptime to the period they have been monitored to. Revenue: the revenue that the channel has produced per block that its funding transaction has been confirmed for.	Metric	string

frdrpc.Recommendation

Field	gRPC Type	REST Type
chan_point The channel point [funding txid: outpoint] of the channel being considered for close.	string	string
value The value of the metric that close recommendations were based on.	float	number
recommend_close A boolean indicating whether we recommend closing the channel.	bool	boolean

Enums

frdrpc.CloseRecommendationRequest.Metric

Name	Number
UNKNOWN	0
UPTIME	1
REVENUE	2
INCOMING_VOLUME	3
OUTGOING_VOLUME	4
TOTAL_VOLUME	5