SignOutputRaw

SignOutputRaw is a method that can be used to generated a signature for a set of inputs/outputs to a transaction. Each request specifies details concerning how the outputs should be signed, which keys they should be signed with, and also any optional tweaks. The return value is a fixed 64-byte signature (the same format as we use on the wire in Lightning).

If we are unable to sign using the specified keys, then an error will be returned.

Source: signrpc/signer.proto

gRPC

rpc SignOutputRaw (SignReq) returns (SignResp);

REST

HTTP Method	Path
POST	/v2/signer/signraw

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', 'signrpc/signer.proto'], loaderOptions);
const signrpc = grpc.loadPackageDefinition(packageDefinition).signrpc;
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 signrpc.Signer(GRPC_HOST, creds);
let request = {
  raw_tx_bytes: <bytes>,
  sign_descs: <SignDescriptor>,
  prev_outputs: <TxOut>,
};
client.signOutputRaw(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "raw_sigs": <bytes>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the signrpc/signer.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import signer_pb2 as signrpc, signer_pb2_grpc as signerstub

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 = signerstub.SignerStub(channel)
request = signrpc.SignReq(
  raw_tx_bytes=<bytes>,
  sign_descs=<SignDescriptor>,
  prev_outputs=<TxOut>,
)
response = stub.SignOutputRaw(request)
print(response)
# {
#    "raw_sigs": <bytes>,
# }

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 = {
  raw_tx_bytes: <string>, // <bytes> (base64 encoded)
  sign_descs: <array>, // <SignDescriptor> 
  prev_outputs: <array>, // <TxOut> 
};
let options = {
  url: `https://${REST_HOST}/v2/signer/signraw`,
  // 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:
//  {
//    "raw_sigs": <array>, // <bytes> 
//  }

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/signer/signraw'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'raw_tx_bytes': base64.b64encode(<bytes>),
  'sign_descs': <SignDescriptor>,
  'prev_outputs': <TxOut>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "raw_sigs": <bytes>,
# }

Shell

# There is no CLI command for this RPC

Messages

signrpc.SignReq

Source: signrpc/signer.proto

Field	gRPC Type	REST Type	REST Placement
raw_tx_bytes The raw bytes of the transaction to be signed.	bytes	string	body
sign_descs A set of sign descriptors, for each input to be signed.	SignDescriptor[]	array	body
prev_outputs The full list of UTXO information for each of the inputs being spent. This is required when spending one or more taproot (SegWit v1) outputs.	TxOut[]	array	body

signrpc.SignResp

Source: signrpc/signer.proto

Field	gRPC Type	REST Type
raw_sigs A set of signatures realized in a fixed 64-byte format ordered in ascending input order.	bytes[]	array

Nested Messages

signrpc.SignDescriptor

Field	gRPC Type	REST Type
key_desc A descriptor that precisely describes which key to use for signing. This may provide the raw public key directly, or require the Signer to re-derive the key according to the populated derivation path. Note that if the key descriptor was obtained through walletrpc.DeriveKey, then the key locator MUST always be provided, since the derived keys are not persisted unlike with DeriveNextKey.	KeyDescriptor	object
single_tweak A scalar value that will be added to the private key corresponding to the above public key to obtain the private key to be used to sign this input. This value is typically derived via the following computation: derivedKey = privkey + sha256(perCommitmentPoint || pubKey) mod N	bytes	string
double_tweak A private key that will be used in combination with its corresponding private key to derive the private key that is to be used to sign the target input. Within the Lightning protocol, this value is typically the commitment secret from a previously revoked commitment transaction. This value is in combination with two hash values, and the original private key to derive the private key to be used when signing. k = (privKeysha256(pubKey || tweakPub) + tweakPrivsha256(tweakPub || pubKey)) mod N	bytes	string
tap_tweak The 32 byte input to the taproot tweak derivation that is used to derive the output key from an internal key: outputKey = internalKey + tagged_hash("tapTweak", internalKey || tapTweak). When doing a BIP 86 spend, this field can be an empty byte slice. When doing a normal key path spend, with the output key committing to an actual script root, then this field should be: the tapscript root hash.	bytes	string
witness_script The full script required to properly redeem the output. This field will only be populated if a p2tr, p2wsh or a p2sh output is being signed. If a taproot script path spend is being attempted, then this should be the raw leaf script.	bytes	string
output A description of the output being spent. The value and script MUST be provided.	TxOut	object
sighash The target sighash type that should be used when generating the final sighash, and signature.	uint32	integer
input_index The target input within the transaction that should be signed.	int32	integer
sign_method The sign method specifies how the input should be signed. Depending on the method, either the tap_tweak, witness_script or both need to be specified. Defaults to SegWit v0 signing to be backward compatible with older RPC clients.	SignMethod	string

signrpc.KeyDescriptor

Field	gRPC Type	REST Type
raw_key_bytes The raw bytes of the public key in the key pair being identified. Either this or the KeyLocator must be specified.	bytes	string
key_loc The key locator that identifies which private key to use for signing. Either this or the raw bytes of the target public key must be specified.	KeyLocator	object

signrpc.KeyLocator

Field	gRPC Type	REST Type
key_family The family of key being identified.	int32	integer
key_index The precise index of the key being identified.	int32	integer

signrpc.TxOut

Field	gRPC Type	REST Type
value The value of the output being spent.	int64	string
pk_script The script of the output being spent.	bytes	string

Enums

signrpc.SignMethod

Name	Number
SIGN_METHOD_WITNESS_V0 Specifies that a SegWit v0 (p2wkh, np2wkh, p2wsh) input script should be signed.	0
SIGN_METHOD_TAPROOT_KEY_SPEND_BIP0086 Specifies that a SegWit v1 (p2tr) input should be signed by using the BIP0086 method (commit to internal key only).	1
SIGN_METHOD_TAPROOT_KEY_SPEND Specifies that a SegWit v1 (p2tr) input should be signed by using a given taproot hash to commit to in addition to the internal key.	2
SIGN_METHOD_TAPROOT_SCRIPT_SPEND Specifies that a SegWit v1 (p2tr) input should be spent using the script path and that a specific leaf script should be signed for.	3