feat(gl-sdk): add list_invoices, list_pays, and unified list_payments API

Three new Node methods for querying payment history:

- list_invoices(): wraps CLN ListInvoices with full native filtering
  (label, invstring, payment_hash, offer_id) and pagination (index,
  start, limit)
- list_pays(): wraps CLN ListPays with native filtering (bolt11,
  payment_hash, status) and pagination
- list_payments(): merges both into a unified Payment timeline sorted
  newest-first, defaults to COMPLETE status filter

New types: Invoice, InvoiceStatus, Pay, ListInvoicesResponse,
ListPaysResponse, Payment, PaymentDirection, PaymentStatus,
ListPaymentsResponse, ListIndex. Payment includes optional invoice/pay
fields for drill-down access to full CLN-specific details.

Kotlin extensions provide default null parameters for idiomatic API.
Includes Python integration tests and Android instrumented tests.

Author: angelix

Cargo.lock

@@ -0,0 +1,119 @@
+// Instrumented tests for list_invoices, list_pays, and list_payments.
+// Tests type construction, empty lists on fresh nodes, invoice creation
+// visibility, and status filtering.
+
+package com.blockstream.glsdk
+
+import android.system.Os
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import kotlin.uuid.ExperimentalUuidApi
+import kotlin.uuid.Uuid
+
+@RunWith(AndroidJUnit4::class)
+class ListPaymentTest {
+
+    @Before
+    fun setup() {
+        Os.setenv("RUST_LOG", "trace", true)
+    }
+
+    // BIP39 test vector — not a real wallet
+    private val testMnemonic =
+        "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong"
+
+    // ============================================================
+    // Type construction
+    // ============================================================
+
+    @Test
+    fun invoice_status_enum_values() {
+        assertNotNull(InvoiceStatus.UNPAID)
+        assertNotNull(InvoiceStatus.PAID)
+        assertNotNull(InvoiceStatus.EXPIRED)
+    }
+
+    @Test
+    fun payment_direction_enum_values() {
+        assertNotNull(PaymentDirection.SENT)
+        assertNotNull(PaymentDirection.RECEIVED)
+    }
+
+    @Test
+    fun payment_status_enum_values() {
+        assertNotNull(PaymentStatus.PENDING)
+        assertNotNull(PaymentStatus.COMPLETE)
+        assertNotNull(PaymentStatus.FAILED)
+        assertNotNull(PaymentStatus.EXPIRED)
+    }
+
+    // ============================================================
+    // Invoice appears in list_invoices and list_payments
+    // ============================================================
+
+    @OptIn(ExperimentalUuidApi::class)
+    @Test
+    fun created_invoice_appears_in_list_invoices() {
+        val config = Config()
+        registerOrRecover(testMnemonic, null, config).use { node ->
+            val label = Uuid.random().toString()
+            node.receive(label = label, description = "Coffee", amountMsat = 10_000_000uL)
+
+            val result = node.listInvoices()
+            val matching = result.invoices.filter { it.label == label }
+            assertEquals("Should find exactly one invoice", 1, matching.size)
+            assertEquals(InvoiceStatus.UNPAID, matching[0].status)
+            assertEquals("Coffee", matching[0].description)
+            assertNotNull(matching[0].bolt11)
+            // Unpaid invoices have no preimage yet
+            assertNull(matching[0].paymentPreimage)
+            // Destination pubkey is parsed from the bolt11 invoice
+            assertNotNull(matching[0].destinationPubkey)
+        }
+    }
+
+    @OptIn(ExperimentalUuidApi::class)
+    @Test
+    fun default_filter_excludes_unpaid() {
+        val config = Config()
+        registerOrRecover(testMnemonic, null, config).use { node ->
+            val label = Uuid.random().toString()
+            node.receive(label = label, description = "Tea", amountMsat = 5_000_000uL)
+
+            // Default (null) filters to COMPLETE, so unpaid invoice should not appear
+            val result = node.listPayments()
+            val matching = result.payments.filter { it.label == label }
+            assertTrue("Default filter should exclude UNPAID invoice", matching.isEmpty())
+        }
+    }
+
+    @OptIn(ExperimentalUuidApi::class)
+    @Test
+    fun pending_filter_includes_unpaid_invoice() {
+        val config = Config()
+        registerOrRecover(testMnemonic, null, config).use { node ->
+            val label = Uuid.random().toString()
+            node.receive(label = label, description = "Tea", amountMsat = 5_000_000uL)
+
+            val result = node.listPayments(PaymentStatus.PENDING)
+            val matching = result.payments.filter { it.label == label }
+            assertEquals("PENDING filter should include UNPAID invoice", 1, matching.size)
+            assertEquals(PaymentDirection.RECEIVED, matching[0].direction)
+            assertEquals(PaymentStatus.PENDING, matching[0].status)
+            assertEquals(InvoiceStatus.UNPAID, matching[0].invoiceStatus)
+            assertNull(matching[0].payStatus)
+            // Received payments have no fee
+            assertNull(matching[0].feeMsat)
+            // For received, amount_total_msat equals amount_msat
+            assertEquals(matching[0].amountMsat, matching[0].amountTotalMsat)
+            // Destination pubkey is available on the unified Payment
+            assertNotNull(matching[0].destinationPubkey)
+            assertNotNull(matching[0].invoice)
+            assertEquals(label, matching[0].invoice?.label)
+            assertNull(matching[0].pay)
+        }
+    }
+}

docs/superpowers/plans/2026-04-01-list-payments-api.md

@@ -0,0 +1,31 @@
+// Kotlin extension functions for Node that provide default parameter values.
+// The UniFFI-generated bindings require all parameters explicitly;
+// these extensions give Kotlin consumers idiomatic optional-parameter APIs.
+
+package com.blockstream.glsdk
+
+@Throws(Exception::class)
+public fun Node.listInvoices(
+    label: String? = null,
+    invstring: String? = null,
+    paymentHash: ByteArray? = null,
+    offerId: String? = null,
+    index: ListIndex? = null,
+    start: ULong? = null,
+    limit: UInt? = null,
+): ListInvoicesResponse = listInvoices(label, invstring, paymentHash, offerId, index, start, limit)
+
+@Throws(Exception::class)
+public fun Node.listPays(
+    bolt11: String? = null,
+    paymentHash: ByteArray? = null,
+    status: PayStatus? = null,
+    index: ListIndex? = null,
+    start: ULong? = null,
+    limit: UInt? = null,
+): ListPaysResponse = listPays(bolt11, paymentHash, status, index, start, limit)
+
+@Throws(Exception::class)
+public fun Node.listPayments(
+    status: PaymentStatus? = null,
+): ListPaymentsResponse = listPayments(status)

docs/superpowers/specs/2026-04-01-list-payments-api-design.md

@@ -32,6 +32,8 @@ pub struct ReceiveResponse {
 pub struct SendResponse {
     pub status: u32,
     pub preimage: Buffer,
+    pub payment_hash: Buffer,
+    pub destination_pubkey: Option<Buffer>,
     /// Amount in millisatoshis (as i64 for JS compatibility)
     pub amount_msat: i64,
     /// Amount sent in millisatoshis (as i64 for JS compatibility)
@@ -512,6 +514,8 @@ impl Node {
         Ok(SendResponse {
             status: response.status as u32,
             preimage: Buffer::from(response.preimage),
+            payment_hash: Buffer::from(response.payment_hash),
+            destination_pubkey: response.destination_pubkey.map(Buffer::from),
             amount_msat: response.amount_msat as i64,
             amount_sent_msat: response.amount_sent_msat as i64,
             parts: response.parts,

libs/gl-sdk-android/lib/src/androidInstrumentedTest/kotlin/com/blockstream/glsdk/ListPaymentTest.kt

@@ -12,6 +12,7 @@ anyhow = "1"
 bip39 = "2.2.0"
 gl-client = { version = "0.3.3", path = "../gl-client" }
 hex = "0.4"
+lightning-invoice = "0.33"
 once_cell = "1.21.3"
 thiserror = "2.0.17"
 tokio = { version = "1", features = ["sync"] }