Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ bridge until Zcash's Tachyon upgrade changes how wallets find payments. Read
`README.md` first for the user-facing description.

**Status (2026-11-01): pre-alpha, phase 1 of 4: spec and prototype.** The
draft protocol spec is `spec/v0.md` (rev 3.20); `crates/lz-proto` holds the
draft protocol spec is `spec/v0.md` (rev 3.21); `crates/lz-proto` holds the
shared protocol types; `server/` is a prototype (OHTTP gateway, devices,
30-minute pings, chain follower, and the scanner with in-memory leases,
events, hints, and long-poll); `gateway/`, `client/core`, and the
Expand Down
40 changes: 37 additions & 3 deletions spec/relays.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,46 @@ A relay qualifies if it meets all of these:
| Relay URL | Operator and policy | Software | Key configuration (§3.2) | Refuses | Added |
| --- | --- | --- | --- | --- | --- |
| `https://relay.lanternzero.com` | Principle Zero Labs ([policy](https://lanternzero.com/relay)) | `lz-relay` | yes | `lanternzero.com` and every name under it, which includes the Lantern Zero hosted service | 2026-11-04 |
| `https://relay.oblivious.network/<relay name>`, one per server, set up by the wallet vendor (below) | Oblivious Network LLC ([privacy](https://oblivious.network/privacy); retention below) | hosted service | yes | none | 2026-11-06 |

**Refuses** lists the servers a relay won't carry, usually because its
operator runs them (spec §1.1 forbids using those anyway). Wallets pick
each server's relays from the ones that don't refuse it. Today that leaves one relay for self-hosted servers and none for
servers under `lanternzero.com`, so this list isn't enough yet for the
two relays per server that spec §1.1 asks for.
each server's relays from the ones that don't refuse it. Today that leaves two relays for self-hosted servers, but only one
(Oblivious Network) for servers under `lanternzero.com`, so this list
isn't yet enough for those servers to have the two relays spec §1.1 asks
for.

## Notes on listed relays

### Oblivious Network

- **Setup.** It's a paid hosted service. Each relay URL forwards to one
gateway, so the wallet vendor creates a relay in its own account for
each server, with that server's gateway URL
(`https://<server>/.well-known/ohttp-gateway`). Raise **First Byte
Timeout** from its 15 s default to at least 35 s (spec §1.1).
- **Logging**, as Oblivious stated it to us on 2026-11-02 and 2026-11-05
(quoted with permission; their privacy page doesn't say this yet):
- It doesn't log client IP addresses.
- Per request, it logs the minute, the duration, the gateway URL, bytes
received and sent, the response status, and the relay region. The
region is one of about 20.
- These records are kept for about 90 days. Totals for billing are kept
indefinitely.
- Its relays run on Fly.io and Vultr by default. Those platforms may keep
their own logs under their own terms.
- **Headers.** Since 2026-11-05 it adds no headers that describe the
client (tested 2026-11-06). A client that sends `x-oblivious-debug: true`
turns region and connection headers back on for its own requests.
Wallets shouldn't send it.
- **Key configuration.** A GET with `Accept: application/ohttp-keys` is
forwarded (spec §3.2). Without that header, the relay answers 404 itself.
- **Quirks.**
- The relay drops query strings, so `?allowed_purposes` can't be fetched
through it. Wallets don't need it.
- Gateway error responses arrive with `Content-Type: message/ohttp-res`.
Clients should recognise an `ohttp-key` problem by its body; the client
core already does.

## Software

Expand Down
19 changes: 10 additions & 9 deletions spec/v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -1095,23 +1095,24 @@ below.
configurable is proposed in
[payjoin/rust-payjoin#2026](https://github.com/payjoin/rust-payjoin/pull/2026),
and would bring its existing operators. Still open: operators. Wallets
need relays from at least two independent operators (1.1), and
`spec/relays.md` lists one so far, which serves only servers its
operator doesn't run.
need relays from at least two independent operators (1.1).
`spec/relays.md` lists two: `relay.lanternzero.com`, which serves only
servers its operator doesn't run, and Oblivious Network (rev 3.21), a
hosted service that refuses none. That's enough for self-hosted servers,
but servers under `lanternzero.com` still have only one.
2. **Finality depth.** The default of 10 is a placeholder. Set it once
post-NU7 reorg behavior is known.
3. **Relay-added headers.** Oblivious Network adds `Region-Ingress`,
`Region-Egress`, and `Connection-Status` to forwarded requests (tested
2026-11-01). Servers ignore them (3.1). Oblivious says they were added
temporarily, for regional connection pools, and will be removed
(2026-11-02). Test again before listing the relay in `spec/relays.md`.
4. **Relays that fetch keys.** alpe's `ohttp-relay` (orelay.dev) serves key
3. **Relays that fetch keys.** alpe's `ohttp-relay` (orelay.dev) serves key
configurations by fetching `/.well-known/ohttp-configs` from the
gateway, not RFC 9540's `/.well-known/ohttp-gateway`. Propose the RFC
9540 path upstream rather than serving a second path.

## Changelog

- **2026-11-06, rev 3.21:** Oblivious Network added to `spec/relays.md`,
now that it no longer adds region or connection headers (tested
2026-11-06). Open question 3 (relay-added headers) is closed, and open
question 1 now counts two relays (9).
- **2026-11-04, rev 3.20:** relays that serve some servers and refuse
others; an operator that runs servers may run a relay for other
operators' servers if it refuses its own, and wallets never use a
Expand Down
Loading