# Lethean BTCPay Server Plugin

Accept [Lethean](https://lethean.io) payments in BTCPay Server. Privacy-focused cryptocurrency with confidential transactions and integrated addresses.

> [!WARNING]
> This plugin shares a single Lethean wallet across all stores in the BTCPay Server instance. Use this plugin only if you are not sharing your instance.

## How it works

When a customer creates an invoice, the plugin generates a unique **integrated address** (containing an embedded payment ID) for each payment. A background poller checks the wallet every 15 seconds for incoming payments matching pending invoices, tracks confirmations, and settles invoices based on your configured threshold.

## Configuration

| Environment variable | Required | Description | Example |
| --- | --- | --- | --- |
| `BTCPAY_LTHN_DAEMON_URI` | Yes | URI of the letheand RPC interface | `http://127.0.0.1:46941` (testnet) or `http://127.0.0.1:36941` (mainnet) |
| `BTCPAY_LTHN_WALLET_DAEMON_URI` | Yes | URI of the simplewallet RPC interface | `http://127.0.0.1:46944` (testnet) or `http://127.0.0.1:36944` (mainnet) |
| `BTCPAY_LTHN_WALLET_DAEMON_WALLETDIR` | No | Directory where wallet files are stored (for auto-loading on startup) | `/wallet` |

## Setup

### 1. Run Lethean daemon

Testnet:
```bash
letheand --testnet --rpc-bind-ip=0.0.0.0 --rpc-bind-port=46941
```

Mainnet:
```bash
letheand --rpc-bind-ip=0.0.0.0 --rpc-bind-port=36941
```

### 2. Run Lethean wallet in RPC mode

Create or open a wallet, then start simplewallet with RPC enabled:

Testnet:
```bash
simplewallet --wallet-file /path/to/wallet \
  --password "your-password" \
  --testnet \
  --daemon-address 127.0.0.1:46941 \
  --rpc-bind-port 46944
```

Mainnet:
```bash
simplewallet --wallet-file /path/to/wallet \
  --password "your-password" \
  --daemon-address 127.0.0.1:36941 \
  --rpc-bind-port 36944
```

For receive-only setups, create a watch-only wallet first:

```bash
simplewallet --generate-new-wallet /path/to/wallet
# Then from the wallet prompt:
save_watch_only /path/to/watch-only-wallet password
```

### 3. Install the plugin

In BTCPay Server, go to **Server Settings > Plugins** and install the Lethean plugin. Then configure the environment variables above and restart.

### 4. Enable Lethean for your store

Go to **Store Settings > Lethean** to enable it and set your preferred confirmation threshold.

## Docker

A Docker image with letheand and simplewallet is available:

```bash
docker pull letheanio/letheand:latest
```

Run the daemon:
```bash
docker run -d --name letheand \
  -p 46941:46941 \
  -v lethean_data:/data \
  letheanio/letheand:latest \
  letheand --testnet --rpc-bind-ip=0.0.0.0 --rpc-bind-port=46941
```

Run the wallet:
```bash
docker run -d --name lethean_wallet \
  -p 46944:46944 \
  -v lethean_wallet:/wallet \
  --entrypoint simplewallet \
  letheanio/letheand:latest \
  --testnet --rpc-bind-ip=0.0.0.0 --rpc-bind-port=46944 \
  --daemon-address=letheand:46941 \
  --wallet-file=/wallet/wallet --password=""
```

## Development

### Requirements

- .NET 8.0 SDK
- Git
- Docker and Docker Compose

### Clone and build

```bash
git clone --recurse-submodules https://github.com/lethean-io/btcpayserver-lethean-plugin
cd btcpayserver-lethean-plugin
dotnet build btcpay-lethean-plugin.sln
```

### Run unit tests

```bash
dotnet test BTCPayServer.Plugins.UnitTests
```

### Run integration tests

```bash
docker compose -f BTCPayServer.Plugins.IntegrationTests/docker-compose.yml run tests
```

### Local development

Start the dev dependencies:

```bash
cd BTCPayServer.Plugins.IntegrationTests/
docker compose up -d dev
```

Create `appsettings.dev.json` in `btcpayserver/BTCPayServer`:

```json
{
  "DEBUG_PLUGINS": "../../Plugins/Lethean/bin/Debug/net8.0/BTCPayServer.Plugins.Lethean.dll",
  "LTHN_DAEMON_URI": "http://127.0.0.1:46941",
  "LTHN_WALLET_DAEMON_URI": "http://127.0.0.1:46944"
}
```

Then run BTCPay Server with the plugin loaded.

## Technical details

- **Address generation**: Integrated addresses with random 8-byte payment IDs (unique per invoice)
- **Payment detection**: Polls `get_bulk_payments` every 15 seconds
- **Fee**: Fixed 0.01 LTHN per transaction
- **Divisibility**: 12 decimal places
- **Rate source**: CoinGecko (`LTHN_BTC`)
- **Confirmations**: Configurable (0, 1, 10, or custom)

## License

[MIT](LICENSE.md)