PendingChannels

PendingChannels returns a list of all the channels that are currently considered "pending". A channel is pending if it has finished the funding workflow and is waiting for confirmations for the funding txn, or is in the process of closure, either initiated cooperatively or non-cooperatively.

Source: lightning.proto

gRPC

rpc PendingChannels (PendingChannelsRequest) returns (PendingChannelsResponse);

REST

HTTP Method	Path
GET	/v1/channels/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', 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 = {
  include_raw_tx: <bool>,
};
client.pendingChannels(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "total_limbo_balance": <int64>,
//    "pending_open_channels": <PendingOpenChannel>,
//    "pending_closing_channels": <ClosedChannel>,
//    "pending_force_closing_channels": <ForceClosedChannel>,
//    "waiting_close_channels": <WaitingCloseChannel>,
//  }

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.PendingChannelsRequest(
  include_raw_tx=<bool>,
)
response = stub.PendingChannels(request)
print(response)
# {
#    "total_limbo_balance": <int64>,
#    "pending_open_channels": <PendingOpenChannel>,
#    "pending_closing_channels": <ClosedChannel>,
#    "pending_force_closing_channels": <ForceClosedChannel>,
#    "waiting_close_channels": <WaitingCloseChannel>,
# }

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}/v1/channels/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:
//  {
//    "total_limbo_balance": <string>, // <int64> 
//    "pending_open_channels": <array>, // <PendingOpenChannel> 
//    "pending_closing_channels": <array>, // <ClosedChannel> 
//    "pending_force_closing_channels": <array>, // <ForceClosedChannel> 
//    "waiting_close_channels": <array>, // <WaitingCloseChannel> 
//  }

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/channels/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())
# {
#    "total_limbo_balance": <int64>,
#    "pending_open_channels": <PendingOpenChannel>,
#    "pending_closing_channels": <ClosedChannel>,
#    "pending_force_closing_channels": <ForceClosedChannel>,
#    "waiting_close_channels": <WaitingCloseChannel>,
# }

Shell

$ lncli pendingchannels --help

NAME:
   lncli pendingchannels - Display information pertaining to pending channels.

USAGE:
   lncli pendingchannels [command options] [arguments...]

CATEGORY:
   Channels

OPTIONS:
   --include_raw_tx  include the raw transaction hex for waiting_close_channels.
   

Messages

lnrpc.PendingChannelsRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
include_raw_tx Indicates whether to include the raw transaction hex for waiting_close_channels.	bool	boolean	query

lnrpc.PendingChannelsResponse

Source: lightning.proto

Field	gRPC Type	REST Type
total_limbo_balance The balance in satoshis encumbered in pending channels	int64	string
pending_open_channels Channels pending opening	PendingOpenChannel[]	array
pending_closing_channelsdeprecated Deprecated: Channels pending closing previously contained cooperatively closed channels with a single confirmation. These channels are now considered closed from the time we see them on chain.	ClosedChannel[]	array
pending_force_closing_channels Channels pending force closing	ForceClosedChannel[]	array
waiting_close_channels Channels waiting for closing tx to confirm	WaitingCloseChannel[]	array

Nested Messages

lnrpc.PendingChannelsResponse.ClosedChannel

Field	gRPC Type	REST Type
channel The pending channel to be closed	PendingChannel	unknown
closing_txid The transaction id of the closing transaction	string	unknown

lnrpc.PendingChannelsResponse.Commitments

Field	gRPC Type	REST Type
local_txid Hash of the local version of the commitment tx.	string	unknown
remote_txid Hash of the remote version of the commitment tx.	string	unknown
remote_pending_txid Hash of the remote pending version of the commitment tx.	string	unknown
local_commit_fee_sat The amount in satoshis calculated to be paid in fees for the local commitment.	uint64	unknown
remote_commit_fee_sat The amount in satoshis calculated to be paid in fees for the remote commitment.	uint64	unknown
remote_pending_commit_fee_sat The amount in satoshis calculated to be paid in fees for the remote pending commitment.	uint64	unknown

lnrpc.PendingChannelsResponse.ForceClosedChannel

Field	gRPC Type	REST Type
channel The pending channel to be force closed	PendingChannel	unknown
closing_txid The transaction id of the closing transaction	string	unknown
limbo_balance The balance in satoshis encumbered in this pending channel	int64	unknown
maturity_height The height at which funds can be swept into the wallet	uint32	unknown
blocks_til_maturity Remaining # of blocks until the commitment output can be swept. Negative values indicate how many blocks have passed since becoming mature.	int32	unknown
recovered_balance The total value of funds successfully recovered from this channel	int64	unknown
pending_htlcs	PendingHTLC[]	unknown
anchor	AnchorState	unknown

lnrpc.PendingChannelsResponse.PendingChannel

Field	gRPC Type	REST Type
remote_node_pub	string	unknown
channel_point	string	unknown
capacity	int64	unknown
local_balance	int64	unknown
remote_balance	int64	unknown
local_chan_reserve_sat The minimum satoshis this node is required to reserve in its balance.	int64	unknown
remote_chan_reserve_sat The minimum satoshis the other node is required to reserve in its balance.	int64	unknown
initiator The party that initiated opening the channel.	Initiator	unknown
commitment_type The commitment type used by this channel.	CommitmentType	unknown
num_forwarding_packages Total number of forwarding packages created in this channel.	int64	unknown
chan_status_flags A set of flags showing the current state of the channel.	string	unknown
private Whether this channel is advertised to the network or not.	bool	unknown
memo An optional note-to-self to go along with the channel containing some useful information. This is only ever stored locally and in no way impacts the channel's operation.	string	unknown
custom_channel_data Custom channel data that might be populated in custom channels.	bytes	unknown

lnrpc.PendingChannelsResponse.PendingOpenChannel

Field	gRPC Type	REST Type
channel The pending channel	PendingChannel	unknown
commit_fee The amount calculated to be paid in fees for the current set of commitment transactions. The fee amount is persisted with the channel in order to allow the fee amount to be removed and recalculated with each channel state update, including updates that happen after a system restart.	int64	unknown
commit_weight The weight of the commitment transaction	int64	unknown
fee_per_kw The required number of satoshis per kilo-weight that the requester will pay at all times, for both the funding transaction and commitment transaction. This value can later be updated once the channel is open.	int64	unknown
funding_expiry_blocks The number of blocks until the funding transaction is considered expired. If this value gets close to zero, there is a risk that the channel funding will be canceled by the channel responder. The channel should be fee bumped using CPFP (see walletrpc.BumpFee) to ensure that the channel confirms in time. Otherwise a force-close will be necessary if the channel confirms after the funding transaction expires. A negative value means the channel responder has very likely canceled the funding and the channel will never become fully operational.	int32	unknown

lnrpc.PendingChannelsResponse.WaitingCloseChannel

Field	gRPC Type	REST Type
channel The pending channel waiting for closing tx to confirm	PendingChannel	unknown
limbo_balance The balance in satoshis encumbered in this channel	int64	unknown
commitments A list of valid commitment transactions. Any of these can confirm at this point.	Commitments	unknown
closing_txid The transaction id of the closing transaction	string	unknown
closing_tx_hex The raw hex encoded bytes of the closing transaction. Included if include_raw_tx in the request is true.	string	unknown

lnrpc.PendingHTLC

Field	gRPC Type	REST Type
incoming The direction within the channel that the htlc was sent	bool	boolean
amount The total value of the htlc	int64	string
outpoint The final output to be swept back to the user's wallet	string	string
maturity_height The next block height at which we can spend the current stage	uint32	integer
blocks_til_maturity The number of blocks remaining until the current stage can be swept. Negative values indicate how many blocks have passed since becoming mature.	int32	integer
stage Indicates whether the htlc is in its first or second stage of recovery	uint32	integer

Enums

lnrpc.CommitmentType

Name	Number
UNKNOWN_COMMITMENT_TYPE Returned when the commitment type isn't known or unavailable.	0
LEGACY A channel using the legacy commitment format having tweaked to_remote keys.	1
STATIC_REMOTE_KEY A channel that uses the modern commitment format where the key in the output of the remote party does not change each state. This makes back up and recovery easier as when the channel is closed, the funds go directly to that key.	2
ANCHORS A channel that uses a commitment format that has anchor outputs on the commitments, allowing fee bumping after a force close transaction has been broadcast.	3
SCRIPT_ENFORCED_LEASE A channel that uses a commitment type that builds upon the anchors commitment format, but in addition requires a CLTV clause to spend outputs paying to the channel initiator. This is intended for use on leased channels to guarantee that the channel initiator has no incentives to close a leased channel before its maturity date.	4
SIMPLE_TAPROOT A channel that uses musig2 for the funding output, and the new tapscript features where relevant.	5
SIMPLE_TAPROOT_OVERLAY Identical to the SIMPLE_TAPROOT channel type, but with extra functionality. This channel type also commits to additional meta data in the tapscript leaves for the scripts in a channel.	6

lnrpc.Initiator

Name	Number
INITIATOR_UNKNOWN	0
INITIATOR_LOCAL	1
INITIATOR_REMOTE	2
INITIATOR_BOTH	3

lnrpc.PendingChannelsResponse.ForceClosedChannel.AnchorState

Name	Number
LIMBO The recovered_balance is zero and limbo_balance is non-zero.	0
RECOVERED The recovered_balance is non-zero.	1
LOST A state that is neither LIMBO nor RECOVERED.	2