98da6c61c1
This is meant to handle a quirk in which key descriptors obtained through walletrpc.DeriveKey don't result in the derived key being persisted to the wallet's database, unlike with DeriveNextKey. Due to this and some fallback logic in the wallet with regards to empty key locators, if a request only specified the compressed public key, the signature returned would be over a different key, namely the one derived from (family=0, index=0).
441 lines
15 KiB
JSON
441 lines
15 KiB
JSON
{
|
|
"swagger": "2.0",
|
|
"info": {
|
|
"title": "signrpc/signer.proto",
|
|
"version": "version not set"
|
|
},
|
|
"consumes": [
|
|
"application/json"
|
|
],
|
|
"produces": [
|
|
"application/json"
|
|
],
|
|
"paths": {
|
|
"/v2/signer/inputscript": {
|
|
"post": {
|
|
"summary": "ComputeInputScript generates a complete InputIndex for the passed\ntransaction with the signature as defined within the passed SignDescriptor.\nThis method should be capable of generating the proper input script for\nboth regular p2wkh output and p2wkh outputs nested within a regular p2sh\noutput.",
|
|
"description": "Note that when using this method to sign inputs belonging to the wallet,\nthe only items of the SignDescriptor that need to be populated are pkScript\nin the TxOut field, the value in that same field, and finally the input\nindex.",
|
|
"operationId": "ComputeInputScript",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcInputScriptResp"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "body",
|
|
"in": "body",
|
|
"required": true,
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcSignReq"
|
|
}
|
|
}
|
|
],
|
|
"tags": [
|
|
"Signer"
|
|
]
|
|
}
|
|
},
|
|
"/v2/signer/sharedkey": {
|
|
"post": {
|
|
"summary": "DeriveSharedKey returns a shared secret key by performing Diffie-Hellman key\nderivation between the ephemeral public key in the request and the node's\nkey specified in the key_loc parameter (or the node's identity private key\nif no key locator is specified):\nP_shared = privKeyNode * ephemeralPubkey\nThe resulting shared public key is serialized in the compressed format and\nhashed with sha256, resulting in the final key length of 256bit.",
|
|
"operationId": "DeriveSharedKey",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcSharedKeyResponse"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "body",
|
|
"in": "body",
|
|
"required": true,
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcSharedKeyRequest"
|
|
}
|
|
}
|
|
],
|
|
"tags": [
|
|
"Signer"
|
|
]
|
|
}
|
|
},
|
|
"/v2/signer/signmessage": {
|
|
"post": {
|
|
"summary": "SignMessage signs a message with the key specified in the key locator. The\nreturned signature is fixed-size LN wire format encoded.",
|
|
"description": "The main difference to SignMessage in the main RPC is that a specific key is\nused to sign the message instead of the node identity private key.",
|
|
"operationId": "SignMessage",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcSignMessageResp"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "body",
|
|
"in": "body",
|
|
"required": true,
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcSignMessageReq"
|
|
}
|
|
}
|
|
],
|
|
"tags": [
|
|
"Signer"
|
|
]
|
|
}
|
|
},
|
|
"/v2/signer/signraw": {
|
|
"post": {
|
|
"summary": "SignOutputRaw is a method that can be used to generated a signature for a\nset of inputs/outputs to a transaction. Each request specifies details\nconcerning how the outputs should be signed, which keys they should be\nsigned with, and also any optional tweaks. The return value is a fixed\n64-byte signature (the same format as we use on the wire in Lightning).",
|
|
"description": "If we are unable to sign using the specified keys, then an error will be\nreturned.",
|
|
"operationId": "SignOutputRaw",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcSignResp"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "body",
|
|
"in": "body",
|
|
"required": true,
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcSignReq"
|
|
}
|
|
}
|
|
],
|
|
"tags": [
|
|
"Signer"
|
|
]
|
|
}
|
|
},
|
|
"/v2/signer/verifymessage": {
|
|
"post": {
|
|
"summary": "VerifyMessage verifies a signature over a message using the public key\nprovided. The signature must be fixed-size LN wire format encoded.",
|
|
"description": "The main difference to VerifyMessage in the main RPC is that the public key\nused to sign the message does not have to be a node known to the network.",
|
|
"operationId": "VerifyMessage",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcVerifyMessageResp"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "body",
|
|
"in": "body",
|
|
"required": true,
|
|
"schema": {
|
|
"$ref": "#/definitions/signrpcVerifyMessageReq"
|
|
}
|
|
}
|
|
],
|
|
"tags": [
|
|
"Signer"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"definitions": {
|
|
"protobufAny": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type_url": {
|
|
"type": "string"
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"format": "byte"
|
|
}
|
|
}
|
|
},
|
|
"runtimeError": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string"
|
|
},
|
|
"code": {
|
|
"type": "integer",
|
|
"format": "int32"
|
|
},
|
|
"message": {
|
|
"type": "string"
|
|
},
|
|
"details": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/protobufAny"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"signrpcInputScript": {
|
|
"type": "object",
|
|
"properties": {
|
|
"witness": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string",
|
|
"format": "byte"
|
|
},
|
|
"description": "The serializes witness stack for the specified input."
|
|
},
|
|
"sig_script": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The optional sig script for the specified witness that will only be set if\nthe input specified is a nested p2sh witness program."
|
|
}
|
|
}
|
|
},
|
|
"signrpcInputScriptResp": {
|
|
"type": "object",
|
|
"properties": {
|
|
"input_scripts": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/signrpcInputScript"
|
|
},
|
|
"description": "The set of fully valid input scripts requested."
|
|
}
|
|
}
|
|
},
|
|
"signrpcKeyDescriptor": {
|
|
"type": "object",
|
|
"properties": {
|
|
"raw_key_bytes": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The raw bytes of the key being identified. Either this or the KeyLocator\nmust be specified."
|
|
},
|
|
"key_loc": {
|
|
"$ref": "#/definitions/signrpcKeyLocator",
|
|
"description": "The key locator that identifies which key to use for signing. Either this\nor the raw bytes of the target key must be specified."
|
|
}
|
|
}
|
|
},
|
|
"signrpcKeyLocator": {
|
|
"type": "object",
|
|
"properties": {
|
|
"key_family": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "The family of key being identified."
|
|
},
|
|
"key_index": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "The precise index of the key being identified."
|
|
}
|
|
}
|
|
},
|
|
"signrpcSharedKeyRequest": {
|
|
"type": "object",
|
|
"properties": {
|
|
"ephemeral_pubkey": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The ephemeral public key to use for the DH key derivation."
|
|
},
|
|
"key_loc": {
|
|
"$ref": "#/definitions/signrpcKeyLocator",
|
|
"description": "The optional key locator of the local key that should be used. If this\nparameter is not set then the node's identity private key will be used."
|
|
}
|
|
}
|
|
},
|
|
"signrpcSharedKeyResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"shared_key": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The shared public key, hashed with sha256."
|
|
}
|
|
}
|
|
},
|
|
"signrpcSignDescriptor": {
|
|
"type": "object",
|
|
"properties": {
|
|
"key_desc": {
|
|
"$ref": "#/definitions/signrpcKeyDescriptor",
|
|
"description": "A descriptor that precisely describes *which* key to use for signing. This\nmay provide the raw public key directly, or require the Signer to re-derive\nthe key according to the populated derivation path.\n\nNote that if the key descriptor was obtained through walletrpc.DeriveKey,\nthen the key locator MUST always be provided, since the derived keys are not\npersisted unlike with DeriveNextKey."
|
|
},
|
|
"single_tweak": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "derivedKey = privkey + sha256(perCommitmentPoint || pubKey) mod N",
|
|
"title": "A scalar value that will be added to the private key corresponding to the\nabove public key to obtain the private key to be used to sign this input.\nThis value is typically derived via the following computation:"
|
|
},
|
|
"double_tweak": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "A private key that will be used in combination with its corresponding\nprivate key to derive the private key that is to be used to sign the target\ninput. Within the Lightning protocol, this value is typically the\ncommitment secret from a previously revoked commitment transaction. This\nvalue is in combination with two hash values, and the original private key\nto derive the private key to be used when signing.\n\nk = (privKey*sha256(pubKey || tweakPub) +\ntweakPriv*sha256(tweakPub || pubKey)) mod N"
|
|
},
|
|
"witness_script": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The full script required to properly redeem the output. This field will\nonly be populated if a p2wsh or a p2sh output is being signed."
|
|
},
|
|
"output": {
|
|
"$ref": "#/definitions/signrpcTxOut",
|
|
"description": "A description of the output being spent. The value and script MUST be\nprovided."
|
|
},
|
|
"sighash": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "The target sighash type that should be used when generating the final\nsighash, and signature."
|
|
},
|
|
"input_index": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "The target input within the transaction that should be signed."
|
|
}
|
|
}
|
|
},
|
|
"signrpcSignMessageReq": {
|
|
"type": "object",
|
|
"properties": {
|
|
"msg": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The message to be signed."
|
|
},
|
|
"key_loc": {
|
|
"$ref": "#/definitions/signrpcKeyLocator",
|
|
"description": "The key locator that identifies which key to use for signing."
|
|
}
|
|
}
|
|
},
|
|
"signrpcSignMessageResp": {
|
|
"type": "object",
|
|
"properties": {
|
|
"signature": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The signature for the given message in the fixed-size LN wire format."
|
|
}
|
|
}
|
|
},
|
|
"signrpcSignReq": {
|
|
"type": "object",
|
|
"properties": {
|
|
"raw_tx_bytes": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The raw bytes of the transaction to be signed."
|
|
},
|
|
"sign_descs": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/signrpcSignDescriptor"
|
|
},
|
|
"description": "A set of sign descriptors, for each input to be signed."
|
|
}
|
|
}
|
|
},
|
|
"signrpcSignResp": {
|
|
"type": "object",
|
|
"properties": {
|
|
"raw_sigs": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string",
|
|
"format": "byte"
|
|
},
|
|
"description": "A set of signatures realized in a fixed 64-byte format ordered in ascending\ninput order."
|
|
}
|
|
}
|
|
},
|
|
"signrpcTxOut": {
|
|
"type": "object",
|
|
"properties": {
|
|
"value": {
|
|
"type": "string",
|
|
"format": "int64",
|
|
"description": "The value of the output being spent."
|
|
},
|
|
"pk_script": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The script of the output being spent."
|
|
}
|
|
}
|
|
},
|
|
"signrpcVerifyMessageReq": {
|
|
"type": "object",
|
|
"properties": {
|
|
"msg": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The message over which the signature is to be verified."
|
|
},
|
|
"signature": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The fixed-size LN wire encoded signature to be verified over the given\nmessage."
|
|
},
|
|
"pubkey": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The public key the signature has to be valid for."
|
|
}
|
|
}
|
|
},
|
|
"signrpcVerifyMessageResp": {
|
|
"type": "object",
|
|
"properties": {
|
|
"valid": {
|
|
"type": "boolean",
|
|
"format": "boolean",
|
|
"description": "Whether the signature was valid over the given message."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|