BumpForceCloseFee

BumpForceCloseFee is an endpoint that allows users to bump the fee of a channel force close. This only works for channels with option_anchors.

Source: walletrpc/walletkit.proto

gRPC

rpc BumpForceCloseFee (BumpForceCloseFeeRequest) returns (BumpForceCloseFeeResponse);

REST

HTTP Method	Path
POST	/v2/wallet/BumpForceCloseFee

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', 'walletrpc/walletkit.proto'], loaderOptions);
const walletrpc = grpc.loadPackageDefinition(packageDefinition).walletrpc;
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 walletrpc.WalletKit(GRPC_HOST, creds);
let request = {
  chan_point: <ChannelPoint>,
  deadline_delta: <uint32>,
  starting_feerate: <uint64>,
  immediate: <bool>,
  budget: <uint64>,
};
client.bumpForceCloseFee(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "status": <string>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the walletrpc/walletkit.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import walletkit_pb2 as walletrpc, walletkit_pb2_grpc as walletkitstub

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 = walletkitstub.WalletKitStub(channel)
request = walletrpc.BumpForceCloseFeeRequest(
  chan_point=<ChannelPoint>,
  deadline_delta=<uint32>,
  starting_feerate=<uint64>,
  immediate=<bool>,
  budget=<uint64>,
)
response = stub.BumpForceCloseFee(request)
print(response)
# {
#    "status": <string>,
# }

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 = {
  chan_point: <object>, // <ChannelPoint> 
  deadline_delta: <integer>, // <uint32> 
  starting_feerate: <string>, // <uint64> 
  immediate: <boolean>, // <bool> 
  budget: <string>, // <uint64> 
};
let options = {
  url: `https://${REST_HOST}/v2/wallet/BumpForceCloseFee`,
  // 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:
//  {
//    "status": <string>, // <string> 
//  }

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/wallet/BumpForceCloseFee'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'chan_point': <ChannelPoint>,
  'deadline_delta': <uint32>,
  'starting_feerate': <uint64>,
  'immediate': <bool>,
  'budget': <uint64>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "status": <string>,
# }

Shell

$ lncli wallet bumpforceclosefee --help

NAME:
   lncli wallet bumpforceclosefee - Bumps the fee of a channel force closing transaction.

USAGE:
   lncli wallet bumpforceclosefee [command options] channel_point

DESCRIPTION:
   
  This command works only for unilateral closes of anchor channels. It
  allows the fee of a channel force closing transaction to be increased by
  using the child-pays-for-parent mechanism. It will instruct the sweeper
  to sweep the anchor outputs of the closing transaction at the requested
  confirmation target and limit the fees to the specified budget.
  

OPTIONS:
   --conf_target value    The deadline in number of blocks that the anchor output should be spent
                          within to bump the closing transaction. (default: 0)
   --sat_per_vbyte value  The starting fee rate, expressed in sat/vbyte. This value will be used
                          by the sweeper's fee function as its starting fee rate. When not set,
                          the sweeper will use the estimated fee rate using the target_conf as the
                          starting fee rate. (default: 0)
   --immediate            Whether this cpfp transaction will be triggered immediately. When set to
                          true, the sweeper will consider all currently pending registered sweeps
                          and trigger new batch transactions including the sweeping of the anchor 
                          output related to the selected force close transaction.
   --budget value         The max amount in sats that can be used as the fees. For already
                          registered anchor outputs if not set explicitly the old value will be
                          used. For channel force closes which have no HTLCs in their commitment
                          transaction this value has to be set to an appropriate amount to pay for
                          the cpfp transaction of the force closed channel otherwise the fee 
                          bumping will fail. (default: 0)
   

Messages

walletrpc.BumpForceCloseFeeRequest

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type	REST Placement
chan_point The channel point which force close transaction we are attempting to bump the fee rate for.	ChannelPoint	object	body
deadline_delta Optional. The deadline delta in number of blocks that the anchor output should be spent within to bump the closing transaction.	uint32	integer	body
starting_feerate Optional. The starting fee rate, expressed in sat/vbyte. This value will be used by the sweeper's fee function as its starting fee rate. When not set, the sweeper will use the estimated fee rate using the target_conf as the starting fee rate.	uint64	string	body
immediate Optional. Whether this cpfp transaction will be triggered immediately. When set to true, the sweeper will consider all currently registered sweeps and trigger new batch transactions including the sweeping of the anchor output related to the selected force close transaction.	bool	boolean	body
budget Optional. The max amount in sats that can be used as the fees. For already registered anchor outputs if not set explicitly the old value will be used. For channel force closes which have no HTLCs in their commitment transaction this value has to be set to an appropriate amount to pay for the cpfp transaction of the force closed channel otherwise the fee bumping will fail.	uint64	string	body

walletrpc.BumpForceCloseFeeResponse

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type
status The status of the force close fee bump operation.	string	string

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