RegisterRPCMiddleware

RegisterRPCMiddleware adds a new gRPC middleware to the interceptor chain. A gRPC middleware is software component external to lnd that aims to add additional business logic to lnd by observing/intercepting/validating incoming gRPC client requests and (if needed) replacing/overwriting outgoing messages before they're sent to the client. When registering the middleware must identify itself and indicate what custom macaroon caveats it wants to be responsible for. Only requests that contain a macaroon with that specific custom caveat are then sent to the middleware for inspection. The other option is to register for the read-only mode in which all requests/responses are forwarded for interception to the middleware but the middleware is not allowed to modify any responses. As a security measure, no middleware can modify responses for requests made with unencumbered macaroons!

Source: lightning.proto

gRPC

info

This is a bidirectional-streaming RPC

rpc RegisterRPCMiddleware (stream RPCMiddlewareResponse) returns (stream RPCMiddlewareRequest);

REST

HTTP Method	Path
POST	/v1/middleware

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 = {
  ref_msg_id: <uint64>,
  register: <MiddlewareRegistration>,
  feedback: <InterceptFeedback>,
};
let call = client.registerRPCMiddleware({});
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:
//  {
//    "request_id": <uint64>,
//    "raw_macaroon": <bytes>,
//    "custom_caveat_condition": <string>,
//    "stream_auth": <StreamAuth>,
//    "request": <RPCMessage>,
//    "response": <RPCMessage>,
//    "reg_complete": <bool>,
//    "msg_id": <uint64>,
//  }

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)
# Define a generator that returns an Iterable of RPCMiddlewareResponse objects.
def request_generator():
    # Initialization code here.
    while True:
        # Parameters here can be set as arguments to the generator.
        request = lnrpc.RPCMiddlewareResponse(
            ref_msg_id=<uint64>,
            register=<MiddlewareRegistration>,
            feedback=<InterceptFeedback>,
        )
        yield request
        # Do things between iterations here.
request_iterable = request_generator()
for response in stub.RegisterRPCMiddleware(request_iterable):
  print(response)
# {
#    "request_id": <uint64>,
#    "raw_macaroon": <bytes>,
#    "custom_caveat_condition": <string>,
#    "stream_auth": <StreamAuth>,
#    "request": <RPCMessage>,
#    "response": <RPCMessage>,
#    "reg_complete": <bool>,
#    "msg_id": <uint64>,
# }

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 = {
  ref_msg_id: <unknown>, // <uint64> 
  register: <object>, // <MiddlewareRegistration> 
  feedback: <object>, // <InterceptFeedback> 
};
let options = {
  url: `https://${REST_HOST}/v1/middleware`,
  // 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:
//  {
//    "request_id": <string>, // <uint64> 
//    "raw_macaroon": <string>, // <bytes> 
//    "custom_caveat_condition": <string>, // <string> 
//    "stream_auth": <object>, // <StreamAuth> 
//    "request": <object>, // <RPCMessage> 
//    "response": <object>, // <RPCMessage> 
//    "reg_complete": <boolean>, // <bool> 
//    "msg_id": <string>, // <uint64> 
//  }



// --------------------------
// 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/middleware?method=POST`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
  ref_msg_id: <uint64>, // <uint64> 
  register: <MiddlewareRegistration>, // <MiddlewareRegistration> 
  feedback: <InterceptFeedback>, // <InterceptFeedback> 
};
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:
//  {
//    "request_id": <string>, // <uint64>
//    "raw_macaroon": <string>, // <bytes>
//    "custom_caveat_condition": <string>, // <string>
//    "stream_auth": <object>, // <StreamAuth>
//    "request": <object>, // <RPCMessage>
//    "response": <object>, // <RPCMessage>
//    "reg_complete": <boolean>, // <bool>
//    "msg_id": <string>, // <uint64>
//  }

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/middleware'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'ref_msg_id': <uint64>,
  'register': <MiddlewareRegistration>,
  'feedback': <InterceptFeedback>,
}
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)
# {
#    "request_id": <uint64>,
#    "raw_macaroon": <bytes>,
#    "custom_caveat_condition": <string>,
#    "stream_auth": <StreamAuth>,
#    "request": <RPCMessage>,
#    "response": <RPCMessage>,
#    "reg_complete": <bool>,
#    "msg_id": <uint64>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.RPCMiddlewareResponse

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
ref_msg_id The request message ID this response refers to. Must always be set when giving feedback to an intercept but is ignored for the initial registration message.	uint64	unknown	unknown
register The registration message identifies the middleware that's being registered in lnd. The registration message must be sent immediately after initiating the RegisterRpcMiddleware stream, otherwise lnd will time out the attempt and terminate the request. NOTE: The middleware will only receive interception messages for requests that contain a macaroon with the custom caveat that the middleware declares it is responsible for handling in the registration message! As a security measure, no middleware can intercept requests made with unencumbered macaroons!	MiddlewareRegistration	object	unknown
feedback The middleware received an interception request and gives feedback to it. The request_id indicates what message the feedback refers to.	InterceptFeedback	object	unknown

lnrpc.RPCMiddlewareRequest

Source: lightning.proto

Field	gRPC Type	REST Type
request_id The unique ID of the intercepted original gRPC request. Useful for mapping request to response when implementing full duplex message interception. For streaming requests, this will be the same ID for all incoming and outgoing middleware intercept messages of the same stream.	uint64	string
raw_macaroon The raw bytes of the complete macaroon as sent by the gRPC client in the original request. This might be empty for a request that doesn't require macaroons such as the wallet unlocker RPCs.	bytes	string
custom_caveat_condition The parsed condition of the macaroon's custom caveat for convenient access. This field only contains the value of the custom caveat that the handling middleware has registered itself for. The condition must be validated for messages of intercept_type stream_auth and request!	string	string
stream_auth Intercept stream authentication: each new streaming RPC call that is initiated against lnd and contains the middleware's custom macaroon caveat can be approved or denied based upon the macaroon in the stream header. This message will only be sent for streaming RPCs, unary RPCs must handle the macaroon authentication in the request interception to avoid an additional message round trip between lnd and the middleware.	StreamAuth	object
request Intercept incoming gRPC client request message: all incoming messages, both on streaming and unary RPCs, are forwarded to the middleware for inspection. For unary RPC messages the middleware is also expected to validate the custom macaroon caveat of the request.	RPCMessage	object
response Intercept outgoing gRPC response message: all outgoing messages, both on streaming and unary RPCs, are forwarded to the middleware for inspection and amendment. The response in this message is the original response as it was generated by the main RPC server. It can either be accepted (=forwarded to the client), replaced/overwritten with a new message of the same type, or replaced by an error message.	RPCMessage	object
reg_complete This is used to indicate to the client that the server has successfully registered the interceptor. This is only used in the very first message that the server sends to the client after the client sends the server the middleware registration message.	bool	boolean
msg_id The unique message ID of this middleware intercept message. There can be multiple middleware intercept messages per single gRPC request (one for the incoming request and one for the outgoing response) or gRPC stream (one for each incoming message and one for each outgoing response). This message ID must be referenced when responding (accepting/rejecting/modifying) to an intercept message.	uint64	string

Nested Messages

lnrpc.MiddlewareRegistration

Field	gRPC Type	REST Type
middleware_name The name of the middleware to register. The name should be as informative as possible and is logged on registration.	string	string
custom_macaroon_caveat_name The name of the custom macaroon caveat that this middleware is responsible for. Only requests/responses that contain a macaroon with the registered custom caveat are forwarded for interception to the middleware. The exception being the read-only mode: All requests/responses are forwarded to a middleware that requests read-only access but such a middleware won't be allowed to alter responses. As a security measure, no middleware can change responses to requests made with unencumbered macaroons! NOTE: Cannot be used at the same time as read_only_mode.	string	string
read_only_mode Instead of defining a custom macaroon caveat name a middleware can register itself for read-only access only. In that mode all requests/responses are forwarded to the middleware but the middleware isn't allowed to alter any of the responses. NOTE: Cannot be used at the same time as custom_macaroon_caveat_name.	bool	boolean

lnrpc.InterceptFeedback

Field	gRPC Type	REST Type
error The error to return to the user. If this is non-empty, the incoming gRPC stream/request is aborted and the error is returned to the gRPC client. If this value is empty, it means the middleware accepts the stream/request/ response and the processing of it can continue.	string	string
replace_response A boolean indicating that the gRPC message should be replaced/overwritten. This boolean is needed because in protobuf an empty message is serialized as a 0-length or nil byte slice and we wouldn't be able to distinguish between an empty replacement message and the "don't replace anything" case.	bool	boolean
replacement_serialized If the replace_response field is set to true, this field must contain the binary serialized gRPC message in the protobuf format.	bytes	string

lnrpc.StreamAuth

Field	gRPC Type	REST Type
method_full_uri The full URI (in the format /<rpcpackage>.<ServiceName>/MethodName, for example /lnrpc.Lightning/GetInfo) of the streaming RPC method that was just established.	string	string

lnrpc.RPCMessage

Field	gRPC Type	REST Type
method_full_uri The full URI (in the format /<rpcpackage>.<ServiceName>/MethodName, for example /lnrpc.Lightning/GetInfo) of the RPC method the message was sent to/from.	string	string
stream_rpc Indicates whether the message was sent over a streaming RPC method or not.	bool	boolean
type_name The full canonical gRPC name of the message type (in the format <rpcpackage>.TypeName, for example lnrpc.GetInfoRequest). In case of an error being returned from lnd, this simply contains the string "error".	string	string
serialized The full content of the gRPC message, serialized in the binary protobuf format.	bytes	string
is_error Indicates that the response from lnd was an error, not a gRPC response. If this is set to true then the type_name contains the string "error" and serialized contains the error string.	bool	boolean