Skip to content

Spec rev 3.22: an optional amount in payment pushes and private pings - #20

Merged
gf5901 merged 2 commits into
mainfrom
push-amount
Nov 15, 2026
Merged

gf5901 merged 2 commits into
mainfrom
push-amount

Conversation

@gf5901

@gf5901 gf5901 commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

What and why

A wallet wants its payment alert to say "0.012 ZEC on its way". It can't fetch anything because of a push (spec §3.3), so the amount has to be in the push. Events in payment pushes and private pings now carry an optional amount.

Spec (§5.2, §6.3, changelog):

  • amount is in zatoshis (u64): the total the transaction pays the lease's keys, across all of its matching outputs. That fits because the server sends one push per transaction.
  • A missing amount means unknown, never zero. Servers that don't send it are still conformant.
  • It is a claim, like the event: wallets keep it unconfirmed until their own sync finds the transaction.
  • It appears only in pushes and pings. It isn't on spent events or in wake/events responses, which carry compact_tx for the wallet to decrypt itself. A webhook's amount is a different field: one output's value.
  • Why it's safe: the server already knows the amount from trial decryption and already sends it in webhooks. The ping stays 1024 bytes and RFC 8291-encrypted, so the gateway, Apple and Google learn nothing new.
  • New SHOULD in §6.3: wallets show the amount in a notification only if the user chose to, because it can be read on a locked screen.
  • private pings now hold one event per transaction, like the payment push. Before, they held one per output, and with per-transaction totals two events from the same transaction would count the money twice.

Code:

  • lz-proto: Event::amount uses #[serde(default, skip_serializing_if = "Option::is_none")], so older wallets and servers keep working (Event already ignores unknown fields). It is redacted from Debug.
  • Server: totals are computed per transaction when the matches are recorded and kept beside the stored event, in memory only. Stored events never carry amount, so events responses and webhook deliveries don't either (the webhook's flattened event leaves the key to the delivery's own field). Nothing logs it.
  • client/uniffi: Event.amount reaches Swift (UInt64?) and Kotlin (ULong?) through open_ping_b64.

Privacy checklist

  • No viewing key, token, or key-derived data can reach disk, logs, errors, metrics, or crash output. (tx_amount lives in the in-memory Stored record and is redacted from Debug.)
  • New secret-holding types redact Debug and zero on drop. (No new types. The new field is redacted in Event's hand-written Debug, and the uniffi Event's Debug already hides everything but rev/status.)
  • Scanning-mode and default-mode wallets still send the same requests, at the same times, at the same sizes. (No request changes.)
  • Push payloads carry nothing in the clear beyond the fixed ping. (Still 1024 bytes, RFC 8291-encrypted.)
  • No per-transaction chain lookups were added.
  • The spec (spec/v0.md) is updated if the wire format or a privacy property changed, and the test vectors are regenerated if needed. (Rev 3.22. No vector covers events, so none changed.)
  • Code touching keys or tokens has tests for the invariants above.
  • Nothing here is a secret, a real key, or a deployment detail.

Testing

  • scripts/check.sh (fmt, clippy, privacy guards, typos, cargo deny check, machete): pass.
  • cargo +stable test --workspace: pass.
  • cargo +1.89 check on the client-side crates (lz-proto, lz-client, lz-client-uniffi): pass. The full 1.89 test leg is left to CI because local disk is short.
  • client/uniffi/check-bindings.sh: Kotlin compiles, Swift typechecks.
  • Regtest not run; the chain follower and mempool code didn't change.

New tests:

  • lz-proto: amount optional both ways, Debug redaction, a webhook delivery serializes a single amount, the fullest private ping (4 events, u64::MAX amounts) fits, and a proptest that pings with any amounts fit the pad and parse back.
  • Server: block and mempool totals across Sapling, Orchard and Ironwood outputs, one ping event per transaction, events pages without amount, and end to end through the encrypted push (5,000 for one output, 14,000 for two outputs in one transaction) and the private ping.
  • Client core end to end: the opened payment push has amount, and the polled event doesn't.
  • uniffi: Ping::from carries amount, and its absence stays None.

🤖 Generated with Claude Code

gf5901 and others added 2 commits November 14, 2026 20:58
A wallet can't make a request because of a push (spec §3.3), so it had
nothing to show the amount from. Events in payment pushes and private
pings now carry `amount`: the total, in zatoshis, that the transaction
pays the lease's keys. Missing means unknown, never zero, and it is a
claim like the event. The server already learns it when it decrypts
the payment and already sends it in webhooks; the ping stays 1024
bytes and RFC 8291-encrypted.

- lz-proto: `Event::amount`, optional both ways, redacted from Debug;
  the fullest private ping (4 events, longest values) still fits.
- server: totals per transaction at record time, kept beside the event
  in memory only; stored events, `events` responses and webhooks don't
  carry it. Private pings now hold one event per transaction, like the
  payment push.
- client/uniffi: `Event.amount` reaches Swift (UInt64?) and Kotlin
  (ULong?) through `open_ping_b64`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- spec §5.2: say plainly which events carry no `amount`; note that it
  stays below 2.1 × 10^15, so double-based JSON parsers read it exactly;
  rewrap.
- lz-proto: name and describe the unknown-fields test for what it checks.
- client/uniffi README: Swift sees `nil`, not `null`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gf5901
gf5901 merged commit b02ebcc into main Nov 15, 2026
11 of 12 checks passed
@gf5901
gf5901 deleted the push-amount branch November 15, 2026 05:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant