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 output 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);
}

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;
}

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 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. In case
    taproot_key_spend is set to true then this value must correspond to the
    taproot root hash (in case of a tapscript output) or the tap hashed internal
    public key (in case of a BIP-0086 output).
    */
    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;

    /*
    Indicates that this should produce a signature that can be used for the key
    spend path of a taproot input. This requires the witness_script field to be
    set to the taproot root hash (in case of a tapscript output) or the tap
    hashed internal public key (in case of a BIP-0086 output).
    */
    bool taproot_key_spend = 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.
    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.
    */
    bool compact_sig = 4;
}
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.
    bytes msg = 1;

    /*
    The fixed-size LN wire encoded signature to be verified over the given
    message.
    */
    bytes signature = 2;

    // The public key the signature has to be valid for.
    bytes pubkey = 3;
}
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;
}