Skip to main content

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 MethodPath
GET /v1/channels/subscribe

Code Samples

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>,
// }

Messages

lnrpc.ChannelEventSubscription

Source: lightning.proto

note

This request has no parameters.

lnrpc.ChannelEventUpdate

Source: lightning.proto

FieldgRPC TypeREST Type
open_channel
Channelobject
closed_channel
ChannelCloseSummaryobject
active_channel
ChannelPointobject
inactive_channel
ChannelPointobject
pending_open_channel
PendingUpdateobject
fully_resolved_channel
ChannelPointobject
type
UpdateTypestring

Nested Messages

lnrpc.Channel

FieldgRPC TypeREST Type
active
boolboolean
remote_pubkey
stringstring
channel_point
stringstring
chan_id
uint64string
capacity
int64string
local_balance
int64string
remote_balance
int64string
commit_fee
int64string
commit_weight
int64string
fee_per_kw
int64string
unsettled_balance
int64string
total_satoshis_sent
int64string
total_satoshis_received
int64string
num_updates
uint64string
pending_htlcs
HTLC[]array
csv_delay
uint32integer
private
boolboolean
initiator
boolboolean
chan_status_flags
stringstring
local_chan_reserve_sat
int64string
remote_chan_reserve_sat
int64string
static_remote_key
boolboolean
commitment_type
CommitmentTypestring
lifetime
int64string
uptime
int64string
close_address
stringstring
push_amount_sat
uint64string
thaw_height
uint32integer
local_constraints
ChannelConstraintsobject
remote_constraints
ChannelConstraintsobject
alias_scids
uint64[]array
zero_conf
boolboolean
zero_conf_confirmed_scid
uint64string

lnrpc.HTLC

FieldgRPC TypeREST Type
incoming
boolboolean
amount
int64string
hash_lock
bytesstring
expiration_height
uint32integer
htlc_index
uint64string
forwarding_channel
uint64string
forwarding_htlc_index
uint64string

lnrpc.ChannelConstraints

FieldgRPC TypeREST Type
csv_delay
uint32integer
chan_reserve_sat
uint64string
dust_limit_sat
uint64string
max_pending_amt_msat
uint64string
min_htlc_msat
uint64string
max_accepted_htlcs
uint32integer

lnrpc.ChannelCloseSummary

FieldgRPC TypeREST Type
channel_point
stringstring
chan_id
uint64string
chain_hash
stringstring
closing_tx_hash
stringstring
remote_pubkey
stringstring
capacity
int64string
close_height
uint32integer
settled_balance
int64string
time_locked_balance
int64string
close_type
ClosureTypestring
open_initiator
Initiatorstring
close_initiator
Initiatorstring
resolutions
Resolution[]array
alias_scids
uint64[]array
zero_conf_confirmed_scid
uint64string

lnrpc.Resolution

FieldgRPC TypeREST Type
resolution_type
ResolutionTypestring
outcome
ResolutionOutcomestring
outpoint
OutPointobject
amount_sat
uint64string
sweep_txid
stringstring

lnrpc.OutPoint

FieldgRPC TypeREST Type
txid_bytes
bytesstring
txid_str
stringstring
output_index
uint32integer

lnrpc.ChannelPoint

FieldgRPC TypeREST Type
funding_txid_bytes
bytesstring
funding_txid_str
stringstring
output_index
uint32integer

lnrpc.PendingUpdate

FieldgRPC TypeREST Type
txid
bytesstring
output_index
uint32integer

Enums

lnrpc.CommitmentType

NameNumber
UNKNOWN_COMMITMENT_TYPE
0
LEGACY
1
STATIC_REMOTE_KEY
2
ANCHORS
3
SCRIPT_ENFORCED_LEASE
4

lnrpc.ChannelCloseSummary.ClosureType

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

lnrpc.Initiator

NameNumber
INITIATOR_UNKNOWN
0
INITIATOR_LOCAL
1
INITIATOR_REMOTE
2
INITIATOR_BOTH
3

lnrpc.ResolutionType

NameNumber
TYPE_UNKNOWN
0
ANCHOR
1
INCOMING_HTLC
2
OUTGOING_HTLC
3
COMMIT
4

lnrpc.ResolutionOutcome

NameNumber
OUTCOME_UNKNOWN
0
CLAIMED
1
UNCLAIMED
2
ABANDONED
3
FIRST_STAGE
4
TIMEOUT
5

lnrpc.ChannelEventUpdate.UpdateType

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