Update documentation for lnd commands

documentation/lnd.md

@@ -1,149 +1,150 @@
 # lnd Support
-BitBook has basic support for [lnd (lightning network daemon)](https://github.com/lightningnetwork/lnd) so that you can
-add ownership information and helpful descriptions for transactions/addresses managed by your lnd instance without
+BitBook has support for [lnd (lightning network daemon)](https://github.com/lightningnetwork/lnd) so that you can
+add ownership information and helpful descriptions for transactions/addresses managed by your `lnd` instance without
 entering these manually.
 
-This is implemented by parsing JSON files generated by the `lncli` command line tool. As such, this involves a bit of
-manual effort, but it also keeps things simple. By copying these files you can easily use BitBook and lnd on
-different computers. Furthermore, by not giving BitBook access to lnd, there's no risk of undesired side effects.
+For this, BitBook parses JSON files you can generate using lnd's `lncli` command line tool. This has the advantage of
+keeping things simple. By copying these files you can easily use BitBook and `lnd` on different computers. Furthermore,
+by not giving BitBook access to lnd, there's no risk of undesired side effects.
 
-### Unspent Outputs
-Using `lncli listunspent` you can get a list of all unspent outputs managed by lnd.
-As such, BitBook should mark these addresses as owned (with the description "lnd").
-You can do this using the command `lnd-add-from-unspent-outputs`:
+### Creating JSON files
+Before you can use any of the command listed below, you need to create and transfer the necessary JSON input files:
+
+1. first create the JSON file using lnd: `$ lncli COMMAND > lnd-COMMAND.json` (where `COMMAND` is described below)
+2. transfer the JSON file to the host where you are running BitBook: `$ scp server:/home/lnd/lnd-COMMAND.json /tmp/`
 
-1. first create the JSON file using lnd: `$ lncli listunspent > lnd-unspent.json`
-2. transfer the JSON file to the host where you are running BitBook: `$ scp server:/home/lnd/lnd-unspent.json /tmp/`
-3. start BitBook
+### Unspent Outputs
+Using `lncli listunspent` you can get a list of all unspent outputs managed by `lnd`.
+BitBook marks these addresses as owned and sets the description to "lnd".
 
-Then you can use the command as follows:
+First, create and transfer the JSON file obtained by `lncli listunspent` (see [above](#creating-json-files)).
+Then, run the command `lnd-add-from-unspent-outputs` as follows:
 ```
-BitBook$ lnd-add-from-unspent-outputs /tmp/lnd-unspent.json
+BitBook$ lnd-add-from-unspent-outputs /tmp/lnd-listunspent.json
 Marked 6 addresses as owned by lnd
 ```
 
 ### Sweeps
 After a channel is closed, your funds (on the "local" side of the channel) are sent to an address that is not derived
-from your lnd wallet seed. To avoid loss of funds, lnd automatically "sweeps" those funds to another address. As such,
-there may be several sweep transactions that transfer funds from one address to another.
+from your `lnd` wallet seed. To avoid loss of funds, `lnd` automatically "sweeps" those funds to another address. As
+such, there may be several sweep transactions that transfer funds from one address to another.
 
-BitBook offers the command `lnd-add-from-sweeps` which parses lnd sweep information and does the following for each
-transaction:
+BitBook offers the command `lnd-add-from-sweeps` which parses `lnd` sweep information and, for each transaction:
 
  - sets the transaction description to "lnd sweep transaction"
  - sets the source and target addresses descriptions to "lnd"
  - marks both addresses as owned
 
-To run the command:
-1. first create the JSON file using lnd: `$ lncli wallet listsweeps > lnd-sweeps.json`
-2. transfer the JSON file to the host where you are running BitBook: `$ scp server:/home/lnd/lnd-sweeps.json /tmp/`
-3. start BitBook
-
-Then you can use the command as follows:
+First, create and transfer the JSON file obtained by `lncli wallet listsweeps` (see [above](#creating-json-files)).
+Then, run the command `lnd-add-from-sweeps` as follows:
 ```
-BitBook$ lnd-add-from-sweeps /tmp/lnd-sweeps.json
+BitBook$ lnd-add-from-sweeps /tmp/lnd-wallet-listsweeps.json
 Added information for 86 sweep transactions
 ```
 
 ### Channels
-lnd stores information about channels, including references to the opening transaction and whether you opened the
-channel.
-
-BitBook offers the command `lnd-add-from-channels` which parses this information and
-
-- marks the channel address as owned if you opened the channel, or as foreign if the remote opened the channel
-- sets the channel address description to "Lightning-Channel with <pubkey>"
-- sets the description to "Opening Channel with <pubkey> (<type>)"
-  - type is one out of "local" or "remote"
+`lnd` stores information about channels, including references to the opening transaction and whether you or the remote
+node opened the channel.
 
-Notes:
-
-- If your lnd node has channels to another node you own, setting ownership of the address belonging to the remote
-  node as *foreign* may be wrong. To avoid this, for addresses already marked as *owned* the ownership is not changed.
-- If a transaction opens more than one channel, only one of these is mentioned in the description.
+BitBook uses this information and
 
-To run the command:
-1. first create the JSON file using lnd: `$ lncli listchannels > lnd-channels.json`
-2. transfer the JSON file to the host where you are running BitBook: `$ scp server:/home/lnd/lnd-channels.json /tmp/`
-3. start BitBook
+- marks the channel address as owned if you opened the channel, or as foreign if the remote node opened the channel
+- sets the channel address description to "Lightning-Channel with {pubkey}" where `{pubkey}` is the remote node's public
+  key
+- sets the transaction description to "Opening Channel with {pubkey} ({type})" where `{type}` is "local" or "remote"
 
-Then you can use the command as follows:
+First, create and transfer the JSON file obtained by `lncli listchannels` (see [above](#creating-json-files)).
+Then, run the command `lnd-add-from-channels` as follows:
 ```
-BitBook$ lnd-add-from-channels /tmp/lnd-channels.json
+BitBook$ lnd-add-from-channels /tmp/lnd-listchannels.json
 Added information for 67 channels
 ```
 
-### Closed Channels
-lnd stores information about closed channels, including references to the opening and closing transactions.
-This record also includes information about the value returned to your own wallet.
-
-BitBook offers the command `lnd-add-from-closed-channels` which parses this information and
-
-- marks the channel address (input of closing transaction) as owned if you opened the channel,
-  or as foreign if the remote opened the channel
-- for the closing transaction:
-  - sets the description to "Closing Channel with <pubkey> (<type>)"
-    - type is one out of "cooperative", "cooperative local", "cooperative remote", "force local", "force remote"
-  - sets the input address description to "Lightning-Channel with <pubkey>"
-  - for addresses which are used to return channel funds, marks these as owned
-  - handles sweep transactions mentioned in HTLC resolutions (see [Sweeps](#sweeps))
-- for the opening transaction:
-  - sets the description to "Opening Channel with <pubkey> (<type>)"
-    - type is one out of "local", "remote", "unknown"
-
 Notes:
 
-- If your lnd node has/had channels to another node you own, setting ownership of the address belonging to the remote
-  node as *foreign* may be wrong. To avoid this, for addresses already marked as *owned* the ownership is not changed.
+- If you are also the owner of the remote node of one of the channels, setting ownership of the address belonging to the
+  remote node as *foreign* may be wrong. To avoid this, for addresses already marked as *owned* the ownership is not
+  changed.
 - If a transaction opens more than one channel, only one of these is mentioned in the description.
 
-To run the command:
-1. first create the JSON file using lnd: `$ lncli closedchannels > lnd-closedchannels.json`
-2. transfer the JSON file to the host where you are running BitBook: `$ scp server:/home/lnd/lnd-closedchannels.json /tmp/`
-3. start BitBook
-
-Then you can use the command as follows:
+### Closed Channels
+In addition to open channels, `lnd` also stores information about closed channels. This includes references to both the
+opening and closing transactions, and information about the amount returned to your own wallet.
+
+BitBook makes use of this information and
+
+- marks the channel address as owned if you opened the channel, or as foreign if the remote node opened the channel 
+- sets the channel address description to "Lightning-Channel with {pubkey}" where `{pubkey}` is the remote node's public
+  key
+- sets the *closing* transaction description to "Closing Channel with {pubkey} ({type})" where `{type}` is one out of
+  "cooperative", "cooperative local", "cooperative remote", "force local", or "force remote"
+- sets the *opening* transaction description to "Opening Channel with {pubkey} ({type})" where `{type}` is
+      "local", "remote", or "unknown"
+- for outputs that receive funds marks their addresses as owned
+- for cooperative closes, mark all other (unowned) outputs as foreign
+- handles sweep transactions mentioned in HTLC resolutions (see [Sweeps](#sweeps))
+
+First, create and transfer the JSON file obtained by `lncli closedchannels` (see [above](#creating-json-files)).
+Then, run the command `lnd-add-from-closed-channels` as follows:
 ```
 BitBook$ lnd-add-from-closed-channels /tmp/lnd-closedchannels.json
-Added information for 99 channels
+Added information for 99 closed channels
 ```
+
+Notes:
 
-### On-Chain Transactions
-lnd keeps a record of all on-chain transactions, which includes regular transactions from/to lnd's wallet, and channel
-opening transactions. You can make use of this information by using the command `lnd-add-from-onchain-transactions`.
+- If you are also the owner of the remote node of one of the channels, setting ownership of the address belonging to the
+  remote node as *foreign* may be wrong. To avoid this, for addresses already marked as *owned* the ownership is not
+  changed.
+- If a transaction opens more than one channel, only one of these is mentioned in the description.
+- Currently, BitBook is unable to determine all neccessary ownership information for addresses that result out of
+  unsettled HTLC transactions. See [issue #90](https://github.com/C-Otto/BitBook/issues/89).
 
-Currently, the following transaction types are supported:
+### On-Chain Transactions
+`lnd` keeps a record of all on-chain transactions, which includes regular transactions from/to `lnd`'s wallet.
+BitBook is able to distinguish the following transaction types:
 
 1. **Funding Transactions**
 
-   For transactions that send funds to lnd's wallet, the target address is marked as owned.
-Furthermore, the description "lnd" is added.
+   For transactions that send funds to `lnd`'s wallet, the target address is marked as owned, and
+   the description "lnd" is set for the address.
+   This is only done if no label is set for the transaction (in `lnd`).
+
+2. **Spending Transactions**
+
+   For transactions that send funds from `lnd`'s wallet, the source and change addresses are marked as owned, and
+   the description "lnd" is set for the addresses.
+   This is only done if all addresses are alreayd marked as owned and if no label is set for the transaction (in `lnd`).
 
-2. **Channel Opening Transactions**
+3. **Channel Opening Transactions**
 
    For transactions where one of the outputs is a lightning channel that is already marked as owned, the other
    output addresses are also marked as owned if:
 
    - all inputs are owned and have the description "lnd"
-   - the amount referenced in the transaction matches the channel balance
    - the channel address has a description as set by BitBook
+   - the amount referenced in the transaction matches the channel balance
 
-   *Important:* To satisfy the first criterion, you should run the other lnd commands first.
+   *Important:* To satisfy the first two criteria, you should run the other `lnd` related commands first.
 
-3. **pool Account Creation Transactions**
+    BitBook also updates the initiator in the transaction description to "local", if it was set to "unknown".
 
-   If you use lnd with [pool](https://github.com/lightninglabs/pool), BitBook can read information about transactions
-   that create a new pool account. If such a transaction is found, all inputs and outputs are automatically marked as
-   owned. For lnd addresses the description "lnd" is set. For the pool address, the address description is set to
-   "pool account <account-id>", and the transaction description is set to "Creating pool account <account-id>".
+4. **Sweep Transactions**
+
+   For transactions that only transfer funds from one address managed by `lnd` to another address managed by `lnd`
+   the changes as described in [Sweeps](#sweeps) are applied.
+
+5. **pool Account Creation Transactions**
 
-To run the command:
-1. first create the JSON file using lnd: `$ lncli listchaintxns > lnd-onchain-transactions.json`
-2. transfer the JSON file to the host where you are running BitBook: `$ scp server:/home/lnd/lnd-onchain-transactions.json /tmp/`
-3. start BitBook
+   If you use `lnd` with [pool](https://github.com/lightninglabs/pool), BitBook can read information about transactions
+   that create, update, or close a `pool` account. In all cases, all addresses are marked as owned, and the address
+   descriptions are set to "lnd" or "pool account {pool-id}". The transaction description is set to
+   "Creating pool account {account-id}", "Closing pool account {account-id}", or
+   "Deposit into pool account {account-id}".
 
-Then you can use the command as follows:
+First, create and transfer the JSON file obtained by `lncli listchaintxns` (see [above](#creating-json-files)).
+Then, run the command `lnd-add-from-onchain-transactions` as follows:
 ```
-BitBook$ lnd-add-from-onchain-transactions /tmp/lnd-onchain-transactions.json
+BitBook$ lnd-add-from-onchain-transactions /tmp/lnd-listchaintxns.json
 Added information from 671 transactions
 ```

lnd/src/main/java/de/cotto/bitbook/lnd/features/ChannelsService.java

@@ -37,16 +37,6 @@ public long addFromChannels(Set<Channel> channels) {
         return channels.size();
     }
 
-    private void setChannelOwnership(Channel channel) {
-        String channelAddress = channel.getChannelAddress();
-        if (channel.isInitiator()) {
-            addressOwnershipService.setAddressAsOwned(channelAddress);
-        }
-        if (!OWNED.equals(addressOwnershipService.getOwnershipStatus(channelAddress))) {
-            addressOwnershipService.setAddressAsForeign(channelAddress);
-        }
-    }
-
     private void setTransactionDescription(Channel channel) {
         String localOrRemote;
         if (channel.isInitiator()) {
@@ -66,4 +56,14 @@ private void setAddressDescription(Channel channel) {
                 ADDRESS_DESCRIPTION_PREFIX + channel.getRemotePubkey()
         );
     }
+
+    private void setChannelOwnership(Channel channel) {
+        String channelAddress = channel.getChannelAddress();
+        if (channel.isInitiator()) {
+            addressOwnershipService.setAddressAsOwned(channelAddress);
+        }
+        if (!OWNED.equals(addressOwnershipService.getOwnershipStatus(channelAddress))) {
+            addressOwnershipService.setAddressAsForeign(channelAddress);
+        }
+    }
 }

lnd/src/main/java/de/cotto/bitbook/lnd/features/ClosedChannelsService.java

@@ -54,14 +54,6 @@ private ClosedChannel addFromClosedChannel(ClosedChannel closedChannel) {
         return closedChannel;
     }
 
-    private void addFromHtlcSweepTransactions(ClosedChannel closedChannel) {
-        Set<String> sweepTransactionHashes = closedChannel.getResolutions().stream()
-                .map(Resolution::getSweepTransactionHash)
-                .filter(sweepTransactonHash -> !sweepTransactonHash.isBlank())
-                .collect(Collectors.toSet());
-        sweepTransactionsService.addFromSweeps(sweepTransactionHashes);
-    }
-
     private void setTransactionDescriptions(ClosedChannel closedChannel) {
         String remotePubkey = closedChannel.getRemotePubkey();
         transactionDescriptionService.set(
@@ -98,6 +90,10 @@ private void setChannelAddressOwnershipAndDescription(
         setChannelAddressOwnership(channelAddress, openInitiator);
     }
 
+    private void setChannelAddressDescription(String channelAddress, String remotePubkey) {
+        addressDescriptionService.set(channelAddress, "Lightning-Channel with " + remotePubkey);
+    }
+
     private void setChannelAddressOwnership(String channelAddress, Initiator openInitiator) {
         if (openInitiator.equals(Initiator.LOCAL)) {
             addressOwnershipService.setAddressAsOwned(channelAddress);
@@ -109,7 +105,11 @@ private void setChannelAddressOwnership(String channelAddress, Initiator openIni
         }
     }
 
-    private void setChannelAddressDescription(String channelAddress, String remotePubkey) {
-        addressDescriptionService.set(channelAddress, "Lightning-Channel with " + remotePubkey);
+    private void addFromHtlcSweepTransactions(ClosedChannel closedChannel) {
+        Set<String> sweepTransactionHashes = closedChannel.getResolutions().stream()
+                .map(Resolution::getSweepTransactionHash)
+                .filter(sweepTransactionHash -> !sweepTransactionHash.isBlank())
+                .collect(Collectors.toSet());
+        sweepTransactionsService.addFromSweeps(sweepTransactionHashes);
     }
 }