Merge branch 'main' into pre-release

snippets/csharp/GettingStarted.cs

@@ -76,4 +76,27 @@ public void FetchNodeInfo(BlockingBreezServices sdk)
         }
         // ANCHOR_END: fetch-balance
     }
+
+    // ANCHOR: logging
+    public void GettingStartedLogging()
+    {
+        try
+        {
+            BreezSdkMethods.SetLogStream(new SdkLogStream());
+        }
+        catch (Exception)
+        {
+            // Handle error
+        }
+    }
+
+    class SdkLogStream : LogStream
+    {
+        public void Log(LogEntry l)
+        {
+            Console.WriteLine($"Received Log [{l.level}]: {l.line}");
+        }
+    }
+    // ANCHOR_END: logging
+
 }

snippets/csharp/Production.cs

@@ -4,7 +4,8 @@ public class ProductionSnippets
 {
     public NodeConfig ProductionNodeConfig() {
         // ANCHOR: moving-to-production
-        // Read your Greenlight credentials from secure storage
+        // Read in your Greenlight credentials from the file 
+        // system, environment variable or build config
         var deviceKey = new List<byte>();
         var deviceCert = new List<byte>();
         var greenlightCredentials = new GreenlightCredentials(deviceKey, deviceCert);

snippets/dart_snippets/lib/getting_started.dart

@@ -63,3 +63,13 @@ Future<void> fetchBalance(String lspId) async {
   }
   // ANCHOR_END: fetch-balance
 }
+
+// ANCHOR: logging
+void onLogEntry(log) {
+  print("Received log ${log.level}]: ${log.line}");
+}
+
+void logging(BreezSDK breezSDK) {
+  breezSDK.logStream.listen(onLogEntry);
+}
+// ANCHOR_END: logging

snippets/dart_snippets/lib/production.dart

@@ -4,7 +4,8 @@ import 'package:breez_sdk/bridge_generated.dart';
 
 NodeConfig productionNodeConfig() {
   // ANCHOR: moving-to-production
-  // Read your Greenlight credentials from secure storage
+  // Read in your Greenlight credentials from the file 
+  // system, environment variable or build config
   Uint8List deviceKey = Uint8List(0);
   Uint8List deviceCert = Uint8List(0);
   GreenlightCredentials greenlightCredentials = GreenlightCredentials(

snippets/go/getting_started.go

@@ -71,3 +71,19 @@ func FetchBalance() {
 	}
 	// ANCHOR_END: fetch-balance
 }
+
+// ANCHOR: logging
+type SdkLogStream struct{}
+
+func (SdkLogStream) Log(l breez_sdk.LogEntry) {
+	log.Printf("Received log [%v]: %v", l.Level, l.Line)
+}
+
+func GettingStartedLogging() {
+	err := breez_sdk.SetLogStream(SdkLogStream{})
+	if err != nil {
+		log.Fatalf("SetLogStream failed: %#v", err)
+	}
+}
+
+// ANCHOR_END: logging

snippets/go/production.go

@@ -6,7 +6,8 @@ import (
 
 func ProductionNodeConfig() breez_sdk.NodeConfig {
 	// ANCHOR: moving-to-production
-	// Read your Greenlight credentials from secure storage
+	// Read in your Greenlight credentials from the file
+	// system, environment variable or build config
 	deviceKey := []uint8{}
 	deviceCert := []uint8{}
 	greenlightCredentials := breez_sdk.GreenlightCredentials{

snippets/kotlin_mpp_lib/shared/src/commonMain/kotlin/com/example/kotlinmpplib/GettingStarted.kt

@@ -60,4 +60,20 @@ class GettingStarted {
         }
         // ANCHOR_END: fetch-balance
     }
+
+    fun logging() {
+        // ANCHOR: logging
+        class SDKLogStream : LogStream {
+            override fun log(l: LogEntry) {
+                // Log.v("SDKListener", "Received log [${l.level}]: ${l.line}")
+            }
+        }
+
+        try {
+            setLogStream(SDKLogStream())
+        } catch (e: Exception) {
+            // handle error
+        }
+        // ANCHOR_END: logging
+    }
 }

snippets/kotlin_mpp_lib/shared/src/commonMain/kotlin/com/example/kotlinmpplib/Production.kt

@@ -4,7 +4,8 @@ import breez_sdk.*
 class Production {
     fun productionNodeConfig(): NodeConfig {
         // ANCHOR: moving-to-production
-        // Read your Greenlight credentials from secure storage
+        // Read in your Greenlight credentials from the file 
+        // system, environment variable or build config
         val deviceKey = emptyList<UByte>()
         val deviceCert = emptyList<UByte>()
         val greenlightCredentials = GreenlightCredentials(deviceKey, deviceCert)

snippets/python/src/getting_started.py

@@ -56,4 +56,15 @@ def getting_started_node_info(sdk_services):
         logging.error(error)
         raise
 
+# ANCHOR: logging
+class SDKLogStream(breez_sdk.LogStream):
+    def log(self, l):
+        print("Received log [", l.level, "]: ", l.line)
 
+def logging():
+    try:
+        breez_sdk.set_log_stream(SDKLogStream())
+    except Exception as error:
+        print(error)
+        raise
+# ANCHOR_END: logging

snippets/python/src/production.py

@@ -2,7 +2,8 @@
 
 def production_node_config():
     # ANCHOR: moving-to-production
-    # Read your Greenlight credentials from secure storage
+    # Read in your Greenlight credentials from the file 
+    # system, environment variable or build config
     deviceKey = []
     deviceCert = []
     greenlightCredentials = breez_sdk.GreenlightCredentials(deviceKey, deviceCert)

snippets/react-native/getting_started.ts

@@ -8,7 +8,9 @@ import {
   mnemonicToSeed,
   type NodeConfig,
   NodeConfigVariant,
-  nodeInfo
+  nodeInfo,
+  type LogEntry,
+  setLogStream
 } from '@breeztech/react-native-breez-sdk'
 
 const exampleGettingStarted = async () => {
@@ -36,6 +38,13 @@ const exampleGettingStarted = async () => {
       nodeConfig
     )
 
+    // By default in React Native the workingDir is set to:
+    // `/<APPLICATION_SANDBOX_DIRECTORY>/breezSdk`
+    // You can change this to another writable directory or a
+    // subdirectory of the workingDir if managing multiple nodes.
+    console.log(`Working directory: ${config.workingDir}`)
+    // config.workingDir = "path to writable directory"
+
     // Connect to the Breez SDK make it ready for use
     const connectRequest: ConnectRequest = { config, seed }
     await connect(connectRequest, onBreezEvent)
@@ -71,3 +80,13 @@ const exampleFetchNodeInfo = async () => {
   }
   // ANCHOR_END: fetch-balance
 }
+
+const exampleLogging = async () => {
+  // ANCHOR: logging
+  const onLogEntry = (l: LogEntry) => {
+    console.log(`Received log [${l.level}]: ${l.line}`)
+  }
+
+  const subscription = await setLogStream(onLogEntry)
+  // ANCHOR_END: logging
+}

snippets/react-native/production.ts

@@ -6,7 +6,8 @@ import {
 
 const productionNodeConfig = (): NodeConfig => {
   // ANCHOR: moving-to-production
-  // Read your Greenlight credentials from secure storage
+  // Read in your Greenlight credentials from the file
+  // system, environment variable or build config
   const deviceKey: number[] = []
   const deviceCert: number[] = []
   const greenlightCredentials: GreenlightCredentials = {

snippets/rust/src/getting_started.rs

@@ -1,7 +1,9 @@
+use std::{fs, path::PathBuf};
+use std::sync::Arc;
+
 use anyhow::Result;
 use bip39::{Language, Mnemonic};
 use breez_sdk_core::*;
-use std::sync::Arc;
 
 use crate::AppEventListener;
 
@@ -60,3 +62,14 @@ async fn getting_started_node_info(sdk: Arc<BreezServices>) -> Result<()> {
 
     Ok(())
 }
+
+async fn getting_started_logging(data_dir: String) -> Result<()> {
+    // ANCHOR: logging
+    let data_dir_path = PathBuf::from(&data_dir);
+    fs::create_dir_all(data_dir_path)?;
+
+    BreezServices::init_logging(&data_dir, None)?;
+    // ANCHOR_END: logging
+
+    Ok(())
+}

snippets/rust/src/production.rs

@@ -3,7 +3,8 @@ use breez_sdk_core::*;
 
 fn production_node_config() -> Result<NodeConfig> {
     // ANCHOR: moving-to-production
-    // Read your Greenlight credentials from secure storage
+    // Read in your Greenlight credentials from the file 
+    // system, environment variable or build config
     let device_key: Vec<u8> = vec![];
     let device_cert: Vec<u8> = vec![];
     let greenlight_credentials = GreenlightCredentials {

snippets/swift/BreezSDKExamples/Sources/GettingStarted.swift

@@ -57,3 +57,15 @@ func gettingStartedNodeInfo(sdk: BlockingBreezServices) {
     }
     // ANCHOR_END: fetch-balance
 }
+
+// ANCHOR: logging
+class SDKLogStream: LogStream {
+    func log(l: LogEntry) {
+        print("Received log [", l.level, "]: ", l.line)
+    }
+}
+
+func logging() throws {
+    try? setLogStream(logStream: SDKLogStream())
+}
+// ANCHOR_END: logging

snippets/swift/BreezSDKExamples/Sources/Production.swift

@@ -9,7 +9,8 @@ import BreezSDK
 
 func productionNodeConfig() -> NodeConfig {
     // ANCHOR: moving-to-production
-    // Read your Greenlight credentials from secure storage
+    // Read in your Greenlight credentials from the file 
+    // system, environment variable or build config
     let deviceKey = [UInt8]()
     let deviceCert = [UInt8]()
     let greenlightCredentials = GreenlightCredentials(deviceKey: deviceKey, deviceCert: deviceCert)

src/SUMMARY.md

@@ -3,7 +3,11 @@
 # API Overview
 
 - [Getting Started](guide/getting_started.md)
-- [Installing](guide/install.md)
+  - [Installing the Breez SDK](guide/install.md)
+    - [Troubleshooting Android](guide/android_troubleshooting.md)
+  - [Connecting to a node](guide/connecting.md)
+  - [Getting the node state](guide/node_state.md)
+  - [Adding logging](guide/logging.md)
 - [Paying in Lightning](guide/payments.md)
   - [Receiving payments](guide/receive_payment.md)
   - [Sending payments](guide/send_payment.md)
@@ -49,6 +53,7 @@
 - [Adding logging](notifications/logging.md)
 - [Configuring the plugin](notifications/service_configuration.md)
 - [Changing default strings](notifications/changing_strings.md)
+- [Customising push messages](notifications/custom_messages.md)
 - [Handling custom notifications](notifications/custom_notifications.md)
 
 <!-- Hidden Links -->

src/guide/android_troubleshooting.md

@@ -0,0 +1,78 @@
+# Troubleshooting Android
+
+After installing Breez SDK into your application you might come across issues compiling on Android platforms because Breez SDK's Notification Plugin: 
+- uses `kotlinx-serialization` dependency,
+- and it relies on JNA library.
+
+If you do, there are several steps you can take to compile and build properly, even if your application is not using the Notification Plugin feature.
+
+## kotlinx-serialization
+
+Starting with this 1.8.20 release, the Kotlin K2 compiler has a preview version of the serialization plugin. It's recommended for users to upgrade their Kotlin version to at least 1.8.20 or [set up the serialization plugin](https://github.com/Kotlin/kotlinx.serialization?tab=readme-ov-file#setup) on their projects explicitly with older versions.
+
+## JNA library
+
+JNA relies on specific class and method names to load native libraries and access native code. If these names are obfuscated or removed, it can cause runtime errors and failures in native library loading. 
+
+The JNA library code obfuscation issue may not be apparent until your application is compiled on `release` mode with maximum optimization and minimal footprint size, that will be used when deploying and publishing an application.
+
+To ensure proper functionality, a Proguard rules needs to be added to explicitly tell R8 compiler to keep certain parts of the JNA library. Here is an example of Proguard rules:
+```pro
+-dontwarn dalvik.system.VMStack
+-dontwarn java.lang.**
+-dontwarn javax.naming.**
+-dontwarn sun.reflect.Reflection
+
+# JNA
+-keep class com.sun.jna.** { *; }
+-keep class * implements com.sun.jna.** { *; }
+
+# Other
+-dontoptimize
+```
+
+These rules ensure that the JNA library's core components are not obfuscated, allowing the library to function correctly. See [Shrink, obfuscate, and optimize your app](https://developer.android.com/build/shrink-code) for more information on how and where to add Proguard rules on your app.
+
+## Inconsistent JVM-target compatibility
+
+It could be that compilation tasks for Java and Kotlin are using different JVM targets, in which case you need to set the [JVM toolchain](https://kotl.in/gradle/jvm/toolchain). In your application's `build.gradle` file in the `app` directory set the Java and Kotlin JVM targets consistently. 
+```
+kotlin {
+    jvmToolchain(17)
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(17))
+    }
+}
+
+android {
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+```
+
+## Java heap space
+
+```
+> Could not resolve all files for configuration
+    > Failed to transform react-android-0.72.10-debug.aar (com.facebook.react:react-android:0.72.10) 
+    to match attributes {artifactType=android-symbol-with-package-name, 
+    com.android.build.api.attributes.BuildTypeAttr=debug, org.gradle.category=library, 
+    org.gradle.dependency.bundling=external, or g.gradle.libraryelements=aar, org.gradle.status=release, 
+    org.gradle.usage=java-api}. 
+        > Java heap error
+```
+
+If you get a `Java heap space` error, try to increase the maximum memory allocation pool for the JVM in `gradle.properties`.
+
+```
+org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=512m
+```