Skip to content

README.md

Latest commit

 

History

History
234 lines (167 loc) · 5.56 KB

README.md

File metadata and controls

234 lines (167 loc) · 5.56 KB
Raw

SamRock Protocol for BTCPay Server

This plugin enables quick setup for receiving funds from your BTCPay Server store directly to your self-custodial mobile wallet using the SamRock Protocol.

Usage

  1. Install the plugin by navigating to your BTCPay Server > Server Settings > Plugins, find "SamRock Protocol" in Available Plugins, install it, and restart your server. a. Ensure that the Boltz plugin is installed and enabled. b. SamRock requires BTCPay Server v2.1.6 or newer (plugin dependency resolution introduced in this version).
  2. Once installed, navigate to your Store > Plugins > SamRock Protocol
  3. You'll be presented with a form where you can select which payment methods you want to set up with your self-custodial wallet:
    • Bitcoin (On-chain)
    • Lightning (via Boltz API)
    • Liquid (On-chain, if Liquid is enabled on your server)
  4. Click "Generate QR Code". A unique QR code will be displayed.
  5. Scan this QR code with a compatible mobile wallet that supports the SamRock Protocol (e.g., Aqua Wallet). This will configure the necessary wallets on your mobile device and link them to your BTCPay Server store for receiving payments.

Protocol specification

SamRock Protocol is triggered by selecting payment methods to setup on BTCPay Server and generating QR code. The QR encodes a one-time setup URL:

https://<btcpayserver>/plugins/{storeId}/samrock/protocol?setup=btc,lbtc,btcln,&otp=<OTP>

Optionally, protocol may signal to wallet to upload all payment methods using setup=all querystring parameter. If setup parameter is omitted, wallet should default to setup=all and sending all supported payment methods.

The wallet must send a POST request to this URL with form field json containing setup details.

Request

POST /plugins/{storeId}/samrock/protocol?otp=<OTP>
Content-Type: application/x-www-form-urlencoded

json={...}

JSON structure

{
  "BTC": {
    "Descriptor": "wpkh([8f681564/84'/0'/0']xpub6CUGRU.../0/*)#8m68c9t7"
  },
  "LBTC": {
    "Descriptor": "ct(slip77(4a3b...ff9),elsh(wpkh([d34db33f/84'/1776'/0']xpub6FUGRU.../0/*)))"
  },
  "BTCLN": {
    "Type": "Boltz",
    "LBTC": {
      "Descriptor": "..."
    }
  }
}
  • BTC.Descriptor – Standard output descriptor (wpkh, pkh, sh(wpkh), tr).
  • LBTC.Descriptor – Confidential descriptor with slip77 blinding key and embedded descriptor.
  • BTCLN – Currently only "Type": "Boltz" is supported, with associated Liquid data.

Response

{
  "Success": true,
  "Message": "Wallet setup successfully.",
  "Result": {
    "BTC":    { "Success": true },
    "LBTC":   { "Success": true },
    "BTC_LN": { "Success": true }
  }
}

Errors include "Success": false with "Message" and "Error" fields.

Compatible Wallets

Greenfield API

The plugin exposes a Greenfield API to automate OTP creation and follow the setup flow programmatically.

Authentication and Permissions

  • Auth scheme: Greenfield
  • Permissions:
    • Create/Delete OTP: Policies.CanModifyStoreSettings
    • Get OTP status/QR: Policies.CanViewStoreSettings

Rate Limiting

  • Zone: SamRockProtocol
  • Default: 5 requests / minute with burst=3 per remote address

Endpoints

Base path: /api/v1/stores/{storeId}/samrock

  1. Create OTP

POST /api/v1/stores/{storeId}/samrock/otps

Headers:

Authorization: token <your-greenfield-token>
Content-Type: application/json

Body:

{
  "btc": true,
  "btcln": true,
  "lbtc": false,
  "expiresInSeconds": 300
}

Response 201:

{
  "otp": "<opaque-token>",
  "expiresAt": "2025-01-01T12:00:00Z",
  "setupUrl": "https://<btcpay>/plugins/<storeId>/samrock/protocol?setup=btc-chain,liquid-chain,btc-ln&otp=<OTP>"
}
  1. Get OTP Status

GET /api/v1/stores/{storeId}/samrock/otps/{otp}

Headers:

Authorization: token <your-greenfield-token>
Accept: application/json

Response 200:

{
  "otp": "<OTP>",
  "expiresAt": "2025-01-01T12:00:00Z",
  "setupUrl": "https://...",
  "status": "pending | success | error",
  "errorMessage": "optional"
}
  1. Get OTP QR (PNG or SVG)

GET /api/v1/stores/{storeId}/samrock/otps/{otp}/qr

Headers (choose one):

Authorization: token <your-greenfield-token>
Accept: image/png

or

Authorization: token <your-greenfield-token>
Accept: image/svg+xml

Response:

  • image/png — QR code PNG
  • image/svg+xml — QR code SVG
  1. Delete OTP

DELETE /api/v1/stores/{storeId}/samrock/otps/{otp}

Headers:

Authorization: token <your-greenfield-token>

Response 200 on success or if already consumed/expired.

cURL Examples

Create OTP:

curl -X POST \
  -H "Authorization: token $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"btc":true,"btcln":true,"lbtc":false,"expiresInSeconds":300}' \
  https://<btcpay>/api/v1/stores/<storeId>/samrock/otps

Get Status:

curl -H "Authorization: token $API_KEY" \
  https://<btcpay>/api/v1/stores/<storeId>/samrock/otps/<otp>

Get QR as SVG:

curl -H "Authorization: token $API_KEY" \
  -H "Accept: image/svg+xml" \
  https://<btcpay>/api/v1/stores/<storeId>/samrock/otps/<otp>/qr > otp.svg

Delete OTP:

curl -X DELETE \
  -H "Authorization: token $API_KEY" \
  https://<btcpay>/api/v1/stores/<storeId>/samrock/otps/<otp>

License

https://github.com/rockstardev/Aqua.BTCPayPlugin/blob/master/LICENSE