lightning 4.12.0 → 4.13.1

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Versions
 
-## 4.12.0
+## 4.13.1
+
+- Add `sendMessageToPeer` to send a peer to peer message to a connected peer
+- Add `subscribeToPeerMessages` to listen to messages from connected peers
+
+## 4.12.2
 
 - `probeForRoute`, `subscribeToProbeForRoute`, `subscribeToPayViaRoutes`,
     `payViaRoutes`: When probing (no hash), delete the payment failure record after the probe

package/README.md

@@ -225,6 +225,8 @@ Methods exported by this library support typescript, but ln-service includes add
     Ask for a CPFP chain fee rate increase on a pending confirm UTXO.
 - [revokeAccess](https://github.com/alexbosworth/ln-service#revokeaccess): Remove the access
     privileges of a previously issued access token macaroon credential.
+- [sendMessageToPeer](https://github.com/alexbosworth/ln-service#sendmessagetopeer): Send
+    message to a connected peer.
 - [sendToChainAddress](https://github.com/alexbosworth/ln-service#sendtochainaddress): Send
     funds on-chain to an address.
 - [sendToChainAddresses](https://github.com/alexbosworth/ln-service#sendtochainaddresses):
@@ -277,6 +279,8 @@ Methods exported by this library support typescript, but ln-service includes add
     Make an off-chain payment using a payment request and subscribe to the payment status.
 - [subscribeToPayViaRoutes](https://github.com/alexbosworth/ln-service#subscribetopayviaroutes):
     Start an off-chain payment using specific payment routes and subscribe to the payment result.
+- [subscribeToPeerMessages](https://github.com/alexbosworth/ln-service#subscribetopeermessages):
+    Listen for incoming peer messages.
 - [subscribeToPeers](https://github.com/alexbosworth/ln-service#subscribetopeers): Listen to peer
     disconnect and connect events.
 - [subscribeToProbeForRoute](https://github.com/alexbosworth/ln-service#subscribetoprobeforroute):

package/grpc/protos/invoices.proto

@@ -35,6 +35,12 @@ service Invoices {
     settled, this call will succeed.
     */
     rpc SettleInvoice (SettleInvoiceMsg) returns (SettleInvoiceResp);
+
+    /*
+    LookupInvoiceV2 attempts to look up at invoice. An invoice can be refrenced
+    using either its payment hash, payment address, or set ID.
+    */
+    rpc LookupInvoiceV2 (LookupInvoiceMsg) returns (lnrpc.Invoice);
 }
 
 message CancelInvoiceMsg {
@@ -134,4 +140,33 @@ message SubscribeSingleInvoiceRequest {
 
     // Hash corresponding to the (hold) invoice to subscribe to.
     bytes r_hash = 2;
+}
+
+enum LookupModifier {
+    // The default look up modifier, no look up behavior is changed.
+    DEFAULT = 0;
+
+    /*
+    Indicates that when a look up is done based on a set_id, then only that set
+    of HTLCs related to that set ID should be returned.
+    */
+    HTLC_SET_ONLY = 1;
+
+    /*
+    Indicates that when a look up is done using a payment_addr, then no HTLCs
+    related to the payment_addr should be returned. This is useful when one
+    wants to be able to obtain the set of associated setIDs with a given
+    invoice, then look up the sub-invoices "projected" by that set ID.
+    */
+    HTLC_SET_BLANK = 2;
+}
+
+message LookupInvoiceMsg {
+    oneof invoice_ref {
+        bytes payment_hash = 1;
+        bytes payment_addr = 2;
+        bytes set_id = 3;
+    }
+
+    LookupModifier lookup_modifier = 4;
 }

package/grpc/protos/lightning.proto

@@ -3056,6 +3056,10 @@ message HopHint {
     uint32 cltv_expiry_delta = 5;
 }
 
+message SetID {
+    bytes set_id = 1;
+}
+
 message RouteHint {
     /*
     A list of hop hints that when chained together can assist in reaching a
@@ -3064,6 +3068,20 @@ message RouteHint {
     repeated HopHint hop_hints = 1;
 }
 
+message AMPInvoiceState {
+    // The state the HTLCs associated with this setID are in.
+    InvoiceHTLCState state = 1;
+
+    // The settle index of this HTLC set, if the invoice state is settled.
+    uint64 settle_index = 2;
+
+    // The time this HTLC set was settled expressed in unix epoch.
+    int64 settle_time = 3;
+
+    // The total amount paid for the sub-invoice expressed in milli satoshis.
+    int64 amt_paid_msat = 5;
+}
+
 message Invoice {
     /*
     An optional memo to attach along with the invoice. Used for record keeping
@@ -3209,7 +3227,7 @@ message Invoice {
 
     /*
     The payment address of this invoice. This value will be used in MPP
-    payments, and also for newer invoies that always require the MPP paylaod
+    payments, and also for newer invoices that always require the MPP payload
     for added end-to-end security.
     */
     bytes payment_addr = 26;
@@ -3218,6 +3236,16 @@ message Invoice {
     Signals whether or not this is an AMP invoice.
     */
     bool is_amp = 27;
+
+    /*
+    [EXPERIMENTAL]:
+
+    Maps a 32-byte hex-encoded set ID to the sub-invoice AMP state for the
+    given set ID. This field is always populated for AMP invoices, and can be
+    used along side LookupInvoice to obtain the HTLC information related to a
+    given sub-invoice.
+    */
+    map<string, AMPInvoiceState> amp_invoice_state = 28;
 }
 
 enum InvoiceHTLCState {

package/grpc/protos/signer.proto

@@ -74,14 +74,14 @@ message KeyLocator {
 
 message KeyDescriptor {
     /*
-    The raw bytes of the key being identified. Either this or the KeyLocator
-    must be specified.
+    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 key to use for signing. Either this
-    or the raw bytes of the target key must be specified.
+    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;
 }

package/index.js

@@ -87,6 +87,7 @@ const {recoverFundsFromChannels} = require('./lnd_methods');
 const {removePeer} = require('./lnd_methods');
 const {requestChainFeeIncrease} = require('./lnd_methods');
 const {revokeAccess} = require('./lnd_methods');
+const {sendMessageToPeer} = require('./lnd_methods');
 const {sendToChainAddress} = require('./lnd_methods');
 const {sendToChainAddresses} = require('./lnd_methods');
 const {sendToChainOutputScripts} = require('./lnd_methods');
@@ -113,6 +114,7 @@ const {subscribeToPastPayments} = require('./lnd_methods');
 const {subscribeToPayViaDetails} = require('./lnd_methods');
 const {subscribeToPayViaRequest} = require('./lnd_methods');
 const {subscribeToPayViaRoutes} = require('./lnd_methods');
+const {subscribeToPeerMessages} = require('./lnd_methods');
 const {subscribeToPeers} = require('./lnd_methods');
 const {subscribeToProbeForRoute} = require('./lnd_methods');
 const {subscribeToRpcRequests} = require('./lnd_methods');
@@ -221,6 +223,7 @@ module.exports = {
   removePeer,
   requestChainFeeIncrease,
   revokeAccess,
+  sendMessageToPeer,
   sendToChainAddress,
   sendToChainAddresses,
   sendToChainOutputScripts,
@@ -247,6 +250,7 @@ module.exports = {
   subscribeToPayViaDetails,
   subscribeToPayViaRequest,
   subscribeToPayViaRoutes,
+  subscribeToPeerMessages,
   subscribeToPeers,
   subscribeToProbeForRoute,
   subscribeToRpcRequests,

package/lnd_methods/offchain/index.d.ts

@@ -32,6 +32,7 @@ export * from './pay';
 export * from './probe_for_route';
 export * from './recover_funds_from_channel';
 export * from './recover_funds_from_channels';
+export * from './send_message_to_peer';
 export * from './subscribe_to_backups';
 export * from './subscribe_to_channels';
 export * from './subscribe_to_forward_requests';
@@ -42,6 +43,7 @@ export * from './subscribe_to_past_payments';
 export * from './subscribe_to_pay_via_details';
 export * from './subscribe_to_pay_via_request';
 export * from './subscribe_to_pay_via_routes';
+export * from './subscribe_to_peer_messages';
 export * from './subscribe_to_probe_for_route';
 export * from './update_connected_watchtower';
 export * from './update_pathfinding_settings';

package/lnd_methods/offchain/send_message_to_peer.d.ts

@@ -0,0 +1,28 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript';
+
+export type LightningMessage = {
+  /** Message Hex String */
+  message: string;
+  /** To Peer Public Key Hex String */
+  public_key: string;
+  /** Message Type Number */
+  type?: number;
+};
+
+export type SendMessageToPeerArgs =
+  AuthenticatedLightningArgs<LightningMessage>;
+
+/**
+ * Send a custom message to a connected peer
+ *
+ * If specified, message type is expected to be between 32768 and 65535
+ * Message data should not be larger than 65533 bytes
+ *
+ * Note: this method is not supported in LND versions 0.13.3 and below
+ *
+ * Requires `offchain:write` permission
+ */
+export const sendMessageToPeer: AuthenticatedLightningMethod<SendMessageToPeerArgs>;

package/lnd_methods/offchain/send_message_to_peer.js

@@ -63,7 +63,6 @@ module.exports = (args, cbk) => {
           }
 
           if (!!err) {
-            console.log("ERR", err)
             return cbk([503, 'UnexpectedErrorSendingMessageToPeer', {err}]);
           }
 

package/lnd_methods/offchain/subscribe_to_peer_messages.d.ts

@@ -0,0 +1,18 @@
+import {LightningMessage} from '.';
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningSubscription,
+  LightningError,
+} from '../../typescript';
+
+export type SubscribeToPeerMessagesMessageReceivedEvent =
+  Required<LightningMessage>;
+
+/**
+ * Subscribe to incoming peer messages
+ *
+ * Requires `offchain:read` permission
+ *
+ * This method is not supported in LND 0.13.3 and below
+ */
+export const subscribeToPeerMessages: AuthenticatedLightningSubscription;

package/package.json

@@ -7,22 +7,22 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.4.1",
+    "@grpc/grpc-js": "1.4.2",
     "@grpc/proto-loader": "0.6.6",
     "@types/express": "4.17.13",
-    "@types/node": "16.11.4",
+    "@types/node": "16.11.6",
     "@types/request": "2.48.7",
     "@types/ws": "8.2.0",
-    "async": "3.2.1",
-    "asyncjs-util": "1.2.6",
+    "async": "3.2.2",
+    "asyncjs-util": "1.2.7",
     "bitcoinjs-lib": "5.2.0",
     "bn.js": "5.2.0",
     "body-parser": "1.19.0",
-    "bolt07": "1.7.3",
+    "bolt07": "1.7.4",
     "bolt09": "0.2.0",
     "cbor": "8.0.2",
     "express": "4.17.1",
-    "invoices": "2.0.0",
+    "invoices": "2.0.1",
     "psbt": "1.1.10"
   },
   "description": "Lightning Network client library",
@@ -56,5 +56,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "4.12.0"
+  "version": "4.13.1"
 }

package/test/protos/protos.json

@@ -4,7 +4,7 @@
     ["lightning", 1218],
     ["lightning", 1226],
     ["lightning", 1233],
-    ["lightning", 3431],
+    ["lightning", 3459],
     ["router", 100],
     ["walletkit", 3],
     ["walletunlocker", 2]

package/test/typescript/send_message_to_peer.test-d.ts

@@ -0,0 +1,24 @@
+import {expectError, expectType} from 'tsd';
+import {AuthenticatedLnd} from '../../lnd_grpc';
+import {sendMessageToPeer} from '../../lnd_methods';
+
+const lnd = {} as AuthenticatedLnd;
+const message = 'msg';
+const public_key = 'pubkey';
+const type = 2;
+
+expectError(sendMessageToPeer());
+expectError(sendMessageToPeer({}));
+expectError(sendMessageToPeer({lnd}));
+expectError(sendMessageToPeer({lnd, message}));
+expectError(sendMessageToPeer({lnd, public_key}));
+
+expectType<void>(await sendMessageToPeer({lnd, message, public_key}));
+expectType<void>(await sendMessageToPeer({lnd, message, public_key, type}));
+
+expectType<void>(
+  sendMessageToPeer({lnd, message, public_key}, (error, result) => {})
+);
+expectType<void>(
+  sendMessageToPeer({lnd, message, public_key, type}, (error, result) => {})
+);

package/test/typescript/subscribe_to_peer_messages.test-d.ts

@@ -0,0 +1,11 @@
+import * as events from 'events';
+import {expectError, expectType} from 'tsd';
+import {AuthenticatedLnd} from '../../lnd_grpc';
+import {subscribeToPeerMessages} from '../../lnd_methods';
+
+const lnd = {} as AuthenticatedLnd;
+
+expectError(subscribeToPeerMessages());
+expectError(subscribeToPeerMessages({}));
+
+expectType<events.EventEmitter>(subscribeToPeerMessages({lnd}));