BumpFee

BumpFee is an endpoint that allows users to interact with lnd's sweeper directly. It takes an outpoint from an unconfirmed transaction and sends it to the sweeper for potential fee bumping. Depending on whether the outpoint has been registered in the sweeper (an existing input, e.g., an anchor output) or not (a new input, e.g., an unconfirmed wallet utxo), this will either be an RBF or CPFP attempt.

When receiving an input, lnd’s sweeper needs to understand its time sensitivity to make economical fee bumps - internally a fee function is created using the deadline and budget to guide the process. When the deadline is approaching, the fee function will increase the fee rate and perform an RBF.

When a force close happens, all the outputs from the force closing transaction will be registered in the sweeper. The sweeper will then handle the creation, publish, and fee bumping of the sweeping transactions. Everytime a new block comes in, unless the sweeping transaction is confirmed, an RBF is attempted. To interfere with this automatic process, users can use BumpFee to specify customized fee rate, budget, deadline, and whether the sweep should happen immediately. It's recommended to call ListSweeps to understand the shape of the existing sweeping transaction first - depending on the number of inputs in this transaction, the RBF requirements can be quite different.

This RPC also serves useful when wanting to perform a Child-Pays-For-Parent (CPFP), where the child transaction pays for its parent's fee. This can be done by specifying an outpoint within the low fee transaction that is under the control of the wallet.

Source: walletrpc/walletkit.proto

gRPC

rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse);

REST

HTTP Method	Path
POST	/v2/wallet/bumpfee

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 = {
  outpoint: <OutPoint>,
  target_conf: <uint32>,
  sat_per_byte: <uint32>,
  force: <bool>,
  sat_per_vbyte: <uint64>,
  immediate: <bool>,
  budget: <uint64>,
  deadline_delta: <uint32>,
};
client.bumpFee(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.BumpFeeRequest(
  outpoint=<OutPoint>,
  target_conf=<uint32>,
  sat_per_byte=<uint32>,
  force=<bool>,
  sat_per_vbyte=<uint64>,
  immediate=<bool>,
  budget=<uint64>,
  deadline_delta=<uint32>,
)
response = stub.BumpFee(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 = {
  outpoint: <object>, // <OutPoint> 
  target_conf: <integer>, // <uint32> 
  sat_per_byte: <integer>, // <uint32> 
  force: <boolean>, // <bool> 
  sat_per_vbyte: <string>, // <uint64> 
  immediate: <boolean>, // <bool> 
  budget: <string>, // <uint64> 
  deadline_delta: <integer>, // <uint32> 
};
let options = {
  url: `https://${REST_HOST}/v2/wallet/bumpfee`,
  // 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/bumpfee'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'outpoint': <OutPoint>,
  'target_conf': <uint32>,
  'sat_per_byte': <uint32>,
  'force': <bool>,
  'sat_per_vbyte': <uint64>,
  'immediate': <bool>,
  'budget': <uint64>,
  'deadline_delta': <uint32>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "status": <string>,
# }

Shell

$ lncli wallet bumpfee --help

NAME:
   lncli wallet bumpfee - Bumps the fee of an arbitrary input/transaction.

USAGE:
   lncli wallet bumpfee [command options] outpoint

DESCRIPTION:
   
  BumpFee is an endpoint that allows users to interact with lnd's sweeper
  directly. It takes an outpoint from an unconfirmed transaction and
  sends it to the sweeper for potential fee bumping. Depending on whether
  the outpoint has been registered in the sweeper (an existing input,
  e.g., an anchor output) or not (a new input, e.g., an unconfirmed
  wallet utxo), this will either be an RBF or CPFP attempt.

  When receiving an input, lnd’s sweeper needs to understand its time
  sensitivity to make economical fee bumps - internally a fee function is
  created using the deadline and budget to guide the process. When the
  deadline is approaching, the fee function will increase the fee rate
  and perform an RBF.

  When a force close happens, all the outputs from the force closing
  transaction will be registered in the sweeper. The sweeper will then
  handle the creation, publish, and fee bumping of the sweeping
  transactions. Everytime a new block comes in, unless the sweeping
  transaction is confirmed, an RBF is attempted. To interfere with this
  automatic process, users can use BumpFee to specify customized fee
  rate, budget, deadline, and whether the sweep should happen
  immediately. It's recommended to call listsweeps to understand the
  shape of the existing sweeping transaction first - depending on the
  number of inputs in this transaction, the RBF requirements can be quite
  different.

  This RPC also serves useful when wanting to perform a
  Child-Pays-For-Parent (CPFP), where the child transaction pays for its
  parent's fee. This can be done by specifying an outpoint within the low
  fee transaction that is under the control of the wallet.
  

OPTIONS:
   --conf_target value     The conf target is the starting fee rate of the fee function expressed
                           in number of blocks. So instead of using sat_per_vbyte the conf target
                           can be specified and LND will query its fee estimator for the current
                           fee rate for the given target. (default: 0)
   --sat_per_vbyte value   The starting fee rate, expressed in sat/vbyte, that will be used to
                           spend the input with initially. 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 input will be swept immediately. When set to true, the
                           sweeper will sweep this input without waiting for the next batch.
   --budget value          The max amount in sats that can be used as the fees. Setting this value
                           greater than the input's value may result in CPFP - one or more wallet
                           utxos will be used to pay the fees specified by the budget. If not set,
                           for new inputs, by default 50% of the input's value will be treated as
                           the budget for fee bumping; for existing inputs, their current budgets
                           will be retained. (default: 0)
   --deadline_delta value  The deadline delta in number of blocks that this input should be spent
                           within to bump the transaction. When specified also a budget value is
                           required. When the deadline is reached, ALL the budget will be spent as
                           fee. (default: 0)
   

Messages

walletrpc.BumpFeeRequest

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type	REST Placement
outpoint The input we're attempting to bump the fee of.	OutPoint	object	body
target_conf Optional. The conf target the underlying fee estimator will use to estimate the starting fee rate for the fee function.	uint32	integer	body
sat_per_bytedeprecated Deprecated, use sat_per_vbyte. The fee rate, expressed in sat/vbyte, that should be used to spend the input with.	uint32	integer	body
forcedeprecated Deprecated, use immediate. Whether this input must be force-swept. This means that it is swept immediately.	bool	boolean	body
sat_per_vbyte Optional. The starting fee rate, expressed in sat/vbyte, that will be used to spend the input with initially. 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 input will be swept immediately. When set to true, the sweeper will sweep this input without waiting for the next block.	bool	boolean	body
budget Optional. The max amount in sats that can be used as the fees. Setting this value greater than the input's value may result in CPFP - one or more wallet utxos will be used to pay the fees specified by the budget. If not set, for new inputs, by default 50% of the input's value will be treated as the budget for fee bumping; for existing inputs, their current budgets will be retained.	uint64	string	body
deadline_delta Optional. The deadline delta in number of blocks that the output should be spent within. This translates internally to the width of the fee function that the sweeper will use to bump the fee rate. When the deadline is reached, ALL the budget will be spent as fees.	uint32	integer	body

walletrpc.BumpFeeResponse

Source: walletrpc/walletkit.proto

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

Nested Messages

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