breez/breez-sdk

Breez SDK

Overview

The Breez SDK enables developers to integrate Lightning and bitcoin payments into their apps with a very shallow learning curve. The use cases are endless – from social apps that want to integrate tipping between users to content-creation apps interested in adding bitcoin monetization. Crucially, this SDK is an end-to-end, non-custodial, drop-in solution powered by Greenlight, a built-in LSP, on-chain interoperability, third-party fiat on-ramps, and other services users and operators need. The Breez SDK is free for developers.

The Breez SDK provides the following services:

• Sending payments (via various protocols such as: bolt11, keysend, lnurl-pay, lightning address, etc.)
• Receiving payments (via various protocols such as: bolt11, lnurl-withdraw, etc.)
• Fetching node status (e.g. balance, max allow to pay, max allow to receive, on-chain balance, etc.)
• Connecting to a new or existing node.

Download our one pager here.

To get started with the Breez SDK, follow these examples.

Note: in order to use the Breez SDK you need an API key from Breez, please email us at [email protected] for more information.

Demo

demo.mp4

For a higher resolution video, click here.

Features

Using the SDK

To get started with the Breez SDK, follow these examples.

API

API documentation is here.

Support

Join this telegram group.

Architecture

This diagram is a high-level description of the Breez SDK:

Command line

Breez sdk-cli is a command line client that allows you to test the functionality of the Breez SDK.

Build & Test

The libs folder contains three sub folders and is a structured as a cargo workspace:

• sdk-core: the core SDK rust library.
• sdk-bindings: ffi bindings for Kotlin, Python, Swift, C# and Go.
• sdk-flutter: a flutter plugin (includes ffi bindings for dart).
• sdk-react-native: a react-native plugin.

The tools folder contains a simple command line interface (sdk-cli) to the SDK. See the instructions in each sub project readme on how to build, test and run.

TODOs

• ‘On-the-fly’ channel creation
• Send/receive bolt11
• LNURL-Pay
• LNURL-Withdraw
• Backup/restore using mnemonics
• Send zero-amount invoices
• Fiat currencies
• Send spontaneous payments
• Send to a Lightning address
• Send to BIP 21
• cli inteface
• Swift bindings
• Kotlin bindings
• API key
• Receive via on-chain address
• React Native bindings
• LNURL-Auth
• Send to an on-chain address
• MoonPay fiat on-ramp
• C# bindings
• Python bindings
• Spend all funds
• Webhook for receiving payments
• Offline receive via notifications
• LSPS2 support
• LSPS1 support
• Send/receive bolt12
• Simplifed key management (cloud key backup)
• WebAssembly support
• Improve key share
• Close channels to a predefined address
• Make mempool.space dependency optional
• Receive 0 amount invoice via LSP (unified QR)
• Async payments
• LDK support
• Splicing

breez-sdk's Issues

SDK: Implement LNUrl auth

Missing payment_preimage on sent funds

• Payment Preimage is empty for sent funds.

Faster initialization time for BreezServices

Since we need the BreezServices API to query payments list we need a short initialization time for the API to be accessible.
Right now it is accessible only after scheduling the node.
I think we can return immediately after the BreezServices is created and run the sync in the background.
It will require some sort of notification from the sdk to the user that the wallet sync is completed.

Document public interfaces for `rustdoc`

The rustdocs can be generated with cargo doc --no-deps --open.

This will build the docs locally and open them in a browser.

Payment failures after start

During the last two test charging sessions on Satimoto I've seen a pattern where the first three invoice payments fail due to routing issues. After the those three payment failures the subsequent payments are successful. The failure message is Destination 0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5 is not reachable directly and all routehints were unusable.

2023-04-05

2023-04-05T09:23:23.442Z [DEBUG]  WalletStore: SAT051: State: STARTED
2023-04-05T09:23:23.442Z [DEBUG]  LightningStore: SAT104: walletStated
2023-04-05T09:23:23.449Z [DEBUG]  ChannelStore: SAT064: max receivable 3919916000, single payment 4294967000
2023-04-05T09:23:23.449Z [DEBUG]  ChannelStore: SAT039: Channel Balance: 80084, 33410, 0
2023-04-05T09:23:28.879Z [DEBUG]  LightningStore: SAT0062: synced
2023-04-05T09:23:28.906Z [DEBUG]  LightningStore: SAT0062: newBlock : 784034
...
2023-04-05T09:28:39.288Z [DEBUG]  SessionStore: SAT070 paySessionInvoice: pr=lnbc32228760p1pjz606xpp5vz6wn8cegm8ufyh33kghf6wafstrup29r42hhgtwey3y9uk2dngsdp6xq6rwwf3vvcnsttyvymx2tf5vs6xytfexucnxtfhv4jxydryxvex2d34vscqzpgxqrrsssp5zj7uug23gfpwar54gj4u9qpu9xpuqehvyh8pl2usd0eyxyhj5q9q9qyyssqkka9lzmx2c6877sw0wg7v89cak9vgv5alrsdg4h89mkm9mc5dktkvf6m09cnnnxqa8cj4p4hdjmyu5sjzjlg6m4umqf8wrh5e99rrsqp35alc5 sig=d7gqjrertpscad7iku3hxa43qa8koxdunrng8d8gysys7iqcckrzqqc9qqoikoytawo8bohpxa8i86a1483esrmqmricqx5eq5p85f1c
2023-04-05T09:28:41.129Z [DEBUG]  LightningStore: SAT0062: paymentFailed : {"bolt11":{"routingHints":[],"timestamp":1680686918,"paymentHash":"60b4e99f1946cfc492f18d9174e9dd4c163e05451d557ba16ec92242f2ca6cd1","expiry":3600,"descriptionHash":null,"description":"04791c18-da6e-4d4b-9713-7edb4d32e65d","payeePubkey":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","paymentSecret":[20,189,206,33,81,66,66,238,142,149,68,171,194,128,60,41,131,192,102,236,37,206,31,171,144,107,242,67,18,242,160,10],"amountMsat":3222876,"bolt11":"lnbc32228760p1pjz606xpp5vz6wn8cegm8ufyh33kghf6wafstrup29r42hhgtwey3y9uk2dngsdp6xq6rwwf3vvcnsttyvymx2tf5vs6xytfexucnxtfhv4jxydryxvex2d34vscqzpgxqrrsssp5zj7uug23gfpwar54gj4u9qpu9xpuqehvyh8pl2usd0eyxyhj5q9q9qyyssqkka9lzmx2c6877sw0wg7v89cak9vgv5alrsdg4h89mkm9mc5dktkvf6m09cnnnxqa8cj4p4hdjmyu5sjzjlg6m4umqf8wrh5e99rrsqp35alc5"},"nodeId":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","error":"status: Internal, message: \"error calling RPC: RPC error response: RpcError { code: 210, message: \\\"Destination 0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5 is not reachable directly and all routehints were unusable.\\\", data: None }\", details: [], metadata: MetadataMap { headers: {\"content-type\": \"application/grpc\", \"date\": \"Wed, 05 Apr 2023 09:28:41 GMT\", \"content-length\": \"0\"} }"}
...
2023-04-05T09:29:39.667Z [DEBUG]  SessionStore: SAT070 paySessionInvoice: pr=lnbc64433790p1pjz60urpp5ckllg45xvjn0mt8n5a3pg3deqg525qk7d48ed9a8ah2rcruepheqdp6xq6rwwf3vvcnsttyvymx2tf5vs6xytfexucnxtfhv4jxydryxvex2d34vscqzpgxqrrsssp5qzqp2h4lmmjwrzdl6g47057fvw4wjqre67f75ect9xenjf9l3lxq9qyyssqjkxga0usa8gp34qac6ygpqavfuj78pn7vyzcsdhjngtnlqeaaju8s6ljdh30u95c5qr69c5xs6fe99y7vkyfk0k0gel2e8mxx9ss40qp26rv37 sig=d9xypr854wsmhitoousxq5xzyjkf3pkfjppj3o514ikkhe6t44j9gruqq6bj9ymqcyig44e6664jz41remtikpn3qziqacu1wsb6unqh
2023-04-05T09:29:41.247Z [DEBUG]  LightningStore: SAT0062: paymentFailed : {"bolt11":{"routingHints":[],"timestamp":1680686979,"paymentHash":"c5bff4568664a6fdacf3a7621445b90228aa02de6d4f9697a7edd43c0f990df2","expiry":3600,"descriptionHash":null,"description":"04791c18-da6e-4d4b-9713-7edb4d32e65d","payeePubkey":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","paymentSecret":[0,128,21,94,191,222,228,225,137,191,210,43,231,211,201,99,170,233,0,121,215,147,234,103,11,41,179,57,36,191,143,204],"amountMsat":6443379,"bolt11":"lnbc64433790p1pjz60urpp5ckllg45xvjn0mt8n5a3pg3deqg525qk7d48ed9a8ah2rcruepheqdp6xq6rwwf3vvcnsttyvymx2tf5vs6xytfexucnxtfhv4jxydryxvex2d34vscqzpgxqrrsssp5qzqp2h4lmmjwrzdl6g47057fvw4wjqre67f75ect9xenjf9l3lxq9qyyssqjkxga0usa8gp34qac6ygpqavfuj78pn7vyzcsdhjngtnlqeaaju8s6ljdh30u95c5qr69c5xs6fe99y7vkyfk0k0gel2e8mxx9ss40qp26rv37"},"nodeId":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","error":"status: Internal, message: \"error calling RPC: RPC error response: RpcError { code: 210, message: \\\"Destination 0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5 is not reachable directly and all routehints were unusable.\\\", data: None }\", details: [], metadata: MetadataMap { headers: {\"content-type\": \"application/grpc\", \"date\": \"Wed, 05 Apr 2023 09:29:41 GMT\", \"content-length\": \"0\"} }"}
...
2023-04-05T09:30:28.648Z [DEBUG]  LightningStore: SAT0062: synced
2023-04-05T09:30:28.659Z [DEBUG]  LightningStore: SAT0062: newBlock : 784035
...
2023-04-05T09:30:40.030Z [DEBUG]  SessionStore: SAT070 paySessionInvoice: pr=lnbc32227770p1pjz60alpp5mn6gk5eql5g58xgzztr4pdey82hm2ym225vkv8kpsh0gmp5tsp0qdp6xq6rwwf3vvcnsttyvymx2tf5vs6xytfexucnxtfhv4jxydryxvex2d34vscqzpgxqrrsssp5pazrrlfkrek3xy9ha020rh9xhr9f75rvj548a5x5resh3egnhs8q9qyyssq4uur7fhkhkyzxs5vjks3gcsg9qh7yk6fm553fey0wpvywvcqfqp542fwx43akv552z0klc7uw7nt67pjz6thex0rlap7ve3fvvk2mssqauq4sk sig=d71k8569p9xkhjt5k8g9zeo433g8kihy6edohspwrusor87w5cc6ox7heg1srqd43anbapq19rt6ogcrfa1ijgeontpasjg1x3qkepje
2023-04-05T09:30:41.875Z [DEBUG]  LightningStore: SAT0062: paymentFailed : {"bolt11":{"routingHints":[],"timestamp":1680687039,"paymentHash":"dcf48b5320fd1143990212c750b7243aafb5136a5519661ec185de8d868b805e","expiry":3600,"descriptionHash":null,"description":"04791c18-da6e-4d4b-9713-7edb4d32e65d","payeePubkey":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","paymentSecret":[15,68,49,253,54,30,109,19,16,183,235,212,241,220,166,184,202,159,80,108,149,42,126,208,212,30,97,120,229,19,188,14],"amountMsat":3222777,"bolt11":"lnbc32227770p1pjz60alpp5mn6gk5eql5g58xgzztr4pdey82hm2ym225vkv8kpsh0gmp5tsp0qdp6xq6rwwf3vvcnsttyvymx2tf5vs6xytfexucnxtfhv4jxydryxvex2d34vscqzpgxqrrsssp5pazrrlfkrek3xy9ha020rh9xhr9f75rvj548a5x5resh3egnhs8q9qyyssq4uur7fhkhkyzxs5vjks3gcsg9qh7yk6fm553fey0wpvywvcqfqp542fwx43akv552z0klc7uw7nt67pjz6thex0rlap7ve3fvvk2mssqauq4sk"},"nodeId":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","error":"status: Internal, message: \"error calling RPC: RPC error response: RpcError { code: 210, message: \\\"Destination 0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5 is not reachable directly and all routehints were unusable.\\\", data: None }\", details: [], metadata: MetadataMap { headers: {\"content-type\": \"application/grpc\", \"date\": \"Wed, 05 Apr 2023 09:30:41 GMT\", \"content-length\": \"0\"} }"}
...
2023-04-05T09:31:40.369Z [DEBUG]  SessionStore: SAT070 paySessionInvoice: pr=lnbc32236170p1pjz60lupp530tk3d2jh5tg3k4yuy2jwadhpjhk5jwacahdeldt403s4w9quufqdp6xq6rwwf3vvcnsttyvymx2tf5vs6xytfexucnxtfhv4jxydryxvex2d34vscqzpgxqrrsssp5h2k53kn8cpy7ywp73qhgy64r3ctephjdlmu3r6yae7v27un5r5ts9qyyssq30nqgm6xzden260hmc7x3v3cjcmds268c8auhvt6d5q2mcs58pmpgx454u3zk2jkm6j9suxpy9m7xegfnue927zvk8vxh3ct3f8fjjsq50k6xa sig=rnxzu8pyo8igiwkyjgz3w31aqrxbc947denrc38uabe13bjey3ww1m6h5uw79fy7d47xykj66ffuid46gi4ebd64z37t4o7jaurzmn3x
2023-04-05T09:31:50.818Z [DEBUG]  LightningStore: SAT0062: synced
2023-04-05T09:31:50.822Z [DEBUG]  LightningStore: SAT0062: paymentSucceed : {"details":{"lnurlMetadata":null,"lnurlSuccessAction":null,"keysend":true,"label":"","paymentPreimage":"","destinationPubkey":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","paymentHash":"8bd768b552bd1688daa4e1152775b70caf6a49ddc76edcfdababe30ab8a0e712","lnAddress":null,"bolt11":"","type":"ln"},"amountMsat":3223617,"paymentTime":1680687102,"id":"8bd768b552bd1688daa4e1152775b70caf6a49ddc76edcfdababe30ab8a0e712","paymentType":"sent","description":null,"pending":false,"feeMsat":1032}

2023-04-12

2023-04-12T09:23:18.890Z [DEBUG]  WalletStore: SAT051: State: STARTED
2023-04-12T09:23:18.891Z [DEBUG]  LightningStore: SAT104: walletStated
2023-04-12T09:23:18.933Z [DEBUG]  ChannelStore: SAT064: max receivable 3891506000, single payment 4294967000
2023-04-12T09:23:18.933Z [DEBUG]  ChannelStore: SAT039: Channel Balance: 108494, 5199, 0
2023-04-12T09:23:26.614Z [DEBUG]  LightningStore: SAT0062: synced
2023-04-12T09:23:26.618Z [DEBUG]  LightningStore: SAT0062: newBlock : 785050
...
2023-04-12T09:36:41.937Z [DEBUG]  SessionStore: SAT070 paySessionInvoice: pr=lnbc32907300p1pjrv7afpp5eultr29pdl0tdxqdy9uql6vumgv2wgtz7zx3sd083rz7p00lcw3qdz22dshg6tdda6x7w3qxajnxdphvg6njtt9xesnytf5xcukytfe8qux2tf5xd3rjc33vejrgdr9vccqzpgxqrrsssp5w96h9w5840p8n7hdk6j6cxvm97ch3pndauv07u8qa5sjv4elwj6q9qyyssqup5a02fvwqrheu9tp8nvx0ylucldz373h6mxedqnlwr5l4elns5rjk3yt60u3xrtzcsnxhzk886869frcpmetaejz882xmr00dakcasp5t2fvm sig=rdrp81s7wgdksdqoxtcyhgmsoymtya6bzzif4yg6zt39wkbgguda1w99di4bb4nkuitw33ckzcwsx8qwtc5dzkkmgiw4pr9x6r1dhfj6
2023-04-12T09:36:43.775Z [DEBUG]  LightningStore: SAT0062: paymentFailed : {"bolt11":{"routingHints":[],"timestamp":1681292201,"paymentHash":"cf3eb1a8a16fdeb6980d21780fe99cda18a72162f08d1835e788c5e0bdffc3a2","expiry":3600,"descriptionHash":null,"description":"Satimoto: 7e347b59-e6a2-469b-988e-43b9b1fd44ef","payeePubkey":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","paymentSecret":[113,117,114,186,135,171,194,121,250,237,182,165,172,25,155,47,177,120,134,109,239,24,255,112,224,237,33,38,87,63,116,180],"amountMsat":3290730,"bolt11":"lnbc32907300p1pjrv7afpp5eultr29pdl0tdxqdy9uql6vumgv2wgtz7zx3sd083rz7p00lcw3qdz22dshg6tdda6x7w3qxajnxdphvg6njtt9xesnytf5xcukytfe8qux2tf5xd3rjc33vejrgdr9vccqzpgxqrrsssp5w96h9w5840p8n7hdk6j6cxvm97ch3pndauv07u8qa5sjv4elwj6q9qyyssqup5a02fvwqrheu9tp8nvx0ylucldz373h6mxedqnlwr5l4elns5rjk3yt60u3xrtzcsnxhzk886869frcpmetaejz882xmr00dakcasp5t2fvm"},"nodeId":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","error":"status: Internal, message: \"error calling RPC: RPC error response: RpcError { code: 210, message: \\\"Destination 0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5 is not reachable directly and all routehints were unusable.\\\", data: None }\", details: [], metadata: MetadataMap { headers: {\"content-type\": \"application/grpc\", \"date\": \"Wed, 12 Apr 2023 09:36:43 GMT\", \"content-length\": \"0\"} }"}
...
2023-04-12T09:37:42.389Z [DEBUG]  SessionStore: SAT070 paySessionInvoice: pr=lnbc65875760p1pjrv7l9pp5zrq29zrnck6aaeqw2y50tdu7nvlfxpsvytfxj7evllp8jl6r669qdz22dshg6tdda6x7w3qxajnxdphvg6njtt9xesnytf5xcukytfe8qux2tf5xd3rjc33vejrgdr9vccqzpgxqrrsssp5lvxf4j7s63z65vke60sy22ch46udn6wa4fy0zh5nglctmzwq7qzq9qyyssqukqtryqd3lygfjpa4f0fv72srnphxag872fhk2kusjtnnr69hgtpklzewfav54c8gm2x7dzfw3sz49ys7puy20ea4d9jm3aqevcknesq0h2zy3 sig=rngg468bqpuqaom15t1jekazafwykc879unxgntn4kec7s5m1ybue61czhatk8nf5jna3xf95nktws9r9mrx3b4t85yybnzkc68uim5i
2023-04-12T09:37:44.287Z [DEBUG]  LightningStore: SAT0062: paymentFailed : {"bolt11":{"routingHints":[],"timestamp":1681292261,"paymentHash":"10c0a28873c5b5dee40e5128f5b79e9b3e93060c22d2697b2cffc2797f43d68a","expiry":3600,"descriptionHash":null,"description":"Satimoto: 7e347b59-e6a2-469b-988e-43b9b1fd44ef","payeePubkey":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","paymentSecret":[251,12,154,203,208,212,69,170,50,217,211,224,69,43,23,174,184,217,233,221,170,72,241,94,147,71,240,189,137,192,240,4],"amountMsat":6587576,"bolt11":"lnbc65875760p1pjrv7l9pp5zrq29zrnck6aaeqw2y50tdu7nvlfxpsvytfxj7evllp8jl6r669qdz22dshg6tdda6x7w3qxajnxdphvg6njtt9xesnytf5xcukytfe8qux2tf5xd3rjc33vejrgdr9vccqzpgxqrrsssp5lvxf4j7s63z65vke60sy22ch46udn6wa4fy0zh5nglctmzwq7qzq9qyyssqukqtryqd3lygfjpa4f0fv72srnphxag872fhk2kusjtnnr69hgtpklzewfav54c8gm2x7dzfw3sz49ys7puy20ea4d9jm3aqevcknesq0h2zy3"},"nodeId":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","error":"status: Internal, message: \"error calling RPC: RPC error response: RpcError { code: 210, message: \\\"Destination 0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5 is not reachable directly and all routehints were unusable.\\\", data: None }\", details: [], metadata: MetadataMap { headers: {\"content-type\": \"application/grpc\", \"date\": \"Wed, 12 Apr 2023 09:37:43 GMT\", \"content-length\": \"0\"} }"}
...
2023-04-12T09:38:42.661Z [DEBUG]  SessionStore: SAT070 paySessionInvoice: pr=lnbc32924450p1pjrvlpppp59za907hkpy5jhwr6nf995c9wehczasgj9y5un8xv5pkvsn3pwwysdz22dshg6tdda6x7w3qxajnxdphvg6njtt9xesnytf5xcukytfe8qux2tf5xd3rjc33vejrgdr9vccqzpgxqrrsssp54ws73eqxd0h64f2s7m69qasu8sctf6fvg5vw4ghrvtsfxgsqwkws9qyyssqgqucq3yzehzpc4af48zfcgzygu8kjv2g7lxtmaekcagr5wg74jdr2hs496pawyy77uukr2x3af0yga4df32r98wqg3e3hs65j9zlwmqp7kxcp4 sig=rdi61yxy7y9t6sythysfx7tio3drd39snzkpqnjsq5aeary63gfrgecrn7zoji8txp7o7s8tikj9pjtn5zhy3b6i4s6pcgwi4oapyadz
2023-04-12T09:38:44.323Z [DEBUG]  LightningStore: SAT0062: paymentFailed : {"bolt11":{"routingHints":[],"timestamp":1681292321,"paymentHash":"28ba57faf609292bb87a9a4a5a60aecdf02ec1122929c99ccca06cc84e217389","expiry":3600,"descriptionHash":null,"description":"Satimoto: 7e347b59-e6a2-469b-988e-43b9b1fd44ef","payeePubkey":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","paymentSecret":[171,161,232,228,6,107,239,170,165,80,246,244,80,118,28,60,48,180,233,44,69,24,234,162,227,98,224,147,34,0,117,157],"amountMsat":3292445,"bolt11":"lnbc32924450p1pjrvlpppp59za907hkpy5jhwr6nf995c9wehczasgj9y5un8xv5pkvsn3pwwysdz22dshg6tdda6x7w3qxajnxdphvg6njtt9xesnytf5xcukytfe8qux2tf5xd3rjc33vejrgdr9vccqzpgxqrrsssp54ws73eqxd0h64f2s7m69qasu8sctf6fvg5vw4ghrvtsfxgsqwkws9qyyssqgqucq3yzehzpc4af48zfcgzygu8kjv2g7lxtmaekcagr5wg74jdr2hs496pawyy77uukr2x3af0yga4df32r98wqg3e3hs65j9zlwmqp7kxcp4"},"nodeId":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","error":"status: Internal, message: \"error calling RPC: RPC error response: RpcError { code: 210, message: \\\"Destination 0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5 is not reachable directly and all routehints were unusable.\\\", data: None }\", details: [], metadata: MetadataMap { headers: {\"content-type\": \"application/grpc\", \"date\": \"Wed, 12 Apr 2023 09:38:44 GMT\", \"content-length\": \"0\"} }"}
...
2023-04-12T09:49:43.010Z [DEBUG]  SessionStore: SAT070 paySessionInvoice: pr=lnbc32935720p1pjrvl4kpp5fnmv9jqe9ye26chrchj0huustc0v34dyukzpae9qr6u2jq947aesdz22dshg6tdda6x7w3qxajnxdphvg6njtt9xesnytf5xcukytfe8qux2tf5xd3rjc33vejrgdr9vccqzpgxqrrsssp5f09cp4y4lm3wkx93eqty2lr02tccfa4zamagzgrjxzj9xlex6hlq9qyyssqc0lwvya3huvjwu8usnq65v6945shhjrzuy2rh8e4u9rg56e3s8z8274qwadpje68skhmyfkcr4x6qzsfdazux6ywqzcqczh5r3y6fgsp7c6wya sig=rdhdme43jb6pfndiixwit6er3sf5b1q7jq55creonefnb11jxmf5q83ry4odhs9tmctco7hw5b9i1en5tnqrdgrdsj6ef3fcpp1bo77z
2023-04-12T09:49:53.894Z [DEBUG]  LightningStore: SAT0062: synced
2023-04-12T09:49:53.896Z [DEBUG]  LightningStore: SAT0062: paymentSucceed : {"details":{"lnurlMetadata":null,"lnurlSuccessAction":null,"keysend":true,"label":"","paymentPreimage":"","destinationPubkey":"0272910e9cbc98295093d3e4490a4c89c00f024e08cec7cf75d635a6005eefa2b5","paymentHash":"4cf6c2c8192932ad62e3c5e4fbf3905e1ec8d5a4e5841ee4a01eb8a900b5f773","lnAddress":null,"bolt11":"","type":"ln"},"amountMsat":3293572,"paymentTime":1681292984,"id":"4cf6c2c8192932ad62e3c5e4fbf3905e1ec8d5a4e5841ee4a01eb8a900b5f773","paymentType":"sent","description":null,"pending":false,"feeMsat":1032}

Update mockito to v1.0.0

Here's the migration guide:

• Migrating to the new API

Add support for LUD-18: Payer identity in payRequest protocol

See https://github.com/lnurl/luds/blob/luds/18.md

Setting log stream does not stream log entries

Binaries compiled for kotlin and swift do not seem to be producing log entries from the breez-sdk.

breez_sdk.setLogStream(logStream: BreezSDKLogStream(emitter: self))

class BreezSDKLogStream: NSObject, LogStream {
    var emitter: RCTEventEmitter
    
    static let emitterName: String = "breezSdkLog"
    
    init(emitter: RCTEventEmitter) {
        self.emitter = emitter
    }
    
    func log(l: LogEntry) {
        self.emitter.sendEvent(withName: BreezSDKListener.emitterName,
                               body: [
                                "line":  l.line,
                                "level": l.level
                               ])
    }
}

Add build step to create Android archive (AAR) file

@ademar111190 as you said in the past it would be easier to Android dev to work with rather than configure the binaries.

Add settlement time on outgoing payment

Add ability to query for closed channels

Send notifications to an endpoint

Routing hints are missing for unconfirmed zero-conf channels.

Currently when we create an invoice for private unconfirmed (zero conf) channel there are no routing hints and we can't populate them in the client side since there is no short channel id populated on the channel returned by list_peers.
It would be best if regardless of adding the hints on the invoice the alias is returned as well.

Connect automatically to peer when scheduled

When we use greenlight API to connect to a peer it would be great if greenlight will re-connect this peer when scheduled.
Otherwise the client would have to maintain this connection which requires periodic polling the peer connection.

ln address is parsed as InputType::Url

error with make init

Ubuntu 18.04.6 LTS

Using android-ndk-r25c-linux

make init
cargo install --version 0.22.0 uniffi_bindgen
    Updating crates.io index
  Downloaded uniffi_bindgen v0.22.0
  Downloaded 1 crate (136.2 KB) in 1.25s
  Installing uniffi_bindgen v0.22.0
  Downloaded askama_shared v0.12.2
  Downloaded atty v0.2.14
  Downloaded askama_escape v0.10.3
  Downloaded anyhow v1.0.69
  Downloaded askama v0.11.1
  Downloaded bitflags v1.3.2
  Downloaded camino v1.1.2
  Downloaded bincode v1.3.3
  Downloaded heck v0.4.1
  Downloaded glob v0.3.1
  Downloaded autocfg v1.1.0
  Downloaded cargo-platform v0.1.2
  Downloaded clap v3.2.23
  Downloaded itoa v1.0.5
  Downloaded cargo_metadata v0.15.3
  Downloaded mime_guess v2.0.4
  Downloaded askama_derive v0.11.2
  Downloaded indexmap v1.9.2
  Downloaded siphasher v0.3.10
  Downloaded termcolor v1.2.0
  Downloaded thiserror v1.0.38
  Downloaded thiserror-impl v1.0.38
  Downloaded unicode-ident v1.0.6
  Downloaded nom v7.1.3
  Downloaded proc-macro-error-attr v1.0.4
  Downloaded once_cell v1.17.1
  Downloaded memchr v2.5.0
  Downloaded clap_lex v0.2.4
  Downloaded cfg-if v1.0.0
  Downloaded textwrap v0.16.0
  Downloaded semver v1.0.16
  Downloaded serde v1.0.152
  Downloaded version_check v0.9.4
  Downloaded unicase v2.6.0
  Downloaded ryu v1.0.12
  Downloaded proc-macro2 v1.0.51
  Downloaded syn v1.0.107
  Downloaded toml v0.5.11
  Downloaded proc-macro-error v1.0.4
  Downloaded strsim v0.10.0
  Downloaded uniffi_meta v0.22.0
  Downloaded libc v0.2.139
  Downloaded scroll v0.11.0
  Downloaded weedle2 v4.0.0
  Downloaded uniffi_testing v0.22.0
  Downloaded plain v0.2.3
  Downloaded uniffi_checksum_derive v0.22.0
  Downloaded scroll_derive v0.11.0
  Downloaded goblin v0.6.0
  Downloaded fs-err v2.9.0
  Downloaded minimal-lexical v0.2.1
  Downloaded paste v1.0.11
  Downloaded hashbrown v0.12.3
  Downloaded serde_derive v1.0.152
  Downloaded quote v1.0.23
  Downloaded mime v0.3.16
  Downloaded os_str_bytes v6.4.1
  Downloaded clap_derive v3.2.18
  Downloaded serde_json v1.0.93
  Downloaded log v0.4.17
  Downloaded 60 crates (3.0 MB) in 1.20s
   Compiling proc-macro2 v1.0.51
   Compiling quote v1.0.23
   Compiling unicode-ident v1.0.6
   Compiling syn v1.0.107
   Compiling version_check v0.9.4
   Compiling serde_derive v1.0.152
   Compiling serde v1.0.152
   Compiling memchr v2.5.0
   Compiling serde_json v1.0.93
   Compiling mime v0.3.16
   Compiling camino v1.1.2
   Compiling semver v1.0.16
   Compiling minimal-lexical v0.2.1
   Compiling libc v0.2.139
   Compiling thiserror v1.0.38
   Compiling autocfg v1.1.0
   Compiling itoa v1.0.5
   Compiling log v0.4.17
   Compiling ryu v1.0.12
   Compiling anyhow v1.0.69
   Compiling askama_escape v0.10.3
   Compiling heck v0.4.1
   Compiling paste v1.0.11
   Compiling cfg-if v1.0.0
   Compiling os_str_bytes v6.4.1
   Compiling once_cell v1.17.1
   Compiling hashbrown v0.12.3
   Compiling textwrap v0.16.0
   Compiling fs-err v2.9.0
   Compiling plain v0.2.3
   Compiling siphasher v0.3.10
   Compiling strsim v0.10.0
   Compiling termcolor v1.2.0
   Compiling bitflags v1.3.2
   Compiling glob v0.3.1
   Compiling unicase v2.6.0
   Compiling proc-macro-error-attr v1.0.4
   Compiling proc-macro-error v1.0.4
   Compiling clap_lex v0.2.4
   Compiling indexmap v1.9.2
   Compiling nom v7.1.3
   Compiling mime_guess v2.0.4
   Compiling atty v0.2.14
   Compiling weedle2 v4.0.0
   Compiling thiserror-impl v1.0.38
   Compiling scroll_derive v0.11.0
   Compiling clap_derive v3.2.18
   Compiling uniffi_checksum_derive v0.22.0
   Compiling scroll v0.11.0
   Compiling goblin v0.6.0
   Compiling clap v3.2.23
   Compiling cargo-platform v0.1.2
   Compiling toml v0.5.11
   Compiling uniffi_meta v0.22.0
   Compiling bincode v1.3.3
   Compiling cargo_metadata v0.15.3
   Compiling askama_shared v0.12.2
   Compiling uniffi_testing v0.22.0
   Compiling askama_derive v0.11.2
   Compiling askama v0.11.1
   Compiling uniffi_bindgen v0.22.0
    Finished release [optimized] target(s) in 1m 36s
  Installing /home/ubuntu/.cargo/bin/uniffi-bindgen
   Installed package `uniffi_bindgen v0.22.0` (executable `uniffi-bindgen`)
make -C ../sdk-bindings init
make[1]: Entering directory '/home/ubuntu/bitcoin/breez-sdk/libs/sdk-bindings'
rustup target add aarch64-apple-ios x86_64-apple-ios
/bin/bash: rustup: command not found
makefile:7: recipe for target 'init' failed
make[1]: *** [init] Error 127
make[1]: Leaving directory '/home/ubuntu/bitcoin/breez-sdk/libs/sdk-bindings'
makefile:3: recipe for target 'init' failed
make: *** [init] Error 2

Add ability to fetch only changes for incremental sync to device

Ideally the client would pass the last sync timestamp with the outgoing payments query and settled invoices query and the service will reply only with the changes since that timestamp.

Ability to limit the fee of a specific payment (base & proportional fees)

Support pagination in payments list query

Implement React Native bindings

Add ability to export SQL storage

Add support for LUD-10: `aes` successAction in LNURL-pay

See https://github.com/lnurl/luds/blob/luds/10.md

Try to send the largest amount from a single channel

lightningnetwork/lnd#4610

Add methods to NodeAPI for signmessage and checkmessage

It would be great if the NodeAPI could expose methods to perform signmessage and checkmessage on the Greenlight node.

https://lightning.readthedocs.io/lightning-checkmessage.7.html
https://lightning.readthedocs.io/lightning-signmessage.7.html

Update uniffi-bindgen to v0.23.0

There has been a big structural rework on UNiFFI crate with v.0.23.0 and it has breaking changes.

Here's the migration guide:
Migrating to UniFFI 0.23

Add lightning address to payment model

We need to add the lightning address to the payment model https://github.com/breez/breez-sdk/blob/main/libs/sdk-core/src/models.rs#L259-L268 in order to replicate the breez mobile logic here https://github.com/breez/breezmobile/blob/232f1178d86b1b7152a03036ab33aafcf0c933a9/lib/bloc/account/account_model.dart#L885

Add auth key for register_payment

Add PaymentSent event

See breez/c-breez#444 (comment)

Addition of Expiry parameter for invoice creation API

Invoices generated right now have a fixed expiry, this is not useful if the invoices are meant to be settled in different timelines.
An additional parameter that would help specifying the expiry of an invoice is required, and in the API call if not specified it needs to be the default expiry that is available

Merge user config with default config

Right now if the user passes a config to the SDK we use all values from it, if not we use the default values.
It is better to allow the user override some of the values so in that case we should merge the config passed by the user with the default config by using first the user provided values and for those that were not provided, take the default ones.

Sync with pending payments

Currently the SDK only sync up with successfully completed payments and returns them as part of the payment list.
We need also to sync with "pending" payments, e.g those with in flight htlcs (https://github.com/Blockstream/greenlight/blob/main/libs/proto/greenlight.proto#L416)

Send largest amount from a single channel

Depends on

• Blockstream/greenlight#65

Reduce SDK storage footprint to improve market penetration

In a recent Livera episode ¹ they mention a big problem with Bitcoin wallets on low-end Android devices (like often used in Africa, Asia, etc) is storage space. People have to uninstall other apps before they can install a wallet app.

Hermann – 00:12:27:

Most adults [...] have smartphones. [...] Most of it is sort of like cheap android devices. [...] And generally the problem is, does the phone have enough memory to load a new application? So if you have a bitcoin wallet that takes up a little bit more memory, then you might have to start deleting other apps. That’s actually the biggest problem that we have.

Stephan – 00:13:00:

[...] That’s something I’ve noticed even when I talk to Sri Lankans as well. It can be a similar situation where they’ve got a cheap Android and they need to uninstall some other applications or they can install Bitcoin apps or wallets.

We should therefore make the SDK as slim as possible, so apps that integrate it have an easier time in those markets.

A few ways to do that:

• consolidate / limit dependencies
• place SDK features behind feature flags, so apps which want to only use a subset of the SDK have a smaller storage footprint
• tweak Cargo flags to reduce binary size²

Footnotes

1. https://stephanlivera.com/episode/441/ ↩

2. https://github.com/johnthagen/min-sized-rust ↩

sdk-react-native iOS/Android example app broken

Hey, just tried to take react-native-sdk for a spin but seems as though it's not currently linking by default (both iOS and Android failing to compile).

What's the current state of the RN lib - is this expected (is the framework still WIP #96)?

Use alias if possible for the lsp routing hints

How to contribute

Hey, I just fond this repo and I'm interested to contribute but greenlight repo is private. How can I start? Where can I ask for a ssh-key?

Failed to parse lnurl

After ln_address changes, parsing non-ln address LNURL payments are failing.

• Create an invoice on https://lightning.gifts from LNURL tab to test.

FfiException(RESULT_ERROR, error decoding response body: data did not match any variant of untagged enum LnUrlRequestData

• Scan the QR code generated on https://tippin.me/@Breez_Tech

FfiException(RESULT_ERROR, Unrecognized input type, null)

Send to on-chain: add NewReverseSwap API

Create a new reverse swap on the Boltz API endpoint.

https://docs.boltz.exchange/en/latest/api/#creating-reverse-swaps

Send notifications to multiple endpoints

Add build step to create iOS framework

This should make iOS devs life a lot easier to work with.

Send to on-chain: add ReverseSwapInfo API

Call the Boltz API to get point-in-time reverse swap infos about a currency pair.

https://docs.boltz.exchange/en/latest/api/#getting-pairs

Enable changing the last node onion in htlc_accepted hook

Missing payment reference with failed payment event

Currently the payment failure event only emits an error string without reference to the original payment. To resolve which payment has failed a client will also need a reference to the payment, be it the original payment object or payment hash.

Publish to crate.io

Consider adding Interoptopus for additional bindings

Please consider adding support for https://github.com/ralfbiedert/interoptopus/ to support generating bindings for C#

Generate React Native module

• Implement the native kotlin code
• Implement the swift native code
• Implement the javascript wrapper
• Implement code generation for the kotlin/swift code
• implement code generation for the javascript wrapper

I believe the end result should be a 100% generated code for RN Native module however we should first develop the module manually and then add the automatic code generation.
Here is an intro on how to create such native modules: https://reactnative.dev/docs/native-modules-intro
Such module has two parts:

1. The native (swift, kotlin) code - which is basically enough for using it from javascript but without type safety for objects passing as arguments.
2. The javascript wrapper - That makes it easier to use and provide type safe interface for the module.

Creating the native code

I think this could be a wrapper on top of the uniffi interface, for example in kotlin it is another kotlin class that delegates the calls to the uniffi generated functions.
The reason why we need a wrapper is because the wrapper provides the interface for the javascript code and it has some constraints (for example doesn't support objects but use ReadableMaps instead https://reactnative.dev/docs/native-modules-android#argument-types) and we can't use the uniffi generated interface for that. So the RN native code needs to provide the interface to the javacript as similar as possible to the uniffi interface and then handle argument mapping when delegating the calls.

After that is in place we can develop the javascript code that consists mostly of delegation to the native code and convert maps to type safe interfaces.

Send to on-chain address

• Boltz API: get reverse swap fees and rate infos
  • #99
• Boltz API: create new reverse swap
  • #100
• Create basic model and helpers to integrate with Breez Services
  • #106
  • #107
  • #108
  • #129
  • #130
• End-to-end successful reverse swap (using CLI): #168
  • Trigger rev swap, persist minimal state (rev swap ID)
  • Step 1: Pay HODL invoice from SDK
  • Step 2: Detect Boltz status change: invoice payment received, lock tx broadcasted
  • Step 3: Detect Boltz status change: lock tx confirmed
  • Step 4: Construct, sign and broadcast claim tx
• Improve successful workflow above
  • Validate lock tx
  • TBD: Store (and validate) redeem script? Or generate it dynamically? (incl. OP_CHECKSIG sig)
    • Same question regarding expiration block height: configurable expiration height?
  • Ensure only one reverse swap is allowed at a time (deny new one until ClaimTx for current one is in mempool)
  • On startup: check if any pending reverse swaps available (if any found, advance the flow)
• Improve claim tx mgmt
  • If claim tx is in mempool, on each new block (or each 6? TBD configurable) re-broadcast the claim tx
• Improve status mgmt:
  • make sure we detect PleaseWait (crucial phase during creation where the HODL payment is being attempted; if app aborts during this phase and the invoice is not paid, the reverse swap on Boltz does not progress to LockTxMempool), Success, Expired and Failed (transaction.failed)
    • TBD: send_onchain should not return until LN payment confirmed or failed? could take up to 1-2 mins
  • If we timeout HODL payment before GL times out, then get_status() cannot differentiate between ReverseSwapStatus::InProgress and ReverseSwapStatus::Cancelled because payment.pending is true when retrieved via NodeAPI. Proposed solution: Remove explicit timeout, let pay() fail or timeout (up to ~2 mins)
  • Rebuild cache if cache table missing
  • TBD: Clarify meaning of in progress: does it covered all monitored stauses? if not (e.g. ClaimTxMempool = in progress), then the API call to list_in_progress_rev_swaps can theoretically return more than one?
• Test cases: simulate transitions based on SDK event (new block, invoice paid)
• Test cases for all success scenarios (incl. retries)
• Test cases for all failure scenarios (incl. retries)
• Improve storage
  • Once model is clear, move from temp global store to SQL table
  • Rebase on main, store cache table in storage.sql, store persistent data in sync_storage.sql
  • TBD: When rev swap cache is not filled: do we query Boltz status of each rev swap in wallet's history? If not, do we then store Boltz status as persistent (not cached) field?
  • Restore wallet (without cache SQL) and test if past successful / failed, ongoing rev swap shows
• Full working CLI command, rustdoc snippet
• TBD: trigger notifications? If yes, at which step?
• TBD: call pairs API within send_onchain, or ask for pairs hash as arg? => as arg to service call
  • Based on that: gracefully handle get_pairs errors
  • Add CLI method for get_pairs, return generic struct and fields from which user can tell the rev swap fees
• Fix: When trying to pay (or start rev swap with) more than available in wallet, payment doesn't immediately fail, but times out 1-2 minutes later
• NodeAPI::list_payments changes
  • include pending payments
  • on next sync, update existing pending payments to their new status
  • test: on success, does pending payment get updated to complete?
  • test: on failure, does pending payment get removed from payment list?
• TBD: Support second reverse swap protocol?

The Boltz backend also supports a different Reverse Swap protocol that requires an invoice for the miner fees to be paid before the actual hold invoice of the Reverse Swap. If that protocol is enabled, the response object will also contain minerFeeInvoice. Once that minerFeeInvoice is paid, Boltz will send the event minerfee.paid and when the actual hold invoice is paid, the onchain coins will be sent.
https://docs.boltz.exchange/en/latest/api/#creating-reverse-swaps

Add configuration to cli

Add ability to query for an external UTXO confirmation

Add domain information to parse results

• Add decoded uri's host information to parse results

This is used to identify sender e.g., "Pay to api.lightning.gifts"