lightning 4.10.7 → 4.12.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Versions
 
+## 4.12.1
+
+- `probeForRoute`, `subscribeToProbeForRoute`, `subscribeToPayViaRoutes`,
+    `payViaRoutes`: When probing (no hash), delete the payment failure record after the probe
+
+## 4.11.1
+
+- `getFailedPayments`: Add method to get past failed payments
+- `subscribeToRpcRequests`: Add method to listen to and interact with RPC requests
+
 ## 4.10.7
 
 - `getPayment`: Expand type definitions to match result data

package/README.md

@@ -131,6 +131,8 @@ Methods exported by this library support typescript, but ln-service includes add
     channels on the node.
 - [getConnectedWatchtowers](https://github.com/alexbosworth/ln-service#getconnectedwatchtowers):
     List watchtowers that were added
+- [getFailedPayments](https://github.com/alexbosworth/ln-service#getfailedpayments): List out
+    past payments that failed.
 - [getFeeRates](https://github.com/alexbosworth/ln-service#getfeerates): List routing fee rates
     and routing policies of channels on the node.
 - [getForwardingConfidence](https://github.com/alexbosworth/ln-service#getforwardingconfidence):

package/grpc/protos/lightning.proto

@@ -557,6 +557,47 @@ service Lightning {
     */
     rpc RegisterRPCMiddleware (stream RPCMiddlewareResponse)
         returns (stream RPCMiddlewareRequest);
+
+    /* lncli: `sendcustom`
+    SendCustomMessage sends a custom peer message.
+    */
+    rpc SendCustomMessage (SendCustomMessageRequest)
+        returns (SendCustomMessageResponse);
+
+    /* lncli: `subscribecustom`
+    SubscribeCustomMessages subscribes to a stream of incoming custom peer
+    messages.
+    */
+    rpc SubscribeCustomMessages (SubscribeCustomMessagesRequest)
+        returns (stream CustomMessage);
+}
+
+message SubscribeCustomMessagesRequest {
+}
+
+message CustomMessage {
+    // Peer from which the message originates
+    bytes peer = 1;
+
+    // Message type. This value will be in the custom range (>= 32768).
+    uint32 type = 2;
+
+    // Raw message data
+    bytes data = 3;
+}
+
+message SendCustomMessageRequest {
+    // Peer to send the message to
+    bytes peer = 1;
+
+    // Message type. This value needs to be in the custom range (>= 32768).
+    uint32 type = 2;
+
+    // Raw message data.
+    bytes data = 3;
+}
+
+message SendCustomMessageResponse {
 }
 
 message Utxo {
@@ -834,6 +875,9 @@ message ChannelAcceptRequest {
     // A bit-field which the initiator uses to specify proposed channel
     // behavior.
     uint32 channel_flags = 13;
+
+    // The commitment type the initiator wishes to use for the proposed channel.
+    CommitmentType commitment_type = 14;
 }
 
 message ChannelAcceptResponse {
@@ -1188,6 +1232,15 @@ enum CommitmentType {
     been broadcast.
     */
     ANCHORS = 2;
+
+    /*
+    A channel that uses a commitment type that builds upon the anchors
+    commitment format, but in addition requires a CLTV clause to spend outputs
+    paying to the channel initiator. This is intended for use on leased channels
+    to guarantee that the channel initiator has no incentives to close a leased
+    channel before its maturity date.
+    */
+    SCRIPT_ENFORCED_LEASE = 4;
 }
 
 message ChannelConstraints {

package/grpc/protos/signer.proto

@@ -193,6 +193,12 @@ message SignMessageReq {
 
     // 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 {
     /*

package/grpc/protos/walletkit.proto

@@ -286,6 +286,16 @@ message AddrRequest {
     default wallet account is used.
     */
     string account = 1;
+
+    /*
+    The type of address to derive.
+    */
+    AddressType type = 2;
+
+    /*
+    Whether a change address should be derived.
+    */
+    bool change = 3;
 }
 message AddrResponse {
     /*

package/grpc/protos/walletunlocker.proto

@@ -176,6 +176,15 @@ message InitWalletRequest {
     mainnet).
     */
     uint64 extended_master_key_birthday_timestamp = 8;
+
+    /*
+    watch_only is the third option of initializing a wallet: by importing
+    account xpubs only and therefore creating a watch-only wallet that does not
+    contain any private keys. That means the wallet won't be able to sign for
+    any of the keys and _needs_ to be run with a remote signer that has the
+    corresponding private keys and can serve signing RPC requests.
+    */
+    WatchOnly watch_only = 9;
 }
 message InitWalletResponse {
     /*
@@ -188,6 +197,63 @@ message InitWalletResponse {
     bytes admin_macaroon = 1;
 }
 
+message WatchOnly {
+    /*
+    The unix timestamp in seconds of when the master key was created. lnd will
+    only start scanning for funds in blocks that are after the birthday which
+    can speed up the process significantly. If the birthday is not known, this
+    should be left at its default value of 0 in which case lnd will start
+    scanning from the first SegWit block (481824 on mainnet).
+    */
+    uint64 master_key_birthday_timestamp = 1;
+
+    /*
+    The fingerprint of the root key (also known as the key with derivation path
+    m/) from which the account public keys were derived from. This may be
+    required by some hardware wallets for proper identification and signing. The
+    bytes must be in big-endian order.
+    */
+    bytes master_key_fingerprint = 2;
+
+    /*
+    The list of accounts to import. There _must_ be an account for all of lnd's
+    main key scopes: BIP49/BIP84 (m/49'/0'/0', m/84'/0'/0', note that the
+    coin type is always 0, even for testnet/regtest) and lnd's internal key
+    scope (m/1017'/<coin_type>'/<account>'), where account is the key family as
+    defined in `keychain/derivation.go` (currently indices 0 to 9).
+     */
+    repeated WatchOnlyAccount accounts = 3;
+}
+
+message WatchOnlyAccount {
+    /*
+    Purpose is the first number in the derivation path, must be either 49, 84
+    or 1017.
+    */
+    uint32 purpose = 1;
+
+    /*
+    Coin type is the second number in the derivation path, this is _always_ 0
+    for purposes 49 and 84. It only needs to be set to 1 for purpose 1017 on
+    testnet or regtest.
+    */
+    uint32 coin_type = 2;
+
+    /*
+    Account is the third number in the derivation path. For purposes 49 and 84
+    at least the default account (index 0) needs to be created but optional
+    additional accounts are allowed. For purpose 1017 there needs to be exactly
+    one account for each of the key families defined in `keychain/derivation.go`
+    (currently indices 0 to 9)
+    */
+    uint32 account = 3;
+
+    /*
+    The extended public key at depth 3 for the given account.
+    */
+    string xpub = 4;
+}
+
 message UnlockWalletRequest {
     /*
     wallet_password should be the current valid passphrase for the daemon. This

package/index.js

@@ -37,6 +37,7 @@ const {getChannelBalance} = require('./lnd_methods');
 const {getChannels} = require('./lnd_methods');
 const {getClosedChannels} = require('./lnd_methods');
 const {getConnectedWatchtowers} = require('./lnd_methods');
+const {getFailedPayments} = require('./lnd_methods');
 const {getFeeRates} = require('./lnd_methods');
 const {getForwardingConfidence} = require('./lnd_methods');
 const {getForwardingReputations} = require('./lnd_methods');
@@ -114,6 +115,7 @@ const {subscribeToPayViaRequest} = require('./lnd_methods');
 const {subscribeToPayViaRoutes} = require('./lnd_methods');
 const {subscribeToPeers} = require('./lnd_methods');
 const {subscribeToProbeForRoute} = require('./lnd_methods');
+const {subscribeToRpcRequests} = require('./lnd_methods');
 const {subscribeToTransactions} = require('./lnd_methods');
 const {subscribeToWalletStatus} = require('./lnd_methods');
 const {unauthenticatedLndGrpc} = require('./lnd_grpc');
@@ -169,6 +171,7 @@ module.exports = {
   getChannels,
   getClosedChannels,
   getConnectedWatchtowers,
+  getFailedPayments,
   getFeeRates,
   getForwardingConfidence,
   getForwardingReputations,
@@ -246,6 +249,7 @@ module.exports = {
   subscribeToPayViaRoutes,
   subscribeToPeers,
   subscribeToProbeForRoute,
+  subscribeToRpcRequests,
   subscribeToTransactions,
   subscribeToWalletStatus,
   unauthenticatedLndGrpc,

package/lnd_methods/index.js

@@ -84,6 +84,7 @@ const {recoverFundsFromChannels} = require('./offchain');
 const {removePeer} = require('./peers');
 const {requestChainFeeIncrease} = require('./onchain');
 const {revokeAccess} = require('./macaroon');
+const {sendMessageToPeer} = require('./offchain');
 const {sendToChainAddress} = require('./onchain');
 const {sendToChainAddresses} = require('./onchain');
 const {sendToChainOutputScripts} = require('./onchain');
@@ -110,6 +111,7 @@ const {subscribeToPastPayments} = require('./offchain');
 const {subscribeToPayViaDetails} = require('./offchain');
 const {subscribeToPayViaRequest} = require('./offchain');
 const {subscribeToPayViaRoutes} = require('./offchain');
+const {subscribeToPeerMessages} = require('./offchain');
 const {subscribeToPeers} = require('./peers');
 const {subscribeToProbeForRoute} = require('./offchain');
 const {subscribeToRpcRequests} = require('./macaroon');
@@ -214,6 +216,7 @@ module.exports = {
   removePeer,
   requestChainFeeIncrease,
   revokeAccess,
+  sendMessageToPeer,
   sendToChainAddress,
   sendToChainAddresses,
   sendToChainOutputScripts,
@@ -240,6 +243,7 @@ module.exports = {
   subscribeToPayViaDetails,
   subscribeToPayViaRequest,
   subscribeToPayViaRoutes,
+  subscribeToPeerMessages,
   subscribeToPeers,
   subscribeToProbeForRoute,
   subscribeToRpcRequests,

package/lnd_methods/macaroon/index.d.ts

@@ -1,4 +1,5 @@
 export * from './get_access_ids';
 export * from './grant_access';
 export * from './revoke_access';
+export * from './subscribe_to_rpc_requests';
 export * from './verify_access';

package/lnd_methods/macaroon/methods.json

@@ -334,6 +334,10 @@
     "method": "DeleteMacaroonId",
     "type": "default"
   },
+  "sendMessageToPeer": {
+    "method": "SendCustomMessage",
+    "type": "default"
+  },
   "sendToChainAddress": {
     "method": "SendCoins",
     "type": "default"
@@ -439,9 +443,14 @@
     "type": "router"
   },
   "subscribeToPayViaRoutes": {
+    "depends_on": ["deletePayment"],
     "method": "SendToRouteV2",
     "type": "router"
   },
+  "subscribeToPeerMessages": {
+    "method": "SubscribeCustomMessages",
+    "type": "default"
+  },
   "subscribeToPeers": {
     "method": "SubscribePeerEvents",
     "type": "default"

package/lnd_methods/macaroon/subscribe_to_rpc_requests.d.ts

@@ -0,0 +1,143 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+  LightningMethod,
+} from '../../typescript';
+
+export type SubscribeToRpcRequestsArgs = AuthenticatedLightningArgs<{
+  /** RPC Middleware Interception Name String */
+  id?: string;
+  /** Intercept Channel Closes Bool */
+  is_intercepting_close_channel_requests?: boolean;
+  /** Intercept Channel Opens Bool */
+  is_intercepting_open_channel_requests?: boolean;
+  /** Intercept Pay Via Route Bool */
+  is_intercepting_pay_via_routes_requests?: boolean;
+}>;
+
+export type SubscribeToRpcRequestsResult = {
+  /** RPC Request Subscription EventEmitter Object */
+  subscription: NodeJS.EventEmitter;
+};
+
+export type SubscribeToRpcRequestsCommonEvent = {
+  /** Request Id Number */
+  id: number;
+  /** Base64 Encoded Macaroon String */
+  macaroon?: string;
+  /** RPC URI String */
+  uri?: string;
+};
+
+export type SubscribeToRpcRequestsEvent<TRequest> =
+  Required<SubscribeToRpcRequestsCommonEvent> & {
+    accept: LightningMethod;
+    reject: LightningMethod<{
+      /** Rejection String */
+      message: string;
+    }>;
+    request: TRequest;
+  };
+
+/** A channel close request was intercepted: by default it will be rejected */
+export type SubscribeToRpcRequestsCloseChannelRequestEvent =
+  SubscribeToRpcRequestsEvent<{
+    /** Request Sending Local Channel Funds To Address String */
+    address?: string;
+    /** Is Force Close Bool */
+    is_force_close?: boolean;
+    /** Confirmation Target Number */
+    target_confirmations?: number;
+    /** Tokens Per Virtual Byte Number */
+    tokens_per_vbyte?: number;
+    /** Transaction Id Hex String */
+    transaction_id: string;
+    /** Transaction Output Index Number */
+    transaction_vout: number;
+  }>;
+
+/** A channel open request was intercepted: by default it will be rejected */
+export type SubscribeToRpcRequestsOpenChannelRequestEvent =
+  SubscribeToRpcRequestsEvent<{
+    /** Chain Fee Tokens Per VByte Number */
+    chain_fee_tokens_per_vbyte?: number;
+    /** Prefer Cooperative Close To Address String */
+    cooperative_close_address?: string;
+    /** Tokens to Gift To Partner Number */
+    give_tokens?: number;
+    /** Channel is Private Bool */
+    is_private?: boolean;
+    /** Local Tokens Number */
+    local_tokens: number;
+    /** Spend UTXOs With Minimum Confirmations Number */
+    min_confirmations?: number;
+    /** Minimum HTLC Millitokens String */
+    min_htlc_mtokens?: string;
+    /** Public Key Hex String */
+    partner_public_key: string;
+    /** Peer Output CSV Delay Number */
+    partner_csv_delay?: number;
+  }>;
+
+/** A pay to route request was intercepted: by default it will be rejected */
+export type SubscribeToRpcRequestsPayViaRouteRequestEvent =
+  SubscribeToRpcRequestsEvent<{
+    /** Payment Hash Hex String */
+    id: string;
+    route: {
+      /** Route Fee Tokens Number */
+      fee: number;
+      /** Route Fee Millitokens String */
+      fee_mtokens: string;
+      hops: {
+        /** Standard Format Channel Id String */
+        channel: string;
+        /** Channel Capacity Tokens Number */
+        channel_capacity: number;
+        /** Fee Tokens Number */
+        fee: number;
+        /** Fee Millitokens String */
+        fee_mtokens: string;
+        /** Forward Tokens Number */
+        forward: number;
+        /** Forward Millitokens String */
+        forward_mtokens: string;
+        /** Forward Edge Public Key Hex String */
+        public_key: string;
+        /** Timeout Block Height Number */
+        timeout?: number;
+      }[];
+      /** Total Fee-Inclusive Millitokens String */
+      mtokens: string;
+      /** Payment Identifier Hex String */
+      payment?: string;
+      /** Timeout Block Height Number */
+      timeout?: number;
+      /** Total Fee-Inclusive Tokens Number */
+      tokens: number;
+      /** Total Payment Millitokens String */
+      total_mtokens?: string;
+    };
+  }>;
+
+export type SubscribeToRpcRequestsRequestEvent =
+  SubscribeToRpcRequestsCommonEvent;
+
+export type SubscribeToRpcRequestsResponseEvent =
+  SubscribeToRpcRequestsCommonEvent;
+
+/**
+ * Subscribe to RPC requests and their responses
+ *
+ * `accept` and `reject` methods can be used with cbk or Promise syntax
+ *
+ * Requires `macaroon:write` permission
+ *
+ * LND must be running with "RPC middleware" enabled: `rpcmiddleware.enable=1`
+ *
+ * This method is not supported in LND 0.13.3 and below
+ */
+export const subscribeToRpcRequests: AuthenticatedLightningMethod<
+  SubscribeToRpcRequestsArgs,
+  SubscribeToRpcRequestsResult
+>;

package/lnd_methods/offchain/get_failed_payments.d.ts

@@ -0,0 +1,136 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+  PaginationArgs,
+} from '../../typescript';
+
+export type GetFailedPaymentsArgs = AuthenticatedLightningArgs<PaginationArgs>;
+
+export type GetFailedPaymentsResult = {
+  payments: {
+    attempts: {
+      failure?: {
+        /** Error Type Code Number */
+        code: number;
+        details?: {
+          /** Standard Format Channel Id String */
+          channel?: string;
+          /** Error Associated Block Height Number */
+          height?: number;
+          /** Failed Hop Index Number */
+          index?: number;
+          /** Error Millitokens String */
+          mtokens?: string;
+          policy?: {
+            /** Base Fee Millitokens String */
+            base_fee_mtokens: string;
+            /** Locktime Delta Number */
+            cltv_delta: number;
+            /** Fees Charged in Millitokens Per Million Number */
+            fee_rate: number;
+            /** Channel is Disabled Bool */
+            is_disabled?: boolean;
+            /** Maximum HLTC Millitokens Value String */
+            max_htlc_mtokens: string;
+            /** Minimum HTLC Millitokens Value String */
+            min_htlc_mtokens: string;
+            /** Updated At ISO 8601 Date String */
+            updated_at: string;
+          };
+          /** Error CLTV Timeout Height Number */
+          timeout_height?: number;
+          update?: {
+            /** Chain Id Hex String */
+            chain: string;
+            /** Channel Flags Number */
+            channel_flags: number;
+            /** Extra Opaque Data Hex String */
+            extra_opaque_data: string;
+            /** Message Flags Number */
+            message_flags: number;
+            /** Channel Update Signature Hex String */
+            signature: string;
+          };
+        };
+        /** Error Message String */
+        message: string;
+      };
+      /** Payment Add Index Number */
+      index?: number;
+      /** Payment Confirmed At ISO 8601 Date String */
+      confirmed_at?: string;
+      /** Payment Attempt Succeeded Bool */
+      is_confirmed: boolean;
+      /** Payment Attempt Failed Bool */
+      is_failed: boolean;
+      /** Payment Attempt is Waiting For Resolution Bool */
+      is_pending: boolean;
+      route: {
+        /** Route Fee Tokens Number */
+        fee: number;
+        /** Route Fee Millitokens String */
+        fee_mtokens: string;
+        hops: {
+          /** Standard Format Channel Id String */
+          channel: string;
+          /** Channel Capacity Tokens Number */
+          channel_capacity: number;
+          /** Fee Number */
+          fee: number;
+          /** Fee Millitokens String */
+          fee_mtokens: string;
+          /** Forward Tokens Number */
+          forward: number;
+          /** Forward Millitokens String */
+          forward_mtokens: string;
+          /** Forward Edge Public Key Hex String */
+          public_key?: string;
+          /** Timeout Block Height Number */
+          timeout?: number;
+        }[];
+        /** Total Fee-Inclusive Millitokens String */
+        mtokens: string;
+        /** Payment Identifier Hex String */
+        payment?: string;
+        /** Timeout Block Height Number */
+        timeout: number;
+        /** Total Fee-Inclusive Tokens Number */
+        tokens: number;
+        /** Total Millitokens String */
+        total_mtokens?: string;
+      };
+    }[];
+    /** Payment at ISO-8601 Date String */
+    created_at: string;
+    /** Destination Node Public Key Hex String */
+    destination?: string;
+    /** Payment Preimage Hash String */
+    id: string;
+    /** Payment Add Index Number */
+    index?: number;
+    /** Payment is Confirmed Bool */
+    is_confirmed: boolean;
+    /** Transaction Is Outgoing Bool */
+    is_outgoing: boolean;
+    /** Millitokens Attempted to Pay to Destination String */
+    mtokens: string;
+    /** BOLT 11 Payment Request String */
+    request?: string;
+    /** Payment Tokens Attempted to Pay Rounded Up Number */
+    safe_tokens: number;
+    /** Rounded Down Tokens Attempted to Pay to Destination Number */
+    tokens: number;
+  }[];
+  /** Next Opaque Paging Token String */
+  next?: string;
+};
+
+/**
+ * Get failed payments made through channels.
+ *
+ * Requires `offchain:read` permission
+ */
+export const getFailedPayments: AuthenticatedLightningMethod<
+  GetFailedPaymentsArgs,
+  GetFailedPaymentsResult
+>;

package/lnd_methods/offchain/index.d.ts

@@ -14,6 +14,7 @@ export * from './get_channel_balance';
 export * from './get_channels';
 export * from './get_closed_channels';
 export * from './get_connected_watchtowers';
+export * from './get_failed_payments';
 export * from './get_fee_rates';
 export * from './get_forwarding_confidence';
 export * from './get_forwarding_reputations';

package/lnd_methods/offchain/index.js

@@ -32,6 +32,7 @@ const payViaRoutes = require('./pay_via_routes');
 const probeForRoute = require('./probe_for_route');
 const recoverFundsFromChannel = require('./recover_funds_from_channel');
 const recoverFundsFromChannels = require('./recover_funds_from_channels');
+const sendMessageToPeer = require('./send_message_to_peer');
 const subscribeToBackups = require('./subscribe_to_backups');
 const subscribeToChannels = require('./subscribe_to_channels');
 const subscribeToForwardRequests = require('./subscribe_to_forward_requests');
@@ -42,6 +43,7 @@ const subscribeToPastPayments = require('./subscribe_to_past_payments');
 const subscribeToPayViaDetails = require('./subscribe_to_pay_via_details');
 const subscribeToPayViaRequest = require('./subscribe_to_pay_via_request');
 const subscribeToPayViaRoutes = require('./subscribe_to_pay_via_routes');
+const subscribeToPeerMessages = require('./subscribe_to_peer_messages');
 const subscribeToProbeForRoute = require('./subscribe_to_probe_for_route');
 const updateConnectedWatchtower = require('./update_connected_watchtower');
 const updatePathfindingSettings = require('./update_pathfinding_settings');
@@ -84,6 +86,7 @@ module.exports = {
   probeForRoute,
   recoverFundsFromChannel,
   recoverFundsFromChannels,
+  sendMessageToPeer,
   subscribeToBackups,
   subscribeToChannels,
   subscribeToForwardRequests,
@@ -94,6 +97,7 @@ module.exports = {
   subscribeToPayViaDetails,
   subscribeToPayViaRequest,
   subscribeToPayViaRoutes,
+  subscribeToPeerMessages,
   subscribeToProbeForRoute,
   updateConnectedWatchtower,
   updatePathfindingSettings,

package/lnd_methods/offchain/probe_for_route.d.ts

@@ -118,6 +118,10 @@ export type ProbeForRouteResult = {
 /**
  * Probe to find a successful route
  *
+ * When probing to a payment request, make sure to specify the fields encoded in the payment request such as `cltv_delta`.
+ *
+ * If `total_mtokens` are specified, a `payment` nonce is required.
+ *
  * Requires `offchain:write` permission
  */
 export const probeForRoute: AuthenticatedLightningMethod<