Repository navigation
Spec rev 3.22: an optional amount in payment pushes and private pings - #20
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
privatepings now carry an optionalamount.Spec (§5.2, §6.3, changelog):
amountis 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.amountmeans unknown, never zero. Servers that don't send it are still conformant.spentevents or inwake/eventsresponses, which carrycompact_txfor the wallet to decrypt itself. A webhook'samountis a different field: one output's value.privatepings 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::amountuses#[serde(default, skip_serializing_if = "Option::is_none")], so older wallets and servers keep working (Eventalready ignores unknown fields). It is redacted fromDebug.amount, soeventsresponses 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.amountreaches Swift (UInt64?) and Kotlin (ULong?) throughopen_ping_b64.Privacy checklist
tx_amountlives in the in-memoryStoredrecord and is redacted fromDebug.)Debugand zero on drop. (No new types. The new field is redacted inEvent's hand-writtenDebug, and the uniffiEvent'sDebugalready hides everything butrev/status.)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.)Testing
scripts/check.sh(fmt, clippy, privacy guards, typos,cargo deny check, machete): pass.cargo +stable test --workspace: pass.cargo +1.89 checkon 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.New tests:
amountoptional both ways, Debug redaction, a webhook delivery serializes a singleamount, the fullest private ping (4 events,u64::MAXamounts) fits, and a proptest that pings with any amounts fit the pad and parse back.eventspages withoutamount, 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.amount, and the polled event doesn't.Ping::fromcarriesamount, and its absence staysNone.🤖 Generated with Claude Code