Lantern ZeroGitHub

For wallet developers

Add Lantern Zero to your wallet

Your users get faster sync and payment alerts. You keep control of your push credentials, and their spending keys never leave the device.

Read the protocol specTalk to us on GitHub

Status: the protocol is a v0 draft and the server is a prototype. No wallet ships Lantern Zero yet, and the spec may still change. Now is the best time to tell us what your wallet needs.

What you build

  1. Accept a connection URL by paste and by QR scan, like a custom server address.
  2. Register the device for wake-ups through your push gateway.
  3. On each wake, send one request, then sync new blocks as your wallet already does.
  4. Optionally, offer scanning: show the consent screen, then lend an incoming viewing key and use the hint list to scan the right blocks first.

A Rust client library with Swift and Kotlin bindings will handle Oblivious HTTP, registration, lease renewal, hints and long-polling for you. It's in progress in the public repository.

The connection URL

Users connect with one URL, the same for hosted, self-hosted and wallet-sponsored servers:

lanternzero://<host>#lzt_…

  • The account token is in the fragment. Strip it before using the address, never log it, store it in the platform keychain, and show only its last four characters.
  • Don't rely on being opened by lanternzero:// links: any app can claim that scheme. Use universal links or app links on an https URL instead.

Your push gateway

Only you hold your APNs and FCM credentials. The Lantern Zero server sends each ping to your gateway as a standard Web Push request, encrypted to the device and signed with the server's key, so your gateway and Apple or Google see only timing.

  • Run the reference gateway from the public repository (in progress), or
  • have us host one for you. Pricing isn't set yet.

Accept pings only from server keys you trust, or rate-limit per key, so your gateway can't be used to send spam.

Sponsor your users

Pay for your users' accounts and pre-fill your own Lantern Zero URL, so they never paste one. Your app sells nothing: Apple's App Store rules don't allow unlocking features with cryptocurrency inside an app, so keep any purchase on the web.

What your wallet must do

Ask before lending a key

Show a consent screen before the first lease. Say that the operator, and anyone who breaches or compels it, can see incoming payments while the lease lasts; that with instant alerts, Apple or Google can see when payments arrive; and that a separate receiving account is recommended.

Use hints only to reorder your sync

Never fetch just the hinted heights from a light wallet server: that would show the server where your user's notes are. Scan the same full range as always, hinted ranges first.

Ship your own relay list

Choose at least two independent Oblivious HTTP relays, pick one at random for each request, and let users edit the list. Server operators, including us, must never choose relays for your users.

Keep alerts generic and missed wakes harmless

Never put amounts, memos or transaction IDs in text that Apple or Google relay; decrypt on the device. iOS throttles background pushes, so your wallet must work correctly when a wake is missed.

The full list is in section 6.3 of the protocol spec.