MuSig2CombineKeys

MuSig2CombineKeys (experimental!) is a stateless helper RPC that can be used to calculate the combined MuSig2 public key from a list of all participating signers' public keys. This RPC is completely stateless and deterministic and does not create any signing session. It can be used to determine the Taproot public key that should be put in an on-chain output once all public keys are known. A signing session is only needed later when that output should be spent again.

NOTE: The MuSig2 BIP is not final yet and therefore this API must be considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming releases. Backward compatibility is not guaranteed!

Source: signrpc/signer.proto

gRPC

rpc MuSig2CombineKeys (MuSig2CombineKeysRequest) returns (MuSig2CombineKeysResponse);

REST

HTTP Method	Path
POST	/v2/signer/musig2/combinekeys

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 = {
  all_signer_pubkeys: <bytes>,
  tweaks: <TweakDesc>,
  taproot_tweak: <TaprootTweakDesc>,
};
client.muSig2CombineKeys(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "combined_key": <bytes>,
//    "taproot_internal_key": <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.MuSig2CombineKeysRequest(
  all_signer_pubkeys=<bytes>,
  tweaks=<TweakDesc>,
  taproot_tweak=<TaprootTweakDesc>,
)
response = stub.MuSig2CombineKeys(request)
print(response)
# {
#    "combined_key": <bytes>,
#    "taproot_internal_key": <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 = {
  all_signer_pubkeys: <array>, // <bytes> (base64 encoded)
  tweaks: <array>, // <TweakDesc> 
  taproot_tweak: <object>, // <TaprootTweakDesc> 
};
let options = {
  url: `https://${REST_HOST}/v2/signer/musig2/combinekeys`,
  // 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:
//  {
//    "combined_key": <string>, // <bytes> 
//    "taproot_internal_key": <string>, // <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/musig2/combinekeys'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'all_signer_pubkeys': base64.b64encode(<bytes>),
  'tweaks': <TweakDesc>,
  'taproot_tweak': <TaprootTweakDesc>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "combined_key": <bytes>,
#    "taproot_internal_key": <bytes>,
# }

Shell

# There is no CLI command for this RPC

Messages

signrpc.MuSig2CombineKeysRequest

Source: signrpc/signer.proto

Field	gRPC Type	REST Type	REST Placement
all_signer_pubkeys A list of all public keys (serialized in 32-byte x-only format!) participating in the signing session. The list will always be sorted lexicographically internally. This must include the local key which is described by the above key_loc.	bytes[]	array	body
tweaks A series of optional generic tweaks to be applied to the the aggregated public key.	TweakDesc[]	array	body
taproot_tweak An optional taproot specific tweak that must be specified if the MuSig2 combined key will be used as the main taproot key of a taproot output on-chain.	TaprootTweakDesc	object	body

signrpc.MuSig2CombineKeysResponse

Source: signrpc/signer.proto

Field	gRPC Type	REST Type
combined_key The combined public key (in the 32-byte x-only format) with all tweaks applied to it. If a taproot tweak is specified, this corresponds to the taproot key that can be put into the on-chain output.	bytes	string
taproot_internal_key The raw combined public key (in the 32-byte x-only format) before any tweaks are applied to it. If a taproot tweak is specified, this corresponds to the internal key that needs to be put into the witness if the script spend path is used.	bytes	string

Nested Messages

signrpc.TweakDesc

Field	gRPC Type	REST Type
tweak Tweak is the 32-byte value that will modify the public key.	bytes	string
is_x_only Specifies if the target key should be converted to an x-only public key before tweaking. If true, then the public key will be mapped to an x-only key before the tweaking operation is applied.	bool	boolean

signrpc.TaprootTweakDesc

Field	gRPC Type	REST Type
script_root The root hash of the tapscript tree if a script path is committed to. If the MuSig2 key put on chain doesn't also commit to a script path (BIP-0086 key spend only), then this needs to be empty and the key_spend_only field below must be set to true. This is required because gRPC cannot differentiate between a zero-size byte slice and a nil byte slice (both would be serialized the same way). So the extra boolean is required.	bytes	string
key_spend_only Indicates that the above script_root is expected to be empty because this is a BIP-0086 key spend only commitment where only the internal key is committed to instead of also including a script root hash.	bool	boolean