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>,
  inbound_fee: <InboundFee>,
};
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>,
  inbound_fee=<InboundFee>,
)
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> 
  inbound_fee: <object>, // <InboundFee> 
};
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>,
  'inbound_fee': <InboundFee>,
}
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)
   --inbound_base_fee_msat value  the base inbound fee in milli-satoshis that will be charged for each forwarded HTLC, regardless of payment size. Its value must be zero or negative - it is a discount for using a particular incoming channel. Note that forwards will be rejected if the discount exceeds the outbound fee (forward at a loss), and lead to penalization by the sender (default: 0)
   --inbound_fee_rate_ppm value   the inbound fee rate that will be charged proportionally based on the value of each forwarded HTLC and the outbound fee. Fee rate is expressed in parts per million and must be zero or negative - it is a discount for using a particular incoming channel. Note that forwards will be rejected if the discount exceeds the outbound fee (forward at a loss), and lead to penalization by the sender (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 which this policy update should be applied to. 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
inbound_fee Optional inbound fee. If unset, the previously set value will be retained [EXPERIMENTAL].	InboundFee	object	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.InboundFee

Field	gRPC Type	REST Type
base_fee_msat The inbound base fee charged regardless of the number of milli-satoshis received in the channel. By default, only negative values are accepted.	int32	integer
fee_rate_ppm The effective inbound fee rate in micro-satoshis (parts per million). By default, only negative values are accepted.	int32	integer

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