HtlcInterceptor

HtlcInterceptor dispatches a bi-directional streaming RPC in which Forwarded HTLC requests are sent to the client and the client responds with a boolean that tells LND if this htlc should be intercepted. In case of interception, the htlc can be either settled, cancelled or resumed later by using the ResolveHoldForward endpoint.

Source: routerrpc/router.proto

gRPC

info

This is a bidirectional-streaming RPC

rpc HtlcInterceptor (stream ForwardHtlcInterceptResponse) returns (stream ForwardHtlcInterceptRequest);

REST

HTTP Method	Path
POST	/v2/router/htlcinterceptor

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 = {
  incoming_circuit_key: <CircuitKey>,
  action: <ResolveHoldForwardAction>,
  preimage: <bytes>,
  failure_message: <bytes>,
  failure_code: <FailureCode>,
};
let call = client.htlcInterceptor({});
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.
});
call.write(request);
// Console output:
//  {
//    "incoming_circuit_key": <CircuitKey>,
//    "incoming_amount_msat": <uint64>,
//    "incoming_expiry": <uint32>,
//    "payment_hash": <bytes>,
//    "outgoing_requested_chan_id": <uint64>,
//    "outgoing_amount_msat": <uint64>,
//    "outgoing_expiry": <uint32>,
//    "custom_records": <CustomRecordsEntry>,
//    "onion_blob": <bytes>,
//    "auto_fail_height": <int32>,
//  }

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)
# Define a generator that returns an Iterable of ForwardHtlcInterceptResponse objects.
def request_generator():
    # Initialization code here.
    while True:
        # Parameters here can be set as arguments to the generator.
        request = routerrpc.ForwardHtlcInterceptResponse(
            incoming_circuit_key=<CircuitKey>,
            action=<ResolveHoldForwardAction>,
            preimage=<bytes>,
            failure_message=<bytes>,
            failure_code=<FailureCode>,
        )
        yield request
        # Do things between iterations here.
request_iterable = request_generator()
for response in stub.HtlcInterceptor(request_iterable):
  print(response)
# {
#    "incoming_circuit_key": <CircuitKey>,
#    "incoming_amount_msat": <uint64>,
#    "incoming_expiry": <uint32>,
#    "payment_hash": <bytes>,
#    "outgoing_requested_chan_id": <uint64>,
#    "outgoing_amount_msat": <uint64>,
#    "outgoing_expiry": <uint32>,
#    "custom_records": <CustomRecordsEntry>,
#    "onion_blob": <bytes>,
#    "auto_fail_height": <int32>,
# }

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 requestBody = {
  incoming_circuit_key: <object>, // <CircuitKey> 
  action: <string>, // <ResolveHoldForwardAction> 
  preimage: <string>, // <bytes> (base64 encoded)
  failure_message: <string>, // <bytes> (base64 encoded)
  failure_code: <string>, // <FailureCode> 
};
let options = {
  url: `https://${REST_HOST}/v2/router/htlcinterceptor`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "incoming_circuit_key": <object>, // <CircuitKey> 
//    "incoming_amount_msat": <string>, // <uint64> 
//    "incoming_expiry": <integer>, // <uint32> 
//    "payment_hash": <string>, // <bytes> 
//    "outgoing_requested_chan_id": <string>, // <uint64> 
//    "outgoing_amount_msat": <string>, // <uint64> 
//    "outgoing_expiry": <integer>, // <uint32> 
//    "custom_records": <object>, // <CustomRecordsEntry> 
//    "onion_blob": <string>, // <bytes> 
//    "auto_fail_height": <integer>, // <int32> 
//  }



// --------------------------
// 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/htlcinterceptor?method=POST`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
  incoming_circuit_key: <CircuitKey>, // <CircuitKey> 
  action: <ResolveHoldForwardAction>, // <ResolveHoldForwardAction> 
  preimage: <bytes>, // <bytes> (base64 encoded)
  failure_message: <bytes>, // <bytes> (base64 encoded)
  failure_code: <FailureCode>, // <FailureCode> 
};
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_circuit_key": <object>, // <CircuitKey>
//    "incoming_amount_msat": <string>, // <uint64>
//    "incoming_expiry": <integer>, // <uint32>
//    "payment_hash": <string>, // <bytes>
//    "outgoing_requested_chan_id": <string>, // <uint64>
//    "outgoing_amount_msat": <string>, // <uint64>
//    "outgoing_expiry": <integer>, // <uint32>
//    "custom_records": <object>, // <CustomRecordsEntry>
//    "onion_blob": <string>, // <bytes>
//    "auto_fail_height": <integer>, // <int32>
//  }

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/htlcinterceptor'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'incoming_circuit_key': <CircuitKey>,
  'action': <ResolveHoldForwardAction>,
  'preimage': base64.b64encode(<bytes>),
  'failure_message': base64.b64encode(<bytes>),
  'failure_code': <FailureCode>,
}
r = requests.post(url, headers=headers, stream=True, data=json.dumps(data), verify=TLS_PATH)
for raw_response in r.iter_lines():
  json_response = json.loads(raw_response)
  print(json_response)
# {
#    "incoming_circuit_key": <CircuitKey>,
#    "incoming_amount_msat": <uint64>,
#    "incoming_expiry": <uint32>,
#    "payment_hash": <bytes>,
#    "outgoing_requested_chan_id": <uint64>,
#    "outgoing_amount_msat": <uint64>,
#    "outgoing_expiry": <uint32>,
#    "custom_records": <CustomRecordsEntry>,
#    "onion_blob": <bytes>,
#    "auto_fail_height": <int32>,
# }

Shell

# There is no CLI command for this RPC

Messages

routerrpc.ForwardHtlcInterceptResponse

Source: routerrpc/router.proto

Field	gRPC Type	REST Type	REST Placement
incoming_circuit_key The key of this forwarded htlc. It defines the incoming channel id and the index in this channel.	CircuitKey	object	body
action The resolve action for this intercepted htlc.	ResolveHoldForwardAction	string	body
preimage The preimage in case the resolve action is Settle.	bytes	string	body
failure_message Encrypted failure message in case the resolve action is Fail. If failure_message is specified, the failure_code field must be set to zero.	bytes	string	body
failure_code Return the specified failure code in case the resolve action is Fail. The message data fields are populated automatically. If a non-zero failure_code is specified, failure_message must not be set. For backwards-compatibility reasons, TEMPORARY_CHANNEL_FAILURE is the default value for this field.	FailureCode	string	body

routerrpc.ForwardHtlcInterceptRequest

Source: routerrpc/router.proto

Field	gRPC Type	REST Type
incoming_circuit_key The key of this forwarded htlc. It defines the incoming channel id and the index in this channel.	CircuitKey	object
incoming_amount_msat The incoming htlc amount.	uint64	string
incoming_expiry The incoming htlc expiry.	uint32	integer
payment_hash The htlc payment hash. This value is not guaranteed to be unique per request.	bytes	string
outgoing_requested_chan_id The requested outgoing channel id for this forwarded htlc. Because of non-strict forwarding, this isn't necessarily the channel over which the packet will be forwarded eventually. A different channel to the same peer may be selected as well.	uint64	string
outgoing_amount_msat The outgoing htlc amount.	uint64	string
outgoing_expiry The outgoing htlc expiry.	uint32	integer
custom_records Any custom records that were present in the payload.	CustomRecordsEntry[]	object
onion_blob The onion blob for the next hop	bytes	string
auto_fail_height The block height at which this htlc will be auto-failed to prevent the channel from force-closing.	int32	integer

Nested Messages

routerrpc.CircuitKey

Field	gRPC Type	REST Type
chan_id The id of the channel that the is part of this circuit.	uint64	string
htlc_id The index of the incoming htlc in the incoming channel.	uint64	string

routerrpc.ForwardHtlcInterceptRequest.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

Enums

routerrpc.ResolveHoldForwardAction

Name	Number
SETTLE	0
FAIL	1
RESUME	2

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