OutlierRecommendations

Get close recommendations for currently open channels based on whether it is an outlier.

Example request: http://localhost:8466/v1/faraday/outliers/REVENUE?rec_request.minimum_monitored=123

Source: faraday.proto

gRPC

rpc OutlierRecommendations (OutlierRecommendationsRequest) returns (CloseRecommendationsResponse);

REST

HTTP Method	Path
GET	/v1/faraday/outliers/{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>,
  outlier_multiplier: <float>,
};
client.outlierRecommendations(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.OutlierRecommendationsRequest(
  rec_request=<CloseRecommendationRequest>,
  outlier_multiplier=<float>,
)
response = stub.OutlierRecommendations(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/outliers/{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/outliers/{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 outliers --help

NAME:
   frcli outliers - Get close recommendations for currently open channels based on whether it is an outlier.

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

CATEGORY:
   recommendations

OPTIONS:
   --outlier_mult value   (optional with outlier strategy) Number of inter quartile ranges a channel should be from quartiles to be considered an outlier. Recommended values are 1.5 for aggressive recommendations and 3 for conservative ones.
   --uptime               set to get recommendations based on the channel's peer's ratio of uptime to time monitored
   --revenue              get recommendations based on the channel's revenue per confirmation
   --incoming_volume      get recommendations based on the channel's incoming volume per confirmation
   --outgoing_volume      get recommendations based on the channel's outgoing volume per confirmation
   --volume               get recommendations based on the channel's total volume per confirmation
   --min_monitored value  amount of time in seconds a channel should be monitored for to be eligible for close (default: 2419200)
   

Messages

frdrpc.OutlierRecommendationsRequest

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
outlier_multiplier The number of inter-quartile ranges a value needs to be beneath the lower quartile/ above the upper quartile to be considered a lower/upper outlier. Lower values will be more aggressive in recommending channel closes, and upper values will be more conservative. Recommended values are 1.5 for aggressive recommendations and 3 for conservative recommendations.	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