fixup! Use ldk-node payment pagination

Expose page tokens as one opaque string across the gRPC, CLI, and MCP
interfaces. This keeps storage-specific token fields out of the public
API.

Keep the forwarded-payment cursor encoding inside the server and reject
malformed cursors as invalid requests.

AI assistance: OpenAI Codex was used for this change.

Author: benthecarman

docs/api-guide.md

@@ -268,6 +268,7 @@ force-closure of the channel.
 2. If the response includes a `next_page_token`, pass it as `page_token` in the next request.
 3. When `next_page_token` is absent, you have reached the end of the results.
 
-Results are ordered by creation time (most recent first).
+The page token is one opaque string. Do not parse or modify it. Results are ordered by creation
+time (most recent first).
 
 The CLI `--number-of-payments` option combines multiple pages. It does not set the gRPC page size.

ldk-server-cli/src/main.rs

@@ -50,7 +50,7 @@ use ldk_server_client::ldk_server_grpc::api::{
 };
 use ldk_server_client::ldk_server_grpc::types::{
 	bolt11_invoice_description, Bolt11InvoiceDescription, ChannelConfig, CustomTlvRecord,
-	PageToken, PayerProofOptions, RouteParametersConfig,
+	PayerProofOptions, RouteParametersConfig,
 };
 use ldk_server_client::{
 	DEFAULT_EXPIRY_SECS, DEFAULT_MAX_CHANNEL_SATURATION_POWER_OF_HALF, DEFAULT_MAX_PATH_COUNT,
@@ -540,7 +540,7 @@ enum Commands {
 		)]
 		number_of_payments: Option<u64>,
 		#[arg(long)]
-		#[arg(help = "Page token to continue from a previous page (format: token:index)")]
+		#[arg(help = "Opaque page token returned by a previous request")]
 		page_token: Option<String>,
 	},
 	#[command(about = "Get details of a specific payment by its payment ID")]
@@ -556,7 +556,7 @@ enum Commands {
 			help = "Fetch at least this many forwarded payments by iterating through multiple pages. Returns combined results with the last page token. If not provided, returns only a single page."
 		)]
 		number_of_payments: Option<u64>,
-		#[arg(long, help = "Page token to continue from a previous page (format: token:index)")]
+		#[arg(long, help = "Opaque page token returned by a previous request")]
 		page_token: Option<String>,
 	},
 	#[command(about = "Update the forwarding fees and CLTV expiry delta for an existing channel")]
@@ -1174,9 +1174,6 @@ async fn main() {
 			);
 		},
 		Commands::ListPayments { number_of_payments, page_token } => {
-			let page_token = page_token
-				.map(|token_str| parse_page_token(&token_str).unwrap_or_else(|e| handle_error(e)));
-
 			handle_response_result::<_, CliListPaymentsResponse>(
 				fetch_paginated(
 					number_of_payments,
@@ -1193,9 +1190,6 @@ async fn main() {
 			);
 		},
 		Commands::ListForwardedPayments { number_of_payments, page_token } => {
-			let page_token = page_token
-				.map(|token_str| parse_page_token(&token_str).unwrap_or_else(|e| handle_error(e)));
-
 			handle_response_result::<_, CliListForwardedPaymentsResponse>(
 				fetch_paginated(
 					number_of_payments,
@@ -1334,9 +1328,8 @@ fn build_open_channel_config(
 }
 
 async fn fetch_paginated<T, R, Fut>(
-	target_count: Option<u64>, initial_page_token: Option<PageToken>,
-	fetch_page: impl Fn(Option<PageToken>) -> Fut,
-	extract: impl Fn(R) -> (Vec<T>, Option<PageToken>),
+	target_count: Option<u64>, initial_page_token: Option<String>,
+	fetch_page: impl Fn(Option<String>) -> Fut, extract: impl Fn(R) -> (Vec<T>, Option<String>),
 ) -> Result<CliPaginatedResponse<T>, LdkServerError>
 where
 	Fut: std::future::Future<Output = Result<R, LdkServerError>>,
@@ -1446,19 +1439,6 @@ fn parse_bolt11_invoice_description(
 	}
 }
 
-fn parse_page_token(token_str: &str) -> Result<PageToken, LdkServerError> {
-	let (token, index) = token_str.rsplit_once(':').ok_or_else(|| {
-		LdkServerError::new(
-			InvalidRequestError,
-			"Page token must be in format 'token:index'".to_string(),
-		)
-	})?;
-	let index = index.parse::<i64>().map_err(|_| {
-		LdkServerError::new(InvalidRequestError, "Invalid page token index".to_string())
-	})?;
-	Ok(PageToken { token: token.to_string(), index })
-}
-
 fn parse_custom_tlv(s: &str) -> Result<(u64, Vec<u8>), String> {
 	let (type_str, hex_str) =
 		s.split_once(':').ok_or_else(|| format!("expected <type_num>:<hex_value>, got '{s}'"))?;
@@ -1500,13 +1480,11 @@ mod tests {
 			None,
 			|page_token| async move {
 				match page_token {
-					None => Ok::<_, LdkServerError>((
-						vec![1, 2],
-						Some(PageToken { token: "store:v2:cursor".to_string(), index: 7 }),
-					)),
+					None => {
+						Ok::<_, LdkServerError>((vec![1, 2], Some("store:v2:cursor:7".to_string())))
+					},
 					Some(token) => {
-						assert_eq!(token.token, "store:v2:cursor");
-						assert_eq!(token.index, 7);
+						assert_eq!(token, "store:v2:cursor:7");
 						Ok((vec![3], None))
 					},
 				}
@@ -1520,13 +1498,6 @@ mod tests {
 		assert!(response.next_page_token.is_none());
 	}
 
-	#[test]
-	fn parse_page_token_accepts_colons_in_token() {
-		let token = parse_page_token("store:v2:cursor:7").unwrap();
-		assert_eq!(token.token, "store:v2:cursor");
-		assert_eq!(token.index, 7);
-	}
-
 	#[test]
 	fn parse_custom_tlv_accepts_valid_record() {
 		let (type_num, value) = parse_custom_tlv("65537:deadbeef").unwrap();

ldk-server-cli/src/types.rs

@@ -17,11 +17,11 @@ use std::fmt;
 use std::str::FromStr;
 
 use hex_conservative::{DisplayHex, FromHex};
-use ldk_server_client::ldk_server_grpc::types::{ForwardedPayment, PageToken, Payment};
+use ldk_server_client::ldk_server_grpc::types::{ForwardedPayment, Payment};
 use serde::Serialize;
 
-/// CLI-specific wrapper for paginated responses that formats the page token
-/// as "token:idx" instead of a JSON object.
+/// CLI-specific wrapper for paginated responses that keeps the page token as
+/// one opaque string.
 #[derive(Debug, Clone, Serialize)]
 pub struct CliPaginatedResponse<T> {
 	/// List of items.
@@ -32,18 +32,14 @@ pub struct CliPaginatedResponse<T> {
 }
 
 impl<T> CliPaginatedResponse<T> {
-	pub fn new(list: Vec<T>, next_page_token: Option<PageToken>) -> Self {
-		Self { list, next_page_token: next_page_token.map(format_page_token) }
+	pub fn new(list: Vec<T>, next_page_token: Option<String>) -> Self {
+		Self { list, next_page_token }
 	}
 }
 
 pub type CliListPaymentsResponse = CliPaginatedResponse<Payment>;
 pub type CliListForwardedPaymentsResponse = CliPaginatedResponse<ForwardedPayment>;
 
-fn format_page_token(token: PageToken) -> String {
-	format!("{}:{}", token.token, token.index)
-}
-
 /// A denomination-aware amount that stores its value internally in millisatoshis.
 ///
 /// Accepts the following formats when parsed from a string:

ldk-server-grpc/src/api.rs

@@ -893,14 +893,14 @@ pub struct GetPaymentDetailsResponse {
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ListPaymentsRequest {
-	/// `page_token` is a pagination token.
+	/// `page_token` is an opaque pagination token string.
 	///
 	/// To query for the first page, `page_token` must not be specified.
 	///
 	/// For subsequent pages, use the value that was returned as `next_page_token` in the previous
 	/// page's response.
-	#[prost(message, optional, tag = "1")]
-	pub page_token: ::core::option::Option<super::types::PageToken>,
+	#[prost(string, optional, tag = "1")]
+	pub page_token: ::core::option::Option<::prost::alloc::string::String>,
 }
 /// The response for the `ListPayments` RPC. On failure, a gRPC error status is returned.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
@@ -912,7 +912,8 @@ pub struct ListPaymentsResponse {
 	/// List of payments.
 	#[prost(message, repeated, tag = "1")]
 	pub payments: ::prost::alloc::vec::Vec<super::types::Payment>,
-	/// `next_page_token` is a pagination token, used to retrieve the next page of results.
+	/// `next_page_token` is an opaque pagination token string used to retrieve the next page of
+	/// results.
 	/// Use this value to query for next-page of paginated operation, by specifying
 	/// this value as the `page_token` in the next request.
 	///
@@ -925,8 +926,8 @@ pub struct ListPaymentsResponse {
 	///
 	/// **Caution**: Clients must not assume a specific number of records to be present in a page for
 	/// paginated response.
-	#[prost(message, optional, tag = "2")]
-	pub next_page_token: ::core::option::Option<super::types::PageToken>,
+	#[prost(string, optional, tag = "2")]
+	pub next_page_token: ::core::option::Option<::prost::alloc::string::String>,
 }
 /// Retrieves list of all forwarded payments.
 /// See more: <https://docs.rs/ldk-node/latest/ldk_node/enum.Event.html#variant.PaymentForwarded>
@@ -936,14 +937,14 @@ pub struct ListPaymentsResponse {
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ListForwardedPaymentsRequest {
-	/// `page_token` is a pagination token.
+	/// `page_token` is an opaque pagination token string.
 	///
 	/// To query for the first page, `page_token` must not be specified.
 	///
 	/// For subsequent pages, use the value that was returned as `next_page_token` in the previous
 	/// page's response.
-	#[prost(message, optional, tag = "1")]
-	pub page_token: ::core::option::Option<super::types::PageToken>,
+	#[prost(string, optional, tag = "1")]
+	pub page_token: ::core::option::Option<::prost::alloc::string::String>,
 }
 /// The response for the `ListForwardedPayments` RPC. On failure, a gRPC error status is returned.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
@@ -955,7 +956,8 @@ pub struct ListForwardedPaymentsResponse {
 	/// List of forwarded payments.
 	#[prost(message, repeated, tag = "1")]
 	pub forwarded_payments: ::prost::alloc::vec::Vec<super::types::ForwardedPayment>,
-	/// `next_page_token` is a pagination token, used to retrieve the next page of results.
+	/// `next_page_token` is an opaque pagination token string used to retrieve the next page of
+	/// results.
 	/// Use this value to query for next-page of paginated operation, by specifying
 	/// this value as the `page_token` in the next request.
 	///
@@ -968,8 +970,8 @@ pub struct ListForwardedPaymentsResponse {
 	///
 	/// **Caution**: Clients must not assume a specific number of records to be present in a page for
 	/// paginated response.
-	#[prost(message, optional, tag = "2")]
-	pub next_page_token: ::core::option::Option<super::types::PageToken>,
+	#[prost(string, optional, tag = "2")]
+	pub next_page_token: ::core::option::Option<::prost::alloc::string::String>,
 }
 /// Sign a message with the node's secret key.
 /// See more: <https://docs.rs/ldk-node/latest/ldk_node/struct.Node.html#method.sign_message>

ldk-server-grpc/src/proto/api.proto

@@ -647,21 +647,22 @@ message GetPaymentDetailsResponse {
 // Retrieves list of all payments.
 // See more: https://docs.rs/ldk-node/latest/ldk_node/struct.Node.html#method.list_payments
 message ListPaymentsRequest {
-  // `page_token` is a pagination token.
+  // `page_token` is an opaque pagination token string.
   //
   // To query for the first page, `page_token` must not be specified.
   //
   // For subsequent pages, use the value that was returned as `next_page_token` in the previous
   // page's response.
-  optional types.PageToken page_token = 1;
+  optional string page_token = 1;
 }
 
 // The response for the `ListPayments` RPC. On failure, a gRPC error status is returned.
 message ListPaymentsResponse {
   // List of payments.
   repeated types.Payment payments = 1;
 
-  // `next_page_token` is a pagination token, used to retrieve the next page of results.
+  // `next_page_token` is an opaque pagination token string used to retrieve the next page of
+  // results.
   // Use this value to query for next-page of paginated operation, by specifying
   // this value as the `page_token` in the next request.
   //
@@ -674,27 +675,28 @@ message ListPaymentsResponse {
   //
   // **Caution**: Clients must not assume a specific number of records to be present in a page for
   // paginated response.
-  optional types.PageToken next_page_token = 2;
+  optional string next_page_token = 2;
 }
 
 // Retrieves list of all forwarded payments.
 // See more: https://docs.rs/ldk-node/latest/ldk_node/enum.Event.html#variant.PaymentForwarded
 message ListForwardedPaymentsRequest {
-  // `page_token` is a pagination token.
+  // `page_token` is an opaque pagination token string.
   //
   // To query for the first page, `page_token` must not be specified.
   //
   // For subsequent pages, use the value that was returned as `next_page_token` in the previous
   // page's response.
-  optional types.PageToken page_token = 1;
+  optional string page_token = 1;
 }
 
 // The response for the `ListForwardedPayments` RPC. On failure, a gRPC error status is returned.
 message ListForwardedPaymentsResponse {
   // List of forwarded payments.
   repeated types.ForwardedPayment forwarded_payments = 1;
 
-  // `next_page_token` is a pagination token, used to retrieve the next page of results.
+  // `next_page_token` is an opaque pagination token string used to retrieve the next page of
+  // results.
   // Use this value to query for next-page of paginated operation, by specifying
   // this value as the `page_token` in the next request.
   //
@@ -707,7 +709,7 @@ message ListForwardedPaymentsResponse {
   //
   // **Caution**: Clients must not assume a specific number of records to be present in a page for
   // paginated response.
-  optional types.PageToken next_page_token = 2;
+  optional string next_page_token = 2;
 }
 
 // Sign a message with the node's secret key.

ldk-server-grpc/src/proto/types.proto

@@ -791,12 +791,6 @@ message AwaitingThresholdConfirmations {
   uint64 amount_satoshis = 5;
 }
 
-// Token used to determine start of next page in paginated APIs.
-message PageToken {
-  string token = 1;
-  int64 index = 2;
-}
-
 message Bolt11InvoiceDescription {
   oneof kind {
     string direct = 1;

ldk-server-grpc/src/types.rs

@@ -938,18 +938,6 @@ pub struct AwaitingThresholdConfirmations {
 	#[prost(uint64, tag = "5")]
 	pub amount_satoshis: u64,
 }
-/// Token used to determine start of next page in paginated APIs.
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
-#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
-#[cfg_attr(feature = "serde", serde(default))]
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct PageToken {
-	#[prost(string, tag = "1")]
-	pub token: ::prost::alloc::string::String,
-	#[prost(int64, tag = "2")]
-	pub index: i64,
-}
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 #[cfg_attr(feature = "serde", serde(default))]

ldk-server-mcp/src/tools/schema.rs

@@ -132,13 +132,8 @@ fn channel_config_schema() -> Value {
 
 fn page_token_schema() -> Value {
 	json!({
-		"type": "object",
-		"description": "Pagination token from a previous response",
-		"properties": {
-			"token": { "type": "string" },
-			"index": { "type": "integer" }
-		},
-		"required": ["token", "index"]
+		"type": "string",
+		"description": "Opaque pagination token from a previous response"
 	})
 }