SetMissionControlConfig

SetMissionControlConfig will set mission control's config, if the config provided is valid.

Source: routerrpc/router.proto

gRPC

rpc SetMissionControlConfig (SetMissionControlConfigRequest) returns (SetMissionControlConfigResponse);

REST

HTTP Method	Path
POST	/v2/router/mccfg

Code Samples

gRPC

Javascript

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

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync(['lightning.proto', 'routerrpc/router.proto'], loaderOptions);
const routerrpc = grpc.loadPackageDefinition(packageDefinition).routerrpc;
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 routerrpc.Router(GRPC_HOST, creds);
let request = {
  config: <MissionControlConfig>,
};
client.setMissionControlConfig(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the routerrpc/router.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import router_pb2 as routerrpc, router_pb2_grpc as routerstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_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 = routerstub.RouterStub(channel)
request = routerrpc.SetMissionControlConfigRequest(
  config=<MissionControlConfig>,
)
response = stub.SetMissionControlConfig(request)
print(response)
# {
# }

REST

Javascript

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

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let requestBody = {
  config: <object>, // <MissionControlConfig> 
};
let options = {
  url: `https://${REST_HOST}/v2/router/mccfg`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v2/router/mccfg'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'config': <MissionControlConfig>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
# }

Shell

$ lncli setmccfg --help

NAME:
   lncli setmccfg - Set mission control's config.

USAGE:
   lncli setmccfg [command options] [arguments...]

CATEGORY:
   Mission Control

DESCRIPTION:
   
        Update the config values being used by mission control to calculate the
        probability that payment routes will succeed. The estimator type must be
        provided to set estimator-related parameters.

OPTIONS:
   --pmtnr value                    the number of payments mission control should store (default: 0)
   --failrelax value                the amount of time to wait after a failure before raising failure amount (default: 0s)
   --estimator value                the probability estimator to use, choose between 'apriori' or 'bimodal' (bimodal is experimental)
   --apriorihalflife value          the amount of time taken to restore a node or channel to 50% probability of success. (default: 0s)
   --apriorihopprob value           the probability of success assigned to hops that we have no information about (default: 0)
   --aprioriweight value            the degree to which mission control should rely on historical results, expressed as value in [0, 1] (default: 0)
   --aprioricapacityfraction value  the fraction of channels' capacities that is considered liquid in pathfinding, a value between [0.75-1.0]. a value of 1.0 disables this feature. (default: 0)
   --bimodaldecaytime value         the time span after which we phase out learnings from previous payment attempts (default: 0s)
   --bimodalscale value             controls the assumed channel liquidity imbalance in the network, measured in msat. a low value (compared to typical channel capacity) anticipates unbalanced channels. (default: 0)
   --bimodalweight value            controls the degree to which the probability estimator takes into account other channels of a router (default: 0)
   

Messages

routerrpc.SetMissionControlConfigRequest

Source: routerrpc/router.proto

Field	gRPC Type	REST Type	REST Placement
config The config to set for mission control. Note that all values must be set, because the full config will be applied.	MissionControlConfig	object	body

routerrpc.SetMissionControlConfigResponse

Source: routerrpc/router.proto

note

This response has no parameters.

Nested Messages

routerrpc.AprioriParameters

Field	gRPC Type	REST Type
half_life_seconds The amount of time mission control will take to restore a penalized node or channel back to 50% success probability, expressed in seconds. Setting this value to a higher value will penalize failures for longer, making mission control less likely to route through nodes and channels that we have previously recorded failures for.	uint64	string
hop_probability The probability of success mission control should assign to hop in a route where it has no other information available. Higher values will make mission control more willing to try hops that we have no information about, lower values will discourage trying these hops.	double	number
weight The importance that mission control should place on historical results, expressed as a value in [0;1]. Setting this value to 1 will ignore all historical payments and just use the hop probability to assess the probability of success for each hop. A zero value ignores hop probability completely and relies entirely on historical results, unless none are available.	double	number
capacity_fraction The fraction of a channel's capacity that we consider to have liquidity. For amounts that come close to or exceed the fraction, an additional penalty is applied. A value of 1.0 disables the capacity factor. Allowed values are in [0.75, 1.0].	double	number

routerrpc.BimodalParameters

Field	gRPC Type	REST Type
node_weight NodeWeight defines how strongly other previous forwardings on channels of a router should be taken into account when computing a channel's probability to route. The allowed values are in the range [0, 1], where a value of 0 means that only direct information about a channel is taken into account.	double	number
scale_msat ScaleMsat describes the scale over which channels statistically have some liquidity left. The value determines how quickly the bimodal distribution drops off from the edges of a channel. A larger value (compared to typical channel capacities) means that the drop off is slow and that channel balances are distributed more uniformly. A small value leads to the assumption of very unbalanced channels.	uint64	string
decay_time DecayTime describes the information decay of knowledge about previous successes and failures in channels. The smaller the decay time, the quicker we forget about past forwardings.	uint64	string

routerrpc.MissionControlConfig

Field	gRPC Type	REST Type
half_life_secondsdeprecated Deprecated, use AprioriParameters. The amount of time mission control will take to restore a penalized node or channel back to 50% success probability, expressed in seconds. Setting this value to a higher value will penalize failures for longer, making mission control less likely to route through nodes and channels that we have previously recorded failures for.	uint64	string
hop_probabilitydeprecated Deprecated, use AprioriParameters. The probability of success mission control should assign to hop in a route where it has no other information available. Higher values will make mission control more willing to try hops that we have no information about, lower values will discourage trying these hops.	float	number
weightdeprecated Deprecated, use AprioriParameters. The importance that mission control should place on historical results, expressed as a value in [0;1]. Setting this value to 1 will ignore all historical payments and just use the hop probability to assess the probability of success for each hop. A zero value ignores hop probability completely and relies entirely on historical results, unless none are available.	float	number
maximum_payment_results The maximum number of payment results that mission control will store.	uint32	integer
minimum_failure_relax_interval The minimum time that must have passed since the previously recorded failure before we raise the failure amount.	uint64	string
model ProbabilityModel defines which probability estimator should be used in pathfinding. Note that the bimodal estimator is experimental.	ProbabilityModel	string
apriori	AprioriParameters	object
bimodal	BimodalParameters	object

Enums

routerrpc.MissionControlConfig.ProbabilityModel

Name	Number
APRIORI	0
BIMODAL	1