MuSig2CreateSession

MuSig2CreateSession (experimental!) creates a new MuSig2 signing session using the local key identified by the key locator. The complete list of all public keys of all signing parties must be provided, including the public key of the local signing key. If nonces of other parties are already known, they can be submitted as well to reduce the number of RPC calls necessary later on.

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 MuSig2CreateSession (MuSig2SessionRequest) returns (MuSig2SessionResponse);

REST

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

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 = {
  key_loc: <KeyLocator>,
  all_signer_pubkeys: <bytes>,
  other_signer_public_nonces: <bytes>,
  tweaks: <TweakDesc>,
  taproot_tweak: <TaprootTweakDesc>,
  version: <MuSig2Version>,
  pregenerated_local_nonce: <bytes>,
};
client.muSig2CreateSession(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "session_id": <bytes>,
//    "combined_key": <bytes>,
//    "taproot_internal_key": <bytes>,
//    "local_public_nonces": <bytes>,
//    "have_all_nonces": <bool>,
//    "version": <MuSig2Version>,
//  }

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.MuSig2SessionRequest(
  key_loc=<KeyLocator>,
  all_signer_pubkeys=<bytes>,
  other_signer_public_nonces=<bytes>,
  tweaks=<TweakDesc>,
  taproot_tweak=<TaprootTweakDesc>,
  version=<MuSig2Version>,
  pregenerated_local_nonce=<bytes>,
)
response = stub.MuSig2CreateSession(request)
print(response)
# {
#    "session_id": <bytes>,
#    "combined_key": <bytes>,
#    "taproot_internal_key": <bytes>,
#    "local_public_nonces": <bytes>,
#    "have_all_nonces": <bool>,
#    "version": <MuSig2Version>,
# }

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 = {
  key_loc: <object>, // <KeyLocator> 
  all_signer_pubkeys: <array>, // <bytes> (base64 encoded)
  other_signer_public_nonces: <array>, // <bytes> (base64 encoded)
  tweaks: <array>, // <TweakDesc> 
  taproot_tweak: <object>, // <TaprootTweakDesc> 
  version: <string>, // <MuSig2Version> 
  pregenerated_local_nonce: <string>, // <bytes> (base64 encoded)
};
let options = {
  url: `https://${REST_HOST}/v2/signer/musig2/createsession`,
  // 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:
//  {
//    "session_id": <string>, // <bytes> 
//    "combined_key": <string>, // <bytes> 
//    "taproot_internal_key": <string>, // <bytes> 
//    "local_public_nonces": <string>, // <bytes> 
//    "have_all_nonces": <boolean>, // <bool> 
//    "version": <string>, // <MuSig2Version> 
//  }

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/createsession'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'key_loc': <KeyLocator>,
  'all_signer_pubkeys': base64.b64encode(<bytes>),
  'other_signer_public_nonces': base64.b64encode(<bytes>),
  'tweaks': <TweakDesc>,
  'taproot_tweak': <TaprootTweakDesc>,
  'version': <MuSig2Version>,
  'pregenerated_local_nonce': base64.b64encode(<bytes>),
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "session_id": <bytes>,
#    "combined_key": <bytes>,
#    "taproot_internal_key": <bytes>,
#    "local_public_nonces": <bytes>,
#    "have_all_nonces": <bool>,
#    "version": <MuSig2Version>,
# }

Shell

# There is no CLI command for this RPC

Messages

signrpc.MuSig2SessionRequest

Source: signrpc/signer.proto

Field	gRPC Type	REST Type	REST Placement
key_loc The key locator that identifies which key to use for signing.	KeyLocator	object	body
all_signer_pubkeys A list of all public keys (serialized in 32-byte x-only format for v0.4.0 and 33-byte compressed format for v1.0.0rc2!) 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
other_signer_public_nonces An optional list of all public nonces of other signing participants that might already be known.	bytes[]	array	body
tweaks A series of optional generic tweaks to be applied to 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
version The mandatory version of the MuSig2 BIP draft to use. This is necessary to differentiate between the changes that were made to the BIP while this experimental RPC was already released. Some of those changes affect how the combined key and nonces are created.	MuSig2Version	string	body
pregenerated_local_nonce A set of pre generated secret local nonces to use in the musig2 session. This field is optional. This can be useful for protocols that need to send nonces ahead of time before the set of signer keys are known. This value MUST be 97 bytes and be the concatenation of two CSPRNG generated 32 byte values and local public key used for signing as specified in the key_loc field.	bytes	string	body

signrpc.MuSig2SessionResponse

Source: signrpc/signer.proto

Field	gRPC Type	REST Type
session_id The unique ID that represents this signing session. A session can be used for producing a signature a single time. If the signing fails for any reason, a new session with the same participants needs to be created.	bytes	string
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
local_public_nonces The two public nonces the local signer uses, combined into a single value of 66 bytes. Can be split into the two 33-byte points to get the individual nonces.	bytes	string
have_all_nonces Indicates whether all nonces required to start the signing process are known now.	bool	boolean
version The version of the MuSig2 BIP that was used to create the session.	MuSig2Version	string

Nested Messages

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

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

Enums

signrpc.MuSig2Version

Name	Number
MUSIG2_VERSION_UNDEFINED The default value on the RPC is zero for enums so we need to represent an invalid/undefined version by default to make sure clients upgrade their software to set the version explicitly.	0
MUSIG2_VERSION_V040 The version of MuSig2 that lnd 0.15.x shipped with, which corresponds to the version v0.4.0 of the MuSig2 BIP draft.	1
MUSIG2_VERSION_V100RC2 The current version of MuSig2 which corresponds to the version v1.0.0rc2 of the MuSig2 BIP draft.	2