SubscribeHtlcEvents

SubscribeHtlcEvents creates a uni-directional stream from the server to the client which delivers a stream of htlc events.

Source: routerrpc/router.proto

gRPC

info

This is a server-streaming RPC

rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest) returns (stream HtlcEvent);

REST

HTTP Method	Path
GET	/v2/router/htlcevents

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', 'routerrpc/router.proto'], loaderOptions);
const routerrpc = grpc.loadPackageDefinition(packageDefinition).routerrpc;
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 routerrpc.Router(GRPC_HOST, creds);
let request = {};
let call = client.subscribeHtlcEvents(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:
//  {
//    "incoming_channel_id": <uint64>,
//    "outgoing_channel_id": <uint64>,
//    "incoming_htlc_id": <uint64>,
//    "outgoing_htlc_id": <uint64>,
//    "timestamp_ns": <uint64>,
//    "event_type": <EventType>,
//    "forward_event": <ForwardEvent>,
//    "forward_fail_event": <ForwardFailEvent>,
//    "settle_event": <SettleEvent>,
//    "link_fail_event": <LinkFailEvent>,
//    "subscribed_event": <SubscribedEvent>,
//    "final_htlc_event": <FinalHtlcEvent>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the routerrpc/router.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import router_pb2 as routerrpc, router_pb2_grpc as routerstub

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 = routerstub.RouterStub(channel)
request = routerrpc.SubscribeHtlcEventsRequest()
for response in stub.SubscribeHtlcEvents(request):
  print(response)
# {
#    "incoming_channel_id": <uint64>,
#    "outgoing_channel_id": <uint64>,
#    "incoming_htlc_id": <uint64>,
#    "outgoing_htlc_id": <uint64>,
#    "timestamp_ns": <uint64>,
#    "event_type": <EventType>,
#    "forward_event": <ForwardEvent>,
#    "forward_fail_event": <ForwardFailEvent>,
#    "settle_event": <SettleEvent>,
#    "link_fail_event": <LinkFailEvent>,
#    "subscribed_event": <SubscribedEvent>,
#    "final_htlc_event": <FinalHtlcEvent>,
# }

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}/v2/router/htlcevents`,
  // 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:
//  {
//    "incoming_channel_id": <string>, // <uint64> 
//    "outgoing_channel_id": <string>, // <uint64> 
//    "incoming_htlc_id": <string>, // <uint64> 
//    "outgoing_htlc_id": <string>, // <uint64> 
//    "timestamp_ns": <string>, // <uint64> 
//    "event_type": <string>, // <EventType> 
//    "forward_event": <object>, // <ForwardEvent> 
//    "forward_fail_event": <object>, // <ForwardFailEvent> 
//    "settle_event": <object>, // <SettleEvent> 
//    "link_fail_event": <object>, // <LinkFailEvent> 
//    "subscribed_event": <object>, // <SubscribedEvent> 
//    "final_htlc_event": <object>, // <FinalHtlcEvent> 
//  }



// --------------------------
// 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}/v2/router/htlcevents?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:
//  {
//    "incoming_channel_id": <string>, // <uint64>
//    "outgoing_channel_id": <string>, // <uint64>
//    "incoming_htlc_id": <string>, // <uint64>
//    "outgoing_htlc_id": <string>, // <uint64>
//    "timestamp_ns": <string>, // <uint64>
//    "event_type": <string>, // <EventType>
//    "forward_event": <object>, // <ForwardEvent>
//    "forward_fail_event": <object>, // <ForwardFailEvent>
//    "settle_event": <object>, // <SettleEvent>
//    "link_fail_event": <object>, // <LinkFailEvent>
//    "subscribed_event": <object>, // <SubscribedEvent>
//    "final_htlc_event": <object>, // <FinalHtlcEvent>
//  }

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}/v2/router/htlcevents'
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)
# {
#    "incoming_channel_id": <uint64>,
#    "outgoing_channel_id": <uint64>,
#    "incoming_htlc_id": <uint64>,
#    "outgoing_htlc_id": <uint64>,
#    "timestamp_ns": <uint64>,
#    "event_type": <EventType>,
#    "forward_event": <ForwardEvent>,
#    "forward_fail_event": <ForwardFailEvent>,
#    "settle_event": <SettleEvent>,
#    "link_fail_event": <LinkFailEvent>,
#    "subscribed_event": <SubscribedEvent>,
#    "final_htlc_event": <FinalHtlcEvent>,
# }

Shell

# There is no CLI command for this RPC

Messages

routerrpc.SubscribeHtlcEventsRequest

Source: routerrpc/router.proto

note

This request has no parameters.

routerrpc.HtlcEvent

Source: routerrpc/router.proto

Field	gRPC Type	REST Type
incoming_channel_id The short channel id that the incoming htlc arrived at our node on. This value is zero for sends.	uint64	string
outgoing_channel_id The short channel id that the outgoing htlc left our node on. This value is zero for receives.	uint64	string
incoming_htlc_id Incoming id is the index of the incoming htlc in the incoming channel. This value is zero for sends.	uint64	string
outgoing_htlc_id Outgoing id is the index of the outgoing htlc in the outgoing channel. This value is zero for receives.	uint64	string
timestamp_ns The time in unix nanoseconds that the event occurred.	uint64	string
event_type The event type indicates whether the htlc was part of a send, receive or forward.	EventType	string
forward_event	ForwardEvent	object
forward_fail_event	ForwardFailEvent	object
settle_event	SettleEvent	object
link_fail_event	LinkFailEvent	object
subscribed_event	SubscribedEvent	object
final_htlc_event	FinalHtlcEvent	object

Nested Messages

routerrpc.FinalHtlcEvent

Field	gRPC Type	REST Type
settled	bool	boolean
offchain	bool	boolean

routerrpc.ForwardEvent

Field	gRPC Type	REST Type
info Info contains details about the htlc that was forwarded.	HtlcInfo	object

routerrpc.ForwardFailEvent

note

This response has no parameters.

routerrpc.HtlcInfo

Field	gRPC Type	REST Type
incoming_timelock The timelock on the incoming htlc.	uint32	integer
outgoing_timelock The timelock on the outgoing htlc.	uint32	integer
incoming_amt_msat The amount of the incoming htlc.	uint64	string
outgoing_amt_msat The amount of the outgoing htlc.	uint64	string

routerrpc.LinkFailEvent

Field	gRPC Type	REST Type
info Info contains details about the htlc that we failed.	HtlcInfo	object
wire_failure FailureCode is the BOLT error code for the failure.	FailureCode	string
failure_detail FailureDetail provides additional information about the reason for the failure. This detail enriches the information provided by the wire message and may be 'no detail' if the wire message requires no additional metadata.	FailureDetail	string
failure_string A string representation of the link failure.	string	string

routerrpc.SettleEvent

Field	gRPC Type	REST Type
preimage The revealed preimage.	bytes	string

routerrpc.SubscribedEvent

note

This response has no parameters.

Enums

lnrpc.Failure.FailureCode

Name	Number
RESERVED The numbers assigned in this enumeration match the failure codes as defined in BOLT #4. Because protobuf 3 requires enums to start with 0, a RESERVED value is added.	0
INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS	1
INCORRECT_PAYMENT_AMOUNT	2
FINAL_INCORRECT_CLTV_EXPIRY	3
FINAL_INCORRECT_HTLC_AMOUNT	4
FINAL_EXPIRY_TOO_SOON	5
INVALID_REALM	6
EXPIRY_TOO_SOON	7
INVALID_ONION_VERSION	8
INVALID_ONION_HMAC	9
INVALID_ONION_KEY	10
AMOUNT_BELOW_MINIMUM	11
FEE_INSUFFICIENT	12
INCORRECT_CLTV_EXPIRY	13
CHANNEL_DISABLED	14
TEMPORARY_CHANNEL_FAILURE	15
REQUIRED_NODE_FEATURE_MISSING	16
REQUIRED_CHANNEL_FEATURE_MISSING	17
UNKNOWN_NEXT_PEER	18
TEMPORARY_NODE_FAILURE	19
PERMANENT_NODE_FAILURE	20
PERMANENT_CHANNEL_FAILURE	21
EXPIRY_TOO_FAR	22
MPP_TIMEOUT	23
INVALID_ONION_PAYLOAD	24
INVALID_ONION_BLINDING	25
INTERNAL_FAILURE An internal error occurred.	997
UNKNOWN_FAILURE The error source is known, but the failure itself couldn't be decoded.	998
UNREADABLE_FAILURE An unreadable failure result is returned if the received failure message cannot be decrypted. In that case the error source is unknown.	999

routerrpc.FailureDetail

Name	Number
UNKNOWN	0
NO_DETAIL	1
ONION_DECODE	2
LINK_NOT_ELIGIBLE	3
ON_CHAIN_TIMEOUT	4
HTLC_EXCEEDS_MAX	5
INSUFFICIENT_BALANCE	6
INCOMPLETE_FORWARD	7
HTLC_ADD_FAILED	8
FORWARDS_DISABLED	9
INVOICE_CANCELED	10
INVOICE_UNDERPAID	11
INVOICE_EXPIRY_TOO_SOON	12
INVOICE_NOT_OPEN	13
MPP_INVOICE_TIMEOUT	14
ADDRESS_MISMATCH	15
SET_TOTAL_MISMATCH	16
SET_TOTAL_TOO_LOW	17
SET_OVERPAID	18
UNKNOWN_INVOICE	19
INVALID_KEYSEND	20
MPP_IN_PROGRESS	21
CIRCULAR_ROUTE	22

routerrpc.HtlcEvent.EventType

Name	Number
UNKNOWN	0
SEND	1
RECEIVE	2
FORWARD	3