# Breez Spark Lightning Plugin

## BETA RELEASE

Allows you to enable lightning on your stores using [Breez Spark SDK](https://github.com/breez/spark-sdk), a **nodeless** Lightning protocol.

Breez Spark SDK enables you to have a self-custodial Lightning experience without hosting any infrastructure yourself or managing channels.

If you have used other wallets that use Breez SDK, you may be able to import the same mnemonic directly into BTCPay Server.

## 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 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. **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 Spark wallet will be initialized
6. You can now use Lightning to receive and send payments

## Important Notes

### 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.

### Liquidity Management

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)
