PendingSweeps

PendingSweeps returns lists of on-chain outputs that lnd is currently attempting to sweep within its central batching engine. Outputs with similar fee rates are batched together in order to sweep them within a single transaction.

NOTE: Some of the fields within PendingSweepsRequest are not guaranteed to remain supported. This is an advanced API that depends on the internals of the UtxoSweeper, so things may change.

Source: walletrpc/walletkit.proto

gRPC

rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse);

REST

HTTP Method	Path
GET	/v2/wallet/sweeps/pending

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 = {};
client.pendingSweeps(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "pending_sweeps": <PendingSweep>,
//  }

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.PendingSweepsRequest()
response = stub.PendingSweeps(request)
print(response)
# {
#    "pending_sweeps": <PendingSweep>,
# }

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 options = {
  url: `https://${REST_HOST}/v2/wallet/sweeps/pending`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "pending_sweeps": <array>, // <PendingSweep> 
//  }

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/sweeps/pending'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "pending_sweeps": <PendingSweep>,
# }

Shell

# There is no CLI command for this RPC

Messages

walletrpc.PendingSweepsRequest

Source: walletrpc/walletkit.proto

note

This request has no parameters.

walletrpc.PendingSweepsResponse

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type
pending_sweeps The set of outputs currently being swept by lnd's central batching engine.	PendingSweep[]	array

Nested Messages

walletrpc.PendingSweep

Field	gRPC Type	REST Type
outpoint The outpoint of the output we're attempting to sweep.	OutPoint	object
witness_type The witness type of the output we're attempting to sweep.	WitnessType	string
amount_sat The value of the output we're attempting to sweep.	uint32	integer
sat_per_byte Deprecated, use sat_per_vbyte. The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee rate is only determined once a sweeping transaction for the output is created, so it's possible for this to be 0 before this.	uint32	integer
broadcast_attempts The number of broadcast attempts we've made to sweep the output.	uint32	integer
next_broadcast_height The next height of the chain at which we'll attempt to broadcast the sweep transaction of the output.	uint32	integer
requested_conf_target The requested confirmation target for this output.	uint32	integer
requested_sat_per_byte Deprecated, use requested_sat_per_vbyte. The requested fee rate, expressed in sat/vbyte, for this output.	uint32	integer
sat_per_vbyte The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee rate is only determined once a sweeping transaction for the output is created, so it's possible for this to be 0 before this.	uint64	string
requested_sat_per_vbyte The requested fee rate, expressed in sat/vbyte, for this output.	uint64	string
force Whether this input must be force-swept. This means that it is swept even if it has a negative yield.	bool	boolean

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

walletrpc.WitnessType

Name	Number
UNKNOWN_WITNESS	0
COMMITMENT_TIME_LOCK A witness that allows us to spend the output of a commitment transaction after a relative lock-time lockout.	1
COMMITMENT_NO_DELAY A witness that allows us to spend a settled no-delay output immediately on a counterparty's commitment transaction.	2
COMMITMENT_REVOKE A witness that allows us to sweep the settled output of a malicious counterparty's who broadcasts a revoked commitment transaction.	3
HTLC_OFFERED_REVOKE A witness that allows us to sweep an HTLC which we offered to the remote party in the case that they broadcast a revoked commitment state.	4
HTLC_ACCEPTED_REVOKE A witness that allows us to sweep an HTLC output sent to us in the case that the remote party broadcasts a revoked commitment state.	5
HTLC_OFFERED_TIMEOUT_SECOND_LEVEL A witness that allows us to sweep an HTLC output that we extended to a party, but was never fulfilled. This HTLC output isn't directly on the commitment transaction, but is the result of a confirmed second-level HTLC transaction. As a result, we can only spend this after a CSV delay.	6
HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL A witness that allows us to sweep an HTLC output that was offered to us, and for which we have a payment preimage. This HTLC output isn't directly on our commitment transaction, but is the result of confirmed second-level HTLC transaction. As a result, we can only spend this after a CSV delay.	7
HTLC_OFFERED_REMOTE_TIMEOUT A witness that allows us to sweep an HTLC that we offered to the remote party which lies in the commitment transaction of the remote party. We can spend this output after the absolute CLTV timeout of the HTLC as passed.	8
HTLC_ACCEPTED_REMOTE_SUCCESS A witness that allows us to sweep an HTLC that was offered to us by the remote party. We use this witness in the case that the remote party goes to chain, and we know the pre-image to the HTLC. We can sweep this without any additional timeout.	9
HTLC_SECOND_LEVEL_REVOKE A witness that allows us to sweep an HTLC from the remote party's commitment transaction in the case that the broadcast a revoked commitment, but then also immediately attempt to go to the second level to claim the HTLC.	10
WITNESS_KEY_HASH A witness type that allows us to spend a regular p2wkh output that's sent to an output which is under complete control of the backing wallet.	11
NESTED_WITNESS_KEY_HASH A witness type that allows us to sweep an output that sends to a nested P2SH script that pays to a key solely under our control.	12
COMMITMENT_ANCHOR A witness type that allows us to spend our anchor on the commitment transaction.	13