lightning 7.0.7 → 7.1.0

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Versions
 
-## 7.0.7
+## 7.1.0
+
+- `signChainAddressMessage`: Add method to sign a message given a chain address
+- `verifyChainAddressMessage`: Add method to verify a chain address message
+
+## 7.0.8
 
 - `getChainAddresses`: Add method to get the list of chain addresses
 

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019-2022 Alex Bosworth
+Copyright (c) 2019-2023 Alex Bosworth
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -281,6 +281,8 @@ variables set:
       off-chain funds when an invoice has held funds from an incoming payment.
 - [signBytes](https://github.com/alexbosworth/ln-service#signbytes): Use node keys to sign over an
     arbitrary set of bytes.
+- [signChainAddressMessage](https://github.com/alexbosworth/ln-service#signchainaddressmessage):
+    Sign a message using the public key behind a chain address with ECDSA
 - [signMessage](https://github.com/alexbosworth/ln-service#signmessage): Use the node identity
     key to generate a signed message that represents the public graph node identity.
 - [signPsbt](https://github.com/alexbosworth/ln-service#signpsbt): Sign inputs and finalize a
@@ -363,5 +365,7 @@ variables set:
     channel fund recovery backups are valid.
 - [verifyBytesSignature](https://github.com/alexbosworth/ln-service#verifybytessignature): Check
     that a signature over arbitrary bytes is valid.
+- [verifyChainAddressMessage](https://github.com/alexbosworth/ln-service#verifychainaddressmessage):
+    Verify that a chain address message has a valid ECDSA signature
 - [verifyMessage](https://github.com/alexbosworth/ln-service#verifymessage): Check that a
     message from a node in the graph has a valid signature.

package/grpc/protos/router.proto

@@ -95,7 +95,9 @@ service Router {
 
     /*
     Deprecated. QueryProbability returns the current success probability
-    estimate for a given node pair and amount.
+    estimate for a given node pair and amount. The call returns a zero success
+    probability if no channel is available or if the amount violates min/max
+    HTLC constraints.
     */
     rpc QueryProbability (QueryProbabilityRequest)
         returns (QueryProbabilityResponse);
@@ -465,6 +467,93 @@ message SetMissionControlConfigResponse {
 }
 
 message MissionControlConfig {
+    /*
+    Deprecated, use AprioriParameters. The amount of time mission control will
+    take to restore a penalized node or channel back to 50% success probability,
+    expressed in seconds. Setting this value to a higher value will penalize
+    failures for longer, making mission control less likely to route through
+    nodes and channels that we have previously recorded failures for.
+    */
+    uint64 half_life_seconds = 1 [deprecated = true];
+
+    /*
+    Deprecated, use AprioriParameters. The probability of success mission
+    control should assign to hop in a route where it has no other information
+    available. Higher values will make mission control more willing to try hops
+    that we have no information about, lower values will discourage trying these
+    hops.
+    */
+    float hop_probability = 2 [deprecated = true];
+
+    /*
+    Deprecated, use AprioriParameters. The importance that mission control
+    should place on historical results, expressed as a value in [0;1]. Setting
+    this value to 1 will ignore all historical payments and just use the hop
+    probability to assess the probability of success for each hop. A zero value
+    ignores hop probability completely and relies entirely on historical
+    results, unless none are available.
+    */
+    float weight = 3 [deprecated = true];
+
+    /*
+    The maximum number of payment results that mission control will store.
+    */
+    uint32 maximum_payment_results = 4;
+
+    /*
+    The minimum time that must have passed since the previously recorded failure
+    before we raise the failure amount.
+    */
+    uint64 minimum_failure_relax_interval = 5;
+
+    enum ProbabilityModel {
+        APRIORI = 0;
+        BIMODAL = 1;
+    }
+
+    /*
+    ProbabilityModel defines which probability estimator should be used in
+    pathfinding.
+    */
+    ProbabilityModel Model = 6;
+
+    /*
+    EstimatorConfig is populated dependent on the estimator type.
+    */
+    oneof EstimatorConfig {
+        AprioriParameters apriori = 7;
+        BimodalParameters bimodal = 8;
+    }
+}
+
+message BimodalParameters {
+    /*
+    NodeWeight defines how strongly other previous forwardings on channels of a
+    router should be taken into account when computing a channel's probability
+    to route. The allowed values are in the range [0, 1], where a value of 0
+    means that only direct information about a channel is taken into account.
+    */
+    double node_weight = 1;
+
+    /*
+    ScaleMsat describes the scale over which channels statistically have some
+    liquidity left. The value determines how quickly the bimodal distribution
+    drops off from the edges of a channel. A larger value (compared to typical
+    channel capacities) means that the drop off is slow and that channel
+    balances are distributed more uniformly. A small value leads to the
+    assumption of very unbalanced channels.
+    */
+    uint64 scale_msat = 2;
+
+    /*
+    DecayTime describes the information decay of knowledge about previous
+    successes and failures in channels. The smaller the decay time, the quicker
+    we forget about past forwardings.
+    */
+    uint64 decay_time = 3;
+}
+
+message AprioriParameters {
     /*
     The amount of time mission control will take to restore a penalized node
     or channel back to 50% success probability, expressed in seconds. Setting
@@ -480,7 +569,7 @@ message MissionControlConfig {
     control more willing to try hops that we have no information about, lower
     values will discourage trying these hops.
     */
-    float hop_probability = 2;
+    double hop_probability = 2;
 
     /*
     The importance that mission control should place on historical results,
@@ -490,18 +579,7 @@ message MissionControlConfig {
     completely and relies entirely on historical results, unless none are
     available.
     */
-    float weight = 3;
-
-    /*
-    The maximum number of payment results that mission control will store.
-    */
-    uint32 maximum_payment_results = 4;
-
-    /*
-    The minimum time that must have passed since the previously recorded failure
-    before we raise the failure amount.
-    */
-    uint64 minimum_failure_relax_interval = 5;
+    double weight = 3;
 }
 
 message QueryProbabilityRequest {

package/index.js

@@ -106,6 +106,7 @@ const {sendToChainOutputScripts} = require('./lnd_methods');
 const {setAutopilot} = require('./lnd_methods');
 const {settleHodlInvoice} = require('./lnd_methods');
 const {signBytes} = require('./lnd_methods');
+const {signChainAddressMessage} = require('./lnd_methods');
 const {signMessage} = require('./lnd_methods');
 const {signPsbt} = require('./lnd_methods');
 const {signTransaction} = require('./lnd_methods');
@@ -147,6 +148,7 @@ const {verifyAccess} = require('./lnd_methods');
 const {verifyBackup} = require('./lnd_methods');
 const {verifyBackups} = require('./lnd_methods');
 const {verifyBytesSignature} = require('./lnd_methods');
+const {verifyChainAddressMessage} = require('./lnd_methods');
 const {verifyMessage} = require('./lnd_methods');
 
 module.exports = {
@@ -258,6 +260,7 @@ module.exports = {
   setAutopilot,
   settleHodlInvoice,
   signBytes,
+  signChainAddressMessage,
   signMessage,
   signPsbt,
   signTransaction,
@@ -299,5 +302,6 @@ module.exports = {
   verifyBackup,
   verifyBackups,
   verifyBytesSignature,
+  verifyChainAddressMessage,
   verifyMessage,
 };

package/lnd_methods/index.js

@@ -103,6 +103,7 @@ const {sendToChainOutputScripts} = require('./onchain');
 const {setAutopilot} = require('./onchain');
 const {settleHodlInvoice} = require('./invoices');
 const {signBytes} = require('./signer');
+const {signChainAddressMessage} = require('./onchain');
 const {signMessage} = require('./message');
 const {signPsbt} = require('./onchain');
 const {signTransaction} = require('./signer');
@@ -143,6 +144,7 @@ const {verifyAccess} = require('./macaroon');
 const {verifyBackup} = require('./offchain');
 const {verifyBackups} = require('./offchain');
 const {verifyBytesSignature} = require('./signer');
+const {verifyChainAddressMessage} = require('./onchain');
 const {verifyMessage} = require('./message');
 
 module.exports = {
@@ -251,6 +253,7 @@ module.exports = {
   setAutopilot,
   settleHodlInvoice,
   signBytes,
+  signChainAddressMessage,
   signMessage,
   signPsbt,
   signTransaction,
@@ -291,5 +294,6 @@ module.exports = {
   verifyBackup,
   verifyBackups,
   verifyBytesSignature,
+  verifyChainAddressMessage,
   verifyMessage,
 };

package/lnd_methods/macaroon/methods.json

@@ -413,6 +413,10 @@
     "method": "SignMessage",
     "type": "signer"
   },
+  "signChainAddressMessage": {
+    "method": "SignMessageWithAddr",
+    "type": "wallet"
+  },
   "signMessage": {
     "method": "SignMessage",
     "type": "default"
@@ -572,6 +576,10 @@
     "method": "VerifyMessage",
     "type": "signer"
   },
+  "verifyChainAddressMessage": {
+    "method": "VerifyMessageWithAddr",
+    "type": "wallet"
+  },
   "verifyMessage": {
     "method": "VerifyMessage",
     "type": "default"

package/lnd_methods/onchain/index.js

@@ -25,6 +25,7 @@ const sendToChainAddress = require('./send_to_chain_address');
 const sendToChainAddresses = require('./send_to_chain_addresses');
 const sendToChainOutputScripts = require('./send_to_chain_output_scripts');
 const setAutopilot = require('./set_autopilot');
+const signChainAddressMessage = require('./sign_chain_address_message');
 const signPsbt = require('./sign_psbt');
 const subscribeToBlocks = require('./subscribe_to_blocks');
 const subscribeToChainAddress = require('./subscribe_to_chain_address');
@@ -32,6 +33,7 @@ const subscribeToChainSpend = require('./subscribe_to_chain_spend');
 const subscribeToTransactions = require('./subscribe_to_transactions');
 const unlockUtxo = require('./unlock_utxo');
 const updateChainTransaction = require('./update_chain_transaction');
+const verifyChainAddressMessage = require('./verify_chain_address_message');
 
 module.exports = {
   broadcastChainTransaction,
@@ -61,6 +63,7 @@ module.exports = {
   sendToChainAddresses,
   sendToChainOutputScripts,
   setAutopilot,
+  signChainAddressMessage,
   signPsbt,
   subscribeToBlocks,
   subscribeToChainAddress,
@@ -68,4 +71,5 @@ module.exports = {
   subscribeToTransactions,
   unlockUtxo,
   updateChainTransaction,
+  verifyChainAddressMessage,
 };

package/lnd_methods/onchain/sign_chain_address_message.js

@@ -0,0 +1,80 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const base64AsHex = base64 => Buffer.from(base64, 'base64').toString('hex');
+const notSupportedError = 'unknown method SignMessageWithAddr for service walletrpc.WalletKit';
+const method = 'signMessageWithAddr';
+const utf8AsBuffer = utf8 => Buffer.from(utf8, 'utf8');
+const type = 'wallet';
+
+/** Sign a chain address message using ECDSA
+
+  Note: this method is not supported in LND versions 0.15.5 and below
+
+  Requires LND built with `walletrpc` tag
+
+  `onchain:write` permission is required
+
+  {
+    address: <Chain Address String>
+    lnd: <Authenticated LND API Object>
+    message: <Message To Sign String>
+  }
+
+  @returns via cbk or Promise
+  {
+    signature: <Hex Encoded Signature String>
+  }
+*/
+module.exports = ({address, lnd, message}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!address) {
+          return cbk([400, 'ExpectedChainAddressToSignChainAddressMessage']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedLndToSignChainAddressMessage']);
+        }
+
+        if (!message) {
+          return cbk([400, 'ExpectedMessageToSignChainAddressMessage']);
+        }
+
+        return cbk();
+      },
+
+      // Sign message
+      sign: ['validate', ({}, cbk) => {
+        return lnd[type][method]({
+          addr: address,
+          msg: utf8AsBuffer(message),
+        },
+        (err, res) => {
+          if (!!err && err.details === notSupportedError) {
+            return cbk([501, 'BackingLndDoesNotSupportSigningChainMessages']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedSignChainAddressMessageError', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseToSignChainAddrMessageRequest']);
+          }
+
+          if (!res.signature) {
+            return cbk([503, 'ExpectedSignatureForChainMessageSignRequest']);
+          }
+
+          return cbk(null, {signature: base64AsHex(res.signature)});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'sign'}, cbk));
+  });
+};

package/lnd_methods/onchain/verify_chain_address_message.js

@@ -0,0 +1,93 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const hexAsBase64 = hex => Buffer.from(hex, 'hex').toString('base64');
+const {isBuffer} = Buffer;
+const isHex = n => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const method = 'verifyMessageWithAddr';
+const notSupportedError = 'unknown method VerifyMessageWithAddr for service walletrpc.WalletKit';
+const utf8StringAsBuffer = str => Buffer.from(str, 'utf8');
+const type = 'wallet';
+
+/** Verify a chain address message using ECDSA
+
+  Note: this method is not supported in LND versions 0.15.5 and below
+
+  Requires LND built with `walletrpc` tag
+
+  `onchain:write` permission is required
+
+  {
+    address: <Chain Address String>
+    lnd: <Authenticated LND API Object>
+    message: <Message to Verify String>
+    signature: <Hex Encoded Signature String>
+  }
+
+  @returns via cbk or Promise
+  {
+    signed_by: <Public Key Hex String>
+  }
+*/
+module.exports = ({address, lnd, message, signature}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!address) {
+          return cbk([400, 'ExpectedChainAddressToVerifyChainAddressMessage']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedLndToVerifyChainAddressMessage']);
+        }
+
+        if (!message) {
+          return cbk([400, 'ExpectedChainAddressMessageToVerify']);
+        }
+
+        if (!isHex(signature)) {
+          return cbk([400, 'ExpectedHexSignatureToVerifyChainAddressMessage']);
+        }
+
+        return cbk();
+      },
+
+      // Check chain address message signature
+      verify: ['validate', ({}, cbk) => {
+        return lnd[type][method]({
+          addr: address,
+          msg: utf8StringAsBuffer(message),
+          signature: hexAsBase64(signature),
+        },
+        (err, res) => {
+          if (!!err && err.details === notSupportedError) {
+            return cbk([501, 'BackingLndDoesNotSupportVerifyingAddrMessages']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedVerifyChainAddrMessageError', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResultForVerifyChainMessageRequest']);
+          }
+
+          if (res.valid !== true) {
+            return cbk([400, 'InvalidSignatureReceivedForChainAddress']);
+          }
+
+          if (!isBuffer(res.pubkey)) {
+            return cbk([503, 'ExpectedPublicKeyInVerifyChainMessageResponse']);
+          }
+
+          return cbk(null, {signed_by: bufferAsHex(res.pubkey)});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'verify'}, cbk));
+  });
+};

package/package.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.8.8",
+    "@grpc/grpc-js": "1.8.9",
     "@grpc/proto-loader": "0.7.5",
     "@types/express": "4.17.17",
     "@types/node": "18.13.0",
@@ -26,7 +26,7 @@
     "invoices": "2.2.3",
     "psbt": "2.7.2",
     "tiny-secp256k1": "2.2.1",
-    "type-fest": "3.5.7"
+    "type-fest": "3.6.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -59,5 +59,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "7.0.7"
+  "version": "7.1.0"
 }

package/test/lnd_methods/onchain/test_sign_chain_address_message.js

@@ -0,0 +1,86 @@
+const {test} = require('@alexbosworth/tap');
+
+const {signChainAddressMessage} = require('./../../../');
+
+const makeArgs = override => {
+  const args = {
+    address: 'address',
+    lnd: {
+      wallet: {
+        signMessageWithAddr: ({}, cbk) => cbk(null, {signature: '12345'}),
+      },
+    },
+    message: 'message',
+  };
+
+  Object.keys(override).forEach(attr => args[attr] = override[attr]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({address: undefined}),
+    description: 'A chain address is required to sign a message',
+    error: [400, 'ExpectedChainAddressToSignChainAddressMessage'],
+  },
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND is required to sign a message',
+    error: [400, 'ExpectedLndToSignChainAddressMessage'],
+  },
+  {
+    args: makeArgs({message: undefined}),
+    description: 'A message is required to sign a message',
+    error: [400, 'ExpectedMessageToSignChainAddressMessage'],
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        wallet: {
+          signMessageWithAddr: ({}, cbk) => cbk({
+            details: 'unknown method SignMessageWithAddr for service walletrpc.WalletKit',
+          }),
+        },
+      },
+    }),
+    description: 'Unsupported error is returned',
+    error: [501, 'BackingLndDoesNotSupportSigningChainMessages'],
+  },
+  {
+    args: makeArgs({
+      lnd: {wallet: {signMessageWithAddr: ({}, cbk) => cbk('err')}},
+    }),
+    description: 'Unexpected error is returned',
+    error: [503, 'UnexpectedSignChainAddressMessageError', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: {wallet: {signMessageWithAddr: ({}, cbk) => cbk()}}}),
+    description: 'A response is expected',
+    error: [503, 'ExpectedResponseToSignChainAddrMessageRequest'],
+  },
+  {
+    args: makeArgs({
+      lnd: {wallet: {signMessageWithAddr: ({}, cbk) => cbk(null, {})}},
+    }),
+    description: 'A signature is expected',
+    error: [503, 'ExpectedSignatureForChainMessageSignRequest'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'Signature produced',
+    expected: {signature: 'd76df8'},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({end, rejects, strictSame}) => {
+    if (!!error) {
+      await rejects(() => signChainAddressMessage(args), error, 'Got error');
+    } else {
+      strictSame(await signChainAddressMessage(args), expected, 'Got result');
+    }
+
+    return end();
+  });
+});

package/test/lnd_methods/onchain/test_verify_chain_address_message.js

@@ -0,0 +1,110 @@
+const {test} = require('@alexbosworth/tap');
+
+const {verifyChainAddressMessage} = require('./../../../');
+
+const makeArgs = override => {
+  const args = {
+    address: 'address',
+    lnd: {
+      wallet: {
+        verifyMessageWithAddr: ({}, cbk) => cbk(null, {
+          pubkey: Buffer.alloc(1),
+          valid: true,
+        }),
+      },
+    },
+    message: 'message',
+    signature: '00',
+  };
+
+  Object.keys(override).forEach(attr => args[attr] = override[attr]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({address: undefined}),
+    description: 'A chain address is required to verify a message',
+    error: [400, 'ExpectedChainAddressToVerifyChainAddressMessage'],
+  },
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND is required to verify a message',
+    error: [400, 'ExpectedLndToVerifyChainAddressMessage'],
+  },
+  {
+    args: makeArgs({message: undefined}),
+    description: 'A message is required to verify a message',
+    error: [400, 'ExpectedChainAddressMessageToVerify'],
+  },
+  {
+    args: makeArgs({signature: undefined}),
+    description: 'A signature required to verify a message',
+    error: [400, 'ExpectedHexSignatureToVerifyChainAddressMessage'],
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        wallet: {
+          verifyMessageWithAddr: ({}, cbk) => cbk({
+            details: 'unknown method VerifyMessageWithAddr for service walletrpc.WalletKit',
+          }),
+        },
+      },
+    }),
+    description: 'Unsupported error is returned',
+    error: [501, 'BackingLndDoesNotSupportVerifyingAddrMessages'],
+  },
+  {
+    args: makeArgs({
+      lnd: {wallet: {verifyMessageWithAddr: ({}, cbk) => cbk('err')}},
+    }),
+    description: 'Unsupported error is returned',
+    error: [503, 'UnexpectedVerifyChainAddrMessageError', {err: 'err'}],
+  },
+  {
+    args: makeArgs({
+      lnd: {wallet: {verifyMessageWithAddr: ({}, cbk) => cbk()}},
+    }),
+    description: 'A response is expected',
+    error: [503, 'ExpectedResultForVerifyChainMessageRequest'],
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        wallet: {
+          verifyMessageWithAddr: ({}, cbk) => cbk(null, {valid: false}),
+        },
+      },
+    }),
+    description: 'A valid result is expected',
+    error: [400, 'InvalidSignatureReceivedForChainAddress'],
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        wallet: {verifyMessageWithAddr: ({}, cbk) => cbk(null, {valid: true})},
+      },
+    }),
+    description: 'A public key result is expected',
+    error: [503, 'ExpectedPublicKeyInVerifyChainMessageResponse'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'Signature validated',
+    expected: {signed_by: '00'},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({end, rejects, strictSame}) => {
+    if (!!error) {
+      await rejects(() => verifyChainAddressMessage(args), error, 'Got error');
+    } else {
+      strictSame(await verifyChainAddressMessage(args), expected, 'Got res');
+    }
+
+    return end();
+  });
+});