lightningd: add ordering and pagination to listforwards.

Changelog-Added: JSON-RPC: `listforwards` new parameters `index`, `start` and `limit`.

.msggen.json

@@ -92,6 +92,10 @@
             "legacy": 0,
             "tlv": 1
         },
+        "ListforwardsIndex": {
+            "created": 0,
+            "updated": 1
+        },
         "ListforwardsStatus": {
             "failed": 3,
             "local_failed": 2,
@@ -940,7 +944,10 @@
         },
         "ListforwardsRequest": {
             "ListForwards.in_channel": 2,
+            "ListForwards.index": 4,
+            "ListForwards.limit": 6,
             "ListForwards.out_channel": 3,
+            "ListForwards.start": 5,
             "ListForwards.status": 1
         },
         "ListforwardsResponse": {
@@ -3624,10 +3631,22 @@
             "added": "pre-v0.10.1",
             "deprecated": false
         },
+        "ListForwards.index": {
+            "added": "v23.11",
+            "deprecated": false
+        },
+        "ListForwards.limit": {
+            "added": "v23.11",
+            "deprecated": false
+        },
         "ListForwards.out_channel": {
             "added": "pre-v0.10.1",
             "deprecated": false
         },
+        "ListForwards.start": {
+            "added": "v23.11",
+            "deprecated": false
+        },
         "ListForwards.status": {
             "added": "pre-v0.10.1",
             "deprecated": false

contrib/pyln-client/pyln/client/lightning.py

@@ -1007,14 +1007,17 @@ def listdatastore(self, key=None):
         }
         return self.call("listdatastore", payload)
 
-    def listforwards(self, status=None, in_channel=None, out_channel=None):
+    def listforwards(self, status=None, in_channel=None, out_channel=None, index=None, start=None, limit=None):
         """List all forwarded payments and their information matching
         forward {status}, {in_channel} and {out_channel}.
         """
         payload = {
             "status": status,
             "in_channel": in_channel,
             "out_channel": out_channel,
+            "index": index,
+            "start": start,
+            "limit": limit,
         }
         return self.call("listforwards", payload)
 

doc/lightning-listforwards.7.md

@@ -4,7 +4,7 @@ lightning-listforwards -- Command showing all htlcs and their information
 SYNOPSIS
 --------
 
-**listforwards** [*status*] [*in\_channel*] [*out\_channel*]
+**listforwards** [*status*] [*in\_channel*] [*out\_channel*] [*index* [*start*] [*limit*]]
 
 DESCRIPTION
 -----------
@@ -18,6 +18,12 @@ If *status* is specified, then only the forwards with the given status are retur
 If *in\_channel* or *out\_channel* is specified, then only the matching forwards
 on the given in/out channel are returned.
 
+If neither *in\_channel* or *out\_channel* is specified,
+`index` controls ordering, by `created` (default) or `updated`.  If
+`index` is specified, `start` may be specified to start from that
+value, which is generally returned from lightning-wait(7), and `limit`
+can be used to specify the maximum number of entries to return.
+
 RETURN VALUE
 ------------
 

doc/schemas/listforwards.request.json

@@ -17,6 +17,25 @@
     },
     "out_channel": {
       "type": "short_channel_id"
+    },
+    "index": {
+      "type": "string",
+      "added": "v23.11",
+      "enum": [
+        "created",
+        "updated"
+      ],
+      "description": ""
+    },
+    "start": {
+      "type": "u64",
+      "added": "v23.11",
+      "description": ""
+    },
+    "limit": {
+      "type": "u32",
+      "added": "v23.11",
+      "description": ""
     }
   }
 }

lightningd/forwards.c

@@ -149,11 +149,14 @@ static void listforwardings_add_forwardings(struct json_stream *response,
 					    struct wallet *wallet,
 					    enum forward_status status,
 					    const struct short_channel_id *chan_in,
-					    const struct short_channel_id *chan_out)
+					    const struct short_channel_id *chan_out,
+					    const enum wait_index *listindex,
+					    u64 liststart,
+					    const u32 *listlimit)
 {
 	const struct forwarding *forwardings;
 
-	forwardings = wallet_forwarded_payments_get(wallet, tmpctx, status, chan_in, chan_out);
+	forwardings = wallet_forwarded_payments_get(wallet, tmpctx, status, chan_in, chan_out, listindex, liststart, listlimit);
 
 	json_array_start(response, "forwards");
 	for (size_t i=0; i<tal_count(forwardings); i++) {
@@ -190,17 +193,37 @@ static struct command_result *json_listforwards(struct command *cmd,
 	struct json_stream *response;
 	struct short_channel_id *chan_in, *chan_out;
 	enum forward_status *status;
+	enum wait_index *listindex;
+	u64 *liststart;
+	u32 *listlimit;
 
 	if (!param(cmd, buffer, params,
 		   p_opt_def("status", param_forward_status, &status,
 			     FORWARD_ANY),
 		   p_opt("in_channel", param_short_channel_id, &chan_in),
 		   p_opt("out_channel", param_short_channel_id, &chan_out),
+		   p_opt("index", param_index, &listindex),
+		   p_opt_def("start", param_u64, &liststart, 0),
+		   p_opt("limit", param_u32, &listlimit),
 		   NULL))
 		return command_param_failed();
 
+	if (*liststart != 0 && !listindex) {
+		return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
+				    "Can only specify {start} with {index}");
+	}
+	if (listlimit && !listindex) {
+		return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
+				    "Can only specify {limit} with {index}");
+	}
+
+	if ((chan_in || chan_out) && *liststart != 0) {
+		return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
+				    "Cannot use start with in_channel or out_channel");
+	}
+
 	response = json_stream_success(cmd);
-	listforwardings_add_forwardings(response, cmd->ld->wallet, *status, chan_in, chan_out);
+	listforwardings_add_forwardings(response, cmd->ld->wallet, *status, chan_in, chan_out, listindex, *liststart, listlimit);
 
 	return command_success(cmd, response);
 }