SubscribeChannelEvents

SubscribeChannelEvents creates a uni-directional stream from the server to the client in which any updates relevant to the state of the channels are sent over. Events include new active channels, inactive channels, and closed channels.

Source: lightning.proto

gRPC

info

This is a server-streaming RPC

rpc SubscribeChannelEvents (ChannelEventSubscription) returns (stream ChannelEventUpdate);

REST

HTTP Method	Path
GET	/v1/channels/subscribe

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 = {};
let call = client.subscribeChannelEvents(request);
call.on('data', function(response) {
  // A response was received from the server.
  console.log(response);
});
call.on('status', function(status) {
  // The current status of the stream.
});
call.on('end', function() {
  // The server has closed the stream.
});
// Console output:
//  {
//    "open_channel": <Channel>,
//    "closed_channel": <ChannelCloseSummary>,
//    "active_channel": <ChannelPoint>,
//    "inactive_channel": <ChannelPoint>,
//    "pending_open_channel": <PendingUpdate>,
//    "fully_resolved_channel": <ChannelPoint>,
//    "type": <UpdateType>,
//  }

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.ChannelEventSubscription()
for response in stub.SubscribeChannelEvents(request):
  print(response)
# {
#    "open_channel": <Channel>,
#    "closed_channel": <ChannelCloseSummary>,
#    "active_channel": <ChannelPoint>,
#    "inactive_channel": <ChannelPoint>,
#    "pending_open_channel": <PendingUpdate>,
#    "fully_resolved_channel": <ChannelPoint>,
#    "type": <UpdateType>,
# }

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/subscribe`,
  // 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:
//  {
//    "open_channel": <object>, // <Channel> 
//    "closed_channel": <object>, // <ChannelCloseSummary> 
//    "active_channel": <object>, // <ChannelPoint> 
//    "inactive_channel": <object>, // <ChannelPoint> 
//    "pending_open_channel": <object>, // <PendingUpdate> 
//    "fully_resolved_channel": <object>, // <ChannelPoint> 
//    "type": <string>, // <UpdateType> 
//  }



// --------------------------
// Example with websockets:
// --------------------------
const WebSocket = require('ws');
const fs = require('fs');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let ws = new WebSocket(`wss://${REST_HOST}/v1/channels/subscribe?method=GET`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
};
ws.on('open', function() {
    ws.send(JSON.stringify(requestBody));
});
ws.on('error', function(err) {
    console.log('Error: ' + err);
});
ws.on('message', function(body) {
    console.log(body);
});
// Console output:
//  {
//    "open_channel": <object>, // <Channel>
//    "closed_channel": <object>, // <ChannelCloseSummary>
//    "active_channel": <object>, // <ChannelPoint>
//    "inactive_channel": <object>, // <ChannelPoint>
//    "pending_open_channel": <object>, // <PendingUpdate>
//    "fully_resolved_channel": <object>, // <ChannelPoint>
//    "type": <string>, // <UpdateType>
//  }

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/subscribe'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, stream=True, verify=TLS_PATH)
for raw_response in r.iter_lines():
  json_response = json.loads(raw_response)
  print(json_response)
# {
#    "open_channel": <Channel>,
#    "closed_channel": <ChannelCloseSummary>,
#    "active_channel": <ChannelPoint>,
#    "inactive_channel": <ChannelPoint>,
#    "pending_open_channel": <PendingUpdate>,
#    "fully_resolved_channel": <ChannelPoint>,
#    "type": <UpdateType>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.ChannelEventSubscription

Source: lightning.proto

note

This request has no parameters.

lnrpc.ChannelEventUpdate

Source: lightning.proto

Field	gRPC Type	REST Type
open_channel	Channel	object
closed_channel	ChannelCloseSummary	object
active_channel	ChannelPoint	object
inactive_channel	ChannelPoint	object
pending_open_channel	PendingUpdate	object
fully_resolved_channel	ChannelPoint	object
type	UpdateType	string

Nested Messages

lnrpc.Channel

Field	gRPC Type	REST Type
active Whether this channel is active or not	bool	boolean
remote_pubkey The identity pubkey of the remote node	string	string
channel_point The outpoint (txid:index) of the funding transaction. With this value, Bob will be able to generate a signature for Alice's version of the commitment transaction.	string	string
chan_id The unique channel ID for the channel. The first 3 bytes are the block height, the next 3 the index within the block, and the last 2 bytes are the output index for the channel.	uint64	string
capacity The total amount of funds held in this channel	int64	string
local_balance This node's current balance in this channel	int64	string
remote_balance The counterparty's current balance in this channel	int64	string
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	string
commit_weight The weight of the commitment transaction	int64	string
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	string
unsettled_balance The unsettled balance in this channel	int64	string
total_satoshis_sent The total number of satoshis we've sent within this channel.	int64	string
total_satoshis_received The total number of satoshis we've received within this channel.	int64	string
num_updates The total number of updates conducted within this channel.	uint64	string
pending_htlcs The list of active, uncleared HTLCs currently pending within the channel.	HTLC[]	array
csv_delaydeprecated Deprecated. The CSV delay expressed in relative blocks. If the channel is force closed, we will need to wait for this many blocks before we can regain our funds.	uint32	integer
private Whether this channel is advertised to the network or not.	bool	boolean
initiator True if we were the ones that created the channel.	bool	boolean
chan_status_flags A set of flags showing the current state of the channel.	string	string
local_chan_reserve_satdeprecated Deprecated. The minimum satoshis this node is required to reserve in its balance.	int64	string
remote_chan_reserve_satdeprecated Deprecated. The minimum satoshis the other node is required to reserve in its balance.	int64	string
static_remote_keydeprecated Deprecated. Use commitment_type.	bool	boolean
commitment_type The commitment type used by this channel.	CommitmentType	string
lifetime The number of seconds that the channel has been monitored by the channel scoring system. Scores are currently not persisted, so this value may be less than the lifetime of the channel [EXPERIMENTAL].	int64	string
uptime The number of seconds that the remote peer has been observed as being online by the channel scoring system over the lifetime of the channel [EXPERIMENTAL].	int64	string
close_address Close address is the address that we will enforce payout to on cooperative close if the channel was opened utilizing option upfront shutdown. This value can be set on channel open by setting close_address in an open channel request. If this value is not set, you can still choose a payout address by cooperatively closing with the delivery_address field set.	string	string
push_amount_sat The amount that the initiator of the channel optionally pushed to the remote party on channel open. This amount will be zero if the channel initiator did not push any funds to the remote peer. If the initiator field is true, we pushed this amount to our peer, if it is false, the remote peer pushed this amount to us.	uint64	string
thaw_height This uint32 indicates if this channel is to be considered 'frozen'. A frozen channel doest not allow a cooperative channel close by the initiator. The thaw_height is the height that this restriction stops applying to the channel. This field is optional, not setting it or using a value of zero will mean the channel has no additional restrictions. The height can be interpreted in two ways: as a relative height if the value is less than 500,000, or as an absolute height otherwise.	uint32	integer
local_constraints List constraints for the local node.	ChannelConstraints	object
remote_constraints List constraints for the remote node.	ChannelConstraints	object
alias_scids This lists out the set of alias short channel ids that exist for a channel. This may be empty.	uint64[]	array
zero_conf Whether or not this is a zero-conf channel.	bool	boolean
zero_conf_confirmed_scid This is the confirmed / on-chain zero-conf SCID.	uint64	string
peer_alias The configured alias name of our peer.	string	string
peer_scid_alias This is the peer SCID alias.	uint64	string
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	string

lnrpc.ChannelCloseSummary

Field	gRPC Type	REST Type
channel_point The outpoint (txid:index) of the funding transaction.	string	string
chan_id The unique channel ID for the channel.	uint64	string
chain_hash The hash of the genesis block that this channel resides within.	string	string
closing_tx_hash The txid of the transaction which ultimately closed this channel.	string	string
remote_pubkey Public key of the remote peer that we formerly had a channel with.	string	string
capacity Total capacity of the channel.	int64	string
close_height Height at which the funding transaction was spent.	uint32	integer
settled_balance Settled balance at the time of channel closure	int64	string
time_locked_balance The sum of all the time-locked outputs at the time of channel closure	int64	string
close_type Details on how the channel was closed.	ClosureType	string
open_initiator Open initiator is the party that initiated opening the channel. Note that this value may be unknown if the channel was closed before we migrated to store open channel information after close.	Initiator	string
close_initiator Close initiator indicates which party initiated the close. This value will be unknown for channels that were cooperatively closed before we started tracking cooperative close initiators. Note that this indicates which party initiated a close, and it is possible for both to initiate cooperative or force closes, although only one party's close will be confirmed on chain.	Initiator	string
resolutions	Resolution[]	array
alias_scids This lists out the set of alias short channel ids that existed for the closed channel. This may be empty.	uint64[]	array
zero_conf_confirmed_scid The confirmed SCID for a zero-conf channel.	uint64	string

lnrpc.ChannelConstraints

Field	gRPC Type	REST Type
csv_delay The CSV delay expressed in relative blocks. If the channel is force closed, we will need to wait for this many blocks before we can regain our funds.	uint32	integer
chan_reserve_sat The minimum satoshis this node is required to reserve in its balance.	uint64	string
dust_limit_sat The dust limit (in satoshis) of the initiator's commitment tx.	uint64	string
max_pending_amt_msat The maximum amount of coins in millisatoshis that can be pending in this channel.	uint64	string
min_htlc_msat The smallest HTLC in millisatoshis that the initiator will accept.	uint64	string
max_accepted_htlcs The total number of incoming HTLC's that the initiator will accept.	uint32	integer

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

lnrpc.HTLC

Field	gRPC Type	REST Type
incoming	bool	boolean
amount	int64	string
hash_lock	bytes	string
expiration_height	uint32	integer
htlc_index Index identifying the htlc on the channel.	uint64	string
forwarding_channel If this HTLC is involved in a forwarding operation, this field indicates the forwarding channel. For an outgoing htlc, it is the incoming channel. For an incoming htlc, it is the outgoing channel. When the htlc originates from this node or this node is the final destination, forwarding_channel will be zero. The forwarding channel will also be zero for htlcs that need to be forwarded but don't have a forwarding decision persisted yet.	uint64	string
forwarding_htlc_index Index identifying the htlc on the forwarding channel.	uint64	string

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

lnrpc.PendingUpdate

Field	gRPC Type	REST Type
txid	bytes	string
output_index	uint32	integer

lnrpc.Resolution

Field	gRPC Type	REST Type
resolution_type The type of output we are resolving.	ResolutionType	string
outcome The outcome of our on chain action that resolved the outpoint.	ResolutionOutcome	string
outpoint The outpoint that was spent by the resolution.	OutPoint	object
amount_sat The amount that was claimed by the resolution.	uint64	string
sweep_txid The hex-encoded transaction ID of the sweep transaction that spent the output.	string	string

Enums

lnrpc.ChannelCloseSummary.ClosureType

Name	Number
COOPERATIVE_CLOSE	0
LOCAL_FORCE_CLOSE	1
REMOTE_FORCE_CLOSE	2
BREACH_CLOSE	3
FUNDING_CANCELED	4
ABANDONED	5

lnrpc.ChannelEventUpdate.UpdateType

Name	Number
OPEN_CHANNEL	0
CLOSED_CHANNEL	1
ACTIVE_CHANNEL	2
INACTIVE_CHANNEL	3
PENDING_OPEN_CHANNEL	4
FULLY_RESOLVED_CHANNEL	5

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 TODO(roasbeef): need script enforce mirror type for the above as well?	5

lnrpc.Initiator

Name	Number
INITIATOR_UNKNOWN	0
INITIATOR_LOCAL	1
INITIATOR_REMOTE	2
INITIATOR_BOTH	3

lnrpc.ResolutionOutcome

Name	Number
OUTCOME_UNKNOWN Outcome unknown.	0
CLAIMED An output was claimed on chain.	1
UNCLAIMED An output was left unclaimed on chain.	2
ABANDONED ResolverOutcomeAbandoned indicates that an output that we did not claim on chain, for example an anchor that we did not sweep and a third party claimed on chain, or a htlc that we could not decode so left unclaimed.	3
FIRST_STAGE If we force closed our channel, our htlcs need to be claimed in two stages. This outcome represents the broadcast of a timeout or success transaction for this two stage htlc claim.	4
TIMEOUT A htlc was timed out on chain.	5

lnrpc.ResolutionType

Name	Number
TYPE_UNKNOWN	0
ANCHOR We resolved an anchor output.	1
INCOMING_HTLC We are resolving an incoming htlc on chain. This if this htlc is claimed, we swept the incoming htlc with the preimage. If it is timed out, our peer swept the timeout path.	2
OUTGOING_HTLC We are resolving an outgoing htlc on chain. If this htlc is claimed, the remote party swept the htlc with the preimage. If it is timed out, we swept it with the timeout path.	3
COMMIT We force closed and need to sweep our time locked commitment output.	4