There exist three states of pending funds within lnd as it's writen today:

1. A channel funding workflow has completed, and a channel is about to be "open". The funds are in limbo until the channel reaches N confirmations.
2. A channel has been cooperatively closed, and the funds are in limbo until the closure transaction reaches a single confirmation.
3. A channel has been unilaterally (forcibly) closed, and the funds are in limbo until T blocks have passed, and the time-lock sweeping transaction enters the chain.

Currently the PendingChannels RPC only shows the channels that are about to be opened and are awaiting N confirmations before they're considered open. The proto itself PendingChannelResponse includes an enum for each pending channel which tells if the channel is being opened or closed. Currently, only channels that are in the process of being opened are display in the response to the request. In order to give higher level applications and wallets more visibility into the various states that funds within lnd can idle in, the RPC response should be extended to display more granular information w.r.t "pending funds" in lnd's wallet.

Steps To Completion

• Expand the concept of "close summaries" (a distinct db bucket)within the database to also include the following information:
  • If the channel was closed forcibly or cooperatively.
  • The total amount of funds allocated to us (including HTLC's) within the commitment transaction when the channel was closed.
• Callers that close a channel should use a newly updated version of CloseChannel which toggles if the channel was closed forcibly or cooperatively.
• A bool should be addd to the close summary which details if the "closing" process is still pending or active. This would be similar to the MarkChannelPending and MarkChannelOpen methods for the channeldb.OpenChannel struct. Once the channel has been fully closed, then most of the limbo balance data in the close channel bucket can safely be deleted, and replaced with either: just the closing tx txid, and the closing txid + the sweeping channel txid.
• The PendingChannels RPC should be expanded to scan the database for channels still actively undergoing closing, and populate the RPC's accordingly based off of this data. This will populate the item listed as #2 in the list above.
• With the above completed, two areas in the codebase will need to be modified in order to properly manage the channel closure states within the database: the peer struct, and the utxoNursery.
  • Once the peer struct initiates a cooperative channel closure, the target channel should be marked as closed.
  • Once the utxoNursery graduates (sweeps) a set of outputs, the channels swept would me themselves marked as closed.