balanceofsatoshis 10.16.2 → 10.19.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Versions
 
+## Version 10.19.0
+
+- `balance`: Included locked UTXO value as on-chain value in `--detailed` balance output
+- `increase-inbound-liquidity|pay|probe|rebalance|send`: Add `AGE` to avoid formulas
+- `peers`: Avoid errors when network name is unknown
+- `push`: Add `--message-omit-from-key` to send messages without including "from" key
+
+## Version 10.18.1
+
+- `open`: In final tx id indication use original external tx id when available
+
+## Version 10.18.0
+
+- `call`: Add support for `broadcastChainTransaction`, `cancelHodlInvoice`
+    `cancelPendingChannel`, `createChainAddress`, `createHodlInvoice`, `deletePayments`,
+    `settleHodlInvoice`, `subscribeToBackups`, `subscribeToBlocks`,
+    `subscribeToChannels`, `subscribeToForwards`, `subscribeToGraph`,
+    `subscribeToInvoice`, `subscribeToInvoices`, `subscribeToPeers`,
+    `subscribeToTransactions`.
+- `services`: Add service `--invoice` to create invoices on request
+- `services`: Automatically retry on `relay` service if destination payment fails
+
+## Version 10.17.0
+
+- `chart-fees-paid`: Add tag icons to nodes in table view
+- `telegram`: Add `/costs` command to report rebalance and chain fees
+
 ## Version 10.16.2
 
 - `chart-chain-fees`: Add mempool space chain fee lookup redundancy

package/README.md

@@ -12,8 +12,8 @@ Commands for working with LND balances.
 If you want to try out any command without npm install, you can also do `npx
 balanceofsatoshis` to run a command directly.
 
-If you have [Docker](https://docs.docker.com/get-docker/) installed, you can
-[run through Docker](#docker) instead.
+If you have [Docker](https://docs.docker.com/get-docker/) installed or are using a Docker based
+platform like Umbrel or BTCPayServer, you can [run through Docker](#docker) instead.
 
 ```shell
 npm install -g balanceofsatoshis
@@ -227,7 +227,12 @@ Use any shorthand you'd like when choosing this profile node name
 
 #### Umbrel Saved Node
 
-Note: Umbrel is not FOSS software, use at your own risk.
+*Note: Umbrel is not FOSS software, use at your own risk.*
+
+If you are using Umbrel and you have already installed but you get an error like
+`Name resolution failed for target dns:umbrel.local:10009` then try adding umbrel.local
+to your `/etc/hosts` file, like `sudo nano /etc/hosts` and add a line
+`127.0.0.1 umbrel.local`
 
 1. Identify your Umbrel home dir, like /home/umbrel/umbrel
 2. Look in the .env file in that dir for the `LND_IP` to use as the socket to connect to
@@ -446,6 +451,17 @@ Or on Linux:
 --network="host" -v $HOME/.lnd:/home/node/.lnd:ro
 ```
 
+On BTCpayServer:
+
+Create the credential.json file as explained in the saved nodes section, and for socket put:
+`"socket": "lnd_bitcoin:10009"`
+
+For Docker network use the Docker bridged network:
+
+```
+docker run -it --rm --network="generated_default" -v $HOME/.bos:/home/node/.bos alexbosworth/balanceofsatoshis balance --node SAVEDNODENAME
+```
+
 On Umbrel this would be:
 
 ```

package/balances/detailed_balances.js

@@ -31,6 +31,9 @@ const witnessSizeCounterVByteLength = 0.25;
         tokens: <Payment Size Tokens Number>
       }]
     }]
+    locked: [{
+      tokens: <Unspent Tokens Number>
+    }]
     pending: [{
       is_opening: <Channel is Pending Bool>
       is_partner_initiated: <Partner Responsible For Chain Fees Bool>
@@ -64,7 +67,7 @@ const witnessSizeCounterVByteLength = 0.25;
     onchain_vbytes: <Estimated Virtual Bytes to Spend On-Chain Funds Number>
   }
 */
-module.exports = ({channels, pending, transactions, utxos}) => {
+module.exports = ({channels, locked, pending, transactions, utxos}) => {
   const channelBalances = channels.map(n => n.local_balance);
   const confirmedUtxos = utxos.filter(n => !!n.confirmation_count);
 
@@ -115,6 +118,7 @@ module.exports = ({channels, pending, transactions, utxos}) => {
   const chainBalance = sumOf([]
     .concat(confirmedUtxos)
     .concat(changeUtxos)
+    .concat(locked)
     .map(n => n.tokens)
   );
 

package/balances/get_balance.js

@@ -21,7 +21,7 @@ const none = 0;
     lnd: <Authenticated LND API Object>
   }
 
-  @returns via cbk
+  @returns via cbk or Promise
   {
     balance: <Tokens Number>
     channel_balance: <Channel Balance Minus Commit Fees Tokens Number>

package/balances/get_detailed_balance.js

@@ -2,12 +2,16 @@ const asyncAuto = require('async/auto');
 const {formatTokens} = require('ln-sync');
 const {getChainTransactions} = require('ln-service');
 const {getChannels} = require('ln-service');
+const {getLockedUtxos} = require('ln-service');
 const {getPendingChannels} = require('ln-service');
 const {getUtxos} = require('ln-service');
 const {returnResult} = require('asyncjs-util');
+const {Transaction} = require('bitcoinjs-lib');
 
 const detailedBalances = require('./detailed_balances');
 
+const {fromHex} = Transaction;
+
 /** Get a detailed balance that categorizes balance of tokens on the node
 
   {
@@ -39,6 +43,18 @@ module.exports = (args, cbk) => {
         return getChannels({lnd: args.lnd}, cbk);
       }],
 
+      // Get locked UTXOs
+      getLocked: ['validate', ({}, cbk) => {
+        return getLockedUtxos({lnd: args.lnd}, (err, res) => {
+          // Ignore errors
+          if (!!err) {
+            return cbk(null, []);
+          }
+
+          return cbk(null, res.utxos);
+        });
+      }],
+
       // Get pending channels
       getPending: ['validate', ({}, cbk) => {
         return getPendingChannels({lnd: args.lnd}, cbk);
@@ -52,17 +68,49 @@ module.exports = (args, cbk) => {
       // Get the UTXOs
       getUtxos: ['validate', ({}, cbk) => getUtxos({lnd: args.lnd}, cbk)],
 
+      // Cross reference locked transactions to UTXO data
+      locked: ['getLocked', 'getTx', ({getLocked, getTx}, cbk) => {
+        const {transactions} = getTx;
+
+        const utxos = getLocked.map(locked => {
+          // Exit early when the lock is expired
+          if (locked.lock_expires_at < new Date().toISOString()) {
+            return;
+          }
+
+          const tx = transactions.find(n => n.id === locked.transaction_id);
+
+          // Exit early when there is no related confirmed transaction
+          if (!tx || !tx.transaction || !tx.confirmation_count) {
+            return;
+          }
+
+          const output = fromHex(tx.transaction).outs[locked.transaction_vout];
+
+          // Exit early when the output is not found in the transaction
+          if (!output) {
+            return;
+          }
+
+          return {tokens: output.value};
+        });
+
+        return cbk(null, utxos.filter(n => !!n));
+      }],
+
       // Calculate balance
       balance: [
         'getChannels',
         'getPending',
         'getTx',
         'getUtxos',
-        ({getChannels, getPending, getTx, getUtxos}, cbk) =>
+        'locked',
+        ({getChannels, getPending, getTx, getUtxos, locked}, cbk) =>
       {
         const format = tokens => formatTokens({tokens}).display.trim();
 
         const balances = detailedBalances({
+          locked,
           channels: getChannels.channels,
           pending: getPending.pending_channels,
           transactions: getTx.transactions,

package/balances/get_liquidity.js

@@ -21,14 +21,14 @@ const topPercentile = 0.9;
     [below]: <Tokens Below Tokens Number>
     [is_outbound]: <Return Outbound Liquidity Bool>
     [is_top]: <Return Top Liquidity Bool>
-    lnd: <Authenticated LND gRPC API Object>
+    lnd: <Authenticated LND API Object>
     [min_node_score]: <Minimum Node Score Number>
     [max_fee_rate]: <Max Inbound Fee Rate Parts Per Million Number>
     [request]: <Request Function>
     [with]: <Liquidity With Specific Node Public Key Hex String>
   }
 
-  @returns via cbk
+  @returns via cbk or Promise
   {
     balance: <Liquid Tokens Number>
   }

package/bos

@@ -216,6 +216,7 @@ prog
     return new Promise(async (resolve, reject) => {
       try {
         return commands.callRawApi({
+          logger,
           ask: (n, cbk) => inquirer.prompt([n]).then(n => cbk(null, n)),
           lnd: (await lndForNode(logger, options.node)).lnd,
           method: args.method,
@@ -358,6 +359,7 @@ prog
       try {
         return routing.getFeesPaid({
           days: options.days,
+          fs: {getFile: readFile},
           is_most_fees_table: options.mostFees,
           is_most_forwarded_table: options.mostForwarded,
           is_network: options.network,
@@ -950,7 +952,7 @@ prog
 
   // Open channels
   .command('open', 'Open channels, optionally using an external wallet')
-  .help('Create channels from an external wallet. Note: do not self-broadcast')
+  .help('When creating channels from an external wallet do not self-broadcast')
   .argument('<peer_public_keys...>', 'With nodes with public keys')
   .option('--amount <channel_capacity>', 'Capacities to open', REPEATABLE)
   .option('--external-funding', 'Use external funds for the channel open')
@@ -1189,7 +1191,7 @@ prog
   .help('--avoid can take a channel id or a public key to avoid')
   .help('--avoid can take a public_key/public_key to avoid a directed pair')
   .help('--avoid can take a FORMULA/public_key to avoid inbound peers')
-  .help('--avoid FORMULA variables: FEE_RATE, BASE_FEE, HEIGHT')
+  .help('--avoid FORMULA variables: FEE_RATE, BASE_FEE, HEIGHT, AGE')
   .help('--in decreases the inbound liquidity with a specific peer/tag')
   .help('--out increases the inbound liquidity with a specific peer/tag')
   .option('--amount <amount>', 'Maximum amount to rebalance')
@@ -1346,6 +1348,7 @@ prog
   .option('--in <pubkey_or_alias>', 'Route in through a specific node')
   .option('--max-fee <fee>', 'Maximum fee tokens', INT, 1337)
   .option('--message <message>', 'Message to include with payment')
+  .option('--message-omit-from-key', 'Leave out the from key on messages')
   .option('--no-color', 'Mute all colors')
   .option('--node <name>', 'Node to send funds from')
   .option('--out <pubkey_or_alias>', 'Route out through a specific peer')
@@ -1366,6 +1369,7 @@ prog
           fs: {getFile: readFile},
           in_through: options.in,
           is_dry_run: options.dryrun,
+          is_omitting_message_from: options.messageOmitFromKey,
           max_fee: options.maxFee,
           message: options.message,
           quiz_answers: flatten([options.quiz].filter(n => !!n)),
@@ -1393,6 +1397,7 @@ prog
   .option('--inbox-sms-to', 'Inbox service sms to number')
   .option('--inbox-sms-twilio-sid', 'Inbox service Twilio account sid')
   .option('--inbox-sms-twilio-auth', 'Inbox service Twilio auth token')
+  .option('--invoice', 'Enable creating custom invoices on demand')
   .option('--node <node_name>', 'Saved node')
   .option('--payer <pay_with_node_name>', 'Node to pay request responses with')
   .option('--profile <profile>', 'Share a profile with info about your node')
@@ -1416,6 +1421,7 @@ prog
           inbox_twilio_account_sid: options.inboxSmsTwilioSid,
           inbox_twilio_auth_token: options.inboxSmsTwilioAuth,
           is_connect_enabled: !!options.connect || undefined,
+          is_invoice_enabled: !!options.invoice || undefined,
           is_relay_enabled: !!options.relay || undefined,
           network_nodes: flatten([options.network].filter(n => !!n)),
           node: options.node,

package/commands/api.json

@@ -14,6 +14,40 @@
       ],
       "method": "addPeer"
     },
+    {
+      "arguments": [
+        {
+          "description": "Raw hex encoded signed raw transaction",
+          "named": "transaction"
+        },
+        {
+          "description": "Transaction description label",
+          "named": "description",
+          "optional": true
+        }
+      ],
+      "method": "broadcastChainTransaction"
+    },
+    {
+      "arguments": [
+        {
+          "description": "Id of invoice to cancel",
+          "named": "id",
+          "type": "hash"
+        }
+      ],
+      "method": "cancelHodlInvoice"
+    },
+    {
+      "arguments": [
+        {
+          "description": "Id of pending channel to cancel",
+          "named": "id",
+          "type": "hash"
+        }
+      ],
+      "method": "cancelPendingChannel"
+    },
     {
       "arguments": [
         {
@@ -34,6 +68,42 @@
       ],
       "method": "closeChannel"
     },
+    {
+      "arguments": [
+        {
+          "description": "Chain address format, np2wpkh or p2wpkh",
+          "named": "format"
+        }
+      ],
+      "method": "createChainAddress"
+    },
+    {
+      "arguments": [
+        {
+          "description": "Final CLTV delta",
+          "named": "cltv_delta",
+          "optional": true,
+          "type": "number"
+        },
+        {
+          "description": "Description",
+          "named": "description",
+          "optional": true
+        },
+        {
+          "description": "Hash",
+          "named": "id",
+          "optional": true,
+          "type": "hash"
+        },
+        {
+          "description": "Millitokens to request",
+          "named": "mtokens",
+          "optional": true
+        }
+      ],
+      "method": "createHodlInvoice"
+    },
     {
       "arguments": [
         {
@@ -72,6 +142,9 @@
     {
       "method": "deleteForwardingReputations"
     },
+    {
+      "method": "deletePayments"
+    },
     {
       "arguments": [
         {
@@ -250,6 +323,16 @@
     {
       "method": "getIdentity"
     },
+    {
+      "arguments": [
+        {
+          "description": "Invoice hex encoded payment hash",
+          "named": "id",
+          "type": "hash"
+        }
+      ],
+      "method": "getInvoice"
+    },
     {
       "arguments": [
         {
@@ -266,16 +349,6 @@
       ],
       "method": "getInvoices"
     },
-    {
-      "arguments": [
-        {
-          "description": "Invoice hex encoded payment hash",
-          "named": "id",
-          "type": "hash"
-        }
-      ],
-      "method": "getInvoice"
-    },
     {
       "method": "getLockedUtxos"
     },
@@ -476,6 +549,15 @@
       ],
       "method": "requestChainFeeIncrease"
     },
+    {
+      "arguments": [
+        {
+          "description": "Hex encoded secret preimage",
+          "named": "secret"
+        }
+      ],
+      "method": "settleHodlInvoice"
+    },
     {
       "arguments": [{
         "description": "Message to sign",
@@ -486,6 +568,54 @@
     {
       "method": "stopDaemon"
     },
+    {
+      "events": ["backup"],
+      "method": "subscribeToBackups"
+    },
+    {
+      "events": ["block"],
+      "method": "subscribeToBlocks"
+    },
+    {
+      "events": [
+        "channel_active_changed",
+        "channel_closed",
+        "channel_opened",
+        "channel_opening"
+      ],
+      "method": "subscribeToChannels"
+    },
+    {
+      "events": ["forward"],
+      "method": "subscribeToForwards"
+    },
+    {
+      "events": ["channel_closed", "channel_updated", "node_updated"],
+      "method": "subscribeToGraph"
+    },
+    {
+      "arguments": [
+        {
+          "description": "Invoice preimage hash hex encoded",
+          "named": "id",
+          "type": "hash"
+        }
+      ],
+      "events": ["invoice_updated"],
+      "method": "subscribeToInvoice"
+    },
+    {
+      "events": ["invoice_updated"],
+      "method": "subscribeToInvoices"
+    },
+    {
+      "events": ["connected", "disconnected"],
+      "method": "subscribeToPeers"
+    },
+    {
+      "events": ["chain_transaction"],
+      "method": "subscribeToTransactions"
+    },
     {
       "arguments": [
         {

package/commands/call_raw_api.js

@@ -10,19 +10,21 @@ const isHash = n => !!n && /^[0-9A-F]{64}$/i.test(n);
 const isPublicKey = n => !!n && /^0[2-3][0-9A-F]{64}$/i.test(n);
 const {keys} = Object;
 const lower = n => n.toLowerCase();
+const methodDetails = (calls, method) => calls.find(n => n.method === method);
 
 /** Call the raw API
 
   {
     ask: <Inquirer Function> ({message, name, type}, cbk) => {}
     lnd: <Authenticated LND API Object>
+    logger: <Winston Logger Object>
     [method]: <Method to Call String>
   }
 
   @returns via cbk or Promise
   <Result Object>
 */
-module.exports = ({ask, lnd, method}, cbk) => {
+module.exports = ({ask, lnd, logger, method}, cbk) => {
   return new Promise((resolve, reject) => {
     return asyncAuto({
       // Check arguments
@@ -35,6 +37,10 @@ module.exports = ({ask, lnd, method}, cbk) => {
           return cbk([400, 'ExpectedAuthenticatedLndToCallApi']);
         }
 
+        if (!logger) {
+          return cbk([400, 'ExpectedLoggerToCallApi']);
+        }
+
         if (!!method && !calls.find(n => lower(n.method) === lower(method))) {
           return cbk([404, 'UnrecognizedMethod']);
         }
@@ -118,8 +124,8 @@ module.exports = ({ask, lnd, method}, cbk) => {
         cbk);
       }],
 
-      // Call API
-      call: ['getArguments', 'getMethod', ({getArguments, getMethod}, cbk) => {
+      // Derive arguments
+      arguments: ['getArguments', ({getArguments}, cbk) => {
         const arguments = getArguments.reduce((sum, answer) => {
           keys(answer).forEach(key => {
             if (answer[key] === Number()) {
@@ -133,6 +139,34 @@ module.exports = ({ask, lnd, method}, cbk) => {
         },
         {lnd});
 
+        return cbk(null, arguments);
+      }],
+
+      // Set up subscription
+      subscribe: ['arguments', 'getMethod', ({arguments, getMethod}, cbk) => {
+        // Exit early when this is a request/response API
+        if (!methodDetails(calls, getMethod.method).events) {
+          return cbk();
+        }
+
+        const sub = lnService[getMethod.method](arguments);
+
+        sub.on('error', err => cbk([503, 'ApiSubscriptionError', {err}]));
+
+        const {events} = methodDetails(calls, getMethod.method);
+
+        logger.info({listening_for: events});
+
+        events.forEach(n => sub.on(n, data => logger.info({[n]: data})));
+      }],
+
+      // Call API
+      call: ['arguments', 'getMethod', ({arguments, getMethod}, cbk) => {
+        // Exit early when this is an event-based API
+        if (!!methodDetails(calls, getMethod.method).events) {
+          return cbk();
+        }
+
         return lnService[getMethod.method](arguments, cbk);
       }],
     },

package/network/get_peers.js

@@ -1,5 +1,6 @@
 const asyncAuto = require('async/auto');
 const asyncMap = require('async/map');
+const asyncReflect = require('async/reflect');
 const asyncUntil = require('async/until');
 const {bold} = require('colorette');
 const {decodeChanId} = require('bolt07');
@@ -191,6 +192,11 @@ module.exports = (args, cbk) => {
         );
       }],
 
+      // Get the network name
+      getNetwork: ['validate', asyncReflect(({}, cbk) => {
+        return getNetwork({lnd: args.lnd}, cbk);
+      })],
+
       // Get payments
       getPayments: ['validate', ({}, cbk) => {
         // Exit early and skip long payments lookup when idle days not needed
@@ -330,6 +336,7 @@ module.exports = (args, cbk) => {
         'forwards',
         'getChannels',
         'getInvoices',
+        'getNetwork',
         'getPayments',
         'getPeers',
         'getPending',
@@ -339,6 +346,7 @@ module.exports = (args, cbk) => {
           forwards,
           getChannels,
           getInvoices,
+          getNetwork,
           getPayments,
           getPeers,
           getPending,
@@ -400,7 +408,7 @@ module.exports = (args, cbk) => {
 
         const maxInbound = args.inbound_liquidity_below;
         const maxOutbound = args.outbound_liquidity_below;
-        const {network} = await getNetwork({lnd: args.lnd});
+        const {network} = getNetwork.value || {};
         const peerKeys = getChannels.channels.map(n => n.partner_public_key);
         const wallet = await getHeight({lnd: args.lnd});
 

package/network/probe_destination.js

@@ -53,6 +53,7 @@ const tokAsMtok = tokens => (BigInt(tokens || 0) * BigInt(1e3)).toString();
       [to_public_key]: <Avoid Routing To Node With Public Key Hex String>
     }]
     [in_through]: <Pay In Through Public Key Hex String>
+    [is_omitting_message_from]: <Omit Message From Fields Bool>
     [is_push]: <Is Push Payment Bool>
     [is_real_payment]: <Pay the Request after Probing Bool> // default: false
     [is_strict_max_fee]: <Avoid Probing Too-High Fee Routes Bool>
@@ -238,14 +239,17 @@ module.exports = (args, cbk) => {
 
         date.writeUIntBE(now(), Number(), datePrecisionLength);
 
+        // Add message
         if (!!args.message) {
-          messages.push({type: dateType, value: date.toString('hex')});
-
           messages.push({
             type: messageType,
             value: Buffer.from(args.message).toString('hex'),
           });
+        }
 
+        // Add message from fields
+        if (!!args.message && !args.is_omitting_message_from) {
+          messages.push({type: dateType, value: date.toString('hex')});
           messages.push({type: fromKeyType, value: getIdentity.public_key});
 
           const preimage = Buffer.concat([

package/network/push_payment.js

@@ -39,6 +39,7 @@ const utf8AsHex = n => Buffer.from(n, 'utf8').toString('hex');
     }
     [in_through]: <Pay In Through Peer String>
     [is_dry_run]: <Do Not Push Payment Bool>
+    [is_omitting_message_from]: <Do Not Include From Key In Message Bool>
     lnd: <Authenticated LND API Object>
     logger: <Winston Logger Object>
     max_fee: <Maximum Fee Tokens Number>
@@ -74,6 +75,10 @@ module.exports = (args, cbk) => {
           return cbk([400, 'MultipleInboundPeersNotSupported']);
         }
 
+        if (!!args.is_omitting_message_from && !args.message) {
+          return cbk([400, 'ExpectedMessageToSendWhenSpecifyingOmitFromKey']);
+        }
+
         if (!args.lnd) {
           return cbk([400, 'ExpectedAuthenticatedLndToPushPayment']);
         }
@@ -365,6 +370,7 @@ module.exports = (args, cbk) => {
           lnd: args.lnd,
           logger: args.logger,
           in_through: getInKey,
+          is_omitting_message_from: args.is_omitting_message_from,
           is_push: true,
           is_real_payment: true,
           max_fee: args.max_fee,