1 User Guide

1.1 Learn

1.1.1 Features

Professional LNURL load balancing for your enterprise:

• CLN Lightning Node support with gRPC
• LND Lightning Node support with gRPC
• built on CloudFlare's Pingora Load Balancer
• Three balancing algorithms: Round Robin, Random and Consistent ( Ketama)
• Node health checks redirect invoice requests to healthy nodes
• Self-healing - if an unhealthy node transitions to healthy, it will automatically start taking invoice requests again
• Weighting can shift invoice requests to preferred nodes
• Liquidity biasing with inbound capacity checks will favor nodes most likely to accept payment
• Timed retries with exponential backoff for spurious node failures
• Partitions bind inbound invoice requests to subset of nodes
• Add nodes in seconds with REST Discovery API - new nodes will automatically start taking invoice requests
• Drop nodes in seconds with REST Discovery API - the balancer will safely direct invoices to remaining healthy nodes
• Publish new LNURLs in seconds with Offer API
• bech32 and QR code generation endpoints
• Sqlite, MySql and Postgres database support for both Discovery and Offer data stores
• Remote REST stores for both Discovery and Offer

1.1.2 Why Bitcoin Lightning Payments Fail

1.1.2.1 Single Points Of Failure

Failure with a standard LNURL service configuration is highly-probable:

1.1.2.2 No Liquidity Bias

Single LNURL + Lightning Node deployments make Liquidity Bias impossible. Liquidity bias deprioritizes nodes for invoice requests that have low inbound capacity, which make payment success unlikely.

1.1.2.3 External Load Balancer Resource Exhaustion

Load balancing multiple LNURL instances with a single fixed Lightning Node will exhaust resources:

• If a node fails, it makes the entire LNURL instance useless
• If a LNURL instance fails, it makes the Lightning Node unreachable
• Duplicating the entire LNURL instance just to attach it to a single Lightning Node raises cost, reducing feasibility of reaching scale
• High latency increases chances of catastrophic retry loop or flooding single node with failover requests

By contrast, every instance of Switchgear in a region can share the Lightning Node fleet, making scale feasible:

• A single Switchgear instance failure does not make a Lightning Node unreachable
• Any Lightning Node failure does not affect the uptime of a Switchgear instance
• Switchgear instances and the Lightning Node fleet size can scale independently, reducing cost
• Health checks are low latency, keeping Lightning Node status accurate
• Internal Backoff runs through entire Backend selection before returning 502 to external balancer, reducing latency and wallet retry cascade

The internal backoff can be entered under two conditions:

1. No healthy Lightning Nodes are available
2. A Lightning Node spurious failure or node failure between health checks

1.2 Feature Reference

1.2.1 Liquidity Bias

Optional Liquidity Bias will prioritize nodes with inbound capacity at the moment of selection. If no nodes are in range of the capacity bias, selection will fall back to standard weight selection.

1.2.1.1 Negative Capacity Bias example (restrictive):

lnurl-service:
  selection-capacity-bias: -0.2

Invoice request amount must be less than 20% of total inbound capacity of the node to be favored over other nodes that are not.

1.2.1.2 Positive Capacity Bias example (permissive):

lnurl-service:
  selection-capacity-bias: 0.1

Invoice request amount may be over inbound capacity by up to 10% of the node and still be favored over other nodes that are not.

1.2.1.3 Inbound Capacity Measurement

Capacity is measured in the same cycle as the Lightning Node health check. It is the sum of inbound capacity for all active channels on the node.

1.2.2 Partitioning

An organization may have a global Offer database. A Switchgear instance may be configured to serve a portion of that database, using partitions. Furthermore, every Lightning Node is configured in Discovery to be bound to one or more partitions, insuring payments only land on nodes they belong to.

Each Switchgear instance is configured for the partitions it will serve.

Example:

lnurl-service:
  partitions: [ "us", "it", "cr" ]

Only Offers created in "us", "it" or "cr" partitions will be available on the Switchgear instance, even if the Offer exists the database:

https://example.com/offers/us/{id} - 200 success
https://example.com/offers/it/{id} - 200 success 
https://example.com/offers/cr/{id} - 200 success
https://example.com/offers/ca/{id} - 404 not found

Each partition must have Discovery Backends configured for the invoice request to succeed. A single backend can serve multiple partitions.

See the Manage Lightning Node Backends with Discovery Service and Manage LNURLs with Offer Service sections for creating Discovery Backends and Offers with partitions.

1.2.3 Balancing Switchgear

Switchgear itself can be balanced. Balancing multiple switchgear instances within a region:

For multi-region Global Load Balancer deployment, use the full health check to signal to the downstream balancer that a Switchgear instance has no healthy Lightning Nodes:

https://{host}/health/full

The full health check will return 500 if no Lightning Nodes are available.

The regional balancer will forward the failing health status to the global balancer, which will send invoice requests to an alternate region:

Switchgear partitions have predictable URLs. Use partitions and a global Application Load Balancer to map invoice requests to alternate regions that have Switchgear instances configured for the requested partition.

1.2.4 LNURL Service

The OpenAPI LNURL Service specification: doc/lnurl-service-openapi.yaml.

The LNURL Service is public facing, and implements the LNURL LUD-06 specification.

See the Manage LNURLs with Offer Service section for complete service manual.

All Switchgear LNURLs are formatted as:

https://{host}/offers/{partition}/{id}

Where:

• partition - the Offer partition
• id - the Offer id (Uuid)

The returned callback is always the LNURL, with the postfix /invoice :

https://{host}/offers/{partition}/{id}/invoice

The bech32 and QR variants are available with:

https://{host}/offers/{partition}/{id}/bech32

And:

https://{host}/offers/{partition}/{id}/bech32/qr

The QR image is in PNG format.

1.2.4.1 Consistent Backend-Selection

Consistent uses the optional LNURL comment query parameter as a hash key, which guarantees the same node will always receive invoice requests for that key. The balancer will move on to the next closest key match if the node becomes unavailable. This is a specific use-case that provides optimized HTLC settlement between cooperating peers for high-frequency transactions.

1.2.5 Discovery Service

The OpenAPI Discovery Service specification: doc/discovery-service-openapi.yaml.

The Discovery Service is an administrative service used to manage connections to individual Lightning Nodes.

The service is isolated from the LNURL Service and can be configured to run on any port. The service supports TLS. Access is protected by a bearer token. Do not run this service without TLS enabled if it is exposed to the public internet.

See the Manage Lightning Node Backends with Discovery Service section for complete service manual.

1.2.6 Offer Service

The OpenAPI Offer Service specification: doc/offer-service-openapi.yaml.

The Offer Service is an administrative service used to manage Offers, which are used to generate LNURLs.

The service is isolated from the LNURL Service and can be configured to run on any port. The service supports TLS. Access is protected by a bearer token. Do not run this service without TLS enabled if it is exposed to the public internet.

See the Manage LNURLs with Offer Service section for complete service manual.