aljaz/BTCPayServerPlugins
1
0
Fork 0
mirror of https://github.com/aljazceru/BTCPayServerPlugins.git synced 2025-12-16 23:24:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update README for Spark SDK migration

Browse Source 
- Document Spark SDK (nodeless) vs Greenlight differences
- Update setup instructions (no more certificates/invite codes)
- Clarify liquidity management with deposits
- Document limitations (no swap-out, no node ID)
- Add technical details and build instructions
- Emphasize security warnings for mnemonic storage
This commit is contained in:
Claude
2025-11-13 16:06:49 +00:00
parent 7e60fe0976
commit 6a739d06bf
1 changed files with 74 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
Plugins/BTCPayServer.Plugins.Breez/README.md
View File

@@ -1,32 +1,90 @@
# Breez lightning support plugin
# Breez Spark Lightning Plugin
## BETA RELEASE
Allows you to enable lightning on your stores using [Breez SDK](https://breez.technology/sdk/), powered by [Blockstream Greenlight](https://blockstream.com/lightning/greenlight/).
Allows you to enable lightning on your stores using [Breez Spark SDK](https://github.com/breez/spark-sdk), a **nodeless** Lightning protocol.
Breez SDK and Greenlight enables you to have a non-custodial lightning experience, without hosting any of the infrastructure yourself.
Breez Spark SDK enables you to have a self-custodial Lightning experience without hosting any infrastructure yourself or managing channels.
Additionally, Breez SDK comes with built-in liquidity and channel automation, reducing the complexity of managing your lightning node.
If you have used other wallets that use Breez SDK, you may be able to import the same mnemonic directly into BTCPay Server.
If you have used any other wallet that uses Breez SDK, you can import it directly into BTCPay Server and continue using it in parallel.
## What is Spark SDK?
Spark SDK is Breez's "nodeless" Layer 2 protocol that provides Lightning functionality without running a full Lightning node. Unlike the previous Greenlight-based implementation which required Blockstream's hosting service, Spark operates through a decentralized network of operators.
### Key Differences from Greenlight:
| Feature | Spark (Nodeless) | Greenlight (Old) |
|---------|------------------|------------------|
| **Infrastructure** | No node hosting required | Hosted by Blockstream |
| **Setup** | Mnemonic + API key only | Required certificates + invite code |
| **Architecture** | Nodeless protocol | Full Lightning node |
| **Channel Management** | Automatic via deposits | Manual swap-in/swap-out |
| **Onchain Operations** | Deposit claims only | Full swap functionality |
## Usage
1. Install the plugin from the BTCPay Server > Settings > Plugin > Available Plugins, and restart
1. Install the plugin from BTCPay Server > Settings > Plugin > Available Plugins, and restart
2. In your store > Wallets > Lightning, Configure Breez
3. You will be on a page asking for:
- Mnemonic: This is your 12 word seed phrase. YOU SHOULD GENERATE THIS FROM A SEGWIT OR LEGACY SEGWIT WALLET AND KEEP IT SAFE. If you have used Breez before, you can use the same seed phrase you used in Breez. You can also use the seed phrase from your BTCPay hot wallet. This SEED PHRASE will be stored on BTCPAY SERVER. IF YOU USE A SHARED BTCPAY SERVER, YOU ARE EXPOSING YOUR SEED PHRASE TO THE SERVER ADMINISTRATOR. Type it in 'word word word..." format.
- Greenlight credentials: In the case of a new seed, you'll need to acquire certificates for issuing new nodes from Blockstream. You can get these for free at https://greenlight.blockstream.com. Select the entire `gl-certs.zip` file provided by Greenlight.
- Invite Code: Alternatively, you may have an invite code which can be used instead of the Greenlight credentials.
- **Mnemonic**: This is your 12 word seed phrase. **GENERATE THIS FROM A SECURE WALLET AND KEEP IT SAFE**. This seed phrase will be stored on BTCPay Server. **IF YOU USE A SHARED BTCPAY SERVER, YOU ARE EXPOSING YOUR SEED PHRASE TO THE SERVER ADMINISTRATOR**. Type it in 'word word word...' format.
- **API Key** (optional): Breez API key. If not provided, a default key will be used.
4. Click Save
5. Your new lightning node will be created.
6. Your first lightning invoice will have a relatively high minimum amount limit. This is because Breez SDK requires a minimum amount to be able to open a channel. A note on Inbound Liquidity - Breez appears to provide a low inbound liquidity at first and as you use it, it grants more inbound liquidity gradaully which puts you at risk of receiving partial paid invoices. But if you want instant channel inbound liquidity, use the Swap In feature to bring in Bitcoin, then create a lightning invoice from an outside lightning wallet such as Breez or Phoenix wallet, and pay it via the Payments tab in Breez. This lubricates the channels and your inbound liquidity will increase by the amount of your paid outbound invoice. You pay the channel open fee, instead of your customers. The amount you set your inbound liquidity is up to you so make it high enough that you don't have to regularly increase channel size which costs you sats down the road. For example, if you receive ten payments of 50,000 sats a month (500,000 sats), to start with 1.5 to 2 million sats channel at the beginning.
7. You can now use your lightning node to receive payments.
5. Your Spark wallet will be initialized
6. You can now use Lightning to receive and send payments
## Important Notes
NOTE: In the future, Blockstream Greenlight will offer a way to generate read-only access keys for your already issued node, so that you can use these instead of exposing your mnemonic phrase to BTCPay Server, allowing a lightweight, non-custodial lightning experience, even on shared BTCPay Server instances.
### Security Warning
⚠️ **Your mnemonic seed phrase is stored on the BTCPay Server**. On shared/hosted BTCPay instances, the server administrator can access your funds. Only use this plugin on BTCPay servers you fully trust or self-host.
## Additional features
### Liquidity Management
* Swap-in: Send and convert onchain funds to your Breez lightning nodes.
* Swap-out: Send and convert lightning funds to your onchain wallet.
Spark SDK handles liquidity differently than traditional Lightning:
- **Deposits**: Send Bitcoin to generated deposit addresses. These are automatically claimed and converted to Lightning liquidity.
- **No Swap-Out**: Unlike Greenlight, Spark SDK does not support converting Lightning funds back to onchain. You can only withdraw via Lightning.
- **Automatic Channel Management**: The Spark network handles all channel operations automatically.
### First Invoice Considerations
Your first Lightning invoices may have higher minimum amounts because the system needs to establish initial liquidity through deposits.
## Additional Features
### Available Operations:
* **Claim Deposits**: Automatically claim onchain deposits and convert them to Lightning liquidity
* **Refund Deposits**: Refund unclaimed deposits back to an onchain address
* **Lightning Payments**: Send and receive Lightning payments (BOLT11)
* **Payment History**: View all Lightning and deposit transactions
### Not Available (compared to Greenlight):
* ❌ Swap-Out (Lightning → Onchain conversion)
* ❌ Manual channel management
* ❌ Node ID / pubkey (this is a nodeless protocol)
## Technical Details
This plugin uses:
- **Breez Spark SDK** C# bindings (built from source)
- Async/await pattern throughout
- Nodeless architecture - no Lightning node infrastructure required
## Building From Source
The Spark SDK C# bindings must be built from the [spark-sdk repository](https://github.com/breez/spark-sdk):
```bash
cd spark-sdk/crates/breez-sdk/bindings
make build-release
make bindings-csharp
cd langs/csharp/src
dotnet pack -c Release
```
## Support
For issues with:
- **The plugin**: Open an issue on this repository
- **Spark SDK**: Visit [Breez Spark SDK](https://github.com/breez/spark-sdk)
- **BTCPay Server**: Visit [BTCPay Server](https://github.com/btcpayserver/btcpayserver)