feat(gl-sdk): builder-style Node creation, signerless by default

NodeBuilder is the sole public entry point for Node construction
across all foreign bindings. The former free functions register /
recover / connect / register_or_recover are demoted to crate-private
helpers (`*_internal`); foreign-binding consumers go through
`NodeBuilder` exclusively.

Two design rules drive the shape:

1. Naked free functions are hard to extend without semver breaks. A
   builder absorbs new modifiers as additional with_* setters —
   additive forever.
2. Signer access ≡ root access on the node (self-certifies runes,
   mints TLS certs). The SDK must support keyless clients that don't
   hold the seed at all (paired devices, browser extensions, hardware
   signers). Signerless connect must be a first-class path, not an
   afterthought.

Resulting surface:

    // Signerless connect — caller has no mnemonic in this process.
    // SDK runs no signer; signing happens at the CLN node, a paired
    // device, or hardware. The keyless-client model.
    let node = NodeBuilder::new(&config).connect(credentials, None)?;

    // Signed connect — caller hands the mnemonic per-call, SDK
    // spawns a signer for the lifetime of the Node.
    let node = NodeBuilder::new(&config).connect(credentials, Some(mnemonic))?;

    // Register / recover / register_or_recover require a mnemonic
    // by definition (the signer must sign the registration /
    // recovery challenge). Mnemonic is positional, not stateful.
    let node = NodeBuilder::new(&config)
        .with_event_listener(listener)
        .register(mnemonic, invite_code)?;

The mnemonic is never stored on the builder. It is a positional
argument on the build call that needs it, so its lifetime is bounded
to that call and there is no half-set state. Modifiers like
with_event_listener live on the builder; secrets do not.

Surface
- NodeBuilder::new(config) — collects config + optional modifiers,
  no I/O.
- with_event_listener(listener) — fluent setter that returns a fresh
  `Arc<NodeBuilder>` carrying the new listener; the original builder
  is unchanged. No interior mutability.
- register(mnemonic, invite_code) — mnemonic required.
- recover(mnemonic) — mnemonic required.
- register_or_recover(mnemonic, invite_code) — mnemonic required.
- connect(credentials, mnemonic: Option<String>) — mnemonic optional;
  None produces a signerless Node.

Builder shape
- Two fields, both immutable after construction: `config:
  Arc<Config>` and `event_listener: Option<Arc<dyn NodeEventListener>>`.
  No `Mutex`, no `RefCell`, no interior mutability anywhere — the
  builder is a value, not a state machine.
- `with_*` setters take `self: Arc<Self>` and return a new
  `Arc<NodeBuilder>` with the modified field, sharing the rest via
  `Arc::clone`. Single small allocation per setter call; the rest is
  pointer copies.
- The listener is stored as `Arc<dyn NodeEventListener>` so the same
  builder can drive multiple builds — each build clones the Arc and
  hands it to the resulting Node. (UniFFI's callback lowering hands
  us a `Box<dyn Trait>` at the FFI boundary; the setter re-wraps it
  via `Arc::from(box)` once.)

Implementation notes
- Node::signerless(credentials) is a new pub (non-UniFFI-export)
  Rust constructor. Used by the builder for the None-mnemonic path
  and by gl-sdk-napi to back its `new Node(credentials)` constructor
  with the same signerless semantics.
- crate::connect_signerless_internal wires Node::signerless into
  the lib.rs internals; crate::connect_internal continues to drive
  the signed connect via the SDK signer spawn.
- Node::set_event_listener (pub(crate)) takes
  `Arc<dyn NodeEventListener>`; spawns a background tokio task that
  tails the gRPC event stream and dispatches to listener.on_event.
  The task is aborted on Drop and replaced if a new listener is set.
- The polling-style Node::stream_node_events() API stays for callers
  who prefer to drive events themselves; the builder route is just a
  callback-style alternative that can't miss early events.

Tests migrated
- Python: test_auth_api.py (24 callsites), test_list_payments.py
  (6), test_node_methods.py (2).
- Kotlin: AuthApiTest.kt (8), NodeOperationsTest.kt (2),
  ListPaymentTest.kt (3), LoggingTest.kt (1). All converted to the
  positional-mnemonic-on-build-call shape.

Verified: `cargo build -p gl-sdk -p gl-sdk-node` clean; Python
bindings expose `NodeBuilder` (with the new method signatures) and
`NodeEventListener` and no longer expose the demoted free
functions.

Author: angelix

gitlab/deploy-maven.yml

@@ -50,7 +50,11 @@ publish_snapshot_to_maven:
     - job: build_kotlin
       artifacts: true
   rules:
-    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: never
+    - if: '$CI_COMMIT_BRANCH == "master"'
+      when: on_success
+    - if: '$CI_COMMIT_BRANCH'
       when: manual
   script:
     - cd libs/gl-sdk-android
@@ -64,6 +68,12 @@ publish_snapshot_to_maven:
     - NEXT_PATCH=$((PATCH + 1))
     - NEXT_VERSION="${MAJOR}.${MINOR}.${NEXT_PATCH}"
     - SNAPSHOT_VERSION="${NEXT_VERSION}-SNAPSHOT"
-    - echo "Publishing snapshot version ${SNAPSHOT_VERSION} (base=${BASE_VERSION})"
-    - ./gradlew -PlibraryVersion=${SNAPSHOT_VERSION} publish --no-daemon
+    - SNAPSHOT_VERSION_COMMIT="${NEXT_VERSION}-${GIT_COMMIT}-SNAPSHOT"
+    - |
+      if [ "$CI_COMMIT_BRANCH" = "master" ]; then
+        echo "Publishing snapshot versions ${SNAPSHOT_VERSION}"
+        ./gradlew -PlibraryVersion=${SNAPSHOT_VERSION} publish --no-daemon
+      fi
+      echo "Publishing snapshot version ${SNAPSHOT_VERSION_COMMIT}"
+      ./gradlew -PlibraryVersion=${SNAPSHOT_VERSION_COMMIT} publish --no-daemon
   allow_failure: true

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

@@ -65,19 +65,19 @@ class AuthApiTest {
     @Test(expected = Exception.PhraseCorrupted::class)
     fun register_bad_mnemonic() {
         val config = Config()
-        register("not a valid mnemonic", null, config)
+        NodeBuilder(config).register("not a valid mnemonic", null)
     }
 
     @Test(expected = Exception.PhraseCorrupted::class)
     fun recover_bad_mnemonic() {
         val config = Config()
-        recover("not a valid mnemonic", config)
+        NodeBuilder(config).recover("not a valid mnemonic")
     }
 
     @Test(expected = Exception.PhraseCorrupted::class)
     fun connect_bad_mnemonic() {
         val config = Config()
-        connect("not a valid mnemonic", "fake-creds".toByteArray(), config)
+        NodeBuilder(config).connect("fake-creds".toByteArray(), "not a valid mnemonic")
     }
 
     // ============================================================
@@ -88,7 +88,7 @@ class AuthApiTest {
     @Test
     fun register_or_recover_returns_node() {
         val config = Config()
-        val node = registerOrRecover(testMnemonic, null, config)
+        val node = NodeBuilder(config).registerOrRecover(testMnemonic, null)
         assertNotNull(node)
         node.use { n ->
             val creds = n.credentials()
@@ -104,12 +104,12 @@ class AuthApiTest {
 
         // Register or recover to get credentials
         val savedCreds: ByteArray
-        registerOrRecover(testMnemonic, null, config).use { node ->
+        NodeBuilder(config).registerOrRecover(testMnemonic, null).use { node ->
             savedCreds = node.credentials()
         }
 
         // Connect with the saved credentials
-        connect(testMnemonic, savedCreds, config).use { node ->
+        NodeBuilder(config).connect(savedCreds, testMnemonic).use { node ->
             assertNotNull(node)
             val reconnectedCreds = node.credentials()
             assertTrue("Reconnected credentials should not be empty", reconnectedCreds.isNotEmpty())
@@ -124,7 +124,7 @@ class AuthApiTest {
     fun disconnect_is_idempotent() {
         val config = Config()
 
-        val node = registerOrRecover(testMnemonic, null, config)
+        val node = NodeBuilder(config).registerOrRecover(testMnemonic, null)
         // First disconnect
         node.disconnect()
         // Second disconnect should not throw
@@ -139,7 +139,7 @@ class AuthApiTest {
     @Test
     fun register_or_recover_and_create_invoice() {
         val config = Config()
-        registerOrRecover(testMnemonic, null, config).use { node ->
+        NodeBuilder(config).registerOrRecover(testMnemonic, null).use { node ->
             val addrResponse = node.onchainReceive()
             assertNotNull(addrResponse)
             println("Deposit funds to: $addrResponse")

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

@@ -63,7 +63,7 @@ class ListPaymentTest {
     @Test
     fun created_invoice_appears_in_list_invoices() {
         val config = Config()
-        registerOrRecover(testMnemonic, null, config).use { node ->
+        NodeBuilder(config).registerOrRecover(testMnemonic, null).use { node ->
             val label = Uuid.random().toString()
             node.receive(label = label, description = "Coffee", amountMsat = 10_000_000uL)
 
@@ -84,7 +84,7 @@ class ListPaymentTest {
     @Test
     fun unpaid_invoices_excluded() {
         val config = Config()
-        registerOrRecover(testMnemonic, null, config).use { node ->
+        NodeBuilder(config).registerOrRecover(testMnemonic, null).use { node ->
             val label = Uuid.random().toString()
             node.receive(label = label, description = "Tea", amountMsat = 5_000_000uL)
 
@@ -107,7 +107,7 @@ class ListPaymentTest {
     @Test
     fun type_filter_received_only() {
         val config = Config()
-        registerOrRecover(testMnemonic, null, config).use { node ->
+        NodeBuilder(config).registerOrRecover(testMnemonic, null).use { node ->
             val label = Uuid.random().toString()
             node.receive(label = label, description = "Tea", amountMsat = 5_000_000uL)
 

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

@@ -53,7 +53,7 @@ class LoggingTest {
         val config = Config()
         val mnemonic = "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong"
         try {
-            registerOrRecover(mnemonic, null, config)
+            NodeBuilder(config).registerOrRecover(mnemonic, null)
         } catch (_: Exception) {
             // May fail on network / credentials — we only care that logs flowed.
         }

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

@@ -27,7 +27,7 @@ class NodeOperationsTest {
     fun test_onchain_receive_and_invoice() {
         val config = Config()
 
-        val node = registerOrRecover(mnemonic = testMnemonic, inviteCode = null, config = config)
+        val node = NodeBuilder(config).registerOrRecover(testMnemonic, null)
 
         node.use { n ->
             // Get an on-chain address to fund the node
@@ -47,7 +47,7 @@ class NodeOperationsTest {
     @Test
     fun test_node_state_returns_valid_snapshot() {
         val config = Config()
-        val node = registerOrRecover(mnemonic = testMnemonic, inviteCode = null, config = config)
+        val node = NodeBuilder(config).registerOrRecover(testMnemonic, null)
         node.use { n ->
             val state = n.nodeState()
             assertTrue(state.id.isNotEmpty())

libs/gl-sdk-cli/src/node.rs

@@ -52,7 +52,9 @@ pub enum Command {
 
 pub fn handle(cmd: Command, data_dir: &DataDir) -> Result<()> {
     let creds = util::read_credentials(data_dir)?;
-    let node = glsdk::Node::new(&creds).map_err(|e| Error::Other(e.to_string()))?;
+    // CLI wraps an externally-running signer (the gl-client signer
+    // launched out-of-process); the SDK Node is signerless.
+    let node = glsdk::Node::signerless(creds).map_err(|e| Error::Other(e.to_string()))?;
 
     match cmd {
         Command::GetInfo => get_info(&node),

libs/gl-sdk-cli/src/output.rs

@@ -323,8 +323,6 @@ pub enum NodeEventOutput {
         label: String,
         amount_msat: u64,
     },
-    #[serde(rename = "unknown")]
-    Unknown,
 }
 
 impl From<glsdk::NodeEvent> for NodeEventOutput {
@@ -337,7 +335,6 @@ impl From<glsdk::NodeEvent> for NodeEventOutput {
                 label: details.label,
                 amount_msat: details.amount_msat,
             },
-            glsdk::NodeEvent::Unknown => NodeEventOutput::Unknown,
         }
     }
 }

libs/gl-sdk-napi/src/lib.rs

@@ -503,15 +503,20 @@ impl NodeEventStream {
 
 #[napi]
 impl Node {
-    /// Create a new node connection
+    /// Create a signerless node from credentials.
+    ///
+    /// No SDK-side signer runs — signing happens elsewhere (paired
+    /// device, hardware signer, the CLN node's local signer). For
+    /// the SDK-as-signer model, use the `register` / `recover` /
+    /// `connect` free functions with a mnemonic.
     ///
     /// # Arguments
     /// * `credentials` - Device credentials
     #[napi(constructor)]
     pub fn new(credentials: &Credentials) -> Result<Self> {
-        // Constructor stays sync — connection is established lazily
+        // Connection is established lazily on first RPC.
         let inner =
-            GlNode::new(&credentials.inner).map_err(|e| Error::from_reason(e.to_string()))?;
+            GlNode::signerless(credentials.inner.clone()).map_err(|e| Error::from_reason(e.to_string()))?;
 
         Ok(Self { inner: std::sync::Arc::new(inner) })
     }
@@ -866,10 +871,6 @@ fn napi_node_event_from_gl(event: GlNodeEvent) -> NodeEvent {
                 amount_msat: details.amount_msat as i64,
             }),
         },
-        GlNodeEvent::Unknown => NodeEvent {
-            event_type: "unknown".to_string(),
-            invoice_paid: None,
-        },
     }
 }