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.21); `crates/lz-proto` holds the
draft protocol spec is `spec/v0.md` (rev 3.22); `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
5 changes: 4 additions & 1 deletion client/uniffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,10 @@ the binding layer can't enforce:
- **Never log requests or responses.** Over Tor the headers carry the
token and bodies may carry viewing keys.
- **One `wake` per scheduled ping, nothing after a payment push**, to any
service (spec §3.3). Show the alert from the ping itself.
service (spec §3.3). Show the alert from the ping itself. A ping
event's `amount` is the transaction's total in zatoshis (`null` or
`nil` when unknown, never 0), unconfirmed like the event. Show it only
if the user chose to, since it can appear on a locked screen.
- **Alerts are claims** (spec §6.3). An app that is not a wallet can never
confirm a payment: show every event as unconfirmed.
- **Persist `state()` after every call.**
Expand Down
7 changes: 7 additions & 0 deletions client/uniffi/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,11 @@ pub struct Event {
/// `CompactTx` protobuf bytes, base64url, to trial-decrypt on the
/// device. Absent in pings.
pub compact_tx: Option<String>,
/// Only in pings (spec §5.2): the total in zatoshis the transaction
/// pays the lease's keys. `None` means unknown, never zero. A claim
/// like the event: show it as unconfirmed until the wallet's own sync
/// finds the transaction.
pub amount: Option<u64>,
}

impl std::fmt::Debug for Event {
Expand Down Expand Up @@ -382,6 +387,7 @@ impl From<proto::Event> for Event {
height: e.height,
confirmations: e.confirmations,
compact_tx: e.compact_tx,
amount: e.amount,
}
}
}
Expand Down Expand Up @@ -869,6 +875,7 @@ impl Client {
height: event.height,
confirmations: event.confirmations,
compact_tx: None,
amount: None,
};
lock(&self.0).ack(&e)
}
Expand Down
18 changes: 18 additions & 0 deletions client/uniffi/tests/bindings.rs
Original file line number Diff line number Diff line change
Expand Up @@ -294,3 +294,21 @@ fn helpers() {
Err(LzError::PushDecrypt)
));
}

/// Spec §5.2: a ping event's `amount` reaches Swift and Kotlin, and its
/// absence stays unknown rather than zero.
#[test]
fn ping_events_carry_their_amount() {
let ping: lz_proto::api::Ping = serde_json::from_str(
r#"{"v":0,"t":"payment","events":[
{"id":"a","rev":1,"kind":"received","status":"mempool","height":null,"confirmations":0,"amount":1200000},
{"id":"b","rev":1,"kind":"received","status":"mempool","height":null,"confirmations":0}
]}"#,
)
.unwrap();
let ping = lz_client_uniffi::Ping::from(ping);
assert_eq!(ping.ping_type, lz_client_uniffi::PingType::Payment);
assert_eq!(ping.events[0].amount, Some(1_200_000));
assert_eq!(ping.events[1].amount, None);
assert!(!format!("{:?}", ping.events[0]).contains("1200000"));
}
81 changes: 79 additions & 2 deletions crates/lz-proto/src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,12 @@ pub struct Event {
/// `CompactTx` protobuf bytes, base64url. Omitted in push payloads.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub compact_tx: Option<String>,
/// In push payloads only (spec §5.2): the total in zatoshis that the
/// transaction pays the lease's keys. `None` means unknown, never
/// zero. A claim, like the event: unconfirmed until the wallet's own
/// sync finds the transaction.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub amount: Option<u64>,
}

impl std::fmt::Debug for Event {
Expand All @@ -191,6 +197,7 @@ impl std::fmt::Debug for Event {
"compact_tx",
&self.compact_tx.as_ref().map(|_| "<redacted>"),
)
.field("amount", &self.amount.map(|_| "<redacted>"))
.finish()
}
}
Expand All @@ -199,10 +206,14 @@ impl std::fmt::Debug for Event {
/// Derived from a key, so `Debug` hides the payment details.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WebhookDelivery {
/// The event without `compact_tx`, and with its `amount` left `None`:
/// the delivery's own `amount` below takes that key.
#[serde(flatten)]
pub event: Event,
pub txid: String,
pub pool: Pool,
/// This output's value in zatoshis (a push's `amount` is the whole
/// transaction's).
pub amount: u64,
/// The whole 512-byte memo field, unpadded base64url; read it as ZIP
/// 302 says. `None` when the server had no full ciphertext for it.
Expand Down Expand Up @@ -328,6 +339,7 @@ mod tests {
height: None,
confirmations: 0,
compact_tx: None,
amount: None,
}
}

Expand All @@ -340,6 +352,54 @@ mod tests {
assert!(dbg.contains("redacted"));
}

#[test]
fn event_debug_redacts_amount() {
let mut e = event();
e.amount = Some(1_234_567);
let dbg = format!("{e:?}");
assert!(!dbg.contains("1234567"), "{dbg}");
assert!(dbg.contains("redacted"));
}

/// Spec §5.2: `amount` is optional both ways. Absent, it parses as
/// unknown (older servers), and it is left out when unknown, so older
/// wallets see the same bytes as before.
#[test]
fn amount_is_optional_on_the_wire() {
let old = r#"{"id":"x","rev":1,"kind":"received","status":"mempool","height":null,"confirmations":0}"#;
let e: Event = serde_json::from_str(old).unwrap();
assert_eq!(e.amount, None);
assert_eq!(serde_json::to_string(&e).unwrap(), old);
let with: Event = serde_json::from_str(
r#"{"id":"x","rev":1,"kind":"received","status":"mempool","height":null,"confirmations":0,"amount":1200000}"#,
)
.unwrap();
assert_eq!(with.amount, Some(1_200_000));
assert!(
serde_json::to_string(&with)
.unwrap()
.ends_with(r#","amount":1200000}"#)
);
let p: Ping = serde_json::from_str(&format!(
r#"{{"v":0,"t":"payment","events":[{}]}}"#,
serde_json::to_string(&with).unwrap()
))
.unwrap();
assert_eq!(p.events[0].amount, Some(1_200_000));
}

/// A field added after `amount` doesn't stop it parsing: `Event`
/// ignores fields it doesn't know, which is also how wallets built
/// before `amount` skip it.
#[test]
fn amount_parses_next_to_unknown_fields() {
let e: Event = serde_json::from_str(
r#"{"id":"x","rev":1,"kind":"received","status":"mined","height":3,"confirmations":1,"amount":5,"later":true}"#,
)
.unwrap();
assert_eq!(e.amount, Some(5));
}

#[test]
fn default_wake_matches_spec_shape() {
let w = WakeRequest {
Expand Down Expand Up @@ -376,6 +436,7 @@ mod tests {
height: Some(5),
confirmations: 1,
compact_tx: None,
amount: None,
},
txid: "aabbccdd".into(),
pool: Pool::Orchard,
Expand All @@ -392,6 +453,20 @@ mod tests {
assert!(!format!("{s:?}").contains("c2VjcmV0"));
}

/// A webhook delivery's `amount` is its own field and lands there, not
/// in the flattened event.
#[test]
fn webhook_amount_is_the_delivery_field() {
let d: WebhookDelivery = serde_json::from_str(
r#"{"id":"e","rev":1,"kind":"received","status":"mined","height":5,"confirmations":1,"txid":"ab","pool":"ironwood","amount":7,"memo":null}"#,
)
.unwrap();
assert_eq!(d.amount, 7);
assert_eq!(d.event.amount, None);
let json = serde_json::to_string(&d).unwrap();
assert_eq!(json.matches("\"amount\"").count(), 1, "{json}");
}

#[test]
fn ignores_unknown_fields() {
let r: EventsResponse =
Expand Down Expand Up @@ -422,15 +497,17 @@ mod tests {
assert!(len + 1024 <= REQUEST_SIZE, "wake body is {len} bytes");
}

/// Spec §5.1: a scheduled ping with the most `private` events still fits
/// the fixed ping size.
/// Spec §5.1, §5.2: a scheduled ping with the most `private` events,
/// each with the longest values (`amount` included), still fits the
/// fixed ping size.
#[test]
fn fullest_ping_fits_ping_size() {
let mut e = event();
e.status = EventStatus::Mined;
e.height = Some(u64::MAX);
e.confirmations = u32::MAX;
e.rev = u32::MAX;
e.amount = Some(u64::MAX);
let p = Ping {
v: 0,
t: PingType::Wake,
Expand Down
1 change: 1 addition & 0 deletions crates/lz-proto/src/webhook.rs
Original file line number Diff line number Diff line change
Expand Up @@ -296,6 +296,7 @@ mod tests {
height: Some(1),
confirmations: 1,
compact_tx: None,
amount: None,
},
txid: "ab".into(),
pool: crate::event_id::Pool::Sapling,
Expand Down
31 changes: 31 additions & 0 deletions crates/lz-proto/tests/properties.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

use std::collections::BTreeSet;

use lz_proto::api::{Event, EventKind, EventStatus, MAX_PING_EVENTS, Ping, PingType};
use lz_proto::hex;
use lz_proto::padding::{PING_SIZE, REQUEST_SIZE, pad_bhttp, pad_ping_json};
use lz_proto::replay::{SeqWindow, WINDOW, next_seq};
Expand Down Expand Up @@ -179,6 +180,36 @@ proptest! {
prop_assert_eq!(back, fields);
}

/// Spec §5.2: a ping with up to the most `private` events, any
/// heights, confirmations, and amounts (or none), fits the pad and
/// parses back to the same events.
#[test]
fn a_ping_with_amounts_fits_and_parses_back(
fields in proptest::collection::vec(
(any::<u32>(), any::<Option<u64>>(), any::<u32>(), any::<Option<u64>>(), any::<bool>()),
0..=MAX_PING_EVENTS,
),
) {
let events: Vec<Event> = fields
.into_iter()
.map(|(rev, height, confirmations, amount, mined)| Event {
id: "A".repeat(22),
rev,
kind: EventKind::Received,
status: if mined { EventStatus::Mined } else { EventStatus::Mempool },
height,
confirmations,
compact_tx: None,
amount,
})
.collect();
let ping = Ping { v: 0, t: PingType::Wake, events };
let padded = pad_ping_json(&serde_json::to_string(&ping).unwrap()).unwrap();
prop_assert_eq!(padded.len(), PING_SIZE);
let back: Ping = serde_json::from_slice(&padded).unwrap();
prop_assert_eq!(back, ping);
}

// --- Replay window (spec §3.4) ---

/// The window against a plain model: a `seq` is accepted exactly when
Expand Down
2 changes: 1 addition & 1 deletion server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ scanning also against real Zebra and Zaino on regtest
| `POST /v0/events` | §4.3 | Long-poll held until the server-wide release (new block, match, or reorg; at most one every 5 s) plus 0–2 s jitter, or 25–30 s; never early, even with events pending; `wait: 0` for `next` pages |
| Scanner | §4.4, §6.1 | Trial decryption of Sapling outputs and Orchard and Ironwood actions in compact blocks, for every active lease; deterministic event ids; `mined` → `reorged` → re-mined; confirmations up to the finality depth; events deleted on ack or after 7 days; expired leases swept every minute; catches up after falling behind |
| Mempool | §4.3, §6.1 | `GetMempoolStream`, reopened after each block; full transactions (v5 and v6) cut to `CompactTx` and trial-decrypted like blocks; matches are `mempool` events that become `mined` with the same id; a new lease is checked against the pending mempool, kept in compact form up to 64 MiB; an unknown branch id is logged, not fatal |
| Payment alerts | §5.2 | `instant`: an extra `Urgency: high` push when a payment is first seen (usually in the mempool, seconds after it was sent), one per transaction, at most 2 a minute per account; `private`: up to 4 events inside the scheduled ping, same 1024-byte size. Backfilled payments don't push |
| Payment alerts | §5.2 | `instant`: an extra `Urgency: high` push when a payment is first seen (usually in the mempool, seconds after it was sent), one per transaction, at most 2 a minute per account; `private`: up to 4 events (one per transaction) inside the scheduled ping, same 1024-byte size. Both carry the transaction's `amount`. Backfilled payments don't push |
| Webhooks | §4.5 | `PUT`/`DELETE /v0/webhook` on a scanning server; URL (https, at most 1024 bytes, no user info, SSRF rules) and `whsec_` secret kept in `state.json`. Every event delivered on each change, Standard Webhooks signed (`webhook-id` from the event's state), retried with backoff and jitter for 24 h; a final delivered event is deleted; `410` deletes the webhook; undelivered events are exempt from the event cap. Deliveries go out on each release and every 5 s |
| Replay protection | §3.4 | `Date` within 60 s, and a `Date` on every response so wallets can correct their clocks; `seq` windows per device, or per account for registration, rotation, and deletion; `409 stale-seq` with `min_seq` |
| Rate limits | §3.5 | Per account and per device, per minute; `429` with `Retry-After`, delivered inside OHTTP |
Expand Down
Loading
Loading