lnrpc+rpcserver: verbose result in ChannelBalance

lnrpc/rpc.proto

@@ -32,8 +32,9 @@ service Lightning {
     rpc WalletBalance (WalletBalanceRequest) returns (WalletBalanceResponse);
 
     /* lncli: `channelbalance`
-    ChannelBalance returns the total funds available across all open channels
+    ChannelBalance returns a report on the total funds across all open channels,
-    in satoshis.
+    categorized in local/remote, pending local/remote and unsettled local/remote
+    balances.
     */
     rpc ChannelBalance (ChannelBalanceRequest) returns (ChannelBalanceResponse);
 
@@ -2133,14 +2134,40 @@ message WalletBalanceResponse {
     int64 unconfirmed_balance = 3;
 }
 
+message Amount {
+    // Value denominated in satoshis.
+    uint64 sat = 1;
+
+    // Value denominated in milli-satoshis.
+    uint64 msat = 2;
+}
+
 message ChannelBalanceRequest {
 }
 message ChannelBalanceResponse {
-    // Sum of channels balances denominated in satoshis
+    // Deprecated. Sum of channels balances denominated in satoshis
-    int64 balance = 1;
+    int64 balance = 1 [deprecated = true];
 
-    // Sum of channels pending balances denominated in satoshis
+    // Deprecated. Sum of channels pending balances denominated in satoshis
-    int64 pending_open_balance = 2;
+    int64 pending_open_balance = 2 [deprecated = true];
+
+    // Sum of channels local balances.
+    Amount local_balance = 3;
+
+    // Sum of channels remote balances.
+    Amount remote_balance = 4;
+
+    // Sum of channels local unsettled balances.
+    Amount unsettled_local_balance = 5;
+
+    // Sum of channels remote unsettled balances.
+    Amount unsettled_remote_balance = 6;
+
+    // Sum of channels pending local balances.
+    Amount pending_open_local_balance = 7;
+
+    // Sum of channels pending remote balances.
+    Amount pending_open_remote_balance = 8;
 }
 
 message QueryRoutesRequest {

lnrpc/rpc.swagger.json

@@ -36,7 +36,7 @@
     },
     "/v1/balance/channels": {
       "get": {
-        "summary": "lncli: `channelbalance`\nChannelBalance returns the total funds available across all open channels\nin satoshis.",
+        "summary": "lncli: `channelbalance`\nChannelBalance returns a report on the total funds across all open channels,\ncategorized in local/remote, pending local/remote and unsettled local/remote\nbalances.",
         "operationId": "ChannelBalance",
         "responses": {
           "200": {
@@ -2476,6 +2476,21 @@
       "description": "- `p2wkh`: Pay to witness key hash (`WITNESS_PUBKEY_HASH` = 0)\n- `np2wkh`: Pay to nested witness key hash (`NESTED_PUBKEY_HASH` = 1)",
       "title": "`AddressType` has to be one of:"
     },
+    "lnrpcAmount": {
+      "type": "object",
+      "properties": {
+        "sat": {
+          "type": "string",
+          "format": "uint64",
+          "description": "Value denominated in satoshis."
+        },
+        "msat": {
+          "type": "string",
+          "format": "uint64",
+          "description": "Value denominated in milli-satoshis."
+        }
+      }
+    },
     "lnrpcBakeMacaroonRequest": {
       "type": "object",
       "properties": {
@@ -2813,12 +2828,36 @@
         "balance": {
           "type": "string",
           "format": "int64",
-          "title": "Sum of channels balances denominated in satoshis"
+          "title": "Deprecated. Sum of channels balances denominated in satoshis"
         },
         "pending_open_balance": {
           "type": "string",
           "format": "int64",
-          "title": "Sum of channels pending balances denominated in satoshis"
+          "title": "Deprecated. Sum of channels pending balances denominated in satoshis"
+        },
+        "local_balance": {
+          "$ref": "#/definitions/lnrpcAmount",
+          "description": "Sum of channels local balances."
+        },
+        "remote_balance": {
+          "$ref": "#/definitions/lnrpcAmount",
+          "description": "Sum of channels remote balances."
+        },
+        "unsettled_local_balance": {
+          "$ref": "#/definitions/lnrpcAmount",
+          "description": "Sum of channels local unsettled balances."
+        },
+        "unsettled_remote_balance": {
+          "$ref": "#/definitions/lnrpcAmount",
+          "description": "Sum of channels remote unsettled balances."
+        },
+        "pending_open_local_balance": {
+          "$ref": "#/definitions/lnrpcAmount",
+          "description": "Sum of channels pending local balances."
+        },
+        "pending_open_remote_balance": {
+          "$ref": "#/definitions/lnrpcAmount",
+          "description": "Sum of channels pending remote balances."
         }
       }
     },

rpcserver.go

@@ -2852,16 +2852,36 @@ func (r *rpcServer) WalletBalance(ctx context.Context,
 // ChannelBalance returns the total available channel flow across all open
 // channels in satoshis.
 func (r *rpcServer) ChannelBalance(ctx context.Context,
-	in *lnrpc.ChannelBalanceRequest) (*lnrpc.ChannelBalanceResponse, error) {
+	in *lnrpc.ChannelBalanceRequest) (
+	*lnrpc.ChannelBalanceResponse, error) {
+
+	var (
+		localBalance             lnwire.MilliSatoshi
+		remoteBalance            lnwire.MilliSatoshi
+		unsettledLocalBalance    lnwire.MilliSatoshi
+		unsettledRemoteBalance   lnwire.MilliSatoshi
+		pendingOpenLocalBalance  lnwire.MilliSatoshi
+		pendingOpenRemoteBalance lnwire.MilliSatoshi
+	)
 
 	openChannels, err := r.server.remoteChanDB.FetchAllOpenChannels()
 	if err != nil {
 		return nil, err
 	}
 
-	var balance btcutil.Amount
 	for _, channel := range openChannels {
-		balance += channel.LocalCommitment.LocalBalance.ToSatoshis()
+		c := channel.LocalCommitment
+		localBalance += c.LocalBalance
+		remoteBalance += c.RemoteBalance
+
+		// Add pending htlc amount.
+		for _, htlc := range c.Htlcs {
+			if htlc.Incoming {
+				unsettledLocalBalance += htlc.Amt
+			} else {
+				unsettledRemoteBalance += htlc.Amt
+			}
+		}
 	}
 
 	pendingChannels, err := r.server.remoteChanDB.FetchPendingChannels()
@@ -2869,17 +2889,48 @@ func (r *rpcServer) ChannelBalance(ctx context.Context,
 		return nil, err
 	}
 
-	var pendingOpenBalance btcutil.Amount
 	for _, channel := range pendingChannels {
-		pendingOpenBalance += channel.LocalCommitment.LocalBalance.ToSatoshis()
+		c := channel.LocalCommitment
+		pendingOpenLocalBalance += c.LocalBalance
+		pendingOpenRemoteBalance += c.RemoteBalance
 	}
 
-	rpcsLog.Debugf("[channelbalance] balance=%v pending-open=%v",
+	rpcsLog.Debugf("[channelbalance] local_balance=%v remote_balance=%v "+
-		balance, pendingOpenBalance)
+		"unsettled_local_balance=%v unsettled_remote_balance=%v "+
+		"pending_open_local_balance=%v pending_open_remove_balance",
+		localBalance, remoteBalance, unsettledLocalBalance,
+		unsettledRemoteBalance, pendingOpenLocalBalance,
+		pendingOpenRemoteBalance)
 
 	return &lnrpc.ChannelBalanceResponse{
-		Balance:            int64(balance),
+		LocalBalance: &lnrpc.Amount{
-		PendingOpenBalance: int64(pendingOpenBalance),
+			Sat:  uint64(localBalance.ToSatoshis()),
+			Msat: uint64(localBalance),
+		},
+		RemoteBalance: &lnrpc.Amount{
+			Sat:  uint64(remoteBalance.ToSatoshis()),
+			Msat: uint64(remoteBalance),
+		},
+		UnsettledLocalBalance: &lnrpc.Amount{
+			Sat:  uint64(unsettledLocalBalance.ToSatoshis()),
+			Msat: uint64(unsettledLocalBalance),
+		},
+		UnsettledRemoteBalance: &lnrpc.Amount{
+			Sat:  uint64(unsettledRemoteBalance.ToSatoshis()),
+			Msat: uint64(unsettledRemoteBalance),
+		},
+		PendingOpenLocalBalance: &lnrpc.Amount{
+			Sat:  uint64(pendingOpenLocalBalance.ToSatoshis()),
+			Msat: uint64(pendingOpenLocalBalance),
+		},
+		PendingOpenRemoteBalance: &lnrpc.Amount{
+			Sat:  uint64(pendingOpenRemoteBalance.ToSatoshis()),
+			Msat: uint64(pendingOpenRemoteBalance),
+		},
+
+		// Deprecated fields.
+		Balance:            int64(localBalance.ToSatoshis()),
+		PendingOpenBalance: int64(pendingOpenLocalBalance.ToSatoshis()),
 	}, nil
 }