lnd/lnrpc/signrpc/signer.proto

syntax = "proto3";

package signrpc;

option go_package = "github.com/lightningnetwork/lnd/lnrpc/signrpc";

// Signer is a service that gives access to the signing functionality of the
// daemon's wallet.
service Signer {
    /*
    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.
    */
    rpc SignOutputRaw (SignReq) returns (SignResp);

    /*
    ComputeInputScript generates a complete InputIndex for the passed
    transaction with the signature as defined within the passed SignDescriptor.
    This method should be capable of generating the proper input script for both
    regular p2wkh/p2tr outputs and p2wkh outputs nested within a regular p2sh
    output.

    Note that when using this method to sign inputs belonging to the wallet,
    the only items of the SignDescriptor that need to be populated are pkScript
    in the TxOut field, the value in that same field, and finally the input
    index.
    */
    rpc ComputeInputScript (SignReq) returns (InputScriptResp);

    /*
    SignMessage signs a message with the key specified in the key locator. The
    returned signature is fixed-size LN wire format encoded.

    The main difference to SignMessage in the main RPC is that a specific key is
    used to sign the message instead of the node identity private key.
    */
    rpc SignMessage (SignMessageReq) returns (SignMessageResp);

    /*
    VerifyMessage verifies a signature over a message using the public key
    provided. The signature must be fixed-size LN wire format encoded.

    The main difference to VerifyMessage in the main RPC is that the public key
    used to sign the message does not have to be a node known to the network.
    */
    rpc VerifyMessage (VerifyMessageReq) returns (VerifyMessageResp);

    /*
    DeriveSharedKey returns a shared secret key by performing Diffie-Hellman key
    derivation between the ephemeral public key in the request and the node's
    key specified in the key_desc parameter. Either a key locator or a raw
    public key is expected in the key_desc, if neither is supplied, defaults to
    the node's identity private key:
        P_shared = privKeyNode * ephemeralPubkey
    The resulting shared public key is serialized in the compressed format and
    hashed with sha256, resulting in the final key length of 256bit.
    */
    rpc DeriveSharedKey (SharedKeyRequest) returns (SharedKeyResponse);

    /*
    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!
    */
    rpc MuSig2CombineKeys (MuSig2CombineKeysRequest)
        returns (MuSig2CombineKeysResponse);

    /*
    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!
    */
    rpc MuSig2CreateSession (MuSig2SessionRequest)
        returns (MuSig2SessionResponse);

    /*
    MuSig2RegisterNonces (experimental!) registers one or more public nonces of
    other signing participants for a session identified by its ID. This RPC can
    be called multiple times until all nonces are registered.

    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!
    */
    rpc MuSig2RegisterNonces (MuSig2RegisterNoncesRequest)
        returns (MuSig2RegisterNoncesResponse);

    /*
    MuSig2Sign (experimental!) creates a partial signature using the local
    signing key that was specified when the session was created. This can only
    be called when all public nonces of all participants are known and have been
    registered with the session. If this node isn't responsible for combining
    all the partial signatures, then the cleanup flag should be set, indicating
    that the session can be removed from memory once the signature was produced.

    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!
    */
    rpc MuSig2Sign (MuSig2SignRequest) returns (MuSig2SignResponse);

    /*
    MuSig2CombineSig (experimental!) combines the given partial signature(s)
    with the local one, if it already exists. Once a partial signature of all
    participants is registered, the final signature will be combined and
    returned.

    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!
    */
    rpc MuSig2CombineSig (MuSig2CombineSigRequest)
        returns (MuSig2CombineSigResponse);

    /*
    MuSig2Cleanup (experimental!) allows a caller to clean up a session early in
    cases where it's obvious that the signing session won't succeed and the
    resources can be released.

    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!
    */
    rpc MuSig2Cleanup (MuSig2CleanupRequest) returns (MuSig2CleanupResponse);
}

message KeyLocator {
    // The family of key being identified.
    int32 key_family = 1;

    // The precise index of the key being identified.
    int32 key_index = 2;
}

message KeyDescriptor {
    /*
    The raw bytes of the public key in the key pair being identified. Either
    this or the KeyLocator must be specified.
    */
    bytes raw_key_bytes = 1;

    /*
    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 key_loc = 2;
}

message TxOut {
    // The value of the output being spent.
    int64 value = 1;

    // The script of the output being spent.
    bytes pk_script = 2;
}

enum SignMethod {
    /*
    Specifies that a SegWit v0 (p2wkh, np2wkh, p2wsh) input script should be
    signed.
    */
    SIGN_METHOD_WITNESS_V0 = 0;

    /*
    Specifies that a SegWit v1 (p2tr) input should be signed by using the
    BIP0086 method (commit to internal key only).
    */
    SIGN_METHOD_TAPROOT_KEY_SPEND_BIP0086 = 1;

    /*
    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.
    */
    SIGN_METHOD_TAPROOT_KEY_SPEND = 2;

    /*
    Specifies that a SegWit v1 (p2tr) input should be spent using the script
    path and that a specific leaf script should be signed for.
    */
    SIGN_METHOD_TAPROOT_SCRIPT_SPEND = 3;
}

message SignDescriptor {
    /*
    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 key_desc = 1;

    /*
    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 single_tweak = 2;

    /*
    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 = (privKey*sha256(pubKey || tweakPub) +
           tweakPriv*sha256(tweakPub || pubKey)) mod N
    */
    bytes double_tweak = 3;

    /*
    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 tap_tweak = 10;

    /*
    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 witness_script = 4;

    /*
    A description of the output being spent. The value and script MUST be
    provided.
    */
    TxOut output = 5;

    /*
    The target sighash type that should be used when generating the final
    sighash, and signature.
    */
    uint32 sighash = 7;

    /*
    The target input within the transaction that should be signed.
    */
    int32 input_index = 8;

    /*
    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 sign_method = 9;
}

message SignReq {
    // The raw bytes of the transaction to be signed.
    bytes raw_tx_bytes = 1;

    // A set of sign descriptors, for each input to be signed.
    repeated SignDescriptor sign_descs = 2;

    /*
    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.
    */
    repeated TxOut prev_outputs = 3;
}

message SignResp {
    /*
    A set of signatures realized in a fixed 64-byte format ordered in ascending
    input order.
    */
    repeated bytes raw_sigs = 1;
}

message InputScript {
    // The serializes witness stack for the specified input.
    repeated bytes witness = 1;

    /*
    The optional sig script for the specified witness that will only be set if
    the input specified is a nested p2sh witness program.
    */
    bytes sig_script = 2;
}

message InputScriptResp {
    // The set of fully valid input scripts requested.
    repeated InputScript input_scripts = 1;
}

message SignMessageReq {
    /*
    The message to be signed. When using REST, this field must be encoded as
    base64.
    */
    bytes msg = 1;

    // The key locator that identifies which key to use for signing.
    KeyLocator key_loc = 2;

    // Double-SHA256 hash instead of just the default single round.
    bool double_hash = 3;

    /*
    Use the compact (pubkey recoverable) format instead of the raw lnwire
    format. This option cannot be used with Schnorr signatures.
    */
    bool compact_sig = 4;

    /*
    Use Schnorr signature. This option cannot be used with compact format.
    */
    bool schnorr_sig = 5;

    /*
    The optional Taproot tweak bytes to apply to the private key before creating
    a Schnorr signature. The private key is tweaked as described in BIP-341:
    privKey + h_tapTweak(internalKey || tapTweak)
    */
    bytes schnorr_sig_tap_tweak = 6;

    /*
    An optional tag that can be provided when taking a tagged hash of a
    message. This option can only be used when schnorr_sig is true.
    */
    bytes tag = 7;
}
message SignMessageResp {
    /*
    The signature for the given message in the fixed-size LN wire format.
    */
    bytes signature = 1;
}

message VerifyMessageReq {
    // The message over which the signature is to be verified. When using
    // REST, this field must be encoded as base64.
    bytes msg = 1;

    /*
    The fixed-size LN wire encoded signature to be verified over the given
    message. When using REST, this field must be encoded as base64.
    */
    bytes signature = 2;

    /*
    The public key the signature has to be valid for. When using REST, this
    field must be encoded as base64. If the is_schnorr_sig option is true, then
    the public key is expected to be in the 32-byte x-only serialization
    according to BIP-340.
    */
    bytes pubkey = 3;

    /*
    Specifies if the signature is a Schnorr signature.
    */
    bool is_schnorr_sig = 4;

    /*
    An optional tag that can be provided when taking a tagged hash of a
    message. This option can only be used when is_schnorr_sig is true.
    */
    bytes tag = 5;
}

message VerifyMessageResp {
    // Whether the signature was valid over the given message.
    bool valid = 1;
}

message SharedKeyRequest {
    // The ephemeral public key to use for the DH key derivation.
    bytes ephemeral_pubkey = 1;

    /*
    Deprecated. The optional key locator of the local key that should be used.
    If this parameter is not set then the node's identity private key will be
    used.
    */
    KeyLocator key_loc = 2 [deprecated = true];

    /*
    A key descriptor describes the key used for performing ECDH. Either a key
    locator or a raw public key is expected, if neither is supplied, defaults to
    the node's identity private key.
    */
    KeyDescriptor key_desc = 3;
}

message SharedKeyResponse {
    // The shared public key, hashed with sha256.
    bytes shared_key = 1;
}

message TweakDesc {
    /*
    Tweak is the 32-byte value that will modify the public key.
    */
    bytes tweak = 1;

    /*
    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 is_x_only = 2;
}

message TaprootTweakDesc {
    /*
    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 script_root = 1;

    /*
    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 key_spend_only = 2;
}

enum MuSig2Version {
    /*
    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.
    */
    MUSIG2_VERSION_UNDEFINED = 0;

    /*
    The version of MuSig2 that lnd 0.15.x shipped with, which corresponds to the
    version v0.4.0 of the MuSig2 BIP draft.
    */
    MUSIG2_VERSION_V040 = 1;

    /*
    The current version of MuSig2 which corresponds to the version v1.0.0rc2 of
    the MuSig2 BIP draft.
    */
    MUSIG2_VERSION_V100RC2 = 2;
}

message MuSig2CombineKeysRequest {
    /*
    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.
    */
    repeated bytes all_signer_pubkeys = 1;

    /*
    A series of optional generic tweaks to be applied to the aggregated
    public key.
    */
    repeated TweakDesc tweaks = 2;

    /*
    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 taproot_tweak = 3;

    /*
    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 version = 4;
}

message MuSig2CombineKeysResponse {
    /*
    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 combined_key = 1;

    /*
    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 taproot_internal_key = 2;

    /*
    The version of the MuSig2 BIP that was used to combine the keys.
    */
    MuSig2Version version = 4;
}

message MuSig2SessionRequest {
    /*
    The key locator that identifies which key to use for signing.
    */
    KeyLocator key_loc = 1;

    /*
    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.
    */
    repeated bytes all_signer_pubkeys = 2;

    /*
    An optional list of all public nonces of other signing participants that
    might already be known.
    */
    repeated bytes other_signer_public_nonces = 3;

    /*
    A series of optional generic tweaks to be applied to the aggregated
    public key.
    */
    repeated TweakDesc tweaks = 4;

    /*
    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 taproot_tweak = 5;

    /*
    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 version = 6;

    /*
    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 pregenerated_local_nonce = 7;
}

message MuSig2SessionResponse {
    /*
    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 session_id = 1;

    /*
    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 combined_key = 2;

    /*
    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 taproot_internal_key = 3;

    /*
    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 local_public_nonces = 4;

    /*
    Indicates whether all nonces required to start the signing process are known
    now.
    */
    bool have_all_nonces = 5;

    /*
    The version of the MuSig2 BIP that was used to create the session.
    */
    MuSig2Version version = 6;
}

message MuSig2RegisterNoncesRequest {
    /*
    The unique ID of the signing session those nonces should be registered with.
    */
    bytes session_id = 1;

    /*
    A list of all public nonces of other signing participants that should be
    registered.
    */
    repeated bytes other_signer_public_nonces = 3;
}

message MuSig2RegisterNoncesResponse {
    /*
    Indicates whether all nonces required to start the signing process are known
    now.
    */
    bool have_all_nonces = 1;
}

message MuSig2SignRequest {
    /*
    The unique ID of the signing session to use for signing.
    */
    bytes session_id = 1;

    /*
    The 32-byte SHA256 digest of the message to sign.
    */
    bytes message_digest = 2;

    /*
    Cleanup indicates that after signing, the session state can be cleaned up,
    since another participant is going to be responsible for combining the
    partial signatures.
    */
    bool cleanup = 3;
}

message MuSig2SignResponse {
    /*
    The partial signature created by the local signer.
    */
    bytes local_partial_signature = 1;
}

message MuSig2CombineSigRequest {
    /*
    The unique ID of the signing session to combine the signatures for.
    */
    bytes session_id = 1;

    /*
    The list of all other participants' partial signatures to add to the current
    session.
    */
    repeated bytes other_partial_signatures = 2;
}

message MuSig2CombineSigResponse {
    /*
    Indicates whether all partial signatures required to create a final, full
    signature are known yet. If this is true, then the final_signature field is
    set, otherwise it is empty.
    */
    bool have_all_signatures = 1;

    /*
    The final, full signature that is valid for the combined public key.
    */
    bytes final_signature = 2;
}

message MuSig2CleanupRequest {
    /*
    The unique ID of the signing session that should be removed/cleaned up.
    */
    bytes session_id = 1;
}

message MuSig2CleanupResponse {
}