DescribeGraph

DescribeGraph returns a description of the latest graph state from the point of view of the node. The graph information is partitioned into two components: all the nodes/vertexes, and all the edges that connect the vertexes themselves. As this is a directed graph, the edges also contain the node directional specific routing policy which includes: the time lock delta, fee information, etc.

Source: lightning.proto

gRPC

rpc DescribeGraph (ChannelGraphRequest) returns (ChannelGraph);

REST

HTTP Method	Path
GET	/v1/graph

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_unannounced: <bool>,
};
client.describeGraph(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "nodes": <LightningNode>,
//    "edges": <ChannelEdge>,
//  }

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.ChannelGraphRequest(
  include_unannounced=<bool>,
)
response = stub.DescribeGraph(request)
print(response)
# {
#    "nodes": <LightningNode>,
#    "edges": <ChannelEdge>,
# }

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`,
  // 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:
//  {
//    "nodes": <array>, // <LightningNode> 
//    "edges": <array>, // <ChannelEdge> 
//  }

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'
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())
# {
#    "nodes": <LightningNode>,
#    "edges": <ChannelEdge>,
# }

Shell

$ lncli describegraph --help

NAME:
   lncli describegraph - Describe the network graph.

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

CATEGORY:
   Graph

DESCRIPTION:
   Prints a human readable version of the known channel graph from the PoV of the node

OPTIONS:
   --include_unannounced  If set, unannounced channels will be included in the graph. Unannounced channels are both private channels, and public channels that are not yet announced to the network.
   

Messages

lnrpc.ChannelGraphRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
include_unannounced Whether unannounced channels are included in the response or not. If set, unannounced channels are included. Unannounced channels are both private channels, and public channels that are not yet announced to the network.	bool	boolean	query

lnrpc.ChannelGraph

Source: lightning.proto

Field	gRPC Type	REST Type
nodes The list of `LightningNode`s in this channel graph	LightningNode[]	array
edges The list of `ChannelEdge`s in this channel graph	ChannelEdge[]	array

Nested Messages

lnrpc.ChannelEdge

Field	gRPC Type	REST Type
channel_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	string	string
last_update	uint32	integer
node1_pub	string	string
node2_pub	string	string
capacity	int64	string
node1_policy	RoutingPolicy	object
node2_policy	RoutingPolicy	object
custom_records Custom channel announcement tlv records.	CustomRecordsEntry[]	object

lnrpc.ChannelEdge.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

lnrpc.Feature

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

lnrpc.LightningNode

Field	gRPC Type	REST Type
last_update	uint32	integer
pub_key	string	string
alias	string	string
addresses	NodeAddress[]	array
color	string	string
features	FeaturesEntry[]	object
custom_records Custom node announcement tlv records.	CustomRecordsEntry[]	object

lnrpc.LightningNode.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

lnrpc.LightningNode.FeaturesEntry

Field	gRPC Type	REST Type
key	uint32	unknown
value	Feature	unknown

lnrpc.NodeAddress

Field	gRPC Type	REST Type
network	string	string
addr	string	string

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
inbound_fee_base_msat	int32	integer
inbound_fee_rate_milli_msat	int32	integer

lnrpc.RoutingPolicy.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown