TrackOnion

TrackOnion allows callers to query whether or not a payment dispatched via SendOnion succeeded or failed.

This RPC is designed to be called after a successful dispatch has been explicitly confirmed via the SendOnion RPC. It should not be used to determine whether an HTLC dispatch was received in an ambiguous network scenario. That ambiguity must be resolved by retrying the idempotent SendOnion RPC until a definitive acknowledgement is received from the Switch RPC server.

Once dispatch is confirmed, TrackOnion provides the mechanism to wait for the result of the in-flight HTLC. A client must handle three distinct categories of outcomes:

1. PAYMENT SUCCESS (gRPC code OK, preimage set): The payment settled successfully. The response contains the payment preimage.

2. PAYMENT FAILURE (gRPC code OK, failure_details set): The payment failed at the application level. The failure_details oneof describes the specific failure type: a ForwardingFailure from a remote hop, a LocalFailure from the local node, an UnreadableFailure if the error could not be decoded, or a SwitchError for other switch-level failures. When encrypted_error_data is populated, the client may perform its own decryption.

3. QUERY FAILURE (gRPC error status): The query itself could not be completed. NotFound indicates the payment ID is unknown. Unavailable signals the switch is shutting down. Canceled or DeadlineExceeded reflects client-side timeouts. These are safe to retry.

Source: switchrpc/switch.proto

gRPC

rpc TrackOnion (TrackOnionRequest) returns (TrackOnionResponse);

REST

HTTP Method	Path
POST	/v2/switch/track

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', 'switchrpc/switch.proto'], loaderOptions);
const switchrpc = grpc.loadPackageDefinition(packageDefinition).switchrpc;
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 switchrpc.Switch(GRPC_HOST, creds);
let request = {
  payment_hash: <bytes>,
  attempt_id: <uint64>,
  session_key: <bytes>,
  hop_pubkeys: <bytes>,
};
client.trackOnion(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "preimage": <bytes>,
//    "failure_details": <FailureDetails>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the switchrpc/switch.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import switch_pb2 as switchrpc, switch_pb2_grpc as switchstub

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 = switchstub.SwitchStub(channel)
request = switchrpc.TrackOnionRequest(
  payment_hash=<bytes>,
  attempt_id=<uint64>,
  session_key=<bytes>,
  hop_pubkeys=<bytes>,
)
response = stub.TrackOnion(request)
print(response)
# {
#    "preimage": <bytes>,
#    "failure_details": <FailureDetails>,
# }

grpcurl

# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightningnetwork/lnd
GRPC_HOST=localhost:10009
LND_DIR=~/.lnd
LND_SOURCE=path/to/lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"

grpcurl \
    -import-path $LND_SOURCE/lnrpc/ \
    -proto switchrpc/switch.proto \
    -cacert $TLS_PATH \
    -H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "payment_hash": BASE64_ENCODED_VALUE, "attempt_id": <uint64>, "session_key": BASE64_ENCODED_VALUE, "hop_pubkeys": BASE64_ENCODED_VALUE }' \
    $GRPC_HOST \
    switchrpc.Switch/TrackOnion

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 = {
  payment_hash: <string>, // <bytes> (base64 encoded)
  attempt_id: <string>, // <uint64> 
  session_key: <string>, // <bytes> (base64 encoded)
  hop_pubkeys: <array>, // <bytes> (base64 encoded)
};
let options = {
  url: `https://${REST_HOST}/v2/switch/track`,
  // 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:
//  {
//    "preimage": <string>, // <bytes> 
//    "failure_details": <object>, // <FailureDetails> 
//  }

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/switch/track'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'payment_hash': base64.b64encode(<bytes>),
  'attempt_id': <uint64>,
  'session_key': base64.b64encode(<bytes>),
  'hop_pubkeys': base64.b64encode(<bytes>),
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "preimage": <bytes>,
#    "failure_details": <FailureDetails>,
# }

curl

REST_HOST=localhost:8080
LND_DIR=~/.lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"

curl -X POST \
    --cacert $TLS_PATH \
    -H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "payment_hash": BASE64_ENCODED_VALUE, "attempt_id": <uint64>, "session_key": BASE64_ENCODED_VALUE, "hop_pubkeys": BASE64_ENCODED_VALUE }' \
    https://$REST_HOST/v2/switch/track

Messages

switchrpc.TrackOnionRequest

Source: switchrpc/switch.proto

Field	gRPC Type	REST Type	REST Placement
payment_hash The payment hash associated with the HTLC. This is needed for tracking and debugging purposes.	bytes	string	body
attempt_id The attempt ID uniquely identifying this payment attempt. The caller can expect to track results for the payment via this attempt ID.	uint64	string	body
session_key Optional: The session key that was used to construct the onion packet. This is required by the server to decrypt any failure message.	bytes	string	body
hop_pubkeys Optional: The public keys of the nodes in the route, used with the session_key to decrypt any failure message.	bytes[]	array	body

switchrpc.TrackOnionResponse

Source: switchrpc/switch.proto

Field	gRPC Type	REST Type
preimage The preimage obtained by making the payment. If this field is set, the payment succeeded.	bytes	string
failure_details The application-level failure for the payment attempt. If this field is set, the payment attempt failed.	FailureDetails	object

Nested Messages

switchrpc.FailureDetails

Field	gRPC Type	REST Type
error_message A human-readable error_message for logging or display.	string	string
local_failure local_failure is set when the failure originates at the local node (e.g. unable to forward due to insufficient balance, channel policy violations, or other link-level rejections). The wire message is available in plaintext without onion decryption.	LocalFailure	object
forwarding_failure forwarding_failure is set when the HTLC was forwarded into the network and a remote node returned an error. The onion error was successfully decrypted, yielding the failure source index. The wire_message may be empty if the inner failure could not be decoded.	ForwardingFailure	object
encrypted_error_data encrypted_error_data contains the raw onion-encrypted error blob. This is returned when no decryption keys were provided in the TrackOnionRequest (i.e. no session key or hop public keys), deferring decryption entirely to the client.	bytes	string
unreadable_failure unreadable_failure indicates that decryption keys were provided and decryption was attempted, but failed. The original error cannot be recovered.	UnreadableFailure	object
switch_error switch_error indicates an unexpected internal error that does not fall into any of the above categories.	SwitchError	object

switchrpc.ForwardingFailure

Field	gRPC Type	REST Type
failure_source_index failure_source_index is the 0-based index of the node within the payment route that reported the failure. Index 0 refers to the local node.	uint32	integer
wire_message The raw, serialized lnwire.FailureMessage reported by the failing node. This field may be empty if the failure message could not be decoded.	bytes	string

switchrpc.LocalFailure

Field	gRPC Type	REST Type
wire_message The raw, serialized `lnwire.FailureMessage`.	bytes	string

switchrpc.SwitchError

note

This response has no parameters.

switchrpc.UnreadableFailure

note

This response has no parameters.