UpdateChannelPolicy

UpdateChannelPolicy allows the caller to update the fee schedule and channel policies for all channels globally, or a particular channel.

Source: lightning.proto

gRPC

rpc UpdateChannelPolicy (PolicyUpdateRequest) returns (PolicyUpdateResponse);

REST

HTTP Method	Path
POST	/v1/chanpolicy

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', loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
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 lnrpc.Lightning(GRPC_HOST, creds);
let request = {
  global: <bool>,
  chan_point: <ChannelPoint>,
  base_fee_msat: <int64>,
  fee_rate: <double>,
  fee_rate_ppm: <uint32>,
  time_lock_delta: <uint32>,
  max_htlc_msat: <uint64>,
  min_htlc_msat: <uint64>,
  min_htlc_msat_specified: <bool>,
};
client.updateChannelPolicy(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "failed_updates": <FailedUpdate>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lightning.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lightning_pb2 as lnrpc, lightning_pb2_grpc as lightningstub

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 = lightningstub.LightningStub(channel)
request = lnrpc.PolicyUpdateRequest(
  global=<bool>,
  chan_point=<ChannelPoint>,
  base_fee_msat=<int64>,
  fee_rate=<double>,
  fee_rate_ppm=<uint32>,
  time_lock_delta=<uint32>,
  max_htlc_msat=<uint64>,
  min_htlc_msat=<uint64>,
  min_htlc_msat_specified=<bool>,
)
response = stub.UpdateChannelPolicy(request)
print(response)
# {
#    "failed_updates": <FailedUpdate>,
# }

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 = {
  global: <boolean>, // <bool> 
  chan_point: <object>, // <ChannelPoint> 
  base_fee_msat: <string>, // <int64> 
  fee_rate: <number>, // <double> 
  fee_rate_ppm: <integer>, // <uint32> 
  time_lock_delta: <integer>, // <uint32> 
  max_htlc_msat: <string>, // <uint64> 
  min_htlc_msat: <string>, // <uint64> 
  min_htlc_msat_specified: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/chanpolicy`,
  // 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:
//  {
//    "failed_updates": <array>, // <FailedUpdate> 
//  }

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}/v1/chanpolicy'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'global': <bool>,
  'chan_point': <ChannelPoint>,
  'base_fee_msat': <int64>,
  'fee_rate': <double>,
  'fee_rate_ppm': <uint32>,
  'time_lock_delta': <uint32>,
  'max_htlc_msat': <uint64>,
  'min_htlc_msat': <uint64>,
  'min_htlc_msat_specified': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "failed_updates": <FailedUpdate>,
# }

Shell

$ lncli updatechanpolicy --help

NAME:
   lncli updatechanpolicy - Update the channel policy for all channels, or a single channel.

USAGE:
   lncli updatechanpolicy [command options] base_fee_msat fee_rate time_lock_delta [--max_htlc_msat=N] [channel_point]

CATEGORY:
   Channels

DESCRIPTION:
   
  Updates the channel policy for all channels, or just a particular channel
  identified by its channel point. The update will be committed, and
  broadcast to the rest of the network within the next batch.
  Channel points are encoded as: funding_txid:output_index

OPTIONS:
   --base_fee_msat value    the base fee in milli-satoshis that will be charged for each forwarded HTLC, regardless of payment size (default: 0)
   --fee_rate value         the fee rate that will be charged proportionally based on the value of each forwarded HTLC, the lowest possible rate is 0 with a granularity of 0.000001 (millionths). Can not be set at the same time as fee_rate_ppm.
   --fee_rate_ppm value     the fee rate ppm (parts per million) that will be charged proportionally based on the value of each forwarded HTLC, the lowest possible rate is 0 with a granularity of 0.000001 (millionths). Can not be set at the same time as fee_rate. (default: 0)
   --time_lock_delta value  the CLTV delta that will be applied to all forwarded HTLCs (default: 0)
   --min_htlc_msat value    if set, the min HTLC size that will be applied to all forwarded HTLCs. If unset, the min HTLC is left unchanged. (default: 0)
   --max_htlc_msat value    if set, the max HTLC size that will be applied to all forwarded HTLCs. If unset, the max HTLC is left unchanged. (default: 0)
   --chan_point value       The channel whose fee policy should be updated, if nil the policies for all channels will be updated. Takes the form of: txid:output_index
   

Messages

lnrpc.PolicyUpdateRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
global If set, then this update applies to all currently active channels.	bool	boolean	body
chan_point If set, this update will target a specific channel.	ChannelPoint	object	body
base_fee_msat The base fee charged regardless of the number of milli-satoshis sent.	int64	string	body
fee_rate The effective fee rate in milli-satoshis. The precision of this value goes up to 6 decimal places, so 1e-6.	double	number	body
fee_rate_ppm The effective fee rate in micro-satoshis (parts per million).	uint32	integer	body
time_lock_delta The required timelock delta for HTLCs forwarded over the channel.	uint32	integer	body
max_htlc_msat If set, the maximum HTLC size in milli-satoshis. If unset, the maximum HTLC will be unchanged.	uint64	string	body
min_htlc_msat The minimum HTLC size in milli-satoshis. Only applied if min_htlc_msat_specified is true.	uint64	string	body
min_htlc_msat_specified If true, min_htlc_msat is applied.	bool	boolean	body

lnrpc.PolicyUpdateResponse

Source: lightning.proto

Field	gRPC Type	REST Type
failed_updates List of failed policy updates.	FailedUpdate[]	array

Nested Messages

lnrpc.ChannelPoint

Field	gRPC Type	REST Type
funding_txid_bytes Txid of the funding transaction. When using REST, this field must be encoded as base64.	bytes	string
funding_txid_str Hex-encoded string representing the byte-reversed hash of the funding transaction.	string	string
output_index The index of the output of the funding transaction	uint32	integer

lnrpc.FailedUpdate

Field	gRPC Type	REST Type
outpoint The outpoint in format txid:n	OutPoint	object
reason Reason for the policy update failure.	UpdateFailure	string
update_error A string representation of the policy update error.	string	string

lnrpc.OutPoint

Field	gRPC Type	REST Type
txid_bytes Raw bytes representing the transaction id.	bytes	string
txid_str Reversed, hex-encoded string representing the transaction id.	string	string
output_index The index of the output on the transaction.	uint32	integer

Enums

lnrpc.UpdateFailure

Name	Number
UPDATE_FAILURE_UNKNOWN	0
UPDATE_FAILURE_PENDING	1
UPDATE_FAILURE_NOT_FOUND	2
UPDATE_FAILURE_INTERNAL_ERR	3
UPDATE_FAILURE_INVALID_PARAMETER	4