SubscribeChannelGraph

SubscribeChannelGraph launches a streaming RPC that allows the caller to receive notifications upon any changes to the channel graph topology from the point of view of the responding node. Events notified include: new nodes coming online, nodes updating their authenticated attributes, new channels being advertised, updates in the routing policy for a directional channel edge, and when channels are closed on-chain.

Source: lightning.proto

gRPC

info

This is a server-streaming RPC

rpc SubscribeChannelGraph (GraphTopologySubscription) returns (stream GraphTopologyUpdate);

REST

HTTP Method	Path
GET	/v1/graph/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.subscribeChannelGraph(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:
//  {
//    "node_updates": <NodeUpdate>,
//    "channel_updates": <ChannelEdgeUpdate>,
//    "closed_chans": <ClosedChannelUpdate>,
//  }

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.GraphTopologySubscription()
for response in stub.SubscribeChannelGraph(request):
  print(response)
# {
#    "node_updates": <NodeUpdate>,
#    "channel_updates": <ChannelEdgeUpdate>,
#    "closed_chans": <ClosedChannelUpdate>,
# }

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/graph/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:
//  {
//    "node_updates": <array>, // <NodeUpdate> 
//    "channel_updates": <array>, // <ChannelEdgeUpdate> 
//    "closed_chans": <array>, // <ClosedChannelUpdate> 
//  }



// --------------------------
// 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/graph/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:
//  {
//    "node_updates": <array>, // <NodeUpdate>
//    "channel_updates": <array>, // <ChannelEdgeUpdate>
//    "closed_chans": <array>, // <ClosedChannelUpdate>
//  }

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/graph/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)
# {
#    "node_updates": <NodeUpdate>,
#    "channel_updates": <ChannelEdgeUpdate>,
#    "closed_chans": <ClosedChannelUpdate>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.GraphTopologySubscription

Source: lightning.proto

note

This request has no parameters.

lnrpc.GraphTopologyUpdate

Source: lightning.proto

Field	gRPC Type	REST Type
node_updates	NodeUpdate[]	array
channel_updates	ChannelEdgeUpdate[]	array
closed_chans	ClosedChannelUpdate[]	array

Nested Messages

lnrpc.NodeUpdate

Field	gRPC Type	REST Type
addresses Deprecated, use node_addresses.	string[]	array
identity_key	string	string
global_features Deprecated, use features.	bytes	string
alias	string	string
color	string	string
node_addresses	NodeAddress[]	array
features Features that the node has advertised in the init message, node announcements and invoices.	FeaturesEntry[]	object

lnrpc.NodeAddress

Field	gRPC Type	REST Type
network	string	string
addr	string	string

lnrpc.NodeUpdate.FeaturesEntry

Field	gRPC Type	REST Type
key	uint32	unknown
value	Feature	unknown

lnrpc.Feature

Field	gRPC Type	REST Type
name	string	string
is_required	bool	boolean
is_known	bool	boolean

lnrpc.ChannelEdgeUpdate

Field	gRPC Type	REST Type
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
chan_point	ChannelPoint	object
capacity	int64	string
routing_policy	RoutingPolicy	object
advertising_node	string	string
connecting_node	string	string

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.RoutingPolicy

Field	gRPC Type	REST Type
time_lock_delta	uint32	integer
min_htlc	int64	string
fee_base_msat	int64	string
fee_rate_milli_msat	int64	string
disabled	bool	boolean
max_htlc_msat	uint64	string
last_update	uint32	integer
custom_records Custom channel update tlv records.	CustomRecordsEntry[]	object

lnrpc.RoutingPolicy.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

lnrpc.ClosedChannelUpdate

Field	gRPC Type	REST Type
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	int64	string
closed_height	uint32	integer
chan_point	ChannelPoint	object