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
- REST
- lncli
- Javascript
- Python
- grpcurl
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>,
create_missing_edge: <bool>,
partial_update: <PartialPolicyUpdate>,
};
client.updateChannelPolicy(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "failed_updates": <FailedUpdate>,
// }
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>,
create_missing_edge=<bool>,
partial_update=<PartialPolicyUpdate>,
)
response = stub.UpdateChannelPolicy(request)
print(response)
# {
# "failed_updates": <FailedUpdate>,
# }
# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightningnetwork/lnd
GRPC_HOST=localhost:10009
LND_DIR=~/.lnd
LND_SOURCE=path/to/lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"
grpcurl \
-import-path $LND_SOURCE/lnrpc/ \
-proto lightning.proto \
-cacert $TLS_PATH \
-H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
-d '{ "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>, "create_missing_edge": <bool>, "partial_update": <PartialPolicyUpdate> }' \
$GRPC_HOST \
lnrpc.Lightning/UpdateChannelPolicy
- Javascript
- Python
- curl
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>
create_missing_edge: <boolean>, // <bool>
partial_update: <object>, // <PartialPolicyUpdate>
};
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>
// }
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>,
'create_missing_edge': <bool>,
'partial_update': <PartialPolicyUpdate>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
# "failed_updates": <FailedUpdate>,
# }
REST_HOST=localhost:8080
LND_DIR=~/.lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"
curl -X POST \
--cacert $TLS_PATH \
-H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
-d '{ "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>, "create_missing_edge": <bool>, "partial_update": <PartialPolicyUpdate> }' \
https://$REST_HOST/v1/chanpolicy
$ 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] [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
Only the fields that are passed are updated, all others keep their
current value. Leaving out base_fee_msat or the fee rate requires lnd
v0.22.0 or later.
To update individual fields, use the flags, for example
--fee_rate_ppm=100. Positional values are the legacy form. They fill
base_fee_msat, fee_rate and time_lock_delta in this order and skip each
field that a flag sets, so together they must set all three. A channel
point can follow as the last positional argument.
OPTIONS:
--base_fee_msat value if set, the base fee in milli-satoshis that will be charged for each forwarded HTLC, regardless of payment size. If unset, the base fee is left unchanged
--fee_rate value if set, 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. If neither is set, the fee rate is left unchanged
--fee_rate_ppm value if set, 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. Can not be set at the same time as fee_rate. If neither is set, the fee rate is left unchanged
--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 if set, the CLTV delta that will be applied to all forwarded HTLCs. If unset, the CLTV delta is left unchanged
--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
--create_missing_edge getchaninfo Under unknown circumstances a channel can exist with a missing edge in the graph database. This can cause an 'edge not found' error when calling getchaninfo and/or cause the default channel policy to be used during forwards. Setting this flag will recreate the edge if not found, allowing updating this channel policy and fixing the missing edge problem for this channel permanently. For fields not set in this command, the default policy will be created.
Messages
lnrpc.PolicyUpdateRequest
Source: lightning.proto
| Field | gRPC Type | REST Type | REST Placement |
|---|---|---|---|
global | bool | boolean | body |
chan_point | ChannelPoint | object | body |
base_fee_msat | int64 | string | body |
fee_rate | double | number | body |
fee_rate_ppm | uint32 | integer | body |
time_lock_delta | uint32 | integer | body |
max_htlc_msat | uint64 | string | body |
min_htlc_msat | uint64 | string | body |
min_htlc_msat_specified | bool | boolean | body |
inbound_fee | InboundFee | object | body |
create_missing_edge | bool | boolean | body |
partial_update | PartialPolicyUpdate | object | body |
lnrpc.PolicyUpdateResponse
Source: lightning.proto
| Field | gRPC Type | REST Type |
|---|---|---|
failed_updates | FailedUpdate[] | array |
Nested Messages
lnrpc.ChannelPoint
| Field | gRPC Type | REST Type |
|---|---|---|
funding_txid_bytes | bytes | string |
funding_txid_str | string | string |
output_index | uint32 | integer |
lnrpc.FailedUpdate
| Field | gRPC Type | REST Type |
|---|---|---|
outpoint | OutPoint | object |
reason | UpdateFailure | string |
update_error | string | string |
lnrpc.InboundFee
| Field | gRPC Type | REST Type |
|---|---|---|
base_fee_msat | int32 | integer |
fee_rate_ppm | int32 | integer |
lnrpc.OutPoint
| Field | gRPC Type | REST Type |
|---|---|---|
txid_bytes | bytes | string |
txid_str | string | string |
output_index | uint32 | integer |
lnrpc.PartialPolicyUpdate
| Field | gRPC Type | REST Type |
|---|---|---|
base_fee_msat | bool | boolean |
fee_rate | bool | boolean |
time_lock_delta | bool | boolean |
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 |