Lightning

Local mock mode

The fastest local setup is Lightning mock mode:

cd froglet && ./scripts/setup-payment.sh lightning

That writes .froglet/payment/lightning.env with:

FROGLET_PAYMENT_BACKEND=lightning
FROGLET_LIGHTNING_MODE=mock

Verification for mock mode is local-only because no external wallet is required.

LND REST mode

When you want a real wallet-backed probe, switch to lnd_rest:

FROGLET_LIGHTNING_MODE=lnd_rest \
FROGLET_LIGHTNING_REST_URL=https://your-lnd.example:8080 \
FROGLET_LIGHTNING_MACAROON_PATH=/path/to/admin.macaroon \
FROGLET_LIGHTNING_TLS_CERT_PATH=/path/to/tls.cert \
cd froglet && ./scripts/setup-payment.sh lightning --mode lnd_rest

Required inputs:

• FROGLET_LIGHTNING_REST_URL
• FROGLET_LIGHTNING_MACAROON_PATH pointing to the raw downloaded macaroon file
• FROGLET_LIGHTNING_TLS_CERT_PATH for https:// endpoints

The verification probe calls GET /v1/getinfo on the configured LND REST endpoint with the provided macaroon.

For Docker deployments, the entrypoint also accepts base64 inputs:

FROGLET_LIGHTNING_MACAROON_B64="$(base64 < /path/to/admin.macaroon | tr -d '\n')" \
FROGLET_LIGHTNING_TLS_CERT_B64="$(base64 < /path/to/tls.cert | tr -d '\n')" \
docker run ...

The container decodes those values into private files and sets the matching *_PATH variables before starting froglet-node.

phoenixd mode (self-custodial, prepaid)

phoenixd is ACINQ’s self-custodial Lightning daemon: a single binary with automatic liquidity (pay-to-open / splicing — no channel management, no inbound-liquidity setup) and a small HTTP Basic-auth API. It is the easiest self-custodial Lightning path.

# 1. Run phoenixd once; it generates a BIP39 seed and an http-password.
phoenixd
# 2. Read the http-password it wrote:
cat ~/.phoenix/phoenix.conf   # look for http-password=...
# 3. Point Froglet at it:
FROGLET_LIGHTNING_MODE=phoenixd \
FROGLET_LIGHTNING_PHOENIXD_URL=http://127.0.0.1:9740 \
FROGLET_LIGHTNING_PHOENIXD_HTTP_PASSWORD=<http-password> \
  ./scripts/setup-payment.sh lightning --mode phoenixd

The verification probe calls GET /getinfo (HTTP Basic auth) and checks for a nodeId.

Trade-off — prepaid, no escrow. Unlike LND mode, phoenixd cannot do hold-invoice escrow, so it uses the lightning.prepaid.v1 method: the buyer pays the full price upfront, before execution. On failure there is no automatic refund — the signed failed receipt is the buyer’s cryptographic evidence. In return you get dead-simple self-custodial Lightning, and the receipt still carries the payment preimage as a cryptographic proof of payment (sha256(preimage) == payment_hash) — stronger than Stripe’s attested model. To buy services this way, configure FROGLET_LIGHTNING_BUYER_PHOENIXD_URL + _HTTP_PASSWORD so your node can pay the provider’s invoice.

Non-loopback (remote, real-funds) phoenixd URLs require an explicit FROGLET_LIGHTNING_PHOENIXD_MAINNET_CONFIRM=1 opt-in.

Choose LND mode instead if you need pay-on-success escrow.

Runtime behavior

Lightning offers two self-hostable settlement tiers:

• LND (lnd_rest) — hold-invoice escrow (lightning.base_fee_plus_success_fee.v1): prepare reserves the deal through the invoice-bundle flow, commit settles the success leg, release cancels or expires the pending hold. The success fee is captured only when the work succeeds.
• phoenixd — prepaid (lightning.prepaid.v1): the provider mints an ordinary invoice at deal creation, the buyer pays it, and the provider confirms payment before executing. No escrow; the preimage is the proof of payment.

More on the artifact model: Settlement (Lightning)