lightning 4.3.1 → 4.7.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Versions
 
+## 4.7.0
+
+- `getPayment`: Add `created_at` to indicate the creation date of the payment
+- `getPayment`: Add `request` to indicate serialized payment request
+- `subscribeToPastPayment`: Add `created_at` to indicate the creation date of the payment
+- `subscribeToPastPayment`: Add `request` to indicate serialized payment request
+- `subscribeToPastPayments`: Add `created_at` to indicate the creation date of the payment
+- `subscribeToPastPayments`: Add `request` to indicate serialized payment request
+
+## 4.6.0
+
+- `getPayment`: Add `destination` to indicate the destination of the payment
+- `subscribeToPastPayment`: Add `destination` to indicate the destination of the payment
+- `subscribeToPastPayments`: Add `destination` to indicate the destination of the payment
+
+## 4.5.0
+
+- `deletePayment`: Add method to delete a single payment
+- `deleteFailedPayAttempts`: Add `id` argument to delete failed attempts for a payment
+- `getWalletStatus`: `is_ready`: Add wallet server ready status
+- `subscribeToWalletStatus`: Add `ready` event to indicate server ready status
+
+## 4.4.0
+
+- `getPayment`: Add `confirmed_at` to indicate when payment resolved successfully
+- `getPayments`: Add `confirmed_at` to indicate when payments resolve successfully
+- `pay`: Add `confirmed_at` to indicate when payment resolved successfully
+- `payViaPaymentDetails`: Add `confirmed_at` to indicate when payment was sent
+- `payViaPaymentRequest`: Add `confirmed_at` to indicate when payment was sent
+- `payViaRoutes`: Add `confirmed_at` to indicate when payment resolved successfully
+- `subscribeToPastPayment`: Add `confirmed_at` to indicate when payment succeeded
+- `subscribeToPastPayments`: Add `confirmed_at` to indicate when payments succeed
+- `subscribeToPayViaDetails`: Add `confirmed_at` to indicate when payment was sent
+- `subscribeToPayViaRequest`: Add `confirmed_at` to indicate when payment was sent
+- `subscribeToPayViaRoutes`: Add `confirmed_at` to indicate when payment was sent
+
 ## 4.3.1
 
 - `getPendingChannels`: Add typescript annotations to result

package/grpc/protos/lightning.proto

@@ -200,6 +200,16 @@ service Lightning {
     */
     rpc OpenChannel (OpenChannelRequest) returns (stream OpenStatusUpdate);
 
+    /* lncli: `batchopenchannel`
+    BatchOpenChannel attempts to open multiple single-funded channels in a
+    single transaction in an atomic way. This means either all channel open
+    requests succeed at once or all attempts are aborted if any of them fail.
+    This is the safer variant of using PSBTs to manually fund a batch of
+    channels through the OpenChannel RPC.
+    */
+    rpc BatchOpenChannel (BatchOpenChannelRequest)
+        returns (BatchOpenChannelResponse);
+
     /*
     FundingStateStep is an advanced funding related call that allows the caller
     to either execute some preparatory steps for a funding workflow, or
@@ -330,7 +340,14 @@ service Lightning {
     rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse);
 
     /*
-    DeleteAllPayments deletes all outgoing payments from DB.
+    DeletePayment deletes an outgoing payment from DB. Note that it will not
+    attempt to delete an In-Flight payment, since that would be unsafe.
+    */
+    rpc DeletePayment (DeletePaymentRequest) returns (DeletePaymentResponse);
+
+    /*
+    DeleteAllPayments deletes all outgoing payments from DB. Note that it will
+    not attempt to delete In-Flight payments, since that would be unsafe.
     */
     rpc DeleteAllPayments (DeleteAllPaymentsRequest)
         returns (DeleteAllPaymentsResponse);
@@ -1776,6 +1793,84 @@ message ReadyForPsbtFunding {
     bytes psbt = 3;
 }
 
+message BatchOpenChannelRequest {
+    // The list of channels to open.
+    repeated BatchOpenChannel channels = 1;
+
+    // The target number of blocks that the funding transaction should be
+    // confirmed by.
+    int32 target_conf = 2;
+
+    // A manual fee rate set in sat/vByte that should be used when crafting the
+    // funding transaction.
+    int64 sat_per_vbyte = 3;
+
+    // The minimum number of confirmations each one of your outputs used for
+    // the funding transaction must satisfy.
+    int32 min_confs = 4;
+
+    // Whether unconfirmed outputs should be used as inputs for the funding
+    // transaction.
+    bool spend_unconfirmed = 5;
+
+    // An optional label for the batch transaction, limited to 500 characters.
+    string label = 6;
+}
+
+message BatchOpenChannel {
+    // The pubkey of the node to open a channel with. When using REST, this
+    // field must be encoded as base64.
+    bytes node_pubkey = 1;
+
+    // The number of satoshis the wallet should commit to the channel.
+    int64 local_funding_amount = 2;
+
+    // The number of satoshis to push to the remote side as part of the initial
+    // commitment state.
+    int64 push_sat = 3;
+
+    // Whether this channel should be private, not announced to the greater
+    // network.
+    bool private = 4;
+
+    // The minimum value in millisatoshi we will require for incoming HTLCs on
+    // the channel.
+    int64 min_htlc_msat = 5;
+
+    // The delay we require on the remote's commitment transaction. If this is
+    // not set, it will be scaled automatically with the channel size.
+    uint32 remote_csv_delay = 6;
+
+    /*
+    Close address is an optional address which specifies the address to which
+    funds should be paid out to upon cooperative close. This field may only be
+    set if the peer supports the option upfront feature bit (call listpeers
+    to check). The remote peer will only accept cooperative closes to this
+    address if it is set.
+
+    Note: If this value is set on channel creation, you will *not* be able to
+    cooperatively close out to a different address.
+    */
+    string close_address = 7;
+
+    /*
+    An optional, unique identifier of 32 random bytes that will be used as the
+    pending channel ID to identify the channel while it is in the pre-pending
+    state.
+    */
+    bytes pending_chan_id = 8;
+
+    /*
+    The explicit commitment type to use. Note this field will only be used if
+    the remote peer supports explicit channel negotiation.
+    */
+    CommitmentType commitment_type = 9;
+}
+
+message BatchOpenChannelResponse {
+    repeated PendingUpdate pending_channels = 1;
+}
+
 message OpenChannelRequest {
     // A manual fee rate set in sat/vbyte that should be used when crafting the
     // funding transaction.
@@ -1867,6 +1962,12 @@ message OpenChannelRequest {
     transaction.
     */
     uint32 max_local_csv = 17;
+
+    /*
+    The explicit commitment type to use. Note this field will only be used if
+    the remote peer supports explicit channel negotiation.
+    */
+    CommitmentType commitment_type = 18;
 }
 message OpenStatusUpdate {
     oneof update {
@@ -3354,6 +3455,16 @@ message ListPaymentsResponse {
     uint64 last_index_offset = 3;
 }
 
+message DeletePaymentRequest {
+    // Payment hash to delete.
+    bytes payment_hash = 1;
+
+    /*
+    Only delete failed HTLCs from the payment, not the payment itself.
+    */
+    bool failed_htlcs_only = 2;
+}
+
 message DeleteAllPaymentsRequest {
     // Only delete failed payments.
     bool failed_payments_only = 1;
@@ -3364,6 +3475,9 @@ message DeleteAllPaymentsRequest {
     bool failed_htlcs_only = 2;
 }
 
+message DeletePaymentResponse {
+}
+
 message DeleteAllPaymentsResponse {
 }
 

package/grpc/protos/stateservice.proto

@@ -41,6 +41,9 @@ enum WalletState {
     UNLOCKED = 2;
     RPC_ACTIVE = 3;
 
+    // SERVER_ACTIVE means that the lnd server is ready to accept calls.
+    SERVER_ACTIVE = 4;
+
     WAITING_TO_START = 255;
 }
 

package/index.js

@@ -107,6 +107,7 @@ const {subscribeToInvoice} = require('./lnd_methods');
 const {subscribeToInvoices} = require('./lnd_methods');
 const {subscribeToOpenRequests} = require('./lnd_methods');
 const {subscribeToPastPayment} = require('./lnd_methods');
+const {subscribeToPastPayments} = require('./lnd_methods');
 const {subscribeToPayViaDetails} = require('./lnd_methods');
 const {subscribeToPayViaRequest} = require('./lnd_methods');
 const {subscribeToPayViaRoutes} = require('./lnd_methods');
@@ -236,6 +237,7 @@ module.exports = {
   subscribeToInvoices,
   subscribeToOpenRequests,
   subscribeToPastPayment,
+  subscribeToPastPayments,
   subscribeToPayViaDetails,
   subscribeToPayViaRequest,
   subscribeToPayViaRoutes,

package/lnd_methods/index.js

@@ -14,6 +14,7 @@ const {decodePaymentRequest} = require('./offchain');
 const {deleteFailedPayAttempts} = require('./offchain');
 const {deleteFailedPayments} = require('./offchain');
 const {deleteForwardingReputations} = require('./offchain');
+const {deletePayment} = require('./offchain');
 const {deletePayments} = require('./offchain');
 const {diffieHellmanComputeSecret} = require('./signer');
 const {disableChannel} = require('./offchain');
@@ -140,6 +141,7 @@ module.exports = {
   deleteFailedPayAttempts,
   deleteFailedPayments,
   deleteForwardingReputations,
+  deletePayment,
   deletePayments,
   diffieHellmanComputeSecret,
   disableChannel,

package/lnd_methods/offchain/delete_failed_pay_attempts.js

@@ -3,7 +3,11 @@ const {returnResult} = require('asyncjs-util');
 
 const {isLnd} = require('./../../lnd_requests');
 
-const method = 'deleteAllPayments';
+const deleteAllMethod = 'deleteAllPayments';
+const deleteOneMethod = 'deletePayment';
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const isHash = n => /^[0-9A-F]{64}$/i.test(n);
+const notSupported = /unknown/;
 const type = 'default';
 
 /** Delete failed payment attempt records
@@ -12,18 +16,25 @@ const type = 'default';
 
   Method not supported on LND 0.12.1 or below
 
+  `id` is not supported on LND 0.13.1 or below
+
   {
+    [id]: <Delete Only Failed Attempt Records For Payment With Hash Hex String>
     lnd: <Authenticated LND API Object>
   }
 
   @returns via cbk or Promise
 */
-module.exports = ({lnd}, cbk) => {
+module.exports = ({id, lnd}, cbk) => {
   return new Promise((resolve, reject) => {
     return asyncAuto({
       // Check arguments
       validate: cbk => {
-        if (!isLnd({lnd, method, type})) {
+        if (!!id && !isHash(id)) {
+          return cbk([400, 'ExpectedPaymentHashToDeleteFailedPayAttempts']);
+        }
+
+        if (!isLnd({lnd, type, method: deleteAllMethod})) {
           return cbk([400, 'ExpectedAuthenticatedLndToDeleteFailedAttempts']);
         }
 
@@ -32,7 +43,17 @@ module.exports = ({lnd}, cbk) => {
 
       // Delete failed payments
       deletePayments: ['validate', ({}, cbk) => {
-        return lnd[type][method]({failed_htlcs_only: true}, err => {
+        const method = !id ? deleteAllMethod : deleteOneMethod;
+
+        return lnd[type][method]({
+          failed_htlcs_only: true,
+          id: !!id ? hexAsBuffer(id) : undefined,
+        },
+        err => {
+          if (!!err && notSupported.test(err.details)) {
+            return cbk([501, 'DeleteFailedPaymentAttemptsMethodNotSupported']);
+          }
+
           if (!!err) {
             return cbk([503, 'UnexpectedErrorDeletingFailedAttempts', {err}]);
           }

package/lnd_methods/offchain/delete_payment.js

@@ -0,0 +1,58 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const hexAsBytes = hex => Buffer.from(hex, 'hex');
+const isHash = n => !!n && /^[0-9A-F]{64}$/i.test(n);
+const method = 'deletePayment';
+const notSupported = /unknown/;
+const type = 'default';
+
+/** Delete a payment record
+
+  Requires `offchain:write` permission
+
+  Note: this method is not supported on LND 0.13.1 and below
+
+  {
+    id: <Payment Preimage Hash Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+*/
+module.exports = ({id, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isHash(id)) {
+          return cbk([400, 'ExpectedPaymentHashToDeletePaymentRecord']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToDeletePayment']);
+        }
+
+        return cbk();
+      },
+
+      // Delete all payments
+      deletePayments: ['validate', ({}, cbk) => {
+        return lnd[type][method]({payment_hash: hexAsBytes(id)}, err => {
+          if (!!err && notSupported.test(err.details)) {
+            return cbk([501, 'DeletePaymentMethodNotSupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorDeletingPayment', {err}]);
+          }
+
+          return cbk();
+        });
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/lnd_methods/offchain/emit_payment.d.ts

@@ -1,7 +1,7 @@
 import * as events from 'events';
 import {ConfirmedFromPaymentResult} from '../../lnd_responses/confirmed_from_payment';
 import {FailureFromPaymentResult} from '../../lnd_responses/failure_from_payment';
-import {LightningError, PaymentState} from '../../typescript';
+import {EmptyObject, LightningError, PaymentState} from '../../typescript';
 
 export type EmitPaymentArgs = {
   data: {
@@ -14,8 +14,8 @@ export type EmitPaymentConfirmedEvent = ConfirmedFromPaymentResult;
 
 export type EmitPaymentFailedEvent = FailureFromPaymentResult;
 
-export type EmitPaymentPayingEvent = {[key: string]: never};
+export type EmitPaymentPayingEvent = EmptyObject;
 
-export type EmitPaymentError = LightningError<never>;
+export type EmitPaymentError = LightningError<undefined>;
 
 export const emitPayment: (args: EmitPaymentArgs) => boolean | undefined;

package/lnd_methods/offchain/finished_payment.js

@@ -5,6 +5,7 @@ const {returnResult} = require('asyncjs-util');
 
   {
     [confirmed]: {
+      confirmed_at: <Payment Confirmed At ISO 8601 Date String>
       fee: <Total Fee Tokens Paid Rounded Down Number>
       fee_mtokens: <Total Fee Millitokens Paid String>
       hops: [{
@@ -66,6 +67,7 @@ const {returnResult} = require('asyncjs-util');
 
   @returns via cbk or Promise
   {
+    confirmed_at: <Payment Confirmed At ISO 8601 Date String>
     fee: <Fee Tokens Number>
     fee_mtokens: <Total Fee Millitokens To Pay String>
     hops: [{
@@ -134,6 +136,7 @@ module.exports = ({confirmed, failed}, cbk) => {
       // Return the payment resolution
       payment: ['checkFailure', ({}, cbk) => {
         return cbk(null, {
+          confirmed_at: confirmed.confirmed_at,
           fee: confirmed.fee,
           fee_mtokens: confirmed.fee_mtokens,
           hops: confirmed.hops,

package/lnd_methods/offchain/get_payment.d.ts

@@ -26,6 +26,12 @@ export type GetPaymentResult = {
   /** Payment Is Pending */
   is_pending?: boolean;
   payment?: {
+    /** Confirmed at ISO-8601 Date */
+    confirmed_at: string;
+    /** Created at ISO-8601 Date */
+    created_at: string;
+    /** Payment Destination Public Key Hex */
+    destination: string;
     /** Total Fee Millitokens To Pay */
     fee_mtokens: string;
     hops: {
@@ -50,6 +56,8 @@ export type GetPaymentResult = {
     id: string;
     /** Total Millitokens Paid */
     mtokens: string;
+    /** BOLT 11 Payment Request */
+    request?: string;
     /** Payment Forwarding Fee Rounded Up Tokens */
     safe_fee: number;
     /** Payment Tokens Rounded Up */

package/lnd_methods/offchain/get_payment.js

@@ -29,6 +29,9 @@ const type = 'router';
     [is_failed]: <Payment Is Failed Bool>
     [is_pending]: <Payment Is Pending Bool>
     [payment]: {
+      confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+      created_at: <Payment Created At ISO 8601 Date String>
+      destination: <Payment Destination Hex String>
       fee: <Total Fees Paid Rounded Down Number>
       fee_mtokens: <Total Fee Millitokens Paid String>
       hops: [{
@@ -56,6 +59,7 @@ const type = 'router';
         }]
         mtokens: <Total Millitokens Paid String>
       }]
+      [request]: <BOLT 11 Encoded Payment Request String>
       safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
       safe_tokens: <Payment Tokens Rounded Up Number>
       secret: <Payment Preimage Hex String>