Skip to content

v2.6.0 — Device WebSocket channel for Bolt Card taps

Choose a tag to compare

@AxelHamburch AxelHamburch released this 01 Sep 13:12
· 20 commits to main since this release

What's new since v2.5.4

Device WebSocket channel (v2.6.0)

Bolt Card taps previously reached the server via a fresh HTTPS POST per tap.
Some consumer routers fail new TLS connections in phases (any destination)
while established connections keep working in both directions — on such a
router the NFC payment failed exactly when the phase was bad, while QR
payments (which only ride the established core WebSocket) kept working.

New endpoint: /zapbox/api/v1/ws/nfc/{device_id} — a persistent WebSocket the
device sends events over. A tap now rides an established channel that was
opened once at boot and needs no fresh TLS connection.

  • {"event": "lnurlw", ...} from the device runs the same payment logic as
    the HTTP endpoint (extracted into a shared process_nfc_lnurlw())
  • The reply (lnurlw_result with status/detail/request_id) goes back on
    the same socket; handling runs in a spawned task so the channel stays
    responsive, replies are serialized per connection
  • The relay trigger on settlement still arrives via the core WebSocket
    (/api/v1/ws/{device_id}) exactly as for QR payments — server pings, the
    "No active ZapBox connections" check, and the PIN flow (pin_required via
    core WS, pin_submit via HTTPS) are all unchanged
  • The HTTP endpoint POST /zapbox/api/v1/nfc/{device_id} remains as fallback
    for older firmware and for when the channel is down — compatible in both
    directions

Compatibility

Component Required version
LNbits ≥ 1.4.0
ZapBox firmware any — older firmware keeps using the HTTP endpoint; the channel needs a firmware with serviceNfcWebSocket() (branch fix/network-stability or later)
Reverse proxy must pass WebSocket upgrades on /zapbox/... (usually already configured host-wide for /api/v1/ws/...)

Upgrade notes

No database migration. Uninstall the old extension in LNbits and install
v2.6.0 so the new module is loaded. Devices reconnect automatically; firmware
with channel support logs Device channel connected – taps use the persistent channel once the new endpoint is live.