diff --git a/.github/workflows/kotlin-sdk-build.yml b/.github/workflows/kotlin-sdk-build.yml index 8919fd7b7dd..ba69afcddc6 100644 --- a/.github/workflows/kotlin-sdk-build.yml +++ b/.github/workflows/kotlin-sdk-build.yml @@ -18,7 +18,6 @@ on: - 'packages/*-contract/**' - 'packages/simple-signer/**' - 'docs/sdk/sdk-parity-manifest.json' - - 'docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md' - 'packages/kotlin-sdk/PARITY_SUMMARY.md' - 'scripts/check_sdk_parity_manifest.py' - 'scripts/tests/**' diff --git a/book/src/drive/document-count-trees.md b/book/src/drive/document-count-trees.md index 2a6ac5b1415..51b9717e985 100644 --- a/book/src/drive/document-count-trees.md +++ b/book/src/drive/document-count-trees.md @@ -393,6 +393,10 @@ A few notes about the index-level flag: A migration check from `dapi-grpc` server logic: every count query requires either `documentsCountable: true` (for unfiltered totals) or a `countable: true` / `rangeCountable: true` index whose properties **exactly match** the query's where-clause fields. No covering index → the call returns a clear `InvalidArgument` describing what the picker was looking for ("requires a `range_countable: true` index whose last property matches the range field" for range queries, "requires a countable index whose properties exactly match the where clause fields" for Equal/In queries). Pick your indexes deliberately at contract creation time — per-index `countable: true` / `rangeCountable: true` flags can't be added later (contract indexes are immutable post-creation). +### Counts Are Public + +Anyone can run a count query and verify its proof, so a countable index publishes everything its counts reveal. Encrypting a document's fields does not hide its existence or its indexed values. A countable index keyed first by a recipient and then by the document owner answers "who sent documents to this recipient, and how many" for every recipient. On the DashPay `contactRequest` type, a countable `[toUserId, $ownerId]` index would publish every user's inbound contacts. If a UI only needs a badge, a countable index on the recipient alone (`["toUserId"]`) reveals a total and no per-sender edges. + ## SDK Access at Three Layers ### `rs-sdk` (native Rust) diff --git a/docs/dashpay/BLOCK_SPEC.md b/docs/dashpay/BLOCK_SPEC.md deleted file mode 100644 index 9770ea01b13..00000000000 --- a/docs/dashpay/BLOCK_SPEC.md +++ /dev/null @@ -1,107 +0,0 @@ -# DashPay ignore — cross-device design + DoS / social-graph-leak analysis - -Status: the single-device **"Block sender"** design this file originally carried was -**superseded** by the shipped local-only **Ignore** (per-sender, reversible; -`ignored_senders`, `ignore_sender`/`unignore_sender`, applied in `changeset/apply.rs`). -That feature is documented in `SPEC.md` (G5) and `SYNC_CORRECTNESS_SPEC.md`; the -single-device Block design — its state/persistence/UI/test plan and the review -resolutions specific to it — is no longer reproduced here. - -This file is retained **only** for the two forward-looking pieces Ignore does not yet -cover: - -- **(a) Cross-device ignore** — how to make ignore sync across a user's devices via a - single owner-scoped, self-encrypted blocklist, and the privacy reason it is **not** - carried via `contactInfo` (§1). -- **(b) DoS / social-graph-leak analysis** — the fetch-cost / flood analysis and the - countable-index social-graph leak that any query-level DoS filter must avoid (§2). - -Owner: platform-wallet / swift-sdk. -Relates to: `SPEC.md` (G5, the shipped Ignore), `SYNC_CORRECTNESS_SPEC.md`, -`CONTACTINFO_FORMAT_SPEC.md`. - ---- - -## 1. Cross-device ignore — a self-encrypted blocklist, NOT `contactInfo` - -Ignore is per-device local state today; you re-ignore a sender on each device. Making -it sync is a **future** item on the contract / governance track — not built. - -**Why not `contactInfo`.** The tempting reuse — carry an ignore flag in the -`contactInfo.privateData` blob we already sync — **breaks the DIP-15 ≥2-contacts -unlinkability gate** and is rejected. An ignore targets a *non-established* sender, so -carrying it would mean creating a `contactInfo` **about a non-contact**. That document's -public existence + `$createdAt` correlates with the inbound `contactRequest` (via the -public `userIdCreatedAt` index) to re-identify *who* you ignored: `encToUserId` is -encrypted so *who* is hidden, but the doc's *existence/count* is not. The -"`displayHidden` is precedent" argument is a false equivalence — `displayHidden` rides a -document that exists anyway (an established contact), whereas an ignore-of-a-non-contact -*creates* the leaking document. It is also mechanically blocked today: -`set_contact_info_with_external_signer` → `set_contact_metadata` hard-requires an -established contact, and the apply side drops non-established `contactInfo`. - -**The design if it ships.** A **single owner-scoped, self-encrypted blocklist -document** — one document the owner encrypts to themselves (same key family as -`contactInfo`'s `privateData`, but a single owner-private list, not per-contact and not -gated by the 2-contact rule). Every device reads and applies it, so ignore (and -optionally decline) apply everywhere. Costs: each edit is a document write (credits); -it reveals only *that* a blocklist exists plus an edit count — **not** one document per -ignored victim. Its update timing should be conflated with normal profile edits so it -does not leak the per-sender existence/count. This is a contract change on the later -governance track, and the metadata-leak analysis above must be settled before building -it. - -## 2. DoS / spam, and the social-graph leak a countable index would create - -### 2.1 Fetch model, and why an ignore can't cut fetch cost - -The received-request query is keyed by recipient: - -``` -where toUserId == me, order_by $createdAt, limit: 100 -``` - -An ignore is a **local read-filter applied after fetch**: the index has no -`sender NOT IN (…)` axis and Sybil senders are unpredictable, so an ignore cannot avoid -the fetch + GroveDB proof-verify cost of an incoming request — it only hides it once -fetched. - -**Threat: a sender (or a funded Sybil swarm) creates many requests.** Invalid ones are -the worst — they fail parse/validation but still cost fetch + proof-verify + parse. The -only built-in deterrent is **economic**: each `contactRequest` costs the sender -platform credits. Spam isn't free, but it isn't prevented. A naive `limit: 100, -start: None` re-fetch also lets a flood of ≥100 junk requests **bury** legitimate ones -past the first page. - -**Mitigation — incremental fetch (high-water).** Track the newest `$createdAt` seen per -identity and query `WHERE toUserId == me AND $createdAt > high_water`, paginating -forward: each request is fetched exactly once, pagination can't bury legit requests past -100, and ignore/decline become one-time-on-first-sight. This bounds steady-state work to -O(new requests per sweep). It does **not** stop the *first* fetch of a request from a new -sender (impossible without server-side sender exclusion), but nothing in the protocol -can. The existing `userIdCreatedAt` index `[toUserId, $createdAt]` already serves this -range-after-equality query, so incremental fetch needs **no** contract change. *(This -high-water incremental fetch has since shipped — see `SYNC_CORRECTNESS_SPEC.md` and the -DIP-15 §8.8/§8.12 row in `DIP_CONFORMANCE_GAPS.md`.)* - -### 2.2 The trap: a countable `[toUserId, $ownerId]` index leaks the inbound social graph - -A natural-looking next step is a **countable** index on the recipient→sender axis so the -wallet can answer "how many pending requests do I have" / "is one sender flooding me" -from a count proof **without fetching documents**: - -``` -byRecipientSender = [{ toUserId: asc }, { $ownerId: asc }] // countable — DO NOT ship as drafted -``` - -(The `$ownerId` of a `contactRequest` *is* the sender.) This is a **social-graph leak** -and must not ship in that form. Platform count / group-by proofs are **public, not -recipient-private**, and return cleartext `{sender_id → count}`. A countable -`[toUserId, $ownerId]` therefore lets *anyone* scrape "who contacted recipient R, with -counts" in O(log n) — the inbound social graph, in the clear. - -**Resolution:** drop the per-sender `GROUP BY $ownerId` axis. At most keep an aggregate -`COUNT(*) WHERE toUserId == me` (a single number, for a pending-request badge), which -reveals only a total and not per-sender edges. Any real query-level DoS filter that -excludes ignored/rejected senders *before* fetching is a contract change (DIP / -maintainer coordination), and this graph-exposure analysis must be carried into that DIP. diff --git a/docs/dashpay/CONTACTINFO_FORMAT_SPEC.md b/docs/dashpay/CONTACTINFO_FORMAT_SPEC.md deleted file mode 100644 index 0ea08e454cc..00000000000 --- a/docs/dashpay/CONTACTINFO_FORMAT_SPEC.md +++ /dev/null @@ -1,306 +0,0 @@ -# contactInfo `privateData` — DIP-15 varint format (migrate off CBOR) - -Status: **IMPLEMENTED** (2026-06-18) — DIP-15 varint codec in `crypto/contact_info.rs`, -byte-vector + compat tests. (The tolerant minor-version decode stays available for a -future additive field, but **ignore state does NOT ride contactInfo** — R1 found -that leaks who you ignored; ignore is local-only, cross-device via a future encrypted -profile field. See the R1 item in the backlog, dashpay/platform#4020.) -Owner: platform-wallet / platform-encryption -Relates to: Spec 2 (Ignore, adds `relationshipState`), `BLOCK_SPEC.md`, -`CONTACTINFO_FORMAT_SPEC.md` Appendix A. - -## Format decision: DIP-15 varint, NOT CBOR (2026-06-18) - -`contactInfo.privateData` is an **opaque encrypted byteArray** — the registered -contract validates only its **length** (`byteArray:true, minItems:48, -maxItems:2048` in `dashpay.schema.json`); the field description's "…encoded as an -array in cbor" is **advisory documentation, not a structural constraint**. The -plaintext inside the AES-256-CBC ciphertext is therefore a writer/reader -convention we are free to choose — and we choose **DIP-15**, the authoritative -protocol spec, so we interop with DIP-15-compliant clients (the reference -`dash-wallet` / `kotlin-platform` will follow the DIP when it implements -contactInfo). **No contract change is needed** (length-only validation accepts any -48..2048-byte ciphertext). No client decodes contactInfo today, so this is a free -window: we set the de-facto format and it matches the DIP. - -> An earlier pass briefly "reconciled" this the other way (keep CBOR, per the -> schema *description* + `CONTACTINFO_FORMAT_SPEC.md` Appendix A). That over-weighted an advisory -> description as binding. Corrected: the contract enforces length only, DIP-15 is -> authoritative — use varint. - -This is **Spec 1** of the DashPay-privacy track. (The minor-version forward-compat -seam — §3 — remains for any future additive field. Note: ignore state is **not** -carried here — R1 found a per-sender `contactInfo` leaks who you ignored, so ignore -is local-only with cross-device deferred to a future encrypted `profile` field.) - ---- - -## 1. Problem - -Our `contactInfo.privateData` codec (`crypto/contact_info.rs::encode/decode_private_data`) -emits a **CBOR array** `[aliasName, note, displayHidden, padding?]`. **DIP-15 -defines a different format** (verified against `github.com/dashpay/dips/dip-0015.md`, -§"Contact Info" / §"Encrypting Private Data"): - -- **Serialization:** "the private data should be serialized in the same way as - done for **Dash message data**" (dip-0015.md:811) — i.e. the Bitcoin/Dash - protocol binary format (var-int-length-prefixed strings/arrays), **not CBOR**. -- **Fields (v0), in order:** - | # | Field | Type | Encoding | - |---|-------|------|----------| - | 0 | `version` | uInt32 | `major << 16 \| minor` (dip-0015.md:771) | - | 1 | `aliasName` | String | var-int length + UTF-8 | - | 2 | `note` | String | var-int length + UTF-8 | - | 3 | `displayHidden` | uInt8 | 1 byte | - | 4 | `acceptedAccounts` | array | var-int count + u32s (dip-0015.md:805) | -- **Crypto:** AES-256-CBC with the `rootEncryptionKey/(2^16+1)'/idx'` derived key - (we already do this — only the *plaintext serialization* changes). - -**Our gaps vs DIP-15:** (a) CBOR instead of Dash-message varint; (b) **no -`version` field**; (c) **no `acceptedAccounts`**. - -**Why now (the one cheap window):** verified 2026-06 that **no client decodes -`contactInfo.privateData` today** — `android-dashpay` has no `ContactInfo` class -(the schema is bundled as JSON only); `dash-wallet` has only a `// TODO: choose -the contactRequest based on the ContactInfo.accountRef value`. So there is **no -reader to break.** When `dash-wallet` implements its TODO it will follow DIP-15 -(varint), not our CBOR — so if we don't align now, the two clients won't interop. -We're the only writer; fix the wire format while it's free. - -## 2. Goal - -- Replace the CBOR codec with the **DIP-15 Dash-message varint** serialization, - including the `version` field and `acceptedAccounts`. -- Adopt DIP-15's **major/minor version forward-compat** model. -- **Define** (not yet populate) `reject` / `block` fields as a **minor-version - extension**, so a later spec can sync reject/block via contactInfo without - another format change. -- No behavior change to alias/note/hidden; pure wire-format + versioning. - -## 3. DIP-15 versioning model (verbatim, because it drives everything) - -dip-0015.md:771-776: `version = major << 16 | minor`. -- **Major** change = **incompatible**: a client that doesn't understand the major - version **discards the whole contactInfo**. -- **Minor** change = "most likely additional fields": an un-updated client - "should still be able to parse the first fields … and **ignore data past the - final field known in the version**." - -Consequence (this answers the "won't old clients break?" question): **adding -`reject`/`block` is a MINOR bump** → a DIP-15-v0 reader parses `version … -acceptedAccounts` and ignores our trailing fields. **No breakage.** Only a major -bump locks old readers out. So: -- our baseline = **major 0, minor 0** (DIP-15 v0 fields exactly); -- our reject/block extension = **major 0, minor 1** (appended fields); -- decoders MUST be **tolerant**: read the fields the known minor defines, ignore - trailing bytes; on an unknown **major**, discard. - -## 4. The reject/block fields — DEFINED but NOT ADOPTED (R1, resolved 2026-06-18) - -> **Resolution.** This field was the proposed cross-device carrier for -> reject/block. It is **not implemented** and is **not part of the shipped DIP-15 -> codec** (which carries only `aliasName` / `note` / `displayHidden` / -> `acceptedAccounts`). Per R1, a `contactInfo` about a *non-established* sender -> leaks *who* you ignored (the timing-correlation argument below), so **Ignore is -> local-only** (Spec 2) and cross-device sync is deferred to a future **encrypted -> field on the `profile` document** (contract / governance track) — NOT to -> `contactInfo`. The design below is retained for reference only. - -Appended after `acceptedAccounts`, present from **minor 1** (design only — unused): - -| # | Field | Type | Meaning | -|---|-------|------|---------| -| 5 | `relationshipState` | uInt8 | 0 = active, 1 = declined, 2 = blocked (extensible) | - -Rationale for a single `relationshipState` byte over two bools: declined/blocked -are mutually-exclusive states of one relationship; one enum is smaller, avoids -the "both set" ambiguity, and extends cleanly (e.g. 3 = muted). `displayHidden` -(field 3) stays as-is for backward DIP-15 compat; `relationshipState` is the -richer superset we read first when present. - -**Scope boundary (critical):** this spec only **defined** the field + its -encoding. *Whether and how* a `contactInfo` is created to carry it — especially -for a **non-established** declined/blocked sender — was the **privacy question -(R1 from the block review)**, **RESOLVED (2026-06-18): not via `contactInfo` at -all.** Ignore is local-only (Spec 2); cross-device goes through an encrypted -`profile` field later. Kept for context: - -> A `contactInfo` *about a non-contact* is a brand-new on-chain document whose -> existence + `$createdAt` can be timing-correlated with the inbound -> `contactRequest` (public `userIdCreatedAt` index) to re-identify *who* you -> blocked — even though `encToUserId` is encrypted, and the ≥2-contacts gate -> (dip-0015.md:697-699) can't cover a non-contact. **Spec 2 resolved this: a -> per-sender `contactInfo` is leaky (above) and even a single owner-scoped list -> on `contactInfo` still signals "an ignore happened", so ignore is kept -> local-only and cross-device is deferred to an encrypted `profile` field whose -> update timing is conflated with ordinary profile edits.** This format spec is agnostic to that -> choice — it just provides the field. - -## 5. Padding / 48-byte floor - -The contract validates `privateData` at **48–2048 bytes** (dip-0015.md:727). -Our CBOR codec appends a padding element to reach 48; the Dash-message format has -no field for that, and trailing padding would collide with the "ignore data past -the final known field" rule (a future reader could mis-read padding as a higher- -minor field). **Decision needed (Q-pad):** -- (a) Pad the **ciphertext region** only — encode the exact fields, then rely on a - reserved **`padding` length-prefixed byte field** placed *last in every minor* - and documented as "ignore"; or -- (b) define the floor purely as an encryption-layer concern (pad plaintext to ≥ - the size that yields 48-byte ciphertext, inside AES-CBC, with the pad length - recoverable) so the field stream itself carries no padding. -Recommend **(a) an explicit trailing `padding` var-bytes field** that is *always -the final field* and always skipped — it's self-describing (var-int length) so -"ignore trailing" still works, and it's the closest analog to today's behavior. - -## 6. Migration / compatibility of *existing* data - -contactInfo docs are immutable on-chain. Any docs **we** already wrote (CBOR, -no version field) become unreadable by the new varint decoder. -- DashPay is **pre-release** (not on mainnet); existing CBOR docs are - testnet/devnet UAT artifacts → **acceptable to abandon** (they'll simply fail - to decode and be skipped, same as a foreign-root doc today). -- Do **not** build a CBOR↔varint dual-reader unless we find we must preserve - specific test data. (Open question Q-dual.) -- The **local** SwiftData/SQLite mirror is rebuilt from chain on sync, so no - local migration is needed beyond the decoder swap. - -## 7. Implementation surface - -- `packages/rs-platform-wallet/src/wallet/identity/crypto/contact_info.rs`: - rewrite `encode_private_data` / `decode_private_data` to the Dash-message varint - format (var-int string/array helpers; `version` first; tolerant decode that - stops at the known-minor field count and skips trailing). Keep the AES-CBC layer. -- `ContactInfoPrivateData` struct: add `version: u32` (or major/minor accessors), - `accepted_accounts: Vec`, and `relationship_state: u8` (minor ≥ 1). - `displayHidden` stays. (Note: the in-memory struct already flows through - `set_contact_metadata(ContactInfoPrivateData)` after the recent refactor.) -- No FFI/Swift signature change (privateData is opaque bytes across the boundary); - only the bytes' internal layout changes. - -## 8. Test plan - -- **Round-trip:** encode→decode every field incl. empty/None strings, empty and - non-empty `acceptedAccounts`, `relationshipState` 0/1/2. -- **Forward-compat:** a **minor-0** decoder reading **minor-1** bytes parses - v0 fields and ignores `relationshipState` (the DIP-15 guarantee) — pin it. -- **Major-incompat:** a decoder reading an unknown **major** discards (returns - None / skips), not a partial parse. -- **Vector:** if any DIP-15 / reference test vector for privateData exists, match - it byte-for-byte (none found in dashj/android-dashpay; we may be authoring the - first — note that). -- **Floor:** encoded output is ≥ 48 bytes after padding (Q-pad), ≤ 2048. - -## 9. Open decisions - -- **Q-pad** — explicit trailing `padding` field (recommended) vs encryption-layer - padding. -- **Q-dual** — abandon existing CBOR docs (recommended, pre-release) vs build a - CBOR/varint dual-reader. -- **Q-state** — single `relationshipState: uInt8` (recommended) vs separate - `declined`/`blocked` flags. -- **Q-minor-now** — define `relationshipState` (minor 1) in *this* spec/PR, or - ship the pure DIP-15-v0 alignment first (minor 0) and add the field in Spec 2? - (Leaning: ship v0 alignment here; add the field in Spec 2 where it's used — - keeps this PR a clean wire-format fix.) - ---- - - - -## Appendix A — contactInfo wire conventions (research, 2026-06-12) - -Source-verified findings for implementing the DashPay `contactInfo` -document (M3 task 13). Full citations at the bottom. - -### Decisive finding: no reference client implements contactInfo - -DashSync-iOS (`DSBlockchainIdentity.m` + Identity models), dashj / -android-dpp / kotlin-platform, and dash-shared-core contain **zero** -contactInfo creation or encryption code. DIP-15 + the deployed -dashpay-contract schema are the only authoritative sources, and **this -repo's implementation sets the de-facto wire convention.** There is no -cross-client byte-compatibility constraint — only self-consistency and -schema validity. - -### Conventions adopted (CONFIRMED unless marked INFERRED) - -#### Key derivation (DIP-15) - -The "root encryption key" is the identity's **registered ENCRYPTION -key** (DIP-11 purpose 1); `rootEncryptionKeyIndex` is that key's id on -the identity. Two child keys are derived from its extended form in the -owner's HD tree (hardened CKDpriv): - -```text -encToUserId key: rootEncryptionKey / 65536' / derivationEncryptionKeyIndex' (2^16) -privateData key: rootEncryptionKey / 65537' / derivationEncryptionKeyIndex' (2^16 + 1) -``` - -The 2^16 offset is DIP-15's explicit "discount other potential -derivations" choice. The AES-256 key is the raw 32-byte child private -key scalar (INFERRED — no hash step is specified anywhere; matches how -contactRequest ECDH consumes key material). - -`derivationEncryptionKeyIndex` is sequential per `$ownerId` starting at -0 (one per contactInfo document; the unique index is -`($ownerId, rootEncryptionKeyIndex, derivationEncryptionKeyIndex)`). - -#### encToUserId (DIP-15, verbatim justification in the DIP) - -`AES-256-ECB(toUserId)` — exactly 32 bytes = two blocks, **no IV, no -padding**. ECB is sound here because the plaintext is itself a SHA-256 -output and the key is never reused for other purposes. - -#### privateData - -> **CORRECTION (2026-06-18): use DIP-15 varint, not CBOR.** The conclusion -> below ("the deployed schema description wins → CBOR") over-weighted an -> advisory note. The contract validates `privateData` by **length only** -> (`byteArray`, 48–2048); its "array in cbor" text is documentation, NOT an -> enforced structural constraint. The encrypted plaintext format is a free -> writer/reader convention, so we follow **DIP-15** (the authoritative protocol -> spec) with `version`/varstr/`acceptedAccounts`. See the spec above. - -`IV(16) ‖ AES-256-CBC(plaintext)` — IV prepended (INFERRED from the -`encryptedPublicKey` convention; DIP-15 doesn't state placement for -this field). - -Plaintext (~~CBOR~~ → **DIP-15 varint**, per the correction above): the original -analysis adopted a **CBOR array `[aliasName, note, displayHidden]`** per the -deployed schema's field description — positional, with CBOR `null` for absent -strings (INFERRED). DIP-15 prose instead describes Bitcoin-varint "Dash message -data" with `version` + `acceptedAccounts` — and that is what we now use (the -schema enforces length only, so there's no conflict and no contract change). - -#### Privacy rule (DIP-15, spec-only — no client enforces it today) - -> "A client should not transmit a contact info document for a user to -> the network until that user has at least two established contacts." - -Enforced at the publish gate: with <2 established contacts the local -state still updates; the document write is deferred until the rule is -satisfied. - -### Discrepancy table (DIP-15 prose vs deployed schema) - -| Question | DIP-15 prose | Deployed schema | -|---|---|---| -| Plaintext format | Bitcoin varint stream | CBOR array | -| Fields | version, aliasName, note, displayHidden, acceptedAccounts | aliasName, note, displayHidden | -| version | uInt32 present | absent | -| acceptedAccounts | array of uInt32 | absent | - -### Sources - -- DIP-0015 (dashpay/dips) — derivation offsets, ECB/CBC modes, privacy rule -- dashpay-contract `schema/v1/dashpay.schema.json` — CBOR-array description, - unique index, 48–2048B bounds -- DIP-0011 (key purposes), DIP-0013 (identity key paths), DIP-0009 - assignments (15'/16' are incoming-funds / auto-accept — no contactInfo path) -- dashsync-iOS Identity models, android-dpp, kotlin-platform, - dash-shared-core — checked: no contactInfo implementation anywhere -- rs-dpp `lib.rs` `RootEncryptionKeyIndex` / `DerivationEncryptionKeyIndex` - type aliases diff --git a/docs/dashpay/DASHPAY_STATE_ENCAPSULATION_SPEC.md b/docs/dashpay/DASHPAY_STATE_ENCAPSULATION_SPEC.md deleted file mode 100644 index 072b95d1024..00000000000 --- a/docs/dashpay/DASHPAY_STATE_ENCAPSULATION_SPEC.md +++ /dev/null @@ -1,463 +0,0 @@ -# DashPay State Encapsulation — extract `ManagedIdentity`'s DashPay fields into `DashPayState` - -Status: draft, rev 2 (review must-fixes folded) -Scope: `packages/rs-platform-wallet` (+ mechanical re-paths in `rs-platform-wallet-ffi`; -test-helper construction in `rs-platform-wallet-storage`). No on-disk format change, no FFI -ABI change, no Swift change. Follow-up to PR #3841 — lands as its own PR after #3841 merges. - -Origin: review question on PR #3841 — "Having dashpay stuff right in identity wallet and -identity manager and managed identity is mixing too much different stuff… shall we have a -separate dashpaywallet and somehow encapsulate dashpay stuff from common identity things?" - -> **Review outcome (rev 2).** Four independent reviewers (feasibility, scope, adversarial -> failure-modes, Rust/domain-fit) audited rev 1 against the code. Scope verdict: -> right-sized; two-tier design and two-commit staging earn their keep. The load-bearing -> corrections folded here: **(MF-1)** rev 1 undercounted the FFI cold-load restore path — -> it raw-writes **six** DashPay fields including all three relationship maps -> (`ffi/persistence.rs:4064/4067/4070`), so the relationship-map `apply_*` methods must be -> `pub`, not `pub(crate)`, and the boundary claim is recalibrated from "sealed" to -> "raw writes impossible; invariant-bypassing writes are named `apply_*` and auditable". -> **(MF-2)** a `pub dashpay` field is bypassable by whole-value replacement -> (`managed.dashpay = Default::default()` / `mem::take` compiles anywhere and silently wipes -> the high-water cursors) — the field itself is now private with a `dashpay()` borrow -> getter and per-field Tier B `_mut` accessors, and **no** whole-struct `dashpay_mut()`. -> **(MF-3)** rev 1 answered only one of the three sites the origin comment names; §0 now -> maps the design to all three honestly, and an optional facade-level `DashPayView` -> (zero-cost borrowing namespace — materially different from the twice-reverted owned -> facade) is added as decision point Q1. Plus: getters live on `DashPayState` itself; -> `dashpay_` field-name stutter dropped; `pub(super)` replaces the long scoped-visibility -> path; the in-crate test-fixture raw writes are inventoried and budgeted (§5); D4's method -> doc keeps the caller-side half of the cursor contract explicit. - ---- - -## 0. What the origin comment names, and what this spec covers - -The PR comment names three sites. Honest mapping: - -1. **`ManagedIdentity` (state)** — the worst offender and **this spec's target**: 12 of 19 - fields are DashPay social state, all `pub`, invariants enforceable only by convention. -2. **`IdentityWallet` (network facade)** — the *largest* mixing by volume (~10.2k lines of - DashPay ops vs ~6.6k identity-core across the `network/` impl files), but already - file-split by concern with documented layering (`network/mod.rs`). Two owned-facade - splits were tried and deliberately reverted on this branch (§4.1). What this spec offers - there is the optional zero-cost `DashPayView` namespace (§3 D8, decision Q1) — call-site - visibility without a second handle. -3. **`IdentityManager` / manager layer** — already clean: the manager holds buckets + a - location index with no DashPay logic; DashPay sync orchestration is already its own - coordinator (`manager/dashpay_sync.rs`). No change proposed. - -## 1. Problem - -`ManagedIdentity` (`src/wallet/identity/state/managed_identity/mod.rs`) mixes two concerns -in one flat, fully-`pub` struct: - -- **Identity-core**: `identity`, `identity_index`, `wallet_id`, `status`, `dpns_names`, - `contested_dpns_names`, two sync block-times. -- **DashPay social state — 12 fields**: `established_contacts`, `sent_contact_requests`, - `incoming_contact_requests`, `ignored_senders`, `auto_accept_verify_failed`, - `dashpay_rescan_triggered`, `dashpay_profile`, `dashpay_payments`, `contact_profiles`, - `high_water_received_ms`, `high_water_sent_ms`, `pending_contact_crypto`. - -Three concrete costs today (all verified against the code): - -1. **No boundary.** Nothing in the type answers "what is DashPay vs identity-core"; the - distinction lives in field-comment prose. Any future extraction (or reasoning about one) - starts from zero. -2. **Invariants are bypassable — and one already lives outside the state layer.** All fields - are `pub`, so the auto-establish invariant (reciprocal request ⇒ established contact), the - `AUTO_ACCEPT_VERIFY_FAILED_CAP` eviction, and the ignore-emits-both changeset rule are - upheld only by the convention of calling the right method. Worse, **high-water cursor - monotonicity is enforced nowhere in the state layer**: the compare-and-advance rule - (`advance_if_unchanged`, `network/contact_requests.rs:822`) is a free function in network - code writing the fields raw (`:1363`, `:1370`). A miss reintroduces the lost-unignore bug - that function's doc-comment describes. -3. **The FFI crate reads 9 public fields directly** inside handle closures - (`ffi/src/dashpay_profile.rs:150` et al.) and **raw-writes six fields on the cold-load - restore path**: `ignored_senders` (`ffi/persistence.rs:3758`), `dashpay_payments` - (`:3806`), `contact_profiles` (`:3900`), and — via `apply_contact_rows` - (`:3961-4077`, production load path) — all three relationship maps (`:4064/:4067/:4070`). - The compiler offers no help distinguishing "legit restore write" from "invariant bypass". - -## 2. Current architecture (facts the design relies on) - -From a three-agent inventory of the state layer, all access sites, and the persistence -coupling, plus four review passes re-verifying the cites: - -- **The core↔DashPay coupling is narrow.** No method in - `state/managed_identity/{contacts,contact_requests,identity_ops,sync}.rs` mutates both an - identity-core field and a DashPay field in the same call. Coupling is exactly: (a) - `snapshot_changeset()` → `IdentityEntry::from_managed` (`changeset/changeset.rs:332-349`) - reads 4 DashPay scalar fields on every core-field persist; (b) the two constructors - initialize both groups; (c) `disable_keys` reads `wallet_id`/`identity_index` alongside a - snapshot. DashPay mutators read only the immutable `self.id()`. -- **Mutation methods are already the norm.** Network code calls state-mutation methods 53×; - direct production field writes outside the owner module: ~11 in `network/` (high-water ×2, - `dashpay_rescan_triggered` ×1, `established_contacts.get_mut` ×3, - `set_dashpay_profile`/`mark_auto_accept_verify_failed` pass-throughs, `contact_profiles` - ×1), 12 in `state/manager/apply.rs` (changeset replay), 9 in `wallet/apply.rs` (changeset - replay), and **9 in the FFI crate** (6 restore-path raw writes + 3 via methods). Test - fixtures add raw writes in `wallet/apply.rs:562-567/:1348-1351`, `network/` test modules, - `ffi/tests/test_data/mod.rs:283-286/:304`, and `contact_workflow_tests.rs:289` - (`established_contacts.get_mut`). -- **Persistence never serializes `ManagedIdentity` itself** — it derives `Debug, Clone` only. - Three persistence tiers cover the 12 fields: - - `IdentityEntry` scalar snapshot (serde-derived flat struct, `changeset.rs:270-323`): - `dashpay_profile` (merge: LWW), `dashpay_payments` (extend, LWW per txid), - `contact_profiles` (extend, LWW per contact), `ignored_senders` (union). - - `ContactChangeSet` (`changeset.rs:634-663`): the three relationship maps + the - `ignored`/`unignored` tombstone pair. - - `PlatformWalletChangeSet.pending_contact_crypto_{added,cleared}` (`changeset.rs:1189/1193`) - for the deferred-crypto queue. - - **In-memory only, never persisted**: `dashpay_rescan_triggered`, - `auto_accept_verify_failed`, `high_water_received_ms`, `high_water_sent_ms`. -- **The FFI ABI is keyed off the flat entry types** (`IdentityEntryFFI::from_entry`, - `ContactRequestFFI::from_*` — `#[repr(C)]` with pinned sizes), NOT off `ManagedIdentity`'s - layout. Regrouping `ManagedIdentity` cannot move a single FFI byte as long as the entry - types stay flat. -- **Two restore paths construct/populate `ManagedIdentity` outside its methods**: the - boot/load path (in-crate: pre-built identities arrive via `IdentityManagerStartState`, - consumed at `manager/load.rs:100` — no field-level construction; FFI loader: - `ManagedIdentity::new` + restore writes, `ffi/persistence.rs:3692-3700`) and the - changeset-replay path (`state/manager/apply.rs`, `wallet/apply.rs` contacts block, - `apply_established_contact`). -- **One external struct-literal construction** exists in `rs-platform-wallet-storage` - (`schema/identities.rs:206-237`) — test-gated (`#[cfg(any(test, feature="__test-helpers"))]`). - It defaults the three relationship maps (loaded separately from the contacts table) and - populates `ignored_senders` by wholesale clone. -- **The WalletPersister is a method parameter**, not a `ManagedIdentity` field. Non-persisting - mutators return a `ContactChangeSet` for the caller to store. A sub-struct inherits the same - two patterns unchanged. -- History: a separate DashPay surface was tried and deliberately reverted twice on this - branch — `914e244401` folded `wallet/dashpay/` under `identity/` (duplicate files, - bidirectional refs, "where does this live?"), `cdd0da880e` merged the `DashPayWallet` - facade into `IdentityWallet` (two FFI handles, two clones per op, straddling ops like - `accept_contact_request`). - -## 3. Design - -### D1 — `DashPayState` struct, privately owned by `ManagedIdentity` - -New file `state/managed_identity/dashpay.rs` (a child module of `managed_identity`, sibling -of the four impl files — verified module chain makes `pub(super)` fields visible to all of -them and to nothing outside `managed_identity/`): - -```rust -/// Per-identity DashPay social state: the DashPay-contract layer -/// (contacts, requests, profile, payments, deferred crypto) carried by -/// a `ManagedIdentity` on top of its identity-core fields. -#[derive(Debug, Clone, Default)] -pub struct DashPayState { - // -- Tier A: guarded (sibling-module fields, mutate via methods) -- - pub(super) established_contacts: BTreeMap, - pub(super) sent_contact_requests: BTreeMap, - pub(super) incoming_contact_requests: BTreeMap, - pub(super) ignored_senders: BTreeSet, - pub(super) auto_accept_verify_failed: BTreeSet<[u8; 32]>, - pub(super) high_water_received_ms: Option, - pub(super) high_water_sent_ms: Option, - - // -- Tier B: open (plain data / caches, no cross-field invariant) -- - pub profile: Option, - pub payments: BTreeMap, - pub contact_profiles: BTreeMap, - pub rescan_triggered: BTreeSet, - pub pending_contact_crypto: Vec, -} -``` - -On `ManagedIdentity`, the 12 flat fields are replaced by a **private** field -`dashpay: DashPayState` (private-to-`managed_identity`: visible in `mod.rs` and all child -impl files, invisible outside — this also closes the whole-value-replacement bypass, see -D3). The existing field doc-comments (several are load-bearing, e.g. the in-memory-only -rationale on `rescan_triggered` and `auto_accept_verify_failed`) move verbatim. The -`dashpay_` name prefix is dropped inside the struct (no stutter behind `dashpay()`). - -**Tier assignment rationale.** Tier A = every field with a cross-field or temporal invariant: -the three relationship maps (auto-establish; rotation-supersede; both-exist precheck), -`ignored_senders` (ignore must emit `removed_incoming` + `ignored` together), -`auto_accept_verify_failed` (CAP eviction — already method-only today), the two high-water -cursors (compare-and-advance; only writer besides the sweep is `unignore_sender`'s rewind). -Tier B = independent per-key caches where a raw insert cannot corrupt sibling state, and where -the replay/restore paths and profile/payment recorders already write directly today. -`pending_contact_crypto` stays Tier B: its dedup invariant lives in the free function -`upsert_pending_contact_crypto` shared with the changeset apply path, and its drain uses -owned snapshots — capturing that in methods is real scope with no bypass bug on record -(possible follow-up, out of scope here). - -### D2 — mutation methods stay on `ManagedIdentity`; signatures unchanged - -Every existing mutation/query method (`add_sent_contact_request`, -`add_incoming_contact_request`, `accept_incoming_request`, `ignore_sender` / -`unignore_sender`, `set_contact_metadata`, `apply_rotated_incoming_request`, -`mark_auto_accept_verify_failed`, `should_enqueue_auto_accept`, `set_dashpay_profile`, -`record_dashpay_payment`, …) keeps its receiver, name, signature, and persister-threading -pattern; bodies reach through `self.dashpay.*`. The 53 existing method call sites don't -change. This is deliberately NOT a `DashPayState`-methods design for mutations: they need -`self.id()` and snapshot access, and moving them would churn every call site for zero -invariant gain. - -### D3 — read access: one `dashpay()` borrow + getters on `DashPayState` - -`ManagedIdentity` gains exactly one read accessor: - -```rust -pub fn dashpay(&self) -> &DashPayState -``` - -Tier B fields are `pub`, so all reads flow `managed.dashpay().payments`, -`managed.dashpay().contact_profiles`, … Tier A fields get borrow getters **on -`DashPayState` itself** (next to the fields): `established_contacts()`, -`sent_contact_requests()`, `incoming_contact_requests()`, `ignored_senders()`, and by-value -`high_water_received_ms()` / `high_water_sent_ms()` (`Option` is `Copy`). -`auto_accept_verify_failed` gets NO getter — the two existing query methods on -`ManagedIdentity` (`is_auto_accept_verify_failed`, `should_enqueue_auto_accept`) cover every -reader. Existing query helpers (`is_sender_ignored`, `established_contact(&id)`, -`prior_sent_account_reference`, …) stay on `ManagedIdentity` unchanged. - -Read sites (~30 network, ~18 FFI, ~55 test assertions) re-path mechanically -(`managed.established_contacts` → `managed.dashpay().established_contacts()`). Verified: no -name collisions with existing `ManagedIdentity` methods; the same-named methods on -`IdentityWallet` are a different type. - -Tier B **writes** get per-field mut accessors on `ManagedIdentity`: `payments_mut()`, -`contact_profiles_mut()`, `rescan_triggered_mut()`, `pending_contact_crypto_mut()`, and -`set_profile_raw` is unnecessary (`set_dashpay_profile` already exists; the replay paths use -the mut accessors). There is deliberately **no whole-struct `dashpay_mut()`** and the -`dashpay` field is private: `managed.dashpay = DashPayState::default()`, `mem::take`, and -`mem::swap` — whole-value replacements that would silently wipe Tier A state including the -cursors — do not compile outside `managed_identity/`. - -`established_contact_mut(&id) -> Option<&mut EstablishedContact>` **stays, promoted to -`pub`** (documented escape hatch; `contact_workflow_tests.rs:289` — an external compilation -unit — needs it, as do three in-crate network sites that mutate contact sub-fields then -persist a hand-built `ContactChangeSet`). Sealing per-contact sub-field mutation is -follow-up scope; the boundary claim here is deliberately modest — see D5. - -### D4 — capture the high-water invariant (the one real behavior-adjacent move) - -`advance_if_unchanged` + `advance_high_water` (free fns, -`network/contact_requests.rs:814-832`) move onto `ManagedIdentity` as the ONLY write path -for the cursors: - -```rust -/// Compare-and-advance: advance the received-direction cursor to -/// `max_fetched` (never below its current value) ONLY if the cursor -/// still holds `snapshot` — the value read at sweep start. A mid-sweep -/// `unignore_sender` rewind (reset to None) must not be clobbered by a -/// stale sweep max, or the un-ignored sender stays invisible until a -/// cold restart. -/// -/// Caller contract (unchanged from the free fn): invoke only when the -/// paginate exhausted without error AND every ingest reached disk — -/// fetch/persist-success gating stays at the call site. -pub fn advance_high_water_received(&mut self, snapshot: Option, max_fetched: Option); -pub fn advance_high_water_sent(&mut self, snapshot: Option, max_fetched: Option); -``` - -The two raw network writes (`:1363`, `:1370`) become calls; `unignore_sender`'s rewind stays -internal to the state layer. The moved invariant is CAS + monotonicity **only**; the -fetch-succeeded/persist-succeeded gating remains caller-side convention, stated in the doc. -Semantics bit-identical: the snapshot stays a caller-supplied param, so the two-guard -interleaving with a concurrent un-ignore is unchanged. - -### D5 — replay/restore writes become named `apply_*` methods - -The replay and cold-load paths currently write Tier A fields raw. They get intent-named -methods that skip business invariants **by design** (establishment/ignore decisions were made -before persist; replay must reproduce state, not re-decide it). Visibility follows the -callers — the FFI crate restores relationship maps in production, so these are `pub`: - -- `pub fn apply_sent_contact_request(&mut self, ContactRequest)` / - `apply_incoming_contact_request` — for `wallet/apply.rs:197-222` and the FFI loader - (`ffi/persistence.rs:4067/:4070`) + FFI fixtures (`ffi/tests/test_data/mod.rs:304`). -- `apply_established_contact` — exists (`contact_requests.rs:621`), promoted - `pub(crate)` → `pub` (FFI loader `:4064`, fixtures `:283-286`). Parity note: its - remove-both-pending-sides is a provable no-op on the cold-load path — `apply_contact_rows`' - match arms emit exactly one of {established, sent, incoming} per contact into fresh maps. -- `pub fn apply_ignored_sender(&mut self, Identifier)` / `apply_unignored_sender` — for - `wallet/apply.rs:255/265`, the FFI restore write (`ffi/persistence.rs:3758`), and the - storage-crate test helper. **Implementer note:** `state/manager/apply.rs:71/:115/:143` and - the storage helper write the *whole set* (`.extend()` union / fresh-object assign) — loop - `apply_ignored_sender` per element. Equivalent because `:115/:143` sit on fresh-insert - branches where the set is constructor-empty (assign ≡ insert-loop) and `:71` is already a - union; pin this equivalence with a test. -- `pub(crate) fn apply_removed_sent(&mut self, &Identifier)` / `apply_removed_incoming` — - only `wallet/apply.rs:225/:230` removes. -- `state/manager/apply.rs`'s remaining writes touch Tier B only (`dashpay_profile` → - `profile`, `dashpay_payments` → `payments`, `contact_profiles`) — they use the Tier B mut - accessors, as do the FFI restore writes to `payments`/`contact_profiles`. - -Each `apply_*` doc-comment states why it bypasses the invariant and who may call it. - -**Boundary claim, calibrated** (this is what the refactor actually buys): raw *field* writes -to Tier A are compile errors outside `managed_identity/`; invariant-*bypassing* writes still -exist but are named `apply_*`, greppable, and auditable — the compiler cannot distinguish a -new illegitimate `apply_*` caller from a restore path. The capability-level seal is real for -exactly two things: the high-water cursors (D4 — the only public write path enforces CAS) -and whole-value replacement of the DashPay group (D3). Everything else is -naming-and-audit, which is the honest, proportionate win. - -### D6 — construction - -`DashPayState` derives `Default` (every field defaults empty/None — true today for both -constructors and the cold-load path; all 12 field types are `Default`-able). -`ManagedIdentity::new` / `new_out_of_wallet` set `dashpay: DashPayState::default()`. The FFI -loader keeps `ManagedIdentity::new` + `apply_*`/Tier-B-mut writes. The storage test helper -(`storage/schema/identities.rs:206-237`) switches its literal to -`dashpay: DashPayState::default()` semantics via constructor + an `apply_ignored_sender` -loop (its relationship maps are already defaulted there; contacts load separately). - -### D7 — persistence mapping updates (no wire change) - -`IdentityEntry::from_managed` (lives in `crate::changeset` — reads Tier A through the `pub` -getters, Tier B through `dashpay()`). `IdentityEntry`, `ContactChangeSet`, all merge -functions, the SQLite schema, and every `#[repr(C)]` FFI mirror are **untouched**. The -on-disk format and FFI ABI provably cannot change: nothing serializes `ManagedIdentity` -(derives `Debug, Clone` only), and no FFI struct or `const` size assert is edited. Only -observable representation delta: `Debug` output nests the group under `dashpay:` — no test -parses `Debug` output (verified). - -### D8 — OPTIONAL: facade-level `DashPayView` namespace (decision Q1) - -The origin comment's eye was on `IdentityWallet` — where DashPay ops outnumber identity-core -ops by lines ~10.2k to ~6.6k. The twice-reverted design was a second **owned** facade (two -handles through FFI, two clones per op). A **borrowing view** has none of those costs: - -```rust -pub struct DashPayView<'a, B: TransactionBroadcaster + ?Sized>(&'a IdentityWallet); - -impl IdentityWallet { - pub fn dashpay(&self) -> DashPayView<'_, B> { DashPayView(self) } -} -``` - -The DashPay op definitions (already file-split: `contact_requests.rs`, `contacts.rs`, -`contact_info.rs`, `payments.rs`, `profile.rs`) move their `impl IdentityWallet` blocks to -`impl DashPayView<'_, B>` — one route per op, no forwarding shims. Call sites become -`wallet.identity().dashpay().send_contact_request(…)`. FFI **function signatures are -unchanged** (they re-path internally); Swift is untouched. Cost: a mechanical re-path of the -FFI + internal DashPay call sites and the sync coordinator; zero new state, zero clones. -This is the piece that makes the DashPay/identity boundary visible at every call site — but -it is severable: commits 1–2 stand alone if this is declined. - -## 4. Alternatives rejected - -1. **Separate owned `DashPayWallet` facade (the PR comment's literal suggestion).** Tried and - reverted twice on this very branch (§2 history). The ops straddle the boundary - (`accept_contact_request` = identity signing + DashPay docs; payments = core broadcaster; - contact crypto = identity DIP-9/14 keys), so a second owned facade re-creates the same - handle with a different name, re-splits ops that straddle, and re-introduces FFI - handle-juggling. DashPay is a *layer on the identity aggregate*, not a sibling domain. - Rejected on evidence, not taste. (The borrowing view in D8 is the surviving kernel of - this idea — namespace without ownership.) -2. **Separate DashPay store keyed by identity id** (e.g. `IdentityManager.dashpay: - BTreeMap`). Splits one aggregate into two maps that must stay - key-synchronized through add/remove/apply/load; every combined read becomes a two-map - join; the changeset apply and both restore paths get a second lookup + orphan mode. All - cost, and the "is it one thing?" answer is unchanged — a DashPay state without its - identity is meaningless. -3. **Extension-trait split of `IdentityWallet`** (`DashPayOps` trait). Pure cosmetics: state - stays mixed, callers add trait imports, and the network layer is already file-split by - concern. The borrowing view (D8) achieves the namespacing without the trait ceremony. -4. **Full lockdown (all 12 fields private, no `_mut` escape hatch).** Forces dedicated - methods for per-contact sub-field mutation (3 network sites), the profile fetch-cache - writer, payments recorder internals, and the pending-crypto upsert/drain — roughly - doubles the new-method surface to protect fields with no cross-field invariants and no - observed bypass bugs. Poor cost/benefit now; Tier A→B promotion later is cheap. -5. **Stop after commit 1 (all-`pub` regroup, no encapsulation).** Fixes cost 1 of §1 - (boundary/naming) but leaves costs 2–3 untouched: the high-water cursors stay raw - network writes guarding a documented lost-unignore bug, and the FFI keeps 6 - indistinguishable raw restore writes. The ~14 new methods in commit 2 are earned by - exactly those two costs. -6. **Docs only (comment banner grouping the fields).** Zero enforcement; the next reviewer - asks the same question. - -## 5. Migration & staging - -Own PR, based on `v4.1-dev` **after #3841 merges** (this touches the same files as #3841's -tail; doing it inside would bloat an already-huge diff and re-trigger full re-review). - -Commits, each independently green: - -1. **Mechanical regroup.** Introduce `DashPayState` with ALL fields temporarily `pub` (and - the `dashpay` field `pub`); move the 12 fields (renaming the three `dashpay_`-prefixed - ones); re-path every access (`managed.X` → `managed.dashpay.X`). No visibility change, no - method change. Compile-error-driven; behavior-identical by construction. Also deletes - the orphaned 0-byte `state/managed_identity/tests.rs` left by `914e244401`. -2. **Encapsulate.** Apply tier visibilities + private `dashpay` field; add `dashpay()`, - Tier A getters, Tier B mut accessors, `advance_high_water_*`, the `apply_*` family; - convert the network + FFI + replay sites; move the two high-water free fns into the - state layer with their tests. **Test-fixture conversions budgeted here** (not - "mechanical re-paths"): `wallet/apply.rs:562-567/:1348-1351` (insert → `apply_*`), - `network/contact_requests.rs` fixture sites (~3411-3418 flag write → - `established_contact_mut`; ~3560-3564 `ignored_senders.clear()` — no direct equivalent, - becomes clone-keys + `apply_unignored_sender` loop), `network/payments.rs:1535/1610/2537` - + `network/contact_info.rs` helper (insert → `apply_*`), FFI fixtures - (`ffi/tests/test_data/mod.rs`), `contact_workflow_tests.rs:289` - (→ `established_contact_mut`). -3. **(Optional, decision Q1) `DashPayView` facade namespace** per D8. - -Rollback story: each commit reverts independently of the ones before it. - -## 6. Failure modes & risks - -- **Missed access site** → compile error (loud, the mechanism working as intended). Zero - runtime discovery. -- **High-water semantics drift** (the only logic that *moves*): mitigated by porting the - existing free-fn unit tests unchanged, plus new method-level tests written to pass against - the free fn's behavior BEFORE the move (kill-the-mutant check: `snapshot != current` must - leave the field untouched). -- **Replay-path behavior change**: `apply_*` methods must reproduce today's raw writes - exactly. Verified caller-side semantics that must NOT move into the methods: - `wallet/apply.rs` keys inserts off `entry.request.recipient_id`/`sender_id`, warns on - orphan inserts but is silent on orphan removes, orders inserts-before-removes and - unignore-after-ignore (un-ignore wins) — all stay in `wallet/apply.rs`. The - `ignored_senders` assign-vs-loop equivalence (D5) gets a pinning test. -- **Borrow-checker fallout**: adversarial pass verified all existing sites compile under the - new surface (the three `get_mut` sites touch only the contact + persister while the `&mut` - is live; loops over Tier A maps are read-only in-body; mutating sites collect inputs before - taking `&mut`). New sites holding a getter-returned borrow across a `&mut` call will fail - to compile — clone first in tests. -- **FFI restore path**: `apply_*` parity is exact (raw inserts have no side effects; - `apply_established_contact`'s extra removes are a no-op on fresh maps — D5). -- **Merge risk with in-flight DashPay work**: pure mechanics; land in a quiet window. - Orthogonal to the pending-contact-crypto follow-ups (that spec moved the field *onto* the - identity; this one only re-paths it). -- **Residual escape hatches — the honest list**: `established_contact_mut` (`pub`), Tier B - `pub` fields + mut accessors, and the **`pub apply_*` family itself** (any crate can call - `apply_ignored_sender` instead of `ignore_sender`, skipping the tombstone contract — same - exposure as today's `pub` fields, but now named and greppable). The boundary claim is - D5's calibrated version, not "all DashPay state is sealed". - -## 7. Test & verification plan - -- **Existing suites are the harness** (behavior-preserving refactor): full - `rs-platform-wallet` lib tests (the auto-establish, rotation, ignore/unignore, CAP-eviction, - persist-before-commit pins all keep passing untouched), `contact_workflow_tests`, - `rs-platform-wallet-ffi` lib + integration tests. -- **New unit tests** (written against the CURRENT free-fn behavior first, then the method): - `advance_high_water_{received,sent}` — advance, never-below, `None`-snapshot, - mid-sweep-rewind-preserved; `apply_ignored_sender` loop ≡ wholesale-assign parity; - `apply_sent/incoming_contact_request` parity with today's `wallet/apply.rs` raw inserts - (including the no-auto-establish property of the replay path). -- **Visibility is its own test — for what it actually seals**: after commit 2, a Tier A raw - *field* write or a whole-`dashpay` replacement outside `managed_identity/` is a compile - error. (`apply_*` misuse is not compiler-catchable — that's the calibrated D5 claim.) -- **Local CI mirror**: `cargo clippy --workspace --all-features` + `cargo fmt --check --all` - (targeted `-p` builds miss feature-gated callers). -- **iOS**: rebuild the xcframework + run the existing FFI persistence round-trip tests; no - Swift source change expected (assert: `git diff --stat` on `packages/swift-sdk` is empty). - -## 8. Open questions (decision points for the PR author) - -1. **Include commit 3 (`DashPayView` facade namespace, D8)?** Recommendation: yes — it is - the only part of this spec that changes what the origin comment's author *sees* at the - `IdentityWallet` layer, and it is zero-cost at runtime. But commits 1–2 deliver the - state-layer value standalone; declining Q1 drops D8 with no other edits. -2. Should `payments` be Tier A? `record_dashpay_payment` has rollback-on-persist semantics, - but the FFI restore + overlay paths write it raw; sealing it means two more `apply_*` - methods. Proposed: keep Tier B now. -3. DPNS fields (`dpns_names`, `contested_dpns_names`): once `DashPayState` lands, their - loose placement becomes the next obvious question. Position: deliberately-separate - follow-up using the identical pattern ("dashpay first, dpns next"), not scope here. diff --git a/docs/dashpay/DIP15_INVITATIONS_SPEC.md b/docs/dashpay/DIP15_INVITATIONS_SPEC.md deleted file mode 100644 index 1f2152e994b..00000000000 --- a/docs/dashpay/DIP15_INVITATIONS_SPEC.md +++ /dev/null @@ -1,835 +0,0 @@ -# DashPay Invitations (DIP-13 sub-feature 3') — Implementation Spec - -> **Status:** SHIPPED on PR #4041 (2026-07-14) — create + claim + reclaim + persistence + UI, -> three review-fix rounds folded, funded testnet e2e green (TEST_PLAN DP-12..19, `AI_QA/QA004`). -> The original design pass (2026-07-08, §1–§14 below) is kept as rationale; **§0 records where -> the as-built implementation deliberately diverged.** Where §0 and a later section disagree, -> §0 wins. - -Tracked as the "NEXT" item in the DashPay backlog (dashpay/platform#4020); called out in -`SPEC.md` Milestone 5 and `DIP_CONFORMANCE_GAPS.md`. - ---- - -## 0. As-built delta (supersedes the marked sections below) - -1. **Link envelope = the LEGACY query format, not the §6 binary blob (supersedes §6, §7).** - The 2026-07-13 legacy-compat rework (owner decision; contract in §0A) replaced the hand-rolled versioned payload with the - query form shared with dash-wallet Android / dashwallet-iOS, so links are field-level - cross-claimable: `dashpay://invite?du=&assetlocktx=&pk=&islock=` - `[&display-name=…][&avatar-url=…]` (also parses `https://invitations.dashpay.io/applink?…`). - Emit strict / parse lenient. Consequences: - - The link carries the funding **txid**, not the embedded proof → **claim-by-fetch**: the - invitee refetches the funding tx by txid (bounded retry for DAPI propagation lag, both - byte orders), reconstructs the proof, and selects the credit output by matching - `voucher_credit_script(pk)`. - - **No expiry field on the wire** — the §5.1/§8/§10 "claim refuses a past-expiry link" - mechanism does not exist in the as-built claim; `expiry_unix` survives only as inviter-side - local display metadata. The economic bounds are the amount caps. - - **No inviter identity id on the wire** (`inviter_id` always zeroed) — the contact bootstrap - resolves the id from the `du` username via DPNS at claim time. `InviterInfo.username` is - `Option`: a display-name/avatar-only link is metadata-only (`has_inviter == true`, - `inviter_username == nil`, no bootstrap). - - Amount is not on the wire (claim preview shows "—"). -2. **Claim accepts ChainLock invites too (amends §5.1).** `islock` absent or literal `"null"` - ⇒ a `ChainAssetLockProof` is reconstructed (requires the funding tx to be chain-locked). - Create still emits only InstantSend links — a slow-IS ChainLock fallback at create is - rejected as a *link* but the funded lock is recorded first and stays reclaimable. -3. **Amounts (amends §5/§8/§9):** `MIN_INVITATION_DUFFS = 300_000` (0.003 DASH — a smaller - voucher can fund neither a claim nor a register-reclaim, discovered by funded e2e), - `MAX_INVITATION_DUFFS = 26_000_000` (0.26 DASH), Swift default **0.03 DASH**. -4. **Persistence as-built (amends §4.2):** the `InvitationChangeSet` flows through - `PlatformWalletPersistence::store()` to each backend — the SQLite backend's - `V003__invitations` table, and on iOS the FFI `on_persist_invitations_fn` bridge into the - SwiftData `PersistentInvitation` model (SwiftData is the UI source; no Rust rehydrate; §0B). Persist failures are signaled end-to-end - (nonzero callback → rolled-back round → `create_invitation` errors), not best-effort. -5. **Durability + ordering hardening (review rounds 1–3; the per-finding log lives in the - PR #4041 review threads + commit messages):** the pre-broadcast gate persists **and flushes** the - invitation funding-index pool (aborting before broadcast on failure); creation refuses - non-durable backends (`PlatformWalletPersistence::persists_durably()`); the funded-asset-lock - flow is split so the invitation record is persisted immediately **after broadcast, before the - proof wait** — an interrupted create can no longer orphan a funded voucher. -6. **Reclaim shipped (extends §1 scope):** an unclaimed voucher is recovered as identity - **credits** (top-up an existing identity or register a new one; the L1 amount was - OP_RETURN-burned). Already-consumed handling is classified via the persisted - `reclaimInFlight` marker: marker unset ⇒ provably a foreign claim (neutral "already - claimed"); marker set ⇒ **explicitly ambiguous** (the marker proves only that a local - consume attempt started, not that it landed — a racing claim is indistinguishable, so the - row resolves to the conservative terminal `Claimed` with an ambiguity message, never an - inferred `Reclaimed`) — see `AI_QA/QA004` step 6 for the exact classifier arms. -7. **QA contract as-built:** TEST_PLAN §4.10 rows **DP-12..DP-19** (not just DP-12..15) + - `AI_QA/QA004_invitation_reclaim.md`; funded e2e evidence recorded there. - ---- - -## 0A. As-built link envelope & legacy interop (absorbs the legacy-compat spec) - -The interop contract is **field-level parity with the live legacy wallets, emit -strict/canonical, parse leniently** — exactly as tolerantly as the live Android wallet. -Byte-for-byte parity is NOT the contract (the two legacy wallets differ in param order and in -scheme/host). The on-chain primitive and derivation path (`m/9'/coin'/5'/3'/idx'`) are -identical across all three wallets — no consensus change. - -### 0A.1 Wire format - -**Emit (canonical, what we produce):** -```text -dashpay://invite - ?du= # required to emit; optional on parse - &assetlocktx= - &pk= - &islock= # or omit (see below) - [&display-name=] - [&avatar-url=] -``` -- Parse **by field name, order-independent**; accept **both** the `dashpay://invite` scheme - and the `https://invitations.dashpay.io/applink` host (iOS legacy links use the latter). -- **`pk`**: WIF, **compressed** flag set (the credit-output hash uses the *compressed* - pubkey — wrong compression ⇒ wrong `hash160` ⇒ claim fails), network byte `0xCC` mainnet / - `0xEF` testnet-family. -- **`assetlocktx`**: emit lowercase big-endian display hex; on claim parse leniently — try - as-given, then **retry byte-reversed** on a fetch miss (old iOS links are little-endian). -- **`islock`**: OPTIONAL, with two absence forms — param missing **and the literal string - `"null"`** (Android emits `"null"` for a chainlock-confirmed invite). Absent/`"null"` ⇒ - reconstruct a **`ChainAssetLockProof`** at claim, never reject. The hex is not - self-describing: decode as the modern deterministic **ISDLOCK**; the ancient - non-deterministic ISLOCK is unrepresentable in rust-dashcore and fails closed (documented - limitation — no live producer exists). -- **Validity (lenient superset of both wallets):** require `assetlocktx` + `pk` - present/non-blank; never reject solely on a missing `du` or missing/`"null"` `islock`. - -### 0A.2 Claim-by-fetch - -The link carries the funding **txid**, not a proof, so claim reconstructs it (mirrors Android -`TopUpRepository.obtainAssetLockTransaction`): -1. Fetch the tx by `assetlocktx` via `Sdk::get_transaction` (bounded retry/backoff for DAPI - propagation lag; reversed-retry per §0A.1). -2. Fail-fast guards: fetched txid matches `assetlocktx` (either byte order); when an islock is - present, `islock.txid == fetched tx.txid`. -3. **Derive `output_index` by script match** — scan the fetched tx's `credit_outputs` for the - output whose `script_pubkey` == `voucher_credit_script(pk)`; never hard-code index 0. -4. Build `InstantAssetLockProof` (islock present) or `ChainAssetLockProof` (absent/`"null"`; - requires the tx to be chain-locked), then submit through the **unchanged** - `put_to_platform_and_wait_for_response_with_private_key`. - -Consensus enforces pk↔output, islock↔tx, and identity_id↔outpoint — all fail closed; the -local guards are fast-fail UX + correct index selection, not theft prevention. - -### 0A.3 Consequences of the legacy format - -- **No inviter identity id on the wire** — only `du`. `InviterInfo = {username?, display_name?, - avatar_url?}` and the invitee resolves the inviter's id from `du` via DPNS at - contact-bootstrap. A `du`-less link is metadata-only (`has_inviter == true`, - `inviter_username == nil`, no bootstrap possible). -- **No expiry on the wire** — the pre-network staleness gate is gone; the real bounds are the - amount caps + reclaim. The inviter-side local record keeps expiry for display only. -- **Amount is not on the wire** — the claim preview shows "—" pre-fetch. - -### 0A.4 Amounts (onboarding tiers) - -`MIN_INVITATION_DUFFS = 300_000` (0.003 DASH, == Android `DASH_PAY_INVITE_MIN`; a smaller -voucher can fund neither a claim nor a register-reclaim — found by funded e2e). -`MAX_INVITATION_DUFFS = 26_000_000` (0.26 DASH). Swift create default **0.03 DASH** = identity -+ a normal DPNS name (Android `DASH_PAY_FEE`). The cap covers the contested/premium tier as -well (0.25, Android `DASH_PAY_FEE_CONTESTED`), with the remaining margin for the create/claim -fees; the claim path is amount-agnostic, so nothing further gates a contested-tier invite. - -### 0A.5 Transport - -The custom `dashpay://` scheme is the shipped, first-class transport (QR / share sheet / -in-person). The legacy wallets' AppsFlyer OneLink wrapper is **externally blocked** (Android -team creds; brand domain + template) and tracked separately (#4096-adjacent); note that -OneLink discloses the plaintext `pk` to AppsFlyer server-side — an accepted, documented -regression vs a self-contained link, bounded by the amount cap + reclaim. The custom scheme's -same-device interception limitation is documented in `Info.plist` + §6.1. - ---- - -## 0B. As-built persistence & reclaim (absorbs the Swift-persistence spec) - -### 0B.1 Persistence bridge - -`InvitationChangeSet` (structurally an `asset_locks`-style `BTreeMap` upserts + -`BTreeSet` removals) flows through `PlatformWalletPersistence::store()` to each backend: the -SQLite backend's `V003__invitations` table, and on iOS the **push-callback FFI bridge** -(`on_persist_invitations_fn` → `persistInvitationsCallback` → SwiftData -`PersistentInvitation`), mirroring the asset-lock wiring. Key properties: -- **SwiftData is the UI source; push-only, no Rust→Swift rehydrate.** A SwiftData wipe loses - only list *visibility* — never funds or key re-derivability (`funding_index` re-derives the - voucher key). -- **Persist failures are signaled, never swallowed:** a skipped write returns nonzero from the - callback, failing the (invitation-only) `store()` round and surfacing an error from - `create_invitation` instead of reporting a voucher that never reached SwiftData. -- **Outpoint key seam:** both the upsert and the removal path derive the unique - `outPointHex` via `PersistentAssetLock.encodeOutPoint` verbatim (key-form drift is pinned by - `InvitationPersistenceTests`). - -### 0B.2 Reclaim - -The invitation's DASH is **burned into an `OP_RETURN`** at create time — the credit output -exists only in the tx payload as a Platform-side authorization, never as an L1 UTXO — so -"reclaim" means: **the inviter consumes the still-unclaimed voucher into a Platform identity -of their own, recovering the value as credits** (mechanically, claiming your own invitation). -UI copy always says "recovered as identity credits", never "DASH returned". - -- **Primitive:** consume the tracked lock via - `FromExistingAssetLock { out_point, consume_invitation_voucher: true }` — the inviter's own - signer re-derives the voucher key at `9'/coin'/5'/3'/funding_index'` internally (no key - export). Two user-picked targets: **top-up an existing identity** or **register a new - one**. The `consume_invitation_voucher` flag is the reclaim flow's **explicit - authorization**: every generic resume/top-up path passes `false` and the funding resolver - refuses `IdentityInvitation`-typed locks, so a shared voucher can never be silently - consumed into an unrelated local identity (the Swift resumable-registrations surface also - excludes `fundingTypeRaw == 3` rows). -- **Race / already-consumed:** no L1 double-spend exists (no shared UTXO); Platform - deterministically rejects the second consume - (`IdentityAssetLockTransactionOutPointAlreadyConsumed` — the loser wastes only an ST fee). - The Swift side classifies via the persisted `reclaimInFlight` marker, which is saved - (required — the consume may not run on a failed save) only immediately before the on-chain - consume: marker unset ⇒ provably the invitee claimed first (row → `Claimed`, neutral - "This invitation was already claimed." — claimant not named); marker set ⇒ **explicitly - ambiguous** — the marker proves only that a local consume attempt started, not that it - landed (a racing claim between crash and retry is indistinguishable), so the row resolves - to the conservative terminal `Claimed` with an ambiguity message, never an inferred - `Reclaimed` (`Reclaimed` is written only by a success observed in-flow). The local - "is not tracked" resume-guard failure with the marker set is surfaced as an explicit - ambiguity error (status unchanged — there is no on-chain proof of consumption at all). - The decision is the pure, unit-tested `classifyReclaimFailure(error:hadPriorReclaimInFlight:)` - seam; see `AI_QA/QA004` step 6 for the verified classifier arms. -- **Status lifecycle:** `Reclaimed`/`Claimed` are written by the Swift UI on the local row - (SwiftData is the UI source; create is the only Rust emitter). - ---- - -## 1. Problem & goal - -DashPay onboarding today assumes the new user already **has** a Dash identity (which -requires L1 Dash to fund the ~0.0002 DASH asset lock that registers it). That is a -chicken-and-egg wall for inviting a friend who has never touched Dash: they can't receive a -payment (no identity → no contact) and can't register an identity (no funds). - -**DIP-13 "Identity Invitation Funding keys" solves this.** An existing user (the *inviter*) -pre-funds an asset lock at a dedicated derivation sub-feature, hands the one-time private key -+ the asset-lock proof to a friend (the *invitee*) as a link, and the invitee registers -**their own new identity** funded by that voucher — no L1 Dash required on the invitee's -side. The invitation optionally bootstraps the DashPay contact in the same act (the invitee's -contact request to the inviter carries a DIP-15 `autoAcceptProof`, so it auto-establishes). - -**Goal:** implement invitation **create** (inviter) and **claim** (invitee) end-to-end across -`rs-platform-wallet` + `rs-platform-wallet-ffi` + `swift-sdk` + `SwiftExampleApp`, with unit -+ integration tests, a testnet funded e2e, and QA-contract scenarios. - -### Non-goals -- **No byte-for-byte interop with the production iOS/Android DashWallet invitation link.** We - can't drive those builds in this environment (same constraint the auto-accept spec accepted: - iOS-first, DIP-faithful where the DIP defines a format, normative-for-us where it is silent). - The **on-chain** artifacts (asset lock, IdentityCreate, contactRequest) are consensus formats - and *are* interoperable; only the off-chain **link envelope** is ours. See §7 for the interop - decision once the reference format is confirmed. -- **No new on-chain artifact.** Invitations reuse the existing AssetLock special-tx, the - IdentityCreate transition, and a plain contactRequest. -- **No auto-accept bearer key in the invitation (v1).** The contact-bootstrap is a *normal* - contact request (see §2 design change); no `dapk` is embedded. -- **No invitation for identity-less inviters in v1** beyond the pure funding voucher: the - contact-bootstrap requires the inviter to hold a registered identity. A voucher from an - identity-less funder still works as pure onboarding funding; it just carries no inviter to - contact. -- **Advisory expiry, not consensus revocation.** The voucher key controls an on-chain asset - lock that never expires; the payload's `expiry` is an **advisory** bound (the claim UI refuses - a stale link; the inviter is prompted to reclaim). True "revocation" is the inviter racing to - *reclaim* the unclaimed lock (a race it can lose if the link already leaked — §8 Finding 6). A - dedicated revoke UI is a follow-up. - ---- - -## 2. The model — two roles, three on-chain acts - -1. **Inviter (Bob, has funds + identity).** - - Derives a one-time ECDSA **voucher key** at the DIP-13 invitation path - `m/9'/coin'/5'/3'/funding_index'` (sub-feature `3'`). - - Builds + broadcasts an **asset lock** paying `amount` duffs to that key, and waits for an - **InstantSend** proof (§5.1 — fast, self-contained; a short IS-scoped expiry covers - staleness). - - **Optionally ticks "send a contact request back to me"** — if checked, the link carries the - inviter's identity id + username; if not, it's a pure funding voucher. - - Emits a `dashpay://invite?...` link carrying: **voucher private key**, **asset-lock - proof (IS)**, **advisory expiry**, and *(if opted in)* **inviter identity id + username + - display name**. The voucher key is re-derivable from `funding_index`, so it is **never - persisted**; only the funding index + outpoint are tracked (for recovery + status). -2. **Invitee (Carol, no funds).** - - Opens the link → decodes (voucher key, proof, optional inviter info). - - Registers **her own new identity** with keys derived from **her** seed at - `m/9'/coin'/5'/0'/0'/identity_index'/…`, funded by the imported `(proof, voucher_key)` via - the SDK's in-process raw-key path (§5.2). No L1 Dash on Carol's side. - - **If the link carries inviter info, Carol is *asked* "establish contact with \?"** — - on confirm, a *normal* contactRequest Carol→Bob is sent via the shipped - `send_contact_request` path; Bob sees it in his Requests and accepts. Opt-in on both ends - (inviter checkbox + invitee prompt); no bearer auto-accept key is embedded. - -> **Design change from the first draft (security review Finding 1 + reference behavior).** The -> first draft embedded a DIP-15 auto-accept `dapk` in the link so the contact would auto-establish -> with zero taps on the inviter. That is **removed**: auto-accept's safety rests entirely on a -> **1-hour TTL**, which is fundamentally incompatible with an invitation that is claimed hours-to- -> days later — a link long-lived enough to be useful would be a long-lived auto-accept bearer -> credential against the inviter (anyone finding a stale/posted link could make the inviter -> publish an encrypted friendship xpub to them). The production wallets don't do this either: -> their claim flow (`sendContactRequestToInviterUsingInvitationURL`) sends a **plain** contact -> request. So v1 auto-sends a normal contactRequest; zero-tap acceptance is the inviter's own -> orthogonal auto-accept setting, not baked into the shared link. (Embedding a short-TTL dapk with -> an explicit "expired → manual request" fallback is a possible v2 nicety — deferred.) - -The consensus acts (asset lock, IdentityCreate, contactRequest) are all already implemented and -tested; invitations are the **orchestration + off-chain envelope + key-handoff** around them. - ---- - -## 3. What already exists (reuse inventory — first-hand code read) - -| Capability | Where | Reused for | -|---|---|---| -| **Invitation funding derivation** `AssetLockFundingType::IdentityInvitation` (sub-feature `3'`), `accounts.identity_invitation` xpub, storage/recovery/persistence all wired | `asset_lock/build.rs:200-216` (`peek_next_funding_address`), storage `schema/accounts.rs`, `asset_lock/sync/recovery.rs:427`, `persistence.rs:3633` | **Create**: derive the voucher key + build the voucher asset lock | -| **Full funded-asset-lock flow** `create_funded_asset_lock_proof(amount, account_index, funding_type, identity_index, signer) -> (AssetLockProof, DerivationPath, OutPoint)` (build → track → broadcast → IS wait → CL-upgrade → attach proof) | `asset_lock/build.rs:305-417` | **Create**: build the voucher lock | -| **IS→CL upgrade** `upgrade_to_chain_lock_proof(out_point, None)` | `identity/network/registration.rs:186-197,247-250` | **Create**: force a CL proof before export | -| **Register identity from a raw asset-lock private key** `Identity::put_to_platform_and_wait_for_response_with_private_key(sdk, proof, asset_lock_proof_private_key: &PrivateKey, identity_signer, settings)` | `rs-sdk/.../put_identity.rs:50-59,146+` | **Claim**: register invitee identity funded by the imported voucher — **core claim needs no new SDK code** | -| **Bare claim FFI (external proof + one-time key)** `dash_sdk_identity_put_to_platform_with_instant_lock` / `_with_chain_lock(sdk, …proof bytes…, private_key:[u8;32], signer, settings)` | `rs-sdk-ffi/src/identity/put.rs:29,211` | Lower layer under the platform-wallet `claim_invitation` wrapper (no Swift binding yet) | -| **`AssetLockProof::Instant` embeds the full tx + islock** (self-contained); `Chain` = outpoint+height (Platform resolves tx) | `asset_lock_proof/instant/…:38`, `…/chain/…:24` | **Link**: serialize the proof directly — no separate txid + L1 fetch | -| **Consensus verifies the create sig against the asset-lock output's P2PKH hash** | `identity_create/state/v0/mod.rs:222-245` | Security trust anchor (§8): holder of the voucher key == who may create the identity | -| **Seedless register (self-funded)** `register_identity_with_funding(AssetLockFunding, identity_index, keys_map, identity_signer, asset_lock_signer, …)` | `identity/network/registration.rs:121` | Template; claim uses the raw-key variant instead | -| **Sanctioned raw-scalar export (path-gated)** `ContactCryptoProvider::export_auto_accept_private_key(&path)` / resolver hook | `contact_requests.rs:63`, `mnemonic_resolver_core_signer.rs:353` | **Create**: template for the new path-gated `export_invitation_private_key` (§5.3) | -| **Send a normal contactRequest** `platform_wallet_send_contact_request_with_signer(...)` | FFI `dashpay.rs:225` | **Claim**: auto-send the plain contact-bootstrap invitee→inviter (no dapk) | -| **Register/resume identity FFI (external signer)** `platform_wallet_register_identity_with_funding_signer`, `platform_wallet_resume_identity_with_existing_asset_lock_signer` | FFI `identity_registration_funded_with_signer.rs` | Template for the new claim FFI marshaling | -| **Asset-lock build FFI + tracked-lock listing** `asset_lock_manager_build_transaction`, `create_funded_proof`, `list_tracked_locks` | FFI `asset_lock/build.rs`, `asset_lock/manager.rs` | Create FFI + inviter-side status | - -**Net: the funding-derivation family and both consensus signing paths already exist.** The new -code is (a) the create orchestration + voucher-key export, (b) the claim orchestration, (c) the -`dashpay://invite` envelope codec, (d) inviter-side invitation persistence, (e) FFI + Swift + UI. - ---- - -## 4. Interface / data flow per layer - -### 4.1 Rust — new module `wallet/identity/network/invitation.rs` (+ codec in `crypto/invitation.rs`) - -**Create (inviter):** -``` -async fn create_invitation( - &self, - amount_duffs: u64, // rejected if 0 or > MAX_INVITATION_DUFFS - funding_account_index: u32, // BIP44 account supplying the L1 UTXOs - inviter: Option, // id + username + display_name (contact-bootstrap) - expiry_unix: u32, // advisory; the FFI sets now + MAX_INVITATION_TTL_SECS - asset_lock_signer: &AS, // funds the asset-lock (funding-input + credit-output) - crypto_provider: &CP, // exports the voucher scalar (path-gated resolver) -) -> Result -``` -where `inviter: Option` is `Some` only when the inviter ticked "send a -contact request back to me" (§ owner decision). Steps: (1) **bound the amount** -(`0 < amount_duffs ≤ MAX_INVITATION_DUFFS`) and the expiry (non-zero), else err; -(2) `create_funded_asset_lock_proof(amount, funding_account_index, IdentityInvitation, signer)` -→ `(IS proof, path, out_point)` — **the builder auto-selects the next unused funding index** and -returns its derivation `path`; **keep the IS proof, no CL upgrade** (§5.1); (3) **export the -voucher private key** via the seedless resolver hook, **path-gated to the fully-hardened -`9'/coin'/5'/3'/idx'`** (§5.3); (4) build the `Invitation` struct + `dashpay://invite` URI (§6); -(5) **persist an invitation record** through the wallet persister (§4.2) — created status, -outpoint, funding_index (from `path`), amount, expiry, optional inviter info; **the voucher key is -never persisted** (re-derived from `funding_index`). - -**Claim (invitee):** -``` -async fn claim_invitation( - &self, - invitation: ParsedInvitation, // decoded from the URI - identity_index: u32, - keys_map: BTreeMap, // invitee's own new-identity keys - identity_signer: &IS, // invitee's identity-key signer - establish_contact: bool, // invitee's answer to "establish contact with ?" -) -> Result -``` -Claim **bypasses the wallet's `AssetLockFunding` machinery** — the deliberately-removed -`UseAssetLock` variant (external proof through the tracked-lock resolver) is *not* revived; the -invitee owns neither the lock's inputs nor its tracking and can't drive its IS→CL fallback, so -claim submits the imported proof directly. Steps: (1) **validate the parsed invitation before -any network act** (§8 Finding 5): proof is an **Instant** proof; the voucher pubkey is the -credit-output's P2PKH target (`proof.output() → credit_outputs[output_index]`); expiry not -past — fail loud with a specific error otherwise; (2) build the placeholder `Identity` with -`keys_map`; (3) -`placeholder.put_to_platform_and_wait_for_response_with_private_key(&sdk, invitation.proof, -&invitation.voucher_key, identity_signer, settings)` → new `Identity` — **wrap this submit in -`submit_with_cl_height_retry`** (feasibility Note A): the direct raw-key SDK call bypasses -`register_identity_with_funding`, so it doesn't inherit that helper's retry on a transient -CL-height-too-low (10506); without the wrapper a transient reject is a hard claim failure; (4) -local bookkeeping -(add to IdentityManager, breadcrumbs) — best-effort, non-propagating (mirrors -`register_identity_with_funding` Step 4); (5) if `invitation.inviter` present **and -`establish_contact`** (the invitee said yes to the prompt), **send a normal contactRequest** -invitee→inviter via the shipped `send_contact_request` path (the new invitee identity as -sender). Idempotent/re-sendable if step 5 fails after step 3 succeeds (§10). If the invitee -declines, the identity is still created — just no contact. - -### 4.2 Rust — inviter-side persistence (proper persister integration — owner decision) -**A first-class persisted invitation record, through the existing wallet persister system** -(not an ad-hoc KV blob). Follow the established DashPay changeset → persister → SwiftData-model -pattern already used for contact requests / payments (`rs-platform-wallet` changeset overlays + -`rs-platform-wallet-storage` migration + the Swift `Persistence/Models` `@Query` models — -research-swift map). Concretely: -- **Rust storage (`rs-platform-wallet-storage`):** a new `invitations` table via a migration - (mirroring `asset_locks` `V001__initial.rs:247`), columns `wallet_id, outpoint, funding_index, - amount_duffs, expiry_unix, status (created|claimed|reclaimed), inviter_opt_in, created_at, - claimed_identity_id?`. **No secret column** — the voucher key is re-derived from `funding_index` - (§5.3), never stored. -- **Rust changeset (`rs-platform-wallet`):** an `InvitationChangeSet` emitted by create/reclaim - and by the sync that flips *created → claimed* (detected by the tracked asset-lock's outpoint - being consumed on Platform / the invitee's inbound contactRequest), queued onto the persister - exactly like `AssetLockChangeSet` / the DashPay overlays. -- **Swift:** a `PersistentInvitation` SwiftData model registered in `DashModelContainer`, driving - a `@Query` "Sent invitations" list (`InvitationsView`). - -Recovery still leans on re-derivation: an unclaimed invitation's voucher key is re-derived from -its `funding_index` to re-package or reclaim (the asset-lock row already tracks the lock's -lifecycle for the actual reclaim submit). The invitations table adds the durable, queryable -*status* surface the UI needs. - -### 4.3 FFI (rs-platform-wallet-ffi) — new `invitation.rs` -- `platform_wallet_create_invitation(wallet, amount_duffs, funding_account_index, - inviter_identity_id: *const [u8;32] /*nullable*/, inviter_username: *const c_char /*nullable*/, - expiry_unix: u32, core_signer_handle, out_uri: **c_char, out_outpoint: *mut OutPointFFI) - -> Result`. **Only `core_signer_handle`** (the asset-lock/Core signer) is needed — pure voucher - creation registers no identity, so there is no identity `signer_handle` (feasibility Note B). - `now`/`expiry_unix` is passed in from Swift (FFI can't read the clock deterministically — same - convention as `build_auto_accept_qr`). -- `platform_wallet_claim_invitation(wallet, uri: *const c_char, identity_index, - identity_pubkeys, identity_pubkeys_count, signer_handle /*invitee identity signer*/, - establish_contact: bool, out_identity_id: *mut [u8;32], out_identity_handle: *mut Handle) - -> Result`. `establish_contact` is the invitee's answer to the "establish contact with - \?" prompt (only acted on if the link carries inviter info). Reuses - `decode_identity_pubkeys` + the managed-identity insert from - `identity_registration_funded_with_signer.rs`. Note: a **bare** identity-create-from-external- - proof FFI already exists one layer down — `dash_sdk_identity_put_to_platform_with_chain_lock` - / `..._with_instant_lock(sdk, …proof bytes…, private_key: *const [u8;32], signer, settings)` - (`rs-sdk-ffi/src/identity/put.rs:29,211`). We do **not** call that bare FFI from Swift for - claim: the platform-wallet `claim_invitation` wrapper is needed so the new invitee identity is - registered in the wallet's `ManagedIdentity` storage **and** the contact-bootstrap fires — it - calls `put_to_platform_and_wait_for_response_with_private_key` internally, then does bookkeeping - + the bootstrap send. (No `core_signer_handle` is needed on claim: the asset-lock signature - uses the imported raw voucher key, not a wallet-derived one.) -- `platform_wallet_list_invitations(...)` + free helpers for the inviter status list. -- String/URI input validation identical to the auto-accept FFIs (null checks, length caps). - -### 4.4 Swift (swift-sdk + SwiftExampleApp) -Current services (note: `PlatformService`/`WalletService`/`UnifiedAppState` were **removed**): -`AppState` (owns the `SDK`, network), `PlatformWalletManager` (per-network, DashPay sync -lifecycle), `ManagedPlatformWallet` (**all identity/DashPay FFI calls live here**). **All Swift -↔ Rust FFI work MUST go through the `swift-rust-ffi-engineer` agent** (repo `CLAUDE.md` rule). -The **DIP-15 auto-accept QR flow is the copy-template** for both directions. -- swift-sdk wrappers on `ManagedPlatformWallet`: - - `createInvitation(amountDuffs:fundingAccount:expiry:) async throws -> InvitationLink` - (idiom of `registerIdentityWithFunding` `ManagedPlatformWallet.swift:3370` — long-running L1 - build, so wrap with a Controller+Coordinator triad like `IdentityRegistrationController`). - - `claimInvitation(uri:identityIndex:) async throws -> ManagedIdentity` (idiom of - `sendContactRequestFromQR` `:1758`). -- SwiftExampleApp UI (under the DashPay tab, `App/Views/DashPay/`): - - **Create**: a "Create invitation" action (beside "Add me QR" in `DashPayProfileView.swift:74`) - → amount entry **+ a "send a contact request back to me" checkbox** (drives the optional - inviter info) → share sheet with the link + a QR (reuse `generateQRCode`). - - **Claim**: a toolbar button + sheet mirroring `AddViaQRSheet` (`DashPayTabView.swift:830`) - (paste/scan the `dashpay://invite` link) → register identity → **if the link carries inviter - info, prompt "establish contact with \?"** → pass the answer as `establish_contact` → - `kickDashPaySync` → the new identity (+ optional contact) land via `@Query`. - - **Invitations list** (created + status): a new `InvitationsView` (`@Query` over - `PersistentInvitation`, §4.2), reached via a toolbar `NavigationLink` (like the Ignored link - at `:151`). - - **Deep link (net-new plumbing):** no `onOpenURL`/`CFBundleURLTypes` exist today. Add the - `dashpay` URL scheme to `SwiftExampleApp/Info.plist` and `.onOpenURL { … }` on the - `WindowGroup` in `SwiftExampleAppApp.swift:105`, routing to `RootTab.dashpay` + the claim - sheet; reuse the `AddViaQRSheet` URI-parse as the model. -- `FundingType.identityInvitation = 3` already exists in Swift - (`ManagedAssetLockManager.swift:36`, `KeyWalletTypes.swift:14`). -- **Framework build:** `DashSDKFFI.xcframework` is a generated artifact (not committed); rebuild - via `packages/swift-sdk/build_ios.sh --target sim` after any FFI/header change, then the - `xcodebuild` app build (§ repo CLAUDE.md). Always clean+rebuild after header changes. - -### 4.5 QA contract -The authoritative QA contract is **`packages/swift-sdk/SwiftExampleApp/TEST_PLAN.md`** (driven by -the `simulator-control` skill; dashboard at `dashpay.github.io/qa-dashboard-site`). Add rows to -**§4.10 DashPay** as **DP-12+** in the existing format: -`| ID | Action | Layer | Tier | Status | Tags | Entry point & test notes |`. Planned rows: -- `DP-12 | Create invitation | Cross | Common | … | funding | DashPay → Create invitation → platform_wallet_create_invitation (builds L1 asset lock; needs testnet funds).` -- `DP-13 | Claim invitation | Platform | Common | … | | Paste/scan dashpay://invite → platform_wallet_claim_invitation → new identity + contact.` -- `DP-14 | Invite→claim e2e (two wallets) | Cross | Thorough | … | multiwallet | Create on A, claim on B, contact auto-establishes both ends (cf. DP-11).` -- `DP-15 | Reject malformed / already-claimed invitation | Platform | Uncommon | … | | Bad link + reused link both fail loudly, no side effects.` -(Secondary: the `AI_QA/` MCP playbooks — add a `QA004`-style invite→claim walkthrough if useful.) - ---- - -## 5. The three technical cruxes (de-risked first-hand; §11 spikes confirm) - -### 5.1 Proof type — DECIDED: InstantSend (owner decision 2026-07-08) -`AssetLockProof` has two variants with very different self-containment (confirmed -`asset_lock_proof/mod.rs:40`): -- **`InstantAssetLockProof { instant_lock, transaction, output_index }`** — embeds the **full - funding tx + the InstantLock**. Self-contained (Platform validates the islock against the - embedded tx). This is what the **reference iOS/Android wallets export** (`islock` + they carry - the txid and re-fetch the tx). Fast to produce (just wait for the IS lock). **Risk:** Platform - rejects an islock whose quorum has rotated or is too old relative to Platform's core height - (`is_instant_lock_proof_invalid` + the IS→CL retry in `registration.rs`). An invitation that - sits **unclaimed** for a long time can go stale. -- **`ChainAssetLockProof { core_chain_locked_height, out_point }`** — tiny (outpoint + height); - Platform resolves the tx from Core by outpoint. **No staleness window** (chain-locked is - permanent), so an unclaimed invitation stays valid indefinitely. Cost: the inviter waits for a - ChainLock at create (≈ up to a block or two, low-minutes). - -**DECISION (owner, 2026-07-08): export an InstantSend proof.** Faster create (no CL wait), matches -the reference wallets, and the `InstantAssetLockProof` embeds the full tx + islock so the link is -fully self-contained (the invitee never fetches anything from L1). `create_funded_asset_lock_proof` -returns exactly this for a fresh tx (its `validate_or_upgrade_proof` only upgrades to CL when the -tx is *old* — not the case at create), so the invitation path **keeps the IS proof, no forced CL -upgrade**. - -> **Slow-IS fallback must be enforced (Rust-core review H1).** `create_funded_asset_lock_proof` -> *also* falls back to a ChainLock proof if the IS lock doesn't propagate within its 300s -> preference window. Since the invitee's `validate_claimable` accepts only an InstantSend proof, -> `create_invitation` **must reject a returned ChainLock proof** — else it would emit a -> `dashpay://invite` link the invitee silently rejects (a dead voucher: funds locked, no signal). -> On this rare path create returns a clear error; the funding lock stays tracked/reclaimable, and -> the inviter retries. *(A future robustness option is to accept a Chain proof on claim too — -> it never goes stale — skipping the local credit-output pre-check since a Chain proof carries no -> embedded tx; deferred, as it deviates from the literal Instant-only decision.)* - -**Staleness mitigation = a short, IS-scoped advisory expiry (not an IS→CL upgrade in v1).** The -one real risk is that Platform rejects a *stale* islock (quorum rotated). Rather than build an -invitee-side IS→CL upgrade (which needs the embedded tx re-tracked — non-trivial, and the -external-proof `UseAssetLock` path was deliberately removed), v1 sets the invitation's advisory -`expiry` conservatively **inside the IS validity window** (default ~24h, ≤ `MAX_INVITATION_TTL`): -the claim path refuses a past-expiry link up front with a clear "invitation expired — ask the -sender for a new one," so an about-to-go-stale proof is never submitted. Cheap, no fund risk (the -inviter simply re-creates), and the inviter's asset lock is reclaimable after expiry. **Future -enhancement (not v1):** an invitee-side IS→CL upgrade from the embedded tx to extend the window to -days/weeks. *(Note: this makes the create FFI's identity-signer moot as before, and the claim's -`submit_with_cl_height_retry` wrapper — feasibility Note A — still applies to the IS submit.)* - -### 5.2 Claim is ordinary identity registration with imported funding -`put_to_platform_and_wait_for_response_with_private_key(proof, voucher_key, identity_signer)` -already does exactly what claim needs. The invitee's identity keys come from the invitee's own -seed (normal registration); only the **funding** `(proof, voucher_key)` is imported. **No new -SDK code for the core claim.** The `identity_invitation` account is an inviter-only concept — -the invitee never derives sub-feature `3'`. - -### 5.3 Exporting the voucher private key is a deliberate bearer-credential export -The architecture's invariant is "private keys never cross the FFI boundary as raw bytes," and -the signer-driven builder deliberately **withholds** the credit-output private key (it returns -`AssetLockCreditKeys::Public((pubkey, path))`, `build.rs:117`). The invitation **is** a raw-key -handoff (the whole point), so exporting it is a scoped, documented exception — exactly like the -auto-accept `dapk` blob, which already exports a bearer private key in a QR. - -**Key choice:** **HD-derived at `m/9'/coin'/5'/3'/index'`** (not a JS-style random key). HD makes -it DIP-13-recoverable — the wallet can re-derive/scan unclaimed invitation funding txs and let -the user reclaim/resend (DIP-13's explicit recommendation) — at the cost of needing an export -step. (A random ephemeral key, JS-SDK precedent `createAssetLockTransaction.ts:26`, exports -trivially but is unrecoverable; rejected.) - -**Export = a NEW seedless resolver hook, path-gated to the exact invitation sub-feature -(security review Finding 2 — normative).** The create FFI is **seedless** (it drives a -`MnemonicResolverCoreSigner`, not a resident `Wallet`), so there is no `&Wallet` to -`derive_extended_private_key` on for the real host — v1 must add a raw-scalar export on the -resolver, exactly mirroring the sanctioned precedent -`export_auto_accept_private_key(&path) -> SecretKey` (`mnemonic_resolver_core_signer.rs:353`, -`ContactCryptoProvider` `contact_requests.rs:63`). **The new `export_invitation_private_key(&path)` -MUST gate on the full path** `comps.len()==5 && comps[0]==9' && comps[2]==5' && comps[3]==3'` — -**not** merely `comps[2]==5'`, because feature `5'` is shared with identity-registration -(`5'/0'`,`5'/1'`), top-up (`5'/2'`), etc.; a loose gate would let a caller exfiltrate the user's -**own** identity-funding keys. Add a negative test mirroring -`export_auto_accept_private_key_gates_to_the_auto_accept_path`. - -**Never persist the key.** Because it is HD-derived, the inviter re-derives it from the seed -whenever it re-packages or reclaims. Storage tracks only funding index + outpoint (§4.2). The -returned URI (which *contains* the plaintext key) is treated as a secret end-to-end: no logging, -no analytics, sensitive-pasteboard flag on the Swift side (§8 Finding 3). - -> **This export hook is v1 critical path, not a follow-up (feasibility Finding 5, BLOCKING).** -> Production/example-app wallets are **seedless at steady state** (`Wallet::new_external_signable`, -> no root key — `persistence.rs:158-163`); only the *first-ever* session has a resident seed. So -> the "derive from a resident `Wallet`" idea is a **dead end**: create a wallet Monday (seed -> resident), relaunch Tuesday (external-signable) → tap "Create invitation" → -> `wallet.derive_extended_private_key(path)` errors and the existing -> `export_auto_accept_private_key` rejects the `5'/3'` path (it gates to `16'`), so **no link can -> be produced.** The fix is the new gated `export_invitation_private_key` on -> `MnemonicResolverCoreSigner` + a `ContactCryptoProvider`-style method (seedless + seed impls, -> cf. `contact_requests.rs:63/188`) + its FFI — a dedicated implementation slice (§13 slice 2). - ---- - -## 6. The `dashpay://invite` link envelope — a single versioned blob - -> **SUPERSEDED (2026-07-13, §0.1):** the shipped envelope is the legacy query format -> (`du`/`assetlocktx`/`pk`/`islock` — see §0A), not this blob. -> Kept for the design rationale it records (secret handling, caps, transport notes still apply). - -**Decision: one opaque, versioned payload** behind a `dashpay://invite?data=` -deep link (keeping the reference's `dashpay://invite` scheme name for familiarity), **not** the -reference's six loose query params. Rationale in §7. The payload is a small versioned blob in a -**hand-rolled little-endian binary encoding** (deliberately *not* serde/bincode — the crate's -`serde` feature is optional and off, and `AssetLockProof` is internally-tagged so bincode-serde -rejects it), so the envelope can evolve without breaking older links. The as-built wire order -(see `crypto/invitation.rs`) is: - -```text -wire = version:u8 // = 0 - ‖ voucher_key:[u8; 32] // one-time ECDSA private key (secret; zeroized) - ‖ expiry_unix:u32(LE) // ADVISORY, IS-scoped (§5.1); not consensus - ‖ inviter_present:u8 // 0 = none, 1 = InviterInfo follows - [ identity_id:[u8; 32] - ‖ username:len-prefixed // DPNS name (whom the invitee's contactRequest targets) - ‖ display_present:u8 [ display_name:len-prefixed ] ] - ‖ asset_lock:len-prefixed // InstantSend proof (§5.1) — embeds tx + islock; LAST, length-prefixed - // NO auto-accept dapk — v1 sends a normal contactRequest, invitee-confirmed (§2) -``` -- Serializing the `InstantAssetLockProof` directly means the link **embeds the full funding tx + - islock**, so the invitee needs **no L1 tx fetch** (an improvement over the reference, which - carried only the txid). Link size is a few hundred bytes → base58 ~a few hundred chars: fine - for a deep link and a QR. -- **Length-cap the `data=` param before decode (§8 Finding 5, LOW).** The base58-**char** cap on - the input *before* decoding is the DoS mitigation (mirrors the `dapk` cap in - `parse_dashpay_contact_uri`). Note: `AssetLockProof`'s consensus bincode decode is **already - bounded and panic-free** on arbitrary bytes (dashcore `MAX_VEC_SIZE`, finite cursor, all - `Result`-based — verified), so the residual is only "a huge blob is fully buffered," which the - pre-decode char cap closes. A fuzz test is cheap insurance, not a blocker. -- The codec pair in `crypto/invitation.rs` is - `encode_invitation_uri(voucher_key: &SecretKey, asset_lock: &AssetLockProof, expiry_unix: u32, - inviter: Option<&InviterInfo>) -> Result` and - `parse_invitation_uri(uri: &str) -> Result`, fully unit-tested (round-trip + - every malformed rejection). A plain `https://…` fallback host can wrap the same `?data=` for - users without the app installed — deferred (no hosting in v1; see §6.1). - -### 6.1 Transport security & the custom-scheme limitation - -The `data=` payload is a **bearer credential**: whoever reads the plaintext link controls the -voucher and can claim (front-run) it. Because the app registers the `dashpay://` **custom URL -scheme**, any other app that also registers `dashpay` can intercept an invite link on the same -device and steal the claim. The load-bearing mitigation is therefore **economic, not transport**: -`MAX_INVITATION_DUFFS` caps the loss at 0.26 DASH, and the inviter can reclaim an unclaimed voucher -(best-effort race). The advisory expiry does **not** bound a leak (a leaked-link holder ignores it). - -A hardened production transport would use **Universal Links** (HTTPS + a hosted -`apple-app-site-association`, `associated-domains` entitlement) or another verified handoff so the -OS can't hand the link to an impostor app. That is **out of scope for this example app** — it -needs hosting infrastructure the sample doesn't have, and the amount cap already bounds the blast -radius — but it is the recommended path for the production wallet and is tracked as a follow-up. -The `?data=` shape is transport-agnostic, so moving from the custom scheme to a Universal Link is a -routing change, not an envelope change. - ---- - -## 7. Interop decision — ~~RESOLVED: ship our own self-contained envelope~~ - -> **REVERSED (2026-07-13, §0.1):** the as-built codec adopts the reference wallets' legacy -> query format for field-level cross-claimability with dash-wallet iOS/Android. The analysis -> below (dead FDL delivery, JS SDK never had invitations) remains accurate — only the -> conclusion changed, by owner decision, once cross-wallet claimability was prioritized. -Research (research-reference, primary sources) settled this: -- The production iOS (DashSync) + Android (dash-wallet) wallets use an **identical plaintext - URL-query payload**: `du` (username), `display-name`, `avatar-url`, `assetlocktx` (**txid - only**, 64-hex), `pk` (**WIF** private key), `islock` (hex InstantLock). The invitee **fetches - the full funding tx from L1 by txid**, then registers using the embedded islock. -- That link was distributed via **Firebase Dynamic Links**, which **Google shut down - 2025-08-25** — the hosted `invitations.dashpay.io/link` short-links now **404**. So even the - production wallets' *share layer is already broken* and must be reworked. -- **The JS SDK never had an invitation API** — invitations existed only in the two native apps. - -**Conclusion:** there is little value matching a legacy wire format whose delivery mechanism is -dead. We ship our own **self-contained, versioned** envelope (§6). The **only** things we must -NOT diverge on are the **on-chain / consensus** semantics — the DIP-13 `3'` derivation and the -islock / asset-lock-proof shapes Platform consensus accepts — because those are what actually -interoperate. This mirrors the auto-accept spec's "iOS-first, DIP-faithful where defined, -normative-for-us where silent" stance. (If byte-interop with a future reworked DashWallet is ever -required, matching is a localized codec change; the on-chain acts already interoperate.) - ---- - -## 8. Security -*(Folds a 4-lens security review: no CRITICALs — the core crypto is sound; findings are must-fix -hardening + honest-framing fixes. Verified-clean floor: in-flight IdentityCreate is -non-malleable, double-claim is deterministic, the invitee never risks its own funds.)* - -- **Consensus trust anchor (why this is safe at all).** Platform validates the IdentityCreate's - outer signature against the **asset-lock output's P2PKH public-key hash** - (`identity_create/state/v0/mod.rs:222-245`) and the identity id is `hash(outpoint)` — so a - network observer who does *not* hold the voucher key cannot swap in their own keys and steal an - in-flight claim, and two racers target the *same* id (consensus commits exactly one). Every - claim-theft attack reduces to **"who holds the link."** The invitee's own identity keys sign - the per-key witnesses separately. -- **Bearer credential — the load-bearing leak mitigation is the amount cap + reclaim, NOT the - expiry (Rust-security-review LOW-2 honesty fix):** - - **Amount cap enforced in Rust (Finding 4).** `create_invitation` rejects - `amount_duffs > MAX_INVITATION_DUFFS` — the *actual* bound on a leaked link's blast radius - (a direct FFI caller / headless host / UI bug can't exceed it). Never UI-only. - - **Expiry is a UX / reclaim signal, not a leak bound.** A malicious *finder* of a leaked link - holds the voucher key + proof and can submit directly, **ignoring the honest UI's expiry - check** — so `expiry_unix` does not bound a leaked-link window. What it *does* do: (a) stop an - **honest** invitee from submitting an about-to-go-stale IS proof (§5.1), and (b) give the - inviter a clear reclaim-after signal. Advisory, not consensus. (The FFI sets a sensible - default expiry from `MAX_INVITATION_TTL_SECS`; clamping it in Rust is symmetry, not security.) - - **Single-use** (asset lock consumed on first claim → deterministic reject thereafter), funds - are the inviter's to give; the inviter can race to **reclaim** an unclaimed voucher (a race it - can lose if already leaked — §8 Finding 6). -- **The link is plaintext key material — treat the URI as secret end-to-end (Finding 3).** The - create FFI returns the URI (which *contains* the voucher key) as a C string that flows through - Swift + a `dashpay://invite` deep-link handler (handlers routinely log URLs) + clipboard - (iOS Universal Clipboard syncs across devices) + the share sheet. Requirements: **no logging / - no analytics** of the URI; secret/`Zeroizing` types Rust-side; a **sensitive-pasteboard** flag - Swift-side; the voucher key is **never persisted** (re-derived from `funding_index`, §5.3). -- **Inviter self-claim / front-run is a real griefing/DoS vector against the invitee (Finding 6 — - honesty fix).** *Not* "no third-party risk." The inviter can front-run or reclaim after handoff, - denying the invitee onboarding mid-flow with no signal it was the inviter's doing. No fund theft - (funds are the inviter's), but real denial. Likewise **"reclaim = revocation" is a race the - inviter can lose** if the link already leaked — reclaim is best-effort, and the advisory expiry - is the actual bound. Documented as an accepted, honestly-stated limitation. -- **Untrusted proof on claim — validate before submit (Finding 5, LOW after re-verify).** The - `AssetLockProof` bincode decode is already bounded/panic-free; the §6 pre-decode length cap is - the DoS mitigation (keep it). The genuinely useful part is **fail-fast UX, not a security gap**: - cheap **local pre-submit checks** — the proof is an **Instant** proof (§5.1), the advisory - expiry is not past, and the **voucher pubkey-hash ∈ the selected credit output** - (`proof.output() → credit_outputs[output_index]`) — so a malformed/hostile/stale link fails with - a clear error instead of an opaque consensus reject. The - credit-output-pubkey binding is itself consensus-enforced, so this cannot be *bypassed* to steal; - it only improves the error. -- **Unauthenticated envelope (Finding 7 — documented, no v1 fix).** Nothing signs the bundle, so a - MITM on the *link channel* can substitute the whole invite. Blast radius is limited (the - contact only forms toward whatever inviter identity is in the link; an attacker can at most make - the invitee contact the attacker's own identity — achievable with a normal contact request - anyway). Reduces to "bearer-link trust = channel trust"; envelope signing wouldn't help (the - channel is the trust root). -- **Privacy (Finding 8, LOW).** Because id = `hash(outpoint)`, the inviter knows the invitee's - future identity id before they claim, and that id is inviter-chosen. Noted. -- **Malformed / hostile link:** every field size-capped before decode; a bad link fails loudly - with no side effects. - ---- - -## 9. Decisions (RESOLVED — owner, 2026-07-08) -1. **Proof type: InstantSend** (§5.1). Fast create, self-contained link; staleness covered by a - short IS-scoped advisory expiry (claim refuses past-expiry), not an IS→CL upgrade in v1. -2. **Contact-bootstrap: opt-in on both ends.** Inviter ticks "send a contact request back to me" - (→ inviter info in the link); the invitee is *asked* "establish contact with \?" at - claim and only then is a normal contactRequest sent. In v1. No auto-accept dapk (§8 Finding 1). -3. **Inviter persistence: proper wallet-persister integration** (§4.2) — a first-class - `invitations` table + changeset + `PersistentInvitation` SwiftData model, not a KV blob. In v1. -4. **Link scheme:** our own self-contained versioned blob (§7). -5. **Amount / TTL:** Rust-enforced `MAX_INVITATION_DUFFS` (default a sensible identity-reg + - small-balance amount; confirm exact duffs during spikes) and `MAX_INVITATION_TTL` bounded to - the **IS validity window** (default ~24h) since the proof is InstantSend. - ---- - -## 10. Failure modes -- **Insufficient inviter balance to fund the lock** → create fails pre-broadcast, funds - untouched (reservation released — existing `create_funded_asset_lock_proof` rejection path). -- **InstantSend lock never arrives at create** → `create_funded_asset_lock_proof`'s 300s IS wait - elapses and (for a fresh tx) it surfaces an error; the tracked lock is resumable (inviter can - retry or reclaim). We do **not** force a CL upgrade (§5.1). -- **Stale IS proof (claimed too late)** → the advisory expiry makes the claim refuse *before* the - IS lock could be rejected by Platform; the inviter re-creates. (Extending the window via an - invitee-side IS→CL upgrade is a post-v1 enhancement.) -- **Invitee claims an already-claimed / inviter-front-run link** → Platform rejects (lock - consumed); claim returns a clear "invitation already used" error; no identity created. (This is - also the inviter-front-run griefing outcome, §8 Finding 6.) -- **Malicious inviter hands a mismatched/IS/expired proof** → caught by the claim pre-submit - checks (§4.1 step 1 / §8 Finding 5) → fail loud, no blind submit. -- **Claim interrupted after identity created but before contact-bootstrap sent** → the identity - exists (self-heals into the invitee's IdentityManager on next re-sync); the contact request is - re-sendable (idempotent — the send path adopts an existing friendship). Not a data-loss path. -- **Malformed / truncated / oversize link** → parse/size-cap error, no side effects. -- **Invitee has no seed / can't derive identity keys** → claim fails before any network act. -- **Voucher never claimed AND inviter loses seed (§8 Finding 9, LOW)** → L1 Dash stranded in the - lock (asset locks are one-way). Mitigated by HD re-derivation from `funding_index` — this stays - a generic "lost your seed" problem, not invitation-specific. - ---- - -## 11. Spikes (before implementation — task #11) -1. **S1 — raw-key claim end-to-end (offline):** in a `rs-platform-wallet` integration test, - build an asset lock at `IdentityInvitation`, derive the voucher key, and drive - `put_to_platform_and_wait_for_response_with_private_key` against a mock/echo SDK to confirm - the proof + raw-key + invitee-identity-signer triple registers an identity. Confirms §5.2. -2. **S2 — seedless voucher-key export + path gate:** add `export_invitation_private_key(&path)` - on the resolver/provider mirroring `export_auto_accept_private_key` - (`mnemonic_resolver_core_signer.rs:353`), and prove the gate: it exports for - `9'/coin'/5'/3'/idx'` and **rejects** `9'/coin'/5'/0'/…` (identity-auth), `…/5'/1'/…` (reg - funding), `…/5'/2'/…` (top-up) — the Finding-2 negative test. Confirms §5.3. -3. **S3 — create keeps the IS proof + persistence round-trip:** confirm - `create_funded_asset_lock_proof(IdentityInvitation)` returns an **Instant** proof for a fresh - tx (no auto-upgrade), and that an `InvitationChangeSet` round-trips through the persister - (`created` row readable back). Confirms §5.1 + §4.2. -4. **S4 — link envelope codec:** implement + unit-test `encode/parse_invitation_uri` - (round-trip + malformed) — cheap, do first. - ---- - -## 12. Test / verification plan -- **Rust unit:** invitation URI codec (round-trip + every malformed rejection incl. the - pre-decode length cap); voucher blob round-trip; the **export-path-gate negative test** (§5.3 / - S2, Finding 2 — the blocking one: exports `5'/3'`, rejects `5'/0'`,`5'/1'`,`5'/2'`,`16'`); - create-invitation **rejects `amount > MAX_INVITATION_DUFFS` and `expiry > now+MAX_TTL`** - (Finding 3/4); claim **pre-submit checks reject** a non-Instant proof and a voucher-pubkey ∉ - credit-output (Finding 5 — fail-fast); expired-link rejection. (Optional insurance: a fuzz test - that `parse_invitation_uri` on arbitrary bytes never panics — not a blocker, decode is already - bounded.) -- **Rust integration (`rs-platform-wallet`):** the S1 offline flow as a permanent test; the - create→export→re-derive-from-`funding_index` round-trip (recovery); reclaim-unused path. -- **FFI:** null/oversize/bad-URI input validation; create→parse round-trip; claim marshaling - (identity handle inserted, id out); assert the URI is not emitted to logs. -- **Swift:** `build_ios.sh` green; wrapper unit tests for encode/decode boundaries. -- **Testnet funded e2e (task #13):** fund an inviter wallet via the **built-in faucet** - (Wallet → Receive → "request from testnet", `TestnetFaucetService` → `faucet.thepasta.org`) → - register the inviter identity + DPNS name → `create_invitation` → parse the link in a **second** - wallet with no funds → `claim_invitation` → assert the invitee identity exists on Platform and - (if bootstrap) the contact auto-establishes after the inviter's drain. This is the acceptance - gate. Can run headless (Rust integration against testnet) and/or two-simulator on-device. -- **On-device (two sims):** create on sim A, claim on sim B, contact appears on both. -- **QA contract:** the scenarios from §4.5. - ---- - -## 13. Commit slicing (implementation order) -1. `crypto/invitation.rs` codec (payload struct + `encode/parse_invitation_uri` + length cap) + - tests (S4). -2. **Voucher-key export (v1 critical path — feasibility Finding 5):** gated - `export_invitation_private_key` on `MnemonicResolverCoreSigner` (gate `9'/coin'/5'/3'/idx'`) + - `ContactCryptoProvider`-style method (seedless + seed impls) + the path-gate negative test (S2). - Without this the seedless host cannot produce a link at all. -3. `network/invitation.rs` create (slice-2 export + keep IS proof + amount/expiry caps) + claim - (raw-key submit wrapped in CL-height retry + Instant-proof pre-submit checks + optional - invitee-confirmed contactRequest) helpers + unit tests (S1). -4. **Inviter persistence (§4.2):** `invitations` migration + `InvitationChangeSet` + status sync. -5. FFI `platform_wallet_create_invitation` (core signer only) / `_claim_invitation` - (`establish_contact` param) + tests (marshaling mirrors `identity_registration_funded_with_signer.rs`). -6. swift-sdk wrappers on `ManagedPlatformWallet` + `PersistentInvitation` SwiftData model (**via - `swift-rust-ffi-engineer`**). -7. SwiftExampleApp: create sheet (amount + "send request back" checkbox), claim sheet (with the - "establish contact with \?" prompt), `InvitationsView` list, + `dashpay://invite` - deep-link handler (`Info.plist` scheme + `.onOpenURL`). -8. QA-contract rows (TEST_PLAN.md §4.10 DP-12+). -9. Testnet e2e evidence + docs (`SPEC.md` Milestone 5 as-built, `DIP_CONFORMANCE_GAPS.md` row). - ---- - -## 14. Multi-agent spec-review resolutions (2026-07-08) -Four research streams (wallet/SDK/Swift/reference) + three adversarial spec reviews -(feasibility / security / scope). Folded: -- **Feasibility — core mechanic CONFIRMED** (claim independence proven at `v0_methods.rs:65-78`; - create/CL/FFI confirmed). **One blocker: seedless voucher-key export** — the resident-`Wallet` - idea is a dead end (production wallets are `new_external_signable`); promoted to **v1 critical - slice 2** (§5.3, §13). Should-fixes folded: bounded CL wait (§5.1/§4.1), claim submit wrapped in - CL-height retry (§4.1), create FFI drops the spurious identity signer (§4.3). -- **Security — no CRITICALs.** Two blockers folded: (1) the **dapk TTL contradiction** → - auto-accept dropped, plain contactRequest bootstrap (§2); (2) **export path-gating** to - `9'/coin'/5'/3'/idx'` with a negative test (§5.3). Hardening folded: Rust amount cap, advisory - voucher expiry, secret/no-log URI (§8 Finding 3/4); honesty fixes (self-claim = griefing/DoS, - reclaim = a race — §8 Finding 6). Proof-parse worry **downgraded to LOW** on re-verify (bincode - is already bounded; the length cap is the mitigation; pre-submit checks are fail-fast UX). -- **Reference/interop** — the production link format is dead (FDL shutdown); ship our own - self-contained versioned envelope, preserve only on-chain semantics (§7). -- **Scope** — scope levers threaded (single versioned blob §6; reuse over new code throughout). -- **Owner decisions (2026-07-08, sync gate):** (1) **InstantSend** proof, not ChainLock — - staleness handled by a short IS-scoped expiry (§5.1); (2) contact-bootstrap **opt-in on both - ends** — inviter checkbox + invitee "establish contact?" prompt (§2, §4.1); (3) **proper - wallet-persister** integration for invitations, not a KV blob (§4.2). All in v1. diff --git a/docs/dashpay/DIP_CONFORMANCE_GAPS.md b/docs/dashpay/DIP_CONFORMANCE_GAPS.md deleted file mode 100644 index 530c6bbea8c..00000000000 --- a/docs/dashpay/DIP_CONFORMANCE_GAPS.md +++ /dev/null @@ -1,359 +0,0 @@ -# DashPay — DIP-15 + DIP-16 conformance gaps (code-verified audit) - -> **Purpose.** A from-scratch re-audit of the DashPay implementation against the -> canonical [DIP-15](https://github.com/dashpay/dips/blob/master/dip-0015.md) -> (DashPay) and [DIP-16](https://github.com/dashpay/dips/blob/master/dip-0016.md) -> (Headers-First SPV synchronization — DIP-15 §12 is built on it), cross-checked -> against the **actual code** on `feat/dashpay-m1-sync-correctness` (not the -> self-reported status in `SPEC.md`/the backlog (now dashpay/platform#4020)). The goal was to catch anything the -> DIPs require that is **missing, stubbed, or only partially wired**, and to -> separate genuine gaps from deliberate divergences. -> -> **Date:** 2026-06-24. **Method:** six parallel code-reading passes (xpub/ECDH/ -> key-purpose; accountReference/multi-account/DoS/label; coreHeight/block-rescan/ -> sync-window; profile/contactInfo/DPNS; dash-spv rescan capability; full DIP-16 -> 9-step sync ordering), each citing `file:line`, plus direct verification of the -> contested findings. SPV evidence is from the pinned `dash-spv` rev `b4779fc` -> (`rust-dashcore`), which the platform-wallet drives via `spv/runtime.rs`. -> -> **Headline.** The DashPay (DIP-15) core flow **fully conforms** and is in places -> *ahead* of the reference clients. The SPV layer (DIP-16) implements the hard -> parts for real (headers-first + checkpoints + masternode-list/quorum -> verification + compact filters) but **deliberately diverges** from the DIP's -> literal phasing (event-driven parallel managers, BIP157 instead of BIP37 for the -> confirmed path, L2 decoupled from L1). Only **two** DIP-15 gaps are -> under-tracked (one a real incoming-payment-loss risk); the rest are correctly -> tracked as deferred (blocked on external resources) or are well-reasoned -> divergences. The §12.6 block-rescan gap (§1.1) turns out to need only a small -> wallet-side trigger — the rescan engine already exists in dash-spv. - ---- - -## 0. Conformance matrix (by DIP-15 section) - -| DIP-15 area | § | Verdict | Evidence | -|---|---|---|---| -| Encrypted xpub = 69-byte compact `fp(4)‖cc(32)‖pk(33)` → 96-byte ciphertext | 8.6 | ✅ **FULLY** | `rs-platform-encryption/src/compact_xpub.rs` (`COMPACT_XPUB_LEN=69`); send asm `network/contact_requests.rs:480-491`; SDK 96-byte assert `rs-sdk/.../contact_request.rs:311-316`; KAT `dip14.rs::compact_xpub_is_69_byte_dip15_plaintext_not_107_byte_encode` | -| ECDH `SHA256(((y&1)|2)‖x)` | 8.3 | ✅ **FULLY** | `rs-platform-encryption/src/ecdh.rs:16-26` + hand-recomputed KAT `:56-85` | -| `senderKeyIndex`/`recipientKeyIndex` purpose policy (liberal receive, ENCRYPTION send fallback, no permanent break on purpose mismatch) | 8.3 | ✅ **FULLY** | send sel `contact_requests.rs:846-871`; validator `crypto/validation.rs:141-251`; purpose-only ≠ broken `:90-92` + drain `:1743-1764` | -| Friendship path `m/9'/coin'/15'/0'/owner256/cp256/index`, DIP-14 256-bit non-hardened CKD | 8.9 | ✅ **FULLY** (account 0) | `crypto/dip14.rs`; byte-identical to dashj per `INTEROP_DESK_CHECK.md` | -| `profile` (displayName/publicMessage/avatarUrl/avatarHash/avatarFingerprint) | 9 | ✅ **FULLY** | `types/dashpay/profile.rs:85-123` — real SHA-256 hash **and** real 8-byte dHash; non-destructive update `network/profile.rs:319-378` | -| Batched profile fetch `$ownerId in [ids]` (counterparties of new requests) | 9.10 | ✅ **FULLY** | `network/profile.rs:738-812` (`In` + required `orderBy`) | -| `contactInfo` (ECB `encToUserId`, CBC `privateData`, `65536'/65537'`, ≥2-contacts gate, varint privateData) | 10 | ✅ **FULLY** | `crypto/contact_info.rs:45-48,232-283`; `rs-platform-encryption/src/contact_info.rs`; gate `network/contact_info.rs:548-556` | -| `accountReference` value + version-bump rotation on re-send | 7, 8.4 | ✅ **send** / ⚪ **receive ignores (by design)** | `account_reference.rs:41-51`; version bump `contact_requests.rs:514-547` | -| `$createdAt` incremental fetch with 10-min skew back-off | 8.8, 8.12 | ✅ **FULLY** | `SYNC_OVERLAP_MS=600_000` → `contact_requests.rs:770-776`; `StartAfter` paging `contact_request_queries.rs:54-108` | -| `$createdAtCoreBlockHeight` populated | 8.7 | ✅ **FULLY** | server-side `document_create_transition/v0/mod.rs:253-256`; client sends `None` `rs-sdk/.../contact_request.rs:478` | -| DPNS name↔identity resolve/search/cache | 11 | 🟡 **PARTIAL** | works (`network/dpns.rs:281-362`); QR-build doesn't fall back to on-chain name | -| **L1 block re-scan from `min(coreHeightCreatedAt)` on new contact** | **8.7, 12.6** | ❌ **MISSING** | never read to drive a rescan; SPV exposes no rescan entry point | -| `encryptedAccountLabel` (48–80B, padded, decrypted) | 8.5 | ✅ **FULLY** | send length-normalized in the crypto primitive (`account_label.rs`); receive decrypted + surfaced via `store_contact_account_label` (incoming-only) → `ContactDetailView` (SPEC.md Milestone 3) | -| `acceptedAccounts` + first-request bloom gating / flood mitigation | 8.4, 10.8 | ❌ **MISSING** | codec only; unpopulated + dropped on ingest | -| Multi-account contacts (`Account ≠ 0`) | 7.1, 8.9 | 🟡 **DEFERRED** | `account_index` hardcoded `0`; blocked on upstream | -| QR auto-accept (`autoAcceptProof`, `m/9'/5'/16'/expiry'`, BIP21/72 URI) | 8.13 | ✅ **FULLY** (iOS-first) | `crypto/auto_accept.rs`; see `QR_AUTO_ACCEPT_SPEC.md` | -| Invitations (asset-lock voucher + claim onboarding, DIP-13) | — | ❌ **NOT STARTED** | queued as "NEXT" in the backlog (dashpay/platform#4020) | - ---- - -## 1. Under-tracked gaps (the value of this audit) - -### 1.1 🔴 No L1 block re-scan from `coreHeightCreatedAt` on new contacts — DIP-15 §8.7 + §12.6 - -**Status: MISSING and not mentioned anywhere in the existing docs.** This is the -only finding with an incoming-**payment-loss** character. - -DIP-15 §8.7 / §12.6 require: when a wallet learns of a new contact request, it must -**resynchronize L1 blocks from the minimum `$coreHeightCreatedAt`** across the new -requests *after* inserting the new address spaces into its filters, so it doesn't -miss payments sent in the device-sync-speed-skew window (a payment that landed on a -DashPay address before that address was being watched). - -What the code actually does: -- `$createdAtCoreBlockHeight` **is** captured and persisted on every request - (`types/dashpay/contact_request.rs:38`), but is **never read** to drive a - re-request. No "minimum across new contacts" is computed anywhere. -- Both account-registration paths — `register_external_contact_account` - (`network/contacts.rs:389`) and `register_contact_account` (`:140`), called from - the G1b sweep at `network/contact_requests.rs:1630,1820` — watch **forward only** - and aren't even passed the height. -- A newly registered contact's addresses **do** enter the compact-filter match set - (`monitored_script_pubkeys` enumerates `all_accounts()`), but only from the - current scan pointer forward — nothing rewinds the pointer to backfill. - -Consequence: the `G1(b)` sync fix rebuilds the address *watch* on restore-from-seed, -but does **not** backfill *history*. An incoming DashPay payment that arrived before -the receiving account was (lazily) registered — restore-from-seed, second device, or -the offline-accept→pay window — can be silently missed until some unrelated full -rescan happens to cover it. - -**The fix is small — the rescan engine already exists.** dash-spv's `FiltersManager` -already performs a targeted backfill rescan whenever a wallet's `synced_height` drops -below the filter scan pointer: `tick` calls `wallets_behind(committed)`, takes the -min stale height, runs `reset_for_rescan()` + `start_download()`, and re-downloads -BIP157 filters from there, re-matches against the now-larger script set, and -re-requests the matching blocks (`dash-spv .../sync/filters/sync_manager.rs:213-236`, -`manager.rs:129-139`). So DIP-15 §12.6 is **a wiring task, not an SPV build**: -1. **platform-wallet (the actual gap):** when the G1b sweep registers a new DashPay - account, lower that wallet's `synced_height` to - `min($coreHeightCreatedAt over the just-built accounts) − 1`. The height is - already on the `ContactRequest`; the existing `FiltersManager` does the rest. -2. **one small upstream piece (`key-wallet-manager`):** `WalletInterface:: - update_wallet_synced_height` is **forward-only by contract** — "a value below the - current is silently ignored" (`wallet_interface.rs:127-129`). A backward rescan - needs a new guard-bypassing method (e.g. `reset_wallet_synced_height_to(id, h)`), - a small upstream change in the vein of rust-dashcore#813. (Optionally expose a - thin `DashSpvClient::rescan_wallet_from(id, h)` convenience wrapper; the - `SpvRuntime` would forward it.) - -Constraints to respect: the backfill floor is the checkpoint the headers were seeded -from (`manager.rs:192`), and the BIP157 filter-headers/filters for that range must be -re-downloadable from peers. Per DIP-15 §12.6, re-request slightly beyond the minimum -height and avoid re-requesting the final ~10 blocks near the tip. It is a genuine -correctness gap, but a contained one — see §6.4 for how it relates to the DIP-16 -filter layer. - -### 1.2 🟡 `encryptedAccountLabel` — the "DONE" padding fix is dead code - -**Status: PARTIAL, and it contradicts a backlog ("DONE + tests pin it") claim (now dashpay/platform#4020).** - -The backlog P1 item records label padding to ≥16 chars (commit `2419159bb3`) as done. In -reality: -- The padded helper `IdentityWallet::encrypt_account_label` + `pad_account_label` - (`network/account_labels.rs:19,49-64`) has **zero live callers** (verified by grep; - only its own unit tests reference it). -- The **live** path — FFI `platform_wallet_send_contact_request_with_signer` - (`rs-platform-wallet-ffi/src/dashpay.rs:236-269`) → `send_contact_request_with_external_signer` - (`network/contact_requests.rs:374`) → `sdk_writer` → rs-sdk — passes the host label - **raw**. The SDK encrypts it unpadded and hard-rejects `<48 || >80` bytes - (`rs-sdk/.../contact_request.rs:319-330`). A **1–15-character label therefore errors - the entire contact-request send** (16-byte plaintext block → 16 ciphertext + 16 IV = - 32 < 48). The FFI accepts a label, so this is reachable, not theoretical. -- The label is **never decrypted on receive**: the ingest path stores - `encrypted_account_label` as raw bytes (`contact_requests.rs:2515`) and nothing calls - `decrypt_account_label` (also dead code in `account_labels.rs:78-107`). The field is - effectively write-only. - -A later refactor (the seedless `ContactCryptoProvider`/`sdk_writer` seam) appears to -have orphaned the padded helper. - -**Resolution (2026-06-24) — send side ✅ fixed; receive surfacing 🟡 remaining.** -The DIP-15 length normalization now lives in the single primitive -`platform_encryption::{encrypt,decrypt}_account_label`: a short/empty label is -space-padded to clear the 48-byte floor **and** an over-long label is truncated (on a -char boundary) to stay under the 80-byte cap — so **no** host-supplied label can error -the broadcast anymore (the review caught that the floor fix alone left a symmetric -`>80` long-label failure). The dead `network/account_labels.rs` helper was deleted (it -duplicated the convention). Red→green test -`account_label_is_always_a_valid_48_to_80_byte_field` pins both bounds + multi-byte + -the exact-48 boundary. - -**Receive-side surfacing — RESOLVED (2026-06-24, 5-lens reviewed; folded into SPEC.md -Milestone 3).** The label is now decrypted in Rust at the two signer-bearing -register sites (drain `RegisterExternal` Ok-branch + `accept_register_external_validated`, -where the ECDH `shared` already lives) and stored on -`EstablishedContact.contact_account_label`. It is **direction-specific** — derived -strictly from the *incoming* request and projected onto the **incoming FFI row only** -(the outgoing row's label is one *we* sent and is never surfaced), so it does **not** -copy the symmetric `alias`/`payment_channel_broken` both-rows pattern. Decrypt -failures / non-printable garbage coerce to `None` (cosmetic — never breaks the -channel); rotation pre-clears the field so it never goes stale. Surfaced through -`ContactRequestFFI.contact_account_label` → `PersistentDashpayContactRequest -.contactAccountLabel` → a read-only "Their account" row in `ContactDetailView`. -Backfill of pre-feature contacts deferred (dev-only; DashPay unreleased). - -**On-device UAT (paloma, 2026-06-25) found a SECOND, decisive bug + fixed it.** -The receive-side surfacing above had nothing to decrypt because the **recurring -sweep's ingest parser `parse_contact_request_doc` silently dropped -`encryptedAccountLabel`** (it read `encryptedPublicKey` + `autoAcceptProof` but not -the label). The send always attached the label and the decrypt was always correct — -the label just never reached the recipient's stored request. (This audit's earlier -"ingest works" claim cited the *sent*-request parser at `:2515`, missing that the -*received* path uses `parse_contact_request_doc`.) **Fix:** the parser now reads -`encryptedAccountLabel`; the sender's local bookkeeping also stores it off the -broadcast doc; and `AddContactView` gained an optional "Account label" field so -labels can be sent in-app. Unit tests missed the bug (they built the incoming -request *with* the label, bypassing the parser) — now pinned by -`parse_contact_request_doc_carries_encrypted_account_label` (red→green). **Verified -full e2e on paloma:** send (48-byte label on-chain) → fresh sweep ingest -(`enc=48`) → accept decrypt (`contactAccountLabel="Bob savings acct"`, incoming row -only / outgoing null) → ContactDetail shows "Their account: Bob savings acct". - ---- - -## 2. Tracked-and-deferred gaps (acknowledged; blocked on external resources) - -These are real DIP-15 gaps, but the existing docs already record them with a correct -blocker — not oversights. - -| Gap | DIP-15 § | Blocker | Doc ref | -|---|---|---|---| -| **True multi-account (`Account ≠ 0`)** — `account_index` hardcoded `0` at the only send site (`contact_requests.rs:476`); friendship path structurally `…/15'/0'/…`. (Key *rotation* via version-bump **is** live.) | 7.1, 8.9 | upstream `rust-dashcore#813` (honor the `index` field) | backlog dashpay/platform#4020 P1/P2 | -| **`acceptedAccounts` + §10.8 flood mitigation** — varint codec carries the field, but publish hardcodes it empty (`network/contact_info.rs:499-506`) and `set_contact_metadata` (`managed_identity/contact_requests.rs:289-299`) **drops** it on ingest. No "first request → bloom filter, additional → require acceptance" gating. | 8.4, 10.8 | query-level DoS filter needs a registered contract change | backlog dashpay/platform#4020 Contract track | -| **Cross-device ignore sync** — ignore is local-only; a per-sender `contactInfo` leaks the ignored target (timing correlation, R1). | 10.7 | needs an encrypted field on the `profile` contract (governance) | backlog dashpay/platform#4020 Contract track | -| **DPNS-name on-chain fallback in QR auto-accept build** — `build_auto_accept_qr` (`rs-platform-wallet-ffi/src/dashpay.rs:801`) uses the locally-cached name; empty for imported/devnet identities. `resolve_name` exists but isn't called from the QR path. | 11 | none (small follow-up) | backlog dashpay/platform#4020 P3 | -| **DashPay Invitations** — asset-lock voucher + claim onboarding (DIP-13 sub-feature `3'`). | — | new feature (L1 funding + identity registration + deep-link) | backlog dashpay/platform#4020 "NEXT" | -| **Devnet/testnet e2e + full add→approve→pay XCUITest** | 11 | funded test harness | backlog dashpay/platform#4020, `SPEC.md` Part 7 | - ---- - -## 3. Deliberate divergences (correct decisions, not bugs) - -- **`accountReference` ASK28 byte order** uses the **iOS** convention - (`be(ASK[28..32])>>4`); iOS and Android genuinely disagree, and the field is a - sender-private one-time-pad the **recipient ignores** (`unmask_account_reference` is - only ever called by the sender's own re-send path), so there is no on-chain interop - break. Documented + KAT-pinned. -- **Reject → reversible local-only `ignore`** (per-sender mute), matching Android's - Accept/Ignore model. No on-chain artifact (R1 privacy). -- **Retained 78/107-byte xpub `decode()` fallback** in `network/contacts.rs:447-461` — - documented insurance for local-only legacy rows; never participates in on-wire - encoding (send only ever emits 69 bytes; the SDK rejects non-69 before encryption). - -### 3.1 Reference-client (dashj / kotlin-platform) source pointers - -For re-checking our behavior against the canonical Android stack — `dashpay/kotlin-platform` -(`org.dashj.platform.dashpay`, the live lib), `dashpay/dashj` (core crypto/keychains), -and `dashpay/dash-wallet` (the app: sync, UI, DAOs), all on `master`. (`android-dashpay` -is the **stale** predecessor, last push 2024-01 — do not diff against it.) The -reference-side anchors that pin each cross-client comparison: - -| Concern | Reference-client anchor | -|---|---| -| `accountReference` ASK28 byte order | `BlockchainIdentity.getAccountReference` = `wrapReversed(ASK).toBigInteger().toInt() ushr 4` (= `u32_le(ASK[0..4])>>4`; we use the iOS `be(ASK[28..32])>>4` — §3 above) | -| Friendship path (receive vs send account) | `FriendKeyChain.getContactPath` — `contact.getUserAccount()` (receive) / `getFriendAccountReference()` (send) | -| `contactRequest` pagination (drain past 100) | `Documents.getAll` loops `startAt = last.id` while `size >= 100`; `retrieveAll` ⇒ `limit(-1)` | -| High-water + 10-min skew overlap | `PlatformSyncService.kt:346-372`, `DashPayContactRequestDao.kt:50-54` (`MAX(timestamp)` per direction) | -| Batched contact-profile fetch | `updateContactProfiles` → `Profiles.getList` (chunks of 100, `whereIn $ownerId`) | -| Non-destructive profile update | `Profiles.replace` — read-modify-write (`profileData.putAll(currentProfile.toObject())`, then overlay) | -| `encryptedAccountLabel` padding | `padAccountLabel()` — pad to ≥16 chars with spaces, always emit | -| Recipient-key selection | kotlin = ENCRYPTION-first with AUTH/HIGH fallback | -| Sent-tx status (live, not stored) | derived from `TransactionConfidence` | -| tx→contact reverse (both directions) | `getFriendFromTransaction` scans sent + received pools | -| Account/keychain self-heal | `checkDatabaseIntegrity` | - -**Perceptual-hash caveat — do NOT write a cross-client exact-match test on -`avatarFingerprint`.** The dHash byte/bit layout coincidentally matches dashj, but the -pixel pipeline differs (greyscale **average vs luma-weighted**, resize filter, 9×9 vs -9×8), so fingerprints **will not be byte-identical cross-client**. That is inherent to -perceptual hashing — the fingerprint is used for Hamming distance, never equality — so a -cross-client exact-match assertion is wrong by construction. - ---- - -## 4. Correction to the existing docs - -- **`SPEC.md` G3 ("`accountReference` hardcoded to 0", deferred to M3) is STALE.** - Code verification shows the send path computes a **real** `accountReference` and - does **version-bump rotation** on re-send (`contact_requests.rs:514-551`, - `account_reference.rs:41-51`). Only the *account-number* multi-account case remains - at `0` (§2 above). The leftover comment `sdk_writer.rs:114` ("DashPay account - reference (currently 0)") is rotted and should be corrected. - ---- - -## 5. Where the implementation is *ahead* of the reference clients - -For calibration (don't "fix" these): -- A real `contactInfo` document type — `kotlin-platform`/`dashj` have **none**. -- A genuine 8-byte dHash `avatarFingerprint` (commonly stubbed/zeroed elsewhere). -- Hand-recomputed ECDH + 69-byte-xpub known-answer tests (not just doc-comment trust). -- Stricter sync re-entrancy/shutdown discipline and a more robust - `reconcile_incoming_payments` self-heal than dashj. - ---- - -## 6. DIP-16 (Headers-First SPV synchronization) conformance - -DIP-15 §12 requires sync to follow **DIP-16**. The SPV client lives in the -`dash-spv` crate (rev `b4779fc`), driven by `packages/rs-platform-wallet/src/spv/`. - -**Two architectural facts frame every verdict:** -1. dash-spv is **not** a literal 4-phase sequential state machine. It is an - **event-driven coordinator** that spawns 8 independent managers (block-headers, - filter-headers, filters, blocks, masternode, chainlock, instantsend, mempool), - each in its own tokio task, progressing reactively off a `SyncEvent` bus - (`dash-spv/src/sync/sync_coordinator.rs:33-62,197-250`). DIP-16's *phases* are - realized as concurrent managers, not ordered stages. -2. The **confirmed-tx receive path uses BIP157/158 compact filters** (pulled from - peers, matched locally against wallet scripts) — **not** BIP37 bloom. BIP37 - `filterload` exists *only* in the optional mempool (unconfirmed-tx) manager. - DIP-16 step 8 literally says "construct a bloom filter"; the implementation - substitutes BIP157 for the confirmed path — a deliberate, stronger-privacy - deviation. - -### 6.1 Conformance matrix (DIP-16 9-step + phasing + locator) - -| DIP-16 element | Verdict | Evidence (`dash-spv` unless noted) | -|---|---|---| -| Step 1 — chain height from **multiple** peers | ✅ IMPLEMENTED (uses `max`, not soft-consensus) | `network/pool.rs:105-151` | -| Step 2 — headers-first from checkpoints + chain/PoW validation | ✅ IMPLEMENTED | `chain/checkpoints.rs:158-725`; `sync/block_headers/pipeline.rs:56-113`; `validation/header.rs:17-46` | -| Step 3 — terminal masternode list + quorums | ✅ IMPLEMENTED | `sync/masternodes/sync_manager.rs:255`; `manager.rs:575` | -| Step 4 — intermediate MN lists to verify quorums | ✅ IMPLEMENTED | `sync/masternodes/sync_manager.rs:42-147,369` | -| Step 5 — verify quorums (real, not stubbed) | ✅ IMPLEMENTED | `sync/masternodes/manager.rs:487,577` | -| Step 6 — retrieve identities | 🟡 PARTIAL (independent, best-effort) | platform-wallet `manager/identity_sync.rs:76,397-437`; `wallet_lifecycle.rs:421` | -| Step 7 — retrieve platform data | ✅ IMPLEMENTED (independent timer) | platform-wallet `manager/dashpay_sync.rs:404-474` | -| **Steps 2–7 ordered in one phase** | ⚪ NOT MODELED (intentional) | `manager/mod.rs:103-195` — no cross-coordinator gating | -| Step 8 — compact-filter build (confirmed path) | ✅ IMPLEMENTED | `sync/filters/manager.rs:654,734,779` | -| Step 8 — **DashPay/contact addresses in filter** | ✅ IMPLEMENTED (once receival acct exists) | `key-wallet .../wallet_info_interface.rs:302-316`; reg `network/contacts.rs:223,233` | -| Step 8 — filter set on **all** peers | 🟡 PARTIAL (eventually-all, looped not atomic; BIP37 mempool only) | `sync/mempool/sync_manager.rs:173-193`; `network/mod.rs:174-176` | -| Step 9 — sync-from block / wallet-birthday checkpoint | ✅ capability present; birthday auto-drive soft | `chain/checkpoints.rs:138-145`; `sync/filters/manager.rs:171-175` | -| Block-locator shape ("last 10 + prev checkpoint + genesis") | 🟡 PARTIAL (single-hash, checkpoint-segmented) | `network/mod.rs:102-107`; `sync/block_headers/segment_state.rs:67-69` | -| Named 4-phase state machine | 🟡 PARTIAL (generic `SyncState`, no named phases) | `sync/progress.rs:9-18` | - -No `todo!`/`unimplemented!`/stub markers were found in the masternode/quorum or -header/filter sync paths — the hard cryptographic parts are real. - -### 6.2 DIP-16 deviations (audit findings — mostly intentional, none are dead stubs) - -1. **No 4-phase ordering; L2 sync decoupled from L1.** Identity/platform sync run on - independent timers with zero gating on SPV header/masternode completion. Notably, - platform-data **proof verification does not consume the local SPV quorum state** — - `SpvRuntime::get_quorum_public_key` exists but no sync manager calls it; proofs go - through the SDK/DAPI path. This is the largest DIP-16 conformance gap, but appears - to be a deliberate UX choice (don't block L2 on full L1 sync). -2. **Single-hash block locator** instead of the DIP's multi-hash fork-recovery - locator. Safe under checkpoint-segmented parallel download (each segment anchor is - a validated checkpoint/tip), but a literal non-conformance with no genesis/previous - fallback hashes in a request. -3. **Height aggregation is `max`, not soft-consensus** — one dishonest peer - advertising a high `start_height` inflates the sync target. Minor, but worth a note. -4. **BIP37 mempool filter is set per-peer in a loop**, not an atomic broadcast. -5. **Birthday-by-timestamp start is available but not obviously auto-driven** from - platform-wallet (`get_sync_checkpoint(creation_time)` exists; default start resumes - from persisted `synced_height`/config height). -6. **DashPay address coverage is conditional** — addresses are watched only *after* - the contact's funds-bearing receival account is registered; there is no pre-emptive - watch. This is the DIP-16-layer facet of the §1.1 gap (below). - -### 6.3 DIP-16 does NOT mandate the §12.6 rescan — confirmed - -Direct fetch of DIP-16 confirms it specifies **no** "re-request blocks from height N -after the address set grows" mechanism. Its filter section says only that Platform-app -address spaces "can be used" in the filter and "a client should set this filter on all -connected peers." The rewind-on-new-address behavior is a **DIP-15 §12.6** obligation -layered on the DIP-16 base — so §1.1 is a DIP-15 gap, not a DIP-16 one. - -### 6.4 The rescan engine already exists at the DIP-16 filter layer - -Relevant to §1.1: dash-spv's filter manager **already implements** the rescan -machinery — `reset_for_rescan()` rolls `committed_height` back and replays when a -wallet's `synced_height` drops below scan progress, and an in-flight `rescan_batch` -re-scans when new gap-limit scripts appear mid-batch -(`sync/filters/manager.rs:129-139,468-505`). It is just never *triggered* for the -DashPay backfill case, because nothing lowers `synced_height` to the contact's -`$coreHeightCreatedAt`. That is why §1.1's fix is a small wallet-side trigger plus one -upstream guard-bypass method, not an SPV build. - ---- - -## 7. Recommended priority - -1. **§1.1 coreHeight block re-scan (DIP-15 §12.6)** — the only untracked - correctness/payment-loss item. Now scoped small: a wallet-side `synced_height` - rewind on new-contact registration + one upstream `reset_wallet_synced_height_to` - method; the dash-spv `FiltersManager` rescan engine already does the rest. -2. **§1.2 account-label** — ✅ DONE. Send length-normalization fixed; receive-side - decryption + UI surfacing implemented (incoming-only) per - SPEC.md Milestone 3. DIP-15 §8.5 now fully conforms. -3. **DIP-16 deviations (§6.2)** — mostly intentional; if any is worth hardening it is - #1 (consider sourcing proof-verification quorum keys from the local SPV engine) and - #3 (height soft-consensus). Track, don't rush. -4. Everything in §2 stays blocked on its external dependency; §3 is intentional. diff --git a/docs/dashpay/IDENTITY_KEY_SCALAR_ELIMINATION_SPEC.md b/docs/dashpay/IDENTITY_KEY_SCALAR_ELIMINATION_SPEC.md deleted file mode 100644 index 885c213a433..00000000000 --- a/docs/dashpay/IDENTITY_KEY_SCALAR_ELIMINATION_SPEC.md +++ /dev/null @@ -1,493 +0,0 @@ -# Identity-Key Scalar Elimination — derive-sign-destroy for discovered keys - -Status: draft, rev 2 (review must-fixes folded) -Scope: removes the carried 32-byte ECDSA scalar -(`IdentityKeyEntry.private_key` / `KeyWithBreadcrumb.verified_scalar`) from the -identity-key discovery → persist → sign flow, replacing it with a -derive-sign-destroy model in which the per-key secret only ever exists in the iOS -Keychain (as the wallet seed), is derived on demand at sign time, and is never -carried across the Rust→FFI→Swift boundary or stored per-key. - -Supersedes the earlier carried-scalar storage posture (the carry-the-verified-scalar -fix this spec reverses). Aligns with the seed-elimination §4.9-blocker item 3 design -and the sibling decision to stop persisting the DashPay friendship xpub and re-derive -on load. - -> **Review outcome (rev 2).** Four independent reviewers (feasibility, scope, -> security, crypto/domain) audited rev 1 against the code. The crux correctness -> claim — pubkey-compare is byte-for-byte equivalent to -> `validate_private_key_bytes(scalar)` — was **verified exact** for both -> `ECDSA_SECP256K1` (33-byte compressed compare) and `ECDSA_HASH160` -> (`ripemd160_sha256(pubkey)` vs `key.data()`; the double-hash gotcha does **not** -> apply because we compare `key.data()`, not `entry.public_key_hash`). No key is -> wrongly authorized and no wallet-derivable key is wrongly dropped to watch-only. -> The must-fixes folded below are all about the **migration**, where removing the -> carried scalar trades an *intrinsic* scalar↔pubkey binding for a *trusted-path* -> binding — the real lockout surface. The five load-bearing corrections: -> **(MF-1)** the backfill reads the Keychain **metadata blob** (named fields), not -> a parse of the account-string label; **(MF-2)** the backfill **and** the sign -> path **re-derive the pubkey at the path and compare to the row's -> `publicKeyData`** before trusting/signing — a present-but-wrong path otherwise -> signs silently and consensus rejects it (silent lockout); **(MF-3)** the -> scalar-field-deletion gate is a **runtime migration stamp**, not a dev-time -> check, and the field-deleted build still runs the Keychain-driven backfill on -> first launch (the Keychain survives a SwiftData store rebuild); **(MF-4)** the -> SwiftData column addition must be a verified-clean lightweight migration (or an -> explicit `MigrationStage`), since this app has historically rebuilt the V1 store -> from scratch; **(MF-5)** the schema delta is exactly `walletId` + -> `identityDerivationPath`, and the FFI layout guard recomputes to exactly **184**. - ---- - -## 1. Problem - -Identity-key discovery carries a verified 32-byte ECDSA scalar **Rust → FFI → -Swift** so the iOS Keychain stores it directly: - -- `discovery.rs::derive_key_breadcrumbs` derives a candidate scalar per on-chain - key; `breadcrumb_decisions` gates each via - `IdentityPublicKey::validate_private_key_bytes(scalar, network)` and carries the - reproducing scalar as `KeyWithBreadcrumb.verified_scalar` - (`changeset.rs:391`). -- It rides `IdentityKeyEntry.private_key` (`changeset.rs:434`, `#[serde(skip)]`, - redacting `Debug`), is copied by value into `IdentityKeyEntryFFI.private_key:[u8;32]` - (`identity_persistence.rs:312`, with `private_key_is_some`), and Swift writes the - 32 bytes to the Keychain via `storeCarriedIdentityKey` → - `KeychainManager.storeIdentityPrivateKey` under account - `identity_privkey..`. -- At sign time the `keyType < 5` branch reads that stored scalar back out - (`KeychainSigner.swift::lookupIdentityPrivateKey` → `ffiSign`). - -This is not a resident keystore — the scalar transits same-tick, is `Zeroizing`, -never serialized, never written to SQLite, and **no Rust signing path reads it** -(Rust signs via the external `VTableSigner`). It exists because the imported-wallet -flow ran `createWallet` (→ discovery) *before* `storeMnemonic`, so the old -Swift re-derive-from-mnemonic produced 23/23 watch-only keys; carrying the -already-verified scalar removed Swift's mnemonic dependency (commit `c567981c46`). - -**Why change it anyway.** The carried scalar is still a raw secret crossing the FFI -ABI and stored per-key at rest. The clean model — already proven for platform -addresses — keeps the only secret (the seed) in the Keychain and derives each -signing key on demand. Removing the carry yields: the raw scalar never crosses the -FFI; one fewer class of secret at rest (no per-key scalar); Rust discovery never -materializes the scalar at all (verify via public key). - -**The hard part.** This is the single most safety-critical path in the wallet: a -wrong key-storage/resolution change **locks users out of signing**, and the change -is only *validatable* against the iOS Keychain signer (iOS-gated). The design must -make the cutover non-lockout **by construction**. - ---- - -## 2. Current vs. target architecture - -### Current (carried scalar) - -``` -discovery.rs derive candidate scalar ── validate_private_key_bytes(scalar) ──┐ - │ verified_scalar: Some -changeset KeyWithBreadcrumb.verified_scalar ─► IdentityKeyEntry.private_key│ -FFI IdentityKeyEntryFFI.private_key[32] + private_key_is_some (by value) -Swift store storeCarriedIdentityKey ─► Keychain item identity_privkey.. (32 raw bytes) -Swift sign keyType<5 ─► lookupIdentityPrivateKey (read scalar back) ─► ffiSign -``` - -### Target (derive-sign-destroy) - -``` -discovery.rs derive candidate PUBLIC key ── compare to on-chain pubkey ──┐ (no scalar materialized) - │ breadcrumb: Some, scalar: ABSENT -changeset KeyWithBreadcrumb{ key, breadcrumb } (no verified_scalar) -FFI IdentityKeyEntryFFI{ …, wallet_id, identity_index, key_index } (breadcrumb only — already crosses) -Swift store persistIdentityKeys ─► PersistentPublicKey.{walletId, identityDerivationPath} (queryable columns) -Swift sign keyType<5 ─► resolveIdentityKeyContext ─► dash_sdk_sign_with_mnemonic_resolver_and_path - (resolve mnemonic in-callback ─► derive ─► sign ─► zeroize; only the signature returns) -``` - -The breadcrumb `(wallet_id, identity_index, key_index)` **already crosses the FFI** -(`identity_persistence.rs` `wallet_id`/`identity_index`/`key_index`, gated behind -`wallet_id_is_some` / `derivation_indices_is_some` — present whenever the entry has -a breadcrumb, independent of the scalar). It is currently used only to build the -Keychain account label and is then discarded. So `persistIdentityKeys` must guard -the new-column write on `entry.derivationIndices != nil` (the snapshot already -exposes `derivationIndices` and `walletId`). - ---- - -## 3. Chosen approach - -Mirror the **platform-address** derive-sign-destroy path, which already works -end-to-end, and reuse its Rust primitive. - -### 3.1 Discovery verifies via public key (no scalar) - -The DIP-9 identity-auth path `m/9'/coin'/5'/0'/ECDSA'/identity_index'/key_index'` -is fully hardened, so the candidate pubkey must still be derived from a master -xpriv (resolved on demand inside the FFI, wiped before return — already the case -for external-signable wallets). The change is local to discovery: compute the -candidate **compressed public key** -(`derive_ecdsa_identity_auth_keypair_from_master(..).public_key`) and compare to -the on-chain key — `key.data() == pubkey` for `ECDSA_SECP256K1`, -`ripemd160_sha256(pubkey) == key.data()` for `ECDSA_HASH160` — instead of calling -`validate_private_key_bytes(scalar)`. **Do not populate `candidate_scalars`.** - -This is byte-for-byte the same decision `validate_private_key_bytes` makes -internally; it just never needs the scalar to leave the derive function. The -transient master resolution in discovery is **not** what we eliminate — the -persisted/carried per-key scalar is. - -An uncompressed externally-registered ECDSA key (65-byte on-chain `data()`) -correctly stays watch-only because the wallet only ever derives the **compressed** -form, so the compare gracefully fails — *not* because Platform forbids uncompressed -identity keys (it does not; `UncompressedPublicKeyNotAllowedError` is an asset-lock -constraint only). Stating the real reason avoids a future "optimization" that -assumes uncompressed identity keys can't exist on-chain. - -### 3.2 Sign via the existing resolver primitive (no new FFI) - -`dash_sdk_sign_with_mnemonic_resolver_and_path` -(`rs-platform-wallet-ffi/src/sign_with_mnemonic_resolver.rs`) is **generic over the -derivation path and ECDSA-only**. Every wallet-derivable identity auth key is ECDSA -(guaranteed by the discovery verify gate), so the identity signing branch calls -this primitive **unchanged** with the DIP-9 identity-auth path string. No new FFI -signing entry point is required. - -**Sign-time binding check (MF-2).** Today's stored-scalar lookup is *intrinsically* -correct — the scalar it returns was the one verified to reproduce that exact pubkey -at discovery. The resolver path loses that: it routes by `wallet_id_bytes` and -derives at `identityDerivationPath`, but never confirms the result matches the key -being signed for. A mis-mapped resolver slot or a stale path would derive a -*different, valid* scalar and produce a signature consensus silently rejects. So the -identity sign path **must verify the derived compressed pubkey equals the row's -`publicKeyData` before signing** (derive-and-compare inside the FFI, or a -pubkey-preview call before `sign`), and fail loud on mismatch rather than emit a -wrong-key signature. This restores the intrinsic binding the stored scalar gave for -free. - -`signIdentityKeyOnDemand` and `signPlatformAddressOnDemand` differ only in their -SwiftData lookup; the `sigBuf` setup + FFI call + error handling are identical. -Extract a shared private `signOnDemandWithContext(walletId:path:expectedPubKey:data:)` -so the two branches don't duplicate ~30 lines (the identity branch passes -`expectedPubKey`, enabling the MF-2 check; the address branch passes `nil`). - -### 3.3 Persist the breadcrumb as queryable columns - -`PersistentPlatformAddress` carries `walletId: Data` + `derivationPath: String` and -the signer reads them in `resolvePlatformAddressContext`. `PersistentPublicKey` -carries only `privateKeyKeychainIdentifier` — no breadcrumb. Add **exactly two** -columns: `walletId: Data?` and `identityDerivationPath: String?`. Both are required -by the resolver FFI — `wallet_id_bytes` is a mandatory parameter (it keys the -mnemonic-resolver callback), and the full path string is what -`dash_sdk_sign_with_mnemonic_resolver_and_path` derives at. **Do not** add separate -`identityIndex`/`keyIndex` columns — they are redundant with the path string (the -inverse of `getIdentityAuthenticationPath`) and the path is authoritative. -`persistIdentityKeys` writes the two columns, building the path with -`KeyDerivation.getIdentityAuthenticationPath` — the same path -`storeCarriedIdentityKey` already computes and currently throws away — and **always -overwrites** when the FFI breadcrumb is present, so a backfilled value and a -fresh-persister value for the same row are byte-identical (a string-format drift -between the two would otherwise desync the stored path from what the resolver -re-derives). - -**Migration safety (MF-4).** Two optional columns are the additive shape SwiftData -lightweight migration handles — *but* this app's `DashModelContainer` runs -`DashSchemaV1` with `stages: []` and has historically rebuilt the dev store from -scratch on any model-hash change. Adding columns must be confirmed to -lightweight-migrate **a real persisted production store on upgrade** (not just a -fresh install); if SwiftData instead rebuilds the store, every -`PersistentPublicKey` row vanishes and the §5 backfill has no rows to heal. Either -verify the clean lightweight path on a real upgrade or bump to `DashSchemaV2` with -an explicit additive `MigrationStage`. Because the backfill is **Keychain-driven** -(§5) and the Keychain survives a SwiftData rebuild, a wiped row set degrades to -re-materialization from the Keychain rather than to lockout — but the migration -shape must still be pinned, not assumed. - -### 3.4 Alternatives rejected - -- **Keep the carried scalar (status quo).** Rejected: leaves a raw secret crossing - the ABI and a per-key secret at rest; diverges from the platform-address model - and the broader "derive on load, don't persist secrets" direction. -- **Re-derive in Swift from the mnemonic at sign time (the pre-`c567981c46` - path).** Rejected: this is exactly the anti-pattern `swift-sdk/CLAUDE.md` forbids - (Swift running `mnemonic → seed → path → key`), and it was the original - imported-identity bug. The resolver primitive keeps the derive inside Rust with - only the path crossing. -- **New identity-specific FFI signing call carrying `(identity_index, key_index)`.** - Rejected as unnecessary now: the generic path primitive already covers every - ECDSA identity key. (A non-ECDSA wallet-derivable identity key — none exist today - — would be the only reason to add one.) - ---- - -## 4. Phased delivery - -**Hard ordering invariant:** the FFI/changeset scalar field is deleted **last**, -only after every already-materialized identity key is proven to sign via the -resolver path on a real device. Deleting it earlier — even though Rust still -compiles — bricks the still-scalar-based Swift signer = lockout. - -### Phase 1 — headless-safe (Rust + FFI only; additive, removes nothing Swift reads) - -Gate: `cargo test -p platform-wallet` + `-p rs-platform-wallet-ffi` green; -cross-compile `aarch64-apple-ios-sim`. No ABI change. - -1. Compute the pubkey-compare decision in `breadcrumb_decisions` and **assert in - tests** it is byte-equivalent to the scalar decision (`reproduces`). This is - *not* a second parallel derive: the candidate pubkey is already a byproduct of - the existing keypair derivation, so the only change is what the decision logic - compares. Production emission is unchanged — `verified_scalar: Some` still - ships in Phase 1 because Swift still reads it; the switch to pubkey-only happens - in Phase 2 step 6. -2. Test the identity DIP-9 path through `dash_sdk_sign_with_mnemonic_resolver_and_path` - (the existing happy-path test already uses `m/9'/1'/5'/0'/0'/0'/0'` — confirm it - covers the identity case or augment it; this step may be test-only, no new code). -3. Test that the FFI breadcrumb round-trips with `private_key_is_some == false`. - -Steps 1–3 have no internal ordering dependency and can land as one atomic Rust commit. - -### Phase 2 — iOS-gated (Swift + on-device), ordered - -1. Add `walletId` + `identityDerivationPath` columns to `PersistentPublicKey` (both - optional ⇒ SwiftData lightweight migration; existing rows get `nil`; no data - loss). -2. Write the breadcrumb columns in `persistIdentityKeys` — **both** old (Keychain - scalar) and new (columns) during the transition window. -3. **Backfill migration (the lockout defense — see §5).** One-time, Keychain-driven, - self-verifying pass populating the new columns from each `identity_privkey.*` - item's `IdentityPrivateKeyMetadata` blob, re-deriving the pubkey at the path and - comparing to the row's `publicKeyData` before trusting it — no network, no seed. -4. Re-route the `keyType < 5` signer branch through `signIdentityKeyOnDemand` + - `resolveIdentityKeyContext` (mirroring the platform-address pair), calling the - existing resolver primitive. **Resolver-first with legacy fallback:** a row with - no `identityDerivationPath` falls back to `lookupIdentityPrivateKey → ffiSign`; - every fallback hit is logged (count only, no key material). -5. **Validation gate:** transitional build on a funded testnet wallet; exercise - signing for every identity (DPNS register, profile set, contact-request - send+accept, payment); confirm **zero fallback hits** after backfill. -6. **Only after the gate:** flip discovery to pubkey-only; delete - `storeCarriedIdentityKey`, the Swift scalar copy/scrub, and the legacy signer - path; then delete the scalar field from FFI (recompute the layout guard from - `const _: [u8; 224]` to exactly `const _: [u8; 184]` — removing - `private_key_is_some` at offset 184 + `private_key: [u8; 32]` + trailing padding - drops bytes 184–223, alignment stays 8) and changeset; regenerate the header; - rebuild. - -**Runtime deletion gate (MF-3) — not a dev-time gate.** Step 6 must not assume every -device passed through the transitional build. A user can upgrade straight from the -scalar-only build to the field-deleted build, skipping the backfill; their rows have -`identityDerivationPath == nil` and there is no legacy signer left → lockout. So: -(a) the field-deleted build **still runs the Keychain-driven backfill on first -launch** (the Keychain items survive any SwiftData rebuild, so the path is -recoverable even with no transitional run); and (b) deleting the *legacy signer -fallback* is gated on a **persisted migration stamp** (set only after a backfill -pass leaves zero un-pathed rows / after the scalar Keychain items are purged), so a -binary without the stamp keeps the fallback and schedules a backfill. The fallback, -not just the field, is the safety net — it lives until the stamp guarantees the -resolver path covers 100 % of the live key set at runtime. - ---- - -## 5. Migration / back-compat — the lockout defense (new design) - -**Danger:** existing installs have scalars in the Keychain under -`identity_privkey..` and `PersistentPublicKey` rows whose -new breadcrumb columns are `nil` after the lightweight migration. If signing flips -to resolver-only and a row has no `identityDerivationPath`, that key is unsignable -→ the user is locked out of an already-working identity. - -Three layers, all required: - -1. **Keychain-metadata-driven, self-verifying backfill (no network, no seed) - (MF-1, MF-2).** Each `identity_privkey.*` Keychain item carries a first-class - `IdentityPrivateKeyMetadata` JSON blob (`kSecAttrGeneric`) with named `walletId`, - `derivationPath`, `identityIndex`, `keyIndex`, `publicKey` fields — - `KeychainManager.identityPrivateKeyAccount` already walks every row and decodes - it. The one-time backfill reads `walletId` + `derivationPath` from the **blob** - (not from a parse of the `identity_privkey..` account - label, which is fragile and has a legacy no-`walletId` variant). It is driven by - the **Keychain item set**, not the SwiftData row set, so it heals even if the - SwiftData store was rebuilt (MF-4) — it can re-create the `PersistentPublicKey` - linkage from the blob's `publicKey`. Crucially it is **self-verifying**: before - writing `identityDerivationPath`, re-derive the compressed pubkey at that path - (resolver / pubkey-preview FFI) and require it to equal the row's - `publicKeyData`; on mismatch leave the column `nil` so the row falls through to - the fallback / re-discovery rather than to a wrong-key sign. A non-zero count of - parse-or-verify failures is a **hard blocker** on the deletion gate (it is not - enough to test that signing works — every existing item must be accounted for). -2. **Resolver-first with legacy fallback.** During the transition the signer tries - the resolver path first and falls back to the stored scalar when the breadcrumb - is absent, so a row can always sign via at least one path. Non-lockout by - construction. (Note: the fallback covers an *absent* path, not a *present-but- - wrong* one — MF-2's sign-time binding check is what catches the latter.) -3. **Re-discovery heals the rest.** Any row not covered by (1) re-materializes on a - from-0 rescan (now writing the breadcrumb columns, needing only the resolver - mnemonic). Surface a "re-scan identities" affordance. - -**Population that blocks deletion (MF-3 / R5).** A wallet with a materialized scalar -but **no readable mnemonic** (the import-flow case that motivated the carried scalar -originally) can never reach zero resolver-fallbacks — the resolver needs the -mnemonic. For that population the legacy scalar fallback must be **retained**, or an -explicit mnemonic-import step required, before its scalar field/path can be removed. -The "zero fallback hits" criterion is otherwise unachievable for exactly the wallets -the carried scalar was introduced to serve. - -The legacy fallback and the scalar field are deleted **only** after the runtime gate -(MF-3) confirms, per device, that the resolver path covers the full live key set — -not merely after a dev-time test pass. - ---- - -## 6. Failure modes & risk register - -| ID | Risk | Mitigation | -|----|------|------------| -| R1 | Pubkey-verify diverges from scalar-verify → a key wrongly breadcrumbed (signable with an unauthorized key) or wrongly watch-only | Phase-1 byte-equivalence test over `ECDSA_SECP256K1` + `ECDSA_HASH160` + foreign key; assert decision set identical to `breadcrumb_decisions` | -| R2 | Existing rows lack breadcrumb columns → resolver-only signer locks out already-materialized keys | §5: backfill migration + resolver-first-with-fallback + zero-fallback gate before deleting legacy | -| R3 | Wrong network → wrong DIP-9 path → wrong key / sign failure | Resolve network from `PersistentWallet` exactly as `storeCarriedIdentityKey` does; unit-test the built path equals the Keychain account string | -| R4 | ABI/layout drift on field removal → `EXC_BAD_ACCESS` in the callback | Recompute `const _: [u8; N]` + the byte-offset comment; cbindgen regen; round-trip test | -| R5 | Resolver mnemonic missing/locked at sign time (watch-only, biometric-gated, import-only wallet with a scalar but no mnemonic) → sign fails where the stored scalar succeeded; zero-fallback gate unachievable for this population | Existing `mnemonicMissing` UX; **retain the legacy scalar fallback for the no-mnemonic population** (§5) — do not delete its scalar/path until a mnemonic-import step runs | -| R6 | A non-ECDSA wallet-derivable identity key appears (future) → the ECDSA-only resolver rejects it | Pre-existing constraint, **not introduced by this change** (the scalar path is already ECDSA-only via `validate_private_key_bytes`); discovery only breadcrumbs ECDSA; a non-ECDSA key would need a new resolver FFI | -| R7 | Old per-key scalars linger in the Keychain indefinitely → negates "one fewer secret at rest" | **Required (not optional)** purge of `identity_privkey.*` items, gated on the same runtime stamp; also doubles as the MF-3 migration-completed signal | -| R8 | **Skip-version upgrade lockout** — user jumps from scalar-only to field-deleted build, skipping the backfill; rows have `identityDerivationPath == nil` and no legacy signer remains | MF-3: field-deleted build still runs the **Keychain-driven** backfill on first launch (Keychain survives a SwiftData rebuild); legacy-fallback deletion gated on a persisted migration stamp, not a dev-time check | -| R9 | **Wrong-mnemonic / present-but-wrong-path silent signing** — resolver routes by `wallet_id_bytes` and derives a valid-but-wrong scalar; signature fails only at consensus, no local diagnostic | MF-2: derive-and-compare the pubkey to the row's `publicKeyData` before signing (and in the backfill before trusting a path); fail loud on mismatch | -| R10 | SwiftData store rebuild on column add wipes `PersistentPublicKey` rows → backfill has nothing to heal | MF-4: verify clean lightweight migration on a real upgrade or declare a `MigrationStage`; backfill is Keychain-driven so a wiped row set degrades to re-materialization, not lockout | - ---- - -## 7. Test / verification plan (red→green) - -**Phase 1 (headless):** -- `discovery.rs` `#[cfg(test)] mod tests` — `breadcrumb_via_pubkey_equivalence`: - derive a multi-key identity, run both the scalar path and the new pubkey path, - assert identical `(breadcrumb, key)` decisions and that the pubkey path carries no - scalar; extend the existing HASH160 + non-reproducible-key tests. **Red first** - (new path wrong), then green. This is the most important Rust correctness gate (R1). -- `sign_with_mnemonic_resolver.rs` tests — `signs_with_dip9_identity_auth_path` - (identity path string, verify signature). Confirms no new FFI is needed. -- `identity_persistence.rs` tests — breadcrumb survives `from_entry` with - `private_key_is_some == false`; (Phase-2 step 6) update the size guard to the new - `N` and assert no scalar field. -- `rs-platform-wallet-storage` round-trip — `IdentityKeyWire` still has no secret - field; compiles after `private_key` removal. - -**Phase 2 (iOS/sim):** -- `KeychainSignerIdentityResolveTests` — `signIdentityKeyOnDemand` resolves - `(walletId, identityDerivationPath)` from a seeded row and signs via a mock - resolver; `canSign` is true with breadcrumb+mnemonic, false without. **Plus the - MF-2 binding test:** a resolver returning a *wrong* mnemonic (or a row with a - *wrong* path) yields a **sign-failure, not a wrong-key signature** — assert the - pre-sign pubkey compare rejects it. -- `PersistentPublicKeyBreadcrumbMigrationTests` — seed a Keychain - `identity_privkey.*` item (with its `IdentityPrivateKeyMetadata` blob) + a row; - run backfill; assert columns are populated **from the blob** and that the - backfilled path **re-derives to the row's `publicKeyData`** (MF-2 self-verify); - assert a blob whose path does *not* re-derive to its pubkey leaves the column - `nil`; assert a row whose backfilled value and a fresh-persister value are - byte-identical; assert a row without a Keychain item falls back to legacy during - the transition; assert backfill works with the **SwiftData row set empty** - (Keychain-driven, MF-4). -- `BackfillCoverageTests` — every existing `identity_privkey.*` item is accounted - for; a non-zero parse-or-verify-failure count blocks the deletion gate (MF-1). -- `persistIdentityKeys` writes the two columns from a breadcrumb-only - (scalar-absent) entry, guarded on `derivationIndices != nil`. - -**On-device acceptance (the real gate):** -- Transitional build over an existing store with already-materialized identities → - backfill runs → exercise signing for every identity (DPNS / profile / contact - request / payment) → **zero legacy-fallback hits** logged. -- Fresh wipe → import funded testnet seed → discover (pubkey-verify, no scalar - carried) → sign → success. -- Wrong-seed rejection (`verify_seed_binds`) still holds. - -**Field deletion is gated:** `git grep verified_scalar` / -`IdentityKeyEntry.private_key` empty only after the zero-fallback on-device gate -passes. If fallbacks > 0, **do not delete** — the scalar is the safety net until the -resolver path is proven for 100 % of the live key set. - ---- - -## 8. Critical files - -- `packages/rs-platform-wallet/src/wallet/identity/network/discovery.rs` — - pubkey-verify in `breadcrumb_decisions` / `derive_key_breadcrumbs`; equivalence test. -- `packages/rs-platform-wallet-ffi/src/sign_with_mnemonic_resolver.rs` — reuse the - signing primitive; add an **optional `expected_pubkey` param** for the MF-2 - derive-and-compare-before-sign check (the address path passes none); add a - DIP-9-path sign test + a wrong-seed-rejects test. -- `packages/rs-platform-wallet-ffi/src/identity_persistence.rs` — (Phase 2 step 6) - delete `private_key` / `private_key_is_some`; recompute the layout guard - `const _: [u8; 224]` → `const _: [u8; 184]` (drops bytes 184–223; align stays 8); - update the byte-offset comment. -- `packages/rs-platform-wallet/src/changeset/changeset.rs` — (Phase 2 step 6) delete - `KeyWithBreadcrumb.verified_scalar` + `IdentityKeyEntry.private_key`. -- `packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/identity_ops.rs` - — `add_keys`: drop the scalar from the destructure + entry literal. -- `packages/swift-sdk/Sources/SwiftDashSDK/Persistence/Models/PersistentPublicKey.swift` - — add `walletId` + `identityDerivationPath`. -- `packages/swift-sdk/Sources/SwiftDashSDK/Persistence/DashModelContainer.swift` — - pin the lightweight migration / `MigrationStage` (MF-4); host the persisted - migration stamp gating legacy-path deletion (MF-3). -- `packages/swift-sdk/Sources/SwiftDashSDK/Security/KeychainManager.swift` — - Keychain-driven backfill reads the `IdentityPrivateKeyMetadata` blob (`walletId`, - `derivationPath`); required purge of `identity_privkey.*` after the gate (R7). -- `packages/swift-sdk/Sources/SwiftDashSDK/FFI/KeychainSigner.swift` — - `signIdentityKeyOnDemand` + `resolveIdentityKeyContext` mirroring the - platform-address pair; fallback dispatch; delete `lookupIdentityPrivateKey` / - `ffiSign` in step 6. -- `packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletPersistenceHandler.swift` - — write breadcrumb columns; delete `storeCarriedIdentityKey` + the scalar - copy/scrub. - ---- - -## 9. As-built notes (what shipped vs. this spec) - -The additive, fallback-protected work (Phase 1 + Phase 2 steps 1–5) shipped on -`feat/dashpay-identity-key-scalar-elimination`. Two deliberate deviations from the -rev-2 design above, plus what is explicitly **not** done: - -- **Resolver FFI accepts `ECDSA_HASH160` (key_type 2), not just SECP256K1.** Full - scalar deletion is impossible otherwise — discovery breadcrumbs both ECDSA key - types. The MF-2 binding disambiguates by `expected_key_data` length: 33 bytes = - compressed-pubkey equality, 20 bytes = `ripemd160_sha256(pubkey)` equality. The - param is nullable (the address path passes none). This widens §3.2's "reuse the - primitive unchanged." -- **The backfill self-check is canonical-path-from-indices, not a pubkey - re-derivation.** §5 layer 1 specified re-deriving the pubkey at the path and - comparing to `publicKeyData`; that needs the seed, which the backfill - deliberately avoids. Instead it rebuilds the canonical DIP-9 path from the - metadata's `(network, identityIndex, keyIndex)` and requires it to equal the - stored `derivationPath` (rejecting format drift), and **relies on the sign-time - MF-2 binding as the real guard** — a present-but-wrong path yields - `ERR_PUBKEY_MISMATCH` at sign time → a logged `IDENTITY_SIGN_FALLBACK`, never a - wrong-key signature. A non-zero backfill failure count is still surfaced. -- **Phase 2 step 6 — the carried scalar IS deleted; the legacy fallback signer is - KEPT (partial by design).** `KeyWithBreadcrumb.verified_scalar`, - `IdentityKeyEntry.private_key`, and `IdentityKeyEntryFFI.{private_key, - private_key_is_some}` are removed (FFI layout guard recomputed `224` → `184`; the - `from_entry` copy + free-scrub gone). Discovery now derives-verifies-**drops** the - candidate scalar instead of emitting it — verification is still - `validate_private_key_bytes`, the scalar just never leaves discovery. The legacy - Keychain-scalar signer (`lookupIdentityPrivateKey` / `ffiSign`) is **retained** so - keys already materialized on existing installs still sign: the §5 lockout defense - is preserved *without* removing the legacy path. New keys are resolver-only. - Merged into `feat/dashpay-m1-sync-correctness` (`fb11783706`; commits `930c100c64` - deletion + `fa1098c081` test). -- **The funded-testnet zero-`IDENTITY_SIGN_FALLBACK` gate (§4 step 5 / §7) was - un-runnable and was substituted.** idb cannot actuate this app's SwiftUI - confirmation controls (the toolbar Create/Cancel, the backup-seed "I wrote it - down" switch), and the macOS-click fallback needs Accessibility / Automation / - Screen-Recording TCC the tmux-hosted shell lacks — so the automated UAT could not - even create a wallet. With explicit sign-off ("delete the field if it passes"), - the gate was replaced by a HEADLESS Swift integration test - (`IdentityResolverSignIntegrationTests`): it seeds a real mnemonic in - `WalletStorage` + a consistent breadcrumb row and asserts `signIdentityKeyOnDemand` - → resolver → on-demand derive → MF-2 binding → valid 65-byte signature (plus a - wrong-path → `.failure`). It stays green *after* the deletion — proof the resolver - path signs through the Swift layer with no stored scalar. Verified end to end: - platform-wallet 314 + FFI (125/26/9) tests, Swift IdentityResolverSign 2/2 + - IdentityKeyBreadcrumb 4/4 + 30 Identity tests, clippy clean, SwiftExampleApp sim - BUILD SUCCEEDED. Because the legacy fallback was retained, the `DashModelContainer` - migration-stamp (MF-3) stays deferred (it only matters once the fallback is - removed). Still unproven: a live on-device discover→materialize→sign over an - existing store. diff --git a/docs/dashpay/INTEROP_DESK_CHECK.md b/docs/dashpay/INTEROP_DESK_CHECK.md index 205b40c5f7c..4a42145d843 100644 --- a/docs/dashpay/INTEROP_DESK_CHECK.md +++ b/docs/dashpay/INTEROP_DESK_CHECK.md @@ -4,8 +4,8 @@ > transient `research/` directory was trimmed — older citations of > "`research/06`" refer to this file. Kept in the shipped docs because it is > the evidence base for the consensus-facing wire-format decisions -> (69-byte compact xpub, key-purpose envelope, ASK28 byte order) cited by -> `SPEC.md` and `DIP_CONFORMANCE_GAPS.md`. +> (69-byte compact xpub, key-purpose envelope, ASK28 byte order) the wallet +> implements. Research date: 2026-06-10 (Milestone 1, task 5 — verify-only). Question: do THIS stack's DashPay wire formats match the reference clients (iOS DashSync, @@ -463,3 +463,48 @@ is unbound, and mobile recipients have no DECRYPTION key for us to select when s (e.g. legacy 2024 AUTHENTICATION docs), degrade to a warning/skip — do **not** permanently mark the payment channel broken, since on-chain history demonstrably contains nonconforming-but-honest documents. + +## Addendum (2026-08-11): the receive side accepts legacy key purposes + +The alignment recommendation above is superseded on the receive side by +[#4372](https://github.com/dashpay/platform/pull/4372). A mainnet wallet with 29 +contacts established through the legacy Android/dashj client had 27 inbound +requests that reference the recipient's AUTHENTICATION or TRANSFER key, and the +documents are immutable, so rejecting them left those contacts unpayable. The +rules now are (rs-sdk `platform/dashpay/contact_request.rs`): + +- **Send (documents we create):** unchanged. The sender key must be ENCRYPTION + (`sender_key_purpose_is_valid`) and the recipient key DECRYPTION or ENCRYPTION + (`recipient_key_purpose_is_valid`). +- **Receive (documents already on chain):** the recipient key may be DECRYPTION, + ENCRYPTION, AUTHENTICATION or TRANSFER + (`recipient_key_purpose_is_acceptable_on_receive`), and the sender key + ENCRYPTION or AUTHENTICATION (`sender_key_purpose_is_acceptable_on_receive`). + Any other purpose is a mismatch that is skipped and retried, never a + permanently broken channel. + +## Re-checking against the reference clients + +The Android sources to compare against are `dashpay/kotlin-platform` +(`org.dashj.platform.dashpay`, the live library), `dashpay/dashj` (core crypto +and keychains) and `dashpay/dash-wallet` (the app: sync, UI, DAOs), all on +`master`. `android-dashpay`, cited in the source table at the top, is the stale +predecessor (last push 2024-01); do not diff against it. + +| Concern | Reference-client anchor | +|---|---| +| `accountReference` ASK28 byte order | `BlockchainIdentity.getAccountReference` = `wrapReversed(ASK).toBigInteger().toInt() ushr 4` (= `u32_le(ASK[0..4])>>4`; we use the iOS `be(ASK[28..32])>>4`, see section (3)) | +| Friendship path (receive vs send account) | `FriendKeyChain.getContactPath`: `contact.getUserAccount()` (receive) / `getFriendAccountReference()` (send) | +| `contactRequest` pagination (past 100) | `Documents.getAll` loops `startAt = last.id` while `size >= 100`; `retrieveAll` means `limit(-1)` | +| High-water + 10-minute skew overlap | `PlatformSyncService.kt` (high-water sync), `DashPayContactRequestDao.kt` (`MAX(timestamp)` per direction) | +| Batched contact-profile fetch | `updateContactProfiles` calls `Profiles.getList` (chunks of 100, `whereIn $ownerId`) | +| Non-destructive profile update | `Profiles.replace`: read-modify-write (`profileData.putAll(currentProfile.toObject())`, then overlay) | +| `encryptedAccountLabel` padding | `padAccountLabel()`: pad to at least 16 chars with spaces, always emit | +| Recipient-key selection | ENCRYPTION first, with an AUTHENTICATION/HIGH fallback | +| Sent-tx status | derived live from `TransactionConfidence`, not stored | +| Transaction to contact (both directions) | `getFriendFromTransaction` scans the sent and received pools | +| Account/keychain self-heal | `checkDatabaseIntegrity` | + +Never assert that `avatarFingerprint` bytes match across clients: the dHash +pixel pipelines differ, so fingerprints are compared by Hamming distance (see +`calculate_dhash_fingerprint`). diff --git a/docs/dashpay/KOTLIN_INVITATIONS_SPEC.md b/docs/dashpay/KOTLIN_INVITATIONS_SPEC.md deleted file mode 100644 index 58ee9fa7d11..00000000000 --- a/docs/dashpay/KOTLIN_INVITATIONS_SPEC.md +++ /dev/null @@ -1,442 +0,0 @@ -# DashPay Invitations (DIP-13 3') — Kotlin/Android Port Spec - -Port the shipped iOS invitation feature (create + claim + reclaim + sent-invitations -persistence, PR #4041, `docs/dashpay/DIP15_INVITATIONS_SPEC.md`) to the Kotlin SDK and -KotlinExampleApp, on branch `feat/kotlin-dashpay-invitations` (base `v4.1-dev`). - -Status: **v3 — synced with owner (2026-07-22), all open questions resolved (§10); -slices 1–5 implemented** (JVM + cargo gates green; instrumented + funded-testnet -QA are the remaining environment-bound gates). (v2 was the post-review draft.) -Reference implementation: `packages/swift-sdk` + SwiftExampleApp (source of truth per the -parity doctrine in `packages/kotlin-sdk/CLAUDE.md`). -Feature behavior spec: `docs/dashpay/DIP15_INVITATIONS_SPEC.md` §0/§0A/§0B (as-built truth). - ---- - -## 1. Problem - -The Kotlin DashPay migration (K1–K3, `KOTLIN_MIGRATION_SPEC.md`) ported all 10 DashPay -screens and declared invitations out of scope (§8) because iOS hadn't shipped them yet. -iOS has since shipped the full feature. Today the Kotlin stack is deliberately -**fail-closed**: `rs-unified-sdk-jni/src/persistence.rs:174` sets -`on_persist_invitations_fn: None`, so the backend never attests the `INVITATIONS` -capability and `create_invitation`'s up-front -`persistence_capabilities().contains(INVITATION_CREATION)` gate refuses to run on -Android — rather than mint a voucher whose one-time bearer key could be re-exported -after a restart (the defect class fixed by 55937e15c1 on iOS). - -Every layer is pre-seamed for this port: -- All three invitation FFI entry points (`create`/`claim`/`parse`) plus the two reclaim - exports already exist in `rs-platform-wallet-ffi` and are consumed by iOS through the - same C ABI. -- The JNI natives for resume/top-up already declare a `consumeInvitationVoucher` - parameter (currently guard-rejected when `true`); the Kotlin *public* wrappers hardcode - `false` and structurally gate invitation locks out (see §3.1 — they need new variants, - not a flag flip). -- Room schema v8 is reserved for invitations (`PARITY.md:49`; DB is at v7). -- The handler already attests 3 of the 4 capability bits in `INVITATION_CREATION` - (`ATOMIC_CHANGESETS 0x01 | ASSET_LOCK_FUNDING_INDICES 0x04 | WALLET_RESTORE 0x80`); - only `INVITATIONS (0x02)` and its callback are missing. - -**Goal:** feature parity with iOS invitations — same flows, same persisted shape, same -crash-safety semantics, same testTags — with **zero changes to `rs-platform-wallet` and -`rs-platform-wallet-ffi`** (shared logic stays shared; the port is bindings + persistence -+ UI only). - -## 2. What does NOT need porting (all shared Rust, already on this branch) - -- Link codec (`dashpay://invite?du=…&assetlocktx=…&pk=…&islock=…`, emit-strict / - parse-lenient, applink host, WIF + byte-order leniency) — `crypto/invitation.rs`. -- Create orchestration: amount caps (`MIN=300_000` / `MAX=5_000_000` duffs), capability - gate, funding-index persist+flush **before broadcast** (abort on failure), invitation - row persisted **after broadcast, before the proof wait** (hard error if it fails), - Instant-proof requirement, path-gated voucher-key export (`9'/coin'/5'/3'/idx'`), - key scrubbing — `network/invitation.rs`. -- Claim orchestration: claim-by-fetch with bounded retry + byte-reversed retry, - credit-output selection by script match, Instant/Chain proof reconstruction, - raw-key identity registration — `network/invitation.rs`. -- Reclaim authorization: `AssetLockFunding::FromExistingAssetLock` + - `authorized_invitation_reclaim` (invitation-typed locks are consumable **only** with - `consume_invitation_voucher = true`, and only into register/top-up; every generic - path refuses them regardless of the flag) — `wallet/asset_lock/orchestration.rs:493,511`. -- The persistence wire type `InvitationEntryFFI` (repr(C), ABI-pinned 64 B, all-POD) - and the `on_persist_invitations_fn` callback slot + `INVITATIONS` capability bit — - `rs-platform-wallet-ffi/src/invitation_persistence.rs`, `persistence.rs:655-664,822`. - -Kotlin re-implements **none** of this. Per doctrine, no JNI function stitches Rust calls -together; each new export is a thin marshaler over exactly one existing C-ABI entry point. - -## 3. Design decisions - -1. **Reclaim: forward the flag in JNI + add outpoint-taking reclaim wrappers.** - Two layers, two different changes: - - *JNI*: the resume/top-up bindings (`identity.rs:496` → hardcoded `false` at `:552`, - guard at `:524`; `credits.rs:286` → `:331`, `:311`) forward the already-declared - `jboolean` verbatim and drop the `generic_asset_lock_recovery_allowed` call — an - interim fail-closed measure pending this port. Rust core enforces the real policy - independently (verified: `authorized_invitation_reclaim` requires - invitation-typed lock ∧ flag ∧ register/top-up target; all other - `FromExistingAssetLock` constructors hardcode `false` Rust-side), and Swift's - wrappers forward the identical boolean with no extra guard — this reproduces the - already-reviewed iOS trust model, not a weaker one. - - *Kotlin wrappers*: the existing public `resumeWithExistingAssetLock` / - `resumeTopUpWithExistingAssetLock` **cannot be reused** — they hardcode `false` - (`IdentityRegistration.kt:158`, `IdentityCredits.kt:115`), `require()` non-invitation - funding types, and `TrackedAssetLock.FundingType` has no `INVITATION(3)` (unknown - types are silently dropped at `TrackedAssetLock.kt:62`). Add two **outpoint-taking - reclaim variants** mirroring Swift (`resumeIdentityWithAssetLock:3939`, - `resumeTopUpWithAssetLock:4128`): raw txid+vout + `consumeInvitationVoucher`, no - funding-type gate, freely chosen `identityIndex`; each still one FFI call — no - doctrine violation. Generic-recovery wrappers and all existing call sites stay - exactly as they are. - *Alternative rejected:* adding `FundingType.INVITATION` and relaxing the three - `require()` gates on the generic-recovery wrappers — that weakens crash-recovery - invariants shared by non-invitation flows to serve one caller. -2. **Status transitions are client-written, exactly as on iOS.** Rust emits only - `Created` rows (create is the sole `InvitationChangeSet` emitter today). `Claimed` - and `Reclaimed` are written locally by the app via the reclaim-outcome classifier. - Room is the UI's source of truth; there is **no Rust→Kotlin rehydrate** (a Room wipe - loses list visibility only — never funds; `funding_index` re-derives the key). -3. **Claim entry = paste + QR scan first-class, deep link additionally** (decided, - §10.2). Add a `dashpay://invite` `VIEW` intent-filter routing to the claim sheet, - mirroring `SwiftExampleAppApp.swift:148`, **plus an intent-filter for the legacy - AppsFlyer host `https://invitations.dashpay.io/applink`** (the form production - dashwallet-iOS emits; our parser already accepts it) — unverified until the domain - serves `assetlinks.json` (dashpay/platform#4096), so it participates in the app - chooser rather than auto-opening; upgradeable to a verified App Link when #4096 - lands. Two further deliberate deviations from iOS: - - **Walletless parking (iOS behavior is a bug, not parity):** iOS clears - `pendingInviteURL` before its no-wallet guard returns - (`DashPayTabView.swift:149-153`), silently discarding the link — on Android the - intent-filter's headline scenario *is* a fresh install tapping an invite. Kotlin - parks the pending URI until a wallet exists (cleared only when the claim sheet is - actually seeded) and shows "create a wallet to claim this invitation". Flag the - drop as an upstream iOS bug to fix separately. - - **Honest Android framing:** a custom scheme can't use App Links auto-verify; any - app may register the same filter. Android shows a chooser on collision (per-tap - visibility iOS doesn't have), **but** one "Always" tap for a malicious app silently - routes every future invite link to it. Documented as an Android-specific - persistence risk, not "the same caveat iOS documents". - The mid-claim deferral gate (analog of `invitationClaimInFlight`) is ported as-is. -4. **Persistence writes go through the round buffer.** On FFI hosts the durable boundary - is `onChangesetEnd`'s single `withTransaction` replay of the per-wallet - `ChangesetBuffer` (`PlatformWalletPersistenceHandler.kt:298-353`); `onFlush` stays the - inherited base-class no-op (verified: Rust's `flush()` after a successful `store()` - round is a post-commit bookkeeping notification — the round's commit result is - honored, not advisory). Hard rule: the invitation handler **stages via `stage {}` - into the round buffer; never writes in its own transaction and never defers past the - round** (no `launch`/`post`) — an immediate standalone write would break round - atomicity, a deferred one would break durability. -5. **One PR, sliced commits** (§5 order). The feature is cohesive; the slices carry - independent compile/test gates. (If review load demands, slice 4 can split - screens+nav vs deep-link+classifier — optional.) - -## 4. Interfaces per layer - -### 4.1 JNI (`rs-unified-sdk-jni`) — new exports in `src/dashpay.rs` - -All under `support::guard`, errors via `take_pwffi_error` → `DashSDKException(code+1000)`. -FFI structs are read via the rlib types directly (no manual offset math). -**Secret-hygiene rule (normative): the `uri` argument is the bearer secret — it must -never be interpolated into any exception message, log line, or debug output from -`createInvitation`, `claimInvitation`, or `parseInvitation`** (the existing -`"$field must be N bytes"` convention covers byte params only; no precedent exists for -a String param that *is* the secret, so this is easy to get wrong). - -| Export (`Java_…_DashpayNative_…`) | Wraps | Notes | -|---|---|---| -| `parseInvitation(uri: String) -> String` | `platform_wallet_parse_invitation` | Returns the preview per the crate's compact-JSON convention (`structurallyValid`, `isInstant`, `hasInviter`, `inviterUsername?`); frees `inviter_username` after copy. Malformed link ⇒ `structurallyValid=false`, not an exception. | -| `createInvitation(walletHandle: Long, amountDuffs: Long, fundingAccountIndex: Int, inviterIdentityId: ByteArray?, inviterUsername: String?, nowUnix: Int, coreSignerHandle: Long) -> String` | `platform_wallet_create_invitation` | Returns the URI (bearer secret). The out-outpoint (caller-owned POD, nothing to free) is ignored — the persistence callback records the row, as on iOS. `now_unix` from a real clock read (Rust rejects 0). | -| `claimInvitation(walletHandle: Long, uri: String, identityIndex: Int, pubkeyRowsBlob: ByteArray, signerHandle: Long, nowUnix: Int)` | `platform_wallet_claim_invitation` | Pubkeys via the existing `decode_registration_pubkeys_blob` (`pubkey_rows.rs:320`); returns id + handle via the **`resumeIdentityWithExistingAssetLock` convention** — `IdentityRegistrationNativeResult` (`[BJ)V`) + `ManagedIdentityHandleGuard` (`identity.rs:569-576, :57-76`). (Not `registerIdentityWithFunding`, which destroys the handle and returns only the id.) | - -Plus the reclaim-flag forwarding change in `identity.rs` / `credits.rs` (§3.1). - -### 4.2 JNI persistence bridge (`src/persistence.rs`) - -- New trampoline `tramp_persist_invitations`, modeled on `tramp_persist_asset_locks` - (`:1233`): loop the `InvitationEntryFFI` upsert slice and the `[u8;36]` removal slice, - calling **per-row** bridge methods (the bridge has no array-of-struct convention): - `onPersistInvitationUpsert(walletId, outPoint: ByteArray(36), fundingIndex: Int, - amountDuffs: Long, expiryUnix: Int, createdAtSecs: Int, hasInviter: Boolean, - status: Int)` and `onPersistInvitationRemoval(walletId, outPoint: ByteArray(36))`. - Any nonzero Kotlin return fails the round so `create_invitation` surfaces - funded-but-unrecorded instead of silently losing the row. -- Set `on_persist_invitations_fn: Some(tramp_persist_invitations)` (replacing the `None` - at `:174` and its fail-closed comment). -- ⚠ Lockstep rule: the Rust `call_method` descriptors and the Kotlin bridge signatures - must land in the same commit — a mismatch is a runtime failure, not a compile error. - **Descriptor coverage is tested, not eyeballed (adversarial M4):** an instrumented - test resolves every `NativePersistenceBridge` (name, signature) pair via a test-only - JNI export (`GetMethodID` over the loaded class — covering all slots, not just the - new ones), so a descriptor typo fails CI instead of failing the first funded create. -- **Address-pool silent-skip fix (adversarial M1, security-critical):** - `onPersistAccountAddressPoolEntry` currently early-returns when the parent account row - is missing (`fetchAccount(...) ?: return@stage`, - `PlatformWalletPersistenceHandler.kt:509`). For the invitation flow that skip is a - **lie to the pre-broadcast durability gate**: Rust treats the round's success as - "funding index durably recorded" and broadcasts; on restart `next_unused` resets and - the already-exported bearer key is re-exported — the 55937e15c1 bug class with no - crash needed. Fix in slice 1: for asset-lock funding account types, a missing parent - account row **fails the round** (nonzero) or upserts the row — never silently skips. - Add the upgrade-path test: a v7-era wallet with no invitation-account Room row → - first `createInvitation` must abort **before broadcast**, not succeed non-durably. - (Audit whether Swift's handler shares the skip; if so, flag upstream.) - -### 4.3 Kotlin SDK - -- `ffi/DashpayNative.kt`: three new `external fun`s matching §4.1. -- `ffi/NativePersistenceBridge.kt`: the two per-row slots from §4.2 - (`open fun … : Int = 0`). -- `persistence/PlatformWalletPersistenceHandler.kt`: - - implement both slots — stage upsert/delete of `InvitationEntity` rows via `stage {}` - keyed by `outPointHex` (the upsert-key ↔ removal-key seam, pinned by test as on - iOS). **Upserts are partial**: only the FFI-fed columns are written on conflict — - client-written columns (`statusRaw`, `reclaimInFlight`) are preserved, so a future - Rust re-emit of an existing outpoint can't reset local status; - - add `CAPABILITY_INVITATIONS: Long = 0x02` and OR it into - `persistenceCapabilitiesBits()` **in the same commit that wires the full path** - (bit + path are inseparable; attesting early re-opens the fail-closed hole). -- New wrapper surface (idiom of `IdentityRegistration.kt` / `IdentityCredits.kt`, suspend - on `Dispatchers.IO`, KDoc citing the Swift source): - - `createInvitation(amountDuffs, fundingAccountIndex, inviterIdentityId: ByteArray?, inviterUsername: String?): String` (Swift `ManagedPlatformWallet.createInvitation:2062`) - - `claimInvitation(uri, identityIndex, identityPubkeys, signer): ByteArray /* identityId */` (Swift `:2145`) — adopts then releases the managed handle per the resume idiom (the claimed identity is already folded into the identity manager + persisted Rust-side); key set = the existing `RegistrationKeys` **6-key** layout (4 base + DashPay enc/dec at keyIds 4–5), pre-persisted via the same path registration uses. - - `parseInvitation(uri): InvitationPreview` (Swift `:2211`) - - **New reclaim variants (§3.1):** `reclaimInvitationAsNewIdentity(outPointTxid: ByteArray(32), outPointVout: Int, identityIndex, identityPubkeys /* 4-key set — iOS reclaim-register uses authKeyCount=4, no DashPay pair */, signer)` and `reclaimInvitationAsTopUp(identityId: ByteArray(32), outPointTxid, outPointVout): ULong /* new balance */` — both passing `consumeInvitationVoucher = true`; the only call sites that ever do. - -### 4.4 Room (`persistence/`) — DB v7 → v8 - -`InvitationEntity` — field-exact port of `PersistentInvitation.swift` (and of -`InvitationEntryFFI` for the callback-fed fields): - -| Column | Type | Notes | -|---|---|---| -| `outPointHex` | String, `@Unique` | `:` via the same encode as the asset-lock entity — the upsert/removal join key | -| `rawOutPoint` | ByteArray(36) | raw `txid_le ‖ vout_le`; reclaim rebuilds the outpoint without re-parsing hex | -| `walletId` | ByteArray, indexed | | -| `fundingIndexRaw` | Int | display metadata; the key is re-derived Rust-side, **no secret column** | -| `amountDuffs` | Long | | -| `expiryUnix` | Int | inviter-side display only (not on the wire) | -| `createdAtSecs` | Int | | -| `hasInviter` | Boolean | | -| `statusRaw` | Int | **0=Created, 1=Claimed, 2=Reclaimed** — pinned Rust-side by `status_to_u8`; discriminants must match byte-for-byte; client-written after create | -| `reclaimInFlight` | Boolean, default false | crash-forensics marker, §4.6 — never a concurrency guard | -| `createdAt` / `updatedAt` | Long | | - -Additive migration `MIGRATION_7_8` + exported schema `8.json` + migration test against -`7.json` (instrumented tier, following `DashDatabaseMigrationTest`). DAO exposes a -`Flow` sorted by `createdAtSecs` desc for the list screen. - -### 4.5 KotlinExampleApp UI (Compose, `app/…/ui/dashpay/`) - -One screen/sheet per Swift file; testTags = iOS accessibility identifiers verbatim; -screens driven by Room Flows + snapshot data — never retained native handles. -**Coroutine-scope rule (all three network flows):** create/claim/reclaim run in an -app-/container-scope (not `rememberCoroutineScope`, which cancels on leaving -composition), with `withContext(NonCancellable)` around the -marker-write → consume → status-write sequence — a mid-flow dismissal must not strand -a half-done reclaim (mirrors the `performDashPaySend` double-send guard precedent). - -| Swift | Compose target | Notes | -|---|---|---| -| `InvitationsView.swift` | `InvitationsScreen` | Room Flow over all invitations filtered to loaded wallets (multi-wallet aware — each row reclaims via its own `walletId`); rows show amount, short outpoint, contact-request badge, expiry, status badge (Created/Claimed/Reclaimed); create entry hidden only when no wallet (an active identity is NOT required). Tags `dashpay.invitations.{list,create,reclaim}`, entry `dashpay.openSentInvitations` on `DashPayTabScreen`. | -| `CreateInvitationSheet.swift` | `CreateInvitationSheet` | amount field default **0.03 DASH**, UI range [0.003, 0.05] mirrored for display (Rust enforces); "Send a contact request back to me" toggle (default on, disabled without a username — inviter id+username passed only when opted in); result = QR (ZXing, in-memory bitmap only) + **share as text** (no image export → no `FileProvider` temp file holding the secret) + copy per the clipboard rules in §6; UI single-flight (submit disabled while creating). Tags `dashpay.invite.create.{amount,sendBack,submit,share,copy,done}`. | -| `ClaimInvitationSheet.swift` | `ClaimInvitationSheet` | URI via paste, the existing `QrScanner` route (`savedStateHandle` result), or a parked deep link; `parseInvitation` preview gated only on `structurallyValid` (amount shows "—"); claim wallet selection pins the iOS rule: the active identity's wallet, else the first loaded wallet, entry disabled when none (`DashPayTabView.swift:131-134`); identity index = next unused (reuse the existing registration index logic); claim pre-persists the 6-key `RegistrationKeys` set then calls `claimInvitation`; on success, if `hasInviter && inviterUsername != null` → "Add \?" prompt → DPNS resolve → `sendContactRequest` (both already ported); works with **no active identity** (fresh invitee); back/dismiss gated while claiming. Tags `dashpay.invite.claim.{uriField,submit}`. | -| `ReclaimInvitationSheet.swift` | `ReclaimInvitationSheet` | reachable only from `statusRaw == 0` rows; segmented target Top-up existing (identity picker) / Register new (**4-key set**); calls the new reclaim wrappers (§4.3); **in-memory `isReclaiming` single-flight gating submit AND dismissal** (Swift `:37,92-109,168-181`) — the persisted marker is crash forensics, never the concurrency guard (an unguarded recomposition off the Room Flow re-emit could double-consume and let the loser's classifier overwrite Reclaimed with Claimed); marker + classifier per §4.6. Tags `dashpay.invite.reclaim.{target,identityPicker,submit}`. | - -Navigation: new routes in `Routes.kt` + `AppNavHost.kt`; entry points on -`DashPayTabScreen` ("Sent invitations" + "Claim invitation", ids as on iOS). Deep link -per §3.3: `dashpay`/`invite` `VIEW` intent-filter on `MainActivity` → pending-invite -state → parked until a wallet exists → claim sheet, with the claim-in-flight deferral. - -### 4.6 Reclaim crash-safety: marker + classifier (verbatim port) - -- **Marker discipline:** capture `hadPriorReclaimInFlight`; persist - `reclaimInFlight = true` (the Room write **must succeed** — abort the reclaim if it - doesn't) only **immediately before** the on-chain consume; the register arm pre-persists - its identity keys **before** setting the marker. On observed success: `statusRaw = 2`, - clear the marker, save. -- **Classifier:** a pure `internal fun classifyReclaimFailure(error, hadPriorReclaimInFlight)` - in the app layer, arms identical to Swift (`ReclaimInvitationSheet.swift:406`): - 1. typed `DashSdkError.PlatformWallet.AssetLockAlreadyConsumed` (the mapped class for - FFI code 24, `DashSdkError.kt:246` — the local tombstone written only after our own - successful consume; match the type, not a numeric code) → **Reclaimed** - (`statusRaw = 2`); - 2. message contains `"already completely used"` (consensus 10504, exact canonical - phrase, lowercased-contains — the typed FFI code for this remains the known - follow-up) → **Claimed** if no prior marker (provably a foreign claim, neutral - "already claimed" copy, claimant never named); **ambiguous** if the marker was set - (resolves to the conservative terminal `Claimed` + ambiguity message, never an - inferred `Reclaimed`); - 3. message contains `"is not tracked"` with the marker set → explicit ambiguity error, - state unchanged; - 4. else generic error; clear a stale marker only when `!hadPrior && isNotTracked`. - -## 5. Work plan (commit slices) - -1. **Persistence spine (the unblocker):** `InvitationEntity` + DAO + `MIGRATION_7_8` + - `8.json`; per-row bridge slots + handler impl (partial upsert); JNI trampoline; flip - `on_persist_invitations_fn` to `Some`; attest `CAPABILITY_INVITATIONS`; **the - address-pool silent-skip fix + upgrade-path test (§4.2)** — all one commit - (capability bit and path are inseparable). Gate: migration test (instrumented) + - handler mapping tests + the descriptor-resolution instrumented test + - `cargo check -p rs-unified-sdk-jni`. -2. **Parse + create + claim bindings:** three JNI exports + `external fun`s + SDK - wrappers + `InvitationPreview` type. Gate: `./build_android.sh --verify` + - symbol-load smoke. -3. **Reclaim:** JNI flag forwarding (guard dropped in exactly the two bindings) + the - two new outpoint-taking Kotlin reclaim wrappers. Gate: compile + tests pinning that - every generic-recovery path still passes `false` and the generic wrappers still - reject invitation locks. -4. **App UI:** four screens + routes + DashPay-tab entry points + deep-link filter with - walletless parking + classifier + marker discipline + single-flight/scope rules. - Gate: `:app:assembleDebug` + classifier/UI tests. -5. **QA + parity bookkeeping:** PARITY.md rows, emulator QA runs (§7), doc updates. - -## 6. Security invariants preserved (review checklist) - -- **Voucher-key-reuse defense (55937e15c1):** honest capability attestation + durable - round commits + **no silent skips anywhere in the funding-index persist chain** - (§4.2 M1 fix). `CAPABILITY_INVITATIONS` is attested only in the commit that wires the - full path; the handler stages into the round buffer (§3.4); a persist path that cannot - complete must fail the round, never no-op. -- **Durability residual (documented, accepted):** Room runs WAL + - `synchronous=NORMAL` — safe across process death (the relevant Android failure mode), - but a hard **power loss** can roll back the most recent committed transaction. This is - pre-existing for every already-attested capability bit and the same class of residual - iOS carries; documented rather than silently assumed. (Optional hardening — - `synchronous=FULL` for the wallet DB — is Open Question 4.) -- **Bearer-secret hygiene:** the URI embeds the voucher WIF. Never logged (no - logcat/android_logger, no exception messages carrying the URI — §4.1 rule — no - crash-report breadcrumbs), never persisted. Clipboard: Android has **no** - local-only or auto-expiring clipboard primitive (unlike iOS's - `localOnly + expirationDate:+60s`), and `ClipDescription.EXTRA_IS_SENSITIVE` is - API 33+ with minSdk 29 — so: set the flag when `SDK_INT >= 33`, and actively - compare-and-clear the clipboard after ~60 s (matching the iOS window); the missing - device-scoping half is an accepted, documented platform gap. Share = text-only - (no secret-bearing temp image files). QR rendered from an in-memory bitmap - (`util/QrCode.kt` precedent, no file/cache writes). -- **Backup:** the example app's manifest already sets `android:allowBackup="false"` - (Room DB has no secret column regardless). Note for integrators: this is an app-level - property the SDK cannot enforce — production apps must set it themselves. -- **Path gate untouched:** zero changes to `rs-platform-wallet` / `rs-platform-wallet-ffi` - / `rs-sdk-ffi`, so the `9'/coin'/5'/3'/idx'` export gate and the amount caps stay - exactly as reviewed on iOS. -- **`consume_invitation_voucher` discipline:** `true` appears at exactly two call sites - (the two reclaim wrappers, reached only from the reclaim sheet); every generic - resume/top-up path stays `false` and Rust refuses invitation locks there regardless. -- **Single-flight everywhere funds move:** create sheet (submit disabled while - creating; Rust's per-wallet build-persist mutex is the backstop) **and** reclaim - sheet (`isReclaiming` gating submit + dismissal — §4.5); claim sheet gates - back/dismiss while claiming. - -## 7. Test / verification plan - -- **JVM unit:** classifier matrix (port `ReclaimInvitationClassifierTests` — all arms, - incl. marker/no-marker ambiguity split and stale-marker clearing); - `InvitationEntity` upsert/removal key-seam test (outPointHex form drift, mirror of - `InvitationPersistenceTests`); handler mapping incl. removal → DAO delete and the - **partial-upsert preserves `statusRaw`/`reclaimInFlight`** pin; status discriminant - pin (0/1/2); generic wrappers still reject invitation locks. -- **Rust:** `cargo check -p rs-unified-sdk-jni` (+ clippy). -- **Instrumented (CI emulator):** Room `MIGRATION_7_8` against `7.json`; - `FfiSmokeTest`-style symbol load for the new externs; the **descriptor-resolution - test over every bridge slot** (§4.2); a capability-bits assertion that the handler - satisfies `INVITATION_CREATION`; the **upgrade-path test** (missing invitation-account - row → create aborts before broadcast). -- **Testnet-gated (`-Ptestnet=true`) / emulator QA** (`emulator-control` skill; faucet is - rate-limited → self-fund): mirror the iOS rows DP-12..DP-19 — - create (funded, row lands in Room + list), claim (second wallet, no funds → funded - identity; optional contact bootstrap), malformed/reused/wrong-network rejection (fail - loud, no side effects), sent-list persistence + upsert-in-place, reclaim-as-top-up - (balance rises, row → Reclaimed), reclaim-as-register (4-key set), already-consumed - race (second consume → deterministic "already completely used" → neutral Claimed - copy). The funded two-wallet race remains manual, as on iOS. -- **Acceptance gate:** the funded create→claim e2e on the emulator against testnet. - -### Funded e2e evidence (2026-07-23, arm64 emulator + testnet) - -- Instrumented tier: 32/32 green (Room `MIGRATION_7_8` + full v1→v8 chain, - `persistenceBridgeDescriptorsAllResolve`, FFI smoke; 3 testnet-gated skips). -- Create (DP-12/16): 0.03 DASH voucher funded + InstantSend-locked, legacy link - emitted, row landed in Room + Sent list as `Created` (outpoint `f9ef7f5b…:0`). -- Claim (DP-13): link pasted → valid preview → new identity `292ebab4…` - registered with 2 818 643 580 credits, funded solely by the voucher. -- Already-consumed (DP-19 classifier, live): reclaiming the claimed voucher hit - consensus 10504 → neutral "This invitation was already claimed.", row → - `Claimed`, reclaim affordance gone. -- Interrupted create: a second create timed out waiting for its InstantSend - lock — the funded row (`732bf38c…:0`) was already persisted and reclaimable, - proving the persist-before-proof-wait ordering on Android. -- Reclaim-as-top-up (DP-17): that voucher consumed into identity `7023bed1…`, - balance 49 818 637 700 → 52 736 112 114 credits, row → `Reclaimed`. -- Malformed link (DP-15): garbage URI → "Invalid invitation link.", claim - disabled, no side effects. -- Not exercised here: the two-wallet contact-bootstrap (DP-14 — inviter had no - DPNS username, so the opt-in toggle was correctly disabled) and - reclaim-as-register (DP-18 — same FFI + wrapper as the seam-tested claim - path); both remain manual QA, matching iOS. - -## 8. Failure modes - -- **Capability over-attestation / silent persist skips** → voucher-key reuse (the - pre-port bug class; adversarial M1 shows a no-crash variant via the address-pool - skip). Guard: bit + path in one commit; the M1 fail-the-round fix; instrumented - capability + upgrade-path assertions. -- **Handler write outside the round buffer** → broken round atomicity or lost-on-crash - rows reported as persisted. Guard: §3.4 rule + mapping tests exercise `stage {}`. -- **JNI descriptor mismatch** → every invitation persist fails at runtime — after real - funds broadcast, if untested. Guard: lockstep rule + the descriptor-resolution - instrumented test **before** any funded QA. -- **Crash between broadcast and the invitation-row round** → a funded voucher with no - Room row: invisible in Sent invitations, unreclaimable from the UI (reclaim is - row-driven), funds stranded pending manual recovery. Inherent to the shared - persist-after-broadcast ordering (iOS carries the same window); the - funded-but-unrecorded error copy must surface the **outpoint** so support/manual - recovery is possible. -- **Process death mid-reclaim** → marker semantics resolve it (our-tombstone → - Reclaimed; foreign claim → Claimed; genuinely ambiguous → conservative Claimed + - message). Double-tap/recomposition races are excluded by the in-memory single-flight - (§4.5), not by the marker. -- **URI leakage via logs/exceptions/clipboard/share files** → bearer theft. Guard: - §4.1 exception rule + §6 clipboard/share rules. -- **ChainLock fallback at create** → Rust rejects the link, lock stays reclaimable; - surface the error copy as iOS does. -- **Deep link with no wallet** → parked, not dropped (§3.3); "create a wallet to claim" - copy. -- **QR/paste garbage** → `structurallyValid=false` preview, claim button disabled, no - side effects. - -## 9. Out of scope - -- Typed FFI code for consensus 10504 already-consumed (shared iOS/Android follow-up). -- A typed funded-failure result carrying the recovery outpoint from - `create_invitation` (adversarial-review follow-up): on the rare - funded-but-row-persist-failed path the outpoint doesn't cross the JNI boundary - (the FFI fills out-params only on success — changing that is a shared-Rust - change). Recovery exists meanwhile via the Rust-side tracked-lock list - (diagnostics surface); the common interrupted-create case persists the row - and is reclaimable from the UI (funded-e2e verified). -- Driving the Rust pre-broadcast abort from a JVM test (the broadcast boundary - is Rust-side; the Kotlin tier pins the round-failure half — - `invitationPoolEntryWithoutWalletFailsTheRound` — and Rust's own - `create_invitation_requires_durable_persistence` pins the abort). -- Any `rs-platform-wallet` / `rs-platform-wallet-ffi` change (incl. Rust-emitted - Claimed/Reclaimed status changesets — latent on iOS too). -- Fixing the iOS walletless deep-link drop (flagged upstream, §3.3). -- AppsFlyer/OneLink or App-Links-style verified deep-link transport (tracked separately - for iOS as well). -- Contested-name claim tier (deferred on iOS). - -## 10. Decisions (RESOLVED — owner sync, 2026-07-22) - -1. **Reclaim JNI guard drop: approved.** `generic_asset_lock_recovery_allowed` is - removed from exactly the two forwarding bindings; Rust core's - `authorized_invitation_reclaim` remains the (independently unit-tested) enforcement — - the same single-gate trust model shipped on iOS. -2. **Deep link: both filters.** `dashpay://invite` custom scheme + the legacy AppsFlyer - `https://invitations.dashpay.io/applink` host (unverified chooser participation until - #4096 serves `assetlinks.json`), with walletless parking (§3.3). -3. **PR strategy: one PR, five sliced commits** (§5). -4. **WAL durability: accept + document** the `synchronous=NORMAL` power-loss residual - (§6) — platform-wide status quo, same class as iOS; `synchronous=FULL` would tax - every wallet write and belongs to a separate measured change if ever. diff --git a/docs/dashpay/KOTLIN_MIGRATION_FOLLOWUPS_SPEC.md b/docs/dashpay/KOTLIN_MIGRATION_FOLLOWUPS_SPEC.md deleted file mode 100644 index db993c19c1e..00000000000 --- a/docs/dashpay/KOTLIN_MIGRATION_FOLLOWUPS_SPEC.md +++ /dev/null @@ -1,219 +0,0 @@ -# Kotlin DashPay Migration — Follow-up Fixes Spec - -**Historical status:** Items A, B, and C are resolved in the consolidated -migration; the completed work is recorded in -[`KOTLIN_MIGRATION_LEFTOVERS.md`](KOTLIN_MIGRATION_LEFTOVERS.md). Item D remains -deferred. The problem/approach sections below preserve the reviewed rationale -and pre-implementation baseline rather than describing current open work. - -Scope: three DashPay follow-ups folded into the consolidated migration PR -(`feat/kotlin-sdk-dashpay-migration`, stacked on the base Kotlin SDK PR -`feat/kotlin-sdk-and-example-app`). A fourth item (durable contact-crypto -queue persistence) is **deferred** with rationale in §D. - -All three items were verified **still open at the base PR HEAD** (`1fd86fbae5`) -and **not** addressed by the parent PR — none duplicates parent work. - ---- - -## A. Platform-address signing: eliminate the JVM-String seed exposure - -### Problem -`KeystoreSigner.signPlatformAddressOnDemand` retrieves the wallet mnemonic as a -`java.lang.String` (`WalletStorage.retrieveMnemonic`) and passes it across JNI to -`SignerNative.signWithMnemonicAndPath(mnemonic: String, …)`. An immutable `String` -cannot be scrubbed; the phrase sits on the JVM heap until GC (if ever), -recoverable from a heap dump. This is the exact anti-pattern the K2 resolver path -eliminated with `resolveMnemonicInto`, and it is explicitly flagged as the tracked -follow-up in three places (`KeystoreSigner.kt:151-157`, `SignerNative.kt:36-38`, -`signer.rs:436-437`). Every on-demand platform-address signature re-exposes the seed. - -### Approach (out-buffer discipline, input direction) -Pass the phrase as a **scrubbable `ByteArray`** the caller owns and zeroes, so no -`String` of the seed ever exists on the signing path. - -- **Rust JNI** (`packages/rs-unified-sdk-jni/src/signer.rs`): replace - `Java_…_SignerNative_signWithMnemonicAndPath` with - `Java_…_SignerNative_signWithMnemonicAndPathInto`; the mnemonic argument becomes - `JByteArray`. Decode the non-secret args (path, payload) **first** and the - mnemonic **last**. **Do NOT use `convert_byte_array` + `reserve_exact`** — that - pattern orphans an unscrubbed plaintext heap copy: `convert_byte_array` returns a - `cap==len==N` `Vec`, and `CString::new`'s NUL append then forces a growth realloc - that frees the original buffer unscrubbed (real on Android's Scudo allocator). - Instead keep the phrase in a `Zeroizing>` **end-to-end** — never launder - it through a `CString` (whose `into_boxed_slice` shrink-to-fit can silently realloc - and free the plaintext unscrubbed, and which sits outside any zeroize guard across - the FFI call): - ```rust - let n = env.get_array_length(&mnemonic)? as usize; // reject Err - let mut plain: Zeroizing> = Zeroizing::new(Vec::with_capacity(n + 1)); - plain.resize(n, 0); // len=n, cap=n+1 - let dst = unsafe { slice::from_raw_parts_mut(plain.as_mut_ptr().cast::(), n) }; - env.get_byte_array_region(&mnemonic, 0, dst)?; // reject Err - if plain.contains(&0) { throw; return } // reject interior NUL - plain.push(0); // NUL-terminate in place, no realloc - // pass plain.as_ptr().cast::() to the FFI; drop(plain) scrubs the sole - // copy after signing — and on any panic unwind, since it never leaves Zeroizing. - ``` -- **Kotlin FFI decl** (`ffi/SignerNative.kt`): replace the `external fun` with - `signWithMnemonicAndPathInto(mnemonicUtf8: ByteArray, derivationPath: String, - network: Int, data: ByteArray): ByteArray?`. -- **Caller** (`security/KeystoreSigner.kt`): switch - `storage.retrieveMnemonic(...)` → `storage.retrieveMnemonicUtf8(...)` (returns - `ByteArray?`, already exists) and wrap the sign in - `try { … } finally { mnemonicUtf8.fill(0) }`. Delete the KNOWN-residual comment - block (151-157) — it is now resolved. - -The old String function has a **single caller** (verified), so it is removed -outright; no String seed path remains. The derived key still never crosses JNI — -Rust derives, signs, and scrubs internally, unchanged. - -### Failure modes -- Interior NUL in the phrase bytes → reject before the FFI call; dropping the - `Zeroizing>` scrubs the phrase copy. -- Empty byte array → a NUL-only buffer reaches the inner FFI, whose mnemonic parse - fails with an invalid-mnemonic error. There is **no size cap** (a large array just - allocates and then fails the parse); the caller's `retrieveMnemonicUtf8` only ever - returns real phrase bytes or null, so this is a defense-in-depth path. -- Caller forgetting to scrub → mitigated by the `finally` block; the array is - caller-owned per `retrieveMnemonicUtf8`'s contract. The Kotlin `null`-check must - precede the `try` (nothing fallible between the retrieve and entering the `try`). -- Note: the JNI symbol name (`Java_…_signWithMnemonicAndPathInto`) must match the - Kotlin `external fun` exactly — a mismatch is a runtime `UnsatisfiedLinkError`, not - a compile error, and the JVM helper test won't catch it (pinned by `cargo check` + - an instrumented/on-device sign smoke). - -### Test plan (red→green) -`KeystoreSigner` cannot be constructed on the JVM tier (its constructor eagerly -calls native `createSigner`), and `WalletStorage` is a final class with no mock -framework in the module — so a seam *on the class* is untestable. Instead extract -a **pure `internal` scrub-and-sign helper** that owns the discipline: - -```kotlin -internal inline fun signWithScrubbedMnemonic( - mnemonicUtf8: ByteArray, - derivationPath: String, - network: Int, - data: ByteArray, - sign: (ByteArray, String, Int, ByteArray) -> ByteArray?, -): ByteArray? = try { sign(mnemonicUtf8, derivationPath, network, data) } - finally { mnemonicUtf8.fill(0) } -``` - -`KeystoreSigner.signPlatformAddressOnDemand` calls it with -`sign = SignerNative::signWithMnemonicAndPathInto`. JVM test -(`SignerMnemonicScrubTest`): call the helper with a fake `sign` that records a -**copy** of the bytes it received and returns a dummy signature, then assert the -input array is all-zero afterward, and that the dummy signature is returned -(scrub happens after the sign, not before). Red→green is demonstrated by toggling -only the `finally { fill(0) }` — without it the array retains the phrase (red), -with it the array is zeroed (green). This pins the scrub invariant honestly (the -String-path removal itself is a structural guarantee, verified by the code + the -absence of any `retrieveMnemonic`/String-sign call on the signing path). -Plus `cargo check -p rs-unified-sdk-jni` for the Rust side. - ---- - -## B. Payment-sheet dispose-mid-send: pin the double-send guard - -### Problem -`SendDashPayPaymentSheet.send()` broadcasts a payment and then records the txid + -triggers the durability refresh (`onSent` → `refreshDashPayPayments`). The K3 fix -wraps the broadcast + bookkeeping in `withContext(NonCancellable)` (plus a Compose -dismissal gate in `ContactDetailScreen`) so a dispose-mid-send cannot skip the -durability refresh — which would otherwise invite a **double-send** on retry (the -JNI broadcast is uncancellable; the coin leaves the wallet regardless). This guard -has **no regression coverage**; a future refactor could drop `NonCancellable` -silently. - -### Approach (extract the send body + inject the sender) -`send()` is a local function inside a `@Composable`, uncallable from `runTest`. -**Extract the coroutine body** (`SendDashPayPaymentSheet.kt:90-120`) into a -non-composable `internal suspend fun performDashPaySend(...)` that takes a minimal -`fun interface PaymentSender { suspend fun send(...): ByteArray? }` plus the -`onSent`/`onClose`/status callbacks. The composable calls it inside its existing -`scope.launch { … }`, so runtime behavior (including the launching Job) is -identical; the production `PaymentSender` closes over `wallet`/`manager` and calls -`w.dashpay.sendPayment(...)`. `performDashPaySend` keeps the `withContext( -NonCancellable) { sender.send(...); onSent() }` wrapper — the guard under test. - -**Critical extraction constraints** (else the test is invalid): -- `performDashPaySend` is a plain `suspend fun` inheriting the caller's Job — it - must NOT introduce a new `CoroutineScope`/`coroutineScope { }`, which would - change the cancellation semantics being tested. -- The `CancellationException` rethrow stays; the best-effort tail - (`kickDashPaySync`/`delay`/`onClose`) stays OUTSIDE the `NonCancellable` block. - -### Test plan (red→green) -JVM `runTest` (`PerformDashPaySendDoubleSendGuardTest`): launch -`performDashPaySend` in a child `Job` with a fake `PaymentSender` that records the -broadcast **before** suspending on a test gate (models "broadcast completed, -bookkeeping pending" — the real hazard, not "cancelled before broadcast"): -1. launch the send; await the recorded broadcast entry; -2. cancel the child Job (simulate dispose-mid-send); -3. release the gate; join. -Assert **`onSent` fired exactly once** (count 0 pre-fix vs 1 post-fix — the -decisive assertion; the `NonCancellable` block completed despite cancellation). -Against the pre-fix code (no `NonCancellable`), cancellation observed on resume -after the broadcast skips `onSent` → count 0 → red. Assert on `onSent` count, NOT -`sendPayment` count (which is 1 either way). - -The Compose **dismissal gate** (secondary, defense-in-depth) is left to the -existing instrumented UI tier; it is not the double-send regression and is not -deterministically JVM-testable without Robolectric (not configured). - ---- - -## C. DataContractRef: add the NativeCleaner GC backstop - -### Problem -`DataContractRef` (`queries/PlatformQueries.kt:621-633`) destroys its native handle -inline in `close()` but registers **no** `NativeCleaner`, so a leaked (never-closed, -never-`use{}`) ref leaks the native contract handle forever. Every other owned -handle — `Sdk`, `ManagedPlatformWallet`, and the K3 `ContactRequestRef`/ -`EstablishedContactRef` — has the GC backstop. Consistency gap. - -### Approach -Match the established idiom exactly: `import NativeCleaner`; register -`private val cleanable = NativeCleaner.register(this, HandleCleanup(handleRef))`; -`close()` → `cleanable.clean()`; standalone inner -`private class HandleCleanup(handleRef: AtomicLong) : Runnable` whose `run()` does -`handleRef.getAndSet(0)` then `QueriesNative.dataContractDestroy(h)` iff non-zero -(destroys exactly once, whichever of close/GC fires first). `AtomicLong handleRef` -and `value` are unchanged; no call sites change. - -### Test plan -`close()` idempotency + registration are the testable surface; the native destroy -and GC-timing of the phantom backstop are not deterministically unit-testable. Rely -on parity with the already-shipped `ContactRequestRef` pattern + compile; add a -`NativeCleaner`-level idempotency assertion only if a fake action seam already -exists. (Noted as best-effort per the untestable-path carve-out.) - ---- - -## D. Durable contact-crypto queue persistence — DEFERRED (own PR) - -The DashPay deferred contact-crypto queue (`PlatformWalletChangeSet. -pending_contact_crypto_added/_cleared`) is not durable across process death on FFI -hosts. Research (see below) shows only the **write** half is cleanly addable; the -**restore** half is blocked upstream: - -- The in-repo SQLite persister already writes the queue, but its reader is - `#[cfg(test)]`-only "because production load restore is blocked upstream - (`LOAD_UNIMPLEMENTED: ClientStartState::wallets`)". -- `rs-platform-wallet/src/wallet/apply.rs:111-116` drops the queue fields on the - changeset-replay path; restore is meant to flow through the wallet **start-state** - path, which isn't wired for this field. - -Adding the FFI `on_persist_pending_contact_crypto_fn` slot + JNI trampoline + a -`DashDatabase` v3→v4 Room migration + Swift SwiftData model would persist rows that -**nothing reads back** — a large, irreversible, cross-cutting surface (including a -schema migration) for **zero cross-restart durability** until the upstream -start-state restore exists. This is worse than the current honest deferral: the -recurring signerless sweep already re-enqueues the work after restart, so the only -exposure is delayed (not lost) contact-crypto work between sweeps. - -**Decision:** keep as a documented leftover; implement as a dedicated PR once the -`rs-platform-wallet` start-state restore path lands. Full data-path map (producers, -SQLite schema, FFI/JNI/Kotlin/Swift layers, the add-a-persisted-field recipe) is -recorded for that future PR. diff --git a/docs/dashpay/KOTLIN_MIGRATION_LEFTOVERS.md b/docs/dashpay/KOTLIN_MIGRATION_LEFTOVERS.md deleted file mode 100644 index 7113bb97c58..00000000000 --- a/docs/dashpay/KOTLIN_MIGRATION_LEFTOVERS.md +++ /dev/null @@ -1,98 +0,0 @@ -# Kotlin DashPay Migration — Known Leftovers & Follow-ups - -Durable record of what is and isn't done as of the consolidated DashPay migration -PR (K1 + K2 + K3 + the follow-up fixes below). Kept so nothing is silently lost -when the four stacked PRs collapse into one. - -## Resolved in this PR (follow-up fixes) - -- **Seed hygiene on the platform-address signing path** — the mnemonic now crosses - JNI as a scrubbable UTF-8 `byte[]` (`signWithMnemonicAndPathInto`) that the caller - zeroes after use, never an un-scrubbable `java.lang.String`. Rust copies it - directly into a pre-sized `Zeroizing>`, NUL-terminates that buffer in - place, and never routes the phrase through `CString`. Pins: - `SignerMnemonicScrubTest` (JVM, red→green). -- **Payment dispose-mid-send double-send guard** — the send flow was extracted to - `performDashPaySend` + a `PaymentSender` seam so the `withContext(NonCancellable)` - guard (broadcast + durability bookkeeping stay atomic against a mid-send teardown) - has a deterministic regression test: `PerformDashPaySendDoubleSendGuardTest` (JVM, - red→green). -- **`DataContractRef` GC backstop** — now registers a `NativeCleaner` like every - other owned handle, so a leaked (never-closed) ref no longer leaks the native - contract handle. -- **`signWithMnemonicAndPathInto` instrumented sign smoke** — - `FfiSmokeTest.mnemonicAndPathSignerSymbolLoadsAndSigns` loads the exact JNI - symbol on-device, derives from a valid BIP-39 vector, and returns a compact - recoverable signature. The direct test caller scrubs its JVM-owned mnemonic - array in `finally`; JNI scrubs only its Rust-owned copy. - -## Deferred to dedicated follow-up PRs - -- **Durable contact-crypto queue persistence (item D).** The DashPay deferred - contact-crypto queue (`PlatformWalletChangeSet.pending_contact_crypto_added/ - _cleared`) is not durable across process death on FFI hosts. Only the *write* half - is cleanly addable; the *restore* half is blocked upstream — the in-repo SQLite - persister's reader is `#[cfg(test)]`-only "because production load restore is - blocked upstream (`LOAD_UNIMPLEMENTED: ClientStartState::wallets`)", and - `rs-platform-wallet/src/wallet/apply.rs` drops the queue fields on the - changeset-replay path. Adding the FFI slot + JNI trampoline + a `DashDatabase` - v3→v4 Room migration + Swift model would persist rows nothing reads back — a large, - irreversible surface (incl. a schema migration) for zero durability until the - upstream start-state restore lands. The recurring signerless sweep already - re-enqueues the work after restart, so the exposure is *delayed*, not *lost* - contact-crypto work between sweeps. Do it as its own PR once the start-state - restore exists. Full data-path map + add-a-persisted-field recipe recorded during - the follow-ups research. - -- **PARITY: 94 ported / 5 partial / 0 deferred views** - (`packages/kotlin-sdk/PARITY.md`). All 10 DashPay screens remain fully ported. - The five partials are `CreateIdentityView`, `IdentityDetailView`, - `TransitionDetailView`, `WalletMemoryExplorerView`, and `CoreContentView`. - All 23 transition-catalog definitions now execute; `TransitionDetailView` is - partial only because `identityUpdate`'s add-keys sub-path remains on the - dedicated AddIdentityKey flow rather than the catalog form. Each partial row - names its concrete remaining FFI, persistence, UI/catalog-adaptation, device, - or restart gate. - -- **`SigningKeyUnavailable` MESSAGE_MARKER fallback removal.** The signer's - "missing key" failure now travels as a typed completion code (rs-sdk-ffi - `DashSDKSignerErrorCode::SigningKeyUnavailable` → platform-wallet code 31 → - `DashSdkError.PlatformWallet.SigningKeyUnavailable`). The message-marker - sniff on the catch-all codes is retained ONLY for the #4191 merge-order - transition and for conversion paths that lose the machine prefix — NOT for - mixed old-native/new-Kotlin builds, which the completion JNI arity change - (3→4 args) makes unsupported outright; delete it (and `MESSAGE_MARKER`'s - matcher role) in the next minor release. Accepted residual until rs-dpp grows a typed variant: the - Rust-internal segment rides the `signer_error:key_unavailable: ` prefix - through `ProtocolError::Generic` (typed at both ABI edges, one Rust-owned - constant bridging the string segment). - -- **On-device `KeyPermanentlyInvalidatedException` coverage.** The - invalidation recovery (generation-checked alias deletion + re-derive via - forced repair) is pinned at the unit tier through the fake Keystore seam; - a REAL KPIE requires biometric re-enrollment mid-test, which CI's emulator - cannot do — same residual #4172 accepted. Exercise manually per the device - test plan when touching the invalidation path. - -## Environment-bound (cannot be code-fixed here) - -- **End-to-end send→accept→pay testnet UAT** — device/testnet-bound; not runnable in - CI. Must be exercised on a real testnet wallet before relying on the full DashPay - flow. -- **Live-network paths** (`searchDpnsNames`, `dashPaySyncNow`, the DashPay write - paths) are exercised only under the `-Ptestnet=true` instrumented tier. - -## Behavioral notes to carry (from the base Kotlin SDK PR) - -- `rs-sdk-ffi` / `rs-sdk-trusted-context-provider` use rustls + webpki roots instead - of the platform TLS stack (OpenSSL doesn't exist on Android). This also changes the - iOS trust roots — no API change, but worth an iOS-side look. - -## Review findings — all resolved upstream - -Every P0/P1/P2 from the base-PR reviews (invalid Cargo `--features` arg, JNI -local-frame leaks, negative-amount/index/selector validation across credits/tokens/ -funding/identity, `sendDashPayPayment` guard) was verified **already fixed** at the -base PR HEAD before this consolidation — none was outstanding. The only carried -review finding was the contact-crypto durability suggestion, addressed as item D -above. diff --git a/docs/dashpay/KOTLIN_MIGRATION_SPEC.md b/docs/dashpay/KOTLIN_MIGRATION_SPEC.md deleted file mode 100644 index 784ff8897d8..00000000000 --- a/docs/dashpay/KOTLIN_MIGRATION_SPEC.md +++ /dev/null @@ -1,441 +0,0 @@ -# DashPay — Kotlin/Android Migration Spec - -**Historical baseline:** This document preserves the reviewed pre-migration plan -and its then-current 88/90 inventory. It is not the current open-work tracker: -subsequent implementation changed the contact-crypto persistence boundary, -shipped invitation support on iOS, and closed the cited transition FFI gaps. See -[`packages/kotlin-sdk/PARITY_SUMMARY.md`](../../packages/kotlin-sdk/PARITY_SUMMARY.md) and -[`docs/sdk/sdk-parity-manifest.json`](../sdk/sdk-parity-manifest.json) for current -capability status. - -Port the complete DashPay feature (as shipped for iOS in PR #3841, merged to -`v4.1-dev` 2026-07-06) to the Kotlin/Android SDK and KotlinExampleApp -(PR #3999, branch `feat/kotlin-sdk-and-example-app`). - -Status: **v2 — post five-lens review** (feasibility, scope, security, -adversarial, domain-fit); all must-fixes folded in. -Reference implementation: `packages/swift-sdk` + SwiftExampleApp. -Feature spec: `docs/dashpay/SPEC.md` (+ companion specs in `docs/dashpay/`). - ---- - -## 1. Problem - -The Kotlin SDK (PR #3999) is a one-for-one Android port of SwiftExampleApp, -snapshotted **before** PR #3841 landed. #3841 completed DashPay on iOS: - -- Replaced the utilitarian `FriendsView` (which the Kotlin `FriendsScreen` - mirrors — now a port of a **deleted** Swift view) with a first-class - **DashPay tab**: 10 views, ~3.8k LOC (`Views/DashPay/`). -- Added a recurring **DashPay background sync** service - (`platform_wallet_manager_dashpay_sync_*`, 7 FFI fns). -- Added **payment history**, **cached contact profiles**, **contactInfo** - (alias/note/hidden, cross-device), **ignore tombstones**, **seedless - unlock + deferred contact-crypto drain**, and **DIP-15 auto-accept QR**. -- Net: 23 new C exports in `rs-platform-wallet-ffi`; 6 old exports removed - (incl. the `*reject_contact_request` pair — reject became ignore). - -Today the Kotlin stack has: 3 of 5 DashPay Room entities (field-exact with -SwiftData), the send/accept/ignore/sync contact-request pipeline bridged -(17 JNI exports in `tokens.rs`), and one compressed `FriendsScreen`. It -lacks: profile/contactInfo writes, payments, the contact-profile cache, the -sync service, QR, seedless unlock, wallet-scoped DPNS search, and the -DashPay tab. `PARITY.md` still claims 88/90 ported against the stale -pre-#3841 view list. - -**Compatibility baseline:** the existing 17 exports were reconciled with -the #3841 Rust in commit `2298a2059f` (reject→ignore, `coreSignerHandle` -threading, contacts-vtable ignored-sender deltas + contactInfo metadata -fields, Room v1→v2). That reconciliation was verified by compile + 3 -Robolectric tests only — no runtime exercise of the Android -send/accept/ignore path against a network has been recorded since the -merge. K1 therefore opens with a runtime revalidation gate (§4). - -**Goal:** feature parity with iOS DashPay per the parity doctrine -(`kotlin-sdk/CLAUDE.md`): cite Swift sources in KDoc, reuse iOS -accessibility identifiers as Compose `testTag`s, keep all orchestration in -Rust. - -## 2. What does NOT need porting - -All DashPay *logic* is shared Rust, already compiled into this branch and -consumed by iOS through the same C ABI: - -- Contact-request crypto (ECDH, AES-256-CBC, DIP-15 69-byte compact xpub), - DIP-14/15 derivation, accountReference — `rs-platform-wallet` + - `platform-encryption` + `key-wallet`. -- Accept → reciprocal request → `register_external_contact_account` - (friendship address derivation) — automatic inside Rust. -- The recurring sync sweep (`manager/dashpay_sync.rs`), seed binding - verification, deferred contact-crypto queue, auto-accept QR - build/parse/proof. -- The bundled DashPay contract. - -Kotlin re-implements **none** of this. Per doctrine, no JNI function may -stitch Rust calls together — any composite gap found during the port goes -into `rs-platform-wallet-ffi` as its own reviewed change (none are -currently known to be needed; iOS ships on the existing exports). - -**Deliberately not bridged** (zero non-README callers in the Swift app — -the app reads this data from persisted rows, not handles; verified -function-by-function during review): - -- The 8 `contact_request_*` field getters + `contact_request_create`. -- The 14 `established_contact_*` accessors + - `managed_identity_get_established_contact` / - `_get_sent_contact_request` — `ContactDetailView` reads alias/note/ - hidden/paymentChannelBroken off `PersistentDashpayContactRequest` rows - and writes via `set_dashpay_contact_info_with_signer`. -- `managed_identity_is_contact_established`, - `platform_wallet_pubkey_hash_from_private_key` (no app consumers), - and the `managed_identity`-level send/accept/ignore variants (Kotlin - uses the `platform_wallet_*` composites, as iOS does). - -Consequence: **no new handle-wrapper types.** The existing -`ContactRequestRef` / `EstablishedContactRef` (`tokens/Dashpay.kt`) stay -as-is for the accept path; new screens are driven by Room Flows and -snapshot data classes. Rule: never retain a native handle in Compose -composition — snapshot fields at the JNI boundary (a Cleaner can free a -handle mid-read otherwise). - -## 3. Approach - -Three milestones, re-cut after review so that **every bridged function -lands in the milestone that first consumes and tests it** (the original -bottom-up "bridge everything first" cut concentrated all marshaling -defects at final UAT — rejected). - -### Alternatives rejected - -- **Re-orchestrating DashPay flows in Kotlin**: forbidden by doctrine; - Swift ships proof that single-call composites suffice. -- **Keeping `FriendsScreen` and bolting features onto it**: its Swift - counterpart was deleted; keeping a dead view's port violates parity. -- **uniffi / JNA instead of hand-rolled JNI**: the crate has 160 - hand-rolled exports with established support patterns (`support::guard`, - handle-as-jlong, GlobalRef callbacks); mixing binding generators adds - toolchain cost for no capability gain. -- **Bridging the full ~47-function FFI sweep**: 24 of them have no - consumer anywhere in the reference app (see §2); bridging them would - add dead surface + a speculative handle-wrapper abstraction. - -## 4. Work plan - -New JNI exports go in a new `rs-unified-sdk-jni/src/dashpay.rs` + -`ffi/DashpayNative.kt`; the 17 existing DashPay exports stay in -`tokens.rs` (moving them is a follow-up refactor). Array-free FFI -counterparts (`dashpay_payment_array_free`, `dpns_search_results_free`, -`platform_wallet_manager_free_account_balances`) are consumed Rust-side -inside the JNI wrappers, as the existing exports do. - -⚠ Lockstep rule: extending the identity-entry persist callback changes the -`onPersistIdentityUpsert` JNI method descriptor (hand-written string, -`persistence.rs:866-893`) — the Rust descriptor and the Kotlin -`NativePersistenceBridge` signature must change in the same commit or -every identity persist fails at runtime. - -### Milestone K1 — Persistence completion + the read surface it can prove - -**Entry gate:** one runtime revalidation of the existing 17-export -pipeline — the FriendsScreen send→accept→ignore flow against testnet -(`-Ptestnet=true`), or its instrumented equivalent — before any new -bridging. Also the 15-minute PARITY.md interim fix: drop the stale -`FriendsView.swift` row claims, mark the DashPay section -"in migration — see KOTLIN_MIGRATION_SPEC.md". - -**Bridge (6 exports):** - -| Group | Functions | -|---|---| -| Payments | `managed_identity_get_dashpay_payments` | -| Profile reads | `platform_wallet_get_contact_profile`, `managed_identity_get_dashpay_profile`, `managed_identity_get_dashpay_sync_state` | -| DPNS search | `platform_wallet_search_dpns_names` (wallet-scoped; the existing `QueriesNative.dpnsSearch` wraps the *SDK-scoped* `dash_sdk_dpns_search` — a different call path; AddContactScreen must use the wallet-scoped one for parity) | -| Account balances | `platform_wallet_manager_get_account_balances` (DashPayTabView's per-account balance display; not DashPay-prefixed, easy to miss) | - -**Persistence** (mirrors `PersistentDashpayContactProfile.swift` / -`PersistentDashpayPayment.swift`): - -- New Room entities `DashpayContactProfileEntity` - (`(networkRaw, ownerIdentityId, contactIdentityId)` unique, `checkedAtMs` - backoff) and `DashpayPaymentEntity` - (`(networkRaw, ownerIdentityId, txid)` unique) + DAOs + Flows; - `DashDatabase` v2→v3 additive migration, exported schema `3.json`. -- **Persist direction — contact profiles:** extend identity-entry - marshaling to carry `IdentityEntryFFI.contact_profiles` (slot exists, - currently skipped at `persistence.rs:825-895`). **Tombstone semantics - are load-bearing:** the projection emits `is_present == false` rows that - mean DELETE the persisted row (`identity_persistence.rs:600-608`) — an - upsert-only implementation compiles, passes upsert tests, and leaves - stale contact names/avatars forever. Required: `is_present=false` → DAO - delete (with test) + `checkedAtMs` round-trip fidelity test. (Note: the - outer doc comment at `identity_persistence.rs:146` contradicts the - projection code and should be corrected in passing.) -- **Persist direction — payments:** pull-based, mirroring iOS exactly. - **Invariant:** payment rows reach Room *only* via the - `refreshDashPayPayments` equivalent (FFI read → Room upsert); - `dashpay_sync_now` reconciles payments **in-memory without persisting** - (identity persist skips payments, `identity_persistence.rs:37-39`). - Android process death is aggressive, so K3's send flow must call - refresh-after-send, and the K1 test suite pins the invariant. -- **Restore direction:** populate the null-stubbed `contact_profiles` / - `payments` arrays in `rs-unified-sdk-jni/src/persistence.rs` - (staging comment :1476-1480, stubs :1848-1853, free-path :2049-2051), - mirroring the Swift restore blocks - (`PlatformWalletPersistenceHandler.swift` ~4918, ~4978). - -**Gate (re-tiered after review):** the persist→wipe→restore→re-read -round-trip runs as an **instrumented test** (extend -`sdk/src/androidTest/.../WalletManagerRoundTripTest.kt`, which already -drives the real native lib on the CI emulator) — payload includes payments -with memo/direction/status, a contact-profile `is_present=false` tombstone, -and ignored senders; the new K1 getters read back restore-injected fixtures -and assert field equality. JVM/Robolectric tests cover handler↔Room mapping -only (they never load the native lib, so they cannot see marshaling bugs — -this was the original spec's top-listed risk guarded by the wrong tier). - -### Milestone K2 — Sync service, seedless unlock, writes - -**Pre-req (security must-fix): mnemonic-handling discipline.** The -existing Kotlin resolver materializes the mnemonic as an immutable JVM -`String` (`WalletStorage.retrieveMnemonic` does `decodeToString()` and -scrubs only the ByteArray; `MnemonicResolverAndPersister.kt:36-42` returns -the String to native). iOS never creates a string-shaped copy: it keeps -XOR-masked UTF-8 bytes (`MaskedMnemonicUTF8`) and writes into Rust's -out-buffer, scrubbing on every access. K2 multiplies resolver calls (the -drain runs it once per queued entry), so **before** wiring the automatic -drain: port the out-buffer + masked-bytes discipline to `WalletStorage.kt` -/ `MnemonicResolverAndPersister.kt` / `mnemonic.rs` (whose "same residual -exposure as iOS" comment is false and must be corrected), and zeroize the -`mnemonic_str`/`mnemonic_c` copies in `signer.rs:342-422` (currently only -`sig_buf` is scrubbed). - -**Bridge (13 exports):** the 7 `platform_wallet_manager_dashpay_sync_*` -fns; the seedless trio `platform_wallet_verify_seed_binds_to_wallet`, -`platform_wallet_pending_contact_crypto_count`, -`platform_wallet_drain_pending_contact_crypto` (takes **both** a -`SignerHandle` and a `MnemonicResolverHandle` — -`rs-platform-wallet-ffi/src/dashpay.rs:757-761`); -`platform_wallet_create_or_update_dashpay_profile_with_signer`, -`platform_wallet_set_dashpay_contact_info_with_signer`; -`dash_sdk_resolver_supports_key_type` (rs-sdk-ffi; consumed by the -production signer — Swift `KeychainSigner.swift`). - -**`DashpaySyncService`** (`sdk/services/`, mirroring -`PlatformWalletManagerDashPaySync.swift`): - -- Owned by the `PlatformWalletManager` instance; started when platform - wallets are present (after load / on the rebind path), stopped and - disposed on the `WalletManagerStore` manager swap. **Not gated on - process lifecycle** — iOS keeps the sweep running while backgrounded - (the OS suspends the process; Android freezes/kills similarly under - modern app-standby), and this matches the manager-owned ownership - doctrine. (The v1 spec's "mirrors scenePhase" claim was wrong — Swift - drives start/stop off wallet-presence/rebind `.onChange`, not - scenePhase. No `lifecycle-process` dependency needed.) -- `isSyncing` / `lastSync` / `pendingAccountBuilds` exposed as `StateFlow`, - updated by a **1 Hz poll with change-gated assignment and stale-key - pruning** — pinned now, not "verify later": that is exactly how iOS does - it (`PlatformWalletManager.swift:1140-1186`; the comment at :1133-1139 - documents why naive re-assignment burned CPU). Natural home: the - `SpvProgressPublisher` pattern. - -**Seedless unlock — invocation topology (domain must-fix; the API method -alone is not the feature):** - -- `unlockWalletFromKeystore(walletId)` = scoped verify → drain, and is - called **automatically, per restored wallet, inside - `loadPersistedWallets`**, best-effort/never-throwing (mirrors - `PlatformWalletManager.swift:477-506`; Kotlin's - `PlatformWalletManager.kt:457` currently documents the absence). This is - load-bearing: the deferred contact-crypto queue is **in-memory by - design** (no persisted table on either platform — do not "fix" that) and - recovery is self-healing only if every launch runs - load → unlock (verify+drain) → sweep. Banner-triggered-only unlock would - leave contacts never finishing establishment after process restart. -- **Seed-mismatch contract:** Rust `SeedMismatch` surfaces as - `ErrorInvalidParameter` (`rs-platform-wallet-ffi/src/dashpay.rs:960-965`); - like Swift, Kotlin disambiguates *only* by scoping the catch to the - verify call (the JNI error code arrives as - `code + PWFFI_CODE_OFFSET`). Publish per-wallet - `draining` / `seedMismatch` / `pendingAccountBuilds` as `StateFlow` - (Swift: `dashPayUnlockStatus`). -- **Re-entrancy guard:** a second unlock while `draining == true` returns - immediately (Swift :622-624) — load-time auto-drain and a user banner - tap must not double-run the ECDH work. -- **Biometric interaction (Android-only failure mode):** Kotlin's - identity-key Keystore alias is auth-gated (30 s validity + - `BiometricGate`) — *stricter than iOS*, whose identity keys are not - auth-gated at all. The reciprocal-accept signing inside a background - drain can therefore throw on an expired auth window with no Activity to - re-prompt. Required behavior: catch, leave the entry queued (the sweep - self-heals), reflect it in the unlock status; instrumented test for the - auth-expired path. -- **Breadcrumb backfill — explicitly not ported.** Swift's unlock also - schedules `scheduleBackfillIdentityKeyBreadcrumbs`, an iOS-legacy - Keychain healing step for pre-breadcrumb installs. The Kotlin SDK is new - — every identity key it has ever created is breadcrumbed at creation — - so there is nothing to heal. Recorded here so its absence is a decision, - not an oversight. - -**Gate:** unit tests + instrumented sync-service lifecycle tests -(start/stop/isRunning; manager-swap disposal; double-start), unlock state -machine with a wrong-seed fixture (seedMismatch path) and the -auth-expired-drain path; write paths against testnet behind -`-Ptestnet=true`. - -### Milestone K3 — DashPay tab UI + parity bookkeeping - -**Bridge (2 exports):** `platform_wallet_build_auto_accept_qr`, -`platform_wallet_send_contact_request_from_qr` (first consumed here). - -Navigation restructure (mirrors Swift `ContentView.swift`): - -- `RootTab`: `SYNC, WALLETS, IDENTITIES, DASHPAY, SETTINGS` — **Contracts - tab is demoted into Settings** (`ContractsHome` becomes an entry in the - Settings screen's Platform section, as on iOS). -- Retire `FriendsScreen` + its route; entry points repoint at the DashPay - tab/contact flows. -- Reset the DashPay tab's identity-picker selection on network switch — - retained Compose state would otherwise query a wallet absent on the new - network-locked manager. - -Port the 10 Swift views (Compose screens under `ui/dashpay/`, one file per -Swift file, testTags = iOS accessibility identifiers, screens driven by -Room Flows / snapshot data classes — never by retained native handles): - -| Swift (`Views/DashPay/`) | Compose target | Notes | -|---|---|---| -| DashPayTabView (909) | `DashPayTabScreen` | identity picker, per-account balances, pull-to-refresh → `syncNow`, unlock banner (reads unlock-status Flow), sub-sheet navigation | -| ContactsView (299) | `ContactsScreen` | Room Flow over established contacts (both-direction join) | -| ContactRequestsView (391) | `ContactRequestsScreen` | incoming accept/ignore + outgoing pending | -| AddContactView (497) | `AddContactScreen` | wallet-scoped DPNS prefix search (300 ms debounce), raw id, QR entry | -| ContactDetailView (561) | `ContactDetailScreen` | payment history (refresh→Room), alias/note editors **surfacing the `ContactInfoPublishOutcome`** — `DeferredUntilTwoContacts` means local-only until ≥2 established contacts and the UI must say so (parity), `SkippedWatchOnly` likewise; hide; send-payment entry | -| SendDashPayPaymentSheet (386) | `SendDashPayPaymentSheet` | amount/memo → `sendDashPayPayment` → txid, then **refresh-after-send** (payments-durability invariant, §K1) | -| DashPayProfileView (188) | `DashPayProfileScreen` | own profile display/edit + auto-accept QR render (ZXing — already a dependency) | -| IgnoredContactsView (181) | `IgnoredContactsScreen` | unignore | -| HiddenContactsView (240) | `HiddenContactsScreen` | unhide | -| DashPayContactMeta (183) | `DashPayContactMeta.kt` | meta store (UserDefaults → SharedPreferences/DataStore; plaintext is parity — iOS documents UserDefaults as "the honest backing" for device-local data), display-name precedence, avatar composable | - -QR scan reuses the already-ported `QrScannerScreen`; the auto-accept -scan-to-send path calls `sendContactRequestFromQR`. - -**New dependency:** Coil (`coil-compose`) for avatar loading — not -currently in `libs.versions.toml`; flagged here because it is the plan's -only new third-party dependency. (ZXing is already present.) - -Parity bookkeeping: full `PARITY.md` DashPay rewrite — a `Views/DashPay/` -section with one row per view, corrected totals (interim stale-claims fix -already landed in K1). - -**Gate:** `:app:assembleDebug` + Compose UI tests mirroring -`DashPayTabUITests.swift`; manual UAT next to the iOS simulator per -`QA_TESTCASES_SPEC.md` flows, including the end-to-end -send→accept→pay testnet run. - -## 5. Interfaces & data flow (summary) - -``` -Compose UI ── StateFlow/Room Flow ── PlatformWalletManager / Dashpay.kt - │ │ (thin, marshal-only) - │ DashpayNative.kt (external fun) - │ │ JNI - ▼ rs-unified-sdk-jni/src/dashpay.rs - Room (Dashpay* entities) │ rlib call - ▲ rs-platform-wallet-ffi (C ABI) - │ persistence callbacks │ - └── NativePersistenceBridge ◄── rs-platform-wallet (all logic) -``` - -- Writes require two callback handles: identity signer (`signer.rs`) and - mnemonic resolver (`mnemonic.rs`) — both exist; DashPay adds no new - callback *types*, only new call sites. Handles are kept strongly - referenced for the duration of each call (GC hazard). -- Contact profiles ride the identity persist/restore callback path - (with tombstone-delete semantics); payments are pull-persisted and - array-restored. The deferred contact-crypto queue is deliberately - not persisted (in-memory + sweep self-heal, both platforms). -- Cold-start contract: `loadPersistedWallets` → per-wallet best-effort - unlock (verify → drain) → sync service start → recurring sweep. -- Threading: FFI calls on `Dispatchers.IO`; Rust→Kotlin callbacks attach - as JVM daemon threads; persistence-handler read-modify-writes run in - Room transactions (callback threads race UI-triggered refreshes - otherwise). - -## 6. Failure modes / risks - -- **Restore-path marshaling bugs** corrupt Rust wallet state on load. - Guard: the K1 instrumented round-trip (real native lib) — JVM tests - cannot see this code. -- **Contact-profile staleness:** upsert-only persist misses tombstones → - stale names/avatars forever. Guard: `is_present=false` delete test (K1). -- **Payment loss on process death:** `syncNow` does not persist payments. - Guard: refresh-after-send + kill/relaunch test (K1/K3). -- **Never-draining wallets:** unlock not wired into load → contacts stuck - pending after every restart. Guard: unlock topology spec (§K2) + - restore→unlock instrumented test. -- **Background drain vs biometric gate:** auth-expired signing during - drain must requeue, not fail silently. Guard: auth-expired test (K2). -- **GC vs callback lifetime** during long drains: strong refs on - signer/resolver bridges per call site; drain stress test. -- **Sync-service leak across network switch:** manager-owned lifecycle, - disposed on `WalletManagerStore` swap; double-start test. UI-side: - identity-picker reset on network change. -- **JNI descriptor lockstep** on the identity persist callback (§4 note): - Rust descriptor + Kotlin signature in one commit. -- **Room migration:** additive-only v3; migration test against `2.json`. -- **Build env:** exFAT gotcha (`build_android.sh` sparse image), NDK r28+, - 16 KB alignment — K1 ends with `./build_android.sh --verify` passing. - -## 7. Test plan - -1. **Instrumented (`connectedDebugAndroidTest`, CI emulator)** — the - load-bearing tier: extend `WalletManagerRoundTripTest` with the DashPay - persist→wipe→restore→re-read round-trip (payments incl. memo/direction/ - status, contact-profile tombstone, ignored senders); K1 getters read - restore-injected fixtures; K2 sync-service lifecycle, unlock - state machine (wrong-seed → seedMismatch; auth-expired drain). -2. **JVM unit (`:sdk:testDebugUnitTest`)** — handler↔Room mapping only - (explicitly *not* the marshaling tier): contact-profile - upsert/delete/backoff, payment row mapping, Room v2→v3 migration. -3. **Compose UI tests** — port `DashPayTabUITests.swift` flows using the - shared testTags (tab presence, add-contact form, requests accept path - with a fake bridge). -4. **Testnet opt-in (`-Ptestnet=true`)** — K1 entry gate: existing - FriendsScreen send→accept→ignore revalidation. K3 exit: end-to-end - send→accept→pay between two fixture identities, mirroring iOS UAT. -5. **CI** — existing `kotlin-sdk-build.yml` runs tiers 1–3. - -## 8. Out of scope - -- Invitations (SPEC.md Milestone 5) — not implemented on iOS either. -- The 24 unconsumed FFI functions listed in §2 (and any new handle-wrapper - types for them). -- `managed_identity_get_contested_dpns_names` — its consumers - (SelectMainName / WalletMemoryExplorer / IdentityDetail) are outside - `Views/DashPay/`; it belongs to the existing non-DashPay PARITY-partial - bucket, not this migration. -- Identity-key breadcrumb backfill (justified in §K2 — no pre-breadcrumb - Android installs can exist). -- Migrating the 17 pre-existing DashPay JNI exports out of `tokens.rs`. -- The 5 non-DashPay `TransitionDetailView` FFI gaps and other PARITY - "partial" items. -- Any change to Rust crates other than `rs-unified-sdk-jni` (a genuine - composite gap, if found, becomes its own reviewed `rs-platform-wallet-ffi` - change). - -## 9. Decisions taken in this spec (previously open) - -- **One PR per milestone** — the milestones carry independent gates by - design; review units should match. -- **Sync lifecycle: manager-owned, not process-lifecycle-gated** (§K2). -- **Poll (1 Hz, change-gated), not events, for sync/unlock status** (§K2). -- **Coil added** as the single new dependency (§K3). - -## 10. Open questions (for Ivan) - -1. **Branch/PR strategy:** land the K-milestones as stacked PRs on top of - `feat/kotlin-sdk-and-example-app` (PR #3999 is already ~50k insertions), - or fold into #3999? Recommendation: **stacked PRs**. -2. **Tab restructure confirmation:** mirroring Swift means demoting the - Contracts tab into Settings on Android too. Confirm parity wins over - Android-specific navigation taste. diff --git a/docs/dashpay/MULTI_ACCOUNT_SPEC.md b/docs/dashpay/MULTI_ACCOUNT_SPEC.md deleted file mode 100644 index dfdf657a79e..00000000000 --- a/docs/dashpay/MULTI_ACCOUNT_SPEC.md +++ /dev/null @@ -1,330 +0,0 @@ -# DashPay simultaneous multi-account contacts — implementation spec - -> **Problem.** DIP-15 lets a contact expose **multiple DashPay accounts** at once — -> each a separate `contactRequest` with a distinct `accountReference` (DIP-15 §8.4, -> §8.9, §10.8). Our contact-state layer collapses everything to **one channel per -> counterparty** (`BTreeMap`, a single-channel `EstablishedContact`), -> and the rotation machinery actively *supersedes* a contact's prior request rather -> than letting accounts coexist. So we can neither represent nor pay across a -> contact's multiple accounts, we always send our own account `0`, and we drop -> `contactInfo.acceptedAccounts` on ingest. -> -> **Status.** REVIEWED (4 lenses, 2026-06-24) — **KEEP DEFERRED** (see *Review -> outcome* below: a foundational blocker B-1 + reopened DoS + abuse surface, and no -> requirement). This feature was **deliberately -> deferred** by the team as *"conditional, not a requirement"* (backlog -> dashpay/platform#4020 multi-account item; `DIP_CONFORMANCE_GAPS.md` §2). There is **no current product -> requirement** forcing simultaneous multi-account. This spec exists so the work is -> *scoped and reviewed* and can be implemented when a requirement appears — and so -> the decision to keep deferring is an informed one. **Do not implement before this -> spec is reviewed and a requirement exists.** -> -> **Source.** Scope map from the 2026-06-24 blast-radius audit (all file:line below -> verified against `feat/dashpay-m1-sync-correctness`, pinned rust-dashcore `b4779fc`). - ---- - -## Review outcome (2026-06-24, 4 lenses) — **KEEP DEFERRED** - -A four-lens review (DIP-15 domain-fit, state-machine feasibility, scope/go-no-go, -security/abuse), each grounded against the code, converged: **the spec is an -accurate scope map, but the feature must NOT be built as designed, and there is no -product requirement driving it. Keep it deferred.** The reviews also corrected -several claims in §0–§4 below (annotated inline as ⚠**REV**). If a requirement ever -appears, **the first deliverable is a focused "channel identity under an opaque -`accountReference`" design note (resolving B-1) — not code.** - -### Blocking findings (must be resolved in a revision before any code) - -- **B-1 — Channel identity is unsolvable from the wire (the foundational blocker).** - The design keys channels by the raw `accountReference`, but DIP-15's - `accountReference = (version<<28) | (ASK28 ^ account)` is a sender-private one-time - pad: the version nibble is cleartext, but `ASK28 = HMAC(sender_secret, compact_xpub)` - is uninvertible by the recipient, **and a rotation ships a new xpub**, so the - low-28-bit value is *uncorrelated* across a rotation. Result: "rotation of added - channel B" is **information-theoretically indistinguishable** from "a brand-new - account." So channels cannot be keyed by `accountReference` and still collapse - rotations. Channel identity must be **out-of-band** (user-assigned at accept time; - every later rotation re-prompts "which channel does this replace?"). This is - permanent UX, not a TODO — and it gates B-2/B-3 below. (`account_reference.rs:41-66`.) -- **B-2 — Keying the collapse by `accountReference` re-opens the PR #3841 sweep - thrash.** Immutable on-chain docs never disappear; a rotated sender leaves both - old+new docs returning every sweep. `newest_received_per_sender` collapses - per-sender *because rotation mutates the reference*; keying the collapse by the - reference produces two survivors that flip-flop the stored channel forever — the - exact regression #3841 fixed. A fixpoint exists only with a rotation-stable key → - loops back to B-1. (`contact_requests.rs:811-829,1087-1117,3103-3105`.) -- **B-3 — The "local channel index" corrupts the receiving derivation path.** - `DashpayReceivingFunds.index` is a **hardened path component** - (`account_type.rs:489`), not just a map key — it selects the BIP32 path the - counterparty derives against. A fabricated local index desyncs our *advertised* - receiving addresses from our *watched* ones → incoming payments to that channel - become invisible. The receiving index must be our **real** DashPay account number - (the one masked into the published `accountReference`); only the *external* account - may use a namespace. The send-side real-account thread (§2.3) is the only correct - mechanism. (`key-wallet account_type.rs:472-526`.) -- **B-4 — `BTreeMap` silently overwrites on collision.** Keying - by a non-unique 28-bit value means two channels masking equal silently shadow each - other (fund misdirection). The on-chain unique index `($ownerId, toUserId, - accountReference)` (`dashpay.schema.json:148-163`) bounds this **per-sender** (a - sender can't broadcast two colliding docs), but the spec must *state and rely on* - that invariant and **reject-on-collision** (insert returning `Some` = loud error), - never overwrite. -- **B-5 — No per-sender flood cap; the re-key converts a flood into pending-queue - exhaustion.** Today `incoming_contact_requests` is one slot per sender + collapse → - a flood is structurally absorbed. The re-key to `(counterparty, accountReference)` - makes each new reference a pending triage prompt (a permanent doc returning every - sweep). Needs a `MAX_PENDING_ADDITIONAL_ACCOUNTS_PER_SENDER` (mirror - `MAX_AUTO_ACCEPT_QUEUED_PER_OWNER`, but per-(owner,sender)); over-cap → **silently - drop, not enqueue**; wire the gate to the existing `ignored_senders` block. -- **B-6 — "Add account" is a phishing / confused-deputy surface.** A *malicious - established contact* can send an add-request whose xpub points at an - attacker-controlled address space (the crypto binds the channel to the contact's - identity, not to the contact being honest). "Add account" must carry the same - trust gravity as accepting a brand-new contact (surface the derived first address; - no one-tap inline accept). The spec frames the gate as anti-flood only and omits - payment redirection. - -### Corrections to the body (factual) -- ⚠**REV §2.2 / Open Q2:** the version nibble is readable but does **not** correlate a - rotation to a specific channel (B-1). Don't claim "consult the version nibble" - resolves rotation-vs-new — it doesn't. -- ⚠**REV §2.1:** strike the "local channel index" for the receiving account (B-3). -- ⚠**REV §2.2:** `acceptedAccounts` per DIP-15 §10.4 stores **only non-version-0** - references — never write channel-0 into it. -- ⚠**REV §4.4:** same-sender collisions are *blocked on-chain* by the unique index; - state this invariant (it's the saving grace) and reject-on-collision (B-4). -- ⚠**REV §4.3:** migration is essentially free — there is **no in-repo SQLite schema**, - `DashMigrationPlan.stages == []` (dev stores recreate from scratch), and contacts - rebuild from chain (metadata rides `contactInfo`). The spec over-worries; the real - plan is "let the store rebuild," with a "wipe local → re-sync reconstructs" test. -- ⚠**REV §3:** T2 (`accepted_accounts` round-trip) is **not** independently valuable — - it writes a field nothing reads (inert). Fold it into T1; do **not** ship standalone. - T1 itself must split into ≥4 PRs (struct re-key / collapse-inversion / user-gate / - account-index thread), each with its own #3841-style fixpoint test. -- **Conformant lower-cost fallback (R1):** DIP-15 §8.4 allows *"either disregard all - future contact requests ... or preferably ask the user."* Silently disregarding - additional requests (≈ today's collapse) is **also conformant** and avoids the - entire B-2/B-3/B-5/B-6 surface — the cheapest path if multi-account is ever wanted - only nominally. - -### Verdict & recommendation -**KEEP DEFERRED.** Upstream (#813) is unblocked, but the feature has a foundational -information-theoretic blocker (B-1), re-opens a fixed DoS (B-2), and adds real abuse -surface (B-4/B-5/B-6) — for **no current requirement**. The review *prevented building -the wrong thing*, which is the point of the pipeline. **Next step only if a -requirement appears:** a B-1 channel-identity design note, then re-spec around it. - ---- - -## 0. What "multi-account" means here (and what it does NOT) - -Two distinct things share the "different `accountReference` from a known sender" -shape and must not be conflated: - -- **Rotation (LIVE today):** the sender rotated the payment xpub for the *same* - logical account; the new request **supersedes** the old (DIP-15 §8.10 immutability - → rotate via a new request). `apply_rotated_incoming_request` - (`state/managed_identity/contact_requests.rs:337-407`) replaces `incoming_request` - in place, tears down the stale external account, rebuilds from the new xpub. The - sync sweep's `newest_received_per_sender` (`network/contact_requests.rs:811-829`) - **discards all-but-newest per sender** — the comment (`:752-765`) calls this "the - idempotency keystone." -- **Simultaneous multi-account (THIS spec):** the sender exposes *additional* live - accounts that must **coexist** as separate channels (DIP-15 §8.4 "Recipients either - ignore subsequent requests or prompt users to select destination accounts"; - §10.8 "additional contact requests require user acceptance; upon approval the new - account reference joins `acceptedAccounts`"). - -These are **antithetical** — rotation's whole purpose is to *prevent* two live -channels per sender. Multi-account must *invert* that for **accepted** additional -accounts while keeping supersede for genuine rotations. The disambiguation is the -crux of this spec (§2.2). - -**Out of scope:** the §10.8 *query-level* flood mitigation ("only the first request -to the bloom filter; filter blocked senders server-side") needs a registered -`dashpay` contract change and stays blocked (Contract track). This spec covers the -**client-side** multi-account model only. - ---- - -## 1. Research — current state (verified) - -### 1.1 What's already multi-account-ready -- **Upstream derivation (#813, merged, in `b4779fc`):** `AccountType::derivation_path()` - for `DashpayReceivingFunds`/`DashpayExternalAccount` uses - `ChildNumber::from_hardened_idx(*account_index)` (`key-wallet/.../account_type.rs:472-531`) - — the friendship path honors a non-zero account. -- **Account collections** are keyed by `DashpayAccountKey { index, user_identity_id, - friend_identity_id }` (`key-wallet/.../account_collection.rs:25-29`) — the - account/UTXO layer already supports multiple accounts per (user, friend). -- **Provider/register signatures already take an account index:** - `receiving_xpub_for(…, account_index, …)`, `account_reference(…, account_index, - version)`, `register_contact_account(…, account_index, …)` (`network/contacts.rs:140`), - `register_external_contact_account` derives `DashpayAccountKey { index }`. - The `accountReference` masking already folds `account_index` into the low 28 bits - correctly (`network/contact_requests.rs:514-551`). - -### 1.2 The bottleneck — contact state collapses to `Identifier` -`ManagedIdentity` (`state/managed_identity/mod.rs:62-85`): -- `established_contacts: BTreeMap` -- `sent_contact_requests: BTreeMap` -- `incoming_contact_requests: BTreeMap` - -`EstablishedContact` (`types/dashpay/established_contact.rs:14-51`) holds **exactly -one** `outgoing_request` + **one** `incoming_request`. It carries a dead -`accepted_accounts: Vec` (`:34`) + `add/remove_accepted_account` (`:138-146`) -with **zero production callers**. - -### 1.3 Hardcoded account `0` on send/build (≈6 sites) -`network/contact_requests.rs:476` (`let account_index: u32 = 0;`), `contacts.rs:397`, -the build sweep `DashpayAccountKey { index: 0 }` (`contact_requests.rs:1398`), the -register-receiving builds (`:1614`, accept `:2259`). - -### 1.4 `accepted_accounts` is lossy -- Codec round-trips it (`crypto/contact_info.rs:133,238-281`, test `:346-366`). ✅ -- Publish hardcodes empty (`network/contact_info.rs:499-506`, "isn't populated yet"). -- `set_contact_metadata` (`state/managed_identity/contact_requests.rs:279-313`) - copies only `alias/note/display_hidden` — **drops `metadata.accepted_accounts`**. -- Not marshalled to FFI/Swift anywhere. - -### 1.5 The recipient-ignores-`accountReference` asymmetry -DIP-15 makes `accountReference` a sender-private one-time pad the recipient **cannot -reliably un-mask** (the 4-way convention split; `DIP_CONFORMANCE_GAPS.md` §3). So the -recipient **cannot** recover the sender's real account number from the wire. It can -only treat the **raw `accountReference` u32** as an opaque channel discriminator, and -derive the actual addresses from the **decrypted xpub** (which is account-correct). -→ multi-account channels must be keyed by the **raw `accountReference`**, not an -unmasked account number. - ---- - -## 2. Chosen approach - -### 2.1 Re-key contact state by `(counterparty, accountReference)` -Replace the single-channel model with a per-contact set of channels keyed by the raw -`accountReference`: -- `EstablishedContact` becomes multi-channel: a `BTreeMap` where `ContactChannel` holds the `{outgoing_request, - incoming_request, payment_channel_broken}` that are today flat on - `EstablishedContact`. Metadata (`alias`, `note`, `is_hidden`, `accepted_accounts`) - stays **per-contact** (one alias for the person, not per channel). -- `incoming_contact_requests` / `sent_contact_requests` re-key to - `(counterparty, accountReference)`. -- Account registration already keys by `DashpayAccountKey { index }`; the channel's - account index comes from the **decrypted-xpub-derived** account, but since we can't - unmask, we allocate a **local channel index** per accepted accountReference and use - it as the `DashpayAccountKey.index` (the xpub is account-correct regardless; the - index only namespaces our local account collection). - -### 2.2 Disambiguate rotation (supersede) vs new account (coexist) — by USER GATE -We cannot tell from the wire whether a new `accountReference` is a rotation or a new -account (§1.5). DIP-15 §8.4/§10.8 resolves this with a **user gate**: -- The **first** request from a sender → auto-established (channel 0), as today. -- A **subsequent** request with a new `accountReference` from an established contact → - surfaced as a **pending additional-account request**, NOT auto-applied. The current - auto-`apply_rotated_incoming_request` supersede is **replaced** by: enqueue as - pending; the user chooses **"replace addresses" (rotation)** or **"add account" - (coexist)**. - - "Replace" → supersede (today's behavior, the channel's request is swapped). - - "Add" → the `accountReference` joins `accepted_accounts`, a new coexisting channel - is built, and the receival/external accounts are registered under a fresh local - index. -- `accepted_accounts` is the **persistent record of which additional references the - user accepted** — so the gate is sticky across sweeps/restarts (an accepted ref is - never re-prompted; an un-accepted one is dropped per §10.8, not bloom-filtered). - -This **inverts the idempotency keystone** (`newest_received_per_sender` collapse) for -accepted references: the sweep must keep every *accepted* `accountReference`'s newest -doc, and collapse only *within* an accountReference (rotation of that channel). That -is the load-bearing, highest-risk change (§4.1). - -### 2.3 Send side — thread a real account (gated behind a UI affordance) -Thread an `account: u32` param from the send FFI through the ≈6 hardcoded sites. The -example app gains an optional "send from account N" affordance; default stays `0`. -**Not a standalone change** — only meaningful once §2.1 state can hold the result. - -### Alternatives rejected -| Approach | Why rejected | -|---|---| -| Unmask `accountReference` to recover the account number, key by that | Recipient can't reliably un-mask (4-way convention split, §1.5). | -| Auto-accept every new `accountReference` as a new account | Violates §10.8 flood mitigation; an attacker floods accounts. | -| Keep single-channel, just stop dropping `accepted_accounts` (Slice A) | Inert today (nothing produces a non-empty value); preserves a field nothing writes — YAGNI. | -| Reuse rotation as the foundation | Rotation *prevents* coexistence by design (§0); it's scaffolding to bypass, not build on. | - ---- - -## 3. Layered change map (task split) - -| Layer | Change | Rough size | -|---|---|---| -| **T1 — Rust contact state** | multi-channel `EstablishedContact`; re-key the 3 maps to `(counterparty, accountRef)`; per-contact metadata; invert the sweep collapse to per-accountRef; user-gate additional accounts; populate `accepted_accounts` | large, the core | -| **T2 — `accepted_accounts` round-trip** | `set_contact_metadata` copies it; publish reads it; (independently shippable as the data-layer floor of T1) | ~15-30 LOC | -| **T3 — Changeset/persistence** | accountRef in `SentContactRequestKey`/`ReceivedContactRequestKey` + `established` map key; carry `accepted_accounts` | medium | -| **T4 — FFI** | `account_index`/`accepted_accounts` on `ContactRequestFFI` + persist callbacks; +1 send param; pending-additional-account surface | medium | -| **T5 — Swift/SwiftData** | accountRef in `PersistentDashpayContactRequest` unique key; per-account grouping in ContactsView/ContactRequestsView/ContactDetailView/AddContactView/SendDashPayPaymentSheet; "add account vs replace" prompt; send-from-account picker | large, UI-heavy | -| **T6 — Tests** | unit (re-key, coexist, user-gate, accepted_accounts round-trip, rotation-still-supersedes-within-a-channel); `dp_*` e2e multi-account send/receive (devnet) | medium | - -The persistence (T3) + Swift (T5) layers need a **migration** for existing -single-channel rows (map the lone channel to `accountReference` of its stored -request). - ---- - -## 4. Failure modes & risks (for reviewers to stress) - -1. **Inverting the idempotency keystone (T1, highest risk).** `newest_received_per_sender` - collapse and `apply_rotated_incoming_request` supersede are the mechanism that keeps - the recurring sweep from thrashing. Splitting "collapse per sender" into "collapse - per (sender, accountRef), keep all accepted refs" must not reintroduce the - multi-doc sweep thrash that PR #3841 fixed (the `newest_received_per_sender` - comment at `:752-765`). Needs the same red→green pinning as the original fix. -2. **Rotation vs add ambiguity.** If the user picks "replace" we must supersede the - *right* channel; if "add" we must not later mistake the rotation of an added channel - for yet another new account. Channels keyed by raw `accountReference` make a - *rotation within a channel* indistinguishable from a *new account* unless the - version nibble is consulted — but the recipient ignores `accountReference`. Resolve: - does "rotation of an added account" even occur, and how is it keyed? -3. **Migration.** Existing persisted single-channel contacts (SQLite + SwiftData) must - map to the new keyed shape without losing alias/note/hidden/broken state or - double-counting payments. -4. **The `accountReference == 0` collision.** Today everything is accountRef `0`-ish; - re-keying must handle the legacy `0` channel and a genuinely-new `0`-masked account - (collisions are possible — `accountReference` uniqueness isn't guaranteed, DIP-15 §7). -5. **UI blow-up.** A contact rendering as N rows vs one row with N accounts; the send - sheet picking an account; the "add vs replace" prompt. Scope creep risk. -6. **No requirement = speculative surface.** Building this without a driving use case - risks shipping inert complexity (Rule 2). The spec must end with a go/no-go. - ---- - -## 5. Verification plan - -- **T2 (unit):** `set_contact_metadata` preserves `accepted_accounts`; publish emits the - contact's accepted set; round-trip through the codec. (TDD red→green.) -- **T1 (unit):** an established contact accepts a second `accountReference` → two live - channels; a rotation of channel 0 supersedes channel 0 only; the sweep does not thrash - across two recurring passes (mirror the PR #3841 idempotency pin); an un-accepted - additional request stays pending and is not watched. -- **Migration (unit):** a persisted single-channel contact loads as a one-channel - multi-account contact with metadata intact. -- **Integration (`dp_*` e2e, devnet-gated):** send from a non-zero account; receive + - accept a contact's second account; pay across both. - ---- - -## 6. Open questions for review (resolve before any coding) - -1. **Go/no-go:** is there an actual requirement for simultaneous multi-account, or does - this stay deferred? (The spec's existence shouldn't force the build.) -2. **Rotation-within-an-added-channel (§4.2):** does it occur in practice, and how is a - channel keyed if not by raw `accountReference`? (Possibly `(accountReference & - 0x0FFFFFFF)` ignoring the version nibble — but the recipient can't unmask… revisit.) -3. **Metadata granularity:** confirm `alias/note/is_hidden` are per-contact (per person) - and only `accepted_accounts` + `payment_channel_broken` are per-channel. -4. **UI model:** one contact row with N accounts (recommended) vs N rows. Send sheet - default account. -5. **Could T2 (accepted_accounts non-lossy) ship now** as a tiny data-preservation fix - ahead of the rest, or does shipping an inert field invite confusion? (Lean: ship with - T1, not standalone.) -6. **Migration safety** for existing devnet/testnet contacts. diff --git a/docs/dashpay/PENDING_CONTACT_CRYPTO_RELOCATION_SPEC.md b/docs/dashpay/PENDING_CONTACT_CRYPTO_RELOCATION_SPEC.md deleted file mode 100644 index 4ff5929ce53..00000000000 --- a/docs/dashpay/PENDING_CONTACT_CRYPTO_RELOCATION_SPEC.md +++ /dev/null @@ -1,188 +0,0 @@ -# Relocate the deferred-crypto queue from the wallet to the identity - -**Status:** implemented (historical reviewed spec). The in-memory relocation is -complete; durable cold-load restoration remains deferred as described in §7. -**Scope:** `packages/rs-platform-wallet` (+ a one-line doc-comment in `rs-platform-wallet-storage`). -Rust-only. FFI signatures, Swift, and whole-struct serialization are **unchanged**. - -## 1. Problem - -`pending_contact_crypto: Vec` lives on the **wallet-level** struct -`PlatformWalletInfo` (`wallet/platform_wallet.rs:57`), a sibling of `identity_manager`. Every -*other* DashPay artifact already lives **per-identity** on `ManagedIdentity` -(`state/managed_identity/mod.rs`): `established_contacts`, `sent_contact_requests`, -`incoming_contact_requests`, `dashpay_rescan_triggered`, `auto_accept_verify_failed`, -`dashpay_payments`. The queue is the lone exception, and each `PendingContactCrypto` entry carries -`owner_identity_id` — manually re-storing the exact container key that is *implicit* for the -others. Identity-network code (`IdentityWallet`) reaches *up* into wallet state to touch it. - -This is **cleanup, not a bug fix**. The queue is functionally correct where it is; the value is -consistency/maintainability. The risk is a routing regression on a signer-gated DashPay path (a -mis-routed drain → a contact account never gets built → a DashPay payment silently can't resolve -its external account). So it is speced, reviewed, isolated (its own commit/PR), and tested. - -## 2. Current architecture (verified in research + review) - -- **Type** (`changeset/changeset.rs:1075`): `PendingContactCrypto { owner_identity_id, contact_id, - op: PendingContactCryptoOp, enqueued_at_ms }`. Dedup key `PendingContactCryptoKey = - (owner_identity_id, contact_id, kind)`; `upsert_pending_contact_crypto` keeps ≤1 entry per key. -- **Receiver**: methods are on `IdentityWallet` (bound to a `wallet_id`, - NOT one identity); reaches the queue via `wm.get_wallet_info(&self.wallet_id)`. -- **`IdentityManager` has TWO buckets** (`state/manager/mod.rs:69-83`): - `wallet_identities: BTreeMap>` and - `out_of_wallet_identities: BTreeMap`. Today's flat wallet-level queue - is **bucket-agnostic**. This is the crux of the refactor's one real trap — see §3 D4 / §5 R1. -- **Enqueue** — exactly THREE production sites, each already holding `&mut PlatformWalletInfo` and - the owner id: `enqueue_pending_auto_accepts` (`contact_requests.rs:1553`), - `enqueue_deferred_contact_crypto` (`:1734`), `enqueue_contact_info_decrypt` - (`contact_info.rs:385`). Each pairs the in-memory `upsert_pending_contact_crypto(&mut - info.pending_contact_crypto, e)` with a changeset `pending_contact_crypto_added: vec![e]` and a - `persister.store(...)`. (`payments.rs:2757` is a **test**, not a production enqueue.) -- **Drain** (`drain_pending_contact_crypto`, `contact_requests.rs:1781`): read-lock → clone the flat - queue → **drop lock** → async match over the owned snapshot (each arm routes every side-effect by - `entry.owner_identity_id`; the loop body never touches the queue) → write-lock → single - `retain_drained_by_snapshot(&mut info.pending_contact_crypto, &cleared)`. - `drain_auto_accepts` (`:2160`) is the signer-gated sibling for `AutoAccept` ops; its removal block - also marks `auto_accept_verify_failed` per owner. -- **Count** (`pending_contact_crypto_count`, `:1763`): `count_account_build_ops` over the flat queue - (excludes `ContactInfoDecrypt`). Backs the "waiting for unlock" UI banner. -- **Op ownership asymmetry (subtle, load-bearing for R1):** `RegisterReceiving` / - `RegisterExternal` are owned-only (`build_contact_accounts` gates on `identity_index.is_some()`, - `contact_requests.rs:1661`); `ContactInfoDecrypt` is owned-only (`contact_info.rs` iterates only - `wallet_identities`). But `AutoAccept` is **NOT** gated — `enqueue_pending_auto_accepts` runs for - every identity in the sweep's `all_identities()` loop (both buckets), so an `AutoAccept` op can - legitimately land on an **out-of-wallet** identity's queue. -- **Changeset** (`PlatformWalletChangeSet.pending_contact_crypto_{added,cleared}`, - `changeset.rs:1189`): flat top-level Vecs; entries carry the owner. -- **Apply is a no-op for the queue** (`wallet/apply.rs:115`): the in-memory queue is mutated - *directly* at the enqueue/drain sites; the changeset deltas are for persistence, not in-memory replay. -- **The queue IS durably persisted** — via the `rs-platform-wallet-storage` SQLite backend: table - `pending_contact_crypto` keyed `(wallet_id, owner_identity_id, contact_id, kind)` - (`migrations/V001__initial.rs:87`), live writer `apply_pending_contact_crypto` - (`sqlite/schema/pending_contact_crypto.rs:49`) driven from `apply_changeset_to_tx` - (`sqlite/persister.rs:1063`), reader `all_pending_contact_crypto` (`:108`), round-trip test - (`:161`). The **FFI/SwiftData** backend has no callback for it, so on iOS it is not durably - persisted — but that is one backend, not "the field is vestigial." **The changeset fields are - load-bearing; nothing here gets deleted.** Because the SQLite writer keys on - `(wallet_id, owner_identity_id, contact_id, kind)`, moving the *in-memory* field per-identity - changes **zero** SQLite writes (the owner stays on every row — D2/D5). -- **Not restored on cold load** (`manager/load.rs:102-114`): starts `Vec::new()`; the sweep - re-enqueues. A restore path is half-wired but blocked upstream — see R6. -- **FFI** (`ffi/dashpay.rs:733, 798`): `platform_wallet_drain_pending_contact_crypto` / - `_count` take a **wallet** handle and call `wallet.identity().()`. Called from Swift - (`PlatformWalletManager.swift:640,968`). D4 keeps the `IdentityWallet` method signatures → - **no FFI or Swift change**. -- **Accessors** (`state/manager/accessors.rs`): `managed_identity(&Identifier)` / - `managed_identity_mut(&Identifier)` (`:70,75`) already resolve across **both** buckets via - `location_index`. Enumerators `all_identities() -> Vec<&Identity>` and `identity_ids() -> - Vec` exist, but **there is no iterator yielding `&ManagedIdentity`** — one is added - (D3). - -## 3. Design - -Move the in-memory Vec to `ManagedIdentity`, keyed by the owning identity. Keep -persistence/apply/FFI shapes unchanged to bound the blast radius. - -- **D1 — Field placement.** Add `pending_contact_crypto: Vec` to - `ManagedIdentity`; remove it from `PlatformWalletInfo`. Init `Vec::new()` in `ManagedIdentity::new` - + `new_out_of_wallet` (next to `established_contacts`); drop the 5 `PlatformWalletInfo` init sites. -- **D2 — Keep `PendingContactCrypto` unchanged (keep `owner_identity_id`).** It is the drain's - routing key (each op's side-effects derive from it) AND the SQLite key column; keeping it holds the - type, dedup key, changeset, and their tests stable. The in-memory redundancy (owner == container) - is benign. *Dropping it is out of scope* (§7). -- **D3 — Access by identity.** - - Enqueue + per-owner removal: existing `managed_identity_mut(&owner)` (spans both buckets). - - Drain-snapshot + count: **add** `IdentityManager::managed_identities(&self) -> impl Iterator` chaining `out_of_wallet_identities.values()` with - `wallet_identities.values().flat_map(|m| m.values())`. Iterate **both buckets** (R1). -- **D4 — Drain/count: flat snapshot → unchanged async loop → per-owner-grouped removal. Both - buckets. Same signatures, same wallet-wide semantics.** Concretely (do NOT write an outer - per-identity loop — it borrows `&mut ManagedIdentity`/holds the lock across `.await` and will not - compile): - 1. **Snapshot:** under a read guard, gather every resident identity's queue into one flat owned - `Vec` (`managed_identities().flat_map(|m| m.pending_contact_crypto.iter() - .cloned())`), then drop the guard. `count` sums `count_account_build_ops` per identity the same - way. - 2. **Async loop:** unchanged — it already keys every lookup/side-effect off - `entry.owner_identity_id` and touches the queue nowhere. - 3. **Removal:** under a write guard, group `cleared_snapshots` by `owner_identity_id` and, per - owner, `retain_drained_by_snapshot(&mut managed_identity_mut(&owner).pending_contact_crypto, - &subset)`. Fully synchronous under one guard — nothing crosses `.await`. - `retain_drained_by_snapshot`'s value-equality (which includes the owner) transfers unchanged. - For `drain_auto_accepts`, the same per-owner hop also carries the `auto_accept_verify_failed` - mark (already per-owner today). - - *Send-drain scope (Q1 resolved → wallet-wide):* keep `payments.rs:575` - `self.drain_pending_contact_crypto` draining every resident identity, not just the sender. It is - safe and useful — the Keychain provider is wallet-**seed**-scoped, so one identity's send - correctly finishes other identities' pending builds as a free, correct side effect; no - cross-identity dependency exists (accounts are keyed by both ids). Narrowing to sender-only is a - one-line snapshot filter with only a mild latency/UX argument — deferred. -- **D5 — Changeset + apply + FFI unchanged.** Keep `pending_contact_crypto_{added,cleared}` flat - (entries carry owner), keep `apply.rs` ignoring them, keep the FFI signatures. Only the *in-memory* - field + its access sites move. The SQLite writer is unaffected (owner-keyed). -- **D6 — `ManagedIdentity` field is persistence-inert. Do NOT add it to `IdentityEntry::from_managed`** - (`changeset/changeset.rs:332`), which explicitly enumerates the persisted per-identity fields. - Leaving it out keeps the queue in-memory-only per identity (like `established_contacts` / - `dashpay_rescan_triggered`), so it is NOT double-persisted (once via the flat changeset delta, - never via a snapshot). This preserves D5. - -## 4. Alternatives rejected - -- **Per-identity changeset routing:** unnecessary — apply ignores the queue deltas and the SQLite - writer already keys by owner. Adds churn + a migration question for zero benefit. -- **Drop `owner_identity_id`:** forces the changeset/SQLite key to carry the owner another way and - rewrites the dedup key + tests. Higher risk, separable, deferred (§7). -- **Move only to `IdentityManager`:** leaves the queue one flat list one struct deeper — still not - keyed by identity. Doesn't achieve the goal. -- **Defer / TODO:** legitimate (a reviewer's call, given this path just absorbed the scalar - elimination). Decision: proceed now as an isolated, tested, reviewed change so it's bisectable. - -## 5. Failure modes & risk register - -| ID | Risk | Mitigation | -|----|------|------------| -| R1 | **[Critical]** Drain/count iterate only the owned bucket → an `AutoAccept` op on an *out-of-wallet* identity is silently never drained/counted (auto-accept never fires; banner under-counts). This reproduces the exact silent signer-gated regression this refactor fears. | D3/D4 iterate **both** buckets (`managed_identities()`). Test: an out-of-wallet identity holding an `AutoAccept` entry is still counted and drained. | -| R2 | Drain restructure holds a `&mut ManagedIdentity` or the wallet-manager guard across `.await` → won't compile / deadlock (the register fns re-acquire the non-reentrant manager lock). | D4: flat owned snapshot → drop guard → async loop → re-lock → synchronous per-owner removal. Never a live `values_mut()` borrow across `.await`; snapshot ids/entries into owned Vecs, re-lookup per owner (mirrors the sweep). | -| R3 | Enqueue routes to a wrong/absent identity. | Owner is already in hand at all 3 sites; add `managed_identity_mut(owner)` before upsert. `None` (identity removed in the narrow collect-guard→write-guard window) → log + drop (benign; the identity is gone). Test: enqueue lands on the owner's queue and nowhere else. | -| R4 | `count`/`drain` totals drift (miss an identity). | Same signatures + wallet-wide semantics over both buckets; test with 2 identities each holding entries asserts the aggregate equals the sum. | -| R5 | Auto-accept verify-failure marking regresses. | Marking is already per-owner (`managed_identity_mut(owner).mark_...`); folds into the same removal hop. Keep its test. | -| R6 | Future cold-load restore drops entries (a persisted row whose owner identity isn't applied yet). | The move introduces an ordering constraint the flat queue didn't have: any future restore must apply identities **before** fanning each persisted row out to its owner's queue. Documented here + in the storage doc-comment so whoever finishes the (currently blocked) restore doesn't reintroduce the drop. Not active today (nothing restores). | -| R7 | Identity removal now GC's its queue (dies with the `ManagedIdentity`). | Behavior change vs the flat wallet Vec (entries used to outlive owner residence). **Accepted** — it's orphan cleanup; a transient remove/re-add loses queued ops that the sweep re-enqueues on re-add. Noted, no code needed. | -| R8 | Identity removed between drain snapshot and removal → its keys aren't retained-off/cleared. | Net-identical to today: the op's target is gone and `apply` ignores the `cleared` delta anyway. Noted. | - -## 6. Change list (critical files) - -- `wallet/platform_wallet.rs` — remove the field + doc. -- `wallet/identity/state/managed_identity/mod.rs` — add the field + doc. -- `wallet/identity/state/managed_identity/identity_ops.rs` — init in `new` + `new_out_of_wallet`; **do not** touch `from_managed`. -- `wallet/identity/state/manager/accessors.rs` — add `managed_identities()` iterator (both buckets). -- `wallet/identity/network/contact_requests.rs` — 2 enqueues (`:1553`, `:1734`); `drain_pending_contact_crypto` (snapshot both buckets, per-owner removal); `pending_contact_crypto_count` (sum both buckets); `drain_auto_accepts`; `empty_info` test helper (`:3254`); the drain/count/auto-accept tests. -- `wallet/identity/network/contact_info.rs` — enqueue (`:385`). -- `wallet/identity/network/payments.rs` — send drain unchanged (`:575`); **re-seed** the drain tests (`:2757`, `:2811`) with real registered identities (out-of-wallet for the `identity_index==None` case). -- `manager/load.rs:114`, `manager/wallet_lifecycle.rs:249`, `wallet/apply.rs:420`, `wallet/platform_wallet_traits.rs:43,56` — drop the `PlatformWalletInfo` init sites. -- `rs-platform-wallet-storage/src/sqlite/schema/pending_contact_crypto.rs:100-106` — update the doc-comment that names `PlatformWalletInfo.pending_contact_crypto` as the restore target (now per-identity fan-out by `owner_identity_id`; see R6). -- `ffi/dashpay.rs` — unchanged; verify it still compiles. - -## 7. Explicitly out of scope - -- Dropping `owner_identity_id` from `PendingContactCrypto`. -- Deleting/altering the `pending_contact_crypto_{added,cleared}` changeset fields — they are - persisted by the SQLite backend (§2). NOT vestigial. -- Wiring the cold-load restore (blocked upstream); this change only leaves it a correct ordering note. -- Any Swift / FFI-signature change. - -## 8. Test / verification plan - -- **R1 (the one that matters):** an out-of-wallet identity holding an `AutoAccept` entry is counted - by `pending_contact_crypto_count` and processed by the drain — asserts both buckets are iterated. -- **R3:** enqueue lands on the owner identity's queue and no other identity's. -- **R4:** 2 resident identities each holding queue entries → aggregate count + drain == sum. -- **R2:** re-uses `retain_drained_by_snapshot`'s existing value-equality test shape, per-owner. -- **R5:** auto-accept verify-failure marks the right identity. -- Cold-load: a freshly-loaded identity has an empty queue; the sweep re-enqueues (behavior unchanged). -- Keep green (re-seeded where noted): `send_payment_runs_pending_contact_crypto_drain`, - `drain_completes_register_receiving_and_clears_queue`, - `drain_leaves_register_external_it_cannot_complete`, - `account_build_count_excludes_contact_info_decrypt`, the changeset merge/dedup tests. -- `cargo test -p platform-wallet -p platform-wallet-ffi`; `cargo clippy … --all-targets` clean; - `build_ios.sh --target sim` BUILD SUCCEEDED (FFI unchanged → Swift unaffected). diff --git a/docs/dashpay/QA_TESTCASES_SPEC.md b/docs/dashpay/QA_TESTCASES_SPEC.md deleted file mode 100644 index 55d0456ee12..00000000000 --- a/docs/dashpay/QA_TESTCASES_SPEC.md +++ /dev/null @@ -1,225 +0,0 @@ -# DashPay (DIP-15 / DIP-16) QA test-case expansion — SPEC - -**Status:** reviewed (4-lens multi-agent pass folded in) -**Target file:** `packages/swift-sdk/SwiftExampleApp/TEST_PLAN.md` §4.10 (+ §5, §6, §1) -**Base:** branched off `feat/dashpay-m1-sync-correctness` (PR #3841, -"fix(platform-wallet)!: complete dashpay") — the DashPay views, `docs/dashpay/`, -and the features these rows describe live there, not yet in `v3.1-dev`. -**PR target:** `v3.1-dev`, to merge **after** #3841 lands (pure-docs diff; -rebased so it shows only the TEST_PLAN.md / spec changes). -**Renders in:** [`dashpay/qa-dashboard-site`](https://github.com/dashpay/qa-dashboard-site) -once the sibling seed task re-seeds the `dash-qa` contract from the updated plan. - ---- - -## 1. Problem - -`TEST_PLAN.md` §4.10 (DashPay) had **6 coarse rows** (`DP-01..06` + cross-ref -`MW-03`) at "feature exists" granularity, and their entry points were **stale**: -they cited `FriendsView` / `AddFriendView`, which #3841 replaced with a dedicated -DashPay tab (`DashPayTabView`, `AddContactView`, `ContactsView`, -`ContactRequestsView`, `ContactDetailView`, `DashPayProfileView`, -`IgnoredContactsView`, `SendDashPayPaymentSheet`). - -#3841 implements substantial **DIP-15** surface the catalog did not exercise -(per the branch's audit `docs/dashpay/DIP_CONFORMANCE_GAPS.md`): -`encryptedAccountLabel` send+receive, QR auto-accept (build + paste-to-add), -on-chain `contactInfo` publish, and the §12.6 incoming-payment backfill rescan. -**DIP-16** is the SPV sync layer underneath (covered by `CORE-07`; its -DashPay-specific facet is the single backfill row `DP-10`). - -## 2. Goal & non-goals - -**Goal:** correct the stale `DP-01..06` entry points and add rows for the -**user-observable, simulator-drivable** DIP-15/16 DashPay flows #3841 ships. - -**Non-goals (out of scope):** -- **DIP-15 crypto internals** (ECDH, 69-byte compact xpub, `accountReference` - masking, avatar hash/dHash) — already Rust known-answer tests; not app rows. -- **Gap / absence rows** (`🚫`/`➖`) for unimplemented features (multi-account - `Account≠0`, `acceptedAccounts` flood mitigation, invitations). Drivable only. -- **A DIP-16 section.** SPV sync is `CORE-07`; the DashPay facet is `DP-10`. -- **New table columns.** Keep the uniform 6-col `ID | Action | Layer | Tier | - Status | Entry point & test notes`; cite DIP §s inline. (The dashboard - normaliser reads no section field; a 7th column is dropped on seed.) -- **A `tags` column.** Tag assignment for the v5 contract is the seed tool's job - (not in these repos). Open question §7. - -## 3. Corrections to existing rows (`DP-01..06`) - -Entry points updated to the #3841 DashPay tab; FFI-symbol naming (matches the -existing §4.10 convention). Merged sub-flows folded in as notes: -- **DPNS-add path** → a note on `DP-01` (precedent: `ID-04`/`MW-01` list input - methods in one row; DPNS resolution itself is `DPNS-03`/`DPNS-07`). -- **Payment-channel-broken** state → a note on `DP-03` (precedent: `ID-12`/`DOC-07` - attach gating state to the action row). -- **Avatar** (url + Rust-computed hash/fingerprint) → a note on `DP-04`. -- `DP-06` **Reject → Ignore** rename (the branch made reject a reversible local mute). - -## 4. New rows (drivable DIP-15/16 flows) - -| ID | Tier | DIP-15 § | Behavior | -|---|---|---|---| -| DP-07 | Common | §8.5 | Attach `encryptedAccountLabel` on send; counterparty sees "Their account" (decrypted, incoming-row only). | -| DP-08 | Thorough | §8.13 | QR auto-accept: build "Add me" QR; add via pasted URI → auto-accepted without manual accept. Paste-drivable; camera = Manual variant. | -| DP-09 | Thorough | §10 | Publish encrypted on-chain `contactInfo`; ≥2-contact gate → `.published` / `.deferredUntilTwoContacts` / `.skippedWatchOnly`. | -| DP-10 | Manual | §8.7/§12.6 | Incoming-payment backfill rescan (no UI trigger; `reconcile_dashpay_rescan` rewinds SPV `synced_height`). Env-limited; the §12.6 payment-loss regression pin. | - -`DP-10` note: the branch's `DIP_CONFORMANCE_GAPS.md` §1.1 still marks this MISSING, -but that audit predates the implementing commit `18483e4232` -(`reconcile_dashpay_rescan`, wired in `manager/dashpay_sync.rs`, 4 unit tests) — -so Status=✅ is correct. - -## 5. Cross-cutting edits (applied) - -- **§6 index** — DashPay: `DP-01..06, MW-03` → `DP-01..10, MW-03`. -- **§5 by-tier** — Common `31→32`, Thorough `35→37`, Manual `1→2` (`CORE-08, DP-10`). -- **§5 by-layer (automatable; Manual EXCLUDED)** — Platform `~72→~75`; **Cross - unchanged** (DP-10 is Manual). -- **§1 worked example** — "list the manual tests" → `CORE-08, DP-10`. - -## 6. Final row set - -6 corrections (`DP-01..06`) **+ 4 new** (`DP-07` account label, `DP-08` QR -auto-accept, `DP-09` on-chain `contactInfo`, `DP-10` backfill rescan). - -## 7. Open questions - -1. **Tags** — does the seed tool assign v5 tags (e.g. `dip15`, `sync`) from - Domain/§6, or should the plan encode them? Needs the seed tool (not in repos). -2. **DP-07 a11y id** — the "Their account" block in `ContactDetailView` has no - `accessibilityIdentifier`, so DP-07 asserts on visible text. A 1-line app - change would make it cleanly automatable — a trivial follow-up, deliberately - kept out of this docs-only PR. - -## 8. Verification plan - -1. **Render check** — IDs match `^DP-\d+$`; tier/category present so the dashboard - matrix charts them (the normaliser only hard-requires `testId`). -2. **Drive each new row** with the `simulator-control` skill on a booted sim; two - on-device wallets where a counterparty is needed (`DP-07`/`DP-08`, cf. `MW-03`). - Verify against **persisted SwiftData state**, not UI alone (§1 pass criteria). - `DP-10` is Manual → skip-and-flag in automation. -3. **No code change** — pure TEST_PLAN.md edit. The seed task re-seeds `dash-qa`; - the dashboard renders. - -## 9. Review provenance - -Four independent review lenses (DIP domain-fit, scope/simplicity, automatability/ -entry-point accuracy, catalog conventions) ran against the draft. Key folds: -- Added `DP-09` (on-chain `contactInfo`) — the draft wrongly excluded it as - "local-only / no UI"; it is a drivable DIP-15 §10 publish. -- Merged the draft's separate DPNS / avatar / channel-broken rows into notes on - `DP-01` / `DP-04` / `DP-03` (catalog precedent; lean set). -- Dropped a 7th `DIP-15 §` column (normaliser ignores it; breaks the 6-col shape). -- Confirmed `DP-10`'s rescan is implemented + wired; corrected the `wallet.pass` - SF-symbol-vs-a11y-id confusion in `DP-07`. - -## 10. Runtime verification (simulator) - -Driven on a booted iOS simulator (iPhone 17) against a live devnet build with real -DashPay fixtures (wallet "SimB", 1 identity, 2 contacts, 5 requests), via the -`simulator-control` skill. Read-only structural pass — navigated to each row's -entry point and confirmed the cited screens/controls exist; **no broadcasts fired**. - -Confirmed live: -- `DP-01` — `AddContactView` mode picker + resolved-recipient preview + **Send Request**. -- `DP-03` — `ContactDetailView` `dashpay.detail.sendDash`. -- `DP-04` — `DashPayProfileView` **Edit** (→ editor) + avatar. -- `DP-05` — DashPay tab: `ContactsView` (search, contacts, segment, profile header). -- `DP-07` (send) — `dashpay.addContact.accountLabel` renders once a recipient resolves. -- `DP-08` — build: `dashpay.profile.qrURI` emits a real `dash:?du=…&dapk=…` URI + QR - image; add: `AddViaQRSheet` `dashpay.qr.uriField`. -- `DP-09` — the **Alias / Note / Hide** editor calls `saveContactInfo` → - `setDashPayContactInfo`; the in-app footer confirms the ≥2-contact encrypted-publish - gate. **Refined the row** accordingly — the original "distinct from a local note" - wording was wrong (the same editor caches locally *and* publishes on-chain). - -Code-confirmed but not rendered this pass (no fixture): `DP-02` / `DP-06` -(`dashpay.request.accept` / `.ignore` — need an *incoming* pending request); -`DP-07` receive-side "Their account" (only shows when a contact sent a label); -`DP-10` (no UI by design — automatic in DashPay sync). Live broadcast execution and -the two-wallet loops (`DP-07`/`DP-08`) are the next step, gated on credits + a -counterparty identity. - -A full code re-audit of every row (4 parallel passes) confirmed 8/10 rows + all the -§5/§6/§1 count edits accurate, and corrected 5 row-wording inaccuracies: DP-01 (open -button id `dashpay.addContact` vs the in-sheet mode toggle), DP-02/DP-05 -(`EstablishedContact` is a Rust/FFI handle, **not** a SwiftData model — the tab views -are backed by `PersistentDashpayContactRequest`), DP-03 (channel-broken is any -permanent channel failure, not only key rotation), and DP-08 (TTL is exactly 3600s). - -## 11. Implementation observations (for #3841 — surfaced during verification, NOT addressed here) - -These are defects/smells in the DashPay *implementation* found while auditing the -plan. They are out of scope for this docs PR; recorded for the #3841 author. - -1. **Stale doc-comment** — `ContactRequestsView.swift:5-8` says incoming rows carry - "**Accept / Reject**", but the button is **Ignore** (reject was replaced by the - reversible local mute). Same file `:35-37` carries an internal `§6.4` spec-gate - ref (rots; against the timeless-comment convention). -2. **Multi-wallet mis-attribution risk** — `DashPayProfileEditorView` falls back to - `walletManager.firstWallet` when `walletId` is nil (`IdentityDetailView.swift:1316`); - in a multi-wallet setup a profile update could submit under the wrong identity. - Already acknowledged in an in-code comment as needing tightening. -3. **Handle-leak smell** — `acceptContactRequest`'s returned `EstablishedContact` - (FFI handle wrapper) is discarded with `_ =` at both call sites - (`ContactRequestsView.swift:228`, `AddContactView.swift:487`); leaks per accept - unless the wrapper frees the handle in `deinit` (worth confirming a `deinit`). -4. **QR clock edge** — `build_auto_accept_qr` derives expiry from - `SystemTime::now()…unwrap_or(0)`; a pre-1970 / badly-skewed clock yields an - already-expired QR. Harmless on a real device. -5. **No collision handling in `AddViaQRSheet`** — pasting a URI from someone who - already sent *you* a request broadcasts a duplicate outgoing request rather than - offering "Accept instead" (`AddContactView` handles this; the QR path does not). - -By-design / cosmetic (no action expected): avatar hash does not change if the image -bytes are swapped behind the same URL; a corrupt/hostile incoming account label -unpads to garbage and is coerced to `None` (shows no "Their account" — relevant to -DP-07 negative testing); `setDashPayContactInfo` maps unknown future outcome bytes to -`.published` on the Swift side; a stale memo doc-comment in `SendDashPayPaymentSheet` -(DashPay payments always pass `memo: nil`); a dead `_ = bytes` local + a redundant -`?? nil` duplicated across four profile-cache reads. - -## 12. Live end-to-end run (freshly-built binary) - -Built `build_ios.sh --target sim` from `feat/dashpay-m1-sync-correctness` HEAD -(`47d9044b5a`), installed on two iOS simulators, and drove the flows on-chain -against devnet (two funded identities per side): **Eve** (SimB) ↔ **Alice / Bob / -Dolly(7A8E)** (SimA), each ~25–30B credits. Verified against SwiftData ground -truth (and on-chain for the payment). - -| Row | Result (fresh build) | Evidence | -|---|---|---| -| DP-01 send | ✅ | labeled contact request broadcast (sheet dismissed, no error); also the DP-02 reciprocal send | -| DP-02 accept | ✅ | 7A8E accepted Eve → reciprocal `7A8E→Eve` row created (established) | -| DP-03 payment | ✅ one direction | Eve→Alice **0.001 DASH** real L1 tx (input spent, change `74,899,477`, fee `226` duffs, txid `850433507c88…560e`) — **after starting Core SPV**. ⚠️ only the forward direction was driven; see the bidirectional gap below | -| DP-04 profile | ✅ | publicMessage updated on-chain → SwiftData (`QA fresh-build 16:10`) | -| DP-05 view | ✅ | contacts / requests / profile rendered throughout | -| DP-06 ignore | ✅ | registered a fresh identity (asset-lock funded, ChainLock proof) → sent Eve a request → Eve **ignored** it (→ ignored-senders) → **un-ignored** (reversed). Local-only mute | -| DP-07 label | ✅ fresh first-contact | Bob→**EveN** (fresh pair) labeled send; EveN accepted → decrypted "Their account" = the sent label. Confirms decrypt-on-accept end-to-end | -| DP-08 QR | ✅ fresh first-contact | Alice built `dash:?du=…&dapk=…`; **EveN** pasted + `sendContactRequestFromQR`; Alice **auto-accepted** (reciprocal, no manual Accept) — *after unlocking Alice's wallet* (signer-backed drain; see note) | -| DP-09 contactInfo | ✅ on-chain | log: `Published contactInfo document identity=Eve contact=Alice` — the `.published` outcome, not just local persist | -| DP-10 backfill rescan | ✅ mechanism (logs) | the §12.6 rescan fired live: `DashPay rescan: lowered SPV synced_height … floor=51112` → `dash_spv…filters: synced_height 51112 fell below committed_height 52175, restarting scan`. No UI trigger (Manual tier); the full restore-from-seed payment-recovery remains a device exercise | - -**10/10 flows verified live on the fresh build** — DP-01..09 driven on-chain -(SwiftData + chain; DP-07/DP-08 via a freshly-registered unconnected identity to -get clean first-contact pairs), DP-09's on-chain publish + DP-10's backfill-rescan -both confirmed in the Rust logs. - -**Gap (DP-03 bidirectional):** only the **forward** payment (Eve→Alice) was driven. -The reverse (Alice→Eve) is symmetric by design — once established, each party derives -the other's payment address from the exchanged xpubs — but it was **not** verified -live (SimA's app context had flipped to a separate testnet wallet set). DP-03 now -explicitly requires verifying **both** directions; the reverse remains to be driven. - -**Finding (DP-08):** the QR auto-accept *reciprocal* is signer-backed, so it only -fires once the recipient's wallet is **unlocked** (the "N contacts waiting to finish -setup → Unlock" drain). The request and auto-accept proof reach the recipient -immediately, but the established reciprocal lands after unlock — so "auto-accept" is -not fully hands-off. Worth surfacing in DIP-15 §8.13 expectations. - -Two plan corrections came out of the run: **DP-03** now records the Core-SPV -precondition (a DashPay payment is an L1 broadcast — fails "SPV Client not started" -if SPV is stopped); **DP-07** now states the label decrypts **on accept**, not on -ingest. diff --git a/docs/dashpay/QR_AUTO_ACCEPT_SPEC.md b/docs/dashpay/QR_AUTO_ACCEPT_SPEC.md deleted file mode 100644 index 23b84e11764..00000000000 --- a/docs/dashpay/QR_AUTO_ACCEPT_SPEC.md +++ /dev/null @@ -1,270 +0,0 @@ -# DashPay QR Auto-Accept (DIP-15) — Implementation Spec - -Decision (2026-06-24): build the DIP-15 `autoAcceptProof` QR flow, **faithful to the -DIP-15 wire formats** so we are a correct reference implementation. Research (incl. the -finding that no reference client implements this today, so it is iOS-first / convention- -setting) informed this spec. Invitations (DIP-13) are queued next. - -> **Status:** IMPLEMENTED (2026-06-24) across Rust + FFI + Swift; `build_ios.sh` green, -> platform-wallet 299 + ffi 117 tests green. REVIEWED (4-lens: DIP-fidelity / security / -> feasibility / scope) and revised — §10. The first draft's §4 was materially wrong -> (verify can't use `&Wallet` in the seedless drain; the drain lacks the identity signer; -> the sweep parser drops the proof) — all fixed. **Owner decisions:** TTL = 1h fixed; -> auto-accept = always automatic; whole feature in one pass; DIP-literal HD-derived owner -> key (scoped raw-key export). **On-device:** My-QR UI + DPNS-name guard verified; the full -> QR-generate→scan→auto-accept loop is pending a DPNS-named *local* identity (the available -> devnet wallets have on-chain names not cached in `PersistentIdentity.dpnsName`). Follow-up -> (P3): resolve the owner's DPNS name on-chain in `build_auto_accept_qr` when the local -> field is empty. - -## 1. Problem & goal - -DashPay contact establishment is two manual taps. DIP-15 defines an optional -`autoAcceptProof` so a party can pre-authorize automatic acceptance — the canonical use -case is a **merchant / in-person QR**: show a QR, the scanner sends a contact request that -the owner's client auto-accepts with no manual tap. The proof crypto exists and is -unit-tested (`auto_accept.rs`) but is **dormant** — nothing generates, verifies, or acts -on it. Goal: wire the full three-role flow, end to end (Rust + FFI + Swift + on-device). - -### Non-goals -- Not Invitations (DIP-13 `dashpay://invite` + AssetLock onboarding) — separate, queued next. -- No Android interop today (no reference client verifies the proof); iOS-first. We still - follow DIP-15 byte layouts so a future client can interop. -- No new on-chain artifact beyond the already-defined optional `autoAcceptProof` field. -- No `di=` identity-id URI fallback in v1 (DIP uses `du`; require a DPNS name — §9). -- No TTL picker, no opt-in toggle (always automatic) in v1 (§9). - -## 2. The DIP-15 model — three roles - -1. **Owner (QR shower, "Bob").** Derives an auto-accept key at `m/9'/5'/16'/expiry'`, - embeds the **private key + expiry** in a QR (`dash:?du=&dapk=`), - shows it. (`expiry = now + 1h`.) -2. **Scanner ("Carol").** Scans, resolves `du`→Bob's identity, decodes `dapk`→(private key, - expiry), derives her friendship `accountReference` to Bob, **signs `Carol.$ownerId ‖ - Bob.toUserId ‖ accountReference` with the handed key**, and sends a contactRequest to - Bob carrying that proof. -3. **Owner receives + auto-accepts.** Bob's client (at a signer-present drain) verifies the - proof against **his own** re-derived auto-accept **public** key and, if valid and - unexpired, **auto-accepts** (sends the reciprocal) with no manual tap. - -Why the scanner signs (not the owner): the signed message includes the scanner's -`$ownerId`, unknown at QR-create time — so the owner delegates signing via the (expiry- -bounded) private key. This per-sender binding means a leaked proof can't be replayed by a -*different* sender. - -## 3. DIP-15 wire formats — normative-for-us - -These are wire-faithful to DIP-15 (fidelity review: byte-for-byte match). Where DIP-15 is -silent, the value below is **normative for our implementation** — a future interop client -MUST match it or verification silently fails. - -**Auto-accept key blob** (`dapk` value), 38 bytes for ECDSA: - -| field | size | value | -|---|---|---| -| key type | 1 | `0x00` (ECDSA_SECP256K1) | -| timestamp/expiry (= derivation index) | 4 | u32, **big-endian** *(DIP-silent → normative)* | -| key size | 1 | `0x20` (32) | -| key | 32 | secp256k1 **private** key | - -**Proof blob** (`autoAcceptProof` field), 70 bytes for ECDSA, 38–102 range: - -| field | size | value | -|---|---|---| -| key type | 1 | `0x00` | -| key index (= expiry, same value as the blob) | 4 | u32, **big-endian** | -| signature size | 1 | `0x40` (64) | -| signature | 64 | compact ECDSA | - -**Signed message** *(DIP names the fields; hashing/encoding DIP-silent → normative)*: -`SHA256($ownerId(32) ‖ toUserId(32) ‖ accountReference(4, little-endian))`, where -`$ownerId` = the contactRequest **sender (scanner)**, `toUserId` = the QR **owner**, and -`accountReference` is the **raw masked u32** the contactRequest carries (`version<<28 | -masked_index`). Matches the existing `auto_accept.rs::build_message_hash`. **Security pin -(§6):** the verifier MUST bind `$ownerId` to the **consensus-authenticated document owner -id** (`doc.owner_id()`), never a self-reported field. - -**Derivation path**: `m / 9' / 5'(mainnet, else 1') / 16' / expiry'`, all hardened; `expiry` -≤ 2^31−1 (hardened-index bound, ~year 2038 — reject at encode time). Matches code. - -**URI**: `dash:?du=&dapk=` (contact-only). Matches the -DIP-15 example. No `di=` fallback in v1. - -## 4. Seedless integration (the corrected crux) - -Our wallets are `ExternalSignable` — no seed in Rust; key material is reachable only via -the Keychain resolver/provider. The background sweep is **signerless**. Both verify -(needs the owner's auto-accept key) and auto-accept (sends a signed state transition) need -key material, so **neither runs in the sweep** — they ride the deferred-crypto queue + -the signer-present drain. The first draft got the mechanics wrong; corrected: - -### 4.1 Sweep (signerless) — read the proof, enqueue, bounded -- **FIX (feasibility #2):** `parse_contact_request_doc` must read - `props.get("autoAcceptProof")` into the parsed `ContactRequest` (today it's hard-coded - `None`, so the proof is dropped before the queue). Mirror the outgoing reader. -- After `add_incoming_contact_request`, if the request carries an `autoAcceptProof` that - passes a cheap **structural pre-check** (length 38–102, key-type `0x00`), enqueue - `PendingContactCryptoOp::AutoAccept { sender_id }` (dedup key `(owner, sender, AutoAccept)`). -- **DoS bound (security #4):** cap queued `AutoAccept` ops per owner (constant, e.g. 64); - beyond the cap, skip enqueue (the request is still manually acceptable — nothing lost). - Log the drop (no silent cap). - -### 4.2 Drain (signer present) — needs BOTH signers -- **FIX (feasibility #3 / scope M1):** the drain needs the identity `Signer` - (to send the reciprocal) **and** the `ContactCryptoProvider`. Thread a `signer` into - `drain_pending_contact_crypto` and add a `signer_handle` to the drain FFI (matching the - send/accept FFIs). Existing arms ignore it (additive bound). **Note:** the drain FFI is - the same one `unlockWalletFromKeychain` calls (needs-unlock work) — that call site now - passes the Swift `KeychainSigner` too. -- Per `AutoAccept` entry, in order: - 1. **Local verify FIRST, before any network fetch** (security #4 — anti-DoS): build the - path `m/9'/coin'/16'/expiry'` (expiry from the proof header), derive the owner's - auto-accept **public** key via `provider.receiving_xpub(&path).public_key` (**FIX - feasibility #4** — verify needs only the pubkey; no `&Wallet`), then - `verify_auto_accept_proof_with_pubkey(pubkey, proof, sender_id = request.sender_id - (= doc.owner_id), recipient_id = self_identity, account_ref = request.account_reference)`. - 2. **Expiry check** against the **same** timestamp that keyed verification - (`now > expiry → reject`). - 3. If valid + unexpired → `accept_contact_request_with_external_signer(request, signer, - provider)` (sends the reciprocal; idempotent — adopts if already reciprocated). -- **Verdict mapping (security #3):** invalid signature / wrong params / expired / - out-of-range index (the `Err` from path derivation) ⇒ **permanent: clear the entry** - (the request falls back to a normal manual-acceptable pending request). Signer/network - unavailable ⇒ **transient: leave queued** for the next drain. Never `mark_channel_broken` - (there's no channel yet). - -Consequence: auto-accept completes at the owner's next signer-present moment (unlock or any -DashPay action), not instantly in the background. Consistent with the seedless model. - -## 5. Interface / data flow per layer - -### 5.1 Rust — `auto_accept.rs` (extend; keep existing tested fns) -- KEEP `derive_auto_accept_private_key(wallet, network, expiry)` (owner, QR-create). -- ADD `encode_auto_accept_key_blob(secret_key, expiry) -> Vec` / - `decode_auto_accept_key_blob(&[u8]) -> Result<(SecretKey, u32)>` (38-byte `dapk`). -- ADD `sign_auto_accept_proof(secret_key, scanner_id, owner_id, account_ref, expiry) -> Vec` - — scanner signs with the **handed** key. Message bytes = `scanner_id ‖ owner_id ‖ - account_ref(LE)` (the existing `build_message_hash`); a doc-comment ties the param names - to DIP roles (**scope M2** — the current `generate` models the owner as `sender_id`, - the opposite; don't invert at wiring). -- ADD `verify_auto_accept_proof_with_pubkey(pubkey, proof, scanner_id, owner_id, account_ref) -> bool` - — pure, no wallet (the drain's verify path). -- ADD `auto_accept_proof_expiry(proof) -> Option` and fold the expiry check into the - acceptance entry point — **do not** expose a public bare `verify` that returns `true` - for an expired proof (**security #2** foot-gun). Keep `verify_auto_accept_proof(wallet,…)` - for owner-side tests only. -- ADD a URI codec `encode_dashpay_contact_uri(username, key_blob)` / - `parse_dashpay_contact_uri(&str) -> Result<(username, key_blob)>` (pure, testable). -- Refactor `generate_auto_accept_proof` to `derive + sign` (test/convenience). -- Remove the stale `// TODO: Where and how we use these helpers?` and fix the docstring - that references a now-real `verify_auto_accept_proof_with_pubkey` (**scope N3**). - -### 5.2 Rust — changeset.rs + contact_requests.rs (flow) -- `PendingContactCryptoOp::AutoAccept { sender_id }` + `PendingContactCryptoKind::AutoAccept` - — 9 sites (feasibility #1 change-list): enum, kind, `kind()`, storage `KIND_LABELS`, - `kind_db_label`, the `kind_labels_match_enum` test, the drain's exhaustive `match`, and - `count_account_build_ops` (decide inclusion — **yes**, so the needs-unlock banner counts - pending auto-accepts; reword the banner copy, **scope S3**). -- `parse_contact_request_doc` reads `autoAcceptProof` (§4.1). -- `sync_contact_requests` enqueues `AutoAccept` (bounded) when a proof is present. -- `drain_pending_contact_crypto` gains the `signer` param + the `AutoAccept` arm (§4.2). -- Scanner send reuses `send_contact_request_with_external_signer(..., auto_accept_proof)` - (already threaded). **scope M3:** the scanner must derive its `accountReference` first - (in-signer, masked over the friendship xpub) and sign the proof over that **exact** value - before broadcast — test that the signed `accountReference` equals the document's. -- DPNS resolve: `IdentityWallet::resolve_name(&str) -> Option` (feasibility #5; - not `search_names`). - -### 5.3 FFI (rs-platform-wallet-ffi) -- `platform_wallet_build_auto_accept_qr(wallet, identity_id, out_uri…)` — owner: resolve - the wallet's DPNS name (error if none), `expiry = now + 3600`, derive the key, build the - `dash:?du=…&dapk=…` URI; return it. (Single Rust entry — no decisions in Swift.) `now` is - passed in from Swift (FFI can't read the clock deterministically) or read via a host hook. -- `platform_wallet_send_contact_request_from_qr(wallet, signer, core_signer, uri, out…)` — - scanner: parse URI → resolve `du` → decode `dapk` → (derive accountRef, sign proof) → send - the contactRequest with the proof. One call. -- `platform_wallet_drain_pending_contact_crypto` gains `signer_handle: *mut SignerHandle` - (the identity signer) alongside the existing `core_signer_handle` (§4.2). - -### 5.4 Swift (SwiftExampleApp) -- **My QR** (net-new, `DashPayProfileView`): a "Show my QR" affordance rendering the URI - from `build_auto_accept_qr` via the existing `generateQRCode` helper. -- **Scan** (net-new entry in the DashPay tab toolbar): present `QRScannerView`; add a new - parse branch + result type (`ScannedContact{username, keyBlob}`) to `QRPayloadParser` - (the existing `ScannedPayment` path doesn't fit a no-address URI — **scope N2**), route to - `platform_wallet_send_contact_request_from_qr`. -- **Drain call-site:** `unlockWalletFromKeychain` now passes the `KeychainSigner` to the - drain FFI (the added `signer_handle`). -- **Feedback (scope S4):** the auto-accepted contact lands in `ContactsView` via `@Query`; - add a light signal (the needs-unlock banner already counts the pending `AutoAccept`, so it - shows "1 contact waiting…" until the drain completes, then it appears as a contact). - -## 6. Security (4 must-fixes folded) - -1. **Consensus-authenticated sender binding (must-fix #1):** verify binds `$ownerId = - doc.owner_id()`. A malicious holder of a leaked QR key *can* sign a proof naming any - sender, but cannot broadcast a contactRequest *as* a victim — platform consensus - requires the doc to be signed by the owner's identity key. The verify gate MUST use the - document owner id, never a proof-internal/client value. -2. **No expired-but-valid foot-gun (must-fix #2):** the only acceptance entry checks expiry - against the same timestamp that keyed verification; no public bare `verify` returns - `true` for an expired proof. -3. **Drain verdict mapping (must-fix #3):** invalid/expired/bad-index → permanent-clear; - signer/network → transient-leave (§4.2). Prevents forever-churn. -4. **Queue bound + verify-before-fetch (must-fix #4):** cap `AutoAccept` per owner; run the - local ECDSA verify + expiry before any `Identity::fetch`, so a spam-N-identities attacker - can't turn the owner's unlock into O(N) network round-trips. -- **Private key in QR:** intrinsic to DIP-15 (the scanner must sign; the owner can't - pre-sign without the scanner's id). Scoped (only auto-accept, not payments/identity), - expiry-bounded (**1h**), blast radius = unwanted contact spam (removable via ignore). - Acceptable documented trade-off, tightened by the short TTL (no off-switch since - auto-accept is always-on, so the short TTL is the mitigation). -- **Replay:** signed message binds `(sender, owner, accountReference)`; the doc's unique - index is `($ownerId, toUserId, accountReference)` — no cross-sender replay, no on-platform - dup. Cross-network separated by coin-type in the path. - -## 7. Failure modes -- **Signer absent when a proof arrives:** enqueued (bounded), completes on next drain; - surfaced by the needs-unlock banner. -- **Expired / invalid / forged proof:** verify-gate rejects, entry cleared (permanent); - request remains manually acceptable. -- **`du` resolves to wrong/missing identity:** scanner send fails loudly; no contact. -- **Owner has no DPNS name:** `build_auto_accept_qr` errors at QR-create (v1 requires `du`). -- **Queue flood:** bounded per owner; junk cleared by local verify before any fetch. -- **Expiry index overflow (> 2^31−1):** rejected at encode (and verify path-derivation errors → permanent-clear). - -## 8. Test plan -- **Rust unit (auto_accept.rs):** key-blob round-trip; URI round-trip; **cross-actor** sign - (loose key, scanner) → verify-with-pubkey (owner's re-derived pubkey) succeeds; wrong - sender/owner/accountRef fails; expiry extraction + now ≤/≥ expiry; truncated/oversize/bad - key-type rejected; structural pre-check. -- **Rust flow (contact_requests.rs):** parser reads `autoAcceptProof`; ingest-with-proof → - `AutoAccept` enqueued (and bounded — Nth+1 dropped); drain valid+unexpired → reciprocal - sent + cleared; expired → cleared, not accepted; invalid → cleared; signerless/transient → - stays queued; **signed `accountReference` == document's** (scope M3). -- **FFI:** null/oversize/bad-URI input validation; build-QR → parse round-trip; drain with - the new signer handle. -- **Swift build:** `build_ios.sh` green. -- **On-device (two sims):** A "Show my QR" → B scans → sends; A unlock/drain → contact - auto-accepts (established, no tap on A); expired-QR path rejected. - -## 9. Decisions (resolved 2026-06-24) -1. **TTL = 1 hour, fixed** (named constant `AUTO_ACCEPT_TTL_SECS = 3600`). DIP-15 is silent - on the value (only mandates the timestamp *is* the expiry); 1h is the safe default given - auto-accept is always-on (no off-switch). No picker in v1. -2. **Auto-accept = always automatic.** No opt-in toggle. Valid + unexpired proofs - auto-accept in the drain. -3. **Scope = whole feature in one pass** (Rust + FFI + Swift + on-device), committed in - logical layers on the branch. -4. **`du`-only** (no `di=` fallback); require a DPNS name to build a QR. - -## 10. Review resolutions (4-lens, 2026-06-24) -- **DIP-fidelity:** wire-faithful, no byte fixes; pinned BE + SHA256/LE as normative (§3). -- **Security:** 4 must-fixes folded (§6); private-key-in-QR accepted as DIP-intrinsic, - mitigated by the 1h TTL. -- **Feasibility (§4 rewrite):** verify via `provider.receiving_xpub(path).public_key` (no - `&Wallet`); drain gains the identity signer + FFI `signer_handle`; the sweep parser must - read `autoAcceptProof`; use `resolve_name`. Queue variant change-list = 9 sites. -- **Scope:** `du`-only + fixed TTL (cut `di=`/picker); cross-actor + `accountReference` - ordering tests; banner counts `AutoAccept`; My-QR + Scan are net-new UI; clean stale - `auto_accept.rs` docstrings. diff --git a/docs/dashpay/SIGNER_SEED_ELIMINATION_SPEC.md b/docs/dashpay/SIGNER_SEED_ELIMINATION_SPEC.md deleted file mode 100644 index a0594bd68d6..00000000000 --- a/docs/dashpay/SIGNER_SEED_ELIMINATION_SPEC.md +++ /dev/null @@ -1,666 +0,0 @@ -# DashPay Signer-Based Seed Elimination — Spec - -Status: DRAFT v3 (revised after a 3-agent deep design review: seedless -background-sync architecture, signer/host-primitive model, security & -failure-mode audit) -Branch: `feat/dashpay-m1-sync-correctness` (PR #3841) -Cross-repo: required key-wallet method (`extended_public_key`) has LANDED; -pinned `rust-dashcore` rev already bumped. - -## 1. Problem - -PR #3639 ("external signable wallets", v3.1-dev) set this codebase's -posture: a registered/restored wallet holds **no resident seed** -(`WalletType::ExternalSignable`). Private-key work is done by passing a -**Keychain-backed `Signer`** per operation; the seed lives only in the iOS -Keychain. - -The DashPay paths added in PR #3841 did not follow that model — they reach -for the resident seed (`send_payment` passes the `Wallet` to `build_signed`; -`derive_contact_xpub` calls `wallet.derive_extended_public_key`; contact -encrypt/decrypt + `accountReference` + contactInfo derive raw secrets off -the `Wallet`). To make them work, `manager/attach_seed.rs::attach_wallet_seed` -re-derives a signing `Wallet` from the Keychain seed and grafts it onto the -loaded wallet via `std::mem::swap`. **That defeats the external-signable -posture** (the seed becomes resident for the whole session) and is a -workaround. - -The resolved **import-wallet bug** was the same disease for identity keys -(Swift re-derived identity scalars from the mnemonic during discovery); -fixed by the carry-scalar change (later reworked into the derive-sign-destroy resolver — see `IDENTITY_KEY_SCALAR_ELIMINATION_SPEC.md`). - -### Goal - -Every DashPay private-key operation runs through a Keychain-backed host -primitive; the wallet seed is **never made persistently resident**; -`attach_wallet_seed` (+ `unlockWalletFromKeychain`'s re-attach + the FFI -export + the dual-gate/`mem::swap`) is **deleted** — but only after the -background sync sweep is seedless-safe (§4.9 ordering constraint). - -### Honest scope of the security win (corrected after the security audit) - -This does **not** make the seed "never resident." Verified facts, to be -stated plainly so the win is not over-credited: - -- **The full BIP-39 64-byte seed + master xprv are reconstructed in one - contiguous buffer per operation** (`MnemonicResolverCoreSigner::resolve_derived_xprv` - — `seed: Zeroizing<[u8;64]>`, master xprv on the next lines; sibling - `sign_with_mnemonic_resolver.rs`). The whole wallet is derivable from that - buffer for the duration of the op. -- **The read is unlock-gated, not biometric-gated.** The Keychain mnemonic is - `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` with **no `LAContext` / - `SecAccessControl`** on the read path (`WalletStorage.swift`). The - `.biometryCurrentSet` stash exists but is **unused**. So "user present" - really means "device unlocked" — any in-process code can drive the resolver - while unlocked. -- **The wipe is best-effort.** Byte buffers use `Zeroizing` (volatile + fence, - runs on unwind). The two `ExtendedPrivKey` scalars use secp256k1's - `non_secure_erase` (fills `[1u8;32]`, self-disclaimed as non-secure; - `ExtendedPrivKey` has no `Drop`/`Zeroize` upstream). There is an **error- - /unwind-path residue gap** (§4.2 hardening). - -The real, defensible benefit is a **smaller in-memory time-window** for the -root secret — per-operation-and-wiped vs `attach_wallet_seed`'s session-long -resident `Wallet` — plus consistency with the #3639 posture. It is a modest, -honest improvement, not "the seed is never in RAM." (The dashj / -dash-shared-core reference clients hold the decrypted seed for the whole -session — see §8 — so there is no off-the-shelf signer-based DashPay to copy.) - -### Non-goals - -- Changing `downgrade_to_external_signable` (`wallet_lifecycle.rs:251`) — it - is what makes the seed absent; it stays. -- Re-introducing an in-memory-seed wallet (the dashj model). -- Wiring QR-based auto-accept — tracked in the backlog (dashpay/platform#4020) (helpers KEPT, not - deleted; §2 note). - -### Q2 scope, status & completion criteria (2026-06-23) - -**Q2** (the PR reviewer ask) = *remove the assign-seed workaround* = delete -`attach_wallet_seed` (this §; §4.9). Live status: the backlog issue dashpay/platform#4020 (authoritative tracker). - -**Done + verified** (branch `feat/dashpay-m1-sync-correctness`; platform-wallet -292/292; glue builds host + `aarch64-apple-ios-sim`): §2 inventory sites **#1–#6** -— the entire seedless contact-request flow (send/accept/drain/always-enqueue -sweep), the `ContactCryptoProvider` seam + signer host primitives (ECDH, -accountReference, contactInfo seal/open, wrong-seed check), the deferred-crypto -queue + SQLite persistence, and C3 (resident ECDH path deleted). Discovery is -NOT a rewrite target — the **carry-scalar fix is kept** (§1). - -**Remaining for Q2 (do in this order). Folds in the 4-lens plan review -(feasibility / security / scope-dedup / adversarial), which corrected two -over-optimistic items in an earlier draft of this banner — see the MUST-FIX -notes.** - -1. **#7 contactInfo (the load-bearing item).** - - Add `contact_info_seal` AND **`contact_info_open`** to `ContactCryptoProvider` - (+ glue impl over the signer primitives + `SeedCryptoProvider` test impl). - **MUST-FIX (review):** publish is NOT seal-only — it must DECRYPT existing - owned docs to decide update-vs-create (the doc↔contact binding lives inside - `encToUserId` ciphertext; `contact_info.rs:435-447`), so it needs `open`. - - Refactor the shared helper `fetch_decrypted_contact_infos` (resident-hardcoded - at `:206`/`:450`, used by BOTH publish and the signerless sweep) into a public - high-water scan (no keys) + a provider-`open` decrypt step. Thread `crypto` - into `set_contact_info_with_external_signer` (publish) and the FFI - (`platform_wallet_set_dashpay_contact_info_with_signer` gains a - `core_signer_handle` — ABI break, like send/accept). - - **MUST-FIX (security): root-path provenance.** Build the contactInfo root - path in **Rust** via `identity_auth_derivation_path_for_type(net, ECDSA, - identity_index, root_key_id)` (never Swift); pin the parity test against that - REAL path, not `test_path()` — a wrong root silently writes undecryptable - contactInfo with no on-chain oracle. - - **MUST-FIX (security): high-water.** Publish is signer-present, so derive the - high-water `derivationIndex` from a FRESH full decrypt, or refuse to publish — - NEVER fall back to `0`/stale (collides the unique `($ownerId, rootIndex, - derivationIndex)` index / reuses a key). - - Implement the `ContactInfoDecrypt` **drain op** (currently a no-op stub, - `contact_requests.rs:1440`): re-fetch owned docs + `contact_info_open` via the - provider + re-run `validate_contact_request`-equivalent. Re-fetch = **testnet - validated**. `derive_contact_info_keys` (resident twin) is deleted ONLY after - both publish AND this sweep/drain path no longer call it. - - **MUST-FIX (security): confused-deputy.** The drain (and opportunistic drains) - must re-validate the queue entry's `owner_identity_id` is owned by THIS wallet - before decrypting/registering. - -2. **Discovery/loading — NO library change (corrected; was wrong in the earlier - draft).** The FFI already routes external-signable wallets through - `discover_from_master` / `load_identity_by_index_from_master` (via - `resolve_master_from_resolver`), and the `ResidentWallet` variants are the - **live path for genuine resident-key wallet TYPES** (`WalletType::Mnemonic`/ - `Seed`, e.g. raw-seed imports with no persisted mnemonic) — NOT dead duplicates. - So **keep** them; do **NOT** attempt the deep `verified_scalar`-drop rewrite - (that's the env-blocked architectural change, and unnecessary — carry-scalar is - kept). The only Q2 work here: (a) confirm every discovery/loading caller passes - a non-null resolver after the deletion makes external-signable the universal - posture (the FFI already errors on null — `identity_discovery.rs:194`); (b) the - test-helper rework in step 3. NOTE: the §2 "exhaustive" table is exhaustive over - *DashPay-contact* paths; the discovery resident derive `derive_identity_auth_keypair` - (`identity_handle.rs:191`) is a resident-key-TYPE path that legitimately stays. - -3. **Test-helper rework + Swift.** ✓ DONE. The test helpers were made seedless - earlier (`c42d2e413e`). Swift (`70aaf32f9f`): `unlockWalletFromKeychain(_:)` - now verifies-binds + drains-on-unlock (no seed graft); send/accept/contactInfo - thread the resolver `core_signer_handle`. Verified by regenerating the - xcframework header (`build_ios.sh --target sim`) + an arm64-sim SwiftExampleApp - build (BUILD SUCCEEDED). - -4. **Delete** `attach_wallet_seed` + FFI export + dual-gate/`mem::swap` + the dead - `dash_sdk_dashpay_*` rs-sdk-ffi surface (4 fns, zero Swift callers — confirmed) - + the legacy `KeychainSigner.sign(...)->Data?` nil-swallow. - - **MUST-FIX (security): atomic wrong-seed wiring.** ✓ DONE (Rust, `fe3ab74e19`): - `attach_wallet_seed` (lib + FFI + dual gate) deleted and `verify_seed_binds` - (`PlatformWallet` method + `platform_wallet_verify_seed_binds_to_wallet` FFI) - landed in the same commit — signer-derived BIP44-0 xpub vs the persisted one, - mismatch → `SeedMismatch`. The comparison lives in `verify_seed_binds`, which - derives the xpub through the `ContactCryptoProvider::receiving_xpub` seam (a - generic derive-at-path) — no redundant trait method. (The signer's - `verify_binds_to_xpub` primitive was NOT used and was deleted post-review as - dead code; the live path reimplements the equality in `verify_seed_binds`.) - The dead `dash_sdk_dashpay_*` surface was removed earlier (`db18688545`). - ✓ Swift wiring DONE (`70aaf32f9f`): the verify FFI is called at unlock and the - `KeychainSigner.sign(...)->Data?` nil-swallow is deleted (see step 3 Swift). - - **SHOULD-FIX (security): §4.2 sibling-FFI leak.** ✓ DONE (`feb266fd1b`): the - `WipingXprv` RAII guard now wraps `master`/`derived` in - `rs-platform-wallet-ffi/src/sign_with_mnemonic_resolver.rs`, scrubbing on the - error/unwind paths the Ok-only `non_secure_erase` missed. - -**Done when:** -- ✓ `git grep attach_wallet_seed` empty (outside docs/regenerated headers). -- ✓ `cargo test -p platform-wallet` green (292) + glue (`platform-wallet-ffi`) green. -- ✓ `build_ios.sh --target sim` regenerates the header (verify FFI present, attach - gone, send/accept/contactInfo carry `core_signer_handle`) + SwiftExampleApp - builds clean (arm64 sim, BUILD SUCCEEDED). -- **On-device acceptance — VALIDATED on devnet `paloma` (2026-06-23)** via idb UI - automation across **two simulators** (sim A = funded `Test_devnet`, 9 DASH, 3 - identities; sim B = freshly created `SimB` wallet + new identity "Eve"). Every - signing op below ran through the Keychain resolver with **no resident seed**: - - ✓ App builds, installs, launches, runs full (SDK init, network switch, wallet - list/detail, DashPay sync) on the new seedless binary — no crash. - - ✓ **Seedless Core payment + IS-lock** — sim A sent 1 DASH to sim B's address; - tx signed via the resolver, broadcast, **InstantLock validated** (this is the - real wrong-seed-would-fail path: the seedless wallet signed a real Core tx). - - ✓ **Seedless identity registration** — sim B: asset lock → InstantSend proof → - ChainLock proof → Platform registration, all via the resolver ("Identity - created" `BfWHEg…`). - - ✓ **Seedless DPNS name registration** (`eveqaseed1ess2026`) + **profile publish** - ("Eve") — both Platform writes via the resolver. - - ✓ **Seedless contactInfo publish** — `setDashPayContactInfo` - (`core_signer_handle`) published an encrypted contactInfo doc, **create** - (`updated=false`) **and update** (`updated=true`). - - ✓ **Seedless contact request SEND** (Alice→Eve) — `send_contact_request_with_signer` - (`core_signer_handle`): registered the DashpayReceivingFunds account. - - ✓ **Seedless contact request ACCEPT** (Eve→Alice) — - `accept_contact_request_with_signer` (`core_signer_handle`): reciprocal request - + registered DashpayReceivingFunds **and** DashpayExternalAccount (the ECDH + - accountReference path). Contact established cross-device (sim A shows Eve as - contact #3). - - ⏳ NOT exercised on-chain (covered elsewhere): (a) **wrong-seed rejected loud** - via `verify_seed_binds` at unlock — gated behind the `loadFromPersistor` - restorable path; cleanly forced only by a destructive wipe+reimport. Covered by - the high-fidelity unit test (real `key_wallet` wallet, same BIP44-0 path, - accept/reject) — and the live Core/Platform signing above proves the resolver - derives correct keys. (b) **cross-device contactInfo decrypt** (same owner on a - 2nd device) — publish validated; decrypt-drain unit-tested. - - **Unrelated finding (not a seed defect):** the DashPay contact-profile chunk fetch - fails with a DAPI error `missing order by for range error: query must have an - orderBy field for each range element` ("Failed to fetch a contact-profile chunk; - will retry next sweep"). Contact establishment still succeeds; contact *profiles* - may not render. Track + fix separately. - -**Out of Q2 scope** (tracked in the backlog (dashpay/platform#4020)): §6b queue restore (upstream -`ClientStartState::wallets` — note the security review's caveat that until restore -works, a contact discovered-then-app-killed-before-unlock never finishes setup); -the §4.8 present-but-zero-keys import caveat; QR auto-accept wiring. - -## 2. Inventory of seed-dependent paths (revised; exhaustive over **DashPay-contact** paths) - -Verified by grepping every `derive_extended_p*_key` / `build_signed(wallet` / -`.has_seed()` reader, and by tracing reachability from the background sweep. -NOTE (plan review): this table enumerates the DashPay-contact seed paths (#1–#7). -The **identity-discovery** resident derive `derive_identity_auth_keypair` -(`identity_handle.rs:191`) is a separate resident-key-TYPE path — it legitimately -stays for `WalletType::Mnemonic`/`Seed` wallets and is NOT a Q2 deletion target -(external-signable wallets already route discovery through the resolver). See the -Q2 banner step 2. - -`bg?` = reachable from the **signerless** recurring sweep -(`DashPaySyncManager` → `dashpay_sync` → `build_contact_accounts` / -`sync_contact_infos`). The sweep FFI takes **no signer handle** and runs with -no user present — so any `bg?`+secret op is a deferral problem (§4.6). - -| # | Call site | Capability | bg? | Phase | -|---|---|---|---|---| -| 1 | `send_payment` (`payments.rs`, build site) | ECDSA sign at path | no | **1 — DONE** | -| 2 | `derive_contact_xpub` (`dip14.rs:98`), caller = send-contact-request flow (signer present) | xpub at hardened path | no | **2** (bundled with #4 — same function) | -| 2b | `register_contact_account` → `wallet.derive_extended_public_key` (`contacts.rs:186`) | xpub at hardened path | **yes** | **2** (steady-state no-op — see note) | -| 3 | contact-request / profile / contactInfo **doc signing** | `Signer` | — | already done | -| 4 | contact-request xpub **encrypt** — `derive_encryption_private_key` (`identity_handle.rs:476`) → `EcdhProvider::SdkSide` (`sdk_writer.rs:240`) | ECDH | no | **2** | -| 5 | contact xpub **decrypt** — `register_external_contact_account` (`contacts.rs:472/510/514`) | ECDH | **yes** | **2 — DEFERRED via queue** | -| 6 | `accountReference` (`contact_requests.rs:204`; `dip14.rs:262`) | HMAC keyed by the **same** ECDH key | partial | **2** | -| 7 | contactInfo AES keys — `derive_contact_info_keys` (`contact_info.rs:80`) via sync (read) + publish (write) | raw hardened-child bytes as AES-256 key | **yes (read)** | **2 — DEFERRED via queue** | - -Reclassification vs v2 (from the review): - -- **Sites 2 and 2b moved Phase 1 → Phase 2.** Both live in functions that - *also* perform Phase-2 ECDH (#4 in `send_contact_request_with_external_signer`; - #5 in the `register_external` path that the sweep drives). Converting their - xpub piecemeal in Phase 1 would double-touch the same functions. Bundle each - xpub conversion with the ECDH conversion of its host function (one - wallet-HD closure threading per function). Phase 1 stays exactly the - already-shipped, green slice (#1 + the `extended_public_key` foundation + - dead-API deletion). -- **2b is a steady-state no-op.** `register_contact_account` has an early-exit - (`contacts.rs:153–174`): once the receiving account exists it returns before - the derive at `:186`. The account **is persisted** — - `AccountRegistrationEntry.account_xpub: ExtendedPubKey` (`changeset.rs:967`) - bincode round-trips (`persistence.rs:2387`/`2869`) and restores via - `Account::from_xpub` into a watch-only `new_external_signable` wallet - (`persistence.rs:2874/2889`), with the address pool + `used` flags - (`AccountAddressPoolEntry`). Gap-limit refill is pure public `ckd_pub` - (`KeySource::Public`, key-wallet `managed_account_trait.rs:295`). So the - derive at `:186` fires **only** on a contact's first-ever registration in a - session where it was never persisted — the deferral edge case (§4.6). -- **Only #5 (ECDH decrypt) and #7-read (contactInfo decrypt) are genuine - background blockers.** Everything else the sweep does (request ingest, - profile sync, address matching, gap-limit refill, payment reconcile) is - pure public derivation or no derivation at all. - -Notes (unchanged from v2): -- **#6 is not a separate key** — `calculate_account_reference` is HMAC-keyed by - the same ECDH scalar as #4/#5; the ECDH handling covers it. -- **auto-accept (`auto_accept.rs:80`) is KEPT** — real but unwired DIP-15 - feature; converts cleanly to a sign path when wired. Tracked in the backlog (dashpay/platform#4020). -- **Dead read APIs** `contact_xpub` / `contact_payment_addresses` had zero - callers → **DELETED in Phase 1**. - -`attach_wallet_seed` consumers to remove (Phase 2, §4.9): FFI -`platform_wallet_manager_attach_wallet_seed_from_mnemonic` (`manager.rs:430`); -Swift `unlockWalletFromKeychain` (`PlatformWalletManager.swift:468`); test -helpers (`payments.rs`). - -## 3. Capabilities the Keychain signer must expose - -Two distinct, correctly-separate signer notions exist and stay separate -across the FFI seam (§4.4): - -- **Doc-signer** — `dpp::identity::signer::Signer` - (state-transition signing). Impl = `VTableSigner`; FFI handle = - `SignerHandle`/`VTableSigner` (seed never enters Rust). Already wired. -- **Wallet-HD signer** — `key_wallet::signer::Signer` (ECDSA-at-path, - `public_key`, `extended_public_key`). Impl = `MnemonicResolverCoreSigner`; - FFI handle = `MnemonicResolverHandle` (mnemonic transiently enters Rust; - all crypto runs in FFI-crate Rust and wipes). - -Wallet-HD capabilities: - -1. **ECDSA sign at path** — EXISTS (`sign_ecdsa`). -2. **public_key at path** — EXISTS. -3. **extended_public_key at path** — DONE (key-wallet method + host primitive). -4. **ECDH** `(path, peer_pubkey) -> shared_secret` — NEW host primitive (§4.5). -5. **contactInfo seal/open** — NEW host primitive (§4.5). - -Capabilities 4–5 are added as **inherent methods on `MnemonicResolverCoreSigner`** -(in `rs-sdk-ffi`, where it already lives) and consumed by platform-wallet via -**closures** (the existing `EcdhProvider::ClientSide` seam) — no new trait, no -new crate (§4.4). - -## 4. Design - -### Phase 1 — sign + xpub (low-risk, SHIPPED green) - -#### 4.1 key-wallet change — LANDED - -`key_wallet::signer::Signer::extended_public_key` added as a **provided -default that errors** (not a breaking required method); `InMemorySigner` test -impls override it; pinned rev bumped. `TransactionSigner`/`build_signed` -unchanged. - -#### 4.2 host primitive: extended_public_key (FFI + Swift) — DONE + 1 hardening - -`MnemonicResolverCoreSigner::extended_public_key` reuses the shared -`resolve_derived_xprv` helper, computes `ExtendedPubKey::from_priv`, and wipes -both scalars. Interop-guard test pins signer-xpub == `Wallet::derive_extended_public_key`. - -**Phase-1 hardening (from the security audit) — TODO before merge:** wipe the -`master` scalar on the **error/unwind path** of `resolve_derived_xprv`. Today -the explicit `non_secure_erase` runs only in the `Ok` arms of `derive_priv` -and `extended_public_key`; if `master.derive_priv(path)` returns `Err`, or a -panic unwinds between materialization and the wipe, the `master` scalar leaks -(no `Drop`/`Zeroize`). Same gap in `sign_with_mnemonic_resolver.rs`. Preferred -fix: a small RAII wipe-guard around the two `ExtendedPrivKey`s (so all exit -paths wipe), rather than more hand-placed calls — there will be **five** such -sites once §4.5 lands. - -**Path provenance (security requirement).** Paths are built in Rust -(`AccountType::…derivation_path()`, `identity_auth_derivation_path_for_type`, -the `dip14`/`contact_info` path builders) and passed **opaquely** through the -FFI; Swift never assembles a path. - -#### 4.3 call-site conversions (Phase 1) — DONE - -- `send_payment` takes `` and signs via - `build_signed(signer, …)`; FFI `platform_wallet_send_dashpay_payment` takes - a `MnemonicResolverHandle`; Swift threads the resolver under - `withExtendedLifetime`. -- Dead `contact_xpub` / `contact_payment_addresses` deleted. -- Sites 2 and 2b are **not** converted here — moved to Phase 2 (§2). - -### Phase 2 — raw-secret paths + seedless sweep + delete the workaround - -#### 4.4 Signer & host-primitive model (no duplicate logic) - -**Decision: two FFI handles; raw-secret ops as inherent methods on the -existing wallet signer, consumed via closures — NO new trait, NO new crate.** - -- Keep `VTableSigner` (doc-signer) and `MnemonicResolverHandle` (wallet-HD) as - **two** FFI handles. Merging them would either regress the doc-signer (seed - currently never enters Rust) or force DIP-15 crypto into Swift — both - rejected. -- `MnemonicResolverCoreSigner` (in `rs-sdk-ffi`) already **is** the wallet-HD - binding (impls `key_wallet::signer::Signer`) and is constructed only by the - `rs-platform-wallet-ffi` glue crate. `rs-sdk-ffi` and `platform-wallet` do not - depend on each other, so a shared `WalletKeyProvider` *trait* would need a new - crate or a layering inversion (the external `key-wallet` is ruled out — keep - the cross-repo PR to one method, and ECDH must not become a `Signer` method). - Avoid all of that: add the raw-secret capabilities as **inherent methods** on - `MnemonicResolverCoreSigner` (it gains a `platform-encryption` dep — a leaf - crypto crate, no cycle), and let platform-wallet consume them via **closures** - — the `EcdhProvider::ClientSide { get_shared_secret }` seam it already uses, - plus a closure param on the decrypt/drain path. The glue crate wires the - closures from the signer's methods (it already owns the signer's construction - + lifetime). *(An earlier draft proposed a `WalletKeyProvider: Signer` - extension trait; dropped — no shared home given the crate graph, and the - closure seam already exists.)* - -Inherent methods on `MnemonicResolverCoreSigner` (sync — derivation is -CPU-bound + the resolver call is synchronous; the consuming `ClientSide` closure -wraps each in a future at the FFI seam): - -```text -ecdh_shared_secret(path, peer_pubkey) -> Zeroizing<[u8;32]> // #4/#5 DONE -ecdh_shared_secret_and_account_reference(path, peer, compact_xpub, account_index, version) - -> (Zeroizing<[u8;32]>, u32) // #6 -unmask_account_reference(path, prior_reference, compact_xpub) -> (u32, u32) // #6 -contact_info_seal(root_path, derivation_index, contact_id, plaintext, iv) -> ContactInfoSealed // #7 -contact_info_open(root_path, derivation_index, enc_to_user_id, blob) -> ContactInfoOpened // #7 -``` - -- Document-ops conversion: send/accept contact-request already thread a - `doc_signer` for the state transition; for the xpub/ECDH they additionally - receive the wallet-HD closure(s) the glue crate builds from the signer. - `send_payment` keeps only its `key_wallet::Signer`. Swift passes the two - handles it already holds — **no new Swift class, no new Swift crypto**. -- **Delete the dead `dash_sdk_dashpay_*` ClientSide FFI surface** - (`rs-sdk-ffi/src/dashpay/contact_request.rs`: the two entry points, - params/results, `DashSDKEcdhMode`, the four `*_with_{shared_secret,private_key}` - helpers) and regenerate the cbindgen header. Zero non-Rust callers; it is a - divergence-prone parallel orchestration of the same `rs-sdk` core, and its - `SdkSide` raw-scalar ABI contradicts the new posture. The `rs-sdk` - contact-request core + `EcdhProvider` stay (single source). - -**No-duplicate-logic trace:** every host method body is "derive scalar at a -Rust-built path (the shared `resolve_derived_xprv`, scrubbed by the `WipingXprv` -guard on every exit path) → call the existing `platform_encryption` / `dip14` -fn → return the result." Zero new crypto. Single sources stay: DIP-15 ECDH/AES → -`platform-encryption`; accountReference HMAC + masking → `dip14`; contact-request -orchestration → `rs-sdk platform::dashpay::contact_request`; contactInfo wire -codec → `crypto/contact_info.rs` (plaintext-only, runs outside the primitive). - -#### 4.5 raw-secret host primitives (option iii) + EcdhProvider collapse - -For #4–#7 the host primitive derives the key **and runs the crypto in -FFI-crate Rust**, returning only the result; the raw scalar never reaches -`rs-platform-wallet` or Swift. - -- **ECDH (#4/#5):** switch `sdk_writer.rs:240` from - `EcdhProvider::SdkSide { get_private_key }` to - `ClientSide { get_shared_secret }` backed by a closure calling - `MnemonicResolverCoreSigner::ecdh_shared_secret` (DONE; parity-pinned). - For all DashPay paths the model **collapses to `ClientSide` only**; delete - `derive_encryption_private_key` (`identity_handle.rs:476`) and - `SendContactRequestParams.ecdh_private_key` — the two places that - materialize the raw scalar in `rs-platform-wallet`. Shared secret MUST be - byte-identical to `platform_encryption::derive_shared_key_ecdh` - (`SHA256((0x02|y_parity)‖x)`); peer pubkey validated on-curve before ECDH. -- **accountReference (#6):** folded into `ecdh_shared_secret_and_account_reference` - / `unmask_account_reference` so the encryption scalar is used for both ECDH - and the `dip14` HMAC in one derivation and never returns raw. -- **contactInfo (#7):** `contact_info_seal` / `contact_info_open` derive the - two hardened-child AES keys and run encrypt/decrypt via `platform_encryption`, - returning only ciphertext/plaintext. The DIP-15 wire codec stays in - `crypto/contact_info.rs` (no key material). - -**Interop parity (required):** host-path accountReference, contactInfo blob, -and ECDH secret MUST equal the in-process results for the same seed+path — -each pinned by a test (DIP-15 interop vs dashj/dash-shared-core). - -#### 4.6 Seedless background-sync & the deferred-crypto queue (NEW — the core) - -The recurring sweep has no signer and no user present (verified: -`DashPaySyncManager` holds no signer; FFI `platform_wallet_sync_contact_requests` -/ `…_dashpay_sync_start` / `…_sync_now` take none). Design rule: every sweep -op is **public-derivable** or **deferred** — never resident-seed. - -**Persisted pending-crypto queue.** Add `pending_contact_crypto: -Vec` to `PlatformWalletChangeSet`, keyed per -`(owner_identity_id, contact_id)` with an op discriminant: - -``` -PendingContactCrypto { owner_identity_id, contact_id, - op: RegisterReceiving // our friendship xpub (2b, first-time only) - | RegisterExternal { encrypted_public_key, our_decryption_key_index, - contact_encryption_key_index } // #5 ECDH decrypt - | ContactInfoDecrypt, // #7 (idempotent re-fetch+decrypt) - enqueued_at_ms } -``` - -- Stores **only ciphertext + public key indices** (safe to persist). Rides the - existing `persister.store(...)` changeset pipeline (no side channel); - restored through `build_wallet_start_state`; a missing/old column restores as - an empty queue (skip-and-continue convention). -- **Persisted, not in-memory**, because restore-from-Keychain is exactly when - it's needed and the app may be killed between background discovery and the - next foreground unlock. - -**Enqueue (background, seedless).** In `build_contact_accounts` and -`sync_contact_infos`, when key material is unavailable (the `Unavailable` -classification, §4.7), **enqueue** instead of the current silent skip-and-log -/ retry-forever / channel-kill. Idempotent per `(owner, contact, op-kind)`. - -**Drain (foreground, signer present)** — no new signer plumbing into the -background manager: - -1. **On-unlock (primary):** a **new FFI** `platform_wallet_drain_pending_contact_crypto(wallet, core_signer)` - wired into the same Swift code path that previously called - `unlockWalletFromKeychain` — so deleting the re-attach and adding the drain - are one change. It runs each entry through the §4.5 host primitives, then - the public registration, and clears the entry. -2. **Opportunistic:** `send_payment` / `send_contact_request_with_external_signer` - / `accept_…` / `set_contact_info_with_external_signer` each drain queue - entries **for the identity they operate on** before their own work — so the - first user action on a contact resolves its deferred crypto (e.g. tapping - "Pay" on an inbound-only contact builds its `DashpayExternalAccount`). - -Drain is idempotent (each op re-checks its early-exit guard). While queued, the -sweep still does all PUBLIC work for the contact (ingest, profile, address -match, reconcile); the contact is visible but "needs unlock to finish setup." - -#### 4.7 Error classification: Transient / Unavailable / Permanent (must-fix) - -The live bug behind "is deferral safe": `build_contact_accounts` today maps an -ECDH/derive failure to `Permanent` → `mark_contact_channel_broken` -(irreversible, `warn!`-only). A **locked Keychain is transient** but would -permanently disable payments to a contact. Fix before any Phase-2 coding: - -- Introduce a **third** arm, `Unavailable` (signer/key material absent), in - `RegisterExternalError` (and the contactInfo path), **distinct** from - `Transient` (retry soon) and `Permanent` (malformed data → mark broken). -- `Unavailable` → **enqueue (§4.6) and pause this contact's build; never kill, - never churn-retry every 15s.** Only genuinely malformed inputs (bad - ciphertext, off-curve pubkey) are `Permanent`. -- **Fix the `is_seedless` gate** (`contact_requests.rs:904–921`): it currently - keys on `identity_index.is_none()`, which a seedless-but-indexed identity - passes — falling through to the channel-kill. Gate on "can I derive **right - now**?" (key material available), not "is this a wallet-owned identity?". -- Add a **needs-rebuild / needs-unlock marker** surfaced to the UI for - deferred contacts. - -#### 4.8 wrong-seed safety check (replaces the deleted dual gate) - -`attach_wallet_seed`'s dual id/xpub gate also verified the Keychain mnemonic -binds to the loaded wallet. Replace it with a **one-time xpub self-check** at -signer construction / first use: derive BIP44 account-0 xpub from the resolved -mnemonic and compare to the wallet's persisted account-0 xpub; mismatch fails -loud. **Caveat (security audit):** this catches a *wrong* seed but **not** a -*present-but-zero-keys* import (the open imported-identity bug, §7 -prerequisite). - -#### 4.9 delete the workaround — ORDERING CONSTRAINT - -Remove `attach_wallet_seed`, the FFI export, `unlockWalletFromKeychain`'s -re-attach (replaced by the §4.6 drain), the dual gate + `mem::swap`; rework -the test helpers to inject a test `Signer` / pre-seed the queue. Also delete -or make-throwing the legacy `KeychainSigner.sign(identityPublicKey:data:) --> Data?` swallow (returns reasonless `nil` on any failure). - -**Do NOT execute this deletion until the sweep is seedless-safe** (§4.6 queue -+ §4.7 classification landed and tested). Until then the resident seed is what -keeps the signerless sweep working; removing it first turns every background -tick on an unbuilt contact into an irreversible channel-kill. - -## 5. Failure modes - -- **Signer unavailable mid-sweep (ECDH/xpub build):** classified `Unavailable` - → enqueued + paused, **not** channel-killed, **not** retried every 15s - (§4.7). Resolves on next drain. -- **Keychain locked while the tokio sweep ticks:** the loop has no - scenePhase/BG gating; it MUST hit the `Unavailable`+enqueue path, never the - kill path. -- **Pending queue never drains:** mitigated by the on-unlock drain wired to the - old re-attach trigger + opportunistic drain on any signer-present action + - a UI "needs unlock" marker. Pinned by an on-device test. -- **Poison entry (permanently malformed ciphertext):** `Permanent` → mark - broken + clear entry (no requeue). Transient → keep for next drain. -- **Partial registration** (persist-ok / in-memory-insert-fail): unchanged - (store-before-insert; relaunch rebuilds) — but the rebuild must classify a - locked Keychain as `Unavailable`, not escalate. -- **Restore-from-Keychain / app-reinstall → zero signing keys:** the - imported-identity bug — **RESOLVED** by carry-scalar (the materialization path no - longer re-derives from a not-yet-stored mnemonic). Phase 2 only confirms imported - wallets reach the resolver for xpub/ECDH (mnemonic stored by `createWallet`). -- **Wrong/mis-mapped mnemonic:** §4.8 xpub self-check, fails loud. -- **Read-path:** converted readers propagate signer errors; never return - empty/zero/stale addresses. - -## 6. Test plan - -- **key-wallet:** `extended_public_key` on `InMemorySigner` matches - `derive_extended_public_key` (DONE). -- **platform-wallet:** test `Signer` replaces `attach_wallet_seed`; - signer-based tests for `send_payment` (DONE: interop-guard) + contact-request - create/accept (ECDH), contactInfo round-trip; **interop parity** tests - (accountReference, contactInfo, ECDH byte-equal to in-process). -- **Seedless sweep:** watch-only wallet + persisted xpubs → sweep does all - PUBLIC ops with no signer; `register_contact_account` early-exit no-op once - persisted. -- **Deferral queue:** background-discover inbound contact → `Unavailable` → - enqueue (not kill); drain on unlock → contact payable. A `Permanent` error - clears the entry AND sets `payment_channel_broken`. A locked-Keychain - (transient) does **not** mark broken. -- **Per-primitive no-residue:** each inherent host-primitive method wipes scalars - on Ok **and error/unwind** paths. -- **FFI:** input-validation (null/oversize/bad-path) incl. contactInfo depth-6 - paths (hardened 65536/65537). -- **Acceptance grep:** `git grep attach_wallet_seed` empty; no surviving - `derive_extended_private_key` / `build_signed(wallet` on DashPay paths. -- **On-device:** clean wipe → import → discover → send/accept contact request, - send payment, publish profile + contactInfo, **background-discover an - inbound contact then unlock → it becomes payable** — all with **no** - re-attach. - -## 7. Rollout order (revised) - -1. **Phase 1 (SHIPPED, green):** key-wallet method → host `extended_public_key` - primitive → `send_payment` conversion → delete dead read APIs. **Remaining - before merge:** the §4.2 error-path wipe hardening + iOS `build_ios.sh` - verification. -2. **Phase 2 prerequisites (design + fix BEFORE feature code):** - - §4.7 three-state error classification + `is_seedless` gate fix. - - §4.6 persisted pending-crypto queue + drain FFI. - - ~~Resolve the imported-identity zero-signing-keys bug~~ **RESOLVED** by the - carry-scalar change (commit `c567981c46`; on-device 23/23 signable, - regression tests green). No longer a blocker. Phase 2 need only confirm an - imported wallet reaches the resolver for xpub/ECDH (its mnemonic is stored in - the Keychain by `createWallet`, so the resolver-backed signer works for it). -3. **Phase 2 feature code:** inherent host primitives on - `MnemonicResolverCoreSigner` (ECDH + accountReference + contactInfo) → - `EcdhProvider` collapse to `ClientSide` → - convert #2/#2b/#4–#7 (each xpub bundled with its function's ECDH) → delete - the dead `dash_sdk_dashpay_*` surface → §4.8 self-check. -4. **Only then §4.9:** delete `attach_wallet_seed` + re-attach + legacy - `KeychainSigner.sign(...)->Data?`. -5. Build + clippy + tests + on-device acceptance after each phase. - -Cross-repo: the key-wallet edit (already landed) needed Claude Code run from -`/Users/ivanshumkov/Projects/dashpay/` (sibling-repo writes). FFI/Swift work -goes through the **swift-rust-ffi-engineer** agent. - -## 8. Alternatives rejected - -- **In-memory seed (dashj / dash-shared-core).** Reference clients hold the - decrypted seed in-session — no signer-based DashPay to copy. Rejected: - abandons the #3639 posture. -- **Phase-1-only (xpub/sign):** does not delete `attach_wallet_seed`. Adopted - *as Phase 1*, not the end state. -- **Keep the workaround:** rejected by product decision. -- **Unified single signer handle (doc + wallet + ECDH):** rejected — regresses - the doc-signer (seed never in Rust today) or pushes DIP-15 crypto into Swift. - Add the wallet-side raw-secret ops as inherent methods on the existing - signer, consumed via closures, instead (§4.4). -- **§4.5 option (i) (return raw scalar):** rejected for option (iii) — exposes - the ECDH key raw, defeating the hashing; the carry-scalar precedent - (write-once Rust→Swift) does not sanction the read-many reverse flow. -- **Skip-and-log deferral (current code):** rejected — silently strands - contacts and (worse) the `Permanent` path irreversibly kills channels. - Replaced by the §4.6 persisted queue + §4.7 classification. - -## 9. Security must-fixes from the multi-agent review (priority order) - -1. **[CRITICAL]** Three-state classification (`Unavailable` ≠ `Permanent`); - never auto-`mark_contact_channel_broken` on unavailable key material (§4.7). -2. **[CRITICAL]** Give the sweep a seedless-safe path: enqueue+defer, never - derive-or-die; do not delete `attach_wallet_seed` until this lands (§4.6, - §4.9 ordering). -3. **[CRITICAL]** Fix the `is_seedless` gate predicate — key-availability, not - `identity_index.is_none()` (§4.7). -4. **[RESOLVED]** Imported-identity zero-signing-keys bug — fixed by carry-scalar - (commit `c567981c46`), on-device-verified, regression tests green. No longer a - Phase-2 blocker; only confirm imported wallets reach the resolver for xpub/ECDH. - (Note: §4.8's xpub self-check still does not cover a present-but-zero-keys import, - but the carry-scalar fix means imports now materialize keys, so this is moot.) -5. **[HIGH]** Tighten §1 honest-scope wording (done) + fix the - `resolve_derived_xprv` error-/unwind-path scalar leak; prefer one RAII - wipe-guard over five hand-placed `non_secure_erase` calls (§4.2). -6. **[MEDIUM]** Delete / make-throwing the legacy `KeychainSigner.sign(...)->Data?` - nil-swallow (§4.9). -7. **[MEDIUM]** UI marker for contacts pending an unlock-drain (§4.6/§4.7). - -## 10. Resolved review questions - -- **key-wallet method:** provided-default-that-errors — §4.1. -- **raw-secret:** option (iii) via inherent host primitives on the wallet - signer, consumed by closures — §4.4/§4.5. -- **signer surface:** two FFI handles; raw-secret ops as inherent methods + - `EcdhProvider::ClientSide` closures (no new trait/crate) — §4.4. -- **dead `dash_sdk_dashpay_*` surface:** delete — §4.4. -- **read-API ripple:** dead → deleted — §2. -- **dual-gate deletion:** safe for grafting; wrong-seed detection preserved via - the §4.8 self-check (but not zero-keys — §7). -- **ECDH placement:** FFI-layer host primitive, not a key-wallet trait method — - §3/§4.5. -- **"defer site 2b":** safe **only** with §4.6 queue + §4.7 classification + - §4.9 ordering. Without them it is silent, irreversible channel corruption. -- **pre-check:** Swift uses `platform_wallet_send_contact_request_with_signer`; - the rs-sdk-ffi ClientSide surface is the reference template for the ECDH - switch and is deleted afterward. diff --git a/docs/dashpay/SPEC.md b/docs/dashpay/SPEC.md deleted file mode 100644 index 6306eec5f1f..00000000000 --- a/docs/dashpay/SPEC.md +++ /dev/null @@ -1,1362 +0,0 @@ -# DashPay — Implementation Spec & Gap Analysis - -> **Purpose.** A single working spec for getting the **full DashPay flow** — sync, -> create/update profile, send contact request, approve/reject contact requests, -> send money to a contact — *done and tested* in the **platform wallet** -> (`rs-platform-wallet` + FFI) and surfaced as a **nice UI** in the -> **SwiftExampleApp**. -> -> **Status (2026-06-10).** DashPay is **already ~80% implemented end-to-end.** This -> document maps the protocol, inventories what exists, isolates the gaps & bugs, -> and lays out the remaining work + test plan. It is *not* a greenfield design — -> it is a finish-and-polish plan. -> -> **Status update (2026-06-18) — the finish-and-polish work is essentially done -> on `feat/dashpay-m1-sync-correctness` (PR #3841).** Resolution of the Part-0 gap -> table: **G1, G2, G12, G13, G14, G15** (the P0 sync/wire/key-purpose blockers) and -> **G3, G6, G7, G8, G9, G10** — all **DONE** (M1–M4). **G5** reworked and shipped as -> a per-sender, reversible, **local-only Ignore** (Spec 2) across every layer incl. -> the SQLite persister; cross-device sync deferred to a future encrypted `profile` -> field (contract track — the `contactInfo` route was rejected for the R1 leak). -> **G11**: the `network/` layer now has unit coverage; the live cross-client e2e -> ride PR #3549 and stay blocked on devnet funding. **G4** (watch-only ECDH) is -> **deferred** with an amended design (needs xpub hooks, not just an ECDH hook). -> Three follow-on specs were written and **implemented** this pass: -> **`SYNC_CORRECTNESS_SPEC.md`** (Spec 0 — paginated/high-water sync + contact-profile -> cache + durable persistence), **`CONTACTINFO_FORMAT_SPEC.md`** (Spec 1 — privateData -> CBOR→DIP-15 varint), and Spec 2 (Ignore). Also resolved: `accountReference` -> byte-order (**keep ours** — recipient-ignored one-time pad, no interop break) and -> the friendship-path `account'` hardcode (fixed upstream in **rust-dashcore#813**, -> pulled in via the dashcore bump **PR #3936**). Remaining is all blocked on external -> resources (devnet funding for e2e/UAT; contract governance for cross-device ignore -> + DoS filter; an upstream rust-dashcore change for multi-account). See -> the DashPay backlog issue [#4020](https://github.com/dashpay/platform/issues/4020) for the authoritative item-by-item status. -> -> **How to read.** Part 0 is the TL;DR. Parts 1–2 are reference (protocol + -> architecture). Part 3 is the current-state inventory. Part 4 is the prioritized -> gap/bug list. Part 5 is the work plan. Part 6 is the Swift UI design. Part 7 is -> the test plan. The durable evidence base ships alongside this spec: -> [`INTEROP_DESK_CHECK.md`](./INTEROP_DESK_CHECK.md) (cross-client wire-format -> verdicts + testnet census) and [`CONTACTINFO_FORMAT_SPEC.md`](./CONTACTINFO_FORMAT_SPEC.md) -> (Appendix A). The transient working-research files that once backed the -> remaining citations were trimmed from the tree; they remain in this branch's -> git history (`docs/dashpay/research/`, up to the trim commit). - ---- - -## Part 0 — Executive summary - -### What works today (end-to-end, real broadcast) - -- **Profile**: create / update / fetch / sync — `rs-platform-wallet` - (`network/profile.rs`), FFI, and Swift `DashPayProfileEditorView` are all wired - and broadcast real document state transitions. -- **Send contact request**: builds the `contactRequest` doc, ECDH + AES-256-CBC - encrypts the receiving xpub (via `dash-sdk` → `platform-encryption`), signs, - broadcasts. Wrapped in Swift (`AddFriendView`). ⚠ **Correction (2026-06-10): - "works" was overstated — the G2 entropy bug meant every broadcast through this - path was rejected by consensus until the M1 task-4 fix. The code path existed; - it did not function. (Exactly what G11's zero-network-tests predicted.)** -- **Accept contact request**: sends the reciprocal request, decrypts the - contact's xpub, registers a watch-only sending account. Wired in Swift - (`ContactRequestRow` Accept). -- **Send money to a contact**: derives the next contact address, builds + signs + - broadcasts an L1 tx, records the payment. Wired in Swift - (`SendDashPayPaymentSheet`). -- **DIP-14 / DIP-15 derivation**: 256-bit non-hardened child derivation, the - `m/9'/5'/15'/0'//` friendship path, the two account - types (`DashpayReceivingFunds`, `DashpayExternalAccount`), gap limit 20 — all - implemented and test-vector-pinned in `rust-dashcore/key-wallet`. -- **Persistence**: contacts / profiles / payments round-trip through the - changeset → SQLite pipeline. SwiftData mirror models exist. -- **Swift FFI coverage**: all ~14 DashPay/DPNS FFI functions are already wrapped - on `ManagedPlatformWallet`. - -### The gaps that block a *complete, correct* flow (detail in Part 4) - -| # | Gap | Severity | Layer | -|---|-----|----------|-------| -| G1 | **Sync never builds sending accounts** — a contact who accepts you *while you're offline* has no spendable account after sync; `send_payment` fails until `register_external_contact_account` is manually called | **P0** | `rs-platform-wallet` | -| G2 | **`send_contact_request` entropy mismatch** — document-ID entropy diverges from the broadcast entropy (`rs-sdk` admits the "simplification"); severity needs verification against `PutDocument` | **P0** | `rs-sdk` | -| G3 | **`accountReference` hardcoded to 0** — DIP-15 masking unused; the unique index `(ownerId,toUserId,accountReference)` makes key rotation / re-send impossible | **P1** | `rs-platform-wallet` | -| G4 | **Watch-only wallets can't send/accept** — ECDH is derived from the in-process seed; only `EcdhProvider::SdkSide` is used, the `ClientSide` push-across-FFI path is unbuilt | **P1** | wallet + FFI | -| G5 | **Reject is local-only** — no tombstone at all (recurring sync would resurrect rejects — stage-1 fix in **M1**) and no `contactInfo` `displayHidden` doc (cross-device — stage 2 in **M3**) | **P1** | wallet + SDK | -| G6 | **Wrong fallback contract ID** — `rs-sdk` `#[cfg(not(feature="dashpay-contract"))]` path hardcodes the **DPNS** id (dead code in default builds, latent bug) | **P2** | `rs-sdk` | -| G7 | **Dead code**: `calculate_account_reference`, `validate_contact_request`, auto-accept proof gen/verify — implemented + tested but never called by live paths | **P2** | `rs-platform-wallet` | -| G8 | **Local sent-request placeholder** — stores `vec![0u8;96]` for `encrypted_public_key` instead of the real ciphertext | **P2** | `rs-platform-wallet` | -| G9 | **No contract cache** — the bundled system contract is re-loaded on every op | **P2** | `rs-platform-wallet` | -| G10 | **No `contactInfo` support** — alias/note/hidden private metadata never syncs across devices | **P2** | wallet + SDK | -| G11 | **Network layer is untested.** Primitives/state/persistence are well covered, but the *whole* `network/` layer (send/sync/accept/pay/profile-broadcast) has **0 tests**; no full send→sync→accept→pay integration test; Swift has **0** DashPay tests | **P0** | both | -| G12 | **DashPay sync is not in the recurring sync loop.** The background `IdentitySyncManager` syncs **token balances only**; `dashpay_sync()` (contact requests + profiles) runs **only on-demand via FFI** — it must be folded into the recurring loop alongside the other syncs | **P0** | `rs-platform-wallet` | -| G13 | **Sync never reconciles own sent requests** — after restore-from-seed or on a second device an established contact renders as a mere incoming request; Accept re-broadcasts a duplicate reciprocal and is **rejected forever** by the unique index | **P1** | `rs-platform-wallet` | -| G14 | **Wrong encrypted-xpub wire format** (desk-check 2026-06-10, `INTEROP_DESK_CHECK.md`): we encrypt the 107-byte DIP-14 `ExtendedPubKey::encode()` instead of DIP-15's **69-byte compact** (`fingerprint‖chaincode‖pubkey`) used by iOS+Android → our send fails its own 96-byte check; our receive can't parse mobile payloads | **P0** | `platform-encryption` + `rs-sdk` + wallet | -| G15 | **Key-purpose convention mismatch**: mobile clients use key 0 (AUTHENTICATION) for both key indices; our send/validation require ENCRYPTION/DECRYPTION-purpose keys → cross-client requests blocked both directions. Verify against a real testnet mobile contactRequest, then align | **P1** | wallet + `rs-sdk` | - -### UI verdict - -The Swift DashPay UI exists but is **buried** (Identities → IdentityDetail → -`Section("DashPay")`) and **utilitarian**. The plan (Part 6) **promotes it to a -first-class `DashPay` tab**, renders the missing outgoing-requests section, moves -lists onto reactive `@Query`, and polishes styling (AsyncImage avatars, empty -states, toasts). No new happy-path FFI is required. - -### Recommended sequencing - -**Milestone 1 (correctness)**: G11-seam, G12, G1+G13 (+G5 tombstone), G2, interop -desk-check, G11-Rust. → the offline-accept→pay path works, is integration-tested, -and the background sync is wired. -**Milestone 2 (UI)**: first-class DashPay tab + polish + Swift tests (Part 6/7). -**Milestone 3 (spec-completeness)**: G3, G5, G10 (accountReference + contactInfo -for rotation/hide/alias sync). -**Milestone 4 (hardening)**: G4 (watch-only ECDH), G6–G9 cleanup. -**Milestone 5 (invitations)**: asset-lock voucher + claim + auto-accept wiring -(new scope 2026-06-10; design pass first). - ---- - -## Part 1 — What DashPay is, and the layered stack - -**DashPay** (DIP-0015) is a Dash Platform application that creates *bidirectional -direct settlement payment channels* between two Dash **identities**. User-facing -model: - -- **Username** → a **DPNS** name (DIP-0012) resolving to an identity. DashPay - itself never stores usernames; it references identities by their 32-byte id. -- **Identity** (DIP-0011) → the cryptographic actor; holds keys + credit balance; - signs all state transitions. -- **Profile** → public presentation (`displayName`, `publicMessage`, avatar). -- **Contact / friend** → an identity you have exchanged `contactRequest` - documents with **in both directions**. -- **Pay a contact** → decrypt the xpub from *their* contactRequest addressed to - you, derive the next L1 address, and pay it with an ordinary Dash transaction. - DashPay is the *key-sharing / coordination* layer; value transfer is plain L1. - -### The implementation stack (bottom → top) - -``` -┌──────────────────────────────────────────────────────────────────────────┐ -│ SwiftExampleApp Views: FriendsView, IdentityDetailView (profile), │ -│ (packages/swift-sdk/ SendDashPayPaymentSheet, AddFriendView [Part 6] │ -│ SwiftExampleApp) State: PlatformWalletManager, AppState, SwiftData │ -├──────────────────────────────────────────────────────────────────────────┤ -│ swift-sdk wrappers ManagedPlatformWallet.{sync,send,accept,reject,pay, │ -│ (Sources/SwiftDashSDK) profile…}, ContactRequest, EstablishedContact, │ -│ DashPayProfile, KeychainSigner (thin, marshal-only)│ -├──────────────────────────────────────────────────────────────────────────┤ -│ rs-platform-wallet-ffi C ABI: platform_wallet_{sync_contact_requests, │ -│ send_contact_request_with_signer, accept…, reject…, │ -│ send_dashpay_payment, *_dashpay_profile_with_signer} │ -├──────────────────────────────────────────────────────────────────────────┤ -│ rs-platform-wallet IdentityWallet (network façade): contact_requests.rs,│ -│ (the brains) contacts.rs, payments.rs, profile.rs, dashpay_sync.rs│ -│ ManagedIdentity state; crypto/{dip14,validation,…} │ -├───────────────────────────────┬──────────────────────────────────────────┤ -│ rs-sdk (dash-sdk) │ platform-encryption │ -│ dashpay/contact_request.rs: │ derive_shared_key_ecdh (libsecp256k1 ECDH),│ -│ create/send_contact_request, │ encrypt/decrypt_extended_public_key │ -│ EcdhProvider, queries │ (AES-256-CBC + PKCS7), account-label crypto │ -├───────────────────────────────┴──────────────────────────────────────────┤ -│ rust-dashcore/key-wallet DIP-9 paths, DIP-14 256-bit CKD, AccountType │ -│ (HD wallet primitives) ::Dashpay{ReceivingFunds,ExternalAccount}, │ -│ managed accounts, gap limit 20, tx checking │ -├──────────────────────────────────────────────────────────────────────────┤ -│ dashpay-contract v1 schema: profile / contactRequest / │ -│ contactInfo; id Bwr4WHCP…NS1C7 │ -└──────────────────────────────────────────────────────────────────────────┘ -``` - -Key architectural facts: -- **ECDH + AES live in `platform-encryption`**, *not* in `key-wallet` - (rust-dashcore has **zero** ECDH code). The wallet calls `dash-sdk`'s - `send_contact_request`, which calls `platform-encryption` internally; the - receive/decrypt path calls `platform-encryption` directly. -- **`key-wallet` only consumes an already-decrypted friend xpub** - (`wallet_add_dashpay_external_account_with_xpub_bytes`). -- **The DashPay system contract is bundled** (`load_system_data_contract`), no - network fetch needed. -- **Swift never orchestrates** — every multi-step DashPay op is *one* - `platform-wallet` FFI call (per `swift-sdk/CLAUDE.md`). - ---- - -## Part 2 — Protocol reference (authoritative numbers) - -Condensed from the DIPs themselves (DIP-9/11/13/14/15, -cross-checked against the deployed v1 contract). **Where DIP prose and the v1 -schema disagree, the schema wins.** - -### 2.1 Friendship lifecycle - -- A `contactRequest{ $ownerId: sender, toUserId: recipient }` is **one-directional**. -- **Established contact (DIP-15: "friendship") = both directions exist** (A→B *and* - B→A). One request = "pending"; the reciprocal = "accept". -- **To pay X**, read **X's** request addressed to you (`$ownerId==X`, - `toUserId==you`), decrypt its `encryptedPublicKey`, derive addresses. -- Contact requests are **immutable & non-deletable** (`documentsMutable:false`, - `canBeDeleted:false`). Key rotation = a **new** request with a bumped - `accountReference` version. - -### 2.2 Friendship derivation path (DIP-15 + DIP-14) - -``` -m / 9' / 5' / 15' / 0' / / / index - └─────── hardened ──────┘ └── non-hardened 256-bit (DIP-14) ──┘ └ non-hardened u32 -``` - -- `9'`=feature purpose, `5'`=Dash (`1'` testnet), `15'`=DashPay, `0'`=account. -- The two 256-bit levels are the raw 32-byte identity ids (owner first). **Must** - stay non-hardened (so a watch-only xpub at `…/0'` covers all contacts) and full - 256-bit (truncating to 31 bits is a DIP-14 security violation). -- Auto-accept proof keys use a **separate** path `m/9'/5'/16'/'`. - -### 2.3 ECDH shared secret - -libsecp256k1 ECDH (**not** raw X-coord): `sharedKey = SHA256( ((y[31]&1)|2) || x )` -of the shared point `d_self · Q_other`. The participating identity keys are -selected by `senderKeyIndex` / `recipientKeyIndex` (identity public-key `id`s, -encryption/decryption purpose). Both parties derive the identical 32-byte key → -the AES-256 key. - -### 2.4 Encryption layout - -- Plaintext = **compact** xpub `parentFingerprint(4) || chainCode(32) || - pubKey(33)` = **69 bytes** (not the 78-byte BIP32 xpub). *(Implementation note — - corrected by the 2026-06-10 desk-check: our stack actually fed - `ExtendedPubKey::encode()` in, which for the DashPay path is the **107-byte** - DIP-14 form → 128-byte ciphertext → our own send path failed. See **G14**; - reference clients confirm the 69-byte compact form.)* -- `encryptedPublicKey` = `IV(16) || AES-256-CBC-PKCS7(80)` = **exactly 96 bytes**. -- `encryptedAccountLabel` = `IV(16) || ciphertext(32–64)` = **48–80 bytes**. -- `contactInfo.privateData` uses **BIP32-derived** symmetric keys (self-encrypt), - not ECDH; `encToUserId` uses AES-ECB. - -### 2.5 `accountReference` - -``` -ASK = HMAC-SHA256(senderSecretKey, extendedPublicKey) -AccountRef = (Version << 28) | (ASK[28 msb] XOR (Account & 0x0FFFFFFF)) -``` -Top 4 bits = version (rotation signal), low 28 bits = account number masked by a -PRF of the xpub. Uniqueness not required. The recipient un-masks the account and -reads the version. - -### 2.6 DashPay v1 contract document types - -Contract id **`Bwr4WHCPz5rFVAD87RqTs3izo4zpzwsEdKPWUT1NS1C7`** -(hex `a2a1…71bc`), owner all-zero. Full field/index tables in the deployed -schema, `packages/dashpay-contract/schema/v1/dashpay.schema.json`. Summary: - -- **`profile`**: `avatarUrl`(uri,≤2048), `avatarHash`(32B), `avatarFingerprint`(8B), - `publicMessage`(1–140), `displayName`(1–25). Avatar trio is `dependentRequired`. - Unique index `$ownerId`; non-unique `$ownerId+$updatedAt`. Mutable. -- **`contactRequest`**: `toUserId`(32B id), `encryptedPublicKey`(**exactly 96B**), - `senderKeyIndex`, `recipientKeyIndex`, `accountReference`, optional - `encryptedAccountLabel`(48–80B), optional `autoAcceptProof`(38–102B, unencrypted). - Required system fields incl. `$createdAtCoreBlockHeight`. Unique index - `$ownerId+toUserId+accountReference`; timelines `toUserId+$createdAt` (received) - and `$ownerId+$createdAt` (sent). Immutable. -- **`contactInfo`**: `encToUserId`(32B), `rootEncryptionKeyIndex`, - `derivationEncryptionKeyIndex`, `privateData`(48–2048B encrypted; **DIP-15 - varint** `version`/`aliasName`/`note`/`displayHidden`/`acceptedAccounts` — - contract enforces length only, see `CONTACTINFO_FORMAT_SPEC.md`). Unique index - `$ownerId+root+derivation`. Privacy rule: don't publish until ≥2 established - contacts. - ---- - -## Part 3 — Current implementation state (inventory) - -Master status matrix. **Legend:** ✅ implemented · 🟡 partial/caveated · ❌ missing. -Citations are abbreviated (file:line against this branch). - -### 3.1 rust-dashcore `key-wallet` (HD primitives) - -| Capability | Status | Evidence | -|---|---|---| -| DIP-9 DashPay root `m/9'/5'/15'` (`/1'` testnet) | ✅ | `key-wallet/src/dip9.rs:167-198` | -| DIP-14 256-bit non-hardened CKD (priv+pub) | ✅ | `bip32.rs:575-598,1533-1589,1817+`; vectors `:2521-2594` | -| `AccountType::DashpayReceivingFunds` / `DashpayExternalAccount` | ✅ | `account/account_type.rs:76-95,469-514` | -| Managed accounts, single pool, **gap limit 20** | ✅ | `managed_account_type.rs:97-118,706-749` | -| Tx checking routes contact funds | ✅ | `transaction_checking/account_checker.rs:501-518` | -| FFI: add receiving / add external(xpub) / get | ✅ | `key-wallet-ffi/src/wallet.rs:397,451`, `managed_account.rs:436,497` | -| ECDH / shared secret / xpub encryption | ❌ (by design — lives in `platform-encryption`) | repo-wide grep: none | -| Auto-create DashPay accounts at wallet init | ❌ (per-contact, after the fact) | `wallet/initialization.rs` | -| Match result carries identity ids | 🟡 (only `account_index`; reverse-lookup needed) | `account_checker.rs:144-153` | - -### 3.2 `platform-encryption` + `rs-sdk` (crypto + send flow) - -| Capability | Status | Evidence | -|---|---|---| -| `derive_shared_key_ecdh` (libsecp256k1) | ✅ | `rs-platform-encryption/src/lib.rs:24-34` | -| `encrypt/decrypt_extended_public_key` (AES-256-CBC, IV-prepend, 96B) | ✅ | `lib.rs:97-128` | -| `encrypt/decrypt_account_label` (48–80B) | ✅ | `lib.rs:139-171` | -| `Sdk::create_contact_request` / `send_contact_request` | ✅ | `rs-sdk/src/platform/dashpay/contact_request.rs:164,378` | -| `EcdhProvider::{ClientSide, SdkSide}` | ✅ (both defined; only SdkSide used upstream) | `contact_request.rs:31-54` | -| Queries: sent / received / all contact requests | ✅ | `contact_request_queries.rs:33,76` | -| SDK helpers for `profile` / `contactInfo` | ❌ (done via generic `Document`+`PutDocument`) | — | -| **Bug: send entropy ≠ doc-id entropy** | 🟡 **G2** | `contact_request.rs:431-435` (code comment admits it) | -| **Bug: fallback contract id = DPNS id** | 🟡 **G6** (dead in default build) | `dashpay/mod.rs:33` | - -### 3.3 `rs-platform-wallet` (+ FFI, storage) — the brains - -| Flow | Status | Evidence | -|---|---|---| -| Identity ↔ wallet (managed identities) | ✅ | `state/managed_identity/mod.rs:37`, `network/identity_handle.rs:256` | -| Profile fetch / sync | ✅ | `network/profile.rs:64,145` | -| Profile create / update (external signer) | ✅ | `network/profile.rs:240,395` | -| `dashpay_sync` aggregator | ✅ | `network/dashpay_sync.rs:16` | -| Sync received contact requests | 🟡 **G1** (ingest guard drops reciprocals; no xpub-decrypt / no external account built) | `network/contact_requests.rs:322,367-372` | -| Sync own sent requests (restore/multi-device reconcile) | ❌ **G13** | sync calls `fetch_received_contact_requests` only | -| Send contact request (seed-in-process) | ✅ / 🟡 **G4** | `network/contact_requests.rs:91` | -| Accept (reciprocal send + register external account) | ✅ | `network/contact_requests.rs:466` | -| Reject | 🟡 **G5** (local-only) | `network/contact_requests.rs:678` | -| Auto-establish on reciprocal match | ✅ | `state/managed_identity/contact_requests.rs` | -| Register receiving / external account | ✅ (UAT 2026-06-12: now also **persisted** — registrations were in-memory only, so accounts vanished on relaunch and restored friendship UTXOs were dropped `dropped_no_account`) | `network/contacts.rs` | -| Send money to contact | ✅ | `network/payments.rs:93` | -| Record incoming payment | ✅ (UAT 2026-06-12: the old `try_record_incoming_payment` had **zero callers** — receiver history was always empty. Replaced by live recording in the wallet-event adapter + an idempotent `reconcile_incoming_payments` step in the recurring sync) | `network/payments.rs`, `changeset/core_bridge.rs` | -| Crypto: DIP-14 xpub / payment addrs | ✅ | `crypto/dip14.rs` | -| Crypto: `accountReference` | 🟡 **G3/G7** (correct but unused; send hardcodes 0) | `crypto/dip14.rs:147` | -| Crypto: auto-accept proof | 🟡 **G7** (dead code, `// TODO` at `auto_accept.rs:39`) | `crypto/auto_accept.rs` | -| Pre-send validation | 🟡 **G7** (never called) | `crypto/validation.rs:76` | -| Persistence round-trip | ✅ | `wallet/apply.rs`, storage `schema/{contacts,dashpay}.rs` | -| Local placeholder `encrypted_public_key` | 🟡 **G8** (`vec![0u8;96]`) | `network/contact_requests.rs:283` | -| Contract cache | 🟡 **G9** (re-load per call) | `network/profile.rs:83` | -| FFI surface (sync/send/accept/reject/pay/profile) | ✅ | `ffi/src/{dashpay,dashpay_profile,contact_request,established_contact,contact}.rs` | - -> **No `todo!()`/`unimplemented!()`/`unreachable!()` anywhere in DashPay paths** — -> all gaps are caveats, dead helpers, or local-only fallbacks, not panics. - -### 3.4 SwiftExampleApp + swift-sdk - -| Capability | Status | Evidence | -|---|---|---| -| All ~14 DashPay/DPNS FFI functions wrapped | ✅ | `Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift:1452-1779` | -| Wrapper objects: `ContactRequest`, `EstablishedContact`, `DashPayProfile` | ✅ | same dir | -| SwiftData mirrors: `PersistentDashpayProfile`, `PersistentDashpayContactRequest` | ✅ | `Persistence/Models/` | -| Contacts list + incoming requests + accept/reject | ✅ (utilitarian) | `Views/FriendsView.swift` | -| Add friend by DPNS name / identity id | ✅ | `FriendsView.swift` (`AddFriendView`) | -| Send money to contact sheet | ✅ (most polished) | `FriendsView.swift` (`SendDashPayPaymentSheet`) | -| Profile view / editor (DIP-15 avatar hashing) | ✅ | `Views/IdentityDetailView.swift:332,1169` | -| First-class DashPay tab | ❌ **(Part 6)** buried under Identities | `ContentView.swift` | -| Outgoing requests rendered | ❌ (loaded, not shown) | `FriendsView.swift` | -| Lists driven by reactive `@Query` | ❌ (reads live Rust snapshot) | `FriendsView.swift` | -| DashPay tests (unit / XCUITest) | ❌ **G11** | `SwiftTests/`, `SwiftExampleAppUITests/` | - ---- - -## Part 4 — Gap analysis & bugs (prioritized) - -### P0 — blocks a correct, complete flow - -**G1 — Sync cannot establish contacts, and never builds sending accounts.** -Two compounding defects in `sync_contact_requests` (`network/contact_requests.rs:322`): -(1) **the ingest guard drops reciprocal requests** — any received doc whose sender is -already in `sent_contact_requests` is skipped (`:367-372`), so in the offline-accept -scenario the reciprocal request never reaches `add_incoming_contact_request` (the -only auto-establish trigger) and the contact stays pending-sent forever; (2) even -for contacts that do establish, sync stores the *encrypted* `encryptedPublicKey` and -never decrypts it or registers a `DashpayExternalAccount` — only the explicit -**accept** path does. **Consequence:** "they accepted me → I sync → I pay them" -fails twice over: the contact never establishes via sync, and `send_payment` -(`network/payments.rs:135`) has no sending account. **Fix:** (a) relax the ingest -guard so a received doc whose sender matches a `sent_contact_requests` entry flows -into `add_incoming_contact_request` (which auto-establishes and collapses the -pending entries); (b) on every sync pass, for **every established contact missing an -external account** (not only newly-established ones — this also repairs contacts -left unpayable by the accept path's best-effort registration), validate the -request's key indices via `validate_contact_request` (purpose ENCRYPTION/DECRYPTION -+ ECDSA key type — never ECDH against an unvalidated index; an attacker-crafted -index pointing at an AUTHENTICATION key silently derives a wrong shared secret and -poisons the account), then decrypt the xpub and register the account — and likewise -register a missing **`DashpayReceivingFunds`** account (derivable from the wallet's -own seed, no decryption needed): it is what makes *incoming* contact payments -visible to SPV, its only creation point today is the fresh-send path -(`contact_requests.rs:300`), and after restore-from-seed nothing rebuilds it — -incoming payments would land on unwatched addresses; (c) **failure -policy** — distinguish transient failures (network: retry next sweep) from permanent -ones (decrypt/decode failure: mark the contact "payment channel broken", surface to -FFI/UI, skip until the request changes — no unbounded retry). Must be seed-aware -(skip + log for watch-only until G4). - -**G2 — `send_contact_request` entropy mismatch.** -`rs-sdk/.../contact_request.rs:431-435`: `create_contact_request` computes the -document id from entropy E1, but `send_contact_request` generates *fresh* entropy -E2 for `put_to_platform_and_wait_for_response`. The code comment admits the -"simplification". **Action:** verify whether `PutDocument` re-derives the id from -E2 (in which case the returned `ContactRequestResult.id` is merely *stale*, a -correctness wart) or whether the broadcast actually fails / duplicates. Thread the -*same* entropy through both. Pin with a test asserting `result.id == on-platform id`. - -**G11 — Test coverage (precise breakdown).** -What's **well covered** (≈60 unit tests): crypto (`crypto/dip14.rs` ×10, -`validation.rs` ×8, `auto_accept.rs` ×6), the contact state machine -(`state/managed_identity/contact_requests.rs` ×12, `mod.rs` ×8), the DashPay types -(`established_contact`/`profile`/`contact_request`/`payment`), and persistence -(`wallet/apply.rs` ×26). Plus `tests/contact_workflow_tests.rs` (8 tests) — but -those are **pure in-memory handshake** tests using `noop_persister()` and **fake -identities** (`data: vec![1u8;33]`, not real keys), so they exercise the state -machine, *not* real ECDH/derivation/broadcast. - -What's **completely untested**: the entire **`network/` layer** — the actual -broadcast/sync/pay paths. `grep #[test] src/wallet/identity/network/` → only -`registration.rs` has one. **Zero** tests for -`send_contact_request_with_external_signer`, `sync_contact_requests`, -`sync_profiles`, `accept_contact_request_with_external_signer`, -`register_external_contact_account`, `send_payment`, `create/update_profile`. And -**zero** DashPay tests in Swift. This is a quality-P0: the flow cannot be declared -"done and tested" without (a) network-layer tests via a mock SDK/broadcaster seam, -and (b) a real devnet/regtest end-to-end test. (Test plan: Part 7.) - -**G12 — DashPay sync is not in the recurring sync loop.** -The background `IdentitySyncManager` (`manager/identity_sync.rs`, owned by -`PlatformWalletManager` at `manager/mod.rs:54,139`, run as a cancel-token loop with -a configurable interval and a re-entrancy guard) syncs **token balances only**. -`dashpay_sync()` (= `sync_contact_requests()` + `sync_profiles()`) is invoked -**only on demand via FFI** — i.e. the Swift app must poll it. There is **no -recurring DashPay refresh**. **Fix (the constraints matter more than the -placement):** `dashpay_sync()` is a method on `IdentityWallet` (needs the -wallet-manager lock, per-wallet persister, broadcaster), while `IdentitySyncManager` -is deliberately self-contained (constructed with sdk + persister only; documented as -not reaching into PlatformWallet/WalletManager) and its registry **skips identities -with empty token lists** — so the recurring DashPay pass must **NOT** be driven "per -registered identity" off the token registry (a DashPay-only identity with no watched -tokens would never sync). Instead, inject the wallets map (the same -`Arc>>>` that -`PlatformAddressSyncManager` already receives at `manager/mod.rs:135-138`; snapshot -the wallet `Arc`s under a read guard per sweep) and iterate wallets calling -`wallet.identity().dashpay_sync()` per pass, reusing the existing -cadence/cancel/quiesce/re-entrancy machinery. Whether this lives inside -`IdentitySyncManager` or as a sibling `DashPaySyncManager` is an implementation -detail; coupling DashPay sync to the token registry is the failure mode to avoid. -**Error semantics:** log-and-continue per wallet/identity (matching the existing -loop's contract) — never fail-fast across identities. Note: wrapping `dashpay_sync` -alone only delivers per-*wallet* continue — `sync_contact_requests` currently -`?`-aborts its multi-identity loop on the first fetch error and `dashpay_sync` -propagates immediately, so the per-identity policy must be implemented *inside* -those loops. This recurring pass is the -natural home for the **G1** establish/decrypt/register sweep, the **G13** sent-side -reconcile, and the **G5** tombstone check. Keep the on-demand FFI entry points for -pull-to-refresh. - -### P1 — spec-correctness / production-readiness - -**G3 — `accountReference` hardcoded to 0.** The send path uses -`account_reference = 0` instead of `calculate_account_reference(...)` -(`crypto/dip14.rs:147`). Because the unique index is -`(ownerId, toUserId, accountReference)`, a second request to the same recipient -(key rotation, multi-account) **collides** and is rejected by Platform. Today this -"works" only because the full account xpub is shared directly (recipient decrypts -it and doesn't need to un-mask the account). **Fix:** wire -`calculate_account_reference` into the send path; add the version-bump path for -rotation; have the receive path tolerate / surface non-zero versions (DIP-15 §7.3 -"sender rotated their addresses" notification). **Receive-side scope note (budget -into M3):** the in-memory maps, changeset keys, and SQLite contacts schema are -keyed by counterparty id alone, and the sync ingest guard skips requests from -already-established contacts — surfacing rotation requires re-keying -contact-request state + persistence by `(counterparty, accountReference)` and -letting rotation requests from established contacts through the guard. Without -this, `dp_005`'s "receive path surfaces the rotation" assertion is unimplementable. - -**G4 — Watch-only wallets can't send/accept.** ECDH is derived from the -in-process seed (`identity_handle.rs:424`); only `EcdhProvider::SdkSide` is used. -For hardware/watch-only wallets, the `ClientSide` path (host supplies the shared -secret) must be pushed across the FFI. **Fix:** add an FFI/signer hook that returns -the ECDH shared secret for `(senderKeyIndex, recipientPubKey)` from the secure -element, and route `send_contact_request` / `register_external_contact_account` -through `EcdhProvider::ClientSide`. *(The example app holds the seed, so this is -not a demo blocker — but it is the right architecture.)* **FFI-hook design lands in -M3** (design-only task) so the wallet API doesn't churn in M4: the hook accepts -only the 32-byte ECDH **shared secret** from the host — never the sender's identity -private key across the ABI (the existing `rs-sdk-ffi` -`DashSDKContactRequestParams.sender_private_key` field is the antipattern to avoid, -and worth auditing in its own right). - -**G5 — Reject is local-only, and the recurring loop will undo it.** -`reject_contact_request` (`network/contact_requests.rs:678`, `// TODO` at `:703`) -drops the local entry but writes no tombstone of any kind — and the still-on-platform -immutable document is re-ingested as a fresh incoming request on the next sync. -Today this is masked because sync is on-demand only; **the moment G12 lands, every -background sweep resurrects every rejected request on the same device.** **Fix (two -stages):** **M1 (with G12):** a locally-persisted rejected-request tombstone -consulted by the sync ingest path — keyed by **document id (or -`(sender, accountReference)`)**, NOT bare sender id: requests are immutable, so the -only legitimate way a once-rejected sender can ever re-request is a new doc with a -bumped `accountReference` (the rotation mechanism), and a sender-keyed tombstone -would silently block that forever with no un-reject affordance. Pinning test: -"rejected request does not reappear after a recurring re-sync — and a -bumped-`accountReference` request from the same sender *does*". **M3:** the -on-platform `contactInfo` `displayHidden` write (see G10) for cross-device sync. - -**G13 — Sync never reconciles your own sent requests.** Sync only calls -`fetch_received_contact_requests`; the identity's own sent requests are never -fetched into state (the `fetch_sent_contact_requests` query exists but is -read-only). After restore-from-seed or on a second device, a mutually-established -contact renders as a mere incoming request; tapping Accept re-broadcasts a duplicate -reciprocal with the same `(ownerId, toUserId, accountReference)` triple, which -Platform rejects on the unique index — **Accept fails forever with no recovery -path**. **Fix (M1):** sync also fetches the identity's own sent contactRequest -documents and ingests them via `add_sent_contact_request` (auto-establish fires when -both sides are present) — **with a sent-side ingest guard symmetric to the received -side**: skip docs whose recipient is already in `sent_contact_requests` or -`established_contacts` (`add_sent_contact_request` has no such guard today, so an -unguarded recurring re-ingest creates phantom pending-sent rows + a changeset write -per contact per sweep). Any (re-)establish path must **merge into an existing -`EstablishedContact`** — `EstablishedContact::new` resets alias/note/is_hidden/ -accepted_accounts, so naive re-establish wipes user metadata every sweep. Accept -detects an existing on-platform reciprocal and adopts it instead of re-broadcasting; -"adopt" includes the local registrations a fresh send performs (receiving-account -registration, G1(b)) and runs the same `validate_contact_request` gate before any -`register_external_contact_account` call — the gate applies to **all three paths** -(sync sweep, normal Accept, Accept-adopt). *Pin:* "established contact is stable -and metadata-preserving across two recurring sweeps". - -**G14 — Wrong encrypted-xpub wire format (P0; found by the M1 desk-check, -`INTEROP_DESK_CHECK.md`).** DIP-15 and BOTH reference clients -(iOS dash-shared-core `ecdsa_key.rs:333-341`, Android dashj -`serializeContactPub()` with a hard `len == 69` receive check) use the compact -**69-byte** plaintext `parentFingerprint(4) ‖ chainCode(32) ‖ pubKey(33)`. Our -stack fed `ExtendedPubKey::encode()` into `encrypt_extended_public_key` — and the -DashPay account xpub ends in a `Normal256` child, so that's the **107-byte -DIP-14** serialization → 128-byte ciphertext → fails our own `== 96` assertion -and the contract's `maxItems: 96`. **Consequence:** our send path errored before -broadcast (nothing nonconforming reached chain — blast radius ≈ zero), and our -receive (`ExtendedPubKey::decode`, 78/107 only) rejects every mobile payload and -would mark the channel permanently broken. **Fix (M1 task 7):** compact 69-byte -assembly on send + compact parser on receive (path context reconstructs -depth/child-number); byte-exact vectors from the reference clients. - -**G15 — Key-purpose convention mismatch (P1; same desk-check).** Mobile clients -populate `senderKeyIndex`/`recipientKeyIndex` with key id 0 — an -**AUTHENTICATION**-purpose ECDSA key — while we *send* selecting -ENCRYPTION/DECRYPTION-purpose keys and *validate* (G1(b)) requiring those -purposes. Cross-client requests would be blocked in both directions. **Action -(M1 task 8):** verify empirically against a real testnet mobile contactRequest, -then align — liberal-on-receive (accept the purposes mobile actually uses; keep -the ECDSA key-*type* gate), compatible-on-send (fall back to the mobile -convention when the recipient lacks a DECRYPTION-purpose key). - -### P2 — cleanup / completeness - -- **G6 — Wrong fallback contract id** (relabeled P2 — dead code in default builds): - `rs-sdk/.../dashpay/mod.rs:33` hardcodes the **DPNS** id under - `#[cfg(not(feature="dashpay-contract"))]` — a latent foot-gun. **Fix:** correct - the constant to the DashPay id `Bwr4WHCP…NS1C7` or delete the fallback. - -- **G7 — Dead code:** wire `validate_contact_request` into the send path (replace - the ad-hoc `find(...)`) — note the *receive/sync* side of this validator is pulled - forward into **M1** by G1(b); decide whether to ship auto-accept (then call the - proof gen/verify) or delete it and its FFI param. **Acceptance criterion if - shipped:** any handler acting on `autoAcceptProof` MUST call - `verify_auto_accept_proof` before triggering automatic acceptance — sync stores - the blob unverified today, so wiring auto-accept without the gate lets forged - 38–102-byte blobs auto-establish attacker contacts. -- **G8 — Local placeholder:** store the real 96-byte ciphertext on the local sent - `ContactRequest` (`contact_requests.rs:283`) so the persisted/SwiftData row - matches Platform. -- **G9 — Contract cache:** hold one `Arc` on the wallet instead of - re-loading the bundled contract per op. -- **G10 — `contactInfo` support:** add SDK + wallet + FFI for the `contactInfo` - document (self-encrypted alias/note/displayHidden/acceptedAccounts) so contact - metadata and hides sync across a user's devices. Respect the "≥2 contacts before - publishing" privacy rule. -- **Compact-xpub note:** DIP-15 specifies a 69-byte compact xpub plaintext; - `platform-encryption` currently encrypts a 78-byte serialization (still 96 bytes - out). Both sides of *this* implementation agree, so it interoperates with itself; - verify against the reference DashPay clients (iOS/Android) before declaring - cross-client compatibility. **Sequencing:** the desk-check (compare reference - client code or captured vectors) is cheap and lands in **M1** (task 5) — a wrong - wire format must be caught before three milestones of tests harden it; the live - cross-client e2e stays in M4. - ---- - -## Part 5 — Work plan (what to build, per milestone) - -Each task notes the layer and the **test** that proves it (TDD: write the failing -test first — see Part 7 and the repo's TDD discipline). - -### Milestone 1 — Correctness (the flow actually completes) - -Ordered so the test seam exists before the TDD-gated tasks that need it. - -1. **G11-seam: make the network layer testable.** The **fetch half needs no new - seam** — use the SDK's built-in mock (`SdkBuilder::new_mock` + - `expect_fetch`/`expect_fetch_many`, already used by `identity_sync.rs` tests) - for the sync/establish tests below. The **put/broadcast half** cannot hide - behind a dyn trait (`Sdk::send_contact_request` is generic over 7 type params): - define ONE object-safe trait exposing only the concrete operations - `IdentityWallet` performs (send contact request with SdkSide ECDH, put profile - document), held as a new `IdentityWallet` field defaulting to an - `Arc`-backed impl so public construction and FFI are untouched. - (`send_payment` already takes an injected `broadcaster: B`.) - **DONE (2026-06-10; revised 2026-07-04):** originally shipped as a - Send-boxed `#[async_trait]` `DashPaySdkWriter` trait; the trait was later - removed as an unused seam (no test ever injected it — the sync/establish - tests mock the fetch half via `SdkBuilder::new_mock` instead). - `network/sdk_writer.rs` now ships a concrete `SdkWriter` held as an - `Arc`-backed `IdentityWallet` field: it still erases the - 7-type-param `send_contact_request` / `PutDocument` generics behind two - concrete methods, it just isn't swappable. -2. **G12: fold DashPay sync into the recurring loop.** Per G12: inject the wallets - map and iterate wallets calling `dashpay_sync()` — do **not** drive off the - token registry; log-and-continue error semantics; keep the on-demand FFI entry - points for pull-to-refresh. - - *Test:* a recurring pass drives DashPay sync for every wallet **including - identities with zero watched tokens**; re-entrancy + quiesce still hold. - **DONE (2026-06-10):** sibling **`DashPaySyncManager`** (`manager/dashpay_sync.rs`, - modeled on `PlatformAddressSyncManager`) — the in-struct option was rejected - because `IdentitySyncManager` is registry-driven. Red→green pinned by - `recurring_pass_syncs_every_wallet_including_zero_token_identities`; per-identity - continue pushed into `sync_contact_requests`. -3. **G1 + G13 + G5-tombstone: sync establishes, reconciles, and builds accounts.** - Relax the ingest guard (G1a); ingest own sent requests (G13); consult the - persisted rejected-senders tombstone (G5 stage 1); then, for every established - contact missing an external account: validate key indices → decrypt → register - (G1b), with the transient/permanent failure policy (G1c). **Lock ordering:** - collect candidates while the wallet-manager write guard is held, drop the - guard, then call `register_external_contact_account` — it re-acquires read - locks on the same tokio `RwLock`, which is **non-reentrant**; calling it inline - under the write guard deadlocks on first execution (mirror the accept path's - guard-drop ordering — `network/contact_requests.rs:466` drops the write guard - before calling `register_external_contact_account`). - - *Tests:* offline-accept→pay (Part 7, `dp_004`); rejected request does NOT - reappear after a recurring re-sync; restore-from-seed then Accept does not - double-broadcast (G13); permanent decrypt failure marks the contact unpayable - and stops retrying. - **DONE (2026-06-10):** tombstone keyed `(owner, sender, accountReference)` - (new `rejected_contact_requests` SQLite table + `ContactChangeSet.rejected`); - broken channel = `EstablishedContact.payment_channel_broken` (new `contacts` - column + FFI accessor `established_contact_is_payment_channel_broken`); - metadata-preserving `reestablish_preserving_metadata()`; sweep candidates - collected under the write guard, registered after guard drop. 192 tests green. - *Deviations:* (1) tests pin the decision logic + state machine; the full - mock-SDK offline-accept→pay and accept-adopt flows live in `dp_004`/`dp_005` - on #3549 (per Part 7.4) — too heavy to stub as unit tests; (2) the Swift - persister bridge does NOT yet project `rejected` / `payment_channel_broken` — - added to M2 plumbing (task 8). -4. **G2: entropy threading.** Fix `rs-sdk` `send_contact_request` to reuse the - creation entropy; assert returned id == on-platform id. - - *Test:* `rs-sdk` unit/integration pinning id equality. - **DONE (2026-06-10) — severity verdict: REAL BROADCAST BUG.** `put_document` - uses the document as-is (E1-derived id) with the supplied fresh entropy E2; - drive-abci consensus recomputes `generate_document_id_v0(…, E2)`, compares to - `base.id`, and rejects with `InvalidDocumentTransitionIdError` — **every - `send_contact_request` through this path failed at consensus**. Fix: additive - `entropy: Bytes32` on `ContactRequestResult`, reused by send; pinned by - `contact_request_result_entropy_derives_returned_id` (red = inexpressible - pre-fix; green post-fix). 136 lib + all test targets green; FFI ABI unchanged. -5. **Interop desk-check (verify-only).** Compare the compact-xpub plaintext - (69B DIP-15 vs 78B current), ECDH derivation, and accountReference masking - against reference DashPay iOS/Android client code or captured vectors; record - the result. A mismatch found here re-scopes M1 before tests harden the wrong - format; the live cross-client e2e stays in M4. - **DONE (2026-06-10)** — `INTEROP_DESK_CHECK.md`. Verdicts: - xpub plaintext **FAIL** (→ new **G14**, task 7 below); ECDH **PASS**; - accountReference **PASS-for-now** (mobile ignores it on receive; our masking - helper has two latent bugs for M3 — 107-byte HMAC input + ASK28 byte order, - where iOS and Android also disagree with *each other*). Bonus hazard → **G15** - (key-purpose convention). -7. **G14: compact-xpub wire format (re-scoped into M1 by task 5).** Send: assemble - the 69-byte compact plaintext (`parentFingerprint(4) ‖ chainCode(32) ‖ - compressedPubKey(33)`) from the already-derived contact xpub instead of - `ExtendedPubKey::encode()`; receive: parse the 69-byte compact (both sides - already know the derivation path, so depth/child-number are reconstructable). - Pin with byte-exact vectors mirroring the reference clients (iOS - `ecdsa_key.rs:333-341`, dashj `serializeContactPub()` — quoted in - `INTEROP_DESK_CHECK.md`). 69 → PKCS7 → 80 ‖ IV 16 = exactly 96 bytes. - **DONE (2026-06-10):** codec in `platform-encryption` - (`compact_xpub_bytes`/`parse_compact_xpub`, `COMPACT_XPUB_LEN=69`); - `ContactXpubData::compact_xpub()` + `reconstruct_contact_xpub` in - `crypto/dip14.rs`; rs-sdk callback contract = "69-byte compact", validated - pre-encryption; receive reconstructs from `chain_code`+`pubkey` (metadata - depth/child synthesized — non-hardened CKD unaffected, pinned by - `reconstructed_xpub_derives_identical_addresses`); legacy 78/107 fallback - branch kept. 194 platform-wallet tests green; FFI ABI unchanged (caller doc - contract tightened). -8. **G15: key-purpose verification (decision gate, cheap).** Fetch a real - mobile-created `contactRequest` + its sender identity from testnet; inspect - `senderKeyIndex`/`recipientKeyIndex` purposes. Then align: likely - liberal-on-receive (accept ECDSA keys of the purposes mobile actually uses) - + compatible-on-send (fall back to the mobile convention when the recipient - has no DECRYPTION-purpose key). Implementation in M1 if the verification - confirms the mismatch; the validation gate from G1(b) stays for key *type*. - **VERIFIED (2026-06-10, all 368 testnet contactRequests — - `INTEROP_DESK_CHECK.md` §G15):** the "key 0 AUTHENTICATION" desk-check reading was - stale. Dominant mobile cohort (223 docs): **unbound ENCRYPTION/MEDIUM key - (id 2) for BOTH indices** (recipientKeyIndex → ENCRYPTION — mobile identities - carry no DECRYPTION key); 2026 cohort (68 docs): contract-bound ENC(4)/DEC(5) - — our convention. Consensus enforces neither purpose nor boundedness on these - fields. **Alignment (task 9):** send — prefer recipient DECRYPTION, fall back - to recipient ENCRYPTION; receive — accept ENCRYPTION for sender, - ENC-or-DEC for recipient; keep the ECDSA type gate; purpose mismatch alone - never marks a channel permanently broken. No AUTHENTICATION fallback. -9. **G15 alignment implementation** (per the verified verdict above): relax the - sender/recipient purpose assertions in `rs-sdk` `create_contact_request` - (`:200-239`) and `rs-platform-wallet` key selection + `validate_contact_request` - wiring; tests for the mobile-cohort shape (ENC/ENC, unbound) and our own - (ENC/DEC, bound). - **DONE (2026-06-10):** recipient selection prefers DECRYPTION, falls back to - ENCRYPTION (ECDSA gate kept, no AUTH fallback); validation gained a recipient - purpose gate (AUTH was silently accepted before!) + `purpose_mismatch` flag; - purpose mismatches log-and-skip, never `payment_channel_broken`; ECDH decrypt - path confirmed index-generic (pinned). 204 platform-wallet + 139 dash-sdk - tests green. **M1 complete** (task 6 e2e rides #3549, non-gating). -6. **G11-Rust: full-cycle e2e confirmation** (`dp_003`): `profile → send → sync → - accept → established → pay`, on live testnet via the #3549 bank harness. - **Not M1-exit-gating** (Part 7.4): M1 exits on tasks 1–5; this task is tracked - on #3549 and lands when the framework does. - -**coreHeight backfill rescan (DIP-15 §8.7/§12.6) — DONE (2026-06-24).** Surfaced by -the re-audit after M1's original plan: an incoming payment to a contact's receival -address that landed *before* the address was watched (restore-from-seed, second -device, or the offline-accept→pay window) was silently missed. Fixed by (a) re-import -scanning from birth-height `Some(0)` (`cba515aaf1`) so on-chain history isn't skipped, -and (b) `reconcile_dashpay_rescan` (`18483e4232`, a local-only step of `dashpay_sync` -in `manager/dashpay_sync.rs`) that lowers the wallet's SPV `synced_height` toward -`min($coreHeightCreatedAt)` over established receival contacts so dash-spv's filter -manager re-matches the now-watched addresses against blocks it already scanned. It uses -the inner unconditional height setter (no upstream change) with a per-contact -`dashpay_rescan_triggered` one-shot guard so the recurring sweep doesn't re-lower the -height every pass. The regression is safe (`synced_height` is the filter-scan -checkpoint, decoupled from the monotonic `last_processed_height`); the floor is clamped -to the engine's header/birth floor, and the one SPV caveat is that a rewind into a -never-stored filter range is retried silently every 30s rather than erroring. - -### Milestone 2 — Swift UI (first-class, polished) + Swift tests - -See Part 6 for the screen design. Tasks: - -> **STATUS (2026-06-10): tasks 7–10 DONE** (Phases A–D on -> `feat/dashpay-m1-sync-correctness`). Delivered: FFI sync-control surface -> (`platform_wallet_manager_dashpay_sync_{start,stop,is_running,is_syncing, -> last_sync_unix_seconds,set_interval,sync_now}`), persister payload extended -> (callback arity 8→10: `payment_channel_broken` on `ContactRequestFFI`, -> `ContactRequestRejectionFFI` tombstones), payment-history getter -> (`managed_identity_get_dashpay_payments`); Swift SDK wrappers + -> `PersistentDashpayPayment` + `@Published dashPaySyncIsSyncing`; the full -> DashPay tab (`Views/DashPay/` — 7 files) with all §6.4 states and -> `dashpay.*` accessibility ids; simulator BUILD SUCCEEDED. -> **Spec deltas accepted:** (1) alias/note/hide are a UserDefaults-backed -> device-local store until M3's `contactInfo` (no SwiftData model added); -> (2) contact DPNS labels captured as an add-time hint (not persisted -> elsewhere); (3) AddContact ID-mode preview is cache-only (no -> fetch-profile-by-id FFI). Task 11 (tests) = Phase D. -> **Task 11 DONE (2026-06-10):** 15 SDK unit tests (persister bridge: broken-flag -> on both rows, tombstone scoped to `(owner,sender,accountReference)` w/ rotation -> survival, 10-arg C-callback round-trip, payment upserts, FFI marshalling) + 2 -> UI smoke tests (§6.4 picker states; passed on-simulator). Phase D also found & -> fixed a changeset-atomicity defect (`persistDashpayPayments` missing the -> `!inChangeset` guard — red→green). Totals: swift test 29/29; app tests 237 -> passed / 18 pre-existing network-gated skips; UI smoke green; BUILD SUCCEEDED. -> Full add→approve→pay XCUITest = documented TODO gated on funded testnet -> identities (tracks `dp_003`). - -7. Add `RootTab.dashpay` + `DashPayTabView` with an active-identity picker - (`ContentView.swift`, `SwiftExampleAppApp.swift`) — picker states per §6.4. -8. Extract/rebuild `ContactsView`, `ContactRequestsView` (incoming **+ outgoing**), - `AddContactView`, `ContactDetailView`, `ProfileView`/editor, reusing the - already-wrapped `ManagedPlatformWallet` methods; implement the §6.4 interaction - states (DPNS resolution states, send-collision flow — **AddContactView only**, - not the payment sheet — in-flight rows). Payment - history requires the persister mapping + `PersistentDashpayPayment` model (§6 - intro). Additional persister-bridge plumbing from M1: project the - `rejected` tombstones and `payment_channel_broken` flag into SwiftData (the - Rust SQLite pipeline already persists them; the Swift `on_persist_contacts_fn` - bridge does not yet). -9. Move lists onto `@Query [PersistentDashpayContactRequest]` / - `[PersistentDashpayProfile]` with the §6.4 optimistic-overlay policy; refresh - via `syncContactRequests()` + `syncDashPayProfiles()` in `.task` / - pull-to-refresh, coordinated through the §6.4 single sync-in-progress signal - (requires M1 task 2 — the three-caller invariant can't be exercised until the - G12 background loop exists). **Realtime cadence (per §6.4):** the tab drives the - background loop's interval to 4s on foreground / 15s on background via - `setDashPaySyncInterval` (NavigationStack `onAppear`/`onDisappear`), and every - local mutation (send/accept/QR-send/pay) fires a non-blocking `kickDashPaySync` - so the counterparty side converges without waiting for the next tick. -10. Polish: AsyncImage avatars w/ initial-circle fallback, empty states, loading & - error states, inline success feedback (§6.4), accessibility identifiers on - every interactive control (for XCUITest). -11. **G11-Swift:** unit tests (wrapper round-trips) + XCUITest (add→approve→pay). - (Part 7.) - -### Milestone 3 — Spec completeness (rotation, hide, alias sync) - -12. **G3:** wire `calculate_account_reference` + version bump into send; - receive-path version handling + "addresses rotated" surfacing — **includes the - receive-side re-keying** of contact-request state/persistence by - `(counterparty, accountReference)` (see G3 scope note). -13. **G10 + G5 stage 2:** `contactInfo` document support (SDK + wallet + FFI) → - cross-device reject/hide + alias/note sync. - - **DONE (2026-06-12), 4 commits:** crypto core (DIP-15 derivation - `root/65536'+65537'/idx'`, AES-256-ECB encToUserId, IV‖CBC privateData; - the `privateData` plaintext was initially a CBOR array but is being - migrated to the **DIP-15 varint** format — the contract enforces length - only, so it's a free convention; see `CONTACTINFO_FORMAT_SPEC.md` / - Spec 1), stateless doc↔contact resolution (decrypt every owned doc's - encToUserId), sync step 3 of the recurring pass, publish with the - DIP-15 ≥2-contacts privacy gate (deferred publishes update local state - only), FFI `platform_wallet_set_dashpay_contact_info_with_signer`, - persister round-trip (alias/note/hidden on the established rows, both - directions), and **contact restore at load** (new contacts array on - `IdentityRestoreEntryFFI`) — without which the re-establish sweep wiped - metadata during the deferred-publish window and contacts were invisible - on offline launches. Verified on-sim: alias save → relaunch → survives - and renders. -14. Swift UI for alias/note edit (reuse `EditAliasView`) now backed by - `contactInfo` — remove the M2 "This device only" labels. - - **DONE (2026-06-12):** ContactDetailView reads alias/note/hidden off - the `@Query` contact rows and writes through - `ManagedPlatformWallet.setDashPayContactInfo`; ContactsView hidden - filter + alias display moved off the UserDefaults meta store (which - now only keeps the add-time DPNS hint); labels updated. - -**Receive-side `encryptedAccountLabel` surfacing (DIP-15 §8.5) — DONE (2026-06-24).** -The send side already length-normalizes the label; the receive side now decrypts and -shows it. Decrypted in Rust at the two signer-bearing register sites (the drain -`RegisterExternal` Ok-branch + `accept_register_external_validated`, where the ECDH -`shared` key lives) by `store_contact_account_label` (`network/contact_requests.rs`), -stored on the derived `EstablishedContact.contact_account_label` field (reset in `new`, -`reestablish_preserving_metadata`, and `apply_rotated_incoming_request` so it never -goes stale). It is surfaced **incoming-only** — it is the contact's label for *their* -account, so it is derived strictly from the incoming request and projected onto the -incoming FFI row only (the outgoing row's label is one *we* sent and is never shown), -via `contact_persistence.rs`. Decrypt failures / garbage / control-chars sanitize to -`None` (cosmetic — never breaks the channel), and it resets on rotation. Renders as a -read-only "Their account" row through Swift `contactAccountLabel` → `ContactDetailView`. - -15. **G4 design-only:** specify the FFI ECDH hook (shared-secret-only across the - ABI — never a raw private key; see G4) so M4's implementation doesn't churn - the wallet API. - - **DONE (2026-06-12) — design:** - - **ABI surface (one new callback on the existing host-signer table** — - the same registration path external-signable wallets already use for - transaction signing**):** - ```c - int32_t (*ecdh_shared_secret_fn)( - void *context, - const uint8_t (*wallet_id)[32], - const uint8_t (*identity_id)[32], - uint32_t key_id, // sender's encryption key id - const uint8_t (*counterparty_pubkey)[33], - uint8_t (*out_shared_secret)[32]); // SHA256((y&1|2)||x) — finished secret - ``` - The host derives the identity encryption private key for - `(identity_id, key_id)` from its keychain/secure element and computes - the **finished DIP-15 shared secret host-side**. The private key never - crosses the ABI (the `rs-sdk-ffi` `DashSDKContactRequestParams. - sender_private_key` field is the antipattern this replaces; flagged for - its own audit). Non-zero return = "host cannot produce the secret" - (locked keychain, missing key): the operation fails with a typed - `EcdhUnavailable` error and is NOT treated as a broken payment channel - (our side failed, not the contact's request). - - **Rust routing:** `send_contact_request` / - `register_external_contact_account` branch on wallet key-residency: - seed-resident wallets keep today's in-process derivation - (`EcdhProvider::SdkSide`); external-signable wallets route - `EcdhProvider::ClientSide { get_shared_secret }` where the closure - calls the FFI hook. No public wallet-API signature changes — the - provider choice is internal, which is what de-risks M4. - - **Zeroization:** Rust wipes `out_shared_secret` (`Zeroizing`) after - deriving the AES key; hosts are instructed to do the same with their - intermediate private key (Swift: `withUnsafeTemporaryAllocation` + - explicit reset, mirroring the signer callback's key handling). - - **Same hook serves decrypt-side** (`register_external_contact_account` - needs ECDH with the *contact's* pubkey at OUR key id) — the - `counterparty_pubkey` parameter covers both directions; no second - callback needed. - -### Milestone 4 — Hardening / cleanup - -16. **G4:** watch-only ECDH via `EcdhProvider::ClientSide` pushed across FFI - (implements the M3 design). - - **DEFERRED with design amendment (2026-06-13):** implementation scoping - found the M3 hook (ECDH shared secret only) is **insufficient** for true - watch-only DashPay: the friendship-xpub derivations are hardened and - seed-bound on BOTH flows — send derives the sender↔recipient receiving - xpub (`m/9'/coin'/15'/account'/`, recipient-dependent so not - pre-derivable), and accept derives our receiving xpub for the new - account. A watch-only host therefore needs **three** hooks: ECDH shared - secret (designed in M3), friendship-xpub derivation, and - receiving-account-xpub derivation — or one combined - "derive-DashPay-context" hook returning `(compact_xpub, shared_secret)`. - The contactInfo self-encryption keys (M3 task 13) are seed-bound the - same way and need a fourth surface (or ride the combined hook). - Since the example app attaches the seed at launch (this gap is - explicitly not a demo blocker), shipping the ECDH-only ABI change would - add churn without enabling any watch-only flow. Revisit as its own - design+implementation slice when a hardware/watch-only host exists. -17. **G6:** fix/delete fallback contract id. - - **DONE (2026-06-13):** fallback corrected from the DPNS id to the - deployed DashPay id. -18. **G7:** wire send-path validation; ship-or-delete auto-accept (verify-gate - acceptance criterion applies if shipped — see G7). - - **DONE (send half, 2026-06-13):** the selected key pair gates through - `validate_contact_request` before any ECDH/broadcast. Auto-accept: - decision = **keep dormant** — it activates with M5 invitations behind - the `verify_auto_accept_proof` hard gate (per Part 8.5), not deleted. -19. **G8/G9:** real local ciphertext; contract cache. - - **DONE (2026-06-13):** sent rows store the real 96-byte ciphertext off - the broadcast document; the bundled DashPay contract is cached - process-wide (OnceLock) replacing five per-call re-parses. -20. Live cross-client interop e2e (compact xpub, ECDH, accountReference) vs - reference DashPay clients (the M1 desk-check verified the formats on paper). - - **BLOCKED-EXTERNAL (2026-06-13):** requires driving real DashWallet - iOS/Android builds against a shared network — not runnable in this - environment. The M1 desk-check (`INTEROP_DESK_CHECK.md`) + on-chain census remain - the interop evidence; the contactInfo research (`CONTACTINFO_FORMAT_SPEC.md` Appendix A) found no - reference client implements contactInfo at all, shrinking the live-e2e - surface to contactRequest + payment addresses. Run manually when a - mobile test build is available. - -### Milestone 5 — Invitations (new scope, 2026-06-10; needs its own design pass) - -Onboard users who don't have Dash yet: inviter creates an asset-lock-funded -credit voucher + link (DIP-13 invitation subfeature, `m/9'/5'/5'/3'`); invitee -claims it → identity created from the voucher → invitee's contact request to the -inviter carries an `autoAcceptProof` (path `m/9'/5'/16'/timestamp'`, helpers -already implemented in `crypto/auto_accept.rs`) → auto-established contact after -`verify_auto_accept_proof` (hard gate, see G7/Part 8.5). Scope before -implementation: a research+design slice (invitation create/claim wallet flows, -deep-link format, expiry/revocation, UI) — the platform wallet has the asset-lock -and identity-registration machinery to build on but no invitation flows today. - ---- - -## Part 6 — Swift UI design (the "nice UI") - -**Decision: promote DashPay to a first-class tab (Option B).** Lower-risk Option A -(polish in place under Identities) is the fallback if tab real estate is contested, -but a "nice DashPay UI" wants its own home. All screens reuse already-wrapped -`ManagedPlatformWallet` FFI — **no new network FFI**; the one new plumbing item is -**payment history** (map the Rust `dashpay_payments` changeset overlay in the Swift -persister into a new `PersistentDashpayPayment` SwiftData model + `@Query` — today -no FFI exposes `PaymentEntry` and no SwiftData model exists for it). - -### 6.1 Navigation - -Add `case dashpay` to `RootTab` (`ContentView.swift`), between `identities` and -`contracts`. Tab icon `person.2.fill`, title "DashPay". - -``` -DashPayTabView (NavigationStack) -├─ Active-identity picker (top) — most DashPay UIs assume one active identity; -│ menu of the wallet's managed identities (DPNS name → truncated id). -├─ Profile header card → tap → ProfileView / ProfileEditorView -│ (empty state → "Set up your DashPay profile" CTA → ProfileEditorView) -├─ Username prompt card → "Register a username" → RegisterNameView -│ (shown only when an on-chain DPNS check confirms the active identity -│ has no name; explains that without a username people can't find you -│ by name, and that the profile display name is cosmetic, not searchable) -├─ Segmented control: [ Contacts | Requests ] -│ ├─ Contacts → ContactsView (@Query established) -│ │ row tap → ContactDetailView → "Send Dash" / alias / note / hide -│ └─ Requests → ContactRequestsView -│ ├─ Incoming (Accept / Reject) -│ └─ Outgoing (pending — NEW, currently unrendered) -└─ Toolbar: + (AddContactView) · refresh (sync) -``` - -Wire DashPay sync into the `.task` of `DashPayTabView` and/or the existing global -`GlobalSyncIndicator`: run `syncContactRequests()` then `syncDashPayProfiles()`. - -### 6.2 Screens - -**ProfileView / ProfileEditorView** (promote from `IdentityDetailView`) -- View: large avatar (`AsyncImage` w/ initial-circle fallback), `displayName`, - DPNS handle, `publicMessage`. "Edit" button. Empty state → "Set up your DashPay - profile" CTA (opens `ProfileEditorView` as a sheet — same target as "Edit"). -- Editor: `Form` with `displayName` (≤25), `publicMessage` (≤140), `avatarUrl`; - live char counters; on save fetch avatar bytes for DIP-15 hash/fingerprint; call - `createDashPayProfile` / `updateDashPayProfile(…signer:)`. - -**Username prompt** (`usernamePromptCard`, below the profile header) -- A second setup CTA, independent of the profile one: shown when the active - identity has **no DPNS username** (confirmed by an on-chain `dpnsGetUsername` - check in `.task` + on app-foreground, so an identity that already has one — - just not yet cached, or registered meanwhile on another device — is never - nagged; mirrors `IdentitiesView`'s lazy fetch. A found name is persisted and - saved; a definitive empty result shows the card; a thrown error retries. - Residual: a name registered on another device *while the user sits on this - tab* clears on the next tab switch / app-foreground). Tap → `RegisterNameView`. - Copy makes the username-vs-profile distinction explicit: a **username** is the - searchable handle people type to add you (contact search); the profile - **display name** is cosmetic and not searchable. On registration the Rust path - persists `dpnsName`, so the prompt hides reactively via `@Query`. - -**ContactsView** -- `@Query` established contacts (joined to `PersistentDashpayProfile` for - display). Row = avatar + (alias → displayName → DPNS → truncated id) + last - payment hint. Search bar. Pull-to-refresh = sync. Empty state → "Add your first - contact". - -**ContactRequestsView** (the **new outgoing section** is the headline UI gap) -- **Incoming**: row + Accept (`borderedProminent`) / Reject (`.tint(.red)`), - relative timestamp, sender profile. On accept → success toast + move to Contacts. -- **Outgoing**: pending sent requests (`fetchSentContactRequests` / - `getSentContactRequestIds`), "Pending" badge, sent timestamp. Currently loaded - but never shown — render it. - -**AddContactView** (restyle `AddFriendView`) -- Segmented: **Username (DPNS)** | **Identity ID**. DPNS mode: live prefix search - (`searchDpnsNames`) with result rows (avatar + name); ID mode: paste + validate - base58. Resolve → preview the target profile → "Send request" → `sendContactRequest`. - -**ContactDetailView** -- Profile header; **Send Dash** (presents the polished `SendDashPayPaymentSheet`); - payment history (from `PaymentEntry` via the `PersistentDashpayPayment` mapping — - see §6 intro); editable **alias** / **note** and **Hide** toggle, each labeled - **"This device only"** in M2 (until M3's `contactInfo` backing replaces the - label) so users don't assume sync semantics that don't exist yet. - -**SendDashPayPaymentSheet** (already polished — restyle only) -- Amount in DASH→duffs, spendable balance, over-spend block, recipient - profile/avatar/DPNS, result txid. (Memo is local-only; keep the field hidden or - label it "private note" until on-chain memo exists.) -- Zero-balance state: when spendable balance is 0 (after the async load), disable - the amount field + Send and show "Your balance is 0 DASH — top up your wallet - before sending." instead of an always-disabled interactive form. - -### 6.3 Conventions (must match house style) - -From `SwiftExampleApp/CLAUDE.md`: -- `@EnvironmentObject var walletManager: PlatformWalletManager`, - `var appState: AppState`; `@Environment(\.modelContext)`. -- Lists via `@Query` on `Persistent*` (move off the live-snapshot read). -- Async FFI: `Task { @MainActor in … }`, `defer { isLoading = false }`, resolve - wallet via `walletManager.wallet(for:)`, fresh `KeychainSigner` per submit, - `errorMessage` red caption on catch. -- `Form`/`Section` for editors, `List`/`Section` with count headers for lists. -- SF Symbols (`person.2`, `person.badge.plus`, `paperplane`, `pencil`, - `person.crop.circle`), blue accent, red destructive, green success, - `.borderedProminent` primaries. -- Amounts entered in DASH, converted to duffs (`× 100_000_000`). -- Display precedence: alias → DashPay `displayName` → DPNS → truncated hex. -- **`.accessibilityIdentifier(...)` on every interactive control** (needed for - XCUITest) — e.g. `dashpay.tab`, `dashpay.addContact`, `dashpay.request.accept`, - `dashpay.send.amount`, `dashpay.send.confirm`. -- **Never orchestrate in Swift** — one FFI call per DashPay op. - -### 6.4 Interaction states & edge cases (normative for M2) - -- **Identity picker** (tab root) — three states: (1) no wallet loaded → disabled - "No wallet loaded" label + link to the Wallets tab; (2) wallet but zero - identities → "No identities yet" + CTA to the Identities tab; (3) ≥1 identity → - menu. Exactly one identity → auto-select and hide the picker. Selection persists - across launches via `@AppStorage`. -- **AddContactView (DPNS mode)** — four states: typing → searching (inline - `ProgressView`) → not-found (inline message + clear-and-retry affordance, never a - dead end) → found (profile-preview card; "Send request" enabled only from this - state). ID mode: inline base58 validation gates the send button. (The current - `AddFriendView` dead-ends on "DPNS name not found".) -- **Send-collision flow** — if the target already has an incoming request to us, - alert "This person already sent you a request — Accept it instead?" with - Accept / Continue anyway. (Sending anyway is protocol-valid; it just establishes - the contact.) -- **Request rows in flight** — on Accept/Reject tap, replace both buttons with a - `ProgressView` for that row (prevents double-tap → duplicate accepts); on - success remove the row optimistically; on failure restore the buttons + inline - error on the row. -- **Optimistic overlay over `@Query`** — accept/reject/send mutate Rust state and - the persister callback lands later; bridge the latency window with a local - `@State` overlay set of affected ids filtering the `@Query` results, cleared - when the query reflects the change. (The old `loadFriends()` re-read pattern is - incompatible with pure `@Query` reactivity.) -- **Single sync-in-progress signal** — one `@Published` flag on - `PlatformWalletManager` observed by all three sync callers (`.task`, - pull-to-refresh, the G12 background loop); a pull-to-refresh during an in-flight - sync attaches to it instead of double-firing. -- **Realtime cadence (foreground-fast / background-slow)** — the G12 background - loop runs on a tunable interval (`setDashPaySyncInterval`, clamped ≥ 1s Rust-side; - default = `backgroundSyncSeconds` = 15s). The DashPay tab drops it to - `foregroundSyncSeconds` = 4s at *effective foreground* — the tab is on screen - **and** the app is active — and restores 15s otherwise. "On screen" is driven - from the tab's **NavigationStack** `onAppear`/`onDisappear` (so drilling into a - contact detail or presenting a sheet, neither of which fires the stack's - `onDisappear`, keeps the fast cadence; only a *tab switch* relaxes it); "app - active" is driven from `scenePhase`, so backgrounding the app while on the tab - also relaxes to 15s. The cadence acts only on transitions. This keeps neither an - inactive tab nor a backgrounded app sweeping every few seconds, while incoming - requests / acceptances / payments surface in near real time when the user is - actually looking. **Entry kick:** `setDashPaySyncInterval` only takes effect on - the loop's *next* sleep (it stores an atomic, no wakeup — `dashpay_sync.rs:157`), - so entering the foreground also fires one `kickDashPaySync` — otherwise a tab - re-entry could wait out a leftover up-to-15s sleep before the first fast tick. - (A Rust-side `Notify` on `set_interval` would shorten the in-flight sleep - directly; deferred as an internal refinement — the entry kick achieves the same - user-visible result app-side.) Best-effort: a not-yet-configured manager keeps - its current interval. -- **Post-mutation sync kick** — after a local mutation (send request, accept, - send-via-QR, pay) the handler fires a non-blocking `dashPaySyncNow()` - (`kickDashPaySync`) so the counterparty's state and the established pair converge - promptly instead of waiting a full poll tick. Non-blocking: the sheet dismisses - right away and the Rust manager folds an in-flight pass into a no-op (the single - sync-in-progress signal above). *Bounded, not instant:* if a pass was already - running when the mutation landed, the kick no-ops and convergence waits for the - next tick (≤ the foreground 4s) rather than enqueuing a coalesced re-run. - Complements, doesn't replace, the optimistic `@Query` overlay — the overlay - covers the sender's own row, the kick pulls the other side. -- **Success feedback** — reuse the existing inline success pattern - (`SendDashPayPaymentSheet`'s green inline text); no new toast component in M2 - (the app has no shared toast — only a clipboard `CopiedToast`). -- **Broken payment channel** (surfaces G1(c)) — ContactsView row shows a warning - badge; ContactDetailView disables Send Dash with "Payment channel broken — ask - the contact to send a new request" (re-enables when a new request arrives). -- **Needs-unlock / verify-failed banner** (seedless wallets) — **DONE (2026-06-23; - `9963923e05` Rust+FFI, `841802c587` Swift).** A signerless sweep enqueues - contact-crypto ops it can't finish while the Keychain is locked; - `pending_contact_crypto_count` (`network/contact_requests.rs`) → FFI - `platform_wallet_pending_contact_crypto_count` (`dashpay.rs`) feeds the ~1 Hz Swift - poller into a per-wallet `DashPayUnlockStatus` / `@Published dashPayUnlockStatus`, - rendered as a banner in `DashPayTabView.swift` (orange "N contact(s) waiting to - finish setup" + Unlock, red on seed-mismatch). The count **excludes** - `ContactInfoDecrypt` ops — those re-enqueue every sweep, so counting them would - falsely re-trip the banner ~15s after every unlock; only the account-build ops - (`RegisterReceiving`/`RegisterExternal`) converge to 0 once the payment account is - built. -- **Profile save flow** — on save: disable Save + inline `ProgressView`; success → - dismiss the editor sheet; failure → re-enable Save + red caption below the form. -- **Payment history list** — empty state "No payments yet"; loading = single - inline `ProgressView`; error = keep last-known list + inline caption. - ---- - -### Multi-reviewer code review (2026-06-14) — 8 findings fixed - -Five specialized reviewers (crypto-security, FFI-memory, sync-correctness, -Swift/iOS, silent-failures) audited the M1–M4 diff. Crypto + FFI-memory -boundaries came back clean. Correctness/silent-failure reviewers found bugs -the live UAT had missed (UAT only hit the pending-sent rotation path, which -the reject-tombstone masked). All fixed with red→green regression tests: - -- **P0** rotation re-send to an ESTABLISHED contact reset the version to 0 - → unique-index rejection → contact unrotatable. Lookup now consults - `established_contacts.outgoing_request` (`prior_sent_account_reference`). -- **P0** multi-doc sweep thrash: immutable docs from a rotated sender both - returned every sweep, flipping state + rebuilding the external account - forever. `newest_received_per_sender` collapses to newest-per-sender - before ingest; `apply_rotated` is idempotent. -- **Critical** swallowed persist errors → memory/disk divergence (reject - resurrection). New `PlatformWalletError::Persistence`; reject + send_payment - propagate, self-healing sweep writes log. -- **H1** Sent payments lost at relaunch (map restored empty) → new - `PaymentRestoreEntryFFI` + `restore_dashpay_payments` fold + Swift builder. -- **H2** deferred-publish lied as "synced" → 3-state `ContactInfoPublishOutcome` - through the FFI; ContactDetailView shows the real state. -- Med: zero-ciphertext fallback → hard Err; contactInfo derivation-index - high-water mark; Swift silent contact-drop now logged; crypto - account_index/accountReference invariant documented. - -230/230 Rust lib + FFI tests green, clippy clean, full iOS build green. -NOTE: on-device re-verify of H1/H2 pending — the sim SwiftData store was -reset environmentally (identities gone), so it needs the devnet identity -setup rebuilt first. - -### Devnet UAT round 2 (2026-06-13) — rotation / reject / DPNS verified live - -On paloma with three identities: **reject + tombstone** (rejected request -suppressed across forced re-sync), **G3 rotation end-to-end** (re-send from -the rejected sender broadcast with a bumped accountReference — accepted by -the unique index — and reappeared through the tombstone on the recipient: -the dp_005 scenario, live), **DPNS register → live search → found preview → -send** and the **not-found state** (inline + retry, no dead end), **accept -of the rotation request** (re-established, accounts rebuilt). Findings -fixed: optimistic pending-sent overlay leaked across identity switches -(now reset on picker change). Open UX item: "SPV client is not running" -dead-ends both Send Dash and identity creation — needs auto-start or a -"Start & retry" affordance (product decision pending). - -## Part 7 — Test plan - -Follow the repo TDD discipline (failing test first; red→green in the commit -message). DashPay's correctness-critical pieces are the crypto and the -state-machine handshake — those get the deepest coverage. - -### 7.1 Rust — `rs-platform-wallet` / `rs-sdk` / `platform-encryption` - -Already covered (keep, don't duplicate): crypto round-trips, the contact -state-machine handshake (`tests/contact_workflow_tests.rs` + inline), and -persistence (`wallet/apply.rs`). See G11 for the inventory. - -Unit — **the missing tier is the `network/` layer** (currently 0 tests). Add behind -a mock SDK/broadcaster seam: -- **Recurring sync (G12):** a recurring pass drives `dashpay_sync` for each wallet - — including identities with zero watched tokens (see G12: do not couple to the - token registry); re-entrancy guard + `quiesce` shutdown still hold; interval - changes are picked up. -- **Sync builds external accounts (G1):** given an established contact with an - encrypted xpub, the sync pass decrypts it and registers a `DashpayExternalAccount` - (and skips gracefully for watch-only). -- **Crypto/derivation wiring:** `calculate_account_reference` is actually used by - the send path (G3) and round-trips (un-mask recovers account + version). -- **State machine** (extend existing): idempotent re-sync; accept when both present; - reject removes incoming. - -Offline crypto/encode tier (rs-sdk, no network) — follow the existing -`packages/rs-sdk/tests/fetch/` harness with `--features mocks,offline-testing` -(`Config` from `tests/.env`, `mock::Mockable` + recorded vectors): -- **G2 (entropy):** after `create_contact_request`, the returned id matches the id - derived from the *broadcast* entropy. Pin id equality. -- contact-request wire-shape: `encryptedPublicKey == 96B`, properties map matches - the v1 schema, `accountReference` round-trips. - -**E2E tier — build on the existing framework (PR #3549, -`packages/rs-platform-wallet/tests/e2e/`).** This is the canonical "how we do e2e" -for this crate (see [Part 7.4](#74-alignment-with-the-existing-e2e-framework)): -gated behind the **`e2e` cargo feature**, funded by the testnet **`bank` wallet** -harness (`framework/bank.rs` — `BankWallet::load`, `fund_address`, -`cross_check_balance`), config via `tests/.env` -(`PLATFORM_WALLET_E2E_BANK_MNEMONIC`), one file per case under -`tests/e2e/cases/_NNN_*.rs` registered in `cases/mod.rs`, run with -`cargo test -p platform-wallet --test e2e --features e2e -- --nocapture`. Add a -**DashPay case family** (proposed prefix `dp_*`), modeled on the shielded `sh_*` -suite (PR #3727) which stacks the same way: - -- **dp_001 (profile):** `create_profile` → fetch from Platform → fields match; - `update_profile` bumps revision. -- **dp_002 (send request):** fund 2 bank-derived identities; A - `send_contact_request(B)`; assert the on-platform `contactRequest` - (`encryptedPublicKey==96B`, key indices, accountReference) + id equality (G2). -- **dp_003 (full cycle — the "done" gate):** A `send_contact_request(B)` → B - recurring-sync sees incoming → B `accept` → **both** established → A - `send_payment(B)` confirms on L1 → B records incoming. -- **dp_004 (offline accept → pay, pins G1+G12):** A sends → B accepts → A offline → - A's **recurring sync** runs → A `send_payment(B)` **succeeds** (external account - built during the sweep). *Must fail before the G1/G12 fix, pass after.* -- **dp_005 (rotation, pins G3):** second `send_contact_request` to the same - recipient with a bumped version is accepted (distinct `accountReference`); the - receive path surfaces the rotation. -- **dp_006 (recurring cadence):** the background recurring sync refreshes - contacts/profiles without an explicit FFI call — including for an identity with - zero watched tokens (assert via the bank harness over a couple of sweeps). -- **dp_006b (foreground-fast cadence + post-mutation kick, §6.4):** entering the - DashPay tab lowers the sweep interval to 4s **and fires one immediate sweep** - (because `set_interval` only applies on the loop's next sleep); leaving the tab - *or backgrounding the app while on it* restores 15s (`setDashPaySyncInterval` - round-trips through the FFI). A send/accept fires an extra `dashPaySyncNow()` - that no-ops when a pass is already in flight. UI-level cadence + the - scenePhase/tab-visibility state machine + the entry kick are covered by a manual - two-sim e2e — these are SwiftUI-lifecycle/wall-clock timing properties the - simulator harness can't assert deterministically; the FFI set-interval/sync-now - round-trip is unit-tested Rust-side. - -### 7.2 Swift — `SwiftTests` + `SwiftExampleAppUITests` - -Unit (`SwiftTests/SwiftDashSDKTests/`): -- `ContactRequest(ffi:)`, `EstablishedContact`, `DashPayProfile(ffi:)` / - `DashPayProfileUpdate` round-trips and marshalling (32-byte id in/out, optional - C-strings, `_free` correctness, no leaks). -- `PersistentDashpay*` SwiftData upsert from the persister callback. - -Flow (mirror the existing `PlatformWalletIntegrationTests.swift` harness, testnet): -- send → sync → accept → established → pay, asserting SwiftData rows + balances. - -XCUITest (`SwiftExampleAppUITests/`, keyed on accessibility ids): -- Open DashPay tab → AddContact by DPNS → request appears in Outgoing → (peer - accepts) → appears in Contacts → open contact → Send Dash → confirm txid. -- Use the `simulator-control` skill for SwiftData inspection + screenshots in UAT. - -### 7.3 "Definition of done" per flow - -| Flow | Done when | -|---|---| -| Create/update profile | `dp_001` + Swift editor XCUITest green; profile visible to peer | -| Send contact request | `dp_002` + G2 (entropy) offline test + AddContact XCUITest green | -| Approve request | `dp_003` accept step → both established; Accept XCUITest green | -| Reject request | local reject unit test green; (M3) `contactInfo` hide syncs across devices | -| Send money to contact | `dp_003` pay step + **`dp_004` (offline accept→pay)** + Send XCUITest green | -| Sync (recurring) | `dp_004`/`dp_006` build external account on the recurring sweep; idempotency unit test green | - -### 7.4 Alignment with the existing e2e framework - -The platform-wallet e2e framework **already exists but is unmerged** — PR -**#3549** (`feat/rs-platform-wallet-e2e`, draft). DashPay e2e cases must be authored -**on that branch** (or rebased onto it after it merges); they are not standalone. -Conventions to follow exactly (from `tests/e2e/README.md`): -- Modeled on `dash-evo-tool/tests/backend-e2e/`; runs against **live Dash testnet** - (v3.0) via DAPI, gated behind the `e2e` cargo feature. -- Funding via the **platform-address `bank` wallet** (seed in - `PLATFORM_WALLET_E2E_BANK_MNEMONIC` / `tests/.env`); most DashPay cases never - touch L1 except the `send_payment` step (which spends Core funds → needs the - bank's Core balance, like CR-003/AL-001). -- Test attribute `#[tokio_shared_rt::test(shared, flavor = "multi_thread", - worker_threads = 12)]`; context provider `TrustedHttpContextProvider`. -- New cases: add `tests/e2e/cases/dp_NNN_*.rs`, register in `cases/mod.rs`, document - in `tests/e2e/TEST_SPEC.md` (pin accounting). The shielded suite (PR #3727, - `sh_*`) is the worked example of stacking a feature-area suite on this framework. - -**Sequencing implication:** the DashPay e2e suite rides #3549 — but **M1's exit -criterion is the mock-seam unit/integration tier** (no #3549 dependency), so M1 is -never blocked on the draft PR. `dp_003`/`dp_004` are the e2e *confirmation* of the -same behaviors, tracked on #3549 (authored stacked on it, or added right after it -merges). The offline crypto/encode tier likewise lands immediately. - ---- - -## Part 8 — Risks, decisions, open questions - -1. **UI shape — first-class tab vs polish-in-place.** Recommended: first-class - `DashPay` tab (Part 6). *Decision owner: product.* Fallback documented. -2. **Cross-client interop. RESOLVED (2026-06-10, desk-check - `INTEROP_DESK_CHECK.md`):** xpub plaintext FAIL → G14 fix in M1 task 7; ECDH PASS; - accountReference PASS-for-now (+2 latent masking bugs noted for M3); new G15 - key-purpose hazard → verification gate in M1 task 8. Live cross-client e2e - stays M4. ⚠ A side-finding: our stack was **not** self-consistent either — - the 107-byte plaintext broke our own send path (see G14). -3. **Watch-only / hardware wallets (G4).** Out of scope for the demo app (it holds - the seed) but required for production. **FFI-hook design lands in M3 (task 15)** - — shared secret only across the ABI, never a raw private key (see G4); - implementation in M4. -4. **`accountReference` semantics (G3).** Decide whether to keep "share full - account xpub, ignore masking" (simpler, but breaks rotation via the unique - index) or implement the DIP-15 masking + version flow. Recommended: implement it - (M3) — rotation is a real user need and the unique-index collision is a latent - bug. -5. **Auto-accept (G7). DECIDED (2026-06-10): keep.** Invitations are now in scope - (Milestone 5) and are built on `autoAcceptProof`, so the helpers + FFI param - stay (dormant until M5 wires them). **Hard requirement when wired:** the - `verify_auto_accept_proof` gate before any automatic acceptance (see G7). -6. **`send_contact_request` entropy (G2). RESOLVED (2026-06-10):** real broadcast - bug — consensus rejected every send (`InvalidDocumentTransitionIdError`). - Fixed in M1 task 4; see the DONE note there. -7. **E2E framework dependency.** The DashPay e2e suite rides PR **#3549** (draft, - unmerged). **M1's exit criterion is the mock-seam tier** (Part 7.4), so M1 never - blocks on it; the `dp_*` cases are authored stacked on #3549 or right after it - merges. *Open: name the owner who decides stack-vs-wait before M1 starts.* - ---- - -## Part 9 — Related in-flight work (open PRs) - -Surfaced from the live PR list — these intersect this plan and should be tracked / -coordinated rather than duplicated: - -| PR | Branch | Relevance | -|----|--------|-----------| -| **#3549** (draft) | `feat/rs-platform-wallet-e2e` | **The e2e framework** the DashPay suite must build on (Part 7.4). | -| **#3727** (draft) | `test/rs-platform-wallet-shielded-e2e` | Shielded `sh_*` e2e suite — the **worked template** for a feature-area suite on #3549. | -| **#3787** | `codex/dashpay-dip15-contact-request-docs` | "DashPay contact request encryption guide" — cross-check against Part 2; avoid doc drift. | -| **#3639** | `feat/platform-wallet-external-signable-wallets` | External/signable wallets — the substrate for **G4** (watch-only ECDH via `ClientSide`). Coordinate before building G4. | -| **#3692** | `feat/platform-wallet-rehydration` | Watch-only rehydration from persistor — touches the same watch-only path as G4. | -| **#3817** | `feature/coinjoin-sweep-and-recovery` | DashSync→SDK migration context (the broader effort DashPay sits inside). | -| **#3750** (NO MERGE) | `feat/platform-wallet-consumer-hardening` | FFI/consumer hardening — may move FFI signatures the Swift layer depends on. | - ---- - -### Appendix — evidence sources - -- [`INTEROP_DESK_CHECK.md`](./INTEROP_DESK_CHECK.md) — - cross-client (iOS DashSync / Android dashj) interop evidence + testnet census. -- [`CONTACTINFO_FORMAT_SPEC.md` Appendix A](./CONTACTINFO_FORMAT_SPEC.md) — - contactInfo wire conventions (this repo sets the de-facto convention). - -The transient working-research files (DIP paraphrase, SDK/contract survey with -worktree-relative file:line citations) were trimmed from the tree; find them in -this branch's git history under `docs/dashpay/research/`. diff --git a/docs/dashpay/SYNC_CORRECTNESS_SPEC.md b/docs/dashpay/SYNC_CORRECTNESS_SPEC.md deleted file mode 100644 index 4b8ab6b4a87..00000000000 --- a/docs/dashpay/SYNC_CORRECTNESS_SPEC.md +++ /dev/null @@ -1,441 +0,0 @@ -# DashPay sync correctness — contact requests **and** profiles (mirror Android `PlatformSyncService`) - -Status: **IMPLEMENTED (2026-06-18)** — both stages shipped on -`feat/dashpay-m1-sync-correctness` (PR #3841), 5-lens review (§9) folded in first. -Stage 1 = paginated retrieve-all + per-identity high-water cursor + 10-min overlap -at a 15s cadence (`network/contact_requests.rs`); stage 2 = id-keyed -`contact_profiles` cache for established + pending senders (`network/contact_info.rs`, -`accessors.rs`). Both are surfaced in the UI and **durably persisted** through the -changeset pipeline to *both* backends (SQLite persister + SwiftData); the high-water -cursor stays in-memory by design (a cold restore does one safe full re-fetch). -Owner: rs-sdk / platform-wallet -Priority: **FIRST** of the DashPay correctness track (ahead of the contactInfo -format migration and the ignore feature). - -This spec covers **two consecutive stages of the same Android sync loop**: - -| Stage | Android (`PlatformSyncService`) | Us before | Delivered | -|-------|--------------------------------|-----------|-----------| -| 1. Contact-request fetch | `updateContactRequests()` — incremental, paginated, high-water | present but **broken** (truncated at 100, no high-water) | **fixed** — retrieve-all + high-water cursor | -| 2. Contact-profile fetch | `updateContactProfiles(userIds)` — batch `whereIn $ownerId` | **absent** (synced only our *own* profile) | **added** — id-keyed cache, established + pending senders | - -Neither is an optimization: stage 1 is a **correctness bug** (real requests are -permanently buried) and stage 2 is a **missing feature** (contacts have no name -or avatar in the UI). The Android wallet (`dash-wallet`, on `kotlin-platform`) -already does both; this spec mirrors that proven design. Delivered as **two -commits** (stage 1, then stage 2) on one branch. - ---- - -## 1. Problem - -### 1.1 Stage 1 — our contact-request fetch is wrong, not just slow - -`packages/rs-sdk/src/platform/dashpay/contact_request_queries.rs`: - -```rust -where toUserId == me, order_by $createdAt, limit: 100, start: None -``` - -`start: None` + a fixed `limit: 100`, re-run every sweep: - -- **Re-fetches the first page from the beginning every sweep** — pays the full - fetch + GroveDB proof-verify each time for data we already have. -- **Truncates at 100 and never paginates** — with ≥100 requests, newer (or, by - `$createdAt asc`, older) legitimate requests are **never fetched**. A spammer - (or a popular identity) **buries real requests permanently**. -- **No durable high-water / cursor** — no notion of "what's new since last sweep". - -### 1.2 Stage 2 — contact-profile sync is entirely absent - -`packages/rs-platform-wallet/.../network/profile.rs::sync_profiles` runs over -`identity_manager.all_identities()` — only **managed** identities (our own), -never contacts (`manager/accessors.rs:54`). So we publish and refresh **our own** -profile but **never fetch a contact's** displayName / avatar / publicMessage. The -UI shows only a raw identity id (or a local alias). Neither `EstablishedContact` -nor any incoming-request sender has a cached profile anywhere. - -## 2. The reference — Android `PlatformSyncService` - -Verified 2026-06 against `github.com/dashpay/dash-wallet` + -`github.com/dashpay/kotlin-platform` (the current JVM platform lib, -`org.dashj.platform:dash-sdk-*`; **not** the stale `android-dashpay`). One -re-entrancy-guarded ticker (`TickerFlow(15.seconds)`) runs, in order: - -``` -updateContactRequests() // stage 1: incremental, paginated, high-water - → discovers userIds (contacts + pending senders) -updateContactProfiles(userIds) // stage 2: batch whereIn $ownerId, cache by userId -checkDatabaseIntegrity()/FixMissingProfiles() // self-heal missing profiles -``` - -- Stage 1 high-water: `SELECT MAX(timestamp)` per direction; **10-min overlap - rewind**; incremental `$createdAt > afterTime` + `startAfter` cursor + - `limit(-1)` = retrieve-all. -- Stage 2 fetches profiles for the userIds drawn from contact-request rows - (**including pending incoming senders** — that's how the request UI shows a - requester's name/avatar), keyed in a `dashpay_profile` table by `userId`, - independent of relationship state. - -## 3. Goal - -1. Make our **contact-request** sync incremental, fully-paginated, - high-water-tracked, and skew-safe, for **both** directions — no truncation, - each request fetched ~once, a flood can't bury anything. -2. Add **contact-profile** sync: fetch established contacts' **and pending - incoming senders'** profiles in batches, cache them (id-keyed) so the UI shows - name + avatar on both the contacts and the requests screens, refresh, and - self-heal any missing profile without unbounded re-querying. - -## 4. Design - -### 4.1 High-water cursor (stage 1) - -**Storage (resolves Q-a).** Android keeps every contact-request row and derives -`MAX(timestamp)`. Our model collapses requests, so we can't `MAX()` a raw table. -We persist **two scalar fields on `ManagedIdentity`** — `high_water_received_ms: -Option` and `high_water_sent_ms: Option` — riding the existing -`IdentityEntry` snapshot (changeset → both persisters → FFI restore), **not** a -separate table. Two integers per identity need no relational shape. - -**The advance invariant (the heart of stage-1 correctness).** Get this wrong and -we reintroduce the burying bug. The cursor: - -1. **Advances only on a fully-exhausted, error-free paginate** of that direction. - "Exhausted" = a page returned `< limit` docs (possibly empty); a final page of - exactly `limit` requires one more fetch to confirm. **Any** fetch/proof error - mid-loop ⇒ **do not advance that direction's cursor this sweep** (leave it at - the prior value; the overlap re-fetches next sweep). -2. **Advances to `max($createdAt)` over every doc *fetched* this sweep** — - *including* docs that ingest then parse-skips, collapses - (`newest_received_per_sender`), or suppresses (ignore/tombstone). The cursor - records **fetch-completeness, not ingest-success**. Ignore `unwrap_or(0)` - sentinels: advance to the max of *present* (`Some`) timestamps only, and never - below the current value. -3. **Never stamps to wall-clock `now`.** On a zero-doc fetch the cursor is left - unchanged. States: `Absent` ⇒ query `$createdAt > 0` (full); `Present(t)` ⇒ - query `$createdAt > (t − OVERLAP_MS)`. - -**Why cursor-loss is safe (the written contract):** every collapsed / suppressed -doc is, by construction, deterministically reproducible from a full re-fetch of -the immutable on-chain set. So **under-shoot is free** (a lost/low cursor just -triggers one full re-fetch; ingest is a fixpoint) and **over-shoot buries**. -Therefore **restore tolerates only under-shoot**: on any restore-consistency -doubt, clamp the cursor to `min(persisted, max($createdAt) over restored contact -rows)`, or reset to `0`. A restored-too-high cursor is a correctness bug. - -**`OVERLAP_MS` is correctness-load-bearing, not cosmetic.** The lower bound is -exclusive (`>`) and the `userIdCreatedAt` index is non-unique on `$createdAt`, so -multiple requests can share a `$createdAt` at a page boundary. The overlap is -what re-includes them; **`OVERLAP_MS = 0` is an invalid configuration**, not a -tuning knob. Default `10 * 60_000` (copy Android). - -### 4.2 The request query (rs-sdk, stage 1) - -`fetch_received_contact_requests` / `fetch_sent_contact_requests` gain -`after_created_at: Option` + cursor pagination: - -```rust -where: [ toUserId == me, $createdAt > (high_water − OVERLAP_MS) ] -order_by: $createdAt asc // REQUIRED — binds the userIdCreatedAt index and - // avoids the "verified-absent" proof trap -start: StartAfter(last_doc_id) // ephemeral, per-loop pagination cursor -``` - -Two distinct cursors, do not conflate: within-sweep pagination uses -`Start::StartAfter(last_document_id)` (a 32-byte doc id, per-loop); the **durable -high-water** persists `max($createdAt)` (cross-sweep, §4.1). Loop pages until -exhausted (§4.1 rule 1). **Precondition (Q-c, stage 1):** before replacing the -working `limit:100` query, verify on testnet that the paginated `$createdAt > t` -+ `StartAfter` form returns a known existing doc (not a verified-absent empty -proof) — the current query's `order_by` comment documents this exact trap. - -### 4.3 Request sweep flow (platform-wallet `sync_contact_requests`) - -1. Read `high_water_received` / `high_water_sent` (Absent ⇒ full). -2. Fetch received `> (hw_received − OVERLAP)`, paginated; fetch sent likewise. -3. Ingest via the existing path — `newest_received_per_sender` collapse, ignore - suppression, auto-establish. **Idempotency is load-bearing**: the overlap - re-delivers seen docs every sweep, so ingest MUST be a fixpoint (it is). -4. **Per direction, iff its paginate exhausted without error** (§4.1 rule 1): - advance the cursor to the max `$createdAt` *fetched* this sweep (§4.1 rule 2). - On any error, skip the advance for that direction. - -### 4.4 Contact-profile fetch (rs-sdk + platform-wallet, stage 2) - -**Query (resolves Q-c stage 2 + Q-cap).** New `fetch_profiles_for(owner_ids)`: - -```rust -where: [ $ownerId In [id0, id1, …] ] // ≤ IN_CAP ids per query -order_by: [] // EMPTY — unique ownerId index, no trap -start: None // each owner yields ≤1 profile; no pagination -``` - -The `profile` doctype has a **unique single-property `ownerId` index**, so an -`In $ownerId` set lookup proves presence/absence cleanly with **empty -`order_by`** and **no pagination** (mirrors the working `profile.rs` point query, -Equal→In). `IN_CAP = 100` is a **hard cap** enforced at query-build -(`rs-drive/src/query/conditions.rs:361`); the `In` array **rejects duplicates** -(`:368`) and **rejects empty** (`:355`). So the caller **dedups** the id set and -**skips** the query entirely when a chunk (or the whole target set) is empty. - -**Target set (resolves the §4.3-vs-§4.4 contradiction): iterate the FULL set -every sweep, not "touched ids".** Each sweep, collect: -`{ established_contacts[].contact_identity_id } ∪ { incoming_contact_requests[].sender }` -across managed identities, **dedup**, and **skip ids that are themselves managed -identities on this wallet** (their profile is their own `dashpay_profile`, which -is authoritative — see §4.7). The stage-1 "touched this sweep" set is at most a -*fetch-these-first hint*, never the iteration set — the existing aggregator -discards `sync_contact_requests`'s return value anyway, and a "touched-only" set -would break both self-heal and first-run backfill (every pre-existing contact is -uncached but untouched). - -**Filter, then chunk, then fetch:** - -1. Drop ids that are **cached and fresh**, and ids that are **confirmed-absent - and checked recently** (negative cache, see below). What remains is the fetch - set — on first run after upgrade this is *every* contact (the dominant, - expected first-sweep cost; bounded by contact count). -2. Chunk the remaining ids into groups of `IN_CAP`, run one `In` query per chunk. -3. **Per-chunk log-and-continue isolation:** a chunk's fetch/proof failure logs - and continues to the next chunk; the freshness/checked markers advance **only - for ids in successfully-fetched chunks**, never sweep-wide on partial failure. - A persistently-failing chunk must not starve the others. - -**Self-heal & the no-profile negative cache.** A contact may have **no `profile` -document on-platform** (profiles are optional). The `In` query simply omits them. -Without a guard, "cached? false" stays true forever and they're re-queried every -sweep — the unbounded-retry pathology `payment_channel_broken` (G1c) exists to -avoid. So record a **confirmed-absent marker with a checked-at timestamp**; the -fetch set targets "no cached profile **and** not checked within the backoff -window". Self-heal then *is* the normal path (an uncached/expired contact re-enters -the fetch set) — no separate `FixMissingProfiles` loop. - -### 4.5 Profile storage — **Option B** (id-keyed cache) - -A new map on `ManagedIdentity`: - -```rust -pub contact_profiles: BTreeMap, -// ContactProfileEntry = { profile: Option, checked_at_ms: u64 } -// profile: Some(..) = fetched & present; None = confirmed-absent (negative cache) -// checked_at_ms: last fetch attempt, drives the self-heal backoff -``` - -Chosen over a field on `EstablishedContact` because the cache must serve **every -relationship state** — established contacts, **pending incoming-request senders** -(requests screen), and **ignored senders** (future Ignored list) — none of which -share one struct. This is the product decision (§4.6) and matches Android's -relationship-independent `dashpay_profile` table. Plumbing (the `dashpay_payments` -5-site pattern; **the two most-forgotten are the merge rule and the store-side -apply** — miss either and contacts silently vanish on relaunch): - -1. field on `ManagedIdentity`; -2. `IdentityEntry` field + `from_managed` (`changeset.rs`); -3. **merge rule** in `IdentityChangeSet::merge` — per-key last-write-wins (the - `dashpay_payments` merge at `changeset.rs:489-495` is the template); -4. FFI: a **contact-keyed** accessor (distinct from the existing identity-keyed - own-profile one), e.g. `platform_wallet_get_contact_profile(wallet, - owner_identity_id, contact_identity_id) -> profile?`, + an - `IdentityRestoreEntryFFI` field + `restore_contact_profiles` fn - (mirror `restore_dashpay_payments`, `persistence.rs`); -5. SwiftData `PersistentDashpayProfile` keyed by `(ownerId, contactId)` (mirror - `PersistentDashpayPayment`) + the **store-side write/apply**. - -**Boundary invariant:** `contact_profiles` holds **only the five public profile -fields** parsed from the on-chain `profile` document. It must never receive any -field derived from the encrypted `contactInfo.privateData` path (which carries -private relationship state — alias/note/hidden/ignore). Keep these two stores -distinct so the contactInfo migration (Spec 1) can't accidentally cross them. - -### 4.6 Scope & privacy - -**Scope (product decision): established contacts + pending incoming-request -senders now; ignored senders ride the same cache when the Ignored list lands.** -This matches Android's observable behavior (requester names in the request UI). - -**Privacy posture (resolves Q-scope).** Fetching a *pending* sender's profile is a -public read, but issuing `whereIn $ownerId [sender_ids]` right after their -requests land is a query-pattern an observer could correlate with your inbound -set. We **accept** this because the marginal leak is small: the contact-request -documents are *already public* (indexed by `[toUserId, $createdAt]`), and the -DAPI node serving our `toUserId == me` request query — which we must run — -**already learns the entire inbound set**. Fetching those public profiles adds -little. This is materially weaker than the R1 leak (which *creates a new on-chain -document* about a non-contact). Documented and accepted; the R1 track may later -minimize query-pattern metadata if desired. - -### 4.7 Cache write semantics - -- **Full-REPLACE, not merge.** A fetched profile document is the authoritative - *complete* state for that owner; storing it **overwrites** the cached entry via - `profile_from_properties` (full parse). This is the **opposite** of the - own-profile *update* path (`merge_profile_properties`, read-modify-write) — do - **not** reuse that helper here, or a contact who *removes* `avatarUrl` would - keep showing a stale avatar forever. -- **All-empty parse ⇒ confirmed-absent, not cached-present.** A doc that parses to - an all-`None` profile is treated as a negative-cache hit (§4.4), not a fresh - empty profile, so self-heal keeps it honest. -- **Persist only on change.** Compare the fetched profile to the cached one before - writing; emit no changeset when unchanged. This keeps the deferred-Q-inc - "refetch-all each sweep" first cut a **persistence fixpoint** — no write - amplification, the same discipline stage 1 enforces. -- **`avatarUrl` validation at insert.** Validate before caching: **`https://` - scheme only**, length-capped (state the contract's max). Treat the cached url as - **untrusted** input downstream — it is attacker-controlled and the UI will load - it (an unsanitized `http:`/`file:`/`javascript:` url is an SSRF / tracking-pixel - vector; a tracking url tied to your IP confirms "you have this contact"). -- **own-vs-contact authority.** If a target id is itself a managed identity on this - wallet, skip the contact fetch; that identity's own `dashpay_profile` wins. - -### 4.8 Driver wiring (`dashpay_sync.rs`) - -Add `sync_contact_profiles()` as a **distinct** step **between** the existing -`sync_profiles()` (own identities) and `sync_contact_infos()`. It is -**log-and-continue, not error-returning** (matches `sync_contact_infos` / -`reconcile_incoming_payments`): a contact-profile fetch failure degrades *display* -only and must never change the sweep's pass/fail outcome. **Do not** fold it into -`sync_profiles` — that function is scoped to `all_identities()` (own) and writes a -different store. Ordering: it must run **after** `sync_contact_requests` so a -contact established this sweep is fetched the same tick. - -### 4.9 Interactions (specify, don't discover) - -- **Un-ignore resync (deferred to the ignore refactor, but constrained here):** - un-ignore must re-fetch the un-ignored sender's requests. The - ignore/reject tombstone is keyed by `(sender, accountReference)` and **does not - store `$createdAt`**, so a *precise* "rewind the cursor past their `$createdAt`" - is **not implementable from the tombstone alone**. Therefore: **un-ignore ⇒ - clear (reset to Absent) the received cursor** → one full re-fetch (cheap, safe - per §4.1). If a targeted rewind is ever wanted, add `$createdAt` to the tombstone - first. The ignore work owns the call site; this is the mechanism constraint. -- **contactInfo-before-contactRequests ordering:** DIP-15 says fetch contactInfo - first (so contacts don't flicker on `displayHidden`). Out of scope here; noted. -- **Cursor as at-rest metadata:** the high-water timestamps are derived from public - on-chain `$createdAt`, but they are a session-activity residue at rest — exclude - the cursor (and the whole DashPay store) from iCloud backup, since a device-local - ignore/blocklist and activity residue should not sync to backup. - -## 5. Non-goals - -- Changing the sweep cadence. -- The **account** half of `checkDatabaseIntegrity` (we already rebuild contact - accounts) — only the **profile** half is in scope (§4.4 self-heal). -- **Avatar image bytes / rendering** — we cache the fields (`avatarUrl` + - hashes); downloading/showing the image is app-layer (but the url is validated - at cache insert, §4.7). -- **Per-profile `$updatedAt`-incremental refetch (Q-inc).** The composite - `$ownerId In […] AND $updatedAt > marker` is **not provable in one query** (an - `In` on the first index field plus a range on the second isn't a contiguous - index range). The first cut refetches all contact profiles each sweep (bounded - by contact count, and a persistence fixpoint per §4.7); a real incremental would - be per-owner equality (loses the batch) or client-side staleness — a follow-up. - -## 6. Implementation surface - -**Stage 1 (commit 1):** -- `rs-sdk/.../dashpay/contact_request_queries.rs` — `after_created_at` + the - `StartAfter(doc_id)` pagination loop; drop `limit:100, start:None`. -- `platform-wallet/.../network/contact_requests.rs::sync_contact_requests` — - read/advance cursors per §4.1/§4.3 (advance gated on exhaustion + no error). -- `ManagedIdentity` gains `high_water_received_ms` / `high_water_sent_ms` - (`Option`) + `IdentityEntry` + merge + both persisters + FFI restore. - -**Stage 2 (commit 2):** -- `rs-sdk/.../dashpay/` — `fetch_profiles_for(owner_ids)` (empty `order_by`, `In`, - dedup, chunk at `IN_CAP=100`, skip-empty). -- `platform-wallet/.../network/profile.rs` — `sync_contact_profiles` (full-set - target, negative cache, per-chunk isolation, full-replace, persist-on-change, - `avatarUrl` validation); reuse `profile_from_properties`. -- `ManagedIdentity.contact_profiles` + the 5 plumbing sites (§4.5), incl. the - contact-keyed FFI accessor + `PersistentDashpayProfile` SwiftData model. -- `dashpay_sync.rs` — wire `sync_contact_profiles` per §4.8. -- UI bind in the **real** consumers: `Views/DashPay/ContactsView.swift` (list - row name/avatar), `ContactDetailView.swift` (header), `ContactRequestsView.swift` - (requester name/avatar), via the existing `DashPayContactMeta` / `DashPayProfileView`. - (There is **no** `FriendsView`.) - -## 7. Test plan - -**Stage 1:** -- **Incremental:** two sweeps; second issues `$createdAt > hw` and ingests only the - delta (no re-fetch beyond the overlap). -- **No-bury:** 150 requests → all eventually fetched via pagination. -- **Equal-timestamp page boundary:** N>limit requests sharing one `$createdAt` - straddling a page cut → all eventually ingested (pins the overlap as - correctness, not just skew). -- **Partial-page failure:** inject a page-2 error → the cursor does **not** advance - and the next sweep re-fetches from the old high-water. -- **Collapsed-doc reachability:** after a cursor wipe, an older-ref doc that was - collapsed away reappears (proves cursor-loss safety / under-shoot). -- **Restore over-shoot guard:** a restored cursor higher than the restored contact - rows still re-fetches the missing contacts (over-shoot clamped to under-shoot). -- **Idempotency:** overlap re-delivery creates no phantom rows / duplicate writes. - -**Stage 2:** -- **Batch/chunk + dedup:** N>IN_CAP contacts (with a duplicate id) → ⌈N/IN_CAP⌉ - chunked queries, deduped, all cached. -- **First-run backfill:** a wallet restored with M established contacts and zero - cached profiles fetches all M on the first sweep even though stage 1 ingests no - new request. -- **Pending-sender profile:** a pending incoming-request sender's profile is - fetched and reachable via the contact-keyed FFI accessor. -- **No-profile negative cache:** a contact with no on-platform profile is fetched - at most once per backoff window, not every sweep. -- **Chunk isolation:** chunk 2 of 3 fails → chunks 1 & 3 cache, chunk 2's contacts - retried next sweep (not marked done). -- **Shrinking profile (full-replace):** cache a full profile, then ingest a doc - missing `avatarUrl` → cached `avatar_url` becomes `None`. -- **Persist-on-change fixpoint:** a steady-state sweep with unchanged profiles - writes zero changesets. -- **avatarUrl validation:** a profile with a non-`https` url is rejected/sanitized - at cache insert. -- **own-vs-contact:** a contact that is also a managed identity resolves to the - own `dashpay_profile`, not a duplicate contact fetch. -- **Round-trip:** a contact profile survives relaunch (changeset → persister → - restore), like `dashpay_payments`. - -## 8. Open questions (most resolved by the review) - -- **Resolved — Q-a** (cursor storage): two scalar `Option` fields on - `ManagedIdentity` (not a table). -- **Resolved — Q-store:** Option B (id-keyed `contact_profiles`), per the - product decision (§4.5/§4.6). -- **Resolved — Q-scope:** established + pending senders; privacy accepted (§4.6). -- **Resolved — Q-c:** stage-1 keeps `order_by $createdAt`; stage-2 uses empty - `order_by` on the unique `ownerId` index, no pagination. (Stage-1 paginated - form still needs the one-time testnet proof check, §4.2.) -- **Resolved — Q-cap:** `IN_CAP = 100`, dedup, skip-empty. -- **Resolved — Q-inc:** not provable as a single batch query; deferred (§5). -- **Open — Q-b:** `OVERLAP_MS = 10 min` (copy Android) — keep, but confirm it - comfortably exceeds observed platform time-skew; **must stay > 0** (§4.1). -- **Open — Q-backoff:** the no-profile negative-cache recheck interval (§4.4) — - propose "once per N sweeps" or a wall-clock window; pick during impl. -- **Open — Q-checked-clock:** the `checked_at_ms` backoff may use wall-clock - (acceptable — it gates re-query cost, not cursor correctness) vs a sweep - counter; decide during impl. - -## 9. Review resolutions (traceability) - -Folded in from the 5-lens review (feasibility / scope / adversarial / security / -flow). The load-bearing changes vs the first draft: - -- **Cursor advance invariant rewritten** (§4.1) — advance only on error-free - *exhausted* pagination, over docs *fetched* (not *applied*), never wall-clock, - under-shoot-only on restore, overlap mandatory. Closes the two CRITICAL burying - holes (advance-past-failed-page, advance-past-collapsed-doc). -- **Cursor storage simplified** to two scalar fields, not a table (Q-a). -- **Stage-2 query shape resolved from the contract indices** (§4.4) — unique - `ownerId` index ⇒ empty `order_by`, no pagination, `IN_CAP=100`, dedup, - skip-empty (Q-c, Q-cap). Q-inc shown unprovable as a batch. -- **Stage-2 negative cache + per-chunk isolation + full-replace + - persist-on-change** added (§4.4/§4.7) — closes infinite-refetch, partial-failure - starvation, stale-field, and write-amplification holes. -- **Target set = full set (established + pending), every sweep** (§4.4) — closes - the §4.3-vs-§4.4 contradiction and the first-run-backfill gap. -- **Storage = Option B** with the full 5-site plumbing called out (merge rule + - store-apply emphasized), public-data boundary (§4.5). -- **avatarUrl validation** + **privacy posture for pending-sender fetch** (§4.6/4.7). -- **Driver hook pinned** as a distinct log-and-continue step (§4.8); **UI surface - corrected** to the real views (no `FriendsView`). -- **Un-ignore = clear-cursor** because the tombstone lacks `$createdAt` (§4.9). diff --git a/docs/sdk/CODE_REVIEW_NOTES.md b/docs/sdk/CODE_REVIEW_NOTES.md deleted file mode 100644 index af6f1b20b0f..00000000000 --- a/docs/sdk/CODE_REVIEW_NOTES.md +++ /dev/null @@ -1,214 +0,0 @@ -# Final multi-agent code review: Kotlin DashPay registration keys - -**Review date:** 2026-07-21 -**Branch:** `feat/kotlin-sdk-dashpay-registration-keys` -**Implementation base:** `6efa83bb53` -**Reviewed implementation commits:** `70b0852edb`, `3a64940af8`, -`c31ca592d4`, `4a25717471`, plus the concurrently-added persistence refactor -`5147d5baa9` - -## Review method - -Three independent agents reviewed the actual diff and call graph under separate -lenses, followed by a primary-agent source audit and full build/test run: - -1. Rust wire format, registration invariants, FFI callers, and consensus-facing - key policy. -2. Kotlin derivation/persistence/zeroization lifecycle, funding policy, resume - exclusion, and the helper-reuse decision. -3. Cross-language fixture and edge-case test adequacy, including the invitation - caller and environment-bound on-chain assertion. - -The agents were instructed to review only and made no edits or commits. While -the review was running, `5147d5baa9` was committed by an external concurrent -session; it was reviewed as part of the resulting branch head and was not -rewritten. - -## Verified correct in the implementation - -- `parse_pubkey_rows` is a pure `&[u8]` parser. JNI conversion is confined to - thin update/registration adapters. -- Empty-list, duplicate-key-ID, and key-ID-0 = MASTER + AUTHENTICATION checks - are registration-only. The shared update parser still accepts ordinary - add-key lists without key ID 0. -- All four Android registration JNI exports use the rich registration decoder: - resume, Core-funded, Platform-address-funded, and shielded-from-pool. -- The fifth `decode_identity_pubkeys` caller, invitation claim, still uses the - shared FFI decoder and therefore receives duplicate-ID rejection without - receiving the JNI-only key-ID-0 policy. -- `role_for_registration_key_id` and `decode_pubkeys_blob` are deleted, not - merely superseded. -- Kotlin explicitly rebuilds the base roles as MASTER/AUTHENTICATION, - CRITICAL/AUTHENTICATION, HIGH/AUTHENTICATION, and CRITICAL/TRANSFER. -- Keys 4/5 are ECDSA secp256k1, ENCRYPTION/DECRYPTION, MEDIUM, writable, and - bounded to the canonical DashPay contract's `contactRequest` document type. -- Fresh registration performs one six-key derivation pass. It does not derive - an overlapping base-four set first. -- Resume derives and submits only the base four keys. The DashPay pair is not - added to an already-funded asset-lock resume. -- The checked-in golden binary is genuinely shared: Kotlin compares its encoder - output to that exact resource, while Rust includes and decodes the same file - and pins its contract ID to `dashpay_contract::ID_BYTES`. -- Strict codec coverage includes truncation, legacy layout, trailing bytes, - invalid bounds/boolean bytes, negative IDs, interior NUL, duplicate IDs, and - update-without-key-0 behavior. FFI tests cover invalid DPP role bytes. - -## Findings fixed during this review - -### 1. Private material survived two failure windows - -`IdentityKeyPreview.decodeAll` wiped the JNI blob only after a complete parse. -A malformed/truncated blob could leave both the source blob and already-copied -private scalars unsanitized. Separately, a blocking JNI preview could finish -after its coroutine was cancelled; `withContext` would then discard the -secret-bearing result before the caller reached provisioning cleanup. - -Fix: - -- Decode under `try/catch/finally`, wiping the source blob on every exit and - wiping all partially decoded private arrays on failure. -- Add `opWithCleanupOnCancellation`, which scrubs a completed result if prompt - cancellation discards it during dispatcher handoff. -- Route both registration preview APIs through that cleanup-aware gate. -- Add malformed-blob and blocking-JNI cancellation regressions. Both tests were - observed failing before the production fix and passing afterward. - -### 2. Six-key Core funding minimum was not enforced - -The app accepted any numeric Core amount even though six creation keys raise -the protocol floor from 228,000 to 241,000 duffs. A below-floor asset lock can -be broadcast before Platform rejects the identity create. - -Fix: - -- Mirror `IdentityCreateTransition::calculate_min_required_fee_v1` for the - current key count. -- Use one amount-policy function for both submit enablement and the click-time - preflight. -- Add boundary tests for the four-key/six-key floors and the resume no-new-funds - case. The new test was observed failing before the implementation and passing - afterward. - -### 3. Invitation claim lacked its required caller-level regression - -The existing duplicate-ID unit test called `decode_identity_pubkeys` directly -and only stated in a comment that invitation claim used it. It did not exercise -the fifth caller itself. - -Fix: - -- Add a valid-invitation/duplicate-row test through - `platform_wallet_claim_invitation`. -- Assert duplicate rejection happens before wallet lookup, signer use, or - network work, and that output sentinels remain zeroed. - -### 4. Coverage and documentation were weaker than the implementation claims - -Fix: - -- Correct the Rust module documentation: the pure structural parser does not - validate DPP role discriminants; the downstream FFI conversion does. -- Add direct invalid key-type/purpose/security-level FFI coverage and a - MASTER-with-wrong-purpose registration invariant test. -- Strengthen Kotlin tests to prove the exact public-key storage key, non-zero - scalar at persistence time, wallet ownership, post-persist scrubbing, - DashPay key type/purpose/security/read-only flags, and exact bounds. -- Correct the helper rationale: the add-key flow persists before broadcast; - the real incompatibilities are its existing-key/max+1 update policy and - per-slot derivation, versus registration's fixed 0..N batch policy. - -## PR #4173 automated-review follow-up - -The first automated PR review found three additional blocking regressions. All -three were independently traced to the current source and fixed: - -1. **Mutable controls could redirect an in-flight registration.** The click - handler captured the key-count choice before suspension but later reread - `fundingSource` and `selectedRecoveryLock`. It now resolves source, amount, - identity index, and a defensive copy of the selected lock into one immutable - submission snapshot before the coroutine starts. Preparation, dispatch, - coordinator tracking, and navigation use only that snapshot. A regression - mutates the backing form values and lock txid after capture and verifies the - submission is unchanged. -2. **Platform-address packing did not reserve the six-key creation fee.** The - default native strategy deducts the fee from the post-spend remainder of - BTreeMap input 0. The packer now mirrors the consensus formula - `2,000,000 + 6,500,000 * keyCount + 500,000 * inputCount`, models Rust's - `(address type, unsigned hash)` ordering, and selects the smallest input set - that contributes the requested identity balance while leaving the full fee - on input 0. This preflight runs before key derivation/persistence. The - reviewer's 70M-balance/30M-spend case was observed failing before the fix; - exact one-input and two-input boundaries are also covered. -3. **Resume lost its HD-slot provenance check.** Rich consensus rows do not - carry a derivation index, so replacing `IdentityKeyPreview` had deleted the - old per-key guard. Provisioning now returns a `RegistrationKeySet` that keeps - the common preview identity index beside the rich rows, rejects mixed-slot - previews before persistence, and resume verifies the set index matches the - tracked lock before JNI. The wrong-slot regression was observed calling JNI - before the fix and passing afterward. - -The full Kotlin SDK/app build, unit-test suites, and instrumented-test-source -compilation passed after these fixes. The PR's initial emulator check hit the -workflow's documented Android Keystore unlock-state race; its failed-job rerun -passed the complete native build and API-35 instrumented suite without a code or -workflow change. - -## Left for human judgment or environment-bound verification - -1. **On-chain bounds assertion is still manual.** No unit test can prove what a - testnet node persisted. Register a fresh identity, fetch it, and assert keys - 4/5 contain the exact DashPay contract ID plus `contactRequest` bounds. Then - run Add Contact as a separate smoke test; Add Contact success alone is not - proof of the bounds. -2. **Public Kotlin/logical wire compatibility.** Public fresh-registration - methods now consume rich `IdentityPubkey` lists, resume consumes a - provenance-carrying `RegistrationKeySet`, and the opaque `byte[]` layout - changed without a version/magic prefix. The parser fails closed on - legacy/malformed shapes, but an old Kotlin artifact must not be paired with - the new native library. Release coordination or an explicit compatibility - layer remains a product/API decision. -3. **No full Compose four-way dispatch seam test.** Static tracing confirms all - three fresh paths pass the same six-row list and resume passes the four-row - list; policy tests cover the funding-source gate and immutable submission - snapshot. Extracting a larger pure screen-dispatch seam solely for - orchestration testing is a maintainability choice, not a discovered - production defect. -4. **Kotlin still trusts Rust's preview row keypair correspondence.** Swift - independently revalidates private/public correspondence. Kotlin documents - why it does not duplicate private-key math; whether to add an equivalent - native validation surface remains a parity-hardening decision. -5. **No existing-identity backfill.** Already-created Android identities still - need the Add Identity Key flow. This remains the reviewed non-goal. -6. **Dedicated provisioning helper.** Keeping `DashpayKeyProvisioning` is - justified by the fixed registration IDs and one batch derivation. Commit - `5147d5baa9` shares the dangerous persist-and-scrub primitive with - `IdentityKeyAdditionFlow`, avoiding lifecycle duplication while preserving - the distinct policies. - -## Verification results - -All required local verification passed: - -```text -cargo test -p rs-unified-sdk-jni --lib - 29 passed - -cargo test -p platform-wallet-ffi --lib - 201 passed - -env RUSTC_WRAPPER= cargo clippy --workspace --all-features - passed (the configured sccache was not permitted in the sandbox) - -cargo fmt --check --all - passed - -JAVA_HOME=/opt/homebrew/opt/openjdk@17 \ -ANDROID_HOME=/opt/homebrew/share/android-commandlinetools \ -./gradlew :sdk:assembleDebug :sdk:testDebugUnitTest \ - :app:assembleDebug :app:testDebugUnitTest \ - :sdk:compileDebugAndroidTestKotlin - passed -``` - -Testnet/device registration, the on-chain bounds assertion, and Add Contact -were intentionally not attempted because they are environment-bound. diff --git a/docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md b/docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md deleted file mode 100644 index 25aed864dd6..00000000000 --- a/docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md +++ /dev/null @@ -1,705 +0,0 @@ -# Kotlin/Swift SDK parity and shared-logic consolidation - -**Status:** REVIEWED v2 — approved after Swift/Rust FFI, Android/JNI/Room, and -adversarial architecture reviews -**Baseline:** PR #3999, `feat/kotlin-sdk-and-example-app` at -`6dbc72a54df72d26eb9c4a014b425d2b95134e4e` -**Scope:** `rs-platform-wallet`, `rs-platform-wallet-ffi`, `rs-unified-sdk-jni`, -`swift-sdk`, `kotlin-sdk`, SwiftExampleApp, and KotlinExampleApp -**Related specifications:** `docs/dashpay/DIP15_INVITATIONS_SPEC.md`, -`docs/dashpay/KOTLIN_MIGRATION_SPEC.md`, -`docs/dashpay/KOTLIN_MIGRATION_FOLLOWUPS_SPEC.md`, and -`docs/dashpay/PENDING_CONTACT_CRYPTO_RELOCATION_SPEC.md` - -**Implementation state on this branch:** partial, not release-complete. The -release-blocker slices are implemented at source/test level, but the executable -manifest remains authoritative for unclosed device, process-restart, and legacy -store gates. Android invitations and the S1–S4 shared-policy moves are explicitly -permitted follow-ups; this commit must not be presented as completing those later -slices. - ---- - -## 1. Problem - -PR #3999 establishes an Android/Kotlin SDK and ports SwiftExampleApp. The port is -large enough that file- or screen-count parity is no longer a reliable correctness -measure. Review found three kinds of drift: - -1. Host persistence callbacks do not implement the same Rust persistence contract. - Some Android omissions disable shared features; one Android callback writes - incorrect authoritative data. -2. Protocol or wallet policy is duplicated in Kotlin and Swift even when Rust - already owns, or should own, the rule. The copies have started to diverge. -3. The parity document records source-file presence rather than executable feature - capability, restart behavior, and protocol-domain coverage. - -The goal is not literal host-code equality. Kotlin/Swift UI, lifecycle, secure -storage, and database adapters remain platform-native. The goal is one shared -implementation of protocol/wallet decisions and equivalent host persistence, -recovery, and example-app capability. - -### 1.1 Baseline and already-integrated work - -Implementation starts from exact PR head `6dbc72a54d` or a descendant. That head -already contains these squash integrations: - -- `516b265bf5` / #4106 — shared wallet deduplication and dead FFI/JNI removal; -- `f74465227f` / #4041 — shared and iOS DIP-13 invitation implementation; -- `97477d1c88` / #4093 — generalized existing-asset-lock top-up and iOS resume; -- `aba6af2420` / #4126 — shared and iOS Orchard viewing-key persistence. - -The `refactor/platform-wallet-dedup`, `feat/dip15-dashpay-invitations`, and -`feat/kotlin-sdk-dashpay-migration` worktrees are historical design/review -references. They are behind the baseline and **must not be merged or cherry-picked**. -This effort adds the missing Android adapters and new shared APIs on the exact -baseline while preserving all later seed-binding, provider, and rollback fixes. - -## 2. Non-negotiable invariants - -1. **Rust owns protocol and wallet policy.** Coin selection, reservation, - authorization, pricing, network endpoint interpretation, protocol constants, - proposal-rule selection, and recovery state machines must not be independently - reimplemented by Kotlin and Swift. -2. **Host bridges adapt; they do not orchestrate.** JNI and Swift wrappers may map - types, dispatch queues, callbacks, cancellation, and errors. A host wrapper must - not compose multiple fallible Rust calls into a new wallet transaction state - machine. -3. **Persistence contracts are capability-checked.** Backends attest individual - capabilities such as atomic changesets, invitations, Orchard FVKs, provider - restore, and deferred contact crypto. A feature requiring durability must fail - closed before broadcast when any required capability is absent. A present no-op - callback violates the contract. -4. **Persisted identity is immutable.** Balance/update callbacks may not rewrite an - address's derivation identity unless the callback explicitly represents a - derivation-map mutation. -5. **Protocol integer domains survive every ABI.** Every protocol field whose valid - consensus domain spans full `u64` must round-trip across Kotlin and Swift. A - narrower carrier is permitted only where Rust enforces a narrower consensus - bound. -6. **Recovery is part of feature parity.** A flow is not “ported” until it can resume - after process death at every point where durable state or on-chain value exists. -7. **Parity is executable.** Every capability row names an automated test or an - explicit device/testnet gate. Counts derived from source files are informational - only. - -## 3. Ownership boundary - -| Concern | Shared Rust | Host SDK | Example app | -| --- | --- | --- | --- | -| Transaction input selection and reservation | Own | Invoke one composite API | Collect user intent | -| Masternode endpoint discovery | Own | Map endpoint result | Display diagnostics only | -| Token authorization, group rules, price quote | Own | Map typed decision/quote | Render decision and collect inputs | -| Protocol constants and amount validation | Own | Preserve exact domain | Format values | -| Recovery state machine | Own | Persist/restore required records and invoke resume | Present resumable operations | -| Persistence schema and callbacks | Define callback semantics/capabilities and ABI version | Implement in Room/SwiftData/Keychain/Keystore | Never bypass SDK persistence | -| UI/navigation/lifecycle | No | Expose async/cancellation-safe API | Own | - -The following duplication is intentional: Room versus SwiftData entities and DAOs, -Android Keystore versus Apple Keychain, Compose versus SwiftUI, and ABI type mapping. -Those implementations must nevertheless satisfy the same Rust callback semantics. - -## 4. Correctness blockers - -**Current status (manifest reconciliation):** C1-C3 are the release-blocker -slices described in the implementation-state note above as implemented at -source/test level. For Kotlin, the manifest marks all three SDK capabilities -supported: C1 (`persistence.platform_address_identity`) has a restart-covering -Room regression; C2 (`core.atomic_send`) has shared reservation/failure unit -coverage plus the host `CORE-05` manual case, with restart correctly marked -`not_applicable`; and C3 (`tokens.full_u64_domain`) has Kotlin/JNI/Room/app -coverage plus a restart-covering device migration test. Swift still has open -restart gates for C1 and C3, so the manifest remains authoritative. The -“Required change” text below is retained as historical design rationale, not as -a claim that these Kotlin changes remain unimplemented. - -### C1 — Android platform-address balance persistence corrupts derivation indices - -The Android balance callback currently copies callback `accountIndex` and -`addressIndex` into the durable address row. Conflict-removal events may carry the -index of a competing address while intentionally leaving the authoritative -address/index bijection unchanged. Swift already ignores those two callback fields. - -**Required change** - -- Update only balance, nonce, used state, and height in the Android balance path. -- Preserve the stored account/address indices for an existing address. -- Add a regression test that seeds address A at index A, delivers a zero-balance - callback for A carrying index B, restarts/restores, and asserts A still maps to A. -- Document the callback semantics beside the JNI callback declaration. -- C1 is prevention-only on the unreleased PR #3999 baseline and requires no Room - migration. If a distributed beta database must later be repaired, recovery must - come from a Rust-authoritative address-pool re-emit, never SQL or host parsing of - derivation paths. - -**Acceptance:** the pre-existing row's account/address tuple and derivation path are -unchanged; Rust's restored bijection maps the canonical address at index A; and a -later valid credit to A is accepted. Database-level uniqueness or cleanup of benign -zero-balance conflict remnants is not required. - -### C2 — Core transaction construction is not atomic - -The shared builder separates funding from signing. Two concurrent calls can select -the same UTXO. Android serializes its wrapper, but Swift exposes the split public API -and other consumers can bypass the Android mutex. - -**Required change** - -- Add the composite to `rs-platform-wallet` first and expose it through thin C/JNI - adapters. Selection and recording in the account `ReservationSet` must be one - indivisible operation: no competing selection may observe the chosen inputs as - available. -- The design must not depend on holding the wallet-manager lock across a host - mnemonic-resolver callback. If key-wallet cannot reserve before signing, add the - required reservation primitive there or use an explicit per-wallet atomic gate in - platform-wallet. -- Add a finalize API that consumes an unfunded/configured builder, atomically funds - and reserves it, then signs. Validation/signing failure and explicit abandon - release the reservation; definitive broadcast rejection releases it; ambiguous - `MaybeSent` retains it under the existing TTL/reconciliation policy. -- Return a new opaque/V2 signed-transaction handle containing fee, funding account, - and reservation metadata. Do not extend `FFICoreTransaction` in place or alter an - existing C layout. Add explicit broadcast and abandon functions. -- Route Kotlin and Swift convenience sends through the composite. Deprecate the old - split builder symbols and public Swift sequence without removing their ABI in this - release. - -**Acceptance:** a barrier-forced concurrent same-UTXO test produces disjoint -reservations or one typed reserved/insufficient-funds failure. Tests also cover -validation/sign failure, explicit abandon, definitive rejection, ambiguous send, -builder consumption, and double-free safety. - -### C3 — Host SDKs preserve protocol `u64` values end to end - -Kotlin previously narrowed token amounts and direct-purchase costs to signed -`Long`. SwiftData uses its original signed `Int64` balance column as a -schema-neutral raw-bit carrier and exposes unsigned values at the SDK/UI boundary; -no alternate iOS balance column or migration-only code path is introduced. - -**Required change** - -- Public Kotlin token APIs use `ULong` (or one `TokenAmount` value type backed by - `ULong`). Internal native declarations remain `Long`/`jlong` raw-bit carriers so - existing JNI names and descriptors remain stable. Kotlin passes `value.toLong()`; - Rust reinterprets the bits with `as u64` and does not reject the sign bit. -- `ULong` and `Long` erase to the same JVM carrier. Any deprecated checked-`Long` - compatibility adapter must therefore have a distinct Kotlin name or explicit - `@JvmName`, reject negative values before the raw-bit native call, and be listed in - a per-method compatibility table. -- Java callers use one documented `BigInteger` or eight-byte adapter layered on the - same native path. Do not create a parallel native implementation. -- Audit mint, burn, transfer, set-price, purchase amount/cost, max supply, distribution - values, results, persistence, comparisons, and UI formatting. Preserve the existing - unsigned-decimal max-supply JSON behavior. -- In Room v5, replace signed SQL semantics such as `TokenBalanceEntity.balance` plus - `WHERE balance > 0` with an order-preserving unsigned representation. Use a fixed - eight-byte big-endian BLOB (lexicographically unsigned-order-preserving) and - explicit zero comparison, or document an equally lossless/order-preserving schema; - values at/above `2^63` must not disappear from DAO results. -- Separate codec-boundary tests (`0`, `Long.MAX_VALUE`, `2^63`, `u64::MAX`) from - operation semantics where zero may still be invalid. - -**Acceptance:** every full-domain token `u64` round-trips through JNI, Room, DAO -queries, and UI formatting without loss or signed-order errors. - -Direct-purchase quotes additionally follow Drive's operation semantics rather -than applying a generic full-`u64` arithmetic rule: amount is limited to DPP's -`2^48 - 1` distribution maximum; single-price multiplication saturates at -`u64::MAX`; set-price multiplication rejects overflow; and a configured zero -price remains valid. - -**Kotlin source-compatibility accounting:** PR #3999 introduces an unreleased -Kotlin SDK surface, so the signed declarations below have no published consumer -contract to deprecate. They are intentionally corrected in place; adding signed -overloads would preserve an invalid negative-value domain and, because `Long` and -`ULong` erase to the same JVM carrier, would complicate the public ABI. Java uses -`JavaTokenActions`/`BigInteger`; JNI descriptors remain unchanged. - -| Kotlin operation | Corrected parameter(s) | Compatibility disposition | -| --- | --- | --- | -| `mint`, `burn`, `transfer` | token amount `Long` → `ULong` | unreleased source break; same raw `jlong` JNI ABI | -| `setPrice` | price `Long` → `ULong` | unreleased source break; same raw `jlong` JNI ABI | -| `purchase` | amount and expected cost `Long` → `ULong` | unreleased source break; same raw `jlong` JNI ABI | -| `updateConfig` | optional max supply `Long?` → `ULong?` | unreleased source break; JSON/native encoding remains unsigned | -| distribution/claim numeric values | protocol `u64` values → `ULong` | unreleased source break; Java checked adapter where exposed | - -## 5. Android persistence and restart parity - -### P1 — Orchard full-viewing-key persistence - -Implement Room storage and JNI callbacks for persist/load/free of shielded viewing -keys, matching the existing Swift persistence contract. - -The exact shared preflight is `atomic_changesets + shielded_viewing_keys`. The -`shielded_viewing_keys` bit is backend-attested and then intersected with the -complete persist/load/free callback triplet; generic wallet-list `wallet_restore` -is not part of this contract because seedless rebind loads FVK rows directly. - -- Key rows uniquely by `(walletId, accountIndex)`; wallet IDs are already - network-specific, so do not add a redundant network key. -- Store exactly 96 FVK bytes. A present malformed row fails closed instead of - silently falling back to the mnemonic. -- Implement callback allocation/free pairing, duplicate-account upsert, wallet purge, - and wrong-wallet/network isolation. -- Reserve Room schema v6 for this entity and export its schema JSON. - -**Acceptance:** create/bind shielded state, terminate, make the mnemonic unavailable, -restart, and successfully rebind/sync from the stored viewing key. Unit/instrumented -tests cover corrupt length, multiple wallets/accounts, callback allocation/free, and -wallet deletion. - -### P2 — Invitation persistence and Android invitation UX - -The shared/iOS invitation protocol, durability ordering, and reclaim semantics are -defined by `DIP15_INVITATIONS_SPEC.md`; this specification does not fork them. - -Implement Android: - -- Push-only invitation persistence callbacks and Room UI schema, including failure - propagation. Rust does not rehydrate the invitation list; tracked asset-lock - restore preserves reclaimability. -- Create, parse/claim, sent-invitations, and reclaim SDK wrappers. -- Deep-link/QR handling with the canonical legacy-compatible envelope. -- Create, Claim, Sent Invitations, and Reclaim screens. -- Test-plan cases `DP-12...DP-19`, including interrupted create/reclaim and - already-consumed ambiguity. - -Creation must remain gated by Rust's exact invitation capability set: -`atomic_changesets + asset_lock_funding_indices + invitations + wallet_restore`. -The narrower `persists_durably()` compatibility wrapper is not sufficient for new -feature code. A no-op callback is not an acceptable compatibility mode. A callback -failure returns nonzero inside the changeset begin/end round and rolls it back. -Persist `reclaimInFlight` transactionally before consume; write `Reclaimed` -only after observed success and use the canonical conservative `Claimed` ambiguity -classification. Room is v8 in the serialized migration chain. Purge by wallet and -never log URI/WIF secrets. - -### P3 — Provider-special-transaction restoration - -Android already stores raw transaction bytes, but payload-only provider transactions -create no TXOs. A TXO join therefore cannot reconstruct wallet/account ownership. - -**Required change** - -- Preserve existing C layouts: `TransactionRecordFFI` already carries - `block_position`/`has_block_position`, and `AccountChangeSetFFI` already surrounds - its transactions with the full typed account identity. Change only the JNI/Kotlin - transaction callback parameters so each call explicitly forwards the enclosing - account fields and the transaction's existing position fields. Do not add C POD - fields or rely on mutable “current account” callback state. -- Add nullable/default block-position columns and a transaction↔account involvement - cross-reference. Reserve Room v7 for these additions and exported schema. -- On cold load, select provider transaction kinds 2...5 through wallet/account - involvement, marshal raw consensus bytes plus context/block metadata into the - existing `ProviderSpecialTxRestoreEntryFFI`, and keep every backing byte buffer - alive until the restore release callback. -- Rust re-decodes the payload and rebuilds ownership/masternode grouping; decoded - host columns are not restore authority. - -**Acceptance:** a payload-only provider transaction belonging to wallet A restores -only to A, survives without a TXO, preserves same-block ordering and optional block -position, and malformed raw data is diagnosed/skipped without crashing. - -### P4 — Deferred contact-crypto queue - -Do not add write-only host persistence. Implement restore in the shared wallet -start-state path first, then add the callback contract and both Room and SwiftData -stores in the same slice. After the relocation described by -`PENDING_CONTACT_CRYPTO_RELOCATION_SPEC.md`, restore hydrates identities first and -then fans rows into the owning `ManagedIdentity` across both identity buckets. -Unknown-owner rows are retained/quarantined or explicitly diagnosed, never silently -dropped. Define POD ownership/free semantics, idempotent operation identity, clear -tombstones, wallet scoping, and corrupt-row behavior. Until then, document that the -recurring sweep re-enqueues work and parity is delayed rather than durable. - -`PersistenceCallbacks` currently has no struct-size negotiation. New callback slots -must use a versioned `PersistenceCallbacksV2`/constructor unless the release explicitly -declares framework and wrapper lockstep source ABI. In either case add cbindgen header, -C layout, and Swift `MemoryLayout` pins; never silently insert fields into the current -layout. - -## 6. Recovery parity - -### R1 — Existing asset-lock resume on Android - -Generic Platform-address (`ADDR-03`) and shielded resume are already implemented and -remain unchanged. Bridge only the missing identity operations: - -- `platform_wallet_resume_identity_with_existing_asset_lock_signer` for registration; -- `platform_wallet_topup_identity_with_existing_asset_lock_signer` for top-up. - -Also bridge tracked-lock enumeration/status (with paired array free) so UI rows are -not reconstructed from private Room assumptions. Eligible generic rows have funding -type registration (`0`) or top-up (`1`/`2`) and a resumable status from Built through -ChainLocked (`0...3`). Funding type invitation (`3`) is never offered by generic -recovery. The shared wallet retains a consumed lock as a terminal tombstone so an -exact-outpoint retry remains a typed already-consumed error in the same process and -after restoration; actionable recovery lists exclude status `4`. - -The registration result's managed-identity handle must be adopted immediately and -freed on every post-call failure. Both operations borrow the mnemonic resolver under -the manager teardown gate. The Android UI uses the same restored outpoint and never -creates a second funding transaction. Generic paths always pass -`consumeInvitationVoucher=false`; only P2 reclaim may pass `true`. - -**Acceptance:** separate registration-resume and top-up-resume coverage (`ID-16` -covers top-up), interruption immediately after Core broadcast and before Platform -submission, and typed handling of untracked, foreign, and already-consumed locks. A -`Built` row re-broadcasts the same transaction and never creates a second distinct -funding transaction. A type-3 row is rejected by generic resume. - -### R2 — Compact-filter rescan on Android - -Expose the shared SPV rescan operation through JNI/Kotlin and add the height picker -and rescan state to the Android sync screen. The call rewinds an in-memory compact -filter checkpoint; it does not itself scan. A running SPV manager acts on the next -tick, a stopped manager acts on next start, equal/forward requests are harmless -no-ops, and unknown wallets return typed errors. Per-wallet failures are collected. -The rewind is not durable: process death before the filter loop consumes and persists -progress loses the rescan request, so the host/user must reissue it. Correct the -misleading shared Rust documentation when R2 is implemented. Do not promise -cancellability or durable rewind without adding a durable rescan-intent contract. - -### R3 — Contested usernames by identity - -Bridge both existing shared operations: - -- `platform_wallet_sync_contested_dpns_names`, which performs one network fetch and - full-snapshot persistence so resolved contests disappear; -- `managed_identity_get_contested_dpns_names`, which returns the cached array, with - its paired free function. - -Alternatively add one Rust composite returning an owned `DpnsNameArray`. Replace -Android's bounded local-label probing with this path. - -**Acceptance:** an identity with more than eight locally unknown contested names is -shown completely with one logical query. - -## 7. Shared-policy consolidation - -### S1 — Masternode discovery - -Discovery currently bootstraps DAPI before an SDK handle exists. Add a standalone -shared Rust entry point taking `(network, quorum_base)` and returning owned typed -records containing both Core peer address and DAPI URL, with an explicit free -function; alternatively move discovery into Rust SDK construction and expose its -cached result. Extract a pure endpoint parser in -`rs-sdk-trusted-context-provider` so the provider and bridge share one parser. - -Define explicit-configuration precedence, HTTP status/timeout/failure fallback, -version/status filtering, string ownership, testnet's missing-port default (`1443`), -bracketed IPv6, and malformed/missing port behavior. Delete Kotlin and Swift host -fetch/parsing only after both consume the shared result; hosts must not fetch twice. -Replace the Kotlin test that currently pins the incorrect `443` default. - -### S2 — Funding selection and account scope - -This concerns DIP-17 Platform credit addresses and nonces, not Core UTXOs from C2. -Add separate account-scoped Rust composites for identity registration/top-up from -Platform addresses. Inputs are `(wallet_id, PlatformPayment account_index, target -credits)`. Rust enumerates hydrated and derived candidates, fetches authoritative -balances/nonces, applies deterministic selection and fee constraints, signs/submits, -and returns the result. - -If multiple Platform Payment accounts exist, the account index is mandatory. Tests -cover only-the-chosen-account, fresh-restart hydrated candidates, exact target, -insufficient funds, and concurrent balance/nonce revalidation. Delete every -Kotlin/Swift pre-enumeration and greedy packing loop in the adopting slice. - -### S3a — Token authorization and proposal evaluation - -After C3, expose a versioned Rust decision result for action + token configuration + -actor context containing allowed/denied, a stable reason discriminant, and zero or -more authorization alternatives/group rules. Include every group-capable action, -especially `maxSupplyChangeRules`; do not collapse alternatives into one “required -key.” Define stable `repr` discriminants or versioned JSON plus typed host decoding -and owned-array/free rules. - -### S3b — Direct-purchase quote - -Expose a separate Rust quote result for schedule + amount containing selected -threshold, unit price, and full-domain `u64` total. Both apps render this result and -delete their local tier/price arithmetic. Rust remains authoritative at broadcast. - -### S4 — Protocol constants and codecs - -Expose versioned consensus identity-funding denomination sets separately from purely -presentational UI presets. Address validation returns typed family, network, payload, -and failure reason rather than `Bool`. Invitation validation already exists in -`platform_wallet_parse_invitation`; Android bridges that API rather than creating a -second codec. Remove hard-coded protocol tables and app-local Base58/Bech32 validators -only when the shared replacements are adopted. - -## 8. Immediate example-app parity fixes - -These are independent, low-risk fixes and do not wait for the larger shared APIs: - -1. Add `DedicatedTransition.CREATE_DOCUMENT`, route Android `documentCreate` to the - existing `CreateDocument` screen using selected contract/type, and remove the - unused `documentFields` catalog input unless it is passed as a real prefill. -2. Include `maxSupplyChangeRules` in Kotlin and Swift pending-proposal discovery - as an explicitly temporary compatibility fix; delete it when S3a replaces host - discovery entirely. -3. Display immature Core balance in Swift WalletDetail and do not label a wallet - containing only immature funds “Empty Wallet.” -4. Correct parity rows for document transitions, invitations, rescan, recovery, and - contested-name discovery. - -## 9. Executable parity manifest - -Replace manually maintained totals with a checked-in manifest. Each capability has: - -```yaml -id: invitations.reclaim -shared_apis: - - platform_wallet_topup_identity_with_existing_asset_lock_signer - - platform_wallet_resume_identity_with_existing_asset_lock_signer -required_persistence_capabilities: - - atomic_changesets - - asset_lock_funding_indices - - invitations - - wallet_restore -hosts: - swift: - sdk: supported - example_app: supported - restart: tested - reason: null - kotlin: - sdk: unsupported - example_app: unsupported - restart: required - reason: "P2 not implemented at the PR #3999 baseline" -verification: - - host: swift - kind: manual - file: packages/swift-sdk/SwiftExampleApp/TEST_PLAN.md - id: DP-19 -``` - -Allowed host states are `supported`, `partial`, `unsupported`, and -`not-applicable`. A capability can be `supported` only when: - -- all listed shared APIs are reachable, when the capability needs shared APIs; -- required persistence capabilities are registered; -- restart behavior is tested when value or durable state can exist; -- its automated verification exists and passes, or the manifest records a release - manual/device gate. - -`shared_apis` is optional because some capabilities are host-only. Restart state is -`required`, `tested`, or `not_applicable`, not a boolean. Verification kinds are -`unit`, `integration`, `device`, or `manual` and include a file, stable ID/test name, -and command where automated. CI validates schema, symbols/files/test IDs, reason -requirements, and generated counts; it does not pretend to prove runtime reachability -by static assertion. `PARITY.md` becomes generated prose or a thin index. - -## 10. Implementation sequence - -### Slice 0 — Spec and regression harness - -- Land this reviewed spec. -- Add the parity-manifest schema/checker and initial manifest representing reality. -- Correct stale documentation without claiming missing features are complete, - including obsolete Swift `core_wallet_send_to_addresses` test-plan references and - shipped Swift invitation rows still marked as bridge-only. - -### Slice 1a — Android address-index safety - -- C1 only. No schema migration. - -### Slice 1b — Atomic shared Core send - -- C2 Rust/key-wallet reservation primitive, new opaque FFI result, both host - adoptions, and old-ABI deprecation. - -### Slice 1c — Lossless token domains - -- C3 compatibility table, JNI raw-bit boundary, v5 unsigned token storage, and both - host/domain tests. C3 gates S3a/S3b. - -These are separate PRs/rollback units. - -### Slice 2a — Serialized Android schema foundation - -- Land/export v5 for C3 unsigned token storage. -- Reserve and land Room v6 for P1 FVK storage. -- Reserve and land Room v7 for P3 block position and transaction-account - involvement. -- Reserve Room v8 for P2 invitation UI persistence. -- Export each schema; test each adjacent migration and v4→latest. Do not develop - parallel conflicting migrations from the same schema version. -- Define a versioned, explicit backend-attested `PersistenceCapability` bitset and - intersect/validate it against structurally required callback groups. Callback - presence alone cannot attest semantic sub-capabilities: for example, - `provider_transactions` shares the broad wallet-list restore callback but is valid - only when the backend actually populates and frees its provider restore payload. - Canonical v1 capabilities are `atomic_changesets`, - `asset_lock_funding_indices`, `invitations`, `shielded_viewing_keys`, - `provider_transactions`, `unsigned_token_storage`, `pending_contact_crypto`, and - `wallet_restore`. `asset_lock_funding_indices` covers account registration and - address-pool watermark persistence; `pending_contact_crypto` covers both durable - queue additions and removals. These names are the public manifest/diagnostic - namespace; source-level compatibility aliases do not create additional bits. - Expose initialization diagnostics and add missing-capability preflight tests per - feature, including a wallet-list callback present while provider capability - remains absent. -- Retain `persists_durably()` only as a compatibility wrapper derived from - `atomic_changesets + asset_lock_funding_indices + invitations`; new feature code - checks its exact required capability set. Invitation creation additionally - requires `wallet_restore`, because a committed voucher is not restart-safe unless - its originating wallet and funding-index state can both be reconstructed. - -### Slice 2b — Android viewing-key callbacks - -- P1 behavior atop v6, including native instrumentation round trip. - -### Slice 2c — Android provider restoration - -- P3 behavior atop v7. This may remain `unsupported` in the manifest until an - Android masternode consumer exists, but must not be claimed as parity. - -### Slice 2d — Android identity recovery - -- R1 tracked-lock listing plus registration/top-up resume. No DB migration. - -### Slice 2e — Android SPV and DPNS queries - -- R2 and R3 as independent commits/PRs. No DB migration. - -Each vertical slice includes its JNI descriptor/symbol smoke and native Android -library build; JVM tests alone do not validate native binding. - -### Slice 3 — Invitations - -- P2 as one vertical feature using v8 and the shipped shared/iOS invitation - semantics. R1 lands before invitation reclaim. -- Do not combine it with generic persistence cleanup; invitation broadcast ordering - and durability gates must remain independently reviewable. - -### Slice 4 — Shared-policy consolidation - -- S1 endpoint discovery. -- S2 account-scoped funding selection. -- S3a proposal/authorization decisions. -- S3b purchase quote. -- S4 constants/codecs. - -Each host implementation is deleted in the same slice that exposes and adopts its -shared replacement; do not leave two live paths. - -### Slice 5 — Deferred durability - -- P4 only after the per-identity queue relocation and shared cold-load restore exist. - -### Release gates - -PR #3999 release blockers are Slice 0, C1, C2, C3, P1, P3 if provider parity is -advertised, R1, and truthful manifest/docs. Invitation Android parity, R2/R3, and -S1-S4 may ship as explicitly `unsupported`/`partial` follow-ups unless product scope -requires them for the same release. Definition of done for the overall program does -not force every consolidation item into one unbounded merge gate. - -## 11. Test matrix - -| Risk | Shared Rust | JNI/Kotlin | Swift | Device/testnet | -| --- | --- | --- | --- | --- | -| Address index conflict | provider event fixture | handler restart/restore | existing semantic pin | Android restore smoke | -| Concurrent Core sends | barrier-forced same-UTXO race and reservation lifecycle | composite wrapper + JNI ownership | composite wrapper + C ownership | two live sends | -| `u64` boundary | ABI encode/decode | raw-bit JNI + Room/DAO/UI unsigned ordering | `UInt64` parity | Android JNI symbol smoke | -| Viewing-key restart | bind without seed | v5→v6 + callback/free round trip | existing callback test | Android seedless restart | -| Provider restore | payload decode/ownership | v6→v7, multiwallet membership, malformed bytes | existing restore | Android callback round trip | -| Asset-lock resume | tracked-lock state machine | process-death recovery | existing resume tests | funded testnet | -| Invitations | protocol/persistence ordering | v7→v8 + DP-12...19 | retain DP-12...19 | cross-platform claim | -| Discovery | port/IPv6 fixtures | no host parser remains | no host parser remains | testnet discovery | -| Token proposal rules | all action-rule variants | render typed result | render typed result | group co-sign | -| Deferred crypto | identity-first restore/fan-out | vtable + Room crash restart | vtable + SwiftData crash restart | locked-seed restart | - -Required validation per slice: - -- `cargo fmt --all -- --check` and targeted Rust tests; -- `cargo clippy` for changed Rust crates and all targets; -- `cargo test -p rs-unified-sdk-jni --lib`, Android native library build, Kotlin JVM - tests under JDK 17, Room `MigrationTestHelper` adjacent and v4→latest tests, and - instrumented callback round trips for P1/P3; -- Swift package tests and iOS framework build for Swift/FFI slices; -- cbindgen header regeneration/diff, C struct size/layout pins, Swift `MemoryLayout` - pins for direct structs, and null/zero-count/double-free buffer tests; -- on-device external-function smokes for R1/R2/R3/C3 and resolver-handle teardown; -- `git diff --check`. - -## 12. Compatibility and rollout - -- Database migrations are additive and serialized as v5 unsigned token storage, v6 - FVK, v7 provider membership/position, and v8 identity-key derivation - breadcrumbs (pending-repair durability, dashpay/platform#4060); the - invitations migration shifts to v9. Do not destructively rewrite address - identity columns. -- New Rust FFI functions are additive and new result PODs are opaque/versioned. - Existing released split-builder entry points are deprecated before removal; - existing struct layouts and JNI descriptors do not change silently. The - unreleased Kotlin token source surface is corrected from signed `Long` to - `ULong` in place as accounted in C3, while retaining identical raw `jlong` - descriptors and a checked Java `BigInteger` adapter. -- Persistence exposes feature-specific capabilities. Registration reports missing - callback sets at initialization where possible, and required feature APIs fail - closed before broadcast. -- The parity manifest initially records known gaps. CI prevents regression but does - not require all gaps to close in the first slice. - -### Keystore rework divergences and convergences (dashpay/platform#4060) - -Recorded in `sdk-parity-manifest.json`; rationale here: - -- **`KeySecurityPolicy` + Keystore alias split (Kotlin-only, deliberate).** - Android Keystore fixes authentication parameters at key generation, so the - AUTH_GATED/DEVICE_BOUND policies require distinct aliases; iOS Keychain has - no per-alias auth-parameter analog (item access control covers the same - ground), so the manifest marks Swift `not-applicable` — no Swift port is - planned. The lockless-device degradation (AUTH_GATED writes redirect to the - DEVICE_BOUND alias, surfaced via `effectiveKeySecurityPolicy`) is likewise - Android-specific: KeyMint rejects gated key generation without a secure - lock screen. -- **Platform-wallet code 98 is now CONVERGENT.** Kotlin previously collapsed - the blanket Option-miss code into the top-level `DashSdkError.NotFound` - while Swift kept it in the wallet family; Kotlin now maps 98 to - `DashSdkError.PlatformWallet.NotFound` (BREAKING for hosts that caught the - top-level type from platform-wallet operations). -- **Durable pending-repair surface (Kotlin-only, port candidate).** - `pendingIdentityKeys` + forced/verified `repairIdentityKey` + the Room v8 - derivation breadcrumbs have no Swift counterpart; the manifest records the - gap as `unsupported` for Swift. -- **Structured `SigningKeyUnavailable` discriminator (both hosts).** The - signer completion carries a typed `error_code` (rs-sdk-ffi - `DashSDKSignerErrorCode`), restored as platform-wallet code 31 on both - hosts. The Rust-internal segment rides the machine prefix - `signer_error:key_unavailable: ` through `ProtocolError::Generic` (a typed - rs-dpp variant was rejected for serialization blast radius — accepted - residual). The Kotlin `MESSAGE_MARKER` text sniff survives ONLY as a - deprecated fallback for the #4191 merge-order transition (marker-based - classification predating the typed code) and for conversion paths that - lose the machine prefix; mixed old-native/new-Kotlin artifacts are - unsupported outright (the sign-completion JNI arity changed 3→4 args). - Remove it (and the marker's matcher role) in the next minor release. - -## 13. Explicitly out of scope - -- Redesigning DIP-13/DIP-15 invitation wire formats. -- Simultaneous multi-account DashPay contacts; that remains governed by - `MULTI_ACCOUNT_SPEC.md` and its product gate. -- Replacing JNI or C FFI with a new binding generator. -- Making Room and SwiftData schemas structurally identical. -- Treating example-app visual layout differences as parity failures when capability, - accessibility contract, and behavior are equivalent. - -## 14. Definition of done - -This effort is complete when: - -1. C1-C3 have regression coverage and both host SDKs use the safe/shared paths. -2. Android registers all persistence capabilities required by features it advertises. -3. Android can resume every funded identity/invitation operation already supported - by iOS. -4. S1-S4 have one live shared implementation with both host copies removed. -5. Every supported capability is represented by the executable manifest and named - tests; no manual parity count contradicts runtime capability. -6. Cross-platform invitation claim and concurrent-send device smoke tests pass. diff --git a/docs/sdk/PR3999_WALLET_LIFECYCLE_HARDENING_SPEC.md b/docs/sdk/PR3999_WALLET_LIFECYCLE_HARDENING_SPEC.md deleted file mode 100644 index 2a9ec4decce..00000000000 --- a/docs/sdk/PR3999_WALLET_LIFECYCLE_HARDENING_SPEC.md +++ /dev/null @@ -1,652 +0,0 @@ -# PR #3999 — Kotlin SDK wallet-lifecycle hardening spec - -Covers the 4 open blocking review findings on PR #3999 -(`feat/kotlin-sdk-and-example-app`) that were not yet addressed: - -1. `PlatformWalletManager.kt:347` — init cleanup starts after fallible - child constructors. -2. `PlatformWalletManager.kt:778` — alias cleanup ignores ownership - recorded only in another wallet's index. -3. `PlatformWalletManager.kt:783` — identity-key persistence can still - run after wallet deletion. -4. `CreateWalletScreen.kt:85` — configuration changes discard the only - recovery-phrase copy. - -Findings 2 and 3 both live in the `removeWallet` / `WalletStorage` -private-key lifecycle and are designed together (§2). 1 and 4 are -independent (§1, §3). - -## Spec review findings (applied) - -Three independent review agents (feasibility, security, scope/simplicity) -checked a first draft of this spec against the actual source. §1 and -the overall scope of §2/§3 came back clean; three must-fix issues were -found and are already folded into the sections below: - -1. **Compile-breaking (feasibility):** the original §2 sketch declared - `isOwnedByAnotherWallet` as a `private` extension function on - `PrivateKeyExclusion`. It's unreachable from `removeWallet`'s - `withPrivateKeyExclusion { }` lambda (only the interface's own - members resolve there) and `private` besides. Fixed: declared on - the `PrivateKeyExclusion` interface itself, like the existing - `deleteOwnerIndex`. -2. **Deadlock-risk (feasibility + security):** the original §2 - `storeIfAbsent` sketch called `derive()` (a Rust FFI call) *inside* - `privateKeyMutex.withLock`, directly violating `WalletStorage.kt`'s - own documented invariant that the locked block must never call into - native code. Fixed: two-phase check → derive-outside-lock → - re-check-and-store. The security pass also caught that the - existence check must treat a present-but-undecryptable ciphertext - blob (a real, already-supported legacy state — see - `isPrivateKeyDecryptable`) as absent, or the fix would silently - defeat that re-derive path. -3. **New risk introduced (security), inconsistent with the rest of the - screen (feasibility):** the original §3 sketch also moved the - wallet-creation coroutine's launch from `rememberCoroutineScope()` - onto `viewModel.viewModelScope`. Feasibility flagged that the - screen's other captured state (`isCreating`, `error`, - `navController`) stays composable-scoped, so a `viewModelScope` - coroutine surviving a config change would mutate/navigate through - dead references. Security separately flagged that `viewModelScope` - surviving longer than the composition (e.g. past navigation-away) - combined with `onCleared()` scrubbing the phrase could wipe the - *only* copy before the emergency dialog is ever shown, for a - creation that fails after the user has already left the screen — a - worse outcome than the bug being fixed. Fixed: keep - `rememberCoroutineScope()` for the launch; only the *storage* of an - already-caught phrase moves to the ViewModel. - -Additionally, the security pass found one HIGH-severity gap the -feasibility/scope passes didn't have the angle to catch: the -tombstone-set design ("a deleted wallet's id is never reused") is -false — re-importing the same recovery phrase after an accidental -delete is a real, supported flow, and would permanently brick under -the original always-on tombstone. Fixed: `createWallet` (the same -entry point both "new" and "restore from phrase" go through) now -clears any stale tombstone for that wallet id before storing. - -Two lower-severity items were surfaced and are intentionally *not* -fixed in this pass (see the "Accepted, not fixed" note in §2 and the -platform-limitation note in §3) — both are pre-existing or -theoretical, not regressions this spec would introduce, and closing -them would widen the diff for gaps that either have no live caller -today or are an accepted platform ceiling. - ---- - -## §1. Init cleanup ordering (finding @ `PlatformWalletManager.kt:347`) - -### Problem - -`PlatformWalletManager`'s primary constructor initializes, in source -order: `scope` (192) → `teardownGate`/`_syncEvents`/`eventBridge` -(203-317) → `mnemonicResolver` (325) → `signer` (326-327) → -`identityKeyDeriver` (337-341) → `persistenceHandler` (343-347) → … -→ `nativeInitialization = initializePlatformWalletNativeManager(...)` -(477-490). - -`initializePlatformWalletNativeManager` already contains a correct -cleanup transaction — on failure it cancels `scope` and closes -`mnemonicResolver`/`signer`/`persistenceHandler` (in that order, -suppressing secondary failures) before rethrowing. But it only guards -failures inside *itself* (native bundle create, manager-handle fetch, -capability reads). It cannot guard `mnemonicResolver`, `signer`, or -`persistenceHandler`'s own constructors, because those already ran to -completion (or threw) *before* `nativeInitialization` is reached — a -throw there aborts the whole primary constructor with no -`PlatformWalletManager` instance to call `close()` on, so: - -- `mnemonicResolver`'s JNI handle (`MnemonicNative.createResolver`) - leaks if `signer`, `identityKeyDeriver`, or `persistenceHandler` - throws after it. -- `signer`'s JNI handle (`SignerNative.createSigner`) leaks if - `identityKeyDeriver` or `persistenceHandler` throws after it (and - `database.platformAddressDao()`, evaluated as `signer`'s 4th - constructor arg, can itself throw before `signer`'s own constructor - even runs). -- `persistenceHandler`'s owned single-thread `Executor` - (`Executors.newSingleThreadExecutor { "dash-persistence" }`) leaks - if it's the one that throws, or leaks the executor while everything - *before* it (resolver, signer) also leaks. - -`identityKeyDeriver` itself holds no releasable resource (confirmed: -plain Kotlin object, no native handle, not `AutoCloseable`). - -### Chosen approach - -Group the four child constructions into one `init`-time block that -builds each as a local `var`, wraps construction in `try`, and on any -`Throwable` closes whichever locals were already assigned (in reverse -construction order) before rethrowing — the same "roll back the -locals, only adopt on success" shape the Swift equivalent -(`PlatformWalletManager.swift`'s `configure(...)`) already uses, -adapted to Kotlin's val-in-constructor idiom via a small holder: - -```kotlin -private class CoreChildren( - val mnemonicResolver: MnemonicResolverAndPersister, - val signer: KeystoreSigner, - val identityKeyDeriver: IdentityKeyPrivateKeyDeriver, - val persistenceHandler: PlatformWalletPersistenceHandler, -) - -private val coreChildren: CoreChildren = run { - var mnemonicResolver: MnemonicResolverAndPersister? = null - var signer: KeystoreSigner? = null - try { - val resolver = MnemonicResolverAndPersister(walletStorage) - .also { mnemonicResolver = it } - val keySigner = KeystoreSigner( - walletStorage, network, biometricGate, database.platformAddressDao(), - ).also { signer = it } - val deriver = IdentityKeyPrivateKeyDeriver( - network = network, - mnemonicResolverHandle = resolver.nativeHandle, - walletStorage = walletStorage, - ) - val handler = PlatformWalletPersistenceHandler( - database = database, privateKeyDeriver = deriver, network = network, - ) - CoreChildren(resolver, keySigner, deriver, handler) - } catch (e: Throwable) { - runCatching { signer?.close() } - runCatching { mnemonicResolver?.close() } - scope.cancel() - throw e - } -} -private val mnemonicResolver get() = coreChildren.mnemonicResolver -private val signer get() = coreChildren.signer -private val identityKeyDeriver get() = coreChildren.identityKeyDeriver -private val persistenceHandler get() = coreChildren.persistenceHandler -``` - -- `persistenceHandler` needs no explicit close-on-catch: if its own - constructor throws, it never assigned itself anywhere, and it's the - last child built, so there's nothing after it to fail and orphan it. -- `scope.cancel()` on the failure path mirrors what - `initializePlatformWalletNativeManager`'s own cleanup already does - for *its* failures; nothing has been launched on `scope` yet at this - point (it's created earlier, at line 192, unused until later), so - cancelling it here is cheap and keeps both failure paths consistent. -- All downstream references to `mnemonicResolver`, `signer`, - `identityKeyDeriver`, `persistenceHandler` throughout the file are - unaffected — they become `private val ... get() = ...` delegating - properties instead of directly-initialized `private val`s, same - read-only surface, no call-site changes. -- `nativeInitialization`'s own cleanup transaction (109-128) is - untouched — it still guards its own failure window exactly as - today. - -### Alternatives rejected - -- **Wrap the whole primary constructor body in try/catch.** Kotlin - doesn't allow arbitrary try/catch around property initializers - mixed with the constructor parameter list in a readable way, and it - would force converting *every* property after this point (including - `identityRegistration`, `voteCasting`, etc., none of which are - fallible or hold resources) into part of the guarded region for no - benefit — larger surface than necessary. -- **`private constructor` + `companion object { fun create(...) }` - factory** (the pattern the finding suggests by analogy to Swift). - Rejected for this specific class: every call site that currently - does `PlatformWalletManager(...)` (`WalletManagerStore`'s factory - lambda, tests) would need to change to `PlatformWalletManager.create(...)`, - and the class already exposes a large public API assuming direct - construction succeeds or throws synchronously — converting to an - external factory is a bigger surface change for the same outcome as - the local-var-holder approach above, which achieves the identical - rollback guarantee without touching any call site. - -### Failure modes covered / not covered - -- Covered: any single child's constructor throwing, at any position in - the four, cleans up every JNI-owning child constructed strictly - before it. -- Not covered (explicitly out of scope for this finding, flagged for - a separate follow-up): `KeystoreSigner.close()` itself does not - cancel `KeystoreSigner`'s own internal `scope` - (`CoroutineScope(SupervisorJob() + Dispatchers.IO)`, `KeystoreSigner.kt:53`) - — that's a pre-existing gap in `KeystoreSigner`'s own `close()` - logic, orthogonal to *when* cleanup runs (which is what this finding - is about). Noting it here so it isn't lost, not fixing it in this - pass to keep the diff surgical. - -### Test plan - -Add to `PlatformWalletManagerInitializationTest.kt` (or a new -`PlatformWalletManagerConstructionTest.kt` if constructing a real -`PlatformWalletManager` needs more fixture setup than that file -currently has): a test that injects a `walletStorage`/`database`/etc. -combination where `KeystoreSigner`'s construction throws (e.g. via a -fake `platformAddressDao()` or a `SignerNative.createSigner` stub that -throws — check what's fake-able without real JNI, per that file's -existing lambda-injection pattern for `nativeCreate`/`nativeManagerHandle`/etc., -since `PlatformWalletManagerInitializationTest` already fakes native -calls at that granularity). Assert: -- The thrown exception propagates (construction still fails). -- `mnemonicResolver`'s `close()` was invoked (spy/count). -- No leaked JNI handle assertion is directly measurable from a JVM - unit test without a real native lib loaded; the practical proof is - "close() was called on every child constructed before the failing - one," which is what the test asserts. - ---- - -## §2. Cross-wallet private-key ownership (findings @ `:778`, `:783`) - -### Shared root cause - -`WalletStorage` (`sdk/src/main/kotlin/.../security/WalletStorage.kt`) -stores private-key ciphertext **globally**, keyed only by pubkey hex -(`privkey.`, no wallet-id component), because sibling network -wallets derived from one mnemonic (Testnet/Devnet/Regtest all share -DIP-9's non-mainnet derivation path) can legitimately derive the same -pubkey and are expected to share that one ciphertext entry. Ownership -is tracked **per-wallet** via a separate index (`privkeyowners.` -→ `Set`), and all wallets share one process-wide -`WalletStorage` instance and one `privateKeyMutex`. - -Two related gaps fall out of that design, both inside `removeWallet` -(`PlatformWalletManager.kt:718-791`): - -**(a) finding @ `:778`.** `aliasesToDelete` (764-770) decides an alias -is safe to delete when no *other Room `public_keys` row* (a committed, -on-chain-registered key) references it outside this wallet's -identities. It never checks whether a *sibling wallet's durable owner -index* (`privkeyowners.`) already claims the alias — -so a sibling wallet that pre-stored (but hasn't yet committed a -`public_keys` row for) the same shared alias loses its ciphertext when -this wallet is deleted. - -**(b) finding @ `:783`.** Two independent gaps, not one: -- `PlatformWalletPersistenceHandler`'s own persist-callback path - (`onPersistIdentityKeyUpsert` → `IdentityKeyPrivateKeyDeriver.hasStored` - then `.deriveAndStore` → `WalletStorage.storePrivateKey`) *is* - exclusion-fenced (`withCallbackExclusion`), but `hasStored` and the - eventual `storePrivateKey` inside `deriveAndStore` are two separate - calls with no single lock spanning both — a sibling caller can store - between the check and the write. -- Two **app-level** call sites — `CreateIdentityScreen.kt:219-227` - and `IdentityKeyAdditionFlow.kt:161-165` — call - `walletStorage.storePrivateKey(...)` directly from their own - `scope.launch`/coroutine, entirely outside - `withPrivateKeyExclusion`/`withCallbackExclusion`/`teardownGate`. - Neither `WalletStorage` nor `storePrivateKey` has any concept of - "this wallet was just deleted," so a store that was already - in-flight when `removeWallet` ran completes anyway, resurrecting the - just-deleted wallet's owner-index entry with fresh ciphertext. - -### Chosen approach - -*(Revised after multi-agent spec review — see "Spec review findings" -below for what changed and why.)* - -Three additions to `WalletStorage`, all executed under the existing -`privateKeyMutex` (via `withPrivateKeyExclusion`/its internal scope), -so no new lock is introduced: - -**1. Cross-wallet ownership query**, used to fix `:778`. Added to the -`PrivateKeyExclusion` **interface** (not a private extension function -— extension functions can't see `WalletStorage`'s private members and -aren't reachable from inside a `withPrivateKeyExclusion { }` lambda, -where only the interface's own receiver is in scope), implemented in -`privateKeyExclusionScope` alongside the existing `deletePrivateKeys`/ -`deleteOwnerIndex`: - -```kotlin -interface PrivateKeyExclusion { - suspend fun deletePrivateKeys(pubkeyHexes: Collection) - suspend fun deleteOwnerIndex(walletId: ByteArray) - - /** True if any wallet OTHER than [excludingWalletId] still claims - * [pubkeyHex] in its durable owner index. */ - suspend fun isOwnedByAnotherWallet(pubkeyHex: String, excludingWalletId: ByteArray): Boolean -} - -private val privateKeyExclusionScope = object : PrivateKeyExclusion { - // ...existing overrides... - override suspend fun isOwnedByAnotherWallet( - pubkeyHex: String, - excludingWalletId: ByteArray, - ): Boolean { - val excludingHex = excludingWalletId.toHex() - val prefs = store.data.first() - return prefs.asMap().any { (key, value) -> - key.name.startsWith(PRIVKEY_OWNERS_PREFIX) && - key.name.removePrefix(PRIVKEY_OWNERS_PREFIX) != excludingHex && - (value as? Set<*>)?.contains(pubkeyHex.lowercase()) == true - } - } -} -``` - -`removeWallet`'s `aliasesToDelete` computation (`PlatformWalletManager.kt:764-770`) -becomes: - -```kotlin -val aliasesToDelete = buildList { - for ((pubkeyHex, publicKeyData) in keysByPubkeyHex) { - val referencedElsewhere = database.publicKeyDao() - .countReferencesOutsideIdentities(publicKeyData, ownedIdentityIds) > 0 - val ownedElsewhere = isOwnedByAnotherWallet(pubkeyHex, walletId) - if (!referencedElsewhere && !ownedElsewhere) add(pubkeyHex) - } -} -``` - -Already runs inside `walletStorage.withPrivateKeyExclusion { ... }` -(736) — as an interface method, `isOwnedByAnotherWallet` resolves on -that lambda's `PrivateKeyExclusion` receiver directly, same as -`deleteOwnerIndex` does today, keeping it under the same lock as the -delete that follows — no TOCTOU between the check and -`deletePrivateKeys`/`deleteOwnerIndex`. - -**2. Atomic-enough check-and-store**, used to fix the `hasStored`/ -`deriveAndStore` half of `:783` (and the same race underlies `:778`'s -"rollback path" note). **Not a single lock-held call** — `WalletStorage.kt`'s -own documented invariant on `withPrivateKeyExclusion` is explicit: *"must -also never call into native code (a persistence callback parked on this -lock can be holding native locks)."* `derive()` is a Rust FFI call -(`IdentityNative.deriveIdentityPrivateKeyWithResolver`), so it cannot run -inside `privateKeyMutex.withLock`. Instead, a double-checked pattern — -lock only for the existence check/write, derive in between, re-check -before writing: - -```kotlin -/** If [pubkeyHex] has no *usable* stored ciphertext (absent, or present - * but undecryptable — see [isPrivateKeyDecryptable]), derive it via - * [derive] and store it; either way record [ownerWalletId] in the - * owner index. Returns whether a derive+store actually happened. */ -suspend fun storeIfAbsent( - pubkeyHex: String, - ownerWalletId: ByteArray, - derive: suspend () -> ByteArray, -): Boolean { - // Fast path: already usable under any owner — just record ownership. - if (privateKeyMutex.withLock { addOwnerIfUsableLocked(pubkeyHex, ownerWalletId) }) { - return false - } - // Derive OUTSIDE the lock (native call) — another writer may store - // the same alias while this runs. - val derived = derive() - return privateKeyMutex.withLock { - if (addOwnerIfUsableLocked(pubkeyHex, ownerWalletId)) { - false // lost the race while deriving; the winner's copy stands - } else { - storePrivateKeyLocked(pubkeyHex, derived, ownerWalletId) - true - } - } -} -``` - -`addOwnerIfUsableLocked` treats "present but not -`isPrivateKeyDecryptable`" the same as absent (so the legacy-blob -re-derive path this codebase already supports keeps working — see -"Spec review findings" #2) — only a present-and-decryptable entry -short-circuits to "just add ownership." `IdentityKeyPrivateKeyDeriver.deriveAndStore` -calls `storeIfAbsent` instead of the current separate -`hasStored`/`storePrivateKey` pair; `PlatformWalletPersistenceHandler`'s -`existedBefore` becomes `!storeIfAbsent(...)`'s result directly, -removing the `runCatching { hasStored }.getOrDefault(true)` fallback -entirely (a genuine simplification, not just a safety fix). This isn't -a single atomic transaction (derivation still happens outside the -lock, matching `storePrivateKey`'s existing outside-the-lock derive -pattern today), but it closes the specific gap the finding names: the -existence check and the eventual write are no longer two calls with an -unguarded window where a sibling wallet's write is invisible to the -first check *and* silently overwritten by the second. - -**3. Deletion tombstone**, used to fix the app-level-bypass half of -`:783`: - -```kotlin -// WalletStorage — guarded by privateKeyMutex. Process-lifetime, but -// explicitly cleared on wallet (re-)creation (see below) — a deleted -// wallet's id CAN be reused within one process (re-import of the same -// recovery phrase after an accidental delete is a real, supported -// flow), so this must not be "set once, never cleared." -private val tombstonedWalletIds = mutableSetOf() -``` - -`removeWallet`'s locked section additionally calls -`walletStorage.tombstoneWallet(walletId)` (same -`withPrivateKeyExclusion` block, right alongside `deleteOwnerIndex`, -so tombstoning happens atomically with the alias cleanup it's -protecting). `PlatformWalletManager.createWallet` (`:541-...`, the -single entry point for both "new wallet" and "restore/re-import from -mnemonic" — same function, both paths pass a mnemonic) calls -`walletStorage.clearTombstone(walletId)` right after the native create -succeeds and before `storeMnemonic`, so a re-imported wallet with a -previously-tombstoned id is immediately usable again, matching -`storePrivateKey`'s pre-existing "keyed globally by wallet id, -deterministic from seed+network" contract. - -`storePrivateKey` (and the new `storeIfAbsent`, via the same -lock-held check) reject writes for a tombstoned `ownerWalletId`, -throwing a new `WalletTombstonedException(walletId)` — the two -app-level call sites (`CreateIdentityScreen.kt:219-227`, -`IdentityKeyAdditionFlow.kt:161-165`) need to catch it. **Accepted, -not fixed, in this pass:** `storePrivateKey`'s `ownerWalletId` param is -nullable (`= null`); a null-owner call bypasses both the tombstone -check and the owner-index union `removeWallet` reads. No current -caller on the derive/register path passes null, so this is a -theoretical gap, not a live bug — noted rather than closed by, e.g., -making the parameter non-nullable (a wider API change touching every -call site for a path nothing currently exercises). What they *do* on -catch is a product decision, not purely mechanical: - -- `CreateIdentityScreen`: the key was already derived and the identity - isn't registered yet — the safest behavior is to abort registration - with a clear "wallet was removed during setup" error, since there's - no wallet left to register against. -- `IdentityKeyAdditionFlow`: adding a key to an *existing* identity on - a now-deleted wallet — same abort-with-error behavior; the identity - itself is decoupled from the wallet's local state at this point. - -**I want to confirm that "abort with a clear error, don't silently -drop it" is the right call for both sites before implementing** — it's -the conservative default but it's the one piece of this section that's -a product/UX decision rather than a pure correctness fix, so flagging -it explicitly for sync rather than assuming. - -### Alternatives rejected - -- **Namespace ciphertext storage per-wallet** (so sibling wallets each - get their own copy instead of sharing one `privkey.` entry). - Rejected: this is a deliberate existing design choice (DIP-9 sibling - wallets sharing one mnemonic are expected to share key material by - construction), not a bug — re-namespacing would be a much larger, - riskier storage-format migration for a problem the ownership-index - fix already solves without touching the ciphertext layer. -- **A single process-wide "wallet lifecycle" lock instead of the - targeted tombstone check.** Rejected: `privateKeyMutex` already - serializes every `WalletStorage` mutation; adding a *second*, - coarser lock spanning arbitrary app-level coroutines - (registration flows, key-addition flows) would be far more invasive - and risks new deadlocks between `withCallbackExclusion` (native - callback path) and app-driven UI coroutines. The tombstone check - reuses the existing lock and only adds a rejection condition. - -### Failure modes - -- `isOwnedByAnotherWallet` false positive/negative: a false negative - (misses a legitimate other-wallet claim) reproduces today's bug; a - false positive (over-retains an alias nobody else needs) only costs - a stray ciphertext entry, not a lost key — asymmetric risk correctly - favors retention. -- `storeIfAbsent` racing two *concurrent* callers for the *same* new - pubkey: the mutex serializes them, so the second caller's `derive()` - result is discarded once `hasPrivateKeyLocked` sees the first - caller's write — matches today's `deriveAndStore`'s intended - idempotency, now actually atomic. -- Tombstone check: a wallet ID is only ever tombstoned by `removeWallet` - itself, under the same lock as the check, so there's no window where - a store could race the tombstone write. - -### Test plan - -New `WalletStorageTest.kt` (currently doesn't exist — flagged as a gap -by the research pass): -- `isOwnedByAnotherWallet` returns true when wallet B's owner index - contains the alias and wallet A is being deleted; false when no - other wallet claims it. -- `storeIfAbsent` returns `false` and does not overwrite ciphertext - when the pubkey already has an entry (from any owner); returns - `true` and writes on first store; two concurrent calls for the same - new pubkey result in exactly one ciphertext write. -- `storePrivateKey`/`storeIfAbsent` throw `WalletTombstonedException` - for a tombstoned wallet id; a non-tombstoned sibling wallet's calls - are unaffected. - -Extend `removeWallet`'s coverage (no dedicated test file currently -exercises `removeWallet` at all — another gap flagged by the research -pass) with a sibling-wallet scenario: wallet A and B share a derived -pubkey via B's *pending* (not-yet-committed) owner-index entry; delete -A; assert B's ciphertext and owner-index entry survive. - ---- - -## §3. `CreateWalletScreen` mnemonic loss on config change (finding @ `:85`) - -### Problem - -`unrecoverablePhrase` (the sole surviving copy of a mnemonic when every -durable store *and* rollback attempt failed, carried by -`WalletCreateRollbackException.mnemonic`) is held in plain -`remember { mutableStateOf(null) }` inside the `@Composable`. -That's deliberately not `rememberSaveable` (so the plaintext never -serializes into the saved-state `Bundle` — correct instinct) but as a -result it also doesn't survive activity recreation from rotation, -locale, or theme changes, which discards the composition and loses the -only copy — the underlying wallet creation already ran, Room rows -exist, but they're now permanently seedless with no recovery path. - -There is no existing ViewModel for this screen; wallet creation runs -on `rememberCoroutineScope()`, not `viewModelScope`. - -### Chosen approach - -*(Revised after multi-agent spec review — the coroutine-scope change -originally proposed here was dropped; see "Spec review findings" -below.)* - -Add `CreateWalletViewModel : ViewModel()` holding -`unrecoverablePhrase` as a plain `mutableStateOf` property — -the same shape `TokenActionViewModel` already establishes elsewhere in -this app module (plain `ViewModel`-retained `mutableStateOf`, not -`SavedStateHandle`-backed) — so it survives config-change-driven -recreation via the normal `viewModel()` retention contract, without -ever touching `SavedStateHandle`/the Bundle: - -```kotlin -class CreateWalletViewModel : ViewModel() { - var unrecoverablePhrase by mutableStateOf(null) - private set - - fun recordUnrecoverablePhrase(phrase: String) { - unrecoverablePhrase = phrase - } - - /** Explicit scrub once the user has acknowledged the backup dialog. */ - fun clearUnrecoverablePhrase() { - unrecoverablePhrase = null - } - - override fun onCleared() { - unrecoverablePhrase = null - super.onCleared() - } -} -``` - -`CreateWalletScreen` takes `viewModel: CreateWalletViewModel = -viewModel()` (standard Compose factory). **The wallet-creation -coroutine itself keeps launching on `rememberCoroutineScope()`, as -today** — only *where the caught phrase is stored* changes. The -`WalletCreateRollbackException` catch calls -`viewModel.recordUnrecoverablePhrase(phrase)` instead of assigning -local `remember` state; the emergency dialog reads -`viewModel.unrecoverablePhrase` and calls -`viewModel.clearUnrecoverablePhrase()` on acknowledgement — same UX, -same non-dismissable-until-acknowledged shape, just backed by -ViewModel state instead of composition-scoped `remember`. This is -deliberately the smallest change that closes the named finding: the -finding is about the phrase being lost *after* it was already -successfully caught (a later rotation wipes the composition's -`remember` state); it is not about the creation coroutine surviving -mid-flight cancellation, which is a different (and not reported) -concern. Moving the *launch* itself onto `viewModelScope` was -considered and rejected — see "Spec review findings" #3. - -`String` immutability means true byte-level zeroization isn't possible -here (same platform limitation the finding implicitly accepts by -saying "explicitly scrubbed... field," not "zeroized bytes") — the -`clear`/`onCleared` calls null the reference promptly, which is the -practical ceiling for a JVM `String`. No existing code in this app -module holds secrets in a `ViewModel`, so this establishes a new (but -narrow, single-field) pattern rather than reusing one — noted for -awareness, not a blocker. - -### Alternatives rejected - -- **`rememberSaveable` with a custom `Saver` that encrypts before - serializing.** Rejected: still writes ciphertext into the - saved-state `Bundle`, which can be included in Android's automatic - backup / restored on a different security surface than intended; - the finding explicitly calls for avoiding `SavedStateHandle`/Bundle - entirely, and `ViewModel` retention already solves the actual - problem (surviving config change) without that exposure. -- **Process-level singleton / repository holding the phrase.** - Rejected: broader lifetime than needed (a `ViewModel` scoped to this - screen's `NavBackStackEntry` already outlives config changes and is - cleared on real navigation-away, which is the right lifetime — a - singleton would need its own manual clearing discipline for no - benefit). - -### Test plan - -Kotlin unit test (Robolectric not required — pure `ViewModel` logic, -no Room/Compose): `CreateWalletViewModelTest.kt` — -`recordUnrecoverablePhrase` sets the field; -`clearUnrecoverablePhrase`/`onCleared()` (via -`ViewModelStore.clear()`) null it. This is a pure-JVM test unlike the -findings in §1/§2, so it's the one item in this spec I can actually -compile-check locally now that JDK 17 + the Android SDK were located -on this machine — I'll run `./gradlew :app:testDebugUnitTest` for it -alongside the others. - ---- - -## Cross-cutting test plan - -All four items get real `./gradlew :sdk:testDebugUnitTest -:app:testDebugUnitTest` runs before this is called done — the earlier -report that I couldn't test Kotlin locally was wrong; JDK 17 -(`openjdk@17` via Homebrew) and the Android SDK (`platforms/android-35`, -`build-tools/35.0.0`) are both present on this machine, just not on -the default `java_home`/`ANDROID_HOME` search path this session -started with. - -## Open questions for sync (before coding) - -1. §2, tombstone rejection UX: confirm "abort registration/key-add - with a clear error" is correct for both - `CreateIdentityScreen`/`IdentityKeyAdditionFlow`, vs. some retry/ - silent-skip behavior. -2. §2 is the largest, most fund/key-safety-critical piece of this - spec (touches `WalletStorage`'s locking and storage format - indirectly via the new tombstone set). Confirm you want it done in - this pass rather than split into its own follow-up PR after #3999 - lands — it's the one item where "ship it now" vs. "land the other 3 - and follow up" is a real tradeoff given the review-cycle history on - this branch already (140 review passes, most from automated - reviewers finding new issues on each push). -3. §2, accepted gap: `storePrivateKey`'s nullable `ownerWalletId` - bypasses the tombstone/owner-index union entirely for a null-owner - call. No current caller passes null on the derive/register path, so - this is flagged rather than closed (closing it means auditing every - `storePrivateKey` call site to require an owner). Confirm you're - fine leaving this as a documented gap rather than widening the API - change to cover it now. diff --git a/packages/dashpay-contract/README.md b/packages/dashpay-contract/README.md index 7e87e8cb45d..8c36e98903a 100644 --- a/packages/dashpay-contract/README.md +++ b/packages/dashpay-contract/README.md @@ -59,6 +59,11 @@ To run tests, simply run npm test ``` +## Design notes + +- Count proofs are public. Never add a countable index on `contactRequest` that groups by sender under a recipient, such as `[toUserId, $ownerId]`: it would let anyone list who contacted whom, with counts. A count keyed on `toUserId` alone reveals only a total. +- Ignoring a sender is local to each device. If it ever syncs across devices, it must be one list the owner encrypts to themselves, not a `contactInfo` document per ignored sender. A `contactInfo` about someone who is not a contact exists publicly, and its creation time lines up with the incoming `contactRequest`, which reveals who was ignored. + ## Contributing Feel free to dive in! [Open an issue](https://github.com/dashpay/platform/issues/new/choose) or submit PRs. diff --git a/packages/kotlin-sdk/CLAUDE.md b/packages/kotlin-sdk/CLAUDE.md index 68c2ff5a77b..bdca8c34ef9 100644 --- a/packages/kotlin-sdk/CLAUDE.md +++ b/packages/kotlin-sdk/CLAUDE.md @@ -46,6 +46,11 @@ are data encrypted under Keystore-wrapped AES keys). `GlobalRef`s. - `PlatformWalletManager` is network-locked at construction. Network switch = destroy + new instance (`WalletManagerStore`), never reconfiguration. +- Screens read Room `Flow`s or snapshot data copied at the JNI boundary. They + never hold a native handle wrapper in composition: `NativeCleaner` can free + it in the middle of a read. +- Bridge an FFI function only when the reference Swift app has a caller for + it. ## Building @@ -84,6 +89,13 @@ export DASH_GRADLE_BUILD_ROOT=/Volumes/DashBuild/gradle-build - Instrumented tests (`sdk/src/androidTest`): FFI smoke test (`FfiSmokeTest`) is the A-M1 gate — library loads, version resolves, SDK handle round-trips. +- JVM and Robolectric tests never load `libdash_sdk_jni`. JNI symbol names, + the hand-written method descriptors in `rs-unified-sdk-jni` and argument + marshaling are exercised only by the instrumented tests, and a mismatch + fails at runtime, not at compile time. Change a Rust descriptor and its + Kotlin signature in the same commit, and extend `FfiSmokeTest` + (`persistenceBridgeDescriptorsAllResolve`) and `WalletManagerRoundTripTest` + when adding a persistence or callback slot. - Testnet integration tests are tagged and opt-in (`-Ptestnet=true`). ## Keeping parity with iOS @@ -92,3 +104,17 @@ The reference implementation is `packages/swift-sdk` + its SwiftExampleApp. When porting behavior, cite the Swift source file in the KDoc. Reuse iOS accessibility identifier strings verbatim as Compose `testTag`s for cross-platform UAT parity. + +Parity status lives in `docs/sdk/sdk-parity-manifest.json`. After a +capability changes, edit the manifest and run +`python3 scripts/check_sdk_parity_manifest.py --write-summary`; CI rejects a +stale `PARITY_SUMMARY.md`. Never hand-edit counts in `PARITY.md` or +`PARITY_SUMMARY.md`. The rules the manifest encodes: + +- A capability is `supported` only when it names an automated test or a + recorded device or manual gate. +- Recovery is part of parity: where durable state or on-chain value exists, a + flow is ported only when it resumes after process death, so its `restart` + must be `tested`. +- Differences in visual layout are not parity failures when the capability, + accessibility identifiers and behavior match. diff --git a/packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md b/packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md index 13784fd4003..1cb02d3fa80 100644 --- a/packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md +++ b/packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md @@ -121,7 +121,7 @@ Most Platform actions have hard preconditions. Establish these fixtures before s | ID | Action | Layer | Tier | Status | Tags | Entry point & test notes | |---|---|---|---|---|---|---| -| ID-01 | Create identity (Core-funded asset lock) | Cross | Essential | ✅ | | `CreateIdentityScreen` / `IdentityRegistrationController` → `platform_wallet_register_identity_with_signer`. New identity + credit balance appear. | +| ID-01 | Create identity (Core-funded asset lock) | Cross | Essential | ✅ | | `CreateIdentityScreen` / `IdentityRegistrationController` → `platform_wallet_register_identity_with_signer`. New identity + credit balance appear. After a fresh six-key registration, fetch the identity and check that keys 4 and 5 are ECDSA ENCRYPTION / DECRYPTION MEDIUM keys bound to the DashPay contract id and `contactRequest` (the `RegistrationKeys` table). A successful Add Contact does not prove the bounds; no unit test can see what the node stored. | | ID-02 | Load / discover identity from wallet | Platform | Essential | ✅ | | `LoadIdentityScreen` / `SearchWalletsForIdentitiesScreen` → `platform_wallet_discover_identities`. | | ID-03 | View identity (info / balance / revision / keys) | Platform | Essential | ✅ | | `IdentityDetailScreen`, `KeysListScreen`, `KeyDetailScreen`. | | ID-04 | Transfer credits identity → identity | Platform | Essential | ✅ | | `IdentityDetailScreen` → **Transfer Credits** (dialog, `TransferCreditsScreen`) → `platform_wallet_transfer_credits_with_signer` (Keystore-signed). Recipient entered via `RecipientPicker` (local identity / paste base58 id / DPNS name). | @@ -137,6 +137,7 @@ Most Platform actions have hard preconditions. Establish these fixtures before s | ID-14 | Credit transfer between two on-device identities (A → B) | Platform | Thorough | ✅ | multiwallet | `IdentityDetailScreen` → **Transfer Credits** (`ID-04`), recipient = wallet B's identity (via `RecipientPicker`). Switch to B; verify credit balance rose. | | ID-15 | Same identity restored into two wallets (duplicate seed) | Platform | Uncommon | ✅ | multiwallet | Importing the same mnemonic as a second wallet derives the **same** identity; verify consistency. | | ID-16 | Resume identity top-up from a tracked asset lock | Cross | Manual | 🚧 | | Source UI selects the Rust-tracked exact outpoint, excludes locks bound to another identity, and reaches the compiled tracked-lock list/free and existing-lock registration/top-up JNI bridges. Device gate: interrupt after Core broadcast, restart, resume the same Built transaction/outpoint, and verify foreign/untracked/consumed locks return typed failures without creating a replacement funding transaction. | +| ID-17 | Signing after biometric re-enrollment | Platform | Manual | ✅ | | Physical device with auth-gated Keystore keys. Re-enroll biometrics (add or remove a fingerprint or face), then sign any identity transition: expect `SigningKeyUnavailable` (code 31). Repair the key from the wallet's key-health sheet (`WalletKeyHealthSheet` → `PlatformWalletManager.repairIdentityKey`); the next sign succeeds. The CI emulator cannot re-enroll biometrics, so the invalidation recovery is pinned only through the fake Keystore at the unit tier. | ### 4.3 Platform Addresses (DIP-17 credit addresses) — `Domain=Address` @@ -333,7 +334,7 @@ Membership of each feature category across **all** sections (primary section mem - **Document** — `DOC-01..15` - **Token** — `TOK-01..20` - **Shielded** — `SH-01..17` -- **DashPay** — `DP-01..19` (`DP-12..19` = invitation create, claim, persistence, reclaim; funded evidence 2026-07-23 in `docs/dashpay/KOTLIN_INVITATIONS_SPEC.md` §7) +- **DashPay** — `DP-01..19` (`DP-12..19` = invitation create, claim, persistence, reclaim; funded run 2026-07-23) - **System / Diagnostics** — `SYS-01..08` ### Tag index diff --git a/packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/wallet/DashPayUnlockAndSyncTest.kt b/packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/wallet/DashPayUnlockAndSyncTest.kt index b6f66ea5ca6..9fd179b594c 100644 --- a/packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/wallet/DashPayUnlockAndSyncTest.kt +++ b/packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/wallet/DashPayUnlockAndSyncTest.kt @@ -22,7 +22,7 @@ import org.junit.runner.RunWith /** * Instrumented coverage for the K2 seedless-unlock topology and the - * DashPay sync-service lifecycle (KOTLIN_MIGRATION_SPEC.md §K2), through + * DashPay sync-service lifecycle, through * the real native lib: * * - The **happy-path unlock is the end-to-end proof of the out-buffer diff --git a/packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/wallet/WalletManagerRoundTripTest.kt b/packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/wallet/WalletManagerRoundTripTest.kt index 34ec9d4ade4..77154af19e8 100644 --- a/packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/wallet/WalletManagerRoundTripTest.kt +++ b/packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/wallet/WalletManagerRoundTripTest.kt @@ -119,7 +119,7 @@ class WalletManagerRoundTripTest { * * Of the K1 getters, `searchDpnsNames` is deliberately untested here: * it is a live network query and belongs to the `-Ptestnet=true` - * tier (KOTLIN_MIGRATION_SPEC.md §7.4). + * tier. */ @Test fun dashPayRestoreRoundTripsPaymentsContactProfilesAndSyncState() = runBlocking { diff --git a/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/DashDatabase.kt b/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/DashDatabase.kt index 94ebbb0267f..e74e3b00954 100644 --- a/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/DashDatabase.kt +++ b/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/DashDatabase.kt @@ -684,6 +684,13 @@ abstract class DashDatabase : RoomDatabase() { * API 16+; writes go through the persistence handler inside * `withTransaction`, mirroring the changeset bracketing contract of * `platform-wallet-ffi`. + * + * Room runs WAL with `synchronous=NORMAL`: a committed transaction + * survives process death, but a power loss can roll back the most + * recent commit. That is accepted for every persistence capability + * the handler attests (the same class of risk as iOS); + * `synchronous=FULL` was deliberately not adopted because it costs + * an fsync on every commit. */ fun create(context: Context): DashDatabase = Room.databaseBuilder(context, DashDatabase::class.java, DATABASE_NAME) diff --git a/packages/rs-platform-wallet/PERSISTENCE_REDESIGN.md b/packages/rs-platform-wallet/PERSISTENCE_REDESIGN.md deleted file mode 100644 index 23609bcb8b8..00000000000 --- a/packages/rs-platform-wallet/PERSISTENCE_REDESIGN.md +++ /dev/null @@ -1,1017 +0,0 @@ ---- -title: "Persistence Redesign — BDK-style changesets across key-wallet and platform-wallet" -type: refactor -status: in-progress -date: 2026-04-08 -updated: 2026-04-10 ---- - -# Persistence Redesign - -Living plan for the BDK-style changeset persistence work that spans -`rust-dashcore/key-wallet` and `platform/packages/rs-platform-wallet`. -Supersedes the "PR-22 ChangeSet-based persistence" row in `PLAN.md` — that -was the first attempt, which grew stale and has been partially rewritten. - -Branches (all called `feat/platform-wallet2` in their respective repos): - -- **rust-dashcore** `feat/platform-wallet2` — base `v0.42-dev` -- **platform** `feat/platform-wallet2` — base `feat/platform-wallet` - -## Why - -The original `feat/platform-wallet` attempt modified dashcore's -`WalletManager` to use per-wallet `Arc>` locks and a -`WalletPersistence` trait baked into the manager. It caused 7× SPV -slowdown from lock contention. - -`feat/platform-wallet2` takes a different approach: - -- Keep dashcore's `WalletManager` **identical to `v0.42-dev`** — no - per-wallet locks, no baked-in persistence. -- Build persistence on top of a **BDK-style changeset API** that - every wallet mutation emits, and that an external persister consumes - at its own pace. -- The changeset carries the wallet's **native types** (`Utxo`, - `TransactionRecord`, `ManagedIdentity`) rather than flattened - persistence-friendly entries. Persistence backends translate at - the storage layer. - -## Shape of the design (BDK pattern) - -The mental model is BDK's `apply_block` / `apply_changeset` — mutation -methods return a `ChangeSet` describing what changed; apply methods -consume one to restore state during load. - -**Key-wallet side (`rust-dashcore/key-wallet`):** - -``` -WalletChangeSet -├── account_keys : Option // HD accounts added -├── chain : Option // synced height / block hash -├── balance : Option // cached balance delta -└── per_account : BTreeMap - // one bucket per ManagedCoreAccount - -AccountChangeSet -├── addresses_used : BTreeSet
-├── highest_used : BTreeMap -├── utxos_added : BTreeMap // native type, not flattened -├── utxos_spent : BTreeSet -├── utxos_instant_locked: BTreeSet -└── transactions : BTreeMap -``` - -**Mutation API:** every per-account mutation method on `ManagedCoreAccount` -returns `(value, WalletChangeSet)`. The method writes into -`cs.per_account[self.account_type.to_account_type()]` directly — no -address-based routing at accumulation time. - -**Apply API:** `ManagedWalletInfo::apply_changeset(wallet, cs)` delegates -per-bucket to `ManagedCoreAccount::apply_changeset(account_type, bucket)` -via a direct `get_by_account_type_mut` lookup. No scanning, no fallbacks. - -**Invariants:** -- Idempotent — applying the same changeset N times = applying it once. -- Monotonic on state flags — `is_confirmed` / `is_instantlocked` OR'd - on replay; never regress. -- No re-emission — apply doesn't return a new changeset. -- Best-effort routing — buckets with unknown `AccountType` are silently - skipped with a `tracing::warn!`. -- Loud on `account_keys` failures — a missing account cascades, so - errors bubble up. - -**Platform-wallet side (`packages/rs-platform-wallet`):** - -`PlatformWalletInfo` wraps a `ManagedWalletInfo` inside `core_wallet` and -adds four platform-specific fields: - -- `identity_manager` — registered identities, DPNS names, top-ups -- `tracked_asset_locks` — asset lock lifecycle (created → IS-locked → used) -- `platform_address_balances` — credit balances per platform address -- `token_balances` / `token_watched` — Platform token balances - -Each gets its own sub-changeset. The top-level `PlatformWalletChangeSet` -will look like: - -```rust -pub struct PlatformWalletChangeSet { - pub core: Option, // delegated to core_wallet - pub identities: Option, - pub contacts: Option, - pub platform_addresses: Option, - pub asset_locks: Option, - pub token_balances: Option, // NEW -} -``` - -`PlatformWalletInfo::apply_changeset` will delegate `core` to -`ManagedWalletInfo::apply_changeset` and apply platform-specific -sub-changesets in-place. - -## What's done - -| Phase | Commit | What | -|-------|--------|------| -| **1+2** | `8384ae88` (dashcore) | `changeset` module skeleton, `Merge` trait, `AddressPool::set_highest_used`, `ManagedCoreAccount::{insert,remove}_utxo`, `Wallet::add_account` made idempotent, first round of tests | -| **3+4+5+6** | `66e6462d` (dashcore) | BDK-style mutate-and-return API: every `ManagedCoreAccount` / `ManagedWalletInfo` mutation method returns `(value, WalletChangeSet)`. First review pass flagged: field rename drift, routing gaps, update_utxos state-flag bug. | -| **P3 review fix** | `1d6b6160` (dashcore) | Rename `last_revealed` → `highest_used`; monotonic UTXO state flags on replay; single-address routing strategy in apply; ApplyChangeSet trait extraction | -| **7** | `e018f773` (dashcore) | `ManagedWalletInfo::apply_changeset` restore path — address-routed | -| **7 review fix** | `1d6b6160` (dashcore) | (same commit as above) | -| **7.5 (BDK)** | `c07207a0` (dashcore) | **Structural:** `WalletChangeSet` restructured to BDK-style `per_account: BTreeMap`. Deletes ~5 routing helpers. Mutation methods pre-route at emission time. `AccountType` gets `Ord/PartialOrd/Hash` derives. | -| **7.5 review fix** | `6111c8fb` (dashcore) | `transactions: Vec → BTreeMap` (free last-write-wins on merge, kills O(n²) dedup loop); `update_utxos` inline style; `mark_utxos_instant_send` extend-not-assign bug fix; `PlatformPayment` replay regression fix via `contains_account_type`; `tracing::warn!` on unknown bucket; `apply` → `apply_changeset` rename; ApplyChangeSet trait deleted (unused); `_match` → `_matching` accessor rename; Ord landmine doc comment; stronger mixed-bucket test; stale doc fixes | -| **7.5 (platform wire-through)** | `a193fa3c` (platform) | `PlatformWalletInfo::update_balance` / `mark_instant_send_utxos` return `WalletChangeSet` — trait signature match | -| **8** | `45a9b126` (dashcore) + `c89f8412` (platform) | Drop `add_to_state` flag from address generation — every real caller was passing `true`, the one internal `false` was vestigial, the `false` branch produced ghost addresses. Net -14 LOC. **Also being extracted as a standalone PR off base branches** (see "Open PRs" below) because it's conceptually independent. | - -## Commit chain - -``` -c89f8412 (platform) refactor(platform-wallet): drop add_to_state arg -45a9b126 (dashcore) refactor(key-wallet): drop add_to_state flag -6111c8fb (dashcore) fix(key-wallet): Phase 7.5 review pass -c07207a0 (dashcore) refactor(key-wallet): BDK-style per-account changeset shape -1d6b6160 (dashcore) fix(key-wallet): Phase 7 review pass on apply_changeset -e018f773 (dashcore) feat(key-wallet): apply_changeset for idempotent restore -66e6462d (dashcore) feat(key-wallet): BDK-style mutate-and-return changesets -8384ae88 (dashcore) feat(key-wallet): changeset module + prep work -b8ffa26f (dashcore) feat(key-wallet-manager): insert_wallet + get_wallet_and_info_mut - (preceded by v0.42-dev head: dda1db7a) -``` - -Tests at each step: key-wallet 491 passing, key-wallet-manager 39 passing, -key-wallet-ffi compiles clean, platform-wallet compiles clean. - -## Where we are right now - -Mid-Phase-9a. The decision fork on `PlatformWalletChangeSet` was -resolved in favour of **Option A — unify** (the platform-wallet-local -sub-changeset types are legacy from the evo-tool migration and should -be deleted in favour of embedding `key_wallet::changeset::WalletChangeSet`). - -**Survey findings** (completed task P9a-1): - -`PlatformWalletChangeSet` at -`packages/rs-platform-wallet/src/changeset/changeset.rs:368` currently -has its own copies of: - -- `ChainChangeSet` (line 37) — duplicates `key_wallet::changeset::ChainChangeSet` -- `TransactionChangeSet` + `TransactionEntry` (lines 69, 92) - — duplicates key-wallet's, but with a flattened `TransactionEntry` - that drops most of the native `TransactionRecord` fields (direction, - input/output details, transaction_type, …) -- `UtxoChangeSet` (line 115) — **lossy**: stores - `BTreeMap` (just value!), drops address/script/coinbase/confirmed/etc -- `AccountChangeSet` (line 251) — uses - `BTreeMap<(u32, DerivationPathReference), u32>` keys vs key-wallet's - per-account `BTreeMap` - -All four predate the key-wallet `WalletChangeSet` work. The comment at -the top of the file even says *"Sub-changesets are modelled after the -real types used in `key-wallet`"* — they were always intended as -stand-ins. - -Genuinely platform-specific (keep as-is): -- `IdentityChangeSet` + `IdentityEntry` -- `ContactChangeSet` + `ContactRequestEntry` -- `PlatformAddressChangeSet` + `PlatformAddressEntry` -- `AssetLockChangeSet` + `AssetLockEntry` - -Missing (needs to be added): -- `TokenBalanceChangeSet` — for `PlatformWalletInfo.token_balances` / `token_watched` - -**`PlatformWalletPersistence` trait** at -`packages/rs-platform-wallet/src/changeset/traits.rs:23` already exposes -`store` / `flush` / `load`. The existing skeleton -`PlatformWallet::apply()` at `platform_wallet.rs:236` only wires -`asset_locks.restore_from_changeset_blocking(...)` with TODOs for the -rest — it'll be rewritten to become -`PlatformWalletInfo::apply_changeset`. - -The `queue_persist` / `flush_persist` / `load_persisted` methods on -`PlatformWallet` carry a `TODO: What these methods for? can we remove?` -comment — they're dead plumbing that predates this redesign and will -be replaced by the proper emit/apply flow in Phase 9c/9d. - -**`ApplyChangeSet` trait:** deleted from key-wallet in Phase 7.5-fix -(it was unused outside a single `WalletManager` wrapper). No stale -references remain in platform-wallet. - -## Write-path architecture — one write, one path - -The goal is **one write path per wallet state type**: - -``` -mutation API on PlatformWalletInfo (or core_wallet) - │ returns PlatformWalletChangeSet - ▼ -orchestrator merges changesets into a buffer - │ - ▼ -SqliteWalletPersister flushes buffer → Database::* writer methods → SQLite -``` - -No wallet-state writes bypass the persister. Direct `Database::*` -writes are allowed **only** for tables that have no corresponding -in-memory field on `PlatformWalletInfo` — lifecycle, settings, -caches, and UI metadata. - -### Catalogue of wallet-state tables and their PlatformWalletInfo mapping - -**Covered today (Category A):** - -| Table | PlatformWalletInfo field | Current write status | -|-------|--------------------------|----------------------| -| `utxos` | `core_wallet.per_account[..].{utxos_added,utxos_spent,utxos_instant_locked}` | **Persister-only**: `insert_utxo` has 0 non-test callers; `drop_utxo` has 1 non-persister caller in `model/wallet/utxos.rs::remove_selected_utxos` (tx building) | -| `wallet_transactions` | `core_wallet.per_account[..].transactions` | **Persister-only**: `replace_wallet_transactions` has 0 callers anywhere — dead code | -| `wallet_addresses` | `core_wallet.per_account[..].addresses_used` + `highest_used` | Persister writes subset; some direct writes via address balance updates | -| `wallet.(balance, last_terminal_block)` | `core_wallet.balance`, `core_wallet.metadata.synced_height` | `update_wallet_balances` called directly from backend tasks — duplicate | -| `identity` | `identity_manager.identities[id].identity` | **Duplicate**: `insert_local_qualified_identity` / `update_local_qualified_identity` have ~25 direct call sites across `backend_task/identity/*` AND `sync_identity_to_platform_wallet` mirrors to `IdentityManager` afterwards. Wrong direction — should be mutation-first, persister-second. | -| `top_up` | `identity_manager.identities[id].top_ups` | Same as identity — direct write, then sync | -| `wallet_identity_dpns_names` | `identity_manager.identities[id].dpns_names` (type mismatch: `Vec` vs runtime `Vec`) | Persister-only; table created inline by persister (not in v1.0-dev) | -| `asset_lock_transaction` | `tracked_asset_locks` | Direct writes from `backend_task/identity/register_identity.rs`, `top_up_identity.rs` + persister path — **duplicate** | -| `platform_address_balances` | `platform_address_balances` | `set_platform_address_info` / `delete_platform_address_info` called directly — need to go through changeset | -| `identity_token_balances` | `token_balances` | `insert_token_identity_balance` called directly + persister path — **duplicate** | -| `token` | `token_watched` (partial — metadata NOT in wallet) | Direct writes for token metadata (ticker, name, decimals). Only `token_watched: BTreeSet` is in the wallet; full metadata stays direct. | -| `dashpay_contacts` | `identity_manager.identities[id].established_contacts` | Direct writes from `backend_task/dashpay/*` — should emit contact changeset | -| `dashpay_contact_requests` | `identity_manager.identities[id].{sent,incoming}_contact_requests` | Direct writes from `backend_task/dashpay/*` — should emit contact changeset | - -**Out of scope (Category C — legitimately direct):** - -No in-memory field exists, no reason to add one. These stay as -direct writes: - -- `settings` — theme, password, network, UI state (not wallet state) -- `wallet` lifecycle columns — encrypted seed, salt, nonce, alias, is_main, password_hint, uses_password, core_wallet_name (create/rename/delete wallet) -- `dashpay_profiles` — avatar bytes, display name, public message (**gap candidate**: could add `profile: Option` to `ManagedIdentity` — defer, documented below) -- `dashpay_payments` — payment history (**gap candidate**: per-contact payment log — defer) -- `dashpay_contact_address_indices` — derivation indices for DashPay contact payments -- `dashpay_address_mappings` — address → contact runtime cache -- `contact_private_info` — encrypted local contact metadata (UI layer) -- `contested_name`, `contestant` — DPNS voting state -- `contract` — data contract metadata cache -- `proof_log` — audit trail -- `scheduled_votes` — voting scheduler -- `shielded_notes` — Zcash shielded integration (separate subsystem) -- `single_key_wallet` — legacy migration path -- `identity_order`, `token_order` — UI sort order - -**Gap candidates (Category D — should be in PlatformWalletInfo but aren't):** - -These have existing DB tables but nothing in `PlatformWalletInfo` -tracks them. They'd be legitimate category A once added. Deferred -out of scope for Phase 9a: - -1. **DashPay profiles** → add `profile: Option` on - `ManagedIdentity`. Fields: display_name, public_message, - avatar_hash, avatar_bytes (optional), created_at. -2. **DashPay payments** → add `payments: BTreeMap<(Identifier, Txid), PaymentEntry>` - on `ManagedIdentity` or top-level. Tracks per-contact payment - history with amounts, direction, timestamps. -3. **DashPay contact address derivation indices** → track per-contact - receive index for BIP44 contact payment paths. Currently in - `dashpay_contact_address_indices`. - -## Evo-tool coupling — the DB layer is stable, the persister is not - -Phase 9a-2 (unify `PlatformWalletChangeSet`) immediately breaks -evo-tool's `SqliteWalletPersister` at -`dash-evo-tool/src/changeset/sqlite.rs` because it imports every -deleted type (`ChainChangeSet`, `TransactionChangeSet`, -`TransactionEntry`, `UtxoChangeSet`, `AccountChangeSet`, …). Evo-tool -also has backend-task code in `register_identity.rs`, -`top_up_identity.rs`, and `contact_requests.rs` that constructs those -types directly. - -### What stays — the DB schema and query modules - -Research against evo-tool `v1.0-dev` (the canonical stable branch — -no feat/platform-wallet2 persistence work) confirms the **DB schema -is already rich enough** to hold the new native changeset types: - -- **`utxos`** (`src/database/initialization.rs`, `src/database/utxo.rs`) - — has `txid BLOB, vout INTEGER, address TEXT NOT NULL, value INTEGER NOT NULL, script_pubkey BLOB NOT NULL, network TEXT NOT NULL`. - The current persister writes empty-string placeholders for - `address` / `script_pubkey`; the columns themselves are sufficient - for native `key_wallet::Utxo` data. Missing columns for - `is_coinbase`, `is_confirmed`, `is_instantlocked`, `block_height` - — these are either recomputed on load or would need a schema - migration. -- **`wallet_transactions`** — has - `seed_hash, txid, network, timestamp, height, block_hash, net_amount, fee, label, is_ours, raw_transaction, status`. - Every column that the native `TransactionRecord` needs already - exists. `input_details` / `output_details` / direction / - transaction_type are recomputed from the deserialized - `raw_transaction` on load. -- **`wallet`** (`src/database/wallet.rs`) — has `seed_hash`, balance - columns, `last_terminal_block`, network metadata. Matches - `ChainChangeSet` + `BalanceChangeSet` needs. -- **`wallet_addresses`** — `seed_hash, address, derivation_path, path_reference, path_type`. - Maps to address pools but the relationship to key-wallet's - per-pool `highest_used` needs translation. -- **`platform_address_balances`** — `seed_hash, address, balance, nonce, updated_at, last_full_sync_balance`. - Matches `PlatformAddressChangeSet` 1:1 (with an extra `nonce` - column that the native platform_address_balances BTreeMap doesn't - carry — that's a gap, either drop the nonce column or add a nonce - field to the runtime state). -- **`asset_lock_transaction`** — has every field - `AssetLockEntry` carries (transaction_data, amount, instant_lock_data, - chain_locked_height, identity_id, account_index, funding_type, - identity_index, proof_data). -- **`identity`**, **`top_up`**, **`dashpay_*`** — identity metadata, - top-ups, contacts. Match the existing `IdentityChangeSet` / - `ContactChangeSet` shapes (with known gaps: identity timestamps, - contact metadata). - -### What was introduced by the persister and will be deleted - -- **`wallet_account_state`** — not in v1.0-dev. Created inline by - `SqliteWalletPersister::persist_accounts` via - `CREATE TABLE IF NOT EXISTS`. Schema: - `(seed_hash, account_index, path_reference, last_revealed, network)`. - **Needs migration decision:** either promote into a first-class - table in `initialization.rs` (keyed by the new per-account shape — - `(account_index, pool_type)` instead of `(account_index, path_reference)`) - or fold the reveal watermark into `wallet_addresses` derivation_path. -- **`wallet_identity_dpns_names`** — not in v1.0-dev. Created inline - by the persister. Schema: `(identity_id, name, network)`. Only - stores string names; `DpnsNameInfo` metadata from the runtime - `ManagedIdentity.dpns_names: Vec` is dropped. - -### Direct writes — the persister doesn't own everything - -The current persister **does not serialize all wallet writes**. -Direct writes that bypass the persister still exist at call sites in -SPV processing and backend tasks, calling domain writer functions -like `Database::insert_utxo`, `drop_utxo`, `replace_wallet_transactions`, -`store_wallet`, `update_wallet_balances`, `store_identities`, etc. - -This means: **the adapter doesn't need to replace all writes — -only the ones the current persister handles.** Direct writes keep -working as-is. The persister becomes a translation layer between -`PlatformWalletChangeSet` and a subset of the existing -`database::*` writer methods. - -### Strategy — thin adapter, not raw SQL - -The current `SqliteWalletPersister` (~1000 LOC) writes raw SQL that -duplicates logic already present in `database/wallet.rs`, -`database/utxo.rs`, `database/identities.rs`, etc. The **right -approach** is to rewrite it as a **thin translation layer**: - -```rust -// Pseudocode for the new SqliteWalletPersister::flush_one: -fn flush_one(&self, wallet_id: WalletId, cs: PlatformWalletChangeSet) -> Result<()> { - let seed_hash = wallet_id; // evo-tool uses WalletId == seed_hash - - // 1. Core wallet deltas from cs.core - if let Some(core) = &cs.core { - // 1a. Chain state → UPDATE wallet.last_terminal_block - if let Some(chain) = &core.chain { - if let Some(h) = chain.synced_height { - self.db.set_wallet_terminal_block(seed_hash, h, ...)?; - } - } - // 1b. Balance delta → recompute absolute + UPDATE wallet.(confirmed|unconfirmed|total)_balance - // (requires reading current balance first — not pure delta) - // 1c. Per-account buckets → iterate and delegate - for (account_type, bucket) in &core.per_account { - // UTXOs added — delegate to Database::insert_utxo per entry - for (outpoint, utxo) in &bucket.utxos_added { - self.db.insert_utxo( - outpoint.txid.as_byte_array(), - outpoint.vout, - &utxo.address, // real Address, not placeholder! - utxo.txout.value, - utxo.txout.script_pubkey.as_bytes(), - network, - )?; - } - // UTXOs spent — delegate to Database::drop_utxo - for outpoint in &bucket.utxos_spent { - self.db.drop_utxo(outpoint, network)?; - } - // Transactions → Database::replace_wallet_transactions (or insert path) - // — the native TransactionRecord has everything the - // existing wallet_transactions row needs - // highest_used → wallet_account_state (if we keep this table) - // OR update wallet_addresses based on the bucket's - // addresses_used + pool-type discriminator - } - } - - // 2. Platform-specific sub-changesets — existing delegation points - if let Some(asset_locks) = &cs.asset_locks { - for entry in asset_locks.asset_locks.values() { - self.db.store_asset_lock_transaction(seed_hash, entry, ...)?; - } - } - if let Some(identities) = &cs.identities { - self.db.store_identities(seed_hash, identities.identities.values(), ...)?; - } - // ... etc - - Ok(()) -} -``` - -**Key property:** every SQL statement lives in `database/*.rs`; the -persister is just translation + routing. Much smaller (~200 LOC vs -~1000), no raw SQL duplication, and writes go through the same -paths as the "direct writes" that bypass the persister — which -means the two paths can't diverge. - -### Gaps that need resolution before landing - -1. **Balance delta tracking.** The native `BalanceChangeSet` is a - *delta* (signed). The existing `wallet` table stores *absolute* - values. The adapter must either: - - Read the current balance, apply the delta, write the absolute. - (Racey if another writer races — but we hold the WalletManager - write lock at this point, so OK.) - - Store deltas-over-time, compute absolute on load. (Bigger - change, not worth it now.) - - **Or punt**: balance recompute happens on every - `update_balance()` call which re-derives from UTXOs. The - persister doesn't need to write balance at all — the next load - will recompute from the persisted UTXO set. -2. **`wallet_account_state` — keep or fold in?** The new per-account - shape is keyed by `AccountType` (enum) + `AddressPoolType` per - pool. The existing `wallet_account_state` uses - `(account_index, path_reference)`. Decision: **keep the table, - migrate the schema** to `(account_type_discriminant, - account_index, pool_type, last_revealed)`. One commit, additive. -3. **Identity timestamps** (`last_updated_balance_block_time`, - `last_synced_keys_block_time`). Not persisted today; they're - ephemeral cache on `ManagedIdentity`. Either add columns to - `identity` or accept them as runtime-only. **Decision: runtime - only.** They're just "don't hammer the network" timestamps, not - authoritative state. -4. **DPNS names as `Vec` vs `Vec`.** Pre-existing - data-shape mismatch. The current persister stores only strings, - dropping `DpnsNameInfo` metadata (expires_at, document_id). - **Decision: fix during this pass** — update `IdentityEntry.dpns_names` - to `Vec` and the persister to store the metadata. -5. **Contacts stored per-identity at runtime, at wallet level in - changeset.** Pre-existing data-shape mismatch. `ContactChangeSet` - uses `(from_identity, to_identity)` tuples keyed at the wallet - level, but `ManagedIdentity` holds `established_contacts`, - `sent_contact_requests`, `incoming_contact_requests` per-identity. - **Decision: fix during this pass** — route contact entries into - the owning `ManagedIdentity` on apply; change `ContactChangeSet` - to key by `(owner_identity_id, contact_identity_id)` matching - the DB tables. - -## What's next — Phase 9 breakdown - -Ordering matters here because platform-wallet and evo-tool share types -via path-dep. Breaking evo-tool's build is OK between sibling commits -on the same branch, but we want to land fixes paired so CI can go -green within a few commits of each other. - -### 9a-1 ✅ platform-wallet restructure (committed as `44d15fac`) - -Unified `PlatformWalletChangeSet`: -- Embedded `core: Option`. -- Deleted duplicate `ChainChangeSet`, `TransactionChangeSet`, - `TransactionEntry`, `UtxoChangeSet`, `AccountChangeSet`, and - `PlatformAddressEntry` (latter folded into - `PlatformAddressChangeSet.addresses: BTreeMap` - matching runtime shape). -- Added `TokenBalanceChangeSet`. -- Bridged platform-wallet's richer `Merge` trait to key-wallet's - via a one-off impl on `WalletChangeSet`. -- platform-wallet builds and its 72 unit tests pass. - -**Status:** landed. Evo-tool's current `feat/platform-wallet2` does -NOT build until 9a-4 lands. - -### 9a-2 platform-wallet mutation methods return changesets - -**Where:** platform-wallet, across: -- `src/wallet/identity/manager.rs` — `IdentityManager::add_identity`, - `remove_identity`, `set_label`, `set_last_scanned_index`, - `set_primary_identity`. And the per-identity mutations on - `ManagedIdentity`: `add_dpns_name`, `add_top_up`, - `update_balance_block_time`, `update_keys_sync_block_time`. -- `src/wallet/identity/managed_identity/contact_requests.rs` — - `add_sent_contact_request`, `add_incoming_contact_request`, - `remove_sent_contact_request`, `remove_incoming_contact_request`. -- `src/wallet/asset_lock/manager.rs` — `record_asset_lock`, - `update_status` (created → IS-locked → chain-locked). -- `src/wallet/platform_addresses/wallet.rs` — direct mutations of - `platform_address_balances` map. -- `src/wallet/tokens/*.rs` — `add_watched_token`, - `update_token_balance`. - -**Goal:** each mutation method returns `PlatformWalletChangeSet` -(or a narrower sub-changeset) instead of `()`. Callers -`result.changeset.merge(cs)` into an accumulator, same pattern as -key-wallet's `ManagedCoreAccount::mark_address_used` etc. - -**Not in scope:** wiring the accumulated changesets to the -persister. That's 9a-5. - -Commit on platform-wallet `feat/platform-wallet2`. Platform-wallet -builds and its unit tests pass. Evo-tool still broken until 9a-4. - -### 9a-3 `PlatformWalletInfo::apply_changeset` (restore path) ✅ - -Landed in two commits: -- `a48aeb3064` — prereq: carry full `EstablishedContact` in - `ContactChangeSet.established` (latent 9a-2 schema bug — auto-establish - paths emitted only the `(owner, contact)` pair, losing the underlying - `ContactRequest`s and making faithful replay impossible). -- (this commit) — `src/wallet/apply.rs` with the canonical - `PlatformWalletInfo::apply_changeset` plus the `apply_identity_entry` - helper on `IdentityManager` and the `apply_*_contact_request` / - `apply_established_contact` helpers on `ManagedIdentity`. - -Final shape: - -```rust -pub fn apply_changeset( - &mut self, - wallet: &mut Wallet, - cs: &PlatformWalletChangeSet, -) -> Result<(), ApplyError> -``` - -Sequencing: `cs.core` → identities (insert + remove + primary fixup + -scan watermark) → contacts (sent / incoming inserts → tombstone removes -→ established promotions, each routed to the owning `ManagedIdentity` by -`(owner, contact)` key) → platform addresses (insert + tombstone) → -asset locks (insert with `amount_duffs` → `amount` rename + tombstone) → -token balances (balance updates + watched/unwatched/removed_balances) → -`update_balance()` recompute and mirror into the lock-free `Arc`. - -Invariants: -- Idempotent (9 unit tests cover insert/remove/double-apply for every - sub-changeset). -- No re-emission — apply returns `Result<(), ApplyError>`. -- Best-effort routing for contacts: orphan owners are - `tracing::warn!`-ed and skipped. -- Loud on core failures: `cs.core` failures (HD account derivation - cascade) propagate as `ApplyError::CoreApply(String)`. - -Apply-side helpers added: -- `IdentityManager::apply_identity_entry(&IdentityEntry)` — in-place - update if the identity already exists, or fresh insert. Mirrors the - merge policy on `IdentityChangeSet` (revision-gated `identity` blob, - union for dpns/top_ups/key_storage). First-inserted identity becomes - primary if no primary is set. -- `IdentityManager::apply_remove(&Identifier) -> bool`. -- `ManagedIdentity::apply_sent_contact_request`, - `apply_incoming_contact_request`, `apply_removed_sent`, - `apply_removed_incoming`, `apply_established_contact` — raw - inserts/removes that skip the auto-establish fast path (it was - already captured at mutation time). - -Deletions: -- The stale `PlatformWallet::apply` (only handled asset locks, had TODOs - for everything else) is now a thin async wrapper that takes the - WalletManager write lock via `get_wallet_mut_and_info_mut` and - delegates to `PlatformWalletInfo::apply_changeset`. -- `AssetLockManager::restore_from_changeset_blocking` — its only caller - was the old `PlatformWallet::apply`, gone. - -**Open follow-up (cross-cutting, both repos) — `apply_changeset` should -consume the changeset by value.** Today both -`PlatformWalletInfo::apply_changeset` (platform-wallet) and -`ManagedWalletInfo::apply_changeset` (rust-dashcore key-wallet) take -`cs: &…ChangeSet`. Every `insert` then has to clone owned data out of -borrowed data: - -- platform-wallet side: `Identity` blobs, `KeyStorage`, `dpns_names`, - `ContactRequest`s, `EstablishedContact`s, `Transaction`s inside - `AssetLockEntry`. -- key-wallet side (bigger blast radius): every `Utxo` and every - `TransactionRecord` in - `ManagedCoreAccount::apply_changeset` is `.clone()`-ed before - insert (`managed_account/mod.rs:745, 768`). The - `Transaction` clone inside each `TransactionRecord` is the heaviest - item in any sync replay. - -For the typical persister-load case (deserialize → apply once → drop) -all of those clones are pure waste — the persister already produced -owned data, we could move it directly into the wallet maps. - -Fix in both crates: - -1. `key_wallet`: switch - `ManagedWalletInfo::apply_changeset(&mut self, wallet, cs: - WalletChangeSet)`. Inside - `ManagedCoreAccount::apply_changeset(account_type, bucket: - AccountChangeSet)` use `into_iter()` / `drain` on each map. The - monotonic-flag merge on UTXOs (`is_confirmed |= existing`) becomes - a `match` on `entry(*outpoint)`: if occupied, take the existing - flags then `into_mut()` or `insert(merged)`; otherwise insert by - value with no clone. -2. `platform-wallet`: switch - `PlatformWalletInfo::apply_changeset(&mut self, wallet, cs: - PlatformWalletChangeSet)`. Same `into_iter()` / `drain` pattern - for every sub-changeset. `apply_identity_entry` and the - `apply_*_contact_request` helpers grow `_owned` variants that - take the entry / request by value. -3. Single-variant API. No `apply_changeset` + `apply_changeset_owned` - overload — the borrow form should be deleted, not co-existed. - Hidden clones are not OK. - -Order: key-wallet first (it's the heavier path and platform-wallet -calls into it via `cs.core`), then platform-wallet. Both land before -9a-5 because the persister adapter is the one caller that benefits -most from the move. - -### 9a-4 round-trip tests on platform-wallet ✅ - -Landed in `apply.rs` as 10 new tests on top of the 9 synthesized-data -tests from 9a-3. Each round-trip test mutates `info_a` via the new -mutation API (which now returns sub-changesets), wraps the captured -sub-changeset into a `PlatformWalletChangeSet`, applies it to a -sibling `info_b`, and asserts convergence. This verifies the round- -trip contract: emitted changesets are faithful enough to rebuild -state via apply. - -Coverage (sync mutation surface): -- `round_trip_add_identity` — IdentityManager::add_identity -- `round_trip_remove_identity_reselects_primary` — - IdentityManager::remove_identity (verifies the primary re-selection - fixup in apply matches the mutation-side selection) -- `round_trip_set_label` — IdentityManager::set_label -- `round_trip_last_scanned_index_watermark` — - IdentityManager::set_last_scanned_index -- `round_trip_dpns_name_and_top_up` — ManagedIdentity::add_dpns_name - + record_top_up via snapshot_changeset -- `round_trip_block_time_updates` — ManagedIdentity timestamp - updates -- `round_trip_sent_contact_request_no_auto_establish` — plain - insert path on add_sent_contact_request -- `round_trip_auto_establish_contact` — incoming + sent → - auto-establish, verifies both pending sets drained on B and the - established contact rebuilt from the carried `EstablishedContact` -- `round_trip_remove_contact_request` — tombstone replay -- `round_trip_double_apply_is_idempotent` — multi-changeset replay - applied twice on B with no divergence - -`core` path: covered by key-wallet's own apply tests; the platform- -wallet integration with `cs.core` is delegated and doesn't need -duplicate coverage here. - -**Deferred — async / SDK-dependent mutation paths:** -The following mutation methods require an `Sdk`, broadcaster, and -`Notify` to construct the manager, so they can't run as plain unit -tests. Their round-trip coverage will land as integration tests in a -9a-4 follow-up: -- `AssetLockManager::{track_asset_lock, advance_asset_lock_status, - remove_asset_lock}` — apply side already covered by the - synthesized-data tests in `apply.rs` -- `TokenWallet::{watch, unwatch, unwatch_identity, sync}` -- `PlatformAddressWallet::{sync_balances, transfer, withdraw, - fund_from_asset_lock}` - -The synthesized-data tests in `apply.rs` already cover the apply -side for all of these — the gap is verifying the *mutation side* -emits a faithful changeset, which only matters once the persister -adapter is wired in 9a-5 / 9a-6 and the data path is exercised -end-to-end. - -Test count: 19 in apply.rs (9 synthesized + 10 round-trip) + 9 -contact workflow integration tests + 81 other lib tests, all green. - -Commit on platform-wallet `feat/platform-wallet2`. - -### 9a-5 rewrite evo-tool `SqliteWalletPersister` as thin adapter - -**Where:** dash-evo-tool `feat/platform-wallet2`, -`src/changeset/sqlite.rs`. - -**Goal:** replace ~1000 LOC of raw SQL with a ~200 LOC translation -layer that delegates to existing `Database::*` writer methods. - -**Scope:** -- Update imports to the new `PlatformWalletChangeSet` shape. -- Rewrite `flush_one` (thin adapter style): - - `cs.core.chain.synced_height` → update `wallet.last_terminal_block` - via existing or new `Database::set_wallet_terminal_block`. - - `cs.core.balance` — **punt.** Balance is recomputed from UTXOs on - load via `update_balance()`. Persister doesn't need to touch - balance columns. - - `cs.core.per_account[..].utxos_added` → `Database::insert_utxo` - with the native `Utxo` fields (real address + script, not - placeholders). - - `cs.core.per_account[..].utxos_spent` → `Database::drop_utxo`. - - `cs.core.per_account[..].transactions` → collect and call - `Database::replace_wallet_transactions` once per wallet. Map - the native `TransactionRecord` to evo-tool's `WalletTransaction` - shape (timestamp, height, block_hash, net_amount, fee, label, - is_ours, raw_transaction, status). - - `cs.core.per_account[..].highest_used` → write to - `wallet_account_state` table. **Migrate schema** to key on - `(seed_hash, account_type_discriminant, account_index, pool_type)` - → `last_revealed`. - - `cs.core.per_account[..].addresses_used` → update - `wallet_addresses` (mark addresses used, extend derivation - state). - - `cs.identities` → `Database::insert_local_qualified_identity` / - `update_local_qualified_identity`. This works because evo-tool's - `QualifiedIdentity` type wraps the dpp `Identity` that - `IdentityEntry` carries. - - `cs.contacts` → `Database::save_contact_request` / - `save_dashpay_contact` per-entry. - - `cs.platform_addresses` → `Database::set_platform_address_info` - per-address. - - `cs.asset_locks` → `Database::store_asset_lock_transaction` per-entry. - - `cs.token_balances` → `Database::insert_token_identity_balance` - per-entry. -- Rewrite `load`: - - Read from the same tables. Return `PlatformWalletChangeSet` - with `core` populated using native key-wallet types. -- Delete the persister-created `wallet_identity_dpns_names` table and - its writer helpers. DPNS names now live inside the persisted - identity blob via `IdentityEntry.dpns_names: Vec`. -- Migrate `wallet_account_state` schema as above (add columns or - drop-and-recreate via evo-tool's migration system). - -**Commit on evo-tool `feat/platform-wallet2`.** - -### 9a-6 rip out duplicate direct writes from evo-tool - -**Where:** dash-evo-tool, across `src/backend_task/`, `src/context/`, -`src/model/wallet/`. - -**Goal:** every write path that currently goes direct to -`Database::*` for a Category A table (from the catalogue above) -instead mutates `PlatformWalletInfo` and relies on the persister -to catch the emitted changeset. - -**Specific call sites to rewire:** - -1. **Identity write-through** (~25 call sites): - - `context/identity_db.rs::insert_local_qualified_identity` — - flip the order: mutate `platform_wallet.identity_manager.add_identity` - first (which emits a changeset), then feed the changeset to - the persister. The direct `self.db.insert_local_qualified_identity` - call goes away. - - Same for `update_local_qualified_identity`. - - Delete `sync_identity_to_platform_wallet` — the mutation IS - the sync. - - All ~25 backend-task call sites now call the mutation API - (which already returns a changeset) and queue it. - -2. **Asset lock writes** (`backend_task/identity/register_identity.rs`, - `top_up_identity.rs`): - - Currently call `store_asset_lock_transaction` directly. - - Flip to `platform_wallet.asset_locks.record_asset_lock` which - returns an `AssetLockChangeSet`. Queue for the persister. - -3. **Platform address balance updates** - (`backend_task/wallet/fund_platform_address_from_wallet_utxos.rs` etc.): - - Currently call `set_platform_address_info` directly. - - Flip to the platform wallet's platform-address mutation API. - -4. **Token balance updates** (`backend_task/tokens/mint_tokens.rs`, - `burn_tokens.rs`, etc.): - - Currently call `insert_token_identity_balance` directly. - - Flip to `platform_wallet.tokens.update_balance` which emits a - `TokenBalanceChangeSet`. - -5. **Transaction building UTXO reservation** - (`model/wallet/utxos.rs::remove_selected_utxos`): - - Currently drops the UTXO from the DB directly when a tx is - being built, to prevent double-spend. - - Flip to a platform-wallet mutation that marks the UTXO as - "reserved" or drops it from the in-memory set, emitting a - changeset. - -6. **SPV integration** — verify: does the SPV event handler - currently feed `TransactionCheckResult.changeset` to the - persister? If not, wire it. If it does, also stop any parallel - direct writes it might be doing. - -**Lifecycle writes stay direct** (Category C): -- `Database::store_wallet` / `remove_wallet` / `set_wallet_alias` / - `set_wallet_core_wallet_name` — wallet existence and metadata, - not state. -- All settings writes. -- All DashPay profile / payment / address mapping writes - (category D, deferred). -- All contract / contested_name / proof_log / scheduled_votes / - shielded_notes / single_key_wallet writes. - -**Commit on evo-tool `feat/platform-wallet2`.** - -### 9a-7 wire persister queue/flush lifecycle - -**Where:** evo-tool, in the platform wallet load/unload path and -SPV event loop. - -**Goal:** every emitted `PlatformWalletChangeSet` from a mutation -call site ends up in `SqliteWalletPersister` via `store(wallet_id, cs)`. -Flush strategy: - -- Immediate flush on `SyncComplete` SPV events. -- Debounced flush 30s after the last `store()`. -- Explicit flush on wallet unload / app shutdown. -- **Never** flush during cold SPV sync — the batching keeps the - buffer merged and writes happen at checkpoints. - -Replace the current `FlushStrategy::Immediate` default with a -scheduled flush driven from SPV events. - -**Commit on evo-tool `feat/platform-wallet2`.** - -### 9a-8 verify + review pass + commit - -cargo check + test across key-wallet, key-wallet-manager, -key-wallet-ffi, platform-wallet, dash-evo-tool. Everything green. -Review pass on the persister rewrite and the write-path rewiring: -rust-quality, simplicity, pattern reviewers in parallel. - -**9a scope does NOT include:** the Category D gaps (DashPay -profiles, payments, contact address indices). Those stay as -direct writes for now and get picked up in a follow-up phase -when the platform wallet grows the corresponding in-memory fields. - -## Phase 9b — Close the Category D gaps (future) - -After 9a lands, a handful of DashPay/wallet-adjacent tables still -have legitimate direct writes because `PlatformWalletInfo` has no -in-memory representation for them. Phase 9b grows the platform -wallet to cover these tables, then migrates their writes through -the changeset flow exactly like Phase 9a does for the Category A -tables. - -Each sub-phase follows the same 5-step pattern: - -1. Add the in-memory field to `PlatformWalletInfo` or `ManagedIdentity`. -2. Add a sub-changeset to `PlatformWalletChangeSet`. -3. Add mutation methods that return a changeset. -4. Extend `PlatformWalletInfo::apply_changeset` to handle the new sub. -5. Extend evo-tool's `SqliteWalletPersister` adapter to translate - the new sub-changeset to the existing DB tables. -6. Flip evo-tool's direct writes to route through the mutation API. - -### 9b-1 — DashPay profiles - -**Table:** `dashpay_profiles` (avatar_bytes, display_name, -public_message, created_at) - -**In-memory:** add `profile: Option` on -`ManagedIdentity`. - -**Writers to flip:** -- `Database::save_dashpay_profile` (dashpay.rs:223) -- `Database::save_dashpay_profile_avatar_bytes` (dashpay.rs:262) - -### 9b-2 — DashPay payment history - -**Tables:** `dashpay_payments` (owner_identity_id, contact_identity_id, -txid, amount) - -**In-memory:** add `payments: BTreeMap<(Identifier, Txid), PaymentEntry>` -on `ManagedIdentity`, where `PaymentEntry` carries amount, direction, -timestamp, status. - -**Writers to flip:** -- `Database::save_payment` (dashpay.rs:521) -- `Database::update_payment_status` (dashpay.rs:552) - -### 9b-3 — DashPay contact address derivation indices - -**Tables:** `dashpay_contact_address_indices` -(owner_identity_id, contact_identity_id, highest_receive_index, -bloom_registered_count) - -**In-memory:** add per-contact derivation state to -`ManagedIdentity.established_contacts`. Matches the key-wallet -`highest_used` pattern but scoped to BIP44 DashPay contact payment -paths. - -**Writers to flip:** -- `Database::update_highest_receive_index` (dashpay.rs:741) -- `Database::update_bloom_registered_count` (dashpay.rs:769) - -### 9b-4 — DashPay address mapping cache (maybe) - -**Table:** `dashpay_address_mappings` (address, contact_identity_id, -network, path_type) - -**Decision needed:** is this a pure runtime cache (ephemeral, never -persisted → out of scope entirely) or a persistence concern? If -the former, drop the table and recompute at load. If the latter, -route via a new sub-changeset. - -**Writers to flip (if persisted):** -- `Database::save_dashpay_address_mapping` (dashpay.rs:827) -- `Database::delete_dashpay_address_mappings_for_contact` (dashpay.rs:919) - -### 9b scope and ordering - -9b-1 through 9b-4 are **independent** and can land in any order -after 9a is complete. Each sub-phase is a self-contained commit -chain (add field → changeset → mutation → apply → evo-tool -persister adapter → direct-write rip-out). - -Estimated size: each sub-phase is smaller than a Phase 9a step -because the plumbing (changeset module, persister, evo-tool -integration points) already exists. The work is almost entirely -mechanical once the pattern is established by 9a. - -## Phase 10+ — Open questions, not planned - -- **Token metadata cache** (`token` table: ticker, name, decimals, - contract ID). Currently direct-write Category C. Could be - promoted to a changeset-driven field if token metadata becomes - wallet-scoped rather than global. -- **Data contract cache** (`contract` table). Similar question — - probably stays global/app-level, not wallet-scoped. -- **Wallet lifecycle via changesets?** Creating and deleting - wallets (the `wallet` table encrypted seed / alias columns) is - currently direct. Arguable whether that's worth changing — - wallet existence isn't really state, it's identity. Probably - leave alone. - -## Open PRs - -- **dashcore `refactor/drop-add-to-state-flag`** (being extracted by - background agent as of 2026-04-10) — Phase 8 refactor, standalone - PR off `v0.42-dev`. No dependency on the rest of this branch; safe - to land independently. -- **platform `refactor/drop-add-to-state-flag`** (same agent) — - companion PR off `feat/platform-wallet`, depends on the dashcore - PR merging first. - -## Review policy - -After each substantive commit, run three reviewer agents in parallel: - -- `rust-quality-engineer` — Rust correctness, unwraps, idempotency, - edge cases -- `code-simplicity-reviewer` — YAGNI, dead code, over-engineering -- `pattern-recognition-specialist` — consistency across mutation sites, - naming, doc comments - -The Phase 3/4/7/7.5 commits all had a review pass that caught real -bugs (the `update_utxos` state-flag gap, the `mark_utxos_instant_send` -assignment clobber, the `PlatformPayment` replay regression). Don't -skip the review round just because the commit "looks small." - -## Decisions log - -Key design calls and why, so we don't relitigate them: - -- **BDK-style mutate-and-return, not compute-and-apply.** BDK's pattern - is simpler at call sites (no two-phase dance) and avoids the - temptation to hide mutations behind a "pure" compute function that - still reads heaps of state. Mutation methods mutate and return a - delta; no separate `compute_*` methods. -- **Native types in changesets, not flattened entries.** The - persister translates native → storage at its layer. Keeps the - changeset API lossless and matches mutation-site output 1:1. -- **Per-account bucketing in `WalletChangeSet::per_account`, not flat - top-level fields.** Pre-routes at emission time. Kills the - multi-account transaction collision bug (same txid in two accounts - with different per-account views). Also kills ~5 routing helpers. -- **`WalletChangeSet` returned from every mutation, not - `AccountChangeSet`.** Uniform return type — one merge pattern at - every call site. Mutation methods know their own `account_type` and - write into `cs.account_bucket(ty)` directly. -- **`ApplyChangeSet` trait deleted.** Unused outside a single - `WalletManager` wrapper. Concrete - `impl WalletManager` is fine; if - `PlatformWalletInfo` needs a similar wrapper later, it can get its - own concrete impl block. -- **No `peek_*` address generation variants.** YAGNI — nothing in the - codebase needed pure-read address derivation. The old `add_to_state` - flag was dead weight. -- **`transactions: BTreeMap`, not `Vec`.** The - map encoding makes "at most one record per txid per account" a type - invariant; merge dedup is free via `BTreeMap::extend`. -- **UTXO state flags are monotonic on replay.** `is_confirmed` / - `is_instantlocked` OR'd with existing entry, never overwritten. - Prevents stale-replay regressions when a live mutation has already - advanced state. -- **Option A on `PlatformWalletChangeSet`** (this document's current - task): embed `key_wallet::changeset::WalletChangeSet` via a `core` - field, delete the legacy evo-tool-migrated duplicate types. The - platform-wallet types were stand-ins from before key-wallet had a - changeset; carrying both forward would be translation-layer tax - forever. - -## Links - -- [`PLAN.md`](PLAN.md) — the full platform-wallet project plan. - This document is a focused plug-in covering the persistence - redesign that supersedes the "PR-22 ChangeSet-based persistence" - row. -- [`key-wallet/CLAUDE.md`](../../../rust-dashcore/key-wallet/CLAUDE.md) - — key-wallet architectural overview. -- [`dash-evo-tool/CLAUDE.md`](../../../dash-evo-tool/CLAUDE.md) - — evo-tool architecture. Key-relevant section: "Database" (single - `Mutex`, domain-specific writer methods in - `src/database/*.rs`). The `v1.0-dev` branch is the canonical - stable base; `feat/platform-wallet2` has the persister work - being rewritten here. -- [`dash-evo-tool/src/database/initialization.rs`](../../../dash-evo-tool/src/database/initialization.rs) - — authoritative `CREATE TABLE` statements for wallet state. -- [`dash-evo-tool/src/changeset/sqlite.rs`](../../../dash-evo-tool/src/changeset/sqlite.rs) - — current `SqliteWalletPersister`. Being rewritten in Phase 9a-2. diff --git a/packages/rs-platform-wallet/PLAN.md b/packages/rs-platform-wallet/PLAN.md deleted file mode 100644 index a17978eaca2..00000000000 --- a/packages/rs-platform-wallet/PLAN.md +++ /dev/null @@ -1,5247 +0,0 @@ ---- -title: "feat: Platform Wallet — Complete Implementation & Evo Tool Integration" -type: feat -status: active -date: 2026-03-13 -updated: 2026-04-08 ---- - -# feat: Platform Wallet — Complete Implementation & Evo Tool Integration - -## Current Status (2026-04-08) - -### What's done - -**All core implementation is complete.** 22 PRs merged, covering the full platform wallet library and evo-tool integration: -- PRs 1–19 ✅: Full library + evo-tool migration (sub-wallets, signing, asset locks, DashPay, tokens, identity, SPV lifecycle) -- PR-22 ✅: ChangeSet-based persistence - -**Recent locking refactoring (committed, all tests passing):** -- Collapsed 7+ independent `Arc>` into a single `Arc>` -- Sub-wallets (CoreWallet, IdentityWallet, etc.) now hold `Arc>` instead of separate locks -- State getters moved from CoreWallet to PlatformWallet (e.g., `wallet.state().balance()` instead of `wallet.core().state().balance()`) -- CoreWallet cleanup: removed broadcaster field, removed dead methods -- Evo-tool fully migrated to new single-lock API - -**Test results:** -- 76 platform-wallet lib tests: **PASS** -- 347 evo-tool lib tests: **PASS** -- Backend E2E tests (testnet): **PASS** (cleanup_only in ~7s, 2026-04-08) - -### Next steps (immediate) - -**PR-30: Switch to dashcore WalletManager** — see detailed spec below. - -### Remaining PRs (future) - -| PR | Description | Status | -|----|-------------|--------| -| PR-20 | ~~Complete identity/asset lock lifecycle~~ Core API done (one-call methods + IS→CL fallback in IdentityWallet). Leftovers in PR-31. | Done | -| PR-21 | ~~Remove remaining duplication~~ TransactionBuilder already unified. Asset lock changeset restore leftover in PR-31. | Done | -| PR-23 | ~~Merge Wallet + ManagedWalletInfo in key-wallet~~ **Superseded** by PR-30 | Superseded | -| PR-24 | Comprehensive test suite + FFI update + final cleanup | Planned | -| PR-25 | Switch asset lock broadcast from DAPI to SPV | Planned | -| PR-26 | ~~Fix lock ordering deadlock~~ **RESOLVED** by single-lock refactoring | Done | -| PR-27 | ~~Merge SpvRuntime + SpvWalletAdapter~~ **Superseded** by PR-30 | Superseded | -| PR-28 | Full SPV replacement — migrate evo-tool SpvManager to PlatformWalletManager | Planned | -| PR-29 | Asset lock test coverage | Planned | -| PR-30 | Switch to dashcore WalletManager — delete SpvWalletAdapter, use BalanceUpdated events | **Next** | -| PR-31 | Leftovers from PR-20/21: evo-tool identity + asset lock cleanup | Planned | - ---- - -## PR-30: Switch to dashcore WalletManager - -### Goal - -Replace platform-wallet's custom `SpvWalletAdapter` (~330 lines), `SpvSyncState` (~55 lines), and `PlatformWalletInfoWriteGuard` (Drop-based balance update) with dashcore's `WalletManager`. This eliminates duplicated multi-wallet iteration logic, duplicated sync height tracking, and the Drop-based balance workaround. - -### Why - -`SpvWalletAdapter` reimplements exactly what `WalletManager` already does: iterate all wallets for each block/mempool transaction, call `check_core_transaction`, track synced heights, and (in WalletManager's case) emit `BalanceUpdated` events. `DashSpvClient` already accepts `Arc>`, and `WalletManager` implements `WalletInterface`. We can pass it directly. - -### Architecture - -``` -PlatformWalletManager - ├─ wallet_manager: Arc>> - │ └─ wallets: BTreeMap>> - │ - ├─ spv_client: DashSpvClient, ..., SpvEventForwarder> - │ └─ wallet: Arc>> (same Arc as above) - │ └─ handler: SpvEventForwarder (on_wallet_event fires automatically) - │ - ├─ wallets: BTreeMap (handles for consumers) - │ └─ each holds clone of Arc> from wallet_manager - │ - ├─ event_tx: broadcast::Sender - └─ sdk: Arc -``` - -**Lock hierarchy during block processing:** -1. DashSpvClient acquires `Arc>` write lock -2. WalletManager iterates `wallets` map (`&mut self` access) -3. For each wallet: acquires `Arc>` write lock -4. `check_core_transaction` runs → mutates state → persists changeset → releases per-wallet lock -5. WalletManager emits `BalanceUpdated` events via broadcast channel -6. DashSpvClient releases WalletManager write lock - -Sub-wallets (CoreWallet, IdentityWallet) go directly to their `Arc>` — skip the manager lock. - -**Event flow:** -``` -WalletManager.event_sender (broadcast) → spawn_broadcast_monitor task - → SpvEventForwarder.on_wallet_event() → PlatformWalletEvent::Wallet(WalletEvent) - → consumers (evo-tool balance updater, asset lock manager, etc.) -``` - -### dashcore changes (rust-dashcore repo) - -**1. New `ManagedWalletState` struct** — bundles Wallet + ManagedWalletInfo + Persister. -`ManagedWalletInfo` stays unchanged (pure UTXO/balance/account state). - -```rust -pub struct ManagedWalletState { - pub wallet: Wallet, - pub wallet_info: ManagedWalletInfo, - pub persister: P, -} -impl WalletInfoInterface for ManagedWalletState

{ - // All ~25 methods delegate to self.wallet_info -} -``` - -**2. `WalletPersistence` trait** — `store(changeset)`, `flush()`. `NoPersistence` for default/tests. - -**3. `WalletInfoInterface` gains `wallet()` / `wallet_mut()`** — so WalletManager can access -the Wallet through T without knowing the concrete type. - -**4. Remove `wallet: &mut Wallet` param from `check_core_transaction`** — T provides its -own wallet. Extract existing logic into `ManagedWalletInfo::check_core_transaction_with_wallet(&mut self, wallet: &Wallet, ...)` helper. `ManagedWalletState` impl calls helper with `&self.wallet` (disjoint field borrow, no borrow-checker issue). Persists changeset synchronously inside the method. - -**5. WalletManager struct change** — single map with per-wallet locks: -```rust -pub struct WalletManager { - wallets: BTreeMap>>, // was: two separate maps - // synced_height, filter_committed_height, event_sender unchanged -} -``` - -**6. Update all WalletManager methods** — wallet creation inserts `Arc::new(RwLock::new(T::from_wallet(&wallet)))`. `check_transaction_in_all_wallets` acquires per-wallet write locks. `get_receive_address`/`get_change_address` extract xpub before mutable borrow. Accessors rewritten for single map. - -### platform-wallet changes - -**1. `PlatformWalletInfo` implements `WalletInfoInterface`** — delegates to `self.wallet_info`. Persister moves from `PlatformWallet` into `PlatformWalletInfo`. `check_core_transaction` calls `self.wallet_info.check_core_transaction_with_wallet(&self.wallet, ...)` and persists `PlatformWalletChangeSet` synchronously. - -**2. Delete `SpvWalletAdapter`** (~330 lines) — replaced by WalletManager's WalletInterface impl. - -**3. Delete `SpvSyncState`** (~55 lines) — WalletManager tracks heights internally. - -**4. Delete `PlatformWalletInfoWriteGuard`** (~25 lines) — balance atomics updated via `BalanceUpdated` events through `SpvEventForwarder.on_wallet_event()`. - -**5. Update `SpvRuntime`** — `DashSpvClient, ...>`. - -**6. Restructure `PlatformWalletManager`** — holds `wallet_manager: Arc>>`, `wallets: BTreeMap` (handles sharing same Arc), `spv_client`. - -**7. Wire `BalanceUpdated` events** — add `update_from_parts(spendable, unconfirmed, immature, locked)` to `WalletBalance`. Event bridge updates atomics. - -### evo-tool changes - -- Update `SpvEventBridge` to handle `PlatformWalletEvent::Wallet(BalanceUpdated{...})` -- Update E2E test harness for new API surface - -### What gets deleted (~410 lines) - -| File | Lines | -|------|-------| -| `spv/wallet_adapter.rs` | ~330 | -| `spv/sync_state.rs` | ~55 | -| `PlatformWalletInfoWriteGuard` | ~25 | - -### Implementation sequence - -Phase 1 (dashcore): Add wallet()/wallet_mut() to trait → extract check_core_transaction helper → create ManagedWalletState + WalletPersistence → change WalletManager to single Arc> map → update all methods/tests/FFI. - -Phase 2 (platform-wallet): Move persister into PlatformWalletInfo → implement WalletInfoInterface → delete SpvWalletAdapter/SpvSyncState/WriteGuard → update SpvRuntime → restructure PlatformWalletManager → wire events. - -Phase 3 (evo-tool): Update event bridge → update E2E tests. - ---- - -## PR-31: Evo-tool identity + asset lock cleanup (leftovers from PR-20/21) - -### Goal - -Clean up remaining gaps from PR-20 (identity lifecycle) and PR-21 (asset lock duplication). Two concrete issues: - -### 1. Evo-tool uses low-level `_with_signer` instead of one-call identity APIs - -**Problem**: Evo-tool's `RegisterIdentityTask` and `TopUpIdentityTask` call the low-level `register_identity_with_signer()` / `top_up_identity_with_signer()` methods and manually implement IS→CL fallback (~40 lines each). Platform-wallet's `IdentityWallet` already has one-call methods (`register_identity_with_funding`, `top_up_identity_with_funding`, `funded_register_identity`, `funded_top_up_identity`) that handle IS→CL fallback internally. - -**Fix**: Switch evo-tool tasks to use the one-call APIs. Delete manual IS→CL fallback code in: -- `dash-evo-tool/src/backend_task/identity/top_up_identity.rs` (lines ~112-190) -- `dash-evo-tool/src/backend_task/identity/register_identity.rs` (lines ~255-298, ~394-430) - -### 2. Asset lock changeset restore is not implemented - -**Problem**: `PlatformWallet::apply()` calls `self.asset_locks.restore_from_changeset_blocking(asset_lock_cs)` but this method doesn't exist. Asset lock changesets are written to the persister (evo-tool's SQLite) but never loaded back. Evo-tool works around this with `register_with_asset_lock_manager()` bridge code that scans the DB and manually re-registers locks with the manager. - -**Fix**: -- Implement `AssetLockManager::restore_from_changeset_blocking()` in platform-wallet — reconstruct `tracked_asset_locks` from `AssetLockChangeSet` -- Verify `PlatformWallet::apply()` actually calls it correctly on wallet load -- Once changeset restore works, simplify evo-tool's `recover_asset_locks.rs` — the bridge code `register_with_asset_lock_manager()` becomes unnecessary since locks are restored from persistence automatically -- Update UI screens (`by_using_unused_asset_lock.rs`) to read from `AssetLockManager.list_tracked_locks()` instead of querying DB directly - -### Files to modify - -**platform-wallet:** -- `src/wallet/asset_lock/manager.rs` — implement `restore_from_changeset_blocking` -- `src/wallet/platform_wallet.rs` — verify `apply()` works end-to-end - -**evo-tool:** -- `src/backend_task/identity/top_up_identity.rs` — switch to one-call API -- `src/backend_task/identity/register_identity.rs` — switch to one-call API -- `src/backend_task/core/recover_asset_locks.rs` — simplify once changeset restore works -- `src/ui/identities/add_new_identity_screen/by_using_unused_asset_lock.rs` — read from manager -- `src/ui/identities/top_up_identity_screen/by_using_unused_asset_lock.rs` — read from manager - ---- - -## Overview - -**Goal**: Replace `dash-evo-tool`'s self-written wallet and duplicated DashPay crypto with `rs-platform-wallet`, building and integrating iteratively — one vertical slice at a time. - -**Approach**: Each PR implements a feature in `rs-platform-wallet` **and** immediately wires it into `evo-tool`, replacing the corresponding old code. Both repos share a feature branch pair (`feat/platform-wallet` in each), linked via `path` dependency in Cargo.toml. No "build everything first, integrate later" — integration is part of every PR. - -**Branch setup**: -- `platform` repo: `feat/platform-wallet` (feature branch, merges to `v3.1-dev` via PRs) -- `dash-evo-tool` repo: `feat/platform-wallet` (feature branch, merges to `v1.0-dev` via PRs) -- `Cargo.toml` in evo-tool: `platform-wallet = { path = "../../platform/packages/rs-platform-wallet" }` - ---- - -## Architecture (current — single-lock design, post-refactoring) - -``` -key-wallet (rust-dashcore) — reused types -├── Wallet ← mutable key store (mnemonic, xprv, accounts added during sync) -├── ManagedWalletInfo ← mutable UTXO state, accounts, balance, address pools -├── ManagedAccountCollection ← BIP44 + DashPay + PlatformPayment + Identity accounts -├── TransactionRouter ← transaction classification + checking -├── WalletTransactionChecker ← trait for tx matching (impl on ManagedWalletInfo) -├── TransactionContext ← Mempool | InstantSend | InBlock(BlockInfo) | InChainLockedBlock(BlockInfo) -└── BlockInfo ← { height, block_hash, timestamp } (all required) - -rs-platform-wallet -├── PlatformWalletInfo ← SINGLE struct behind Arc> -│ ├── wallet: Wallet -│ ├── wallet_info: ManagedWalletInfo -│ ├── identity_manager: IdentityManager -│ ├── tracked_asset_locks: BTreeMap -│ ├── platform_address_balances: BTreeMap -│ ├── token_watched: BTreeMap> -│ └── token_balances: BTreeMap<(Identifier, Identifier), TokenAmount> -│ -├── PlatformWallet ← cheaply cloneable handle to shared state -│ ├── wallet_id: WalletId -│ ├── sdk: Arc -│ ├── core: CoreWallet ← balance, UTXOs, addresses, tx building -│ ├── identity: IdentityWallet ← register, discover, top-up, withdraw, transfer, DPNS -│ ├── dashpay: DashPayWallet ← send/accept contact requests, sync contacts -│ ├── platform: PlatformAddressWallet ← DIP-17 sync, transfer, withdraw -│ ├── tokens: TokenWallet ← per-identity registry, sync, transfer, mint, burn -│ ├── asset_locks: Arc ← build, broadcast, track, proof lifecycle -│ ├── event_tx: broadcast::Sender -│ ├── persister: WalletPersister -│ └── state: Arc> ← THE SINGLE LOCK (all sub-wallets share this) -│ -│ State access: -│ ├── wallet.state() → RwLockReadGuard (async read) -│ ├── wallet.state_mut() → PlatformWalletInfoWriteGuard (async write, auto-updates balance) -│ └── Sub-wallets also hold state: Arc> -│ -├── Sub-wallets (all hold Arc> + Arc) -│ ├── CoreWallet ← state: Arc> -│ ├── IdentityWallet ← state: Arc> -│ ├── DashPayWallet ← state: Arc> -│ ├── PlatformAddressWallet ← state: Arc> + Signer -│ └── TokenWallet ← state: Arc> -│ -├── PlatformWalletManager ← multi-wallet + SPV coordinator (feature-gated: manager) -│ ├── sdk: Sdk -│ ├── wallets: Arc>> -│ ├── event_tx: broadcast::Sender -│ └── spv: SpvRuntime -│ -├── SpvRuntime (src/spv/runtime.rs) ← SPV lifecycle -│ ├── wallets: Arc>> -│ ├── event_tx: broadcast::Sender -│ ├── synced_height: AtomicU32 -│ ├── monitor_revision: Arc -│ ├── finality_waiters: Mutex>> -│ └── client: RwLock> -│ -├── SpvWalletAdapter (src/spv/wallet_adapter.rs) ← multi-wallet WalletInterface -│ └── Iterates ALL wallets for process_block/process_mempool_transaction -│ -├── SpvEventForwarder (src/spv/event_forwarder.rs) ← EventHandler impl -│ -├── Signing -│ ├── IdentitySigner ← Signer -│ ├── ManagedIdentitySigner ← key_storage + IdentitySigner fallback -│ └── PlatformAddressWallet ← Signer -│ -├── Events -│ ├── PlatformWalletEvent ← Wallet(WalletEvent) | Spv(SpvEvent) -│ └── TransactionStatus ← Unconfirmed | InstantSendLocked | Confirmed | ChainLocked -│ -└── [ShieldedWallet] ← PR-15: feature-gated Orchard/Halo2 - -evo-tool integration (current state): -├── Wallet struct embeds Arc — no duplicate fields -├── SPV: evo-tool's SpvManager still runs (old system), PlatformWalletManager bridges events -├── All UI reads go through wallet.state() (lock-free WalletBalance for hot path) -└── 347 lib tests passing -``` - -**Key design decisions:** -- **Single lock**: All mutable state in one `Arc>` — eliminates deadlocks from PR-26. Sub-wallets share the same Arc. `PlatformWalletInfoWriteGuard` auto-updates `WalletBalance` on drop. -- **No WalletHandle**: `PlatformWallet.clone()` is cheap (few atomic increments). A clone is a shared handle to the same state. -- **State access pattern**: `wallet.state()` for async read, `wallet.state_mut()` for async write. Sub-wallets use `self.state.read().await` / `self.state.write().await` internally. -- **Lock ordering eliminated**: With one lock, there's no ordering problem. The old multi-lock design had confirmed deadlock risks between wallet/wallet_info/tracked locks. -- **SPV dual-system**: Evo-tool still runs its own SpvManager alongside PlatformWalletManager. Full SPV replacement is PR-28. - ---- - -## PR History (completed) - -1. **PR-1** ✅: Project scaffold + `PlatformWallet` + `PlatformWalletManager` + `CoreWallet` + evo-tool bridge -2. **PR-2** ✅: CoreWallet deep integration — `Signer`, per-address data, asset locks, transaction sending -3. **PR-3** ✅: `IdentityWallet` — register, discover, top-up, withdraw, transfer, `IdentitySigner` -4. **PR-4** ✅: `DashPayWallet` — contact requests (simplified API), sync, accept -5. **PR-5** ✅: `PlatformAddressWallet` — DIP-17 sync, send, withdraw + review fixes -6. **PR-6** ✅: SPV lifecycle + TransactionStatus + EventHandler -7. **PR-7** ✅: Identity update + address fund flows + DPNS -8. **PR-8** ✅: Token operations — `TokenWallet` -9. **PR-9** ✅: Evo-tool integration Phase 1+2 — token + identity tasks migrated -10. **PR-10** ✅: ManagedIdentity — KeyStorage, IdentityStatus, DPNS names, 12-key discovery -11. **PR-11** ✅: Asset lock lifecycle + multi-mode funding -12. **PR-12** ✅: DashPay DIP-14/15 — 256-bit key derivation -13. **PR-13** ✅: Evo-tool integration Phase 3 — 20 tasks total migrated -14. **PR-14** ✅: Protocol completeness + evo-tool convergence — 27/42 tasks migrated -15. **PR-15** ✅: Shielded pool (feature-gated) -16. **PR-16** ✅: AssetLockFinalityEvent -17. **PR-17** ✅: Use dashcore asset lock builder -18. **PR-18** ✅: Replace evo-tool Wallet model with CoreWallet (~1,600 lines removed) -19. **PR-19** ✅: Migrate remaining Wallet fields (~2,700 lines removed) -22. **PR-22** ✅: ChangeSet-based persistence -**Uncommitted (on feat/platform-wallet):** Single-lock refactoring (PR-26 scope) — 7+ locks → single RwLock, state getters on PlatformWallet, CoreWallet cleanup - ---- - -## PR-6: SPV lifecycle + TransactionStatus + EventHandler - -### Status after v3.1-dev merge (2026-03-31) - -**Already done** (by merging v3.1-dev with dashcore rev `5db46b4d` and fixing compilation): -- `TransactionContext::InBlock(BlockInfo)` — updated from named fields -- `check_core_transaction(&mut wallet, update_state, update_balance)` — extra params adapted -- `process_mempool_transaction(tx, is_instant_send) -> MempoolTransactionResult` — new signature -- `watched_outpoints()` — implemented via `get_spendable_utxos()` -- `TransactionContext::InstantSend` variant — used in mempool processing - -**Cancelled**: `key-wallet-manager` crate merge into `key-wallet` — decision to keep them as separate crates. All imports remain `use key_wallet_manager::*`. - -### What PR-6 now delivers - -**1. TransactionStatus lifecycle tracking** - -Add `TransactionStatus` enum to `events.rs` and per-transaction status tracking in `CoreWallet`: - -```rust -#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] -#[repr(u8)] -pub enum TransactionStatus { - Unconfirmed = 0, // In mempool, no IS lock - InstantSendLocked = 1, // IS-locked, not yet mined - Confirmed = 2, // Mined in a block - ChainLocked = 3, // In a chain-locked block (highest finality) -} -``` - -- Track status per txid in `CoreWallet` (or via `SpvWalletAdapter`) -- Emit `PlatformWalletEvent::Wallet(WalletEvent::TransactionStatusChanged)` on transitions -- `process_instant_send_lock()` on `SpvWalletAdapter`: update status, call `mark_instant_send_utxos()` on WalletInfoInterface -- Pattern from evo-tool: `src/model/wallet/mod.rs` lines 520-577 - -**2. EventHandler implementation** - -Implement `dash_spv::EventHandler` trait on a new `SpvEventForwarder` struct that forwards SPV events to `PlatformWalletEvent` broadcast channel: - -```rust -pub(crate) struct SpvEventForwarder { - event_tx: broadcast::Sender, -} - -impl EventHandler for SpvEventForwarder { - fn on_sync_event(&self, event: &SyncEvent) { /* → PlatformWalletEvent::Spv(SpvEvent::Sync(event)) */ } - fn on_network_event(&self, event: &NetworkEvent) { /* → PlatformWalletEvent::Spv(SpvEvent::Network(event)) */ } - fn on_progress(&self, progress: &SyncProgress) { /* → PlatformWalletEvent::Spv(SpvEvent::Progress(progress)) */ } - fn on_wallet_event(&self, event: &WalletEvent) { /* → PlatformWalletEvent::Wallet(event) */ } - fn on_error(&self, error: &str) { /* → tracing::error! */ } -} -``` - -`EventHandler` trait (from `dash-spv/src/client/event_handler.rs`): -- `on_sync_event(&self, event: &SyncEvent)` — sync lifecycle (headers stored, sync complete) -- `on_network_event(&self, event: &NetworkEvent)` — peer connection changes -- `on_progress(&self, progress: &SyncProgress)` — overall sync progress -- `on_wallet_event(&self, event: &WalletEvent)` — transaction received, balance updated -- `on_error(&self, error: &str)` — fatal errors -- All have default no-op implementations - -**3. Wire SPV lifecycle via `SpvRuntime`** - -SPV lifecycle is managed by `SpvRuntime` (extracted from `PlatformWalletManager`). -`PlatformWalletManager::spv().start(config)` / `spv().stop()` delegates to `SpvRuntime`: - -```rust -// SpvRuntime creates the SpvWalletAdapter (multi-wallet) and SpvEventForwarder -// DashSpvClient - -impl SpvRuntime { - pub async fn start(&self, config: ClientConfig) -> Result<(), PlatformWalletError> { - let adapter = SpvWalletAdapter::new(self.wallets.clone(), self.event_tx.clone(), self.monitor_revision.clone()); - let handler = Arc::new(SpvEventForwarder::new(self.event_tx.clone())); - // ...construct and start DashSpvClient - } -} -``` - -Need to determine concrete types for `N: NetworkManager` and `S: StorageManager` — check what evo-tool uses (likely `PeerNetworkManager` and `DiskStorageManager` from dash-spv). - -**~~4. AssetLockFinalityEvent tracking~~** — deferred to PR-11 (SPV migration) - -Currently `CoreWallet` uses SDK's `wait_for_asset_lock_proof_for_transaction()` which polls DAPI. -The SPV-based approach (listen for IS/CL events via finality channel) requires SPV to be running, -which isn't guaranteed for standalone `PlatformWallet`. Will be implemented when evo-tool's -`SpvManager` is migrated to `SpvRuntime::start()` (via `PlatformWalletManager::spv()`) in PR-11. - -### What was delivered (PR-6 + follow-up) - -| File | Changes | -|------|---------| -| `src/events.rs` | `TransactionStatus` enum, `SpvEvent` (Sync/Network/Progress), `PlatformWalletEvent` (Wallet/Spv) | -| `src/spv/wallet_adapter.rs` | Full `WalletInterface` impl, multi-wallet block/mempool processing, per-tx status tracking | -| `src/spv/event_forwarder.rs` | `EventHandler` impl forwarding SPV sync/network/wallet events to `PlatformWalletEvent` | -| `src/spv/runtime.rs` | `SpvRuntime` — SPV lifecycle, finality waiters, `start(config)`/`stop()` | -| `src/manager.rs` | `PlatformWalletManager` — CRUD + `spv()` accessor | -| `src/wallet/core/wallet.rs` | `transaction_statuses` map, `transaction_status()`, `update_transaction_status()` (monotonic) | -| `src/error.rs` | `SpvAlreadyRunning`, `NoWalletsConfigured`, `SpvError` variants | -| `Cargo.toml` | `dash-spv` dependency under `manager` feature gate | - ---- - -## PR-1 Status: Complete - -### What was delivered - -**Platform-wallet library** (`rs-platform-wallet`): -- `PlatformWallet` — standalone wallet with sub-wallets as stored fields, cheaply cloneable (all Arc fields) -- `CoreWallet` — balance, UTXOs, spendable UTXOs, address generation, monitored addresses, transaction history, immature transactions, synced/birth height, network -- `IdentityWallet`, `DashPayWallet`, `PlatformAddressWallet` — struct stubs sharing `wallet_info` and `wallet` Arcs -- `IdentitySigner` — stub for state transition signing -- `PlatformWalletManager` — multi-wallet coordinator with create/import/remove/list/get, event subscription -- `SpvWalletAdapter` — implements `WalletInterface` for SPV integration -- `IdentityManager` — refactored (no sdk field, added last_scanned_index) -- Events: `PlatformWalletEvent` (Wallet/Spv), `WalletEvent`, `SpvEvent`, `TransactionStatus` -- No `WalletHandle` — `PlatformWallet.clone()` is cheap (~35 atomic ops) -- `Wallet` stored as `Arc>` (mutable — accounts added during contact establishment/sync) -- Clean `mod.rs` files (module defs + re-exports only) -- `Send + Sync` assertions in `tests/thread_safety.rs` - -**Evo-tool integration** (`dash-evo-tool`): -- `PlatformWalletManager` added to `AppContext` with `DebugWrapper` -- `platform_wallets` bridge map (keyed by `WalletSeedHash`) + `WalletIdMapping` (bidirectional) -- Wallet creation/import/unlock registers with bridge via `register_with_platform_wallet_manager()` -- Lock/remove/clear cleans up bridge -- `get_platform_wallet()` / `require_platform_wallet()` helpers -- 7 backend tasks validate via bridge at entry point -- `generate_receive_address` has diagnostic logging comparing old vs new paths -- `transfer_to_addresses` tries `platform_wallets` first with fallback -- Migration guide documented in `platform_wallet_bridge.rs` - -**Dashcore** (`rust-dashcore`): -- `&mut Wallet` → `&Wallet` in `WalletTransactionChecker::check_core_transaction` -- All test callers cleaned up - -**Platform SDK** (separate PRs): -- PR #3375: dashcore rev update + `Network::Dash` → `Network::Mainnet` rename -- PR #3376: Extract fetch helpers to fix HRTB Send inference - ---- - -## PR-2 Status: Complete - -### What was delivered - -**Platform-wallet library** (`rs-platform-wallet`): -- `CoreAddressInfo`, `CoreAccountSummary` types (`wallet/core/types.rs`) -- Per-address methods: `all_address_info()`, `address_info()`, `account_summaries()`, `utxos_by_address()` -- `Signer` on `PlatformAddressWallet` — `blocking_read()` bridge with sequential lock acquisition (no dual-lock window) -- Asset lock tx building: `build_registration_asset_lock_transaction()`, `build_topup_asset_lock_transaction()`, `build_asset_lock_transaction()` — DIP-9 key derivation, greedy UTXO selection, two-pass fee calc, `AssetLockPayload`, P2PKH signing -- `broadcast_transaction()` via DAPI `BroadcastTransactionRequest` -- `send_transaction()` — full payment flow (UTXO select with correct output count, overflow-safe amount sum, build, sign, broadcast) -- `create_registration_asset_lock_proof()`, `create_topup_asset_lock_proof()` — build + broadcast + wait for proof via `Sdk::wait_for_asset_lock_proof_for_transaction()` -- `build_and_broadcast_*` convenience methods -- Error variants: `AssetLockTransaction`, `TransactionBroadcast`, `TransactionBuild`, `AssetLockProofWait` - -**Evo-tool integration** (`dash-evo-tool`): -- 4 signing callsites migrated from old `Wallet` to `platform_wallet.platform()` as `Signer` (transfer_platform_credits, withdraw_from_platform_address, fund_platform_address_from_asset_lock, top_up_identity_from_platform_addresses) -- Asset lock creation tasks use CoreWallet with fallback to legacy (`try_build_registration_via_platform_wallet`, `try_build_topup_via_platform_wallet`) -- Shared `broadcast_and_track_asset_lock` helper eliminates broadcast code duplication -- Address table UI: cached snapshot pattern via `WalletTask::LoadAddressInfo` → `BackendTaskSuccessResult::AddressInfo` → `cached_address_info` in `WalletsBalancesScreen` -- `CoreAddressInfo` re-exported in `platform_wallet_bridge.rs` - -**Review fixes applied:** -- Fee estimation uses actual output count (not hardcoded 2) -- `total_output` sum uses `checked_add` to prevent overflow -- Signer drops `wallet_info` lock before acquiring `wallet` lock (no deadlock window) - -### Next steps - -See PR-3 (IdentityWallet) in the PR Sequence section below. -5. **Payment building**: `send_transaction()` requires coin selection, signing, broadcast via SPV or RPC. -6. **SPV lifecycle**: `start_spv()` / `stop_spv()` are stubs — need network config wiring. - ---- - -## Problem Statement (historical — kept for context) - -**`dash-evo-tool`** maintains its own self-written wallet and duplicates DashPay crypto inline: - -- `src/model/wallet/` — custom wallet struct with `identities`, `utxos`, `platform_address_info` fields -- `backend_task/dashpay/dip14_derivation.rs` — DIP-14 256-bit key derivation -- `backend_task/dashpay/hd_derivation.rs` — DashPay contact xpub path wrapper -- `backend_task/dashpay/encryption.rs` — DIP-15 ECDH + AES-CBC (duplicates `rs-platform-encryption`) - -**`rs-platform-wallet`** is the intended canonical library but is incomplete: - -- No `PlatformWallet` struct — only `PlatformWalletInfo` (the old pattern, being deleted) -- No identity registration, top-up, withdrawal, or credit transfer -- No DIP-14 CKDpriv256/CKDpub256 -- No DashPay payment address derivation or payment sending -- No DIP-17 `AddressProvider` implementation -- No signing facade for state transition submission -- No bincode serialization for `IdentityManager`, `ManagedIdentity`, `ContactRequest`, `EstablishedContact` - -**What already exists and can be reused** (confirmed in codebase): - -- `rs-platform-encryption` crate — `derive_shared_key_ecdh`, `encrypt_extended_public_key`, `decrypt_extended_public_key`, `encrypt_account_label` — already a dependency of `rs-platform-wallet` -- `ContactRequest` and `EstablishedContact` structs — fully implemented -- `ManagedIdentity` with contact request management — fully implemented -- `IdentityManager` — implemented (needs `Arc>` wrapping + `last_scanned_index` field + removal of `sdk` field) -- `platform_wallet_info/contact_requests.rs` — `send_contact_request`, `add_incoming_contact_request`, `add_sent_contact_request` — consolidate into `DashPayWallet` -- `platform_wallet_info/identity_discovery.rs` — `discover_identities` — consolidate into `IdentityWallet::sync()` - ---- - -## Architecture (OUTDATED — see "Architecture (current)" section above) - -> **NOTE**: This section describes the OLD multi-lock design. The current design uses a single -> `Arc>` — see the "Architecture (current)" section at the top. - -``` -key-wallet (rust-dashcore) — reused types -├── Wallet ← mutable key store (mnemonic, xprv, accounts added during sync) -├── ManagedWalletInfo ← mutable UTXO state, accounts, balance, address pools -├── ManagedAccountCollection ← BIP44 + DashPay + PlatformPayment + Identity accounts -├── TransactionRouter ← transaction classification + checking -├── WalletTransactionChecker ← trait for tx matching (impl on ManagedWalletInfo) -├── TransactionContext ← Mempool | InstantSend | InBlock(BlockInfo) | InChainLockedBlock(BlockInfo) -└── BlockInfo ← { height, block_hash, timestamp } (all required) - -rs-platform-wallet -├── PlatformWallet ← cheaply cloneable (~35 atomic ops), all Arc fields -│ ├── wallet_id: WalletId -│ ├── sdk: Sdk ← ref-counted -│ ├── core: CoreWallet ← balance, UTXOs, addresses, tx building, asset locks -│ │ ├── wallet: Arc> -│ │ ├── wallet_info: Arc> -│ │ ├── transaction_statuses: Arc>> -│ │ └── tracked_asset_locks: Arc>> -│ ├── identity: IdentityWallet ← register, discover, top-up, withdraw, transfer, update, DPNS -│ │ ├── wallet, wallet_info, identity_manager: Arc> -│ │ ├── signer_for(identity_id) → ManagedIdentitySigner (key_storage + IdentitySigner fallback) -│ │ ├── update_identity(add_keys, disable_keys) ← IdentityUpdateTransition -│ │ ├── top_up_from_addresses() / transfer_credits_to_addresses() -│ │ ├── register_name() / resolve_name() / search_names() ← DPNS -│ │ ├── register_identity(IdentityFundingMethod) ← multi-mode funding -│ │ └── top_up_identity(TopUpFundingMethod) ← multi-mode top-up -│ ├── dashpay: DashPayWallet ← send/accept contact requests, sync contacts -│ │ ├── wallet, wallet_info, identity_manager: Arc> -│ │ ├── register_contact_payment_addresses() ← gap limit + SPV watch -│ │ ├── match_payment_to_contact() ← incoming payment attribution -│ │ └── DIP-14 256-bit derivation (ckd_priv_256/ckd_pub_256) ← moved to library -│ ├── platform: PlatformAddressWallet ← DIP-17 sync, transfer, withdraw, fund_from_asset_lock -│ │ ├── wallet, wallet_info: Arc> -│ │ ├── balances: Arc>> -│ │ └── implements Signer (blocking_read bridge) -│ ├── tokens: TokenWallet ← per-identity registry, sync, transfer, mint, burn, etc. -│ │ ├── wallet, identity_manager: Arc> -│ │ ├── watched: Arc>>> -│ │ ├── balances: Arc>> -│ │ └── watch/unwatch/sync/transfer/mint/burn/freeze/purchase/claim/set_price -│ └── [shielded: Option] ← feature-gated, Orchard ZK pool (PR-15) -│ -├── PlatformWalletManager ← multi-wallet + SPV coordinator (feature-gated: manager) -│ ├── sdk: Sdk -│ ├── wallets: Arc>> -│ ├── event_tx: broadcast::Sender -│ ├── spv: SpvRuntime ← extracted SPV lifecycle -│ └── sdk() / spv() / add_wallet() / remove_wallet() / get_wallet() / wallet_ids() -│ -├── SpvRuntime (src/spv/runtime.rs) ← SPV lifecycle, extracted from manager -│ ├── wallets: Arc>> -│ ├── event_tx: broadcast::Sender -│ ├── synced_height: AtomicU32 -│ ├── monitor_revision: Arc ← shared with SpvWalletAdapter -│ ├── finality_waiters: Mutex>> -│ ├── client: RwLock> -│ └── start(config) / stop() / synced_height() / notify_wallets_changed() -│ -├── SpvWalletAdapter (src/spv/wallet_adapter.rs) ← multi-wallet WalletInterface -│ ├── wallets: Arc>> ← ALL wallets -│ ├── process_block() iterates ALL wallets -│ ├── process_mempool_transaction() iterates ALL wallets -│ ├── watched_outpoints() unions ALL wallets (for bloom filter) -│ ├── process_instant_send_lock() → per-wallet status tracking -│ └── monitor_revision: Arc (shared with SpvRuntime) -│ -├── SpvEventForwarder (src/spv/event_forwarder.rs) ← EventHandler impl -│ └── forwards SPV sync/network/wallet events → PlatformWalletEvent -│ -├── Signing -│ ├── IdentitySigner ← Signer (ECDSA/BLS/EdDSA, DIP-9 paths) -│ ├── ManagedIdentitySigner ← Signer wrapping key_storage + IdentitySigner fallback -│ └── PlatformAddressWallet ← Signer (ECDSA P2PKH, DIP-17 paths) -│ -├── Events -│ ├── PlatformWalletEvent ← Wallet(WalletEvent) | Spv(SpvEvent) -│ ├── SpvEvent ← Sync(SyncEvent) | Network(NetworkEvent) | Progress(SyncProgress) -│ └── TransactionStatus ← Unconfirmed | InstantSendLocked | Confirmed | ChainLocked (monotonic) -│ -└── [ShieldedWallet] ← PR-15: shield, unshield, transfer, withdraw (Orchard/Halo2) - ├── keys.rs ← OrchardKeySet (SpendingKey → FullViewingKey → OrchardAddress) - ├── store.rs ← ShieldedStore trait, InMemoryShieldedStore - ├── prover.rs ← CachedOrchardProver with cached ProvingKey - ├── sync.rs ← note sync + nullifier sync - ├── operations.rs ← shield, unshield, transfer, withdraw, shield_from_asset_lock - └── note_selection.rs ← select_spendable_notes - -rs-sdk (Dash Platform SDK) — operations used by platform-wallet -├── Identity: PutIdentity, TopUpIdentity, WithdrawFromIdentity, TransferToIdentity -├── Identity update: IdentityUpdateTransition (add/disable keys, nonce-based) -├── Identity from addresses: TopUpIdentityFromAddresses, TransferToAddresses -├── DashPay: create/send_contact_request, fetch sent/received/all requests -├── Platform addresses: TransferAddressFunds, WithdrawAddressFunds, TopUpAddress -├── DPNS: register_dpns_name, resolve_dpns_name_to_identity, search_dpns_names -├── Tokens: transfer, mint, burn, freeze, purchase, claim, balance queries -├── Shielded: ShieldFunds, UnshieldFunds, TransferShielded, WithdrawShielded, ShieldFromAssetLock -├── Documents: PutDocument, TransferDocument, PurchaseDocument (for DashPay internals) -├── Fetch/FetchMany: identity, documents, balances, keys, platform addresses -└── sync_address_balances() with AddressProvider trait -``` - -**Key design decisions:** -- **No WalletHandle — use PlatformWallet.clone()**: All fields are Arc-wrapped, clone is ~35 atomic - ops (nanoseconds). A separate handle type added complexity without meaningful encapsulation. -- **Wallet is mutable** (`Arc>`): Accounts are added during DashPay contact - establishment and sync. The `check_core_transaction` trait takes `&mut Wallet` (write lock) - for transaction checking, as it may update wallet state (gap limit maintenance). -- **Sub-wallets share state via Arc**: All hold `Arc>` and - `Arc>`. SPV writes through the Arc — visible to all clones immediately. -- **Network from sdk.network**: Sub-wallets no longer store a `network` field — they use - `self.sdk.network` to get the network. Eliminates redundant cached state. -- **Lock ordering**: Always acquire `wallet` before `wallet_info` to prevent deadlocks. - Signers use sequential `blocking_read()` (drop first lock before acquiring second). -- **key-wallet-manager stays as separate crate**: Imports use `key_wallet_manager::*`. - The `WalletInterface` trait, `WalletEvent`, `BlockProcessingResult`, `MempoolTransactionResult` - are in `key_wallet_manager`. -- **SpvRuntime extracted from manager**: `SpvRuntime` is a standalone struct in `src/spv/runtime.rs` - that owns the `DashSpvClient`, tracks sync height, and manages finality waiters. Can be used - both with the multi-wallet manager and potentially standalone. Manager delegates via `spv()`. -- **Multi-wallet SPV adapter**: `SpvWalletAdapter` wraps `Arc>>` — processes blocks and mempool transactions against ALL managed wallets, - not a single wallet. `watched_outpoints()` unions outpoints from all wallets for bloom filters. -- **Shared monitor_revision via Arc**: `SpvRuntime` and `SpvWalletAdapter` share a - `monitor_revision` counter. `notify_wallets_changed()` bumps it on wallet add/remove, triggering - bloom filter rebuild in SPV. No manual filter management needed. -- **Manager simplified to CRUD + spv()**: `PlatformWalletManager` has `sdk()`, `spv()`, - `add_wallet()`, `remove_wallet()`, `get_wallet()`, `wallet_ids()`, `subscribe_events()`. No - create/import convenience methods — callers construct `PlatformWallet` directly, then `add_wallet()`. -- **TransactionStatus lifecycle**: Unconfirmed → InstantSendLocked → Confirmed → ChainLocked. - Tracked per transaction in CoreWallet. Events emitted on state changes. -- **PlatformWalletEvent**: Two variants only — `Wallet(WalletEvent)` and `Spv(SpvEvent)`. - `SpvEvent` wraps `Sync(SyncEvent)`, `Network(NetworkEvent)`, `Progress(SyncProgress)` from - dash-spv. `Spv` variant is feature-gated behind `manager`. -- **Feature-gated shielded**: Orchard/Halo2 deps are heavy (~30s ProvingKey). Behind `shielded` - feature. ShieldedWallet is fundamentally different (client-side state, note trial decryption, - commitment tree) so it's a separate sub-wallet, not an extension of PlatformAddressWallet. -- **Private key zeroization**: `Zeroizing<[u8; 32]>` for all derived key material. `blocking_read()` - drops locks before acquiring the next. Signer closures validate key ID parameters. -- **Simplified DashPay API**: `send_contact_request(sender, recipient)` — 2 params. All key indices, - ECDH, derivation resolved internally. `accept_contact_request(request)` — 1 param. -- **Lazy key derivation** (PR-10): `PrivateKeyData::AtWalletDerivationPath` avoids holding raw private - keys in memory for wallet-backed identities. Keys are derived on-demand during signing. -- **Identity status tracking** (PR-10): `IdentityStatus` state machine tracks identity lifecycle - from registration through confirmation. Enables UI to show pending/active/failed states. -- **Asset lock lifecycle** (PR-11): `TrackedAssetLock` tracks locks from broadcast to use. IS→CL - fallback is automatic via `resolve_asset_lock_proof()`. No lost or double-spent locks. -- **Multi-mode funding** (PR-11): `IdentityFundingMethod`/`TopUpFundingMethod` enums let callers - choose between wallet UTXOs, pre-existing proofs, specific UTXOs, or platform addresses. -- **DashPay protocol crypto in library** (PR-12): DIP-14 256-bit derivation, contact payment address - registration with gap limit, account reference calculation — protocol specs, not app logic. -- **Owned vs watched identity split** (PR-14): `ManagedIdentity` (owned, has key_storage, can sign, - identity_index required) vs `WatchedIdentity` (observed, read-only, no keys). Type system enforces - the distinction — no runtime "can I sign?" checks. Loaded-by-DPNS-name identities go to watched. -- **ManagedIdentitySigner resolves from key_storage** (PR-14): Three-step key resolution: (1) clear - bytes from storage, (2) derive from wallet at stored path, (3) fall back to standard IdentitySigner - derivation. Created via `managed_identity.signer(wallet, network)` or - `identity_wallet.signer_for(identity_id)`. - ---- - -## Implementation Plan (OUTDATED struct definitions — see current code) - -> **NOTE**: The struct definitions below show the OLD multi-lock design with separate -> `Arc>`, `Arc>`, etc. The CURRENT design uses -> a single `Arc>` containing all mutable state. Sub-wallets -> now hold `state: Arc>` instead of individual lock fields. -> See the source code for current struct definitions. - -`PlatformWallet` is a standalone wallet type (usable without SPV/manager). Cheaply cloneable -(a few atomic increments). No separate `WalletHandle` — use `PlatformWallet.clone()` directly. -`PlatformWalletManager` is the multi-wallet + SPV coordinator (no `WalletManager` dependency). - -### Struct Definitions - -```rust -// Standalone wallet — owns all state, sub-wallets as stored fields -// Usable directly for Platform-only operations (scripts, tests, no SPV needed) -// Same type is wrapped in per-wallet RwLock when managed by PlatformWalletManager -// NOTE: No `wallet` field on PlatformWallet — sub-wallets hold their own Arc refs -pub struct PlatformWallet { - wallet_id: WalletId, - sdk: Sdk, // cheaply cloneable (ref-counted) - core: CoreWallet, - identity: IdentityWallet, - dashpay: DashPayWallet, - platform: PlatformAddressWallet, - tokens: TokenWallet, -} - -// Sub-wallets — stored fields, share wallet_info via Arc> -// Network is accessed via sdk.network (no cached network field) -pub struct CoreWallet { - sdk: Sdk, - wallet: Arc>, - wallet_info: Arc>, - transaction_statuses: Arc>>, // finality tracking - tracked_asset_locks: Arc>>, // asset lock lifecycle -} - -pub struct IdentityWallet { - sdk: Sdk, - wallet: Arc>, - wallet_info: Arc>, - identity_manager: Arc>, -} - -pub struct DashPayWallet { - sdk: Sdk, - wallet: Arc>, - wallet_info: Arc>, - identity_manager: Arc>, // same instance as IdentityWallet -} - -pub struct PlatformAddressWallet { - sdk: Sdk, - wallet: Arc>, - wallet_info: Arc>, - balances: Arc>>, // balance cache -} - -pub struct TokenWallet { - sdk: Sdk, - wallet: Arc>, - identity_manager: Arc>, - watched: Arc>>>, // identity → tokens - balances: Arc>>, // cache -} - -// Multi-wallet + SPV coordinator (feature-gated: manager) -// Delegates SPV lifecycle to SpvRuntime; simplified CRUD API -pub struct PlatformWalletManager { - sdk: Sdk, - wallets: Arc>>, - event_tx: broadcast::Sender, - spv: SpvRuntime, // extracted SPV lifecycle -} - -// SPV client runtime — owns the DashSpvClient, tracks sync height, -// and manages asset-lock finality proof waiting. -// Extracted from PlatformWalletManager so it can be used standalone. -pub struct SpvRuntime { - wallets: Arc>>, - event_tx: broadcast::Sender, - synced_height: AtomicU32, - monitor_revision: Arc, // shared with SpvWalletAdapter - finality_waiters: Mutex>>, - client: RwLock>, -} - -// Multi-wallet SPV adapter — processes blocks against ALL wallets -pub(crate) struct SpvWalletAdapter { - wallets: Arc>>, - event_tx: broadcast::Sender, - platform_event_tx: broadcast::Sender, - synced_height: AtomicU32, - filter_committed_height: AtomicU32, - monitor_revision: Arc, // shared with SpvRuntime -} - -// IdentityManager is shared between IdentityWallet and DashPayWallet. -// Implements Clone — all fields are cheap to clone (just Arc clones). -// IdentityWallet and DashPayWallet share the same IdentityManager -// instance because PlatformWallet constructs them from the same source at build time. -// Two collections: `managed` for owned identities (can sign), `watched` for observed (read-only). -pub struct IdentityManager { - managed: Arc>>, // owned, has key_storage - watched: Arc>>, // observed, read-only - primary_identity_id: Arc>>, - last_scanned_index: Arc>, // persisted gap scan state - // REMOVED: sdk: Option> — SDK flows through caller struct -} -// Clone is cheap — just Arc clones. IdentityWallet and DashPayWallet hold -// the same Arc pointers — mutations visible to both. - -// ManagedIdentity — an owned identity with key material. Can sign transitions. -// Requires identity_index: u32 (always required, not Optional) — set during -// registration or discovery. Used for DIP-9 key derivation paths. -// (PR-10) Enhanced with KeyStorage, IdentityStatus, DPNS names, wallet association. -// (PR-14) identity_index is always required — type system enforces this. -pub struct ManagedIdentity { - pub identity: Identity, - pub identity_index: u32, // always required (not Optional) - pub key_storage: BTreeMap, // (PR-10) - pub status: IdentityStatus, // (PR-10) state machine - pub dpns_names: Vec, // (PR-10) associated DPNS names - pub wallet_seed_hash: Option<[u8; 32]>, // (PR-10) link to source wallet - pub wallet_index: Option, // (PR-10) HD index in wallet - pub sent_contact_requests: Vec, - pub received_contact_requests: Vec, - pub established_contacts: Vec, -} - -// WatchedIdentity — an observed identity without key material. Read-only, cannot sign. -// Loaded via load_identity_by_dpns_name() or other external lookups. -// No key_storage, no identity_index — just identity data + DPNS names + status. -pub struct WatchedIdentity { - pub identity: Identity, - pub dpns_names: Vec, - pub status: IdentityStatus, -} - -// ManagedIdentitySigner — Signer that resolves keys from a -// ManagedIdentity's key_storage with IdentitySigner fallback. -// Three-step key resolution: -// 1. Clear bytes from key_storage (PrivateKeyData::Clear) -// 2. Derive from wallet at stored path (PrivateKeyData::AtWalletDerivationPath) -// 3. Fall back to standard IdentitySigner derivation (DIP-9 path from identity_index) -// Created via managed_identity.signer(wallet, network) or identity_wallet.signer_for(identity_id). -pub struct ManagedIdentitySigner { - key_storage: BTreeMap, - identity_signer: IdentitySigner, // fallback for keys not in storage -} - -// (PR-10) Private key data — either raw bytes or lazy wallet derivation. -pub enum PrivateKeyData { - Clear(Zeroizing<[u8; 32]>), - AtWalletDerivationPath { - wallet_seed_hash: [u8; 32], - derivation_path: DerivationPath, - }, -} - -// (PR-10) Identity lifecycle state machine. -pub enum IdentityStatus { - Unknown, // Not yet checked against Platform - PendingCreation, // Registration submitted, awaiting confirmation - Active, // Confirmed on Platform - FailedCreation, // Registration failed (can retry) - NotFound, // Was active but no longer on Platform -} - -// (PR-10) DPNS name associated with an identity. -pub struct DpnsNameInfo { - pub label: String, - pub acquired_at: Option, -} - -// (PR-11) Asset lock lifecycle tracking. -pub struct TrackedAssetLock { - pub transaction: Transaction, - pub output_address: Address, - pub amount_duffs: u64, - pub proof: Option, - pub identity_id: Option, - pub status: AssetLockStatus, -} - -pub enum AssetLockStatus { - Broadcast, // TX sent, waiting for proof - InstantLocked, // IS proof received - ChainLocked, // CL proof received (higher finality) - UsedForRegistration, // Linked to an identity - UsedForTopUp, // Linked to an identity top-up -} - -// (PR-11) Multi-mode identity registration funding. -pub enum IdentityFundingMethod { - UseAssetLock { proof: AssetLockProof, private_key: PrivateKey }, - FundWithWallet { amount_duffs: u64 }, - FundWithUtxo { outpoint: OutPoint, txout: TxOut, address: Address }, - FundFromAddresses { inputs: BTreeMap }, -} - -// (PR-11) Multi-mode identity top-up funding. -pub enum TopUpFundingMethod { - UseAssetLock { proof: AssetLockProof, private_key: PrivateKey }, - FundWithWallet { amount_duffs: u64 }, - FundWithUtxo { outpoint: OutPoint, txout: TxOut, address: Address }, -} -``` - -**No dashcore changes required.** Only `key-wallet` crate types are used directly (`Wallet`, -`ManagedWalletInfo`, `ManagedAccountCollection`, `TransactionRouter`, `WalletTransactionChecker`). -`key-wallet-manager` remains a separate crate — imports use `key_wallet_manager::*`. - -**Concurrency model**: Sub-wallets share `Arc>` — this is the synchronization -point between SPV (writes UTXO state) and wallet operations (reads balance, builds transactions). -No outer per-wallet lock needed. The manager's `RwLock` is only for wallet add/remove. - -**No WalletHandle**: `PlatformWallet.clone()` is cheap (~35 atomic ops, all Arc fields). -A separate handle type was removed — it added complexity without meaningful encapsulation. - -**Sub-wallets are stored fields** on `PlatformWallet`: - -```rust -impl PlatformWallet { - pub fn core(&self) -> &CoreWallet { &self.core } - pub fn core_mut(&mut self) -> &mut CoreWallet { &mut self.core } - pub fn identity(&self) -> &IdentityWallet { &self.identity } - pub fn dashpay(&self) -> &DashPayWallet { &self.dashpay } - pub fn platform(&self) -> &PlatformAddressWallet { &self.platform } - pub async fn sync(&self) -> Result -} - -impl PlatformAddressWallet { - pub fn new( - sdk: Sdk, - wallet: Arc>, - wallet_info: Arc>, - ) -> Self { - Self { - sdk, wallet, wallet_info, - balances: Arc::new(RwLock::new(BTreeMap::new())), - } - } -} -``` - -`PlatformWalletManager` API — simplified CRUD + SPV access. Callers construct `PlatformWallet` -directly, then add it to the manager. No create/import convenience methods: - -```rust -impl PlatformWalletManager { - // Construction - pub fn new(sdk: Sdk) -> Self; - - // Accessors - pub fn sdk(&self) -> &Sdk; - pub fn spv(&self) -> &SpvRuntime; - - // Wallet CRUD - pub async fn add_wallet(&self, wallet: PlatformWallet) -> Result; - pub async fn remove_wallet(&self, wallet_id: &WalletId) -> Result; - pub async fn get_wallet(&self, wallet_id: &WalletId) -> Option; - pub async fn wallet_ids(&self) -> Vec; - - // Events — unified stream - pub fn subscribe_events(&self) -> broadcast::Receiver; -} - -impl SpvRuntime { - pub fn new(wallets: Arc>>, - event_tx: broadcast::Sender) -> Self; - pub fn synced_height(&self) -> u32; - pub fn notify_wallets_changed(&self); // bumps monitor_revision - pub async fn start(&self, config: ClientConfig) -> Result<()>; - pub async fn stop(&self) -> Result<()>; - pub async fn register_for_finality(&self, txid: Txid); - pub async fn wait_for_finality(&self, txid: Txid, timeout: Duration) -> Result; -} - -// Unified event enum — two variants only -pub enum PlatformWalletEvent { - Wallet(WalletEvent), // from block processing (TransactionReceived, BalanceUpdated) - #[cfg(feature = "manager")] - Spv(SpvEvent), // from DashSpvClient -} - -// SPV event — groups sync, network, and progress events from dash-spv -#[cfg(feature = "manager")] -pub enum SpvEvent { - Sync(dash_spv::sync::SyncEvent), - Network(dash_spv::network::NetworkEvent), - Progress(dash_spv::sync::SyncProgress), -} -``` - -Call sites — standalone `PlatformWallet`: - -```rust -let wallet = PlatformWallet::from_mnemonic(sdk, network, "word1 ...", "", 1_500_000, options)?; -wallet.identity().register_identity(amount, keys).await?; -wallet.dashpay().send_contact_request(&sender_id, &recipient_id).await?; -wallet.core().balance(); -``` - -Call sites — managed via `PlatformWalletManager` (construct wallet, then add to manager): - -```rust -let wallet = PlatformWallet::from_mnemonic(sdk, "word1 ...", "", 1_500_000, options)?; -let wallet = mgr.add_wallet(wallet).await?; // returns clone -mgr.spv().start(config).await?; // SPV syncs all managed wallets -wallet.identity().register_identity(amount, keys).await?; -wallet.dashpay().sync().await?; -wallet.core().balance(); -``` - -`sync()` on `PlatformWallet` orchestrates Platform-side syncs (SPV runs independently in background): - -```rust -pub async fn sync(&self) -> Result { - self.identity().sync().await?; - self.dashpay().sync().await?; - self.platform().sync_platform_address_balances(None).await?; - Ok(SyncResult::default()) -} -``` - ---- - -### 1.1 Wallet Construction - -> How a `PlatformWallet` is created from key material + Sdk. - -`PlatformWallet` is SPV-free. It needs only key material and an `Sdk`. No SPV config here — SPV -lives in `PlatformWalletManager` (via `SpvRuntime`). There is no `wallet` field on `PlatformWallet` -itself — each sub-wallet holds its own `Arc>` reference. Sub-wallets use -`sdk.network` for the network (no cached `network` field). - -Creation methods mirror `key-wallet`'s `Wallet` constructors, plus `sdk` parameter: - -```rust -impl PlatformWallet { - // Mirrors key-wallet Wallet creation methods + sdk - pub fn from_mnemonic( - sdk: Sdk, network: Network, mnemonic: &str, passphrase: &str, - birth_height: CoreBlockHeight, options: WalletAccountCreationOptions, - ) -> Result; - - pub fn from_xprv( - sdk: Sdk, network: Network, xprv: &str, - options: WalletAccountCreationOptions, - ) -> Result; - - pub fn from_seed( - sdk: Sdk, network: Network, seed: Seed, - options: WalletAccountCreationOptions, - ) -> Result; - - pub fn from_seed_bytes( - sdk: Sdk, network: Network, seed_bytes: &[u8; 64], - options: WalletAccountCreationOptions, - ) -> Result; - - pub fn from_xpub( - sdk: Sdk, network: Network, xpub: &str, can_sign_externally: bool, - ) -> Result; - - pub fn from_external_signable( - sdk: Sdk, network: Network, xpub: &str, - ) -> Result; - - pub fn random( - sdk: Sdk, network: Network, - options: WalletAccountCreationOptions, - ) -> Result<(Self, Mnemonic)>; - - pub fn from_bytes(sdk: Sdk, wallet_bytes: &[u8]) -> Result; -} - -// Standalone usage -let mut wallet = PlatformWallet::from_mnemonic( - sdk, Network::Testnet, "word1 word2 ...", "", - 1_500_000, WalletAccountCreationOptions::Default, -)?; -wallet.identity().register_identity(amount, keys).await?; - -// Multi-wallet with SPV — construct wallet, add to manager -let mgr = PlatformWalletManager::new(sdk.clone()); -let wallet = PlatformWallet::from_mnemonic( - sdk, "word1 word2 ...", "", - 1_500_000, WalletAccountCreationOptions::Default, -)?; -let wallet = mgr.add_wallet(wallet).await?; -mgr.spv().start(spv_config).await?; -``` - -**Internally**: each creation method calls `key-wallet`'s `Wallet::from_mnemonic()` (etc.) to create the -mutable key store (`Arc>`), then `ManagedWalletInfo::from_wallet()` for UTXO state, then -wraps both with `IdentityManager::new()` into a `PlatformWallet`. `PlatformAddressWallet::new()` is -called with a fresh `balances` cache (`Arc>>`). - -**`WalletAccountCreationOptions`**: always required (matches dashcore). Callers pass -`WalletAccountCreationOptions::Default` for standard BIP-44 account 0 + identity + DIP-17 accounts. - -**Birth height**: passed through to `ManagedWalletInfo::with_birth_height()` — used by SPV -to skip earlier blocks when loaded into `PlatformWalletManager`. Defaults to 0 (full sync). - -**`ManagedIdentity` requires `identity_index: u32`** (not Optional) — set during registration or -gap-limit discovery. Used for DIP-9 key derivation paths. Operations that need the index -(e.g., `send_contact_request`) return `IdentityIndexNotSet` if missing. - -#### Files - -- `packages/rs-platform-wallet/src/wallet/platform_wallet.rs` (replaces `platform_wallet_info/mod.rs`) -- `packages/rs-platform-wallet/src/manager.rs` (feature-gated `manager`) - -#### Migration - -The old `platform_wallet_info/` module (currently staged as deleted in git) must be fully removed. -`lib.rs` currently still imports `pub mod platform_wallet_info` — update to `pub mod platform_wallet`. - ---- - -### 1.2 Platform SDK Integration - -> Sdk lives in `PlatformWallet` and each sub-wallet — never in `IdentityManager`. - -**Current state**: SDK is stashed inside `IdentityManager.sdk: Option>` — accessed only by identity -discovery. Every async method that submits state transitions requires the caller to pass `&Sdk` separately. - -**Goal**: `PlatformWallet` holds `sdk: Sdk` as a plain field (cheaply cloneable via internal ref-counting — -confirmed at `rs-sdk/src/sdk.rs:134`). Each sub-wallet receives a clone at construction. All async methods -on sub-structs call `self.sdk` internally. - -#### SDK traits used by platform-wallet - -**Identity operations** (trait methods on `Identity`): -- `PutIdentity` — `put_to_platform_and_wait_for_response(sdk, proof, key, signer, settings)` -- `TopUpIdentity` — `top_up_identity(sdk, proof, key, fee_increase, settings) -> u64` -- `WithdrawFromIdentity` — `withdraw(sdk, address, amount, fee, signing_key, signer, settings) -> u64` - - Note: takes signer **by value** -- `TransferToIdentity` — `transfer_credits(sdk, to_id, amount, signing_key, signer, settings) -> (u64, u64)` - - Note: takes signer **by value** - -**Identity from addresses**: -- `TopUpIdentityFromAddresses` — fund identity from platform addresses -- `TransferToAddresses` — move identity credits to platform addresses - -**Platform address operations**: -- `TransferAddressFunds` — transfer between platform addresses -- `WithdrawAddressFunds` — withdraw platform address credits to Core L1 -- `TopUpAddress` — fund platform address from identity balance - -**Shielded pool** (feature-gated): -- `ShieldFunds`, `UnshieldFunds`, `TransferShielded`, `WithdrawShielded`, `ShieldFromAssetLock` - -**DPNS** (convenience wrappers): -- `register_dpns_name`, `resolve_dpns_name_to_identity` - -**Token transitions**: -- Transfer, mint, burn, freeze, purchase, claim, balance queries - -**Signing** (Signer trait implementations): -- `Signer` — `IdentitySigner` (withdraw/transfer take signer **by value**) -- `Signer` — `PlatformAddressWallet` directly - -**Documents** (for DashPay internals): -- `PutDocument`, `TransferDocument`, `PurchaseDocument` - -**Fetch/FetchMany**: -- Identity, documents, balances, keys, platform addresses -- `sync_address_balances()` with `AddressProvider` trait - -#### Tasks - -- **1.2.1** Add `sdk: Sdk` to `PlatformWallet` and each sub-wallet. Sub-wallets receive a clone at construction. -- **1.2.2** Remove `sdk: Option>` from `IdentityManager` — SDK access flows through the caller struct. - -#### Files - -- `packages/rs-platform-wallet/src/wallet/platform_wallet.rs` -- `packages/rs-platform-wallet/src/wallet/identity/manager.rs` - ---- - -### 1.3 Core Wallet Capabilities - -> Expose UTXO wallet: accounts, addresses, balances, send Dash, SPV sync, asset lock proofs. - -`key-wallet` (`rust-dashcore/key-wallet`) already implements all the building blocks: -`Wallet` (immutable key store), `ManagedWalletInfo` (mutable runtime state), -`TransactionBuilder` (coin selection, fee calc, signing), `AddressPool` (gap limit), -`WalletInfoInterface` + `ManagedAccountOperations` traits. -`dash-spv` handles SPV header sync and BIP157/158 compact filter transaction delivery. - -`CoreWallet` is a stored sub-struct that holds `Arc>` and exposes -these capabilities without leaking key-wallet internals. (`WalletInterface` is implemented -by `SpvWalletAdapter`, not `CoreWallet` — see §1.3.5 and §1.7.) - -**Note on `ManagedAccountCollection` field names** (confirmed from key-wallet source): -- Standard accounts: `standard_bip44_accounts: BTreeMap` (NOT a single `core_accounts` field) -- DashPay receive: `dashpay_receival_accounts: BTreeMap` -- DashPay send: `dashpay_external_accounts: BTreeMap` -- Platform payments: `platform_payment_accounts: BTreeMap` - -#### 1.3.1 — Wallet Initialization - -Accounts are created automatically at wallet construction — callers never call -`add_account` explicitly. `PlatformWallet::new()` passes -`WalletAccountCreationOptions::Default` to `key-wallet`, which derives standard BIP-44 -accounts and populates the initial address pool. This matches how evo-tool initializes -wallets via `import_wallet_from_extended_priv_key`. - -DashPay and DIP-17 platform payment accounts are added lazily on first use -(contact establishment / first platform address request). - -#### 1.3.2 — Address Generation - -```rust -pub fn next_receive_address(&mut self) -> Result - -pub fn next_change_address(&mut self) -> Result - -pub fn monitored_addresses(&self) -> Vec

-// Returns ALL watched addresses: BIP44 core + DashPay receival + (optionally) DIP-17 -// dash-spv uses this to match BIP157/158 compact block filters -``` - -Derives next unused BIP-44 external/change address respecting gap limit (20). -`monitored_addresses()` is the hook for SPV integration — `dash-spv` calls this via -`WalletInterface` to match BIP157/158 compact filters against wallet addresses. - -**Critical**: `monitored_addresses()` must include addresses from **all** account types in -`ManagedAccountCollection`, not just `standard_bip44_accounts`. This is how DashPay receiving addresses -get watched for incoming payments — no separate registration step, no manual bloom filter -management. When `DashPayWallet::sync()` adds a new `DashpayReceivingFunds` account (on contact -accepted), those addresses automatically appear in the next `monitored_addresses()` call. - -#### 1.3.3 — Balance & UTXO Access - -```rust -// Methods on CoreWallet: -pub fn balance(&self) -> WalletCoreBalance -// confirmed, unconfirmed, total in duffs - -pub fn utxos(&self) -> Vec -pub fn spendable_utxos(&self) -> Vec -// filtered: confirmed, non-dust, unlocked - -pub fn transaction_history(&self) -> Vec -pub fn immature_transactions(&self) -> Vec -// coinbase outputs not yet mature (< 100 blocks) -``` - -All delegate to `WalletInfoInterface` on `wallet_info`. - -**Per-address data** (research finding): `ManagedWalletInfo` already tracks richer per-address data -than the evo-tool model via `AddressPool::AddressInfo` (balance, total_received, total_sent, tx_count, -derivation_path, used status, label, metadata). CoreWallet needs methods to surface this: - -```rust -pub async fn all_address_info(&self) -> Vec -pub async fn address_info(&self, address: &Address) -> Option -pub async fn account_summaries(&self) -> Vec -pub async fn utxos_by_address(&self) -> BTreeMap> -pub async fn derivation_path_for_address(&self, address: &Address) -> Option<(DerivationPath, AccountType)> -``` - -Platform credits/nonces are NOT in key-wallet — they come from Platform state queries and -stay in a separate cache (populated by `PlatformAddressWallet::sync()`). - -**UI sync/async bridge**: Cached snapshot pattern — screen holds `Vec`, -background task calls `core_wallet.all_address_info().await`, sends snapshot via `TaskResult`, -screen renders from cache. Matches existing evo-tool `AppAction::BackendTask` / -`display_task_result` pattern. - -#### 1.3.4 — Transaction Send - -key-wallet only **builds** transactions — it has no send method. Broadcasting is a -separate concern (RPC, SPV, or DAPI). `CoreWallet` exposes `TransactionBuilder` directly -rather than a custom request struct — callers compose exactly what they need: - -```rust -// Methods on CoreWallet: -pub async fn send_transaction( - &self, - outputs: Vec<(Address, u64)>, -) -> Result - -// Power-user escape hatches for custom flows (DashPay, asset lock, etc.) -pub fn transaction_builder(&self) -> TransactionBuilder // change_address pre-set -pub fn spendable_utxos_with_keys(&self) -> (Vec, impl Fn(&Utxo) -> Option) -pub async fn broadcast_transaction(&self, tx: Transaction) -> Result -``` - -Common case: - -```rust -let txid = wallet.core.send_transaction(vec![(addr, amount_duffs)]).await?; -``` - -`send_transaction` handles coin selection (greedy UTXO selection with correct output count), -signing (P2PKH), and broadcast internally. Uses `checked_add` for overflow-safe amount sums. -Two-pass fee calculation: first pass estimates with placeholder, second pass with actual size. - -**`broadcast_transaction`**: broadcasts a raw Core transaction via DAPI `BroadcastTransactionRequest`. -This is the primary broadcast path when SPV is not active. - -**Broadcast paths**: -- **DAPI mode**: `broadcast_transaction()` via `BroadcastTransactionRequest` — always available -- **SPV mode**: `DashSpvClient::broadcast_transaction(tx)` → P2P to connected peers - -**`TransactionStatus`** tracks the lifecycle of each transaction: -```rust -pub enum TransactionStatus { - Unconfirmed, - InstantSendLocked, - Confirmed { height: u32 }, - ChainLocked { height: u32 }, -} -``` -Lifecycle: Unconfirmed → InstantSendLocked → Confirmed → ChainLocked. -Tracked per transaction in CoreWallet. Events emitted on state changes. - -#### 1.3.5 — SPV Sync Integration - -`dash-spv` (`DashSpvClient`) is the P2P sync layer. It uses **BIP157/158 compact -block filters** (not Bloom filters). It accepts `Arc>`. -`DashSpvClient` is now parameterized with `EventHandler` (generic `H`) for SPV event forwarding. - -**`SpvWalletAdapter`** implements the full `WalletInterface` trait (from `key_wallet_manager`): -- `process_block()` — iterates wallets, locks each `wallet_info`, calls `check_core_transaction` per tx -- `process_mempool_transaction(tx, is_instant_send: bool)` → `MempoolTransactionResult` -- `watched_outpoints() -> Vec` — for bloom filter construction -- `monitor_revision() -> u64` — bloom filter staleness detection; change triggers reconstruction -- `process_instant_send_lock()` — marks UTXOs as instant-send confirmed -- `monitored_addresses` — collects from all wallets' `ManagedWalletInfo` -- `synced_height` / `update_synced_height` — tracks via `AtomicU32`, updates each wallet - -Note: `check_core_transaction()` has gained an `update_balance: bool` parameter. - -SPV lives in `SpvRuntime` (accessed via `PlatformWalletManager::spv()`), not in `PlatformWallet`. -`PlatformWallet` is SPV-free. - -**Wiring** (`SpvRuntime::start(config)`): - -```rust -// SpvRuntime creates SpvWalletAdapter (multi-wallet) + SpvEventForwarder -let adapter = SpvWalletAdapter::new(wallets.clone(), event_tx.clone(), monitor_revision.clone()); -let handler = Arc::new(SpvEventForwarder::new(event_tx.clone())); -let client = DashSpvClient::new(config, network, storage, adapter, handler).await?; -``` - -**Block processing call chain**: - -``` -DashSpvClient - → SpvWalletAdapter::process_block() // WalletInterface impl - → wallets.read() → iterate wallets - → for each wallet: - → wallet.core.wallet_info.write() // Arc> — inner lock - → check_core_transaction(tx, update_balance) // WalletTransactionChecker (key-wallet) - → ManagedWalletInfo state mutated - → PlatformWalletEvent::Wallet(...) emitted -``` - -**`PlatformWalletEvent`** (unified enum, two variants): -- `Wallet(WalletEvent)` — `TransactionReceived`, `BalanceUpdated` (from block/mempool processing) -- `Spv(SpvEvent)` — `Sync(SyncEvent)`, `Network(NetworkEvent)`, `Progress(SyncProgress)` (feature-gated: `manager`) - -**`SpvEventForwarder`** impl (`EventHandler` trait) forwards SPV events to `PlatformWalletEvent`: -- `on_sync_event`, `on_network_event`, `on_progress`, `on_wallet_event`, `on_error` - -**Event subscription**: -```rust -let rx: broadcast::Receiver = mgr.subscribe_events(); -``` - -**Two event channels**: `WalletInterface::subscribe_events()` returns `WalletEvent` (for SPV). -`PlatformWalletManager::subscribe_events()` (public API) returns `PlatformWalletEvent` which -wraps `WalletEvent` + `SpvEvent`. Internally, the `SpvWalletAdapter` forwards `WalletEvent`s -into the `PlatformWalletEvent` channel. - -**No reorg notification**: `WalletInterface` has no `process_reorg` method — reorgs are handled -only at the `ChainTipManager` level in dash-spv; the wallet is never notified. - -`key-wallet-manager` remains a separate crate — imports use `key_wallet_manager::*`. -`WalletInterface`, `WalletEvent`, `BlockProcessingResult`, `MempoolTransactionResult` are in -`key_wallet_manager`. - -Transaction broadcasting goes through `DashSpvClient::broadcast_transaction(tx)` — P2P -to connected peers (see §1.3.4). `dash-spv` also delivers InstantLock and ChainLock events -needed for asset lock proof creation (§1.3.6). - -#### 1.3.6 — Asset Lock Proof Creation - -Required for identity **registration** and **top-up** (§1.4). - -```rust -pub async fn create_asset_lock_proof( - &self, - amount_duffs: u64, -) -> Result<(AssetLockProof, PrivateKey), CoreWalletError> -``` - -`CoreWallet` method — derives the next DIP-9 funding key internally, sources UTXOs -from `wallet_info`, builds an `AssetLock` special transaction via `TransactionBuilder`, -broadcasts it, waits for the InstantLock via SPV, returns `(AssetLockProof, funding_private_key)`. - -**Two proof types** (both fully implemented in rs-dpp): -- `AssetLockProof::Instant` — wraps InstantLock + full transaction + output index. Primary path. -- `AssetLockProof::Chain` — wraps `core_chain_locked_height` + outpoint. Fallback if InstantLock - is not received within timeout (suggest 60s, matching DashSync iOS behaviour). - -**Important**: The fallback to `AssetLockProof::Chain` requires the referenced block height to be -ChainLocked from Platform's perspective. The wallet must poll block confirmation before using -a Chain proof. - -DIP-9 funding key paths: -- Registration: `m/9'/coin'/5'/1'/identity_index` (non-hardened terminal index) -- Top-up (unbound): `m/9'/coin'/5'/2'/topup_index` (non-hardened terminal) -- Top-up (bound): `m/9'/coin'/5'/2'/registration_index'/topup_index` - -**Note**: `ManagedAccountCollection` has dedicated fields for these: -`identity_registration: Option`, -`identity_topup: BTreeMap`, -`identity_topup_not_bound: Option`. - -**Implementation notes**: -- **DIP-9** (not DIP-13) is the funding key derivation standard. Paths use `m/9'/coin'/5'/...`. -- **Two-pass fee calculation**: first pass estimates with placeholder inputs, second pass with actual - transaction size. Minimum fee: 3000 duffs. Size formula: `10 + inputs*148 + outputs*34 + 60` bytes. -- **Proof wait**: uses `Sdk::wait_for_asset_lock_proof_for_transaction()` (rs-sdk, 232 lines) which - polls Platform for proof availability after broadcast. -- **Reuse**: key-wallet `TransactionBuilder` for UTXO selection (greedy strategy). -- **Port ~300-400 lines**: asset lock tx construction (version-3 `Transaction` with `AssetLockPayload` - special payload, OP_RETURN burn output). -- **Port ~400 lines**: recovery scanning (scan DIP-9 funding paths for unconfirmed locks). -- DIP-9 key derivation reuses `Wallet::derive_extended_private_key()` + identity account paths. - -Additional API for top-up: -```rust -pub async fn create_topup_asset_lock_proof( - &self, - amount_duffs: u64, - identity_index: u32, -) -> Result<(AssetLockProof, PrivateKey), CoreWalletError> -``` - -#### 1.3.7 — Asset Lock Recovery - -```rust -pub async fn recover_asset_locks(&self) -> Result, CoreWalletError> -``` - -Scans known funding key paths for broadcast-but-unconfirmed asset lock transactions -and attempts to recover or rebroadcast them. Mirrors evo-tool's -`CoreTask::RecoverAssetLocks`. - -#### 1.3.8 — Asset Lock Tracking (PR-11) - -`CoreWallet` tracks asset locks from broadcast through to usage. This replaces ad-hoc -tracking in evo-tool and ensures asset locks are not lost or double-spent. - -```rust -// Methods on CoreWallet: -pub fn track_asset_lock(&self, lock: TrackedAssetLock) -pub fn unused_asset_locks(&self) -> Vec<&TrackedAssetLock> // Broadcast or IS/CL-proved, not yet used -pub fn mark_asset_lock_used(&self, txid: &Txid, usage: AssetLockStatus) -``` - -`tracked_asset_locks: Arc>>` holds all asset locks created -by this wallet. Status transitions: `Broadcast → InstantLocked → UsedForRegistration` (or -`→ ChainLocked → UsedForTopUp`). The `resolve_asset_lock_proof()` method (see below) -updates the status as proofs arrive. - -#### 1.3.9 — Asset Lock Proof Resolution with IS→CL Fallback (PR-11) - -When an InstantSend proof is rejected by Platform (`AssetLockInstantLockProofInvalid`), -the wallet automatically falls back to a ChainLock proof: - -```rust -pub async fn resolve_asset_lock_proof( - &self, - txid: &Txid, -) -> Result -``` - -Steps: -1. Try InstantSend proof (primary path — fast, ~2s) -2. If Platform rejects IS proof → query DAPI for tx to check `is_chain_locked` and `height` -3. If chain-locked and Platform has verified that height → build `ChainAssetLockProof` -4. If not chain-locked → return `AssetLockNotChainLocked` error - -This logic is shared by both identity registration and top-up flows. - -#### 1.3.10 — UTXO Retry on Exhaustion (PR-11) - -When building an asset lock TX fails due to insufficient UTXOs: -1. Release wallet lock -2. Refresh UTXOs (if SPV running, trigger rescan; otherwise return error) -3. Retry once - -```rust -pub async fn build_asset_lock_with_retry( - &self, - amount_duffs: u64, -) -> Result<(Transaction, PrivateKey), CoreWalletError> -``` - -#### Files - -- `packages/rs-platform-wallet/src/wallet/core/wallet.rs` (new) -- `packages/rs-platform-wallet/src/wallet/core/asset_lock.rs` (PR-11) — TrackedAssetLock, tracking methods -- Depends on: `key-wallet` (`ManagedWalletInfo`, `TransactionBuilder`, `WalletInfoInterface`, - `ManagedAccountOperations`, `FeeRate`, `SelectionStrategy`) -- Depends on: `key-wallet-manager` — `WalletInterface`, `WalletEvent`, - `BlockProcessingResult`, `MempoolTransactionResult` -- Depends on: `dash-spv` (`broadcast_transaction`, InstantLock/ChainLock events) - ---- - -### 1.4 Identity Management - -> Register, discover, refresh, top-up, withdraw, transfer, update identities. Register DPNS names. - -All methods are on `IdentityWallet` which holds `sdk`, `wallet: Arc>`, and `identity_manager`. -No `wallet: &Wallet` parameter anywhere — key derivation and signing use `self.wallet` directly. -`identity_index` is stored on `ManagedIdentity` as `u32` (always required, not Optional). - -**Managed vs watched routing** (PR-14): -- `sync()` adds discovered identities to `managed` collection (owned, with key_storage) -- `load_identity_by_index()` adds to `managed` collection (owned, with key_storage) -- `load_identity_by_dpns_name()` adds to `watched` collection (observed, read-only, no keys) -- `signer_for(identity_id)` creates `ManagedIdentitySigner` from the managed identity's key_storage - -**ManagedIdentity enrichments** (PR-10): -- `key_storage: BTreeMap` — lazy wallet derivation via `AtWalletDerivationPath`; avoids storing raw private keys in memory for wallet-backed identities -- `status: IdentityStatus` — state machine tracking identity lifecycle (`Unknown → PendingCreation → Active`, with `FailedCreation` and `NotFound` branches) -- `dpns_names: Vec` — DPNS names associated with this identity, populated during `sync()` -- `wallet_seed_hash: Option<[u8; 32]>` — links identity back to source wallet for key re-derivation on recovery -- `wallet_index: Option` — HD index in the wallet, paired with `wallet_seed_hash` - -**SDK method surface** (confirmed from `rs-sdk` source — these are trait methods on `Identity`, not on `Sdk`): -- `Identity::put_to_platform_and_wait_for_response(sdk, asset_lock_proof, private_key, signer, settings)` — `PutIdentity` trait -- `identity.top_up_identity(sdk, asset_lock_proof, private_key, user_fee_increase, settings) -> Result` — `TopUpIdentity` trait -- `identity.withdraw(sdk, address, amount, core_fee_per_byte, signing_key, signer, settings) -> Result` — `WithdrawFromIdentity` trait - - Note: takes signer **by value** -- `identity.transfer_credits(sdk, to_identity_id, amount, signing_key, signer, settings) -> Result<(u64, u64)>` — `TransferToIdentity` trait - - Note: takes signer **by value** - -**Additional SDK traits**: -- `TopUpIdentityFromAddresses` — fund identity from platform addresses -- `TransferToAddresses` — move identity credits to platform addresses -- Key update: no SDK trait — build `IdentityUpdateTransition` via DPP, broadcast with `BroadcastStateTransition` - -#### 1.4.1 — Register New Identity - -**Current** (PR-3): -```rust -pub async fn register_identity( - &mut self, - amount_duffs: u64, - key_types: &[IdentityKeySpec], -) -> Result -``` - -**Enhanced** (PR-11) — multi-mode funding via `IdentityFundingMethod`: -```rust -pub async fn register_identity( - &mut self, - funding: IdentityFundingMethod, - key_types: &[IdentityKeySpec], -) -> Result -``` - -The `IdentityFundingMethod` enum supports four funding paths: -- `FundWithWallet { amount_duffs }` — builds asset lock from wallet UTXOs (with UTXO retry on exhaustion), broadcasts, waits for proof with IS→CL fallback -- `UseAssetLock { proof, private_key }` — uses a pre-existing asset lock proof -- `FundWithUtxo { outpoint, txout, address }` — builds asset lock from a specific UTXO -- `FundFromAddresses { inputs }` — funds from platform addresses (no asset lock needed, uses `put_with_address_funding()`) - -Steps (for `FundWithWallet`): - -1. `core_wallet.build_asset_lock_with_retry(amount)` → `(Transaction, PrivateKey)` (PR-11: with UTXO retry) -2. `core_wallet.broadcast_transaction(tx)` + `core_wallet.track_asset_lock(...)` (PR-11: track from broadcast) -3. `core_wallet.resolve_asset_lock_proof(txid)` → `AssetLockProof` (PR-11: IS→CL fallback) -4. Set `ManagedIdentity.status = PendingCreation` (PR-10) -5. Derive auth keys at DIP-9 paths, build `IdentityPublicKey` entries -6. Store derivation paths in `key_storage` as `AtWalletDerivationPath` (PR-10) -7. Build `Identity` object with keys -8. `identity.put_to_platform_and_wait_for_response(&sdk, proof, &key, &signer, None)` → confirmed `Identity` -9. Set `ManagedIdentity.status = Active` (PR-10), store `wallet_seed_hash` and `wallet_index` (PR-10) -10. Add to `identity_manager` - -SDK traits used: -- `PutIdentity::put_to_platform_and_wait_for_response` — takes `&Identity`, `AssetLockProof`, `&PrivateKey`, `&impl Signer`, returns confirmed `Identity` -- `TopUpIdentity::top_up_identity` — takes `AssetLockProof`, `&PrivateKey`, returns `u64` (new balance). No signer needed. -- `WithdrawFromIdentity::withdraw` — takes `Option
`, amount, signer **by value**, returns `u64` -- `TransferToIdentity::transfer_credits` — takes `Identifier`, amount, signer **by value**, returns `(u64, u64)` - -**DIP-9 key path** (3-component path with `key_type`): The full path is -`m/9'/coin'/5'/0'/key_type'/identity_index'/key_index'` -where `key_type` is: `0'` = ECDSA, `1'` = BLS. The existing `key_derivation.rs` omits the -`key_type'` segment — this must be fixed. The `key_type'` level enables multi-algorithm keys -under the same identity index. - -**`signer_for` factory** on `IdentityWallet`: -```rust -pub fn signer_for( - &self, - identity_id: &Identifier, -) -> Result -``` -Looks up the `ManagedIdentity` from the `managed` collection (errors if identity is only watched), -clones its `key_storage`, and constructs a `ManagedIdentitySigner` with an `IdentitySigner` fallback. -Three-step key resolution: (1) clear bytes from storage, (2) derive from wallet at stored path, -(3) fall back to standard IdentitySigner derivation from `identity_index`. -Also available as `managed_identity.signer(wallet, network)` for direct construction. - -#### 1.4.2 — Identity Discovery (DIP-9 gap-limit scan) - -Implementation exists in the old `platform_wallet_info/identity_discovery.rs`. -Current behaviour (pre-PR-10): - -- Derives ECDSA auth key at `key_index=0` only -- Queries Platform via `Identity::fetch(&sdk, PublicKeyHash(key_hash))` — unique key hash -- `start_index` and `gap_limit` passed by caller — state not persisted -- SDK pulled from `IdentityManager.sdk` (stale pattern) -- Errors during fetch silently treated as misses - -**What was fixed (PR-3):** - -- Moved to `IdentityWallet::sync()`, no parameters -- `last_scanned_index: u32` stored in `IdentityManager` — persisted and resumed -- Gap limit hardcoded to 5 -- `PublicKeyHash` unique lookup — correct for authentication keys -- Fetch errors surfaced properly -- SDK sourced from `self.sdk` on `IdentityWallet` - -**Enhanced discovery (PR-10):** - -- Scan key indices 0..12 per identity index (12-key lookup window, matching evo-tool's `AUTH_KEY_LOOKUP_WINDOW`) -- Support ECDSA_HASH160 matching (not just full pubkey) — handles identities registered with hash-based key types -- Fetch DPNS names for each discovered identity via DPNS contract query (`records.identity == identity_id`) -- Store matched derivation paths in `KeyStorage` as `AtWalletDerivationPath` — enables lazy key derivation without holding raw private keys -- Set `IdentityStatus::Active` for discovered identities -- Store `wallet_seed_hash` and `wallet_index` on discovered identities for recovery - -```rust -pub async fn sync(&self) -> Result, PlatformWalletError> -``` - -Discovered identities are added to the `managed` collection (owned, with key_storage). - -#### 1.4.3 — Refresh Identity - -```rust -pub async fn refresh_identity( - &mut self, - identity_id: &Identifier, -) -> Result<(), PlatformWalletError> -``` - -Fetches latest balance and keys from Platform, updates `ManagedIdentity`. - -#### 1.4.4 — Top Up Identity Credits - -**Current** (PR-3): -```rust -pub async fn top_up_identity( - &mut self, - identity_id: &Identifier, - amount_duffs: u64, -) -> Result // returns new balance -``` - -**Enhanced** (PR-11) — multi-mode funding via `TopUpFundingMethod`: -```rust -pub async fn top_up_identity( - &mut self, - identity_id: &Identifier, - funding: TopUpFundingMethod, -) -> Result // returns new balance -``` - -The `TopUpFundingMethod` enum supports three funding paths: -- `FundWithWallet { amount_duffs }` — builds asset lock from wallet UTXOs (with UTXO retry), broadcasts, waits for proof with IS→CL fallback -- `UseAssetLock { proof, private_key }` — uses a pre-existing asset lock proof -- `FundWithUtxo { outpoint, txout, address }` — builds asset lock from a specific UTXO - -Note: `FundFromAddresses` for top-up uses `top_up_from_addresses()` (already implemented in PR-7). - -Steps (for `FundWithWallet`): - -1. `self.core.build_asset_lock_with_retry(amount_duffs)` → `(Transaction, PrivateKey)` (PR-11: UTXO retry) -2. `self.core.broadcast_transaction(tx)` + `self.core.track_asset_lock(...)` (PR-11: track lifecycle) -3. `self.core.resolve_asset_lock_proof(txid)` → `AssetLockProof` (PR-11: IS→CL fallback) -4. Call `identity.top_up_identity(&self.sdk, asset_lock_proof, private_key, None, None)` — `TopUpIdentity` trait -5. Update `ManagedIdentity` balance - -**Note**: `top_up_identity` takes `private_key: [u8; 32]` — pass the raw bytes of the asset lock funding private key. - -#### 1.4.5 — Withdraw Credits to Core - -```rust -pub async fn withdraw_identity_credits( - &mut self, - identity_id: &Identifier, - to_address: Option
, // None = next wallet receive address from self.core - amount_credits: u64, - core_fee_per_byte: Option, -) -> Result // returns remaining balance -``` - -Calls `identity.withdraw(&self.sdk, address, amount, core_fee_per_byte, signing_key, signer, settings)`. -Signs using `IdentitySigner` (see §1.10). - -#### 1.4.6 — Transfer Credits Between Identities - -```rust -pub async fn transfer_credits( - &mut self, - from_identity_id: &Identifier, - to_identity_id: &Identifier, - amount_credits: u64, -) -> Result -``` - -Calls `identity.transfer_credits(&self.sdk, to_identity_id, amount, signing_key, signer, settings)`. -Returns `(from_balance, to_balance)` — expose the from-balance to caller. - -#### 1.4.7 — Update Identity Keys - -```rust -pub async fn add_key_to_identity( - &mut self, - identity_id: &Identifier, - new_key_spec: IdentityKeySpec, -) -> Result<(), PlatformWalletError> - -pub async fn disable_identity_key( - &mut self, - identity_id: &Identifier, - key_id: u32, -) -> Result<(), PlatformWalletError> -``` - -`add_key_to_identity` builds an `IdentityUpdateTransition` via DPP (not a raw SDK trait) and -broadcasts it with `BroadcastStateTransition`. The new key is derived at the next available -key index under the identity's DIP-9 path. - -#### 1.4.8 — Top Up from Platform Addresses - -```rust -pub async fn top_up_from_addresses( - &mut self, - identity_id: &Identifier, - from_addresses: BTreeMap, -) -> Result // returns new balance -``` - -Uses `TopUpIdentityFromAddresses` SDK trait. Signs each address contribution with -its DIP-17 derived key via `Signer`. - -#### 1.4.9 — Transfer to Platform Addresses - -```rust -pub async fn transfer_to_addresses( - &mut self, - identity_id: &Identifier, - to_addresses: BTreeMap, -) -> Result // returns remaining identity balance -``` - -Uses `TransferToAddresses` SDK trait. - -#### 1.4.10 — DPNS Name Operations - -Convenience wrappers around SDK DPNS methods: - -```rust -pub async fn register_name( - &mut self, - identity_id: &Identifier, - name: &str, -) -> Result // document id - -pub async fn resolve_name( - &self, - name: &str, -) -> Result, PlatformWalletError> // identity id -``` - -`register_name` wraps `sdk.register_dpns_name()`. `resolve_name` wraps -`sdk.resolve_dpns_name_to_identity()`. - -#### 1.4.11 — Load Identity by Index (PR-14) - -Targeted lookup for a single wallet identity index (unlike `sync()` which does a gap scan). - -```rust -/// Derives auth key at identity_index, queries Platform by key hash. -/// If found, adds to IdentityManager's `managed` collection with KeyStorage + DPNS names. -/// Returns None if no identity is registered at this index. -pub async fn load_identity_by_index( - &self, - identity_index: u32, -) -> Result, PlatformWalletError> -``` - -Used when the caller knows the specific index (e.g., wallet recovery, user-selected index). -Adds to `managed` collection (owned, with key_storage derived from wallet). - -#### 1.4.12 — Refresh Identity (PR-14) - -Fetch latest state for a known identity from Platform (balance, keys, revision). - -```rust -/// Re-fetches the identity from Platform and updates the local ManagedIdentity. -/// Unlike sync() which discovers NEW identities, this updates an EXISTING one. -pub async fn refresh_identity( - &self, - identity_id: &Identifier, -) -> Result -``` - -Updates: `identity` field (balance, revision, keys), `status` → Active (if found), -`last_updated_balance_block_time`. - -#### 1.4.13 — Batch DPNS Refresh (PR-14) - -Refresh DPNS names for all managed identities. - -```rust -/// Queries Platform for current DPNS names for each identity in the manager. -/// Updates ManagedIdentity.dpns_names for all identities. -pub async fn refresh_dpns_names(&self) -> Result<(), PlatformWalletError> -``` - -Used on app startup or periodic refresh to keep names current. - -#### 1.4.14 — Load Identity by DPNS Name (PR-14) - -Resolve a DPNS name and load the identity into the manager. - -```rust -/// Resolves name → identity ID, fetches identity from Platform, adds to manager's -/// `watched` collection (read-only, no key material). -/// Returns None if name doesn't resolve. -pub async fn load_identity_by_dpns_name( - &self, - name: &str, -) -> Result, PlatformWalletError> -``` - -Combines `resolve_name()` + `Identity::fetch()` + adds to `watched` collection as `WatchedIdentity` -(observed, read-only, no keys). Cannot sign transitions for watched identities. - -#### Files - -- `packages/rs-platform-wallet/src/wallet/identity/wallet.rs` — IdentityWallet -- `packages/rs-platform-wallet/src/wallet/identity/manager.rs` — IdentityManager (managed + watched) -- `packages/rs-platform-wallet/src/wallet/identity/funding.rs` — IdentityFundingMethod, TopUpFundingMethod -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/mod.rs` — ManagedIdentity -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/key_storage.rs` — PrivateKeyData, IdentityStatus, DpnsNameInfo, WatchedIdentity -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/block_time.rs` — BlockTime -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/identity_ops.rs` -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/contact_requests.rs` -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/contacts.rs` -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/label.rs` -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/sync.rs` -- `packages/rs-platform-wallet/src/wallet/signer.rs` — IdentitySigner + ManagedIdentitySigner - ---- - -### 1.5 DashPay — Contacts, Transactions, Sync - -> Full DIP-14/15 implementation: contact requests, encrypted xpub exchange, payment address -> derivation, send/receive Dash between contacts. - -**Existing** (PR-4): `send_contact_request`, `accept_contact_request`, `decrypt_incoming_contact_request`, -`derive_payment_address_for_contact`, `send_dashpay_payment`, `sync()`, profiles, auto-accept proofs. - -**PR-12 adds**: DIP-14 256-bit derivation moved to library, contact payment address registration with -gap limit management, account reference calculation, incoming payment attribution via `match_payment_to_contact()`. - -#### DIP-14 Background - -DashPay uses 256-bit derivation (CKDpriv256/CKDpub256) for contact-specific address spaces: - -``` -m(userA)/9'/5'/15'/0'/(userA_id_256bit)/(userB_id_256bit)/index -``` - -The 256-bit identity ID indices prevent the 31-bit collision attack. `CKDpriv256` is fully -compatible with BIP32 for indices < 2^32; uses `ser_256(i)` (big-endian, 32 bytes) for larger indices. - -**Current state**: Lives in `dash-evo-tool/src/backend_task/dashpay/dip14_derivation.rs`. -Moves to `packages/rs-platform-wallet/src/platform_wallet/dashpay/dip14.rs` (PR-12). -This is protocol-level crypto and belongs in the library, not in the application. - -#### DIP-15 Background - -A contact request document on Platform contains: - -- `encryptedPublicKey` (exactly 96 bytes = IV 16 + ciphertext 80): AES-CBC-256 encrypted xpub - - xpub is 78 bytes in BIP32 wire format → padded to 80 bytes via PKCS7 (2 padding bytes) -- `encryptedAccountLabel` (optional 48-80 bytes): encrypted account name -- `accountReference` (32-bit): `(version<<28) | (HMAC-SHA256(senderKey, xpub)_28bits XOR account_28bits)` -- `senderKeyIndex` / `recipientKeyIndex`: identity key indices used for ECDH -- `$createdAt`, `$createdAtCoreBlockHeight`: required system fields -- **Documents are immutable**: `documentsMutable: false, canBeDeleted: false` — no update/delete API - -ECDH shared key: `SHA256( (y[31]&0x1 | 0x2) || x )` — confirmed correct per DIP-15. -Uses `libsecp256k1_ecdh` with compressed-point SHA256 hash (verify libsecp256k1 >= 0.3.0). - -**The `rs-platform-encryption` crate already implements all DIP-15 crypto** (confirmed in codebase): -- `derive_shared_key_ecdh()`, `encrypt_extended_public_key()`, `decrypt_extended_public_key()`, - `encrypt_account_label()`, `encrypt_aes_256_cbc()`, `decrypt_aes_256_cbc()` -- Already a dependency: `platform-encryption = { path = "../rs-platform-encryption" }` -- **Do NOT duplicate these functions** — reuse `rs-platform-encryption` directly. - -**Recipient key purpose**: The recipient's key must have `Purpose::DECRYPTION` (confirmed from -SDK's `contact_request.rs:229` — the SDK validates `Purpose::DECRYPTION` on the recipient key, NOT `ENCRYPTION`). - -#### 1.5.1 — DIP-14 Key Derivation (dashpay module) (PR-12: moved from evo-tool to library) - -```rust -// packages/rs-platform-wallet/src/platform_wallet/dashpay/dip14.rs (new file) -pub fn ckd_priv_256( - parent: &ExtendedPrivKey, - index: &[u8; 32], // 32-byte big-endian index (must be big-endian — interop requirement) - hardened: bool, -) -> Result - -pub fn ckd_pub_256( - parent: &ExtendedPubKey, - index: &[u8; 32], // non-hardened only -) -> Result - -pub fn derive_dashpay_contact_xpub( - master: &ExtendedPrivKey, - network: Network, - account: u32, - sender_id: &[u8; 32], - recipient_id: &[u8; 32], -) -> Result -// Path: m/9'/coin'/15'/0'/(sender_id_256bit)/(recipient_id_256bit) -// First 4 components hardened, last 2 (identity IDs) non-hardened -``` - -**DIP-14 test vectors** — must implement and pass before merging PR-3: -- Mnemonic: "birth kingdom trash renew flavor utility donkey gasp regular alert pave layer" -- Four vectors provided in DIP-14 Appendix A with full hex outputs - -**Big-endian requirement**: `ser_256(i)` must use big-endian byte order (most-significant byte -first), matching BIP32's `ser_32`. Verify this in `ckd_priv_256` before relying on the output. - -**Backward compatibility**: For indices < 2^32, `CKDpriv256` produces identical results to BIP32. - -#### 1.5.2 — DIP-15 Encryption (reuse `rs-platform-encryption`) - -```rust -// DO NOT re-implement — use existing rs-platform-encryption functions: -use platform_encryption::{ - derive_shared_key_ecdh, // ECDH: SHA256((y[31]&0x1|0x2)||x) - encrypt_extended_public_key, // AES-CBC-256, IV(16) + ciphertext(80) = 96 bytes - decrypt_extended_public_key, // Returns ExtendedPubKey from 96-byte blob - encrypt_account_label, // Optional account label encryption - compute_account_reference, // (version<<28) | (HMAC-SHA256_28bits XOR account_28bits) -}; -``` - -**Critical bug to fix**: The existing `add_incoming_contact_request` in `contact_requests.rs` -calls `ExtendedPubKey::decode(&encrypted_public_key)` on the raw encrypted bytes without first -decrypting them via AES-CBC-256. This must be fixed: decrypt first, then decode. - -The correct flow: -```rust -let shared_key = derive_shared_key_ecdh(&our_privkey, &sender_pubkey); -let xpub = decrypt_extended_public_key(&contact_request.encrypted_public_key, &shared_key)?; -// Now xpub is the 78-byte BIP32 xpub — use it to create DashpayExternalAccount -``` - -#### 1.5.3 — Send Contact Request - -Simplified 2-parameter API — all other parameters resolved internally by the wallet: - -```rust -pub async fn send_contact_request( - &self, - sender_identity_id: &Identifier, - recipient_identity_id: &Identifier, -) -> Result<(), PlatformWalletError> -``` - -Internally resolved: -- **identity_index**: looked up from `ManagedIdentity.identity_index` (u32, required) -- **sender_key_index**: first key with `Purpose::ENCRYPTION` on the sender identity -- **recipient_key_index**: first key with `Purpose::DECRYPTION` on the recipient identity (fetched from Platform) - - ECDH key type validation: both keys must be ECDH-compatible (secp256k1) -- **account_index**: defaults to `0` -- **ECDH**: always performed using `EcdhProvider::SdkSide` (wallet has seed, can derive private key) - -Steps: - -1. Retrieve sender identity and its HD index from `IdentityManager` -2. Fetch recipient identity from Platform -3. Find sender ENCRYPTION key (first match) — validate ECDH key type -4. Find recipient DECRYPTION key (first match) — validate ECDH key type -5. Derive DashPay receiving-account xpub -6. Derive ECDH private key from wallet using `m/9'/coin'/5'/0'/0'/identity_index'/key_id'` -7. Submit via `sdk.send_contact_request()` with `EcdhProvider::SdkSide` -8. Store in `ManagedIdentity.sent_contact_requests` - -**Note**: `contactRequest` documents are immutable — no retry/update API. If submission fails, it's a new request. - -**Note**: `ManagedIdentity.identity_index` is `u32` (required). Operations return `IdentityIndexNotSet` if missing. - -#### 1.5.3a — Accept Contact Request - -Simplified 1-parameter API: - -```rust -pub async fn accept_contact_request( - &self, - contact_request: &ContactRequest, -) -> Result<(), PlatformWalletError> -``` - -Internally: -1. Decrypt the incoming contact request (§1.5.4) -2. Create `DashpayReceivingFunds` account in `ManagedAccountCollection` -3. Store as `EstablishedContact` - -All key indices, ECDH derivation, and account index resolution happen internally. - -#### 1.5.4 — Decrypt Incoming Contact Request - -Fix the existing implementation: - -```rust -pub fn decrypt_incoming_contact_request( - &self, - our_identity_id: &Identifier, - contact_request: &ContactRequest, -) -> Result -``` - -Steps: - -1. Retrieve our DECRYPTION private key at `contact_request.recipient_key_index` -2. Retrieve sender's public key at `contact_request.sender_key_index` -3. Compute ECDH shared key: `derive_shared_key_ecdh(&our_privkey, &sender_pubkey)` -4. **Decrypt first**: `decrypt_extended_public_key(&contact_request.encrypted_public_key, &shared_key)?` -5. Store resulting xpub as `DashpayExternalAccount` in `ManagedAccountCollection` - -#### 1.5.5 — Payment Address Derivation - -```rust -pub fn derive_payment_address_for_contact( - &self, - our_identity_id: &Identifier, - contact_id: &Identifier, - payment_index: u32, -) -> Result -``` - -Non-hardened BIP32 child of the stored `DashpayExternalAccount` xpub at `payment_index`. -Payment gap limit: **10** (per DIP-15: "a gap limit of 10 at this stage"). -Document this as a deliberate choice (20 is more conservative but DIP-15 specifies 10). - -**PR-12 enhancements:** - -Contact payment address registration + gap limit management: -```rust -/// (PR-12) Register payment addresses for all established contacts. -/// Derives up to highest_receive_index + GAP_LIMIT addresses per contact. -/// Returns new addresses that should be added to SPV bloom filter. -pub async fn register_contact_payment_addresses( - &self, -) -> Result, PlatformWalletError> - -/// (PR-12) Process an incoming payment detected at a contact address. -/// Returns contact info if the address matches a known contact relationship. -pub fn match_payment_to_contact( - &self, - address: &Address, -) -> Option<(Identifier, Identifier, u32)> // (owner_id, contact_id, address_index) -``` - -Gap limit = 20 per contact for receiving. When payment arrives at index N, extend -registration to N + 20. `register_contact_payment_addresses()` is called during -`sync()` and after each incoming payment to maintain the gap window. - -Account reference calculation (PR-12): -```rust -/// (PR-12) Calculate account reference per DIP-15. -/// HMAC-SHA256(sender_secret, xpub_bytes) → take 28 MSBs → XOR with account bits. -pub fn calculate_account_reference( - sender_secret_key: &[u8; 32], - contact_xpub: &ExtendedPubKey, - account_index: u32, - version: u32, -) -> u32 -``` - -#### 1.5.6 — Send Payment to Contact - -```rust -pub async fn send_dashpay_payment( - &self, - our_identity_id: &Identifier, - contact_id: &Identifier, - amount_duffs: u64, - fee_per_byte: u32, -) -> Result -``` - -Gets next unused payment index → derives address → coin-selects UTXOs → -builds, signs, broadcasts Core transaction → increments stored payment index. - -#### 1.5.7 — DashPay Sync (`DashPayWallet::sync()`) - -`DashPayWallet::sync()` is the Platform-side half of DashPay sync. It fetches new contact -request documents from DAPI and establishes the corresponding address accounts: - -```rust -pub async fn sync(&self) -> Result -``` - -Uses `sdk.fetch_all_contact_requests_for_identity(identity, limit)` which returns -`(sent_requests, received_requests)` in one call. - -For each known identity, in order: - -1. Call `sdk.fetch_all_contact_requests_for_identity(&identity, None)` → `(sent, received)` -2. For each new incoming request: call `decrypt_incoming_contact_request()` to get the sender's xpub -3. Add a `DashpayReceivingFunds` account (`AccountType::DashpayReceivingFunds { index, user_identity_id, friend_identity_id }`) to `ManagedAccountCollection` — pre-derives gap_limit (20) addresses -4. For mutual contacts (both sent + received exist): ensure `DashpayReceivingFunds` account exists - -**How incoming payments are detected (no manual registration needed):** - -`CoreWallet::monitored_addresses()` returns addresses from ALL account types including -`dashpay_receival_accounts`. After `sync()` adds a new `DashpayReceivingFunds` account, the -next SPV compact filter pass automatically watches those addresses. No separate "register -dashpay addresses" task — the gap limit pool is maintained exactly like BIP44: - -- When SPV delivers a tx matching a DashPay receiving address at index N: - - `CoreWallet::process_transaction()` calls `wallet_info.process_transaction()` - - key-wallet records the tx and marks that address used - - If `N >= pool_size - gap_limit`, the pool is extended by deriving more addresses - - Next `monitored_addresses()` call includes the new addresses — SPV picks them up - -**Gap limits:** - -- Receiving address pool per contact: 20 (same as BIP44 core, matches DIP-15: "watch highest_receive_index + 20 addresses per contact") -- Payment gap limit (sending): 10 (DIP-15 spec) - -#### 1.5.8 — Profile Management - -```rust -pub async fn create_dashpay_profile( - &mut self, - identity_id: &Identifier, - display_name: Option, - bio: Option, - avatar_url: Option, -) -> Result - -pub async fn update_dashpay_profile( - &mut self, - identity_id: &Identifier, - display_name: Option, - bio: Option, - avatar_url: Option, -) -> Result<(), PlatformWalletError> -``` - -#### 1.5.9 — Contact Info Document (Encrypted Private Metadata) - -```rust -pub async fn update_contact_info( - &mut self, - identity_id: &Identifier, - contact_id: &Identifier, - nickname: Option, - accepted_account_reference: Option, -) -> Result<(), PlatformWalletError> -``` - -Submits DashPay `contactInfo` document — only visible to the identity owner. - -#### 1.5.10 — DPNS Name Registration - -DPNS usernames are the lookup mechanism for DashPay contact discovery. - -```rust -pub async fn register_dpns_name( - &mut self, - identity_id: &Identifier, - name: &str, -) -> Result // document id -``` - -#### 1.5.11 — Auto-Accept Proof - -Auto-accept key derivation path: `m/9'/coin'/16'/timestamp'` (hardened timestamp). -Note: feature code `16'` (not `15'`) — distinct from the DashPay receiving fund path. -Proof format: 1-byte key type + 4-byte key index + 1-byte signature size + 32–96 bytes signature. - -```rust -pub fn generate_auto_accept_proof( - &self, - sender_identity_id: &Identifier, - recipient_identity_id: &Identifier, -) -> Result, PlatformWalletError> - -pub fn verify_auto_accept_proof( - &self, - proof: &[u8], - sender_identity: &Identity, - recipient_identity: &Identity, -) -> bool -``` - -#### 1.5.12 — Reject Contact Request (PR-14) - -```rust -/// Reject an incoming contact request by hiding it via contactInfo document. -/// Contact requests are immutable — rejection is done by creating/updating -/// a contactInfo document with display_hidden=true. -pub async fn reject_contact_request( - &self, - identity_id: &Identifier, - contact_identity_id: &Identifier, -) -> Result<(), PlatformWalletError> -``` - -- Document type: `contactInfo` (DashPay contract) -- Sets `display_hidden: true`, other fields empty (nickname: None, note: None, accepted_accounts: []) - -#### 1.5.13 — QR Auto-Accept Proof (PR-14) - -```rust -/// Generate auto-accept proof for QR code sharing. -/// Derivation path: m/9'/coin'/16'/timestamp' -/// Signs: SHA256(sender_id || recipient_id || account_reference) -pub fn generate_auto_accept_proof( - &self, - sender_id: &Identifier, - recipient_id: &Identifier, - account_reference: u32, - timestamp: u32, -) -> Result, PlatformWalletError> - -/// Verify an auto-accept proof from a scanned QR code. -pub fn verify_auto_accept_proof( - proof_bytes: &[u8], - sender_id: &Identifier, - recipient_id: &Identifier, - account_reference: u32, -) -> Result -``` - -- Proof format: key_type(1B) + timestamp(4B BE) + sig_size(1B) + signature(64B) -- Message: SHA256(sender_id(32B) || recipient_id(32B) || account_ref(4B LE)) - -#### 1.5.14 — Pre-Send Validation (PR-14) - -```rust -/// Validate a contact request before sending. -/// Checks sender/recipient key types, purposes, security levels, -/// core height freshness, and account reference range. -pub fn validate_contact_request( - sender_identity: &Identity, - sender_key_index: u32, - recipient_identity: &Identity, - recipient_key_index: u32, - account_reference: u32, - core_height: u32, -) -> ContactRequestValidation - -pub struct ContactRequestValidation { - pub is_valid: bool, - pub errors: Vec, - pub warnings: Vec, -} -``` - -Validation rules: -- Sender key must be ECDSA_SECP256K1, Purpose::ENCRYPTION, not disabled -- Recipient key must exist and be compatible with ECDH -- Core height within +-200 blocks of current -- Account reference within reasonable range - -#### 1.5.15 — Account Label Encryption (PR-14) - -```rust -/// Encrypt an account label for inclusion in contact request. -/// Uses ECDH shared key, CBC-AES-256 with PKCS7 padding. -/// Format: IV(16B) + ciphertext(32-64B). Max label: 62 bytes. -pub fn encrypt_account_label(label: &str, shared_key: &[u8; 32]) -> Result, PlatformWalletError> -pub fn decrypt_account_label(encrypted: &[u8], shared_key: &[u8; 32]) -> Result -``` - -#### 1.5.16 — Payment Address Registration (PR-14) - -```rust -/// Register payment addresses for all established contacts. -/// Per contact: derives addresses up to highest_receive_index + GAP_LIMIT (20). -/// Returns new addresses for SPV bloom filter registration. -pub async fn register_contact_payment_addresses( - &self, -) -> Result - -/// Match an incoming payment to a contact relationship. -pub fn match_payment_to_contact( - &self, - address: &Address, -) -> Option - -pub struct ContactPaymentMatch { - pub owner_id: Identifier, - pub contact_id: Identifier, - pub address_index: u32, -} - -pub struct ContactAddressRegistration { - pub new_addresses: Vec
, - pub contacts_processed: usize, -} -``` - -- Gap limit: 20 per contact -- Derivation path: m/9'/coin'/15'/0'/(our_id)/(contact_id)/index -- Track per-contact: highest_receive_index, registered_count -- When payment at index N arrives, extend to N + 20 - -#### 1.5.17 — Sent Contact Requests Query (PR-14) - -```rust -/// Fetch sent (outgoing) contact requests from Platform. -pub async fn sent_contact_requests( - &self, - identity_id: &Identifier, -) -> Result, PlatformWalletError> -``` - -- Query: `$ownerId == identity_id`, order by `$createdAt` -- Currently only `sync_contact_requests()` fetches incoming; need both directions - -#### Files - -- `packages/rs-platform-wallet/src/wallet/dashpay/wallet.rs` — DashPayWallet struct + methods -- `packages/rs-platform-wallet/src/wallet/dashpay/dip14.rs` — DIP-14/15 crypto, ContactXpubData -- `packages/rs-platform-wallet/src/wallet/dashpay/auto_accept.rs` — QR auto-accept proof -- `packages/rs-platform-wallet/src/wallet/dashpay/validation.rs` — ContactRequestValidation -- `packages/rs-platform-wallet/src/wallet/dashpay/contact_request.rs` — contact request types -- `packages/rs-platform-wallet/src/wallet/dashpay/established_contact.rs` — established contact types -- `packages/rs-platform-wallet/src/wallet/dashpay/crypto.rs` — crypto helpers -- Reuses: `packages/rs-platform-encryption/` (DIP-15 crypto — do NOT duplicate) - ---- - -### 1.6 Platform Addresses (DIP-17) - -> Sync, send, transfer, and withdraw DIP-17 P2PKH credits through `PlatformWallet`. - -**Key finding**: `ManagedAccountCollection` already has `platform_payment_accounts: -BTreeMap`. `ManagedPlatformAccount` (key-wallet) tracks -per-address credit balances + gap-limit address pool. `PlatformWallet` must expose these -and implement the SDK's `AddressProvider` trait. - -Derivation path (DIP-17): `m/9'/coin_type'/17'/account'/key_class'/index` -- `key_class' = 0'` for receive keys; `key_class' = 1'` reserved -- `index` is non-hardened -- Gap limit: 20 (`DIP17_GAP_LIMIT` constant in key-wallet `gap_limit.rs` — confirmed, 20 is the DIP-17 RECOMMENDED value) - -#### 1.6.1 — AddressProvider Implementation - -The rs-sdk's `sync_address_balances()` requires `&mut impl AddressProvider`. - -**`PlatformPaymentAddressProvider`** implements the `AddressProvider` trait (confirmed from -`rs-sdk/src/platform/address_sync/provider.rs`): - -```rust -pub trait AddressProvider: Send { - fn gap_limit(&self) -> AddressIndex; - fn pending_addresses(&self) -> Vec<(AddressIndex, AddressKey)>; // AddressKey = [u8; 32] - fn on_address_found(&mut self, index: AddressIndex, key: &[u8], funds: AddressFunds); - fn on_address_absent(&mut self, index: AddressIndex, key: &[u8]); - fn has_pending(&self) -> bool; - fn highest_found_index(&self) -> Option; - fn current_balances(&self) -> Vec<(AddressIndex, AddressKey, AddressFunds)>; - fn last_sync_height(&self) -> u64; -} -``` - -**Note**: The trait uses a push-based callback API (`on_address_found`/`on_address_absent`), NOT -the `addresses()` / `apply_balance()` pattern described in earlier drafts. Implementors push -address indices into a `pending_addresses` set and handle SDK callbacks as balances arrive. - -`PlatformAddressWallet` implements `AddressProvider` using `platform_payment_accounts` for -state storage. The `AddressKey` ([u8; 32]) is the DIP-17 derived P2PKH address key. - -**Gap limit extension**: The gap limit extends for ANY found address (not just the highest index). -When `on_address_found` is called, the provider extends the pending set to maintain the gap limit -window beyond the newly found address. - -**Balance cache**: `PlatformAddressWallet` maintains `balances: Arc>>` -which is updated on each `on_address_found` callback. This cache is the source of truth for -`platform_credit_balance()` and `platform_address_info()` queries. - -Function: `sync_address_balances(sdk: &Sdk, provider: &mut P, config, last_sync_timestamp)` at `rs-sdk`. - -#### 1.6.2 — Platform Address Sync - -```rust -pub async fn sync_platform_address_balances( - &self, - last_sync_timestamp: Option, -) -> Result -``` - -Calls `sync_address_balances(&self.sdk, self, config, last_sync_timestamp)` where `self` -is the `AddressProvider` implementation. - -#### 1.6.3 — Balance Accessors - -```rust -pub fn platform_credit_balance(&self) -> u64 -// Sum of platform_payment_accounts.values().credit_balance - -pub fn platform_address_info(&self) -> BTreeMap -// (balance_credits, nonce) for each known funded address - -pub fn next_platform_receive_address( - &mut self, - account: u32, - key_class: u32, -) -> Result -``` - -#### 1.6.4 — Send Credits to Platform Address (Top Up Address) - -```rust -pub async fn top_up_platform_address( - &self, - identity_id: &Identifier, - target_address: &PlatformP2PKHAddress, - amount_credits: u64, -) -> Result<(), PlatformWalletError> -``` - -Calls `sdk::TopUpAddress` state transition, funded from the identity's balance. - -#### 1.6.5 — Transfer Between Platform Addresses - -```rust -pub async fn transfer_platform_address_funds( - &self, - from_addresses: BTreeMap, // address -> credits - to_address: &PlatformP2PKHAddress, - fee_strategy: AddressFundsFeeStrategy, -) -> Result<(), PlatformWalletError> -``` - -Calls `sdk::TransferAddressFunds`. Each `from_address` signed with its DIP-17 derived key. - -#### 1.6.6 — Withdraw Platform Address Credits to Core - -```rust -pub async fn withdraw_platform_address_funds( - &self, - from_addresses: BTreeMap, - to_core_address: Option
, // None = new wallet UTXO address - fee_strategy: AddressFundsFeeStrategy, - core_fee_per_byte: u32, -) -> Result<(), PlatformWalletError> -``` - -Calls `sdk::WithdrawAddressFunds::withdraw_address_funds()`. - -#### 1.6.7 — Platform Address Signer - -`Signer` is implemented **directly on `PlatformAddressWallet`** (not a separate -struct). This gives a simpler API where `platform_wallet.platform()` can be passed as signer. - -```rust -impl Signer for PlatformAddressWallet { - fn sign(&self, address: &PlatformAddress, data: &[u8]) -> Result> { - // Sequential lock acquisition: acquire wallet read lock, derive key, drop lock - // No dual-lock window — drops first lock before acquiring second - let key = self.wallet.blocking_read() - .derive_key_for_platform_address(address, self.network)?; - // Sign with ECDSA P2PKH - sign_ecdsa(key, data) - } -} -``` - -**Implementation notes**: -- `Signer::sign()` is sync, wallet is behind `tokio::sync::RwLock`. Uses `blocking_read()` with - sequential lock acquisition — drops `wallet` lock before acquiring any other lock (no deadlock window). -- Network is accessed via `sdk.network` (no cached field). -- 4 evo-tool callsites migrated: `transfer_platform_credits`, `withdraw_from_platform_address`, - `fund_platform_address_from_asset_lock`, `top_up_identity_from_platform_addresses`. - -#### 1.6.8 — Fund from Asset Lock - -```rust -pub async fn fund_from_asset_lock( - &self, - target_address: &PlatformP2PKHAddress, - amount_duffs: u64, -) -> Result<(), PlatformWalletError> -``` - -Builds an asset lock transaction targeting a platform address, broadcasts it, waits for proof, -then uses `TopUpAddress` SDK trait to credit the platform address. - -#### Files - -- `packages/rs-platform-wallet/src/wallet/platform_addresses/wallet.rs` — PlatformAddressWallet -- `packages/rs-platform-wallet/src/wallet/platform_addresses/provider.rs` — PlatformPaymentAddressProvider - ---- - -### 1.7 Mempool Support - -> Transaction lifecycle tracking, SPV mempool processing, bloom filter management. - -**TransactionStatus** tracks the lifecycle of each Core transaction: - -```rust -pub enum TransactionStatus { - Unconfirmed, // broadcast but not yet confirmed - InstantSendLocked, // IS lock received from network - Confirmed { height: u32 }, // included in a block - ChainLocked { height: u32 }, // block is ChainLocked (final) -} -``` - -Lifecycle: `Unconfirmed → InstantSendLocked → Confirmed → ChainLocked`. -Tracked per transaction in CoreWallet. `PlatformWalletEvent::Wallet(WalletEvent)` emitted on transitions. - -**SpvWalletAdapter** implements the full `WalletInterface` (from `key_wallet_manager`): - -```rust -impl WalletInterface for SpvWalletAdapter { - fn process_block(&mut self, block: &Block, height: u32) -> BlockProcessingResult; - - fn process_mempool_transaction( - &mut self, - tx: &Transaction, - is_instant_send: bool, - ) -> MempoolTransactionResult; - - fn watched_outpoints(&self) -> Vec; - // Returns outpoints the bloom filter should watch — for mempool tx matching - - fn monitor_revision(&self) -> u64; - // Bloom filter staleness: when this changes, SPV reconstructs the bloom filter - // Incremented when addresses or watched outpoints change - - fn process_instant_send_lock(&mut self, islock: &InstantSendLock); - // Marks matching UTXOs as instant-send confirmed -} -``` - -**DashSpvClient** is parameterized with `EventHandler`: - -```rust -pub struct DashSpvClient { ... } - -// Constructor: DashSpvClient::new(config, network, storage, wallet, Arc::new(handler)) -``` - -**EventHandler** trait methods: `on_sync_event`, `on_network_event`, `on_progress`, -`on_wallet_event`, `on_error`. The platform-wallet impl forwards these to -`PlatformWalletEvent` variants. - -**SpvRuntime** SPV lifecycle (accessed via `PlatformWalletManager::spv()`): - -```rust -impl SpvRuntime { - pub async fn start(&self, config: ClientConfig) -> Result<()>; - // Creates DashSpvClient - - pub async fn stop(&self) -> Result<()>; - // Stops the client -} -``` - -**Bloom filter reconstruction**: Triggered when `monitor_revision()` changes. This happens -when new addresses are generated (gap limit extension, DashPay account creation) or when -watched outpoints change (new UTXOs received). - -#### Files - -- `packages/rs-platform-wallet/src/spv/wallet_adapter.rs` — SpvWalletAdapter (multi-wallet WalletInterface) -- `packages/rs-platform-wallet/src/spv/event_forwarder.rs` — SpvEventForwarder (EventHandler impl) -- `packages/rs-platform-wallet/src/spv/runtime.rs` — SpvRuntime (SPV lifecycle + finality) -- `packages/rs-platform-wallet/src/events.rs` — PlatformWalletEvent, SpvEvent, TransactionStatus - ---- - -### 1.8 Token Operations - -> `TokenWallet` sub-wallet with per-identity registry-based balance tracking. - -#### Status: Complete (PR-8) - -**Design**: Platform has no "list all tokens for an identity" query — -callers must specify which token IDs to track. `TokenWallet` uses a per-identity -registry: consumers call `watch(identity_id, token_id)` to register interest, -then `sync()` queries Platform for balances of all watched identity+token pairs. -This mirrors evo-tool's `identity_token_balances` DB table pattern. - -```rust -pub struct TokenWallet { - sdk: Sdk, - wallet: Arc>, - identity_manager: Arc>, - watched: Arc>>>, // identity → tokens - balances: Arc>>, // cache -} -``` - -**Registry** (per-identity): - -```rust -wallet.tokens().watch(identity_id, token_id).await; -wallet.tokens().unwatch(&identity_id, &token_id).await; -wallet.tokens().unwatch_identity(&identity_id).await; -wallet.tokens().watched_for(&identity_id).await; // → Vec -wallet.tokens().watched().await; // → Vec<(IdentityId, TokenId)> -``` - -**Sync** (queries Platform, updates cache): - -```rust -wallet.tokens().sync().await?; // fetches per identity × watched tokens -``` - -**Balance queries** (from cache): - -```rust -wallet.tokens().balance(&identity_id, &token_id).await; // → Option -wallet.tokens().balances_for_identity(&identity_id).await; // → Map -wallet.tokens().all_balances().await; // → Map<(IdentityId, TokenId), TokenAmount> -``` - -**User operations** (all take `Arc` + `TokenContractPosition` + identity): - -```rust -wallet.tokens().transfer(contract, pos, &from_id, to_id, amount).await?; -wallet.tokens().purchase(contract, pos, &id, amount, total_price).await?; -wallet.tokens().claim(contract, pos, &id, distribution_type).await?; -``` - -**Admin operations**: - -```rust -wallet.tokens().mint(contract, pos, &id, amount, recipient).await?; -wallet.tokens().burn(contract, pos, &id, amount).await?; -wallet.tokens().freeze(contract, pos, &id, target_id).await?; -wallet.tokens().unfreeze(contract, pos, &id, target_id).await?; -wallet.tokens().set_price(contract, pos, &id, price).await?; -``` - -All operations use SDK builders (`TokenTransferTransitionBuilder`, etc.) internally. -The `resolve_identity_and_signer()` helper resolves identity + HD index + signing key -from the identity manager for each operation. - -**Evo-tool integration** (future PR): Replace direct SDK calls in -`backend_task/tokens/*.rs` with `platform_wallet.tokens().*` calls. The -per-identity watch registry replaces evo-tool's `identity_token_balances` DB table. - -#### Files - -- `packages/rs-platform-wallet/src/wallet/tokens/mod.rs` -- `packages/rs-platform-wallet/src/wallet/tokens/wallet.rs` - ---- - -### 1.9 Shielded Pool - -> Feature-gated (`shielded`) ZK-private transactions using Orchard/Halo2. -> `ShieldedWallet` is generic over storage backend. - -#### Design - -ShieldedWallet is fundamentally different from other sub-wallets: -- Maintains **client-side state** (notes, nullifiers, commitment tree) that cannot be derived from Platform queries -- Requires a **storage backend** for persistence — abstracted via `ShieldedStore` trait -- Requires a **proving key** (~30s cold start, ~5MB memory) for ZK proof generation -- Uses **trial decryption** to discover incoming notes (scan all encrypted notes with viewing key) - -Generic over storage: `ShieldedWallet` — consumers provide in-memory (tests) or SQLite (production) storage. - -#### ShieldedStore trait - -```rust -/// Storage abstraction for shielded wallet state. -/// Consumers implement this for their persistence layer. -pub trait ShieldedStore: Send + Sync { - type Error: std::error::Error + Send + Sync + 'static; - - // --- Notes --- - fn save_note(&mut self, note: &ShieldedNote) -> Result<(), Self::Error>; - fn get_unspent_notes(&self) -> Result, Self::Error>; - fn get_all_notes(&self) -> Result, Self::Error>; - fn mark_spent(&mut self, nullifier: &[u8; 32]) -> Result; - - // --- Commitment tree --- - fn append_commitment(&mut self, cmx: &[u8; 32], retention: Retention) -> Result<(), Self::Error>; - fn checkpoint_tree(&mut self, checkpoint_id: u32) -> Result<(), Self::Error>; - fn witness(&self, position: u64) -> Result; - fn tree_anchor(&self) -> Result<[u8; 32], Self::Error>; - - // --- Sync state --- - fn last_synced_note_index(&self) -> Result; - fn set_last_synced_note_index(&mut self, index: u64) -> Result<(), Self::Error>; - fn nullifier_checkpoint(&self) -> Result, Self::Error>; - fn set_nullifier_checkpoint(&mut self, checkpoint: NullifierSyncCheckpoint) -> Result<(), Self::Error>; -} -``` - -Built-in implementations: -- `InMemoryShieldedStore` — for tests and short-lived wallets (Vec + BTreeMap + in-memory tree) -- No SQLite in the library — evo-tool implements `ShieldedStore` using its existing `database/shielded.rs` - -#### ShieldedNote - -```rust -pub struct ShieldedNote { - pub note: orchard::Note, // Orchard note (value, rseed, rho) - pub position: u64, // Global position in commitment tree - pub cmx: [u8; 32], // Note commitment - pub nullifier: [u8; 32], // For detecting when spent - pub block_height: u64, // Where it appeared - pub is_spent: bool, // Nullifier was seen in global set - pub value: u64, // Credits (convenience, same as note.value()) -} -``` - -#### OrchardKeySet - -```rust -/// ZIP-32 derived Orchard key hierarchy. -/// Derivation path: m/32'/coin_type'/account' (coin_type: 5=Mainnet, 1=Testnet) -pub struct OrchardKeySet { - pub spending_key: SpendingKey, - pub full_viewing_key: FullViewingKey, - pub spend_auth_key: SpendAuthorizingKey, - pub incoming_viewing_key: IncomingViewingKey, - pub outgoing_viewing_key: OutgoingViewingKey, - pub default_address: PaymentAddress, -} - -impl OrchardKeySet { - /// Derive from wallet seed bytes using ZIP-32. - pub fn from_seed(seed: &[u8], network: Network, account: u32) -> Result; - - /// Derive payment address at index. - pub fn address_at(&self, index: u32) -> PaymentAddress; - - /// Prepare incoming viewing key for efficient trial decryption. - pub fn prepared_ivk(&self) -> PreparedIncomingViewingKey; -} -``` - -#### ShieldedWallet - -```rust -pub struct ShieldedWallet { - sdk: Sdk, - keys: OrchardKeySet, - store: Arc>, - network: Network, -} -``` - -**Construction:** -```rust -impl ShieldedWallet { - pub fn new(sdk: Sdk, keys: OrchardKeySet, store: S, network: Network) -> Self; - - /// Derive keys from wallet seed and create shielded wallet. - pub fn from_seed(sdk: Sdk, seed: &[u8], network: Network, account: u32, store: S) -> Result; -} -``` - -**Sync operations:** -```rust -impl ShieldedWallet { - /// Sync notes from Platform — trial decrypts all new encrypted notes. - /// Appends all notes to commitment tree (for witness generation). - /// Stores decrypted notes that belong to us. - /// Returns count of new notes found. - pub async fn sync_notes(&self) -> Result; - - /// Check which owned notes have been spent (nullifier sync). - /// Privacy-preserving: uses trunk/branch tree scan. - /// Marks spent notes in store. - /// Returns count of newly spent notes. - pub async fn check_nullifiers(&self) -> Result; - - /// Full sync: notes + nullifiers + balance update. - pub async fn sync(&self) -> Result; -} - -pub struct SyncNotesResult { - pub new_notes: usize, - pub total_scanned: u64, -} - -pub struct ShieldedSyncSummary { - pub notes_result: SyncNotesResult, - pub newly_spent: usize, - pub balance: u64, -} -``` - -**Balance queries:** -```rust -impl ShieldedWallet { - /// Total unspent shielded balance. - pub async fn balance(&self) -> Result; - - /// Default payment address for receiving shielded funds. - pub fn default_address(&self) -> &PaymentAddress; - - /// Derive address at specific index. - pub fn address_at(&self, index: u32) -> PaymentAddress; -} -``` - -**Operations (5 transition types):** - -Each operation: -1. Selects spendable notes (if spending) -2. Generates Merkle witness paths from commitment tree -3. Builds Orchard bundle via DPP `build_*_transition()` builders -4. Broadcasts via SDK traits (`ShieldFunds`, `UnshieldFunds`, `TransferShielded`, `WithdrawShielded`, `ShieldFromAssetLock`) -5. Marks spent notes in store - -```rust -impl ShieldedWallet { - /// Shield: platform addresses -> shielded pool. - /// Uses Signer for input authorization. - pub async fn shield>( - &self, - inputs: BTreeMap, - amount: u64, - signer: &Signer, - ) -> Result<(), PlatformWalletError>; - - /// Shield from asset lock: Core L1 -> shielded pool. - pub async fn shield_from_asset_lock( - &self, - asset_lock_proof: AssetLockProof, - private_key: &[u8], - amount: u64, - ) -> Result<(), PlatformWalletError>; - - /// Unshield: shielded pool -> platform address. - pub async fn unshield( - &self, - to_address: &PlatformAddress, - amount: u64, - ) -> Result<(), PlatformWalletError>; - - /// Transfer: shielded pool -> shielded pool (private). - pub async fn transfer( - &self, - to_address: &PaymentAddress, - amount: u64, - ) -> Result<(), PlatformWalletError>; - - /// Withdraw: shielded pool -> Core L1 address. - pub async fn withdraw( - &self, - to_address: &Address, - amount: u64, - core_fee_per_byte: u32, - ) -> Result<(), PlatformWalletError>; -} -``` - -**Proving key management:** -```rust -/// Cached proving key — built once (~30s), reused for all proofs. -/// Use `warm_up()` at app startup to avoid blocking first operation. -pub struct CachedOrchardProver { - key: OnceLock, -} - -impl CachedOrchardProver { - pub fn new() -> Self; - pub fn warm_up(&self); // Build key in background - pub fn is_ready(&self) -> bool; -} - -impl OrchardProver for CachedOrchardProver { - fn proving_key(&self) -> &ProvingKey { self.key.get_or_init(ProvingKey::build) } -} -``` - -The `CachedOrchardProver` is held as a static or on `PlatformWalletManager`. All `ShieldedWallet` instances share it. - -**Note selection for spending:** -```rust -/// Select notes to cover the requested amount + fee. -/// Returns selected notes with Merkle witness paths from commitment tree. -fn select_spendable_notes( - store: &S, - amount: u64, - fee: u64, -) -> Result, PlatformWalletError>; -``` - -Greedy selection: sort unspent notes by value descending, accumulate until >= amount + fee. - -#### Integration with PlatformWallet - -`ShieldedWallet` is a **standalone component** — not a field on `PlatformWallet`. This avoids -infecting `PlatformWallet` with the `S: ShieldedStore` type parameter. Consumers create -`ShieldedWallet` separately, providing their own `ShieldedStore` implementation: - -```rust -// Consumer creates ShieldedWallet separately -let shielded = ShieldedWallet::from_seed( - sdk, &seed_bytes, network, 0, InMemoryShieldedStore::new() -)?; -shielded.sync().await?; -shielded.shield(inputs, amount, &platform_signer).await?; -``` - -`ShieldedWallet` shares the `Sdk` with `PlatformWallet` but manages its own state through -the `ShieldedStore` backend. - -#### Files - -- `packages/rs-platform-wallet/src/wallet/shielded/mod.rs` — ShieldedWallet, re-exports -- `packages/rs-platform-wallet/src/wallet/shielded/keys.rs` — OrchardKeySet, ZIP-32 derivation -- `packages/rs-platform-wallet/src/wallet/shielded/store.rs` — ShieldedStore trait, ShieldedNote, InMemoryShieldedStore -- `packages/rs-platform-wallet/src/wallet/shielded/sync.rs` — sync_notes, check_nullifiers, sync -- `packages/rs-platform-wallet/src/wallet/shielded/operations.rs` — shield, unshield, transfer, withdraw, shield_from_asset_lock -- `packages/rs-platform-wallet/src/wallet/shielded/prover.rs` — CachedOrchardProver -- `packages/rs-platform-wallet/src/wallet/shielded/note_selection.rs` — select_spendable_notes - ---- - -### 1.10 State Transition Signing Facade - -> `PlatformWallet` provides `IdentitySigner` so callers never manage key material directly. - -```rust -// platform_wallet/signer.rs -pub struct IdentitySigner { - wallet: Arc>, - identity_index: u32, // required (u32, not Optional) -} - -impl Signer for IdentitySigner { - fn sign(&self, key: &IdentityPublicKey, data: &[u8]) -> Result> { - // Derive private key using 3-component DIP-9 path: - // m/9'/coin'/5'/0'/key_type'/identity_index'/key_index' - // where key_type: 0' = ECDSA, 1' = BLS - let secret = Zeroizing::new( - self.wallet.blocking_read() - .derive_identity_key(self.identity_index, key.id(), key.key_type())? - ); - match key.key_type() { - KeyType::ECDSA_SECP256K1 | KeyType::ECDSA_HASH160 => sign_ecdsa(&secret, data), - KeyType::BLS12_381 => sign_bls(&secret, data), - KeyType::EDDSA_25519_HASH160 => sign_eddsa(&secret, data), - } - } -} -``` - -**Private key zeroization**: All derived key material uses `Zeroizing<[u8; 32]>`. Keys are -zeroed on drop — no plaintext key material persists in memory after signing. - -Factory on `IdentityWallet` — no external `wallet` param, borrows from `self.wallet`: - -```rust -pub fn signer_for_identity( - &self, - identity_id: &Identifier, -) -> Result -// Looks up identity_index from ManagedIdentity (u32, required) -``` - -**`PlatformAddressWallet` as `Signer`**: See §1.6.7. Uses sequential lock -acquisition with `blocking_read()` — no dual-lock window. - -**Important**: `WithdrawFromIdentity::withdraw` and `TransferToIdentity::transfer_credits` take -the signer **by value** (not by reference). Callers must construct a new `IdentitySigner` for -each call, or the signer must implement `Clone`. - -**Implementation notes**: -- Derives keys at `m/9'/coin_type'/5'/0'/key_type'/identity_index'/key_index'` (3-component DIP-9 path) -- Signs based on key type: ECDSA (`secp256k1`), BLS (`bls-signatures`), EdDSA (`ed25519-dalek`) -- Sync/async bridge: `blocking_read()` — safe because SDK calls `sign()` from blocking context -- Replaces evo-tool's `QualifiedIdentity::sign()` long-term - -#### Files - -- `packages/rs-platform-wallet/src/wallet/signer.rs` (extend existing stub) - ---- - -### 1.11 Serialization / Persistence - -> `PlatformWallet` is the single persistence unit — callers (e.g. evo-tool's SQLite) store -> the blob and don't need to know about sub-struct layout. - -```rust -// Top-level backup/restore — covers Wallet + ManagedWalletInfo + IdentityManager + DashPay state -pub fn backup(&self) -> Result, PlatformWalletError> -pub fn restore(data: &[u8]) -> Result -``` - -`Sdk` is excluded from the blob (it's a live connection) — caller re-provides it via -`PlatformWallet::from_bytes(sdk, blob)`. - -`ManagedWalletInfo` and `ManagedAccountCollection` already have `#[cfg(feature="bincode")]` -encode/decode. `ManagedPlatformAccount` and `PlatformP2PKHAddress` already have bincode. -Still missing serialization: - -- `IdentityManager` — add bincode `Encode`/`Decode` (with `Arc>` wrapping, serialize inner values) -- `ManagedIdentity` (Identity + BlockTime + contact maps) — add bincode -- `ContactRequest` — add bincode -- `EstablishedContact` — add bincode - -#### Files - -- `packages/rs-platform-wallet/src/wallet/identity/serialization.rs` (new) -- `packages/rs-platform-wallet/src/wallet/identity/managed_identity/serialization.rs` (new) -- `packages/rs-platform-wallet/src/wallet/dashpay/contact_request.rs` (extend) -- `packages/rs-platform-wallet/src/wallet/dashpay/established_contact.rs` (extend) - ---- - -### 1.12 Sync Architecture - -There are **three distinct sync mechanisms** with different lifecycles: - -#### Core chain sync — push-based, long-running - -`dash-spv` runs as a permanent background task started once at app startup. It pushes -blocks and transactions to `CoreWallet` via `WalletInterface` callbacks — no polling needed: - -```rust -// App startup — spawned once, runs until cancellation -tokio::spawn(async move { - spv_client.run(cancellation_token).await -}); -// dash-spv calls SpvWalletAdapter::process_block() reactively as blocks arrive -``` - -#### Mempool reconciliation — push-based, event-driven - -SPV also delivers mempool transactions via `process_mempool_transaction(tx, is_instant_send)`. -The `TransactionStatus` lifecycle tracks each transaction: - -``` -Unconfirmed → InstantSendLocked → Confirmed { height } → ChainLocked { height } -``` - -- `process_mempool_transaction` is called when SPV receives an unconfirmed tx matching watched addresses -- `process_instant_send_lock` upgrades status from `Unconfirmed` to `InstantSendLocked` -- `process_block` upgrades to `Confirmed` when the tx appears in a block -- ChainLock events upgrade to `ChainLocked` - -`PlatformWalletEvent::Wallet(WalletEvent)` is emitted on each status transition. - -**Bloom filter staleness**: `monitor_revision()` is incremented when addresses or watched outpoints -change. SPV detects the change and reconstructs the bloom filter to include the new addresses. - -#### Platform sync — poll-based, periodic - -Platform state (identities, contacts, credit balances) is fetched via DAPI on a timer. -`PlatformWallet::sync()` is the single entry point: - -```rust -pub async fn sync(&self) -> Result -``` - -Sync order: - -1. `self.identity.sync()` — DIP-9 gap scan for new identities -2. `self.dashpay.sync()` — contact requests for all known identities -3. `self.platform.sync()` — DIP-17 address credit balances via DAPI -4. `self.shielded.sync()` (if feature enabled) — note sync + nullifier sync + tree updates - -**Shielded note sync** (feature-gated): Trial decryption of Orchard output notes using the -`FullViewingKey`. Discovered notes stored in `NoteStore`. Nullifier sync detects spent notes. -Commitment tree updated with each batch of processed notes. - -Designed to run on a timer in the app's background loop: - -```rust -tokio::spawn(async move { - let mut interval = tokio::time::interval(Duration::from_secs(30)); - loop { - interval.tick().await; - if let Err(e) = wallet.sync().await { - tracing::warn!("Platform sync failed: {}", e); - } - } -}); -``` - -Sub-struct `sync()` methods remain individually callable for fine-grained control. -`PlatformWallet` is `Send + Sync` — safe to share across threads via `Arc`. - ---- - -## PR Sequence - -Each PR implements features in `rs-platform-wallet` **and** immediately integrates into `evo-tool`. -Old evo-tool code is deleted in the same PR that introduces the replacement. - ---- - -### PR-1: Project Scaffold + PlatformWallet + PlatformWalletManager + CoreWallet - -**Library** (`rs-platform-wallet`): - -- Clean up `lib.rs`: replace `pub mod platform_wallet_info` with `pub mod platform_wallet` -- `PlatformWallet` struct with stored sub-wallets sharing `Arc>` (§Struct Definitions) -- `PlatformWallet` creation methods mirroring `key-wallet`'s `Wallet` constructors + `sdk` param (§1.1) -- `CoreWallet` with `Arc>`, balance, UTXOs, address generation (§1.3) -- `PlatformWalletManager`: multi-wallet coordinator, `RwLock` for wallet add/remove -- `SpvWalletAdapter` implements `WalletInterface` using `key-wallet` types (`TransactionRouter`, `WalletTransactionChecker`) — no `WalletManager` dependency (§1.3.5, §1.7) -- `PlatformWalletEvent` unified enum: `Wallet(WalletEvent)`, `Spv(SpvEvent)` (two variants only) -- `monitored_addresses()` returns ALL account types including `dashpay_receival_accounts` -- `send_transaction`, `broadcast_transaction`, asset lock proof creation (§1.3.4–1.3.6) -- Asset lock timeout/fallback: 60s InstantLock wait, then ChainLock polling -- `IdentitySigner` stub (§1.10) — needed for identity registration in PR-2 -- `static_assertions::assert_impl_all!(PlatformWallet: Send, Sync)` -- `IdentityManager` refactor: add `last_scanned_index`, remove `sdk` field - -**evo-tool integration**: - -- Add `platform-wallet = { path = "../../platform/packages/rs-platform-wallet" }` to `Cargo.toml` -- Replace `AppContext.wallets` + `SpvManager` with `PlatformWalletManager` -- `wallet_lifecycle.rs`: construct via `PlatformWallet::from_mnemonic()` / `from_xprv()`, wire `sdk` from `AppContext.sdk` -- SPV: `SpvRuntime::start()` (via `PlatformWalletManager::spv()`) replaces manual `SpvManager` setup -- `PlatformWallet.clone()` replaces `WalletSeedHash` as wallet accessor (no WalletHandle) -- Delete `src/model/wallet/` (old custom wallet struct) - -**Database migration** (in this PR): - -- Add version byte to DB wallet record -- If old format: deserialize as old `Wallet`, convert to `PlatformWallet`, re-save -- On first run after migration: `IdentityManager` starts empty — identities re-discovered in PR-2 - -**Done when**: evo-tool builds with `PlatformWalletManager`; SPV sync works via `WalletInterface` impl; `send_transaction` works; PlatformWallet clone provides sync access to sub-wallets. - -**PR-1 status**: ✅ Complete. Scaffold in place, bridge working, 7 backend tasks validating via bridge. - ---- - -### PR-2: CoreWallet Deep Integration - -**Library** (`rs-platform-wallet`): - -- Per-address data methods on CoreWallet (§1.3.3): `all_address_info()`, `account_summaries()`, `utxos_by_address()`, `derivation_path_for_address()` -- `CoreAddressInfo` and `CoreAccountSummary` structs -- `Signer` on `PlatformAddressWallet` (§1.6) with `blocking_read()` bridge -- Asset lock proof creation on CoreWallet (§1.3.6): `create_asset_lock_proof()`, `create_topup_asset_lock_proof()` -- Asset lock recovery (§1.3.7): `recover_asset_locks()` -- Transaction sending: `send_transaction()` on CoreWallet (§1.3.4) -- `PlatformAddressWallet` uses `sdk.network` for network access - -**evo-tool integration**: - -- Migrate 4 signing callsites from old `Wallet` to `platform_wallet.platform()` as `Signer` -- Migrate `generate_receive_address` from diagnostic to primary path -- Add `WalletTask::LoadAddressTable` backend task using `CoreWallet::all_address_info()` -- Update address table UI to render from cached `CoreAddressInfo` snapshot -- Migrate `create_asset_lock` tasks to use `CoreWallet::create_asset_lock_proof()` - -**Done when**: All backend tasks that touch balance/UTXOs/addresses use CoreWallet; signing uses PlatformAddressWallet; asset lock creation works through platform-wallet. - ---- - -### PR-3: IdentityWallet - -**Library** (`rs-platform-wallet`): - -- `IdentityWallet` with `identity_manager`, sdk, wallet Arc (§1.4) -- `register_identity` (with corrected `m/9'/coin'/5'/0'/key_type'/identity_index'/key_index'` path), `sync()`, `refresh_identity` (§1.4.1–1.4.3) -- Identity discovery: gap limit 5, consider AUTH_KEY_LOOKUP_WINDOW = 12 for key index scanning -- `top_up_identity`, `withdraw_identity_credits`, `transfer_credits` (§1.4.4–1.4.6) -- `add_key_to_identity`, `disable_identity_key` (§1.4.7) -- `IdentitySigner` complete (§1.10) -- `IdentityManager` bincode serialization (§1.11 partial) -- DPNS name registration (§1.5.10, belongs to IdentityWallet for SDK access) - -**evo-tool integration**: - -| File | Action | -|------|--------| -| `backend_task/identity/discover_identities.rs` | → `wallet.identity.sync()` | -| `backend_task/identity/register_identity.rs` | → `wallet.identity.register_identity()` | -| `backend_task/identity/top_up_identity.rs` | → `wallet.identity.top_up_identity()` | -| `backend_task/identity/withdraw_from_identity.rs` | → `wallet.identity.withdraw_identity_credits()` | -| `backend_task/identity/transfer.rs` | → `wallet.identity.transfer_credits()` | -| `backend_task/identity/add_key_to_identity.rs` | → `wallet.identity.add_key_to_identity()` | - -All signing replaced with `wallet.identity.signer_for_identity(identity_id)`. - -**Done when**: Identity registration and discovery work in evo-tool via library; old identity task files deleted. - ---- - -### PR-4: DashPayWallet (DIP-14 + DIP-15 + Sync) - -**Library** (`rs-platform-wallet`): - -- DIP-14: `ckd_priv_256`, `ckd_pub_256`, `derive_dashpay_contact_xpub` in `dashpay/dip14.rs` (§1.5.1) - - Big-endian `ser_256(i)` — verify and test before relying on it -- DIP-15: Reuse `rs-platform-encryption` — do NOT duplicate functions (§1.5.2) -- Fix the AES decryption bug: `decrypt_extended_public_key` before `ExtendedPubKey::decode` -- Fix recipient key purpose: use `Purpose::DECRYPTION`, not `ENCRYPTION` -- `DashPayWallet` with `send_contact_request`, `decrypt_incoming_contact_request` (§1.5.3–1.5.4) -- `derive_payment_address_for_contact` (gap limit: 10), `send_dashpay_payment` (§1.5.5–1.5.6) -- `DashPayWallet::sync()` using `sdk.fetch_all_contact_requests_for_identity()` (§1.5.7) -- Profile, contact info, auto-accept proof (§1.5.8–1.5.11) -- `ManagedIdentity` contact maps + `ContactRequest` + `EstablishedContact` bincode (§1.11) - -Test against DIP-14 Appendix A test vectors before merging. -Note: `contactRequest` documents are immutable — do not expose update/delete operations. - -**evo-tool integration**: - -| File | Action | -|------|--------| -| `backend_task/dashpay/dip14_derivation.rs` | Delete (replaced by `platform_wallet/dashpay/dip14.rs`) | -| `backend_task/dashpay/hd_derivation.rs` | Delete | -| `backend_task/dashpay/encryption.rs` | Delete (was duplicating `rs-platform-encryption`) | -| `backend_task/dashpay/contact_requests.rs` | → `wallet.dashpay.send_contact_request()` | -| `backend_task/dashpay/contacts.rs` | → `wallet.dashpay.sync()` | -| `backend_task/dashpay/payments.rs` | → `wallet.dashpay.send_dashpay_payment()` | -| `backend_task/dashpay/incoming_payments.rs` | → `wallet.dashpay.sync()` handles this | -| `backend_task/dashpay/profile.rs` | → `wallet.dashpay.create_dashpay_profile()` | -| `backend_task/dashpay/auto_accept_proof.rs` | → `wallet.dashpay.generate_auto_accept_proof()` | -| `backend_task/dashpay/contact_info.rs` | → `wallet.dashpay.update_contact_info()` | - -**Done when**: DIP-14 vectors pass; contact requests sent/received and decrypted correctly (including AES decryption fix); incoming DashPay payments detected via SPV without manual address registration. - ---- - -### PR-5: PlatformAddressWallet (DIP-17) - -**Library** (`rs-platform-wallet`): - -- `PlatformAddressWallet` with actual `AddressProvider` impl — push-based callbacks (`pending_addresses`, `on_address_found`, `on_address_absent`) (§1.6.1) -- `sync_platform_address_balances`, balance accessors (§1.6.2–1.6.3) -- `top_up_platform_address`, `transfer_platform_address_funds`, `withdraw_platform_address_funds` (§1.6.4–1.6.6) -- `Signer` on `PlatformAddressWallet` directly (§1.6.7) - -**evo-tool integration**: - -- `backend_task/wallet/fetch_platform_address_balances.rs`: replace `WalletAddressProvider::new(&wallet, ...)` with `wallet.platform` as `AddressProvider` -- Replace `wallet.platform_address_info` field access with `wallet.platform.platform_address_info()` - -**Done when**: DIP-17 address balance sync works; top-up, transfer, and withdrawal work in evo-tool. - ---- - -### PR-7 Status: Complete - -### What was delivered - -- `IdentityWallet::update_identity(add_keys, disable_keys)` — `IdentityUpdateTransition` via DPP - (nonce lookup, master key signing, broadcast_and_wait) -- `IdentityWallet::top_up_from_addresses()` — `TopUpIdentityFromAddresses` SDK trait -- `IdentityWallet::transfer_credits_to_addresses()` — `TransferToAddresses` SDK trait -- `IdentityWallet::register_name()` — DPNS username registration via `Sdk::register_dpns_name` -- `IdentityWallet::resolve_name()` — DPNS resolution via `Sdk::resolve_dpns_name` -- `IdentityWallet::search_names()` — DPNS prefix search via `Sdk::search_dpns_names` -- `PlatformAddressWallet::fund_from_asset_lock()` — `TopUpAddress` SDK trait - -All identity fund flows now work: L1→identity, address→identity, identity→address. -Identity keys can be added/disabled. DPNS names can be registered, resolved, and searched. - ---- - -### PR-8 Status: Complete - -### What was delivered - -**TokenWallet** — per-identity registry-based token balance tracking and operations: - -- **Registry**: `watch(identity_id, token_id)` / `unwatch()` / `unwatch_identity()` / `watched_for()` / `watched()` - — per-identity token watch list (mirrors evo-tool's `identity_token_balances` DB pattern) -- **Sync**: `sync()` queries Platform via `FetchMany` for each - identity's watched tokens, updates local `BTreeMap<(IdentityId, TokenId), TokenAmount>` cache -- **Balance queries**: `balance()`, `balances_for_identity()`, `all_balances()` — read from cache -- **User operations**: `transfer()`, `purchase()`, `claim()` — SDK builders + broadcast -- **Admin operations**: `mint()`, `burn()`, `freeze()`, `unfreeze()`, `set_price()` — SDK builders + broadcast -- All operations take `Arc` + `TokenContractPosition` to identify the token - (wallet doesn't store contract metadata, only balances) -- Shared `resolve_identity_and_signer()` helper for all token operations - -**Evo-tool integration** (future PR): Replace direct SDK calls in `backend_task/tokens/*.rs` -with `platform_wallet.tokens().*`. The per-identity watch registry replaces the -`identity_token_balances` SQLite table. - ---- - -### PR-9: Evo-tool integration - -Replace ALL evo-tool backend tasks with platform-wallet calls across every domain: -tokens, identity, dashpay, core wallet, platform addresses. Evo-tool keeps its own -`SpvManager` — SPV migration is PR-11. - -**Migration by domain** (in `dash-evo-tool/src/backend_task/`): - -**Phase 1 — Tokens** (~17 tasks, all trivial SDK wrappers): -| Evo-tool task | Replaced by | -|---------------|-------------| -| `tokens/transfer_tokens.rs` | `wallet.tokens().transfer()` | -| `tokens/mint_tokens.rs` | `wallet.tokens().mint()` | -| `tokens/burn_tokens.rs` | `wallet.tokens().burn()` | -| `tokens/freeze_tokens.rs` | `wallet.tokens().freeze()` | -| `tokens/unfreeze_tokens.rs` | `wallet.tokens().unfreeze()` | -| `tokens/claim_tokens.rs` | `wallet.tokens().claim()` | -| `tokens/purchase_tokens.rs` | `wallet.tokens().purchase()` | -| `tokens/set_token_price.rs` | `wallet.tokens().set_price()` | -| `tokens/query_my_token_balances.rs` | `wallet.tokens().sync()` + `.balance()` | - -**Phase 2 — Simple identity + DPNS** (trivial wrappers): -| Evo-tool task | Replaced by | -|---------------|-------------| -| `identity/withdraw_from_identity.rs` | `wallet.identity().withdraw_credits()` | -| `identity/transfer.rs` | `wallet.identity().transfer_credits()` | -| `identity/refresh_identity.rs` | `wallet.identity().sync()` | -| `identity/add_key_to_identity.rs` | `wallet.identity().update_identity()` | -| `identity/register_dpns_name.rs` | `wallet.identity().register_name()` | -| `identity/load_identity_by_dpns_name.rs` | `wallet.identity().resolve_name()` | - -**Phase 3 — Identity registration + top-up + discovery** (asset lock handling): -| Evo-tool task | Replaced by | -|---------------|-------------| -| `identity/register_identity.rs` | `wallet.identity().register_identity()` (uses `wallet.core()` for asset locks) | -| `identity/top_up_identity.rs` | `wallet.identity().top_up_identity()` | -| `identity/discover_identities.rs` | `wallet.identity().sync()` | -| `identity/load_identity.rs` | Adapter: fetch via SDK + register in `identity_manager` | -| `identity/load_identity_from_wallet.rs` | Adapter: HD derivation + `wallet.identity().sync()` | - -**Phase 4 — DashPay contacts** (encryption via `rs-platform-encryption`): -| Evo-tool task | Replaced by | -|---------------|-------------| -| `dashpay/contact_requests.rs` (send) | `wallet.dashpay().send_contact_request()` | -| `dashpay/contact_requests.rs` (accept) | `wallet.dashpay().accept_contact_request()` | -| `dashpay/contact_requests.rs` (load) | `wallet.dashpay().sync_contact_requests()` | -| `dashpay/contacts.rs` | `wallet.dashpay().established_contacts()` | - -**Phase 5 — Core wallet + platform addresses**: -| Evo-tool task | Replaced by | -|---------------|-------------| -| `core/create_asset_lock.rs` | `wallet.core().build_registration_asset_lock_transaction()` + `.broadcast_transaction()` | -| `core/refresh_wallet_info.rs` | SPV feeds `ManagedWalletInfo` directly (no change needed) | -| Platform address transfer | `wallet.platform().transfer()` | -| Platform address withdraw | `wallet.platform().withdraw()` | -| Platform address fund | `wallet.platform().fund_from_asset_lock()` | -| Signing callsites (4+) | `wallet.platform()` as `Signer` | - -**Bridge architecture** (in `dash-evo-tool/src/context/`): -- `platform_wallet_bridge.rs` exists from PR-1 on `feat/platform-wallet` branch -- Extend bridge: `register_with_platform_wallet_manager()` for all wallet types -- Backend tasks call `require_platform_wallet()` → delegate to platform-wallet -- Evo-tool DB persistence remains — platform-wallet results are persisted by evo-tool after each operation - -**What stays in evo-tool**: -- `SpvManager` — keeps its own `DashSpvClient`, `ConnectionStatus`, debounced reconciliation (→ PR-11) -- Database layer — SQLite persistence for wallet state, identities, tokens, contacts -- UI screens — presentation unchanged, backend calls change -- `QualifiedIdentity` model — adapter maps to/from platform-wallet's `IdentityManager` - -**What gets deleted**: -- Direct SDK calls in backend tasks (replaced by `wallet.*()` calls) -- Duplicate crypto code (`dashpay/encryption.rs`, `dashpay/dip14_derivation.rs`) → use `rs-platform-encryption` -- Duplicate wallet model code in `src/model/wallet/` (partially — full deletion in PR-15) - -**Done when**: All backend tasks delegate to platform-wallet. No direct SDK identity/token/address/dashpay -calls remain in evo-tool backend tasks. SPV and database stay. - -**Done when**: All backend tasks delegate to platform-wallet. No direct SDK identity/token/address -calls remain in evo-tool (except SPV and database). Duplicate wallet code deleted. - ---- - -### PR-10: Enrich ManagedIdentity - -**Goal**: Make `ManagedIdentity` rich enough to replace evo-tool's `QualifiedIdentity` for -wallet-based identities. Any app using platform-wallet should get full identity management -without reimplementing key storage, status tracking, or discovery. - -**1. KeyStorage with lazy wallet derivation** - -Replace flat private key storage with a `PrivateKeyData` enum: - -```rust -pub enum PrivateKeyData { - /// Raw key bytes in memory. - Clear(Zeroizing<[u8; 32]>), - /// Derive on-demand from wallet at this path (key not held in memory). - AtWalletDerivationPath { - wallet_seed_hash: [u8; 32], - derivation_path: DerivationPath, - }, -} -``` - -`ManagedIdentity` gets a `KeyStorage` map: `BTreeMap`. - -When signing, if the key is `AtWalletDerivationPath`, the signer resolves it by finding the -wallet by seed hash, acquiring a read lock, and deriving at the path. This avoids storing -private keys in memory for wallet-backed identities. - -**2. IdentityStatus state machine** - -```rust -pub enum IdentityStatus { - Unknown, // Not yet checked against Platform - PendingCreation, // Registration submitted, awaiting confirmation - Active, // Confirmed on Platform - FailedCreation, // Registration failed (can retry) - NotFound, // Was active but no longer on Platform -} -``` - -Status transitions: `Unknown → PendingCreation → Active` (happy path), -`PendingCreation → FailedCreation → Active` (retry), `Active → NotFound → Active` (reappears). - -**3. DPNS name association** - -```rust -pub struct DpnsNameInfo { - pub label: String, // e.g., "alice" - pub acquired_at: Option, // timestamp -} -``` - -Add `dpns_names: Vec` to `ManagedIdentity`. Populated during `sync()` by querying -DPNS contract for documents with `records.identity == identity_id`. - -**4. Enhanced identity discovery** - -Current `sync()` only checks key_index 0 (primary auth key). Enhance to: -- Scan key indices 0..12 per identity index (12-key lookup window) -- Support ECDSA_HASH160 matching (not just full pubkey) -- Fetch DPNS names for discovered identities -- Store matched derivation paths in `KeyStorage` as `AtWalletDerivationPath` - -**5. Wallet association** - -Add `wallet_seed_hash: Option<[u8; 32]>` and `wallet_index: Option` to `ManagedIdentity`. -These link an identity back to the wallet it was registered from, enabling key re-derivation -on wallet recovery. - -**Files to modify:** -- `src/wallet/identity/managed_identity/mod.rs` — KeyStorage, IdentityStatus, DpnsNameInfo, wallet fields -- `src/wallet/identity/wallet.rs` — enhanced `sync()` with multi-key window + DPNS -- `src/wallet/signer.rs` — support `AtWalletDerivationPath` resolution - -**Done when**: `ManagedIdentity` has rich key storage, status tracking, DPNS names, and wallet -association. Discovery finds identities with any registered key, not just the primary. - ---- - -### PR-11: Asset lock lifecycle + multi-mode funding - -**Goal**: Handle the full asset lock lifecycle and support all identity funding modes. -Any app should be able to register/top-up identities without reimplementing IS→CL fallback -or UTXO management. - -**1. Asset lock tracking** - -```rust -pub struct TrackedAssetLock { - pub transaction: Transaction, - pub output_address: Address, - pub amount_duffs: u64, - pub proof: Option, // None until IS/CL arrives - pub identity_id: Option, // None until used for registration - pub status: AssetLockStatus, -} - -pub enum AssetLockStatus { - Broadcast, // TX sent, waiting for proof - InstantLocked, // IS proof received - ChainLocked, // CL proof received (higher finality) - UsedForRegistration, // Linked to an identity - UsedForTopUp, // Linked to an identity top-up -} -``` - -Add `tracked_asset_locks: Arc>>` to `CoreWallet`. -Methods: `unused_asset_locks()`, `track_asset_lock()`, `mark_used()`. - -**2. IS→CL fallback** - -When Platform rejects an InstantSend proof (`AssetLockInstantLockProofInvalid`): -1. Query DAPI for the TX to check `is_chain_locked` and `height` -2. If chain-locked and Platform has verified that height → retry with `ChainAssetLockProof` -3. If not chain-locked → return `AssetLockExpired` error - -This logic lives in a shared `resolve_asset_lock_proof()` method used by both -registration and top-up. - -**3. Multi-mode identity registration** - -```rust -pub enum IdentityFundingMethod { - /// Use a pre-existing asset lock proof. - UseAssetLock { - proof: AssetLockProof, - private_key: PrivateKey, - }, - /// Build asset lock from wallet UTXOs. - FundWithWallet { - amount_duffs: u64, - }, - /// Use a specific UTXO. - FundWithUtxo { - outpoint: OutPoint, - txout: TxOut, - address: Address, - }, - /// Fund from platform addresses (no asset lock needed). - FundFromAddresses { - inputs: BTreeMap, - }, -} -``` - -`IdentityWallet::register_identity()` updated to accept `IdentityFundingMethod`. -The `FundWithWallet` path builds the asset lock internally, broadcasts, waits for proof -(with IS→CL fallback). `FundFromAddresses` uses `put_with_address_funding()`. - -**4. Multi-mode identity top-up** - -Same pattern with `TopUpFundingMethod` (UseAssetLock, FundWithWallet, FundWithUtxo). -`FundFromAddresses` uses `top_up_from_addresses()` (already implemented in PR-7). - -**5. UTXO retry on exhaustion** - -When building an asset lock TX fails due to insufficient UTXOs: -1. Release wallet lock -2. Refresh UTXOs (if SPV running, trigger rescan; otherwise return error) -3. Retry once - -**Files to create/modify:** -- `src/wallet/core/asset_lock.rs` — new: TrackedAssetLock, AssetLockStatus, tracking methods -- `src/wallet/core/wallet.rs` — add tracked_asset_locks field, resolve_asset_lock_proof() -- `src/wallet/identity/wallet.rs` — multi-mode register_identity(), top_up_identity() -- `src/wallet/identity/funding.rs` — new: IdentityFundingMethod, TopUpFundingMethod enums -- `src/error.rs` — AssetLockExpired, AssetLockNotChainLocked error variants - -**Done when**: Identity registration/top-up works with all 4/3 funding modes. -IS→CL fallback is automatic. Asset locks are tracked from broadcast to use. - ---- - -### PR-12: DashPay completeness - -**Goal**: Move DashPay protocol-level crypto from evo-tool into platform-wallet. -DIP-14 256-bit derivation, contact payment addresses, and account reference calculation -are protocol specifications, not application logic. - -**1. DIP-14 256-bit key derivation** - -Move from evo-tool's `dip14_derivation.rs` into platform-wallet (or `rs-platform-encryption`): - -```rust -/// Child key derivation with 256-bit index (DIP-14). -/// For contact-based derivation paths where identity IDs (32 bytes) are used as indices. -pub fn ckd_priv_256( - parent: &ExtendedPrivKey, - index: &[u8; 32], - hardened: bool, -) -> Result - -pub fn ckd_pub_256( - parent: &ExtendedPubKey, - index: &[u8; 32], -) -> Result -``` - -**2. DashPay xpub derivation** - -```rust -/// Derive the contact-specific extended public key. -/// Path: m/9'/coin'/15'/account'/(sender_id)/(recipient_id) -/// Uses DIP-14 256-bit derivation for the identity ID segments. -pub fn derive_contact_xpub( - wallet: &Wallet, - network: Network, - account_index: u32, - sender_id: &Identifier, - recipient_id: &Identifier, -) -> Result<(ExtendedPubKey, [u8; 4], [u8; 32], [u8; 33]), Error> -// Returns: (xpub, parent_fingerprint, chain_code, compressed_pubkey) -``` - -**3. Account reference calculation (DIP-15)** - -```rust -/// Calculate account reference per DIP-15. -/// HMAC-SHA256(sender_secret, xpub_bytes) → take 28 MSBs → XOR with account bits. -pub fn calculate_account_reference( - sender_secret_key: &[u8; 32], - contact_xpub: &ExtendedPubKey, - account_index: u32, - version: u32, -) -> u32 -``` - -**4. Contact payment address derivation** - -```rust -/// Derive payment receiving address for a contact at a given index. -/// Standard BIP32 from contact xpub: contact_xpub / index -pub fn derive_contact_payment_address( - contact_xpub: &ExtendedPubKey, - index: u32, - network: Network, -) -> Address -``` - -**5. Contact payment address registration + gap limit** - -Add to `DashPayWallet`: - -```rust -/// Register payment addresses for all established contacts. -/// Derives up to highest_receive_index + GAP_LIMIT addresses per contact. -/// Returns new addresses that should be added to SPV bloom filter. -pub async fn register_contact_payment_addresses( - &self, -) -> Result, PlatformWalletError> - -/// Process an incoming payment detected at a contact address. -/// Returns contact info if the address matches a known contact relationship. -pub fn match_payment_to_contact( - &self, - address: &Address, -) -> Option<(Identifier, Identifier, u32)> // (owner_id, contact_id, address_index) -``` - -Gap limit = 20 per contact. When payment arrives at index N, extend registration to N + 20. - -**6. Account label encryption (optional)** - -Move from evo-tool to `DashPayWallet`: -```rust -pub fn encrypt_account_label(label: &str, shared_key: &[u8; 32]) -> Vec -pub fn decrypt_account_label(encrypted: &[u8], shared_key: &[u8; 32]) -> Result -``` - -**Files to create/modify:** -- `src/wallet/dashpay/dip14.rs` — new: ckd_priv_256, ckd_pub_256 -- `src/wallet/dashpay/contacts.rs` — new: derive_contact_xpub, account_reference, payment addresses -- `src/wallet/dashpay/wallet.rs` — add register_contact_payment_addresses(), match_payment_to_contact() -- `src/wallet/dashpay/payments.rs` — new: contact payment tracking, gap limit management - -**Done when**: All DashPay crypto operations (DIP-14 derivation, ECDH, xpub encryption, -account reference, payment address derivation) are in platform-wallet. An app can build -full DashPay contact + payment flows without reimplementing protocol-level crypto. - ---- - -### PR-13: Evo-tool integration Phase 3 - -### PR-13 Status: Complete - -**What was delivered:** - -Phase 3 identity migration (using enriched library from PR-10/11/12): -- `register_identity.rs` → `identity_wallet.register_identity_with_signer()` (with platform-wallet fallback) -- `top_up_identity.rs` → `identity_wallet.top_up_identity_with_signer()` (with platform-wallet fallback) -- `discover_identities.rs` → `identity_wallet.sync()` with QualifiedIdentity adapter (legacy fallback) - -Remaining token tasks (4): -- `destroy_frozen_funds.rs` → `token_wallet.destroy_frozen_funds_with_signer()` -- `pause_tokens.rs` → `token_wallet.pause_with_signer()` -- `resume_tokens.rs` → `token_wallet.resume_with_signer()` -- `update_token_config.rs` → `token_wallet.update_config_with_signer()` - -Platform-wallet additions: -- `register_identity_with_signer()` — register with external Identity + Signer -- `top_up_identity_with_signer()` — top up with external Identity + proof -- `identity_manager()` — read access for inspecting managed identities after sync -- 4 new TokenWallet methods + `_with_signer` variants (destroy, pause, resume, update_config) - -**Migration tally (all phases):** - -| Domain | Migrated | Total | Remaining | Details | -|--------|----------|-------|-----------|---------| -| **Tokens** | 13 | 13 | — | All complete | -| **Identity** | 11 | 13 | 2 | See details below | -| **DashPay** | 2 | 9 | 7 | See details below | -| **Core** | 1 | 7 | 6 | See details below | -| **Total** | **27** | **42** | **15** | | - -**Tokens — 13/13 migrated:** -- ✅ `transfer_tokens.rs` → `token_wallet.transfer_with_signer()` -- ✅ `mint_tokens.rs` → `token_wallet.mint_with_signer()` -- ✅ `burn_tokens.rs` → `token_wallet.burn_with_signer()` -- ✅ `freeze_tokens.rs` → `token_wallet.freeze_with_signer()` -- ✅ `unfreeze_tokens.rs` → `token_wallet.unfreeze_with_signer()` -- ✅ `claim_tokens.rs` → `token_wallet.claim_with_signer()` -- ✅ `purchase_tokens.rs` → `token_wallet.purchase_with_signer()` -- ✅ `set_token_price.rs` → `token_wallet.set_price_with_signer()` -- ✅ `destroy_frozen_funds.rs` → `token_wallet.destroy_frozen_funds_with_signer()` -- ✅ `pause_tokens.rs` → `token_wallet.pause_with_signer()` -- ✅ `resume_tokens.rs` → `token_wallet.resume_with_signer()` -- ✅ `update_token_config.rs` → `token_wallet.update_config_with_signer()` -- ✅ `query_my_token_balances.rs` → `token_wallet.watch()` + `.sync()` + `.balance()` - -**Identity — 11/13 migrated:** -- ✅ `withdraw_from_identity.rs` → `identity_wallet.withdraw_credits_with_signer()` -- ✅ `transfer.rs` → `identity_wallet.transfer_credits_with_signer()` -- ✅ `add_key_to_identity.rs` → `identity_wallet.update_identity_with_signer()` -- ✅ `register_dpns_name.rs` → `identity_wallet.register_name_with_signer()` -- ✅ `register_identity.rs` → `identity_wallet.register_identity_with_signer()` (with fallback) -- ✅ `top_up_identity.rs` → `identity_wallet.top_up_identity_with_signer()` (with fallback) -- ✅ `discover_identities.rs` → `identity_wallet.sync()` (with legacy fallback) -- ✅ `refresh_identity.rs` → `identity_wallet.refresh_identity_with_signer()` (with fallback) -- ✅ `load_identity_from_wallet.rs` → `identity_wallet.load_identity_by_index()` (with legacy fallback) -- ✅ `load_identity_by_dpns_name.rs` → `sdk.resolve_dpns_name()` + platform wallet watched identity -- ✅ `refresh_loaded_identities_dpns_names.rs` → `sdk.get_dpns_usernames_by_identity()` -- ❌ `load_identity.rs` — UI-driven manual import (user pastes ID, masternode types, manual key input). Genuinely app-level. -- ❌ Support files (`encryption.rs`, `dip14_derivation.rs`, `hd_derivation.rs`) — crypto utilities still used by non-migrated DashPay tasks - -**DashPay — 2/9 migrated:** -- ✅ `contact_requests.rs` (send) → `platform_wallet.dashpay().send_contact_request()` -- ✅ `contact_requests.rs` (accept) → `platform_wallet.dashpay().send_contact_request()` (reciprocal) -- ❌ `contact_requests.rs` (load) — UI expects raw `Vec<(Identifier, Document)>`, platform-wallet returns `Vec` (different shape) -- ❌ `contact_requests.rs` (reject) — platform-wallet only does local removal, evo-tool persists rejection to Platform via contactInfo document -- ❌ `contacts.rs` — UI-specific contact list management -- ❌ `incoming_payments.rs` — SPV payment address registration, gap limit tracking -- ❌ `auto_accept_handler.rs` — evo-tool orchestration of auto-accept batching -- ❌ Support files (`encryption.rs`, `dip14_derivation.rs`, `hd_derivation.rs`, `validation.rs`) — still used by non-migrated tasks - -**Core — 1/7 migrated:** -- ✅ `create_asset_lock.rs` — partial (uses `CoreWallet.build_asset_lock_transaction()` with fallback) -- ❌ `refresh_wallet_info.rs` — UTXO refresh from RPC/SPV, tightly coupled to evo-tool's SpvManager -- ❌ `refresh_single_key_wallet_info.rs` — single-key wallet refresh -- ❌ `send_single_key_wallet_payment.rs` — Core transaction from single-key wallet -- ❌ `recover_asset_locks.rs` — unused asset lock recovery from DB -- ❌ `start_dash_qt.rs` — subprocess launcher (not platform-related) -- ❌ `mod.rs` core task dispatch — orchestration logic - ---- - -### PR-14: Protocol completeness — DashPay + Identity - -**Goal**: Complete protocol-level support so any app can build full DashPay contact + -payment flows AND full identity management without reimplementing protocol logic. - -**DashPayWallet additions:** -- `reject_contact_request()` — contactInfo document with display_hidden=true -- `generate_auto_accept_proof()` / `verify_auto_accept_proof()` — DIP-15 QR auto-accept -- `validate_contact_request()` — pre-send key/height/reference validation -- `encrypt_account_label()` / `decrypt_account_label()` — CBC-AES-256 with ECDH key -- `register_contact_payment_addresses()` — bulk address derivation + gap limit tracking -- `match_payment_to_contact()` — address → (owner, contact, index) lookup -- `sent_contact_requests()` — query outgoing requests from Platform -- `send_contact_request_with_signer()` / `accept_contact_request_with_signer()` — external signer variants - -**IdentityWallet additions:** - -```rust -/// Load a single identity by wallet index (not gap scan — targeted lookup). -/// Derives auth key at identity_index, queries Platform, adds to manager. -pub async fn load_identity_by_index( - &self, - identity_index: u32, -) -> Result, PlatformWalletError> -``` - -```rust -/// Refresh a known identity's state from Platform (balance, keys, revision). -/// Unlike sync() which discovers new identities, this updates an existing one. -pub async fn refresh_identity( - &self, - identity_id: &Identifier, -) -> Result -``` - -```rust -/// Refresh DPNS names for all managed identities. -/// Queries Platform for current names, updates ManagedIdentity.dpns_names. -pub async fn refresh_dpns_names(&self) -> Result<(), PlatformWalletError> -``` - -```rust -/// Load an identity by DPNS name resolution + fetch. -/// Combines resolve_name() + fetch identity + add to manager. -pub async fn load_identity_by_dpns_name( - &self, - name: &str, -) -> Result, PlatformWalletError> -``` - -**Files to create/modify:** -- `src/wallet/dashpay/auto_accept.rs` — new: proof generation + verification -- `src/wallet/dashpay/validation.rs` — new: pre-send validation -- `src/wallet/dashpay/payments.rs` — new: payment address registration + matching -- `src/wallet/dashpay/wallet.rs` — reject, sent_requests, label encryption, _with_signer methods -- `src/wallet/identity/wallet.rs` — load_identity_by_index, refresh_identity, refresh_dpns_names, load_identity_by_dpns_name - -**Evo-tool migration** (same PR or follow-up): -- `load_identity_from_wallet.rs` → `wallet.identity().load_identity_by_index()` -- `refresh_identity.rs` → `wallet.identity().refresh_identity()` -- `refresh_loaded_identities_dpns_names.rs` → `wallet.identity().refresh_dpns_names()` -- `load_identity_by_dpns_name.rs` → `wallet.identity().load_identity_by_dpns_name()` -- DashPay tasks → `wallet.dashpay().*_with_signer()` methods - -**Done when**: Full DashPay + identity protocol coverage. Only `load_identity.rs` (manual import -with masternode types) remains evo-tool-specific. - ---- - -### PR-15: Shielded pool (feature-gated `shielded`) - -**Goal**: Implement `ShieldedWallet` — a standalone, storage-generic shielded -transaction component using Orchard/Halo2 ZK proofs. All code behind `#[cfg(feature = "shielded")]`. - -**Key design decision**: Storage is abstracted via the `ShieldedStore` trait. The library provides -`InMemoryShieldedStore` for tests; consumers (evo-tool) bring their own persistence (SQLite). -This keeps the library dependency-light and testable without database infrastructure. - -**Architectural note**: `ShieldedWallet` is **not** a field on `PlatformWallet`. It is a standalone -component that consumers create separately with their own `ShieldedStore` implementation. This -avoids infecting `PlatformWallet` with the `S: ShieldedStore` generic parameter. `ShieldedWallet` -shares the `Sdk` with `PlatformWallet` but manages its own state. - -**Library** (`rs-platform-wallet`): - -New `wallet/shielded/` module behind `#[cfg(feature = "shielded")]`: - -- `mod.rs` — `ShieldedWallet` struct (`Sdk`, `OrchardKeySet`, `Arc>`, `Network`), - constructors (`new`, `from_seed`), re-exports -- `keys.rs` — `OrchardKeySet` (ZIP-32 key hierarchy: `SpendingKey`, `FullViewingKey`, - `SpendAuthorizingKey`, `IncomingViewingKey`, `OutgoingViewingKey`, `PaymentAddress`), - derivation from seed, address generation, `PreparedIncomingViewingKey` for trial decryption -- `store.rs` — `ShieldedStore` trait (note CRUD, commitment tree ops, sync state checkpoints), - `ShieldedNote` struct, `InMemoryShieldedStore` (Vec + BTreeMap + in-memory tree) -- `sync.rs` — `sync_notes()` (trial decryption of encrypted notes, commitment tree append), - `check_nullifiers()` (privacy-preserving trunk/branch scan), `sync()` (full orchestration), - result types (`SyncNotesResult`, `ShieldedSyncSummary`) -- `operations.rs` — 5 transition types, each using DPP `build_*_transition()` builders and - broadcasting via SDK traits (`ShieldFunds`, `UnshieldFunds`, `TransferShielded`, - `WithdrawShielded`, `ShieldFromAssetLock`): - - `shield()` — platform addresses to shielded pool (needs `Signer`) - - `shield_from_asset_lock()` — Core L1 to shielded pool via asset lock proof - - `unshield()` — shielded pool to platform address - - `transfer()` — shielded pool to shielded pool (private, to `PaymentAddress`) - - `withdraw()` — shielded pool to Core L1 address -- `prover.rs` — `CachedOrchardProver` (`OnceLock`, `warm_up()` for background - init, implements `OrchardProver` trait), shared across all `ShieldedWallet` instances -- `note_selection.rs` — `select_spendable_notes()` (greedy: sort by value descending, - accumulate until >= amount + fee, returns notes with Merkle witness paths) - -**Files**: -- `packages/rs-platform-wallet/src/wallet/shielded/mod.rs` -- `packages/rs-platform-wallet/src/wallet/shielded/keys.rs` -- `packages/rs-platform-wallet/src/wallet/shielded/store.rs` -- `packages/rs-platform-wallet/src/wallet/shielded/sync.rs` -- `packages/rs-platform-wallet/src/wallet/shielded/operations.rs` -- `packages/rs-platform-wallet/src/wallet/shielded/prover.rs` -- `packages/rs-platform-wallet/src/wallet/shielded/note_selection.rs` - -**Done when**: -- `ShieldedStore` trait compiles with `InMemoryShieldedStore` passing unit tests -- `OrchardKeySet::from_seed()` derives correct keys (verified against reference vectors) -- `sync_notes()` trial-decrypts test notes and populates store -- `check_nullifiers()` detects spent notes and marks them -- All 5 operations build valid Orchard bundles via DPP builders and broadcast via SDK traits -- `CachedOrchardProver` initializes and generates valid proofs -- Note selection covers amount + fee or returns insufficient-funds error -- Full round-trip test: shield, sync, check balance, transfer, unshield - ---- - -### PR-16: AssetLockFinalityEvent - -**Scope change**: Originally planned to replace evo-tool's SpvManager with -PlatformWalletManager. After research, SpvManager has ~1,500 lines of app-specific -orchestration (ConnectionStatus push updates, 300ms debounced reconciliation, wallet-to-DB -sync, peer count tracking, quorum lookups, RPC/SPV mode switching) that is NOT protocol-level. - -**Decision**: Keep evo-tool's SpvManager. It coexists with platform-wallet — both share -the same `ManagedWalletInfo` via `Arc>`. Only add the protocol-level finality -tracking to platform-wallet. - -**What to implement:** - -```rust -impl SpvRuntime { - /// Register a transaction to wait for finality (InstantLock or ChainLock). - /// Call BEFORE broadcasting the transaction. - pub async fn register_for_finality(&self, txid: Txid); - - /// Wait for a finality proof for a previously registered transaction. - /// Returns the proof once an InstantLock or ChainLock is received. - /// Timeout: configurable (default 5 minutes). - pub async fn wait_for_finality( - &self, - txid: Txid, - timeout: Duration, - ) -> Result; -} -``` - -Internal state: -- `finality_waiters: Mutex>>` on SpvRuntime -- `SpvEventForwarder` forwards `InstantLockReceived` / `ChainLockReceived` events -- Add a listener that updates `finality_waiters` when matching events arrive -- `wait_for_finality()` polls the map with sleep intervals (like evo-tool's pattern) - -Critical invariant: call `register_for_finality()` BEFORE broadcasting to prevent -race where proof arrives before registration. - -**Files to modify:** -- `src/spv/runtime.rs` — finality_waiters field + register/wait methods -- `src/spv/event_forwarder.rs` — forward finality events to waiter map -- `src/error.rs` — add FinalityTimeout variant - -**Done when**: `wait_for_finality(txid)` returns an AssetLockProof when IS/CL event -arrives via SPV. CoreWallet's register_identity/top_up can optionally use this instead -of DAPI polling. - ---- - -### PR-17: Comprehensive test suite - -**Infrastructure**: -- `tests/common/mod.rs` — shared helpers: `create_test_wallet()`, `create_funded_wallet()`, `inject_utxos()` -- `dash-sdk` with `mocks` feature in `[dev-dependencies]` -- Known test mnemonic (`"abandon abandon..."`) -- E2E feature flag `#[cfg(feature = "e2e-tests")]` - -**Unit tests** (~70 ported from evo-tool + new): -- Balance calculation (10 tests), UTXO selection (8), platform address info (4) -- Derivation paths (13), address derivation (6), seed lifecycle (2) -- Asset lock fee calc (9), wallet transactions (3) -- DIP-14 derivation (5), seed encryption (2) -- IdentityManager, ManagedIdentity, ContactRequest, EstablishedContact (existing 35 + new) - -**Integration tests** (mock SDK): -- Wallet construction (10+ tests), manager CRUD (10+) -- IdentitySigner signing (8+), PlatformAddressSigner (5+) -- CoreWallet async queries (12+), asset lock building (8+) -- Identity registration/sync/topup/withdraw flow (mocked Platform) -- DashPay contact request flow (mocked) -- Platform address sync/transfer/withdraw (mocked) -- Token watch/sync/transfer/mint/burn (mocked) - -**E2E tests** (live network, feature-gated): -- SPV sync + wallet balance (BackendTestContext pattern from evo-tool PR #778) -- Send/receive funds round-trip -- Identity registration + discovery -- Contact request send + accept between two wallets -- Platform address operations -- Token operations - ---- - -### PR-18: Replace evo-tool Wallet model with CoreWallet (COMPLETED) - -**Completed work:** - -Platform-wallet: -- `Arc` — cloned PlatformWallet handles share balance atomics -- `blocking_wallet_info()` — sync read access for egui UI code -- CoreWallet convenience wrappers removed (done in earlier PRs) - -Evo-tool: -- Embedded `Option` inside evo-tool `Wallet` struct — set on unlock, cleared on lock -- All UI balance reads migrated to lock-free `WalletBalance` via `wallet.platform_wallet` -- All UI UTXO/address reads migrated to `blocking_wallet_info()` + `CoreAddressInfo` -- Removed `platform_wallets` bridge map from AppContext — all lookups go through `wallet.platform_wallet` -- Removed 6 duplicate fields from Wallet: `confirmed_balance`, `unconfirmed_balance`, `total_balance`, `spv_balance_known`, `address_balances`, `address_total_received` -- Balance methods (`confirmed_balance_duffs()`, `total_balance_duffs()`, etc.) delegate to PlatformWallet -- New `address_balance()` method reads per-address balance from CoreAddressInfo -- `funding_common` reads UTXOs from PlatformWallet's `get_spendable_utxos()` - -Additional completed work (same PR): -- Migrated RPC send payment to `platform_wallet.core().send_transaction()` -- Migrated all asset lock building (create_asset_lock, register_identity, top_up_identity, fund_platform_address, shielded bundle) to `platform_wallet.core().build_asset_lock_transaction()` -- Removed all fallback paths (try PlatformWallet → fall back to old Wallet) -- Removed ~600 lines of dead asset lock building code from asset_lock_transaction.rs -- Removed build_standard_payment_transaction, build_multi_recipient_payment_transaction (~270 lines) -- Removed reload_utxos (~120 lines), utxos_by_address, max_balance -- Made broadcast_and_commit_asset_lock take Option (None for PlatformWallet paths) -- Removed 22 obsolete tests (UTXO selection, balance fallbacks, utxos_by_address) -- Total: ~1,625 lines removed - -**Remaining Wallet fields (PR-19 scope):** -- `utxos` — SPV reconciliation writes, _for_utxo asset lock paths, transaction_processing -- `known_addresses` — address derivation (receive_address, change_address), key lookup, bootstrap -- `watched_addresses` — address metadata, account summaries, UI display -- `transactions` — transaction history display - ---- - -### PR-19: Migrate remaining Wallet fields - -**Goal**: Remove `utxos`, `known_addresses`, `watched_addresses`, `transactions` from evo-tool's Wallet by migrating all remaining callers to PlatformWallet. - -**Completed:** -- `register_contact_account()` on DashPayWallet — creates DashpayReceivingFunds managed accounts in ManagedWalletInfo when contacts are established -- Called automatically from `send_contact_request()` -- key-wallet already has: `ManagedAccountCollection::insert()` for DashpayReceivingFunds, `ManagedCoreAccount::from_account()` for creating managed wrappers with address pools - -#### How DashPay interacts with the core wallet (DIP-14/15) - -When a contact is established (mutual contact requests on Platform): - -1. **Send request** (`DashPayWallet::send_contact_request()`): - - Derives DashPay receiving-account xpub: `m/9'/coin'/15'/0'/(sender_id)/(recipient_id)` using DIP-14 256-bit derivation - - Encrypts xpub with ECDH (recipient's decryption key) - - Submits contactRequest document to Platform - - **Now also**: creates `DashpayReceivingFunds` account in `ManagedWalletInfo` so SPV monitors incoming payment addresses - -2. **Accept request** (`DashPayWallet::accept_contact_request()`): - - Sends reciprocal request (calls `send_contact_request()`) - - Auto-establish logic in ManagedIdentity detects both requests → creates `EstablishedContact` - -3. **Address monitoring** (now automatic via ManagedWalletInfo): - - `ManagedCoreAccount` for `DashpayReceivingFunds` has address pools with gap limit - - SPV adapter iterates all accounts via `monitored_addresses()` → includes contact addresses - - When incoming payment arrives, `check_core_transaction()` matches against address pools - - Gap limit automatically derives more addresses as used addresses are consumed - -4. **Previously (evo-tool manual flow, being removed)**: - - `register_dashpay_addresses_for_identity()` manually derived addresses from seed - - Inserted into `known_addresses` and `watched_addresses` BTreeMaps - - Maintained `dashpay_contact_address_indices` DB table for gap limit tracking - - Required explicit `RegisterDashPayAddresses` backend task trigger - -#### Address types and their account mapping - -| Address type | DIP | Derivation path | key-wallet account | Status | -|---|---|---|---|---| -| BIP44 receive/change | BIP44 | `m/44'/coin'/acct'/0or1/i` | `standard_bip44_accounts` | In ManagedWalletInfo ✓ | -| Identity registration | DIP-9 | `m/9'/coin'/5'/1'/i` | `identity_registration` | In ManagedWalletInfo ✓ | -| Identity top-up | DIP-9 | `m/9'/coin'/5'/2'/i` | `identity_topup` | In ManagedWalletInfo ✓ | -| DashPay receive | DIP-15 | `m/9'/coin'/15'/0'/(self)/(friend)/i` | `dashpay_receival_accounts` | **Now registered** ✓ | -| DashPay send (watch) | DIP-15 | contact xpub + index | `dashpay_external_accounts` | TODO | -| Platform payment | DIP-17 | `m/9'/coin'/17'/acct'/class'/i` | `platform_payment_accounts` | In ManagedWalletInfo ✓ | -| CoinJoin | - | `m/9'/coin'/cointype'/i` | `coinjoin_accounts` | In ManagedWalletInfo ✓ | -| Provider keys | - | various | `provider_*_keys` | In ManagedWalletInfo ✓ | - -#### Remaining migration steps - -**All phases COMPLETE.** 10/10 duplicate fields removed from evo-tool's Wallet struct. - -Summary of completed work: -- [x] DashPay contact accounts registered in both key-wallet Wallet + ManagedWalletInfo -- [x] Address derivation delegated to PlatformWallet (blocking_next_receive/change_address) -- [x] Bootstrap skipped when PlatformWallet available (locked wallets show nothing — privacy) -- [x] All UI/backend reads migrated to CoreAddressInfo / WalletBalance / blocking_wallet_info -- [x] All asset lock building migrated to CoreWallet::build_asset_lock_transaction -- [x] RPC send payment migrated to CoreWallet::send_transaction -- [x] Removed fields: confirmed_balance, unconfirmed_balance, total_balance, spv_balance_known, address_balances, address_total_received, utxos, known_addresses, watched_addresses, transactions -- [x] Removed ~600 lines of asset lock building, ~400 lines of bootstrap, ~270 lines of tx building -- [x] Arc in PlatformWallet, Arc in manager and evo-tool Wallet -- [x] WalletBalance reverted from Arc to plain (shared via Arc) -- [x] Removed platform_wallets bridge map from AppContext - -**Remaining in Wallet struct** (app-level metadata, NOT duplicates): -- `platform_wallet: Option>` — canonical wallet -- `wallet_seed` — encrypted seed for persistence -- `uses_password`, `master_bip44_ecdsa_extended_public_key` — auth -- `unused_asset_locks` — asset lock tracking -- `alias`, `identities`, `is_main` — app metadata -- `platform_address_info` — platform credits (could migrate to PlatformAddressWallet) -- `core_wallet_name` — RPC config - -**Remaining code that still references old patterns** (functional, not dead): -- `_for_utxo` asset lock paths (register_identity, top_up_identity) — need CoreWallet API -- `remove_selected_utxos` in utxos.rs — DB persistence for _for_utxo paths -- `update_address_balance`/`update_address_total_received` — DB persistence -- `platform_addresses`/`platform_receive_address` — reads watched_addresses but from platform_address_info -- DB tables (wallet_addresses, utxos, wallet_transactions) — kept for future serialization PR - -**Total: ~2,700 lines removed from evo-tool.** - ---- - -### PR-20: Complete Identity/Asset Lock Lifecycle - -**Goal**: Platform-wallet provides one-call APIs for identity registration and -top-up. Apps never touch asset locks, finality tracking, or proof construction. - -#### Current problem - -Identity registration is split across repos: -1. **Evo-tool** builds asset lock, broadcasts, tracks finality via SPV, waits for proof -2. **Platform-wallet** has the identity state transition but expects pre-built proof -3. **Platform-wallet SPV runtime** has `register_for_finality()`/`wait_for_finality()` but they're NEVER CALLED -4. **Platform-wallet** has `broadcast_and_wait_for_asset_lock_proof()` that uses DAPI streaming instead of SPV - -This means: -- Every app must reimplement asset lock orchestration (200+ lines) -- SPV finality infrastructure exists but is unused -- DAPI streaming approach is fragile (5min hardcoded timeout) -- `TrackedAssetLock.status` never updates beyond `Broadcast` - -#### Layered design - -**CoreWallet** — owns asset lock TX lifecycle (Core chain concerns): -```rust -/// Asset lock status on the Core chain. -/// Tracked until used, then removed from tracked set. -pub enum AssetLockStatus { - Built, - Broadcast, - InstantSendLocked, - ChainLocked, -} - -/// A tracked asset lock — Core wallet knows about the TX, its status, -/// and how to re-derive the private key. Private keys stay in -/// key-wallet's Wallet, re-derived from funding_type + identity_index. -pub struct TrackedAssetLock { - pub txid: Txid, - pub funding_type: AssetLockFundingType, - pub identity_index: u32, - pub amount: u64, - pub status: AssetLockStatus, -} - -impl CoreWallet { - /// Build asset lock TX (existing). - pub async fn build_asset_lock_transaction(...) -> Result<...> - - /// Build + broadcast + wait for SPV proof. Returns when IS-lock or - /// ChainLock is received. Tracks lifecycle internally. - pub async fn create_funded_asset_lock_proof( - &self, - amount_duffs: u64, - funding_type: AssetLockFundingType, - identity_index: u32, - spv_runtime: Option<&SpvRuntime>, - ) -> Result<(AssetLockProof, PrivateKey, Txid), PlatformWalletError> - - /// List unused (funded but not consumed) asset locks. - pub fn unused_asset_locks(&self) -> Vec<&TrackedAssetLock> - - /// Scan Core chain for asset lock TXs not yet used. - pub async fn recover_unused_asset_locks(&self) -> Vec - - /// Remove a lock from tracking (called after successful use). - pub fn remove_asset_lock(&self, txid: &Txid) -} -``` - -**IdentityWallet** — orchestrates identity operations using CoreWallet: -```rust -/// How to fund an identity operation. -pub enum IdentityFunding { - /// Build asset lock from wallet UTXOs (most common). - FromWalletBalance { amount_duffs: u64 }, - /// Use credits from a Platform address (DIP-17). - FromPlatformAddress { address: PlatformAddress, amount_credits: Credits, nonce: u32 }, - /// Use an existing unused asset lock (recovery from previous attempt). - FromExistingAssetLock { txid: Txid }, - /// Use a specific UTXO (QR-funded flow). - FromUtxo { outpoint: OutPoint, tx_out: TxOut, address: Address }, -} - -impl IdentityWallet { - /// Register identity — complete flow, one call. - pub async fn register_identity( - &self, - funding: IdentityFunding, - keys: IdentityKeys, - identity_index: u32, - ) -> Result - - /// Top up identity — complete flow, one call. - pub async fn top_up_identity( - &self, - identity_id: Identifier, - funding: IdentityFunding, - identity_index: u32, - ) -> Result -} -``` - -Note: `FromExistingAssetLock` just takes `txid` — CoreWallet already -tracks the lock, has the proof, and can re-derive the private key. -No key material in IdentityFunding. - -#### Key design decisions - -**1. CoreWallet owns asset lock lifecycle**: Asset locks are Core chain -transactions used by multiple Platform features (identities, platform -addresses, shielded). CoreWallet tracks their status (Built → Broadcast -→ IS-locked → ChainLocked). When consumed by any Platform operation, -the lock is removed from tracking. - -**2. Private keys stay in key-wallet**: `TrackedAssetLock` stores -`funding_type` + `identity_index` — enough to re-derive the private key -from the wallet seed when needed. No key material stored in tracking state. - -**3. Transaction status from key-wallet**: Core TX confirmation status -(unconfirmed, IS-locked, confirmed, chainlocked) is already tracked by -key-wallet's `TransactionRecord.context`. `AssetLockStatus` mirrors this -for asset-lock-specific tracking until the lock is consumed. - -**4. Remove when used, not track usage**: Once an asset lock is consumed -(identity registered, address funded, etc.), CoreWallet removes it from -the tracked set. No `UsedForRegistration` state — that's the consumer's -concern, not the Core wallet's. - -**5. SPV finality (not DAPI streaming)**: Proof detection uses SPV's -`wait_for_finality()` which listens for InstantSend and ChainLock events -natively. No DAPI subscription streams. - -**6. Recovery**: `recover_unused_asset_locks()` scans for funded-but-unused -locks on Core chain and adds them to tracking with appropriate status. - -#### Implementation steps - -**Steps 1, 4, 5 — DONE:** -- ✅ `TrackedAssetLock` + `AssetLockStatus` types (no private keys, remove when consumed) -- ✅ `AssetLockManager` extracted, shared across sub-wallets via `Arc` -- ✅ `IdentityWallet` uses `self.asset_locks` directly (no CoreWallet parameter) -- ✅ `funded_register_identity` / `funded_top_up_identity` call `remove_asset_lock` after use -- ✅ Evo-tool callers updated to `platform_wallet.asset_locks()` - -**Step 2 — AssetLockManager subscribes to SPV events for finality:** -- Add `event_tx: broadcast::Sender` to `AssetLockManager` -- Pass it from `PlatformWallet::from_wallet_and_info()` (same channel SPV adapter uses) -- Replace `wait_for_proof_via_dapi()` with event-driven SPV waiting: - ```rust - async fn wait_for_proof(&self, txid: &Txid, timeout: Duration) -> Result { - let mut rx = self.event_tx.subscribe(); - let deadline = Instant::now() + timeout; - loop { - tokio::select! { - event = rx.recv() => { - match event { - Ok(PlatformWalletEvent::Spv(SpvEvent::Sync( - SyncEvent::InstantLockReceived { instant_lock, .. } - ))) if instant_lock.txid == *txid => { - // Build InstantAssetLockProof from instant_lock - return Ok(proof); - } - Ok(PlatformWalletEvent::Spv(SpvEvent::Sync( - SyncEvent::ChainLockReceived { .. } - ))) => { - // Check if our tx is in a chain-locked block - // Build ChainAssetLockProof - } - _ => continue, - } - } - _ = tokio::time::sleep_until(deadline) => { - return Err(PlatformWalletError::FinalityTimeout(*txid)); - } - } - } - } - ``` -- Update `create_funded_asset_lock_proof()` to use this instead of DAPI streaming -- Delete `wait_for_proof_via_dapi()` and `SpvRuntime::wait_for_finality()` (replaced) - -**Step 3 — Asset lock recovery in AssetLockManager:** -- `recover_unused_asset_locks()` scans Core chain for funded-but-unused locks -- Move logic from evo-tool's `recover_asset_locks.rs` -- Recovered locks enter tracking at InstantSendLocked or ChainLocked status - -**Step 6 — Simplify evo-tool:** -- Remove `transactions_waiting_for_finality` from AppContext -- Remove `spv_setup_finality_listener()` / `handle_spv_finality_event()` / `received_asset_lock_finality()` -- Remove `wait_for_asset_lock_proof()` polling -- Remove `broadcast_and_commit_asset_lock()` -- Remove `Wallet.unused_asset_locks` field (tracked by AssetLockManager) -- Remove `recover_asset_locks.rs` (moved to AssetLockManager) -- Simplify `create_asset_lock.rs` to call `asset_locks().create_funded_asset_lock_proof()` - ---- - -### PR-21: Remove Remaining Duplication - -**Goal**: Clean up remaining duplicated code identified in the duplication audit. - -- Replace CoreWallet's `send_transaction()` manual UTXO selection with key-wallet's `TransactionBuilder` -- Remove dead `derive_account_xpub()` (already simplified to use AccountType) -- Remove blocking address derivation path construction duplication -- Clean up any remaining evo-tool code that duplicates platform-wallet - ---- - -### PR-23: Merge Wallet + ManagedWalletInfo (dashcore) - -Merge `Wallet` and `ManagedWalletInfo` in `key-wallet` — both are mutable and always used -together. Single `Arc>` containing all state. - -**Why**: The original split assumed `Wallet` was immutable (key store) while `ManagedWalletInfo` -was mutable (UTXO state). In practice, `Wallet` is also mutable — accounts are added during -DashPay contact establishment and sync. Having them behind separate `RwLock`s creates: -1. Lock ordering risk (must always acquire wallet before wallet_info) -2. Read starvation during block processing (SPV holds write locks on both for entire block) -3. Non-atomic updates when operations touch both structs (crash = inconsistent state) - -**Investigation needed**: read starvation mitigation (per-tx lock release vs snapshot/MVCC vs -accept latency), atomic multi-struct update strategy (merge vs journaling vs eventual consistency). - ---- - -### PR-22: ChangeSet-based Persistence (inspired by BDK) - -**Goal**: Atomic state updates + persistence via a layered ChangeSet pattern. -Every mutation produces a delta that is applied atomically to in-memory state -and persisted atomically to storage. Two layers: key-wallet owns core wallet -deltas, platform-wallet composes them with platform-specific deltas. - -#### Architecture: Two-Layer ChangeSets - -``` -key-wallet (dashcore) platform-wallet -┌─────────────────────┐ ┌──────────────────────────────┐ -│ WalletChangeSet │ │ PlatformWalletChangeSet │ -│ ├─ utxos │ composed into │ ├─ wallet: WalletChangeSet │ -│ ├─ transactions │ ───────────────>│ ├─ identities │ -│ ├─ accounts │ │ ├─ contacts │ -│ └─ balance │ │ ├─ platform_addresses │ -└─────────────────────┘ │ ├─ shielded │ - │ └─ asset_locks │ - └──────────────────────────────┘ -``` - -**Flow for every operation:** -``` -1. Operation executes (e.g., process_block, send_contact_request) -2. key-wallet mutation returns WalletChangeSet (UTXO/tx/account deltas) -3. platform-wallet wraps it + adds platform deltas → PlatformWalletChangeSet -4. apply() to in-memory state (single write lock, all or nothing) -5. stage() into accumulated changeset -6. persist() to storage (single DB transaction, all or nothing) -``` - -**Key insight**: Each layer owns its own deltas. key-wallet knows exactly what -UTXOs/transactions/addresses changed — it produces `WalletChangeSet` natively. -Platform-wallet composes it with identity/contact/platform state and persists -the whole `PlatformWalletChangeSet` atomically. - -#### Layer 1: key-wallet `WalletChangeSet` (dashcore crate) - -Lives in `rust-dashcore/key-wallet/src/changeset/`. Captures ALL core -wallet mutations from a single operation: - -```rust -// key-wallet/src/changeset/changeset.rs - -/// Delta of core wallet state from a single operation. -pub struct WalletChangeSet { - /// Chain sync state (new block height + hash). - pub chain: Option, - /// UTXO changes (added from received outputs, spent from consumed inputs). - pub utxos: Option, - /// Transaction changes (new transactions, confirmation/IS-lock status updates). - pub transactions: Option, - /// Account changes (new accounts, address pool expansion, used address marking). - pub accounts: Option, - /// Aggregate balance change (recomputed from UTXO delta). - pub balance: Option, -} - -pub struct ChainChangeSet { - pub height: Option, - pub block_hash: Option, -} - -pub struct UtxoChangeSet { - /// UTXOs created by received transaction outputs. - pub added: BTreeMap, - /// UTXOs consumed by spent transaction inputs. - pub spent: BTreeSet, - /// UTXOs whose InstantSend lock status changed. - pub instant_locked: BTreeSet, -} - -pub struct TransactionChangeSet { - /// New or updated transaction records. - pub records: BTreeMap, -} - -pub struct AccountChangeSet { - /// New accounts added (DashPay contacts, new identity accounts). - pub new_accounts: Vec, - /// Address pool indices advanced (account key → new last_revealed index). - pub last_revealed: BTreeMap, - /// Addresses marked as used. - pub addresses_used: Vec<(AccountKey, Address)>, -} - -pub struct BalanceChangeSet { - pub spendable: i64, // delta, not absolute - pub unconfirmed: i64, - pub immature: i64, - pub locked: i64, -} -``` - -**Produced by**: `check_core_transaction()`, `record_transaction()`, -`confirm_transaction()`, `mark_utxos_instant_send()`, `maintain_gap_limit()`. -Each mutation method returns a `WalletChangeSet` instead of (or alongside) -mutating in place. - -#### Layer 2: platform-wallet `PlatformWalletChangeSet` - -Lives in `rs-platform-wallet/src/persistence/`. Composes key-wallet's -changeset with platform-specific deltas: - -```rust -// platform-wallet/src/persistence/changeset.rs - -/// Full delta of platform wallet state from a single operation. -pub struct PlatformWalletChangeSet { - /// Core wallet changes (UTXOs, transactions, accounts, balance). - /// Produced by key-wallet operations. - pub wallet: Option, - /// Identity changes (registered, updated, key changes, DPNS names). - pub identities: Option, - /// DashPay contact changes (requests sent/received, contacts established). - pub contacts: Option, - /// Platform address changes (DIP-17 balance/nonce from Platform proofs). - pub platform_addresses: Option, - /// Shielded state changes (commitment tree, nullifiers). - pub shielded: Option, - /// Asset lock lifecycle changes (created, broadcast, confirmed, used). - pub asset_locks: Option, -} -``` -``` - -#### The Merge Trait - -```rust -/// Combine two changesets. Used to batch multiple operations before persisting. -pub trait Merge: Default { - fn merge(&mut self, other: Self); - fn is_empty(&self) -> bool; -} -``` - -Merge semantics per sub-changeset: -- **UTXOs**: union of added, union of spent (idempotent — adding same UTXO twice is no-op) -- **Transactions**: insert or update (later status wins: chainlocked > confirmed > IS-locked > unconfirmed) -- **Identities**: monotonic revision (keep higher), append new keys -- **Contacts**: state machine ordering (pending < accepted < blocked) -- **Chain**: keep higher block height, insert new headers -- **Accounts**: append new addresses to pools, advance gap limit indices -- **Platform addresses**: keep higher nonce, update balance (last write wins from Platform proofs) - -#### The Persistence Trait - -```rust -/// Storage backend abstraction. Implementors choose their own storage -/// (SQLite, file, memory, remote). The trait guarantees atomic persistence. -pub trait WalletPersistence { - type Error: std::error::Error; - - /// Load the aggregated state from storage. - /// Returns a single ChangeSet representing the full stored state - /// (equivalent to merging all previously persisted changesets). - fn initialize(&mut self) -> Result; - - /// Persist a delta atomically. Either all sub-changesets are stored - /// or none are. Implementations MUST guarantee atomicity (e.g., - /// SQLite transaction, atomic file write). - fn persist(&mut self, changeset: &WalletChangeSet) -> Result<(), Self::Error>; -} -``` - -#### How Operations Produce ChangeSets - -Every mutation on PlatformWallet returns a `WalletChangeSet`: - -```rust -impl PlatformWallet { - /// Process a new block from SPV. - /// Computes changes (read-only), then applies atomically. - pub fn process_block(&self, block: &Block, height: u32) -> WalletChangeSet { - let mut changeset = WalletChangeSet::default(); - - // 1. Update chain state - changeset.chain = Some(ChainChangeSet { height, block_hash: block.header.hash() }); - - // 2. Check each transaction against all accounts - for tx in &block.txdata { - let tx_changes = self.check_transaction(tx, height); - changeset.merge(tx_changes); - } - - // 3. Return delta — caller applies + persists - changeset - } - - /// Send a contact request (DashPay). - /// Returns changes to identities + contacts + accounts. - pub async fn send_contact_request(&self, ...) -> Result { - let mut changeset = WalletChangeSet::default(); - - // 1. Create contact request document on Platform - let request = self.dashpay().submit_request(...).await?; - - // 2. Record sent request - changeset.contacts = Some(ContactChangeSet::request_sent(our_id, their_id, request)); - - // 3. Register DashPay receiving account - let account_changes = self.register_contact_account(our_id, their_id)?; - changeset.accounts = Some(account_changes); - - Ok(changeset) - } -} -``` - -#### The Staged ChangeSet Pattern - -PlatformWallet accumulates changesets in a `stage` field until the caller -explicitly persists: - -```rust -pub struct PlatformWallet { - // ... existing fields ... - - /// Accumulated changesets not yet persisted. - stage: RwLock, -} - -impl PlatformWallet { - /// Apply a changeset to in-memory state and stage for persistence. - pub fn apply_and_stage(&self, changeset: WalletChangeSet) { - // Apply to in-memory structs - self.apply(changeset.clone()); - // Merge into staged changes - self.stage.write().merge(changeset); - } - - /// Persist all staged changes and clear the stage. - pub fn persist(&self, persister: &mut impl WalletPersistence) -> Result<(), Error> { - let staged = self.stage.write().take(); - if let Some(changeset) = staged { - persister.persist(&changeset)?; - } - Ok(()) - } -} -``` - -#### In-Memory Atomicity - -Two approaches (choose one): - -**Option A — Single struct behind one RwLock (PR-21):** -Merge Wallet + ManagedWalletInfo + IdentityManager into one struct. The `apply()` -method takes `&mut self` — only one writer at a time, all changes atomic by Rust's -ownership rules. No lock ordering issues. - -**Option B — Compute-then-apply (current multi-lock architecture):** -The changeset is computed without holding any write locks (read-only analysis). -Then `apply()` acquires all write locks in a fixed order, applies all changes, -releases all locks. If any lock acquisition fails, no changes are applied. - -Option A is simpler and recommended. Option B works as a stepping stone. - -#### Storage Atomicity - -**SQLite implementation:** -```rust -impl WalletPersistence for SqlitePersister { - fn persist(&mut self, changeset: &WalletChangeSet) -> Result<(), Error> { - let tx = self.conn.transaction()?; // BEGIN TRANSACTION - - if let Some(chain) = &changeset.chain { - persist_chain(&tx, chain)?; - } - if let Some(utxos) = &changeset.utxos { - persist_utxos(&tx, utxos)?; - } - if let Some(txs) = &changeset.transactions { - persist_transactions(&tx, txs)?; - } - if let Some(ids) = &changeset.identities { - persist_identities(&tx, ids)?; - } - if let Some(contacts) = &changeset.contacts { - persist_contacts(&tx, contacts)?; - } - // ... all sub-changesets ... - - tx.commit()?; // COMMIT — all or nothing - Ok(()) - } -} -``` - -**File store implementation (for testing/dev):** -Append-only binary log. Each `persist()` appends one serialized changeset. -`initialize()` reads all entries, merges via `Merge` trait. Simple, no SQLite -dependency. - -#### Recovery - -If the app crashes: -- **After apply, before persist**: In-memory state is ahead of storage. On restart, - `initialize()` loads last persisted state. SPV re-syncs from the stored chain height, - re-producing the missing changesets. Platform state is re-fetched. -- **During persist (SQLite)**: Transaction rolls back. Storage is at the previous state. - Same recovery as above. -- **After persist**: Both in sync. No recovery needed. - -The gap between in-memory and storage is always bounded by the time since last `persist()`. -Calling `persist()` after every block or every user action keeps the gap small. - -#### Layered Responsibilities - -``` -key-wallet (dashcore): - - WalletChangeSet types + Merge trait - - compute_*() methods — read-only, return changeset - - apply() — mutate state from changeset - - NO persister, NO stage, NO persistence awareness - -platform-wallet: - - PlatformWalletChangeSet (wraps key-wallet + platform deltas) - - Optional persister field (configurable) - - Calls key-wallet compute_*() → gets WalletChangeSet - - Wraps in PlatformWalletChangeSet → queues on persister - - Persister owns the pending buffer + flush strategy - - apply() delegates to ManagedWalletInfo + IdentityManager -``` - -key-wallet stays pure — compute + apply. If used standalone -(without platform-wallet), no persistence overhead. - -#### Persister Architecture - -The persister lives on PlatformWallet. It owns the pending buffer -and decides when to flush. The wallet queues and forgets: - -```rust -pub struct PlatformWallet { - // ... wallet fields ... - persister: Option>>, -} - -impl PlatformWallet { - // Queue changeset — persister decides when to flush - fn queue_persist(&self, changeset: PlatformWalletChangeSet) { - if let Some(persister) = &self.persister { - persister.lock().queue(changeset); - } - // No persister = no-op, no accumulation, no memory growth - } - - fn set_persister(&mut self, persister: impl PlatformWalletPersistence) { - self.persister = Some(Arc::new(Mutex::new(persister))); - } -} -``` - -The persister owns flush strategy: -```rust -pub trait PlatformWalletPersistence { - type Error: std::error::Error; - - /// Queue a changeset. Persister merges into pending buffer. - /// May flush immediately or defer based on strategy. - fn queue(&mut self, changeset: PlatformWalletChangeSet); - - /// Force flush all pending changes to storage. - fn flush(&mut self) -> Result<(), Self::Error>; - - /// Load all persisted state as one changeset (for startup). - fn initialize(&mut self) -> Result; -} - -pub struct SqliteWalletPersister { - db: Arc, - seed_hash: [u8; 32], - network: String, - pending: PlatformWalletChangeSet, // accumulates here - strategy: FlushStrategy, -} - -pub enum FlushStrategy { - /// Flush after every queue() call - Immediate, - /// Flush every N queued changesets - EveryN(usize), - /// Never auto-flush — caller must call flush() explicitly - Manual, -} - -impl PlatformWalletPersistence for SqliteWalletPersister { - fn queue(&mut self, changeset: PlatformWalletChangeSet) { - self.pending.merge(changeset); - match self.strategy { - FlushStrategy::Immediate => { let _ = self.flush(); } - FlushStrategy::EveryN(n) => { self.count += 1; if self.count >= n { let _ = self.flush(); } } - FlushStrategy::Manual => {} // caller decides - } - } - - fn flush(&mut self) -> Result<(), Self::Error> { - if let Some(changeset) = self.pending.take() { - // Single SQLite transaction — all or nothing - let tx = self.conn.transaction()?; - self.persist_changeset(&tx, &changeset)?; - tx.commit()?; - } - Ok(()) - } -} -``` - -**No persister = no memory growth.** The `queue_persist()` call is a -no-op when persister is None. No stage field accumulating forever. - -#### Compute-Then-Apply Architecture - -Every mutation follows the same pattern: - -**Internal** (`compute_*`) — read-only, return changeset, don't mutate: -```rust -// key-wallet: pure computation -fn compute_record_transaction(&self, tx, context) -> WalletChangeSet { ... } -fn compute_mark_address_used(&self, address) -> AccountChangeSet { ... } -fn compute_maintain_gap_limit(&self, xpub) -> AccountChangeSet { ... } -fn compute_update_balance(&self) -> BalanceChangeSet { ... } -``` - -**Public** (existing names) — aggregate + apply, return result. -key-wallet returns changeset to caller for persistence: -```rust -// key-wallet public method -pub fn check_core_transaction(&mut self, tx, ctx) -> (TransactionCheckResult, WalletChangeSet) { - // 1. Compute all changes (read-only) - let changeset = self.compute_transaction_changeset(tx, ctx); - - // 2. Apply atomically (single &mut self) - self.apply(&changeset); - - // 3. Return changeset to caller (for persistence) - (result, changeset) -} - -// platform-wallet SPV adapter wraps + queues -let (result, kw_changeset) = wallet_info.check_core_transaction(tx, ctx); -let platform_cs = PlatformWalletChangeSet { wallet: Some(kw_changeset), .. }; -platform_wallet.queue_persist(platform_cs); // persister handles the rest -``` - -**`apply()` method** on ManagedWalletInfo: -```rust -impl ManagedWalletInfo { - pub fn apply(&mut self, changeset: &WalletChangeSet) { - if let Some(utxos) = &changeset.utxos { - for (outpoint, entry) in &utxos.added { self.add_utxo(outpoint, entry); } - for outpoint in &utxos.spent { self.remove_utxo(outpoint); } - } - if let Some(txs) = &changeset.transactions { - for (txid, record) in &txs.records { self.insert_transaction(txid, record); } - } - if let Some(accounts) = &changeset.accounts { - for (idx, revealed) in &accounts.last_revealed { self.advance_pool(idx, revealed); } - for (idx, addr) in &accounts.addresses_used { self.mark_used(idx, addr); } - } - if let Some(balance) = &changeset.balance { - self.apply_balance_delta(balance); - } - } -} -``` - -Same for PlatformWallet — delegates to sub-stores: -```rust -impl PlatformWallet { - pub fn apply(&self, changeset: &PlatformWalletChangeSet) { - if let Some(wallet_cs) = &changeset.wallet { - self.core().blocking_wallet_info_mut().apply(wallet_cs); - } - if let Some(contacts) = &changeset.contacts { /* IdentityManager */ } - if let Some(identities) = &changeset.identities { /* IdentityManager */ } - if let Some(platform_addrs) = &changeset.platform_addresses { /* metadata */ } - } -} -``` - -`initialize()` uses `apply()` — same code path as runtime: -```rust -let changeset = persister.initialize()?; -platform_wallet.apply(&changeset); -``` - -**Consistency guarantees:** -- Compute phase fails → no state change, consistent -- Apply panics → Rust poisons the lock, no partial state visible -- Between apply and queue_persist → in-memory ahead of storage, re-sync fixes -- No persister → no accumulation, no memory growth - -#### Implementation Steps (compute-then-apply refactor) - -**Step 9 — Add `apply()` to ManagedWalletInfo (dashcore):** - -Implement `apply(&mut self, changeset: &WalletChangeSet)` that applies -each sub-changeset to the wallet state. Used by both runtime mutations -and `initialize()` startup loading — same code path guarantees consistency. - -**Step 10 — Split mutation methods into compute + apply (dashcore):** - -For each mutation method in `ManagedCoreAccount` and `WalletTransactionChecker`, -extract read-only analysis into `compute_*` (returns changeset). The existing -public method becomes: compute + apply + return (result, changeset). - -Methods to split: -- `record_transaction` → `compute_record_transaction` + apply -- `confirm_transaction` → `compute_confirm_transaction` + apply -- `mark_utxos_instant_send` → `compute_instant_send_lock` + apply -- `mark_address_used` → `compute_mark_address_used` + apply -- `maintain_gap_limit` → `compute_gap_limit_expansion` + apply -- `update_balance` → `compute_balance_update` + apply - -`check_core_transaction` aggregates all compute_* results, applies once, -returns (result, changeset) to caller. - -**Step 11 — Persister on PlatformWallet (platform-wallet):** - -- Remove `stage: StdRwLock` field -- Add `persister: Option>>` -- Add `queue_persist()` method — no-op without persister -- Add `set_persister()` method -- Update `PlatformWalletPersistence` trait: `queue()` + `flush()` + `initialize()` -- Add `FlushStrategy` enum (Immediate, EveryN, Manual) -- Add `apply()` on PlatformWallet delegating to ManagedWalletInfo + IdentityManager - -**Step 12 — Update SqliteWalletPersister (evo-tool):** - -- Implement new `PlatformWalletPersistence` trait (queue + flush + initialize) -- Add `pending: PlatformWalletChangeSet` buffer -- Add `strategy: FlushStrategy` field -- Move existing `persist()` logic into `flush()` -- Wire: user actions use `FlushStrategy::Immediate`, - SPV sync uses `FlushStrategy::Manual` with periodic flush timer - -**Step 13 — Wire initialize() through apply() (evo-tool):** - -On startup: -```rust -let changeset = persister.initialize()?; -platform_wallet.apply(&changeset); -``` - -Replace scattered DB loading. Remove `persist_platform_wallet()` helper. -Persister is set on PlatformWallet at creation time. - -#### Migration Strategy - -The implementation touches 3 repos in order: - -1. **dashcore** (key-wallet): Steps 1-2 done, Steps 9-10 next. -2. **platform** (platform-wallet): Steps 3-5 done, Step 11 next. -3. **evo-tool**: Steps 6-8 done, Steps 12-13 next. - -Each step compiles independently. No intermediate fallback code. - -#### What Stays in evo-tool's DB (app-level, NOT wallet state) - -- Encrypted wallet seed (identity, not state) -- Wallet alias, is_main, uses_password (app preferences) -- DashPay contact UI metadata (display name, avatar, last seen) -- Settings, feature flags, proof logs -- Shielded commitment tree (via ShieldedStore trait — already persistent) - -#### What Moves to WalletPersistence - -- UTXOs, transactions, balances (currently in wallet_addresses, utxos, wallet_transactions tables) -- Identity state (registered, keys, DPNS names) -- Contact request state (sent, received, established) -- Platform address balances/nonces -- Asset lock lifecycle state -- Chain sync progress (height, block hashes) - -#### Atomicity Guarantees - -**In-memory**: Each mutation method in key-wallet mutates AND returns a delta. -The mutation is atomic (single `&mut self`). The delta is a faithful record. - -**Cross-struct**: Platform operations (contacts, identities) produce a -`PlatformWalletChangeSet` that bundles ALL related deltas — e.g., -`send_contact_request` produces `ContactChangeSet` + `AccountChangeSet` -(for the new DashPay account) in ONE changeset. Applied and persisted together. - -**Storage**: `PlatformWalletPersistence::persist()` wraps all sub-changeset -writes in a single DB transaction. All or nothing. - -**Recovery**: If crash after in-memory apply but before persist, restart -loads last persisted state via `initialize()`. SPV re-syncs from stored -chain height, reproducing the missing changesets. - -**Done when**: -- Every key-wallet mutation returns a `WalletChangeSet` -- Every platform-wallet operation returns a `PlatformWalletChangeSet` -- No direct DB writes outside the changeset path -- Recovery works correctly after crash at any point -- Audit confirms no atomicity gaps (all cross-struct changes bundled) -- SingleKeyWallet migrated to changeset path (currently uses direct DB writes — separate code path) - -#### Implementation Plan - -**Step 1 — key-wallet `WalletChangeSet` (dashcore repo):** - -Create `rust-dashcore/key-wallet/src/changeset/` module: - -``` -key-wallet/src/changeset/ -├── mod.rs -├── changeset.rs // WalletChangeSet + sub-changesets -├── merge.rs // Merge trait -└── traits.rs // WalletPersistence trait (generic) -``` - -Define `Merge` trait, `WalletChangeSet`, all sub-changesets, and -`WalletPersistence` trait. key-wallet types use dashcore primitives -(`OutPoint`, `Txid`, `Transaction`, `BlockHash`, `Address`). - -`check_core_transaction()` currently returns `TransactionCheckResult` -and mutates `ManagedWalletInfo` in place. Change it to ALSO return a -`WalletChangeSet` capturing what was mutated: -- `record_transaction()` → populate `transactions` + `utxos.added` -- `confirm_transaction()` → populate `transactions` status update -- `mark_utxos_instant_send()` → populate `utxos.instant_locked` -- `mark_address_used()` → populate `accounts.addresses_used` -- `maintain_gap_limit()` → populate `accounts.last_revealed` -- `update_balance()` → populate `balance` - -Each of these methods currently returns void. Change each to return -a sub-changeset that the caller merges into the operation's -`WalletChangeSet`. - -This is the **core refactor** — every mutation in key-wallet produces -a delta. The mutation still happens (in-memory state updated), but -the delta is also captured and returned to the caller. - -**Step 2 — Refactor key-wallet mutations to return changesets (dashcore repo):** - -For each mutation method in `ManagedCoreAccount` and `WalletTransactionChecker`: - -```rust -// Before (mutates in place, returns nothing): -pub fn record_transaction(&mut self, tx: &Transaction, ...) -> TransactionRecord { ... } - -// After (mutates in place AND returns delta): -pub fn record_transaction(&mut self, tx: &Transaction, ...) -> (TransactionRecord, WalletChangeSet) { ... } -``` - -Methods to change: -- `ManagedCoreAccount::record_transaction()` → return tx + UTXO deltas -- `ManagedCoreAccount::confirm_transaction()` → return status update delta -- `ManagedCoreAccount::mark_utxos_instant_send()` → return IS-lock delta -- `ManagedCoreAccount::mark_address_used()` → return address-used delta -- `AddressPool::maintain_gap_limit()` → return new-addresses delta -- `WalletTransactionChecker::check_core_transaction()` → aggregate all deltas from above -- `WalletTransactionChecker::update_balance()` → return balance delta - -The `TransactionCheckResult` gains a `changeset: WalletChangeSet` field -that aggregates all sub-deltas from the operation. - -**Step 3 — Rename platform-wallet changeset to PlatformWalletChangeSet:** - -- Rename existing `WalletChangeSet` → `PlatformWalletChangeSet` -- Add `wallet: Option` field -- Update `Merge` impl to merge the `wallet` sub-changeset -- Update `stage_changeset()` / `persist()` to use `PlatformWalletChangeSet` -- Update SPV adapter to wrap key-wallet's changeset into platform changeset - -**Step 4 — SPV adapter uses key-wallet changesets natively:** - -Currently the SPV adapter reconstructs changesets from `TransactionCheckResult`. -After Step 2, it just takes the `result.changeset` field and wraps it: - -```rust -let result = wi.check_core_transaction(tx, context, &mut w, true, true).await; -if result.state_modified { - let platform_changeset = PlatformWalletChangeSet { - wallet: Some(result.changeset), - ..Default::default() - }; - wallet.stage_changeset(platform_changeset); -} -``` - -No more manual TransactionEntry construction in the adapter. - -**Step 5 — Contact/identity operations produce complete changesets:** - -Each platform-wallet operation that mutates state returns a -`PlatformWalletChangeSet`: - -```rust -// send_contact_request returns the complete delta: -pub async fn send_contact_request(&self, ...) -> Result { - let mut changeset = PlatformWalletChangeSet::default(); - - // 1. Submit to Platform (external, no local state change) - let result = self.sdk.send_contact_request(input, ...).await?; - - // 2. Record sent request → ContactChangeSet - changeset.contacts = Some(ContactChangeSet { sent_requests: ... }); - - // 3. Register account → AccountChangeSet (via key-wallet WalletChangeSet) - let account_changeset = self.register_contact_account_changeset(...)?; - changeset.wallet = Some(account_changeset); - - // 4. Store in IdentityManager → IdentityChangeSet - changeset.identities = Some(IdentityChangeSet { ... }); - - Ok(changeset) -} -``` - -Caller calls `apply_and_stage(changeset)` then `persist()`. - -**Step 6 — Update SqlitePersister for PlatformWalletChangeSet:** - -The existing `SqliteWalletPersister` is updated to: -- Persist `changeset.wallet` (key-wallet deltas: UTXOs, transactions, accounts) -- Persist `changeset.identities` (identity state) -- Persist `changeset.contacts` (contact requests, established) -- Persist `changeset.platform_addresses` (DIP-17 balances) -- Persist `changeset.asset_locks` (asset lock lifecycle) -- All in one SQLite transaction - -**Step 7 — Remove old direct DB writes:** - -- Remove `update_address_balance()`, `update_address_total_received()` direct calls -- Remove `replace_wallet_transactions()` direct calls -- Remove `insert_utxo()` / `drop_utxo()` direct calls -- Remove `reconcile_spv_wallets()` balance/UTXO writes (replaced by changeset flow) -- All persistence goes through `persist()` → `SqliteWalletPersister` - -**Step 8 — Implement `initialize()` for startup:** - -`SqliteWalletPersister::initialize()` loads all persisted state from DB -tables and returns a single `PlatformWalletChangeSet` representing the -full stored state. Platform-wallet applies it to rebuild in-memory state. - -This replaces the current scattered DB loading in `get_wallets()`, -`load_wallet_transactions()`, etc. - -#### File Structure - -``` -rust-dashcore/key-wallet/src/ -├── persistence/ -│ ├── mod.rs -│ ├── changeset.rs // WalletChangeSet + UTXO/Tx/Account/Balance sub-changesets -│ ├── merge.rs // Merge trait + impls for BTreeMap, BTreeSet, Option, Vec -│ └── traits.rs // WalletPersistence trait (storage-agnostic) -└── ... - -packages/rs-platform-wallet/src/ -├── persistence/ -│ ├── mod.rs -│ ├── changeset.rs // PlatformWalletChangeSet (wraps key-wallet + platform deltas) -│ ├── merge.rs // Merge trait (re-export from key-wallet + platform impls) -│ └── traits.rs // PlatformWalletPersistence trait (extends key-wallet) -└── ... - -dash-evo-tool/src/ -├── persistence/ -│ ├── mod.rs -│ └── sqlite.rs // SqlitePersister implementing PlatformWalletPersistence -└── ... -``` - ---- - -## Address Type Coverage Summary - -| Address type | DIP | Derivation path | key-wallet collection field | Plan section | -|---|---|---|---|---| -| Core UTXO receive | BIP44 | `m/44'/coin'/acct'/0/i` | `standard_bip44_accounts` | §1.3.2 | -| Core UTXO change | BIP44 | `m/44'/coin'/acct'/1/i` | `standard_bip44_accounts` | §1.3.2 | -| Identity reg. funding | DIP-9 | `m/9'/coin'/5'/1'/i` (non-hardened i) | `identity_registration` | §1.4.1 | -| Identity top-up funding | DIP-9 | `m/9'/coin'/5'/2'/i` (non-hardened i) | `identity_topup_not_bound` | §1.4.4 | -| Identity auth keys | DIP-9 | `m/9'/coin'/5'/0'/key_type'/id'/key'` | — | §1.4.1 | -| Auto-accept proof key | DIP-15 | `m/9'/coin'/16'/timestamp'` | — | §1.5.11 | -| DashPay receive from contact | DIP-15 | `m/9'/coin'/15'/0'/(self)/(friend)/i` | `dashpay_receival_accounts` | §1.5.3 | -| DashPay send to contact | DIP-15 | contact xpub + index | `dashpay_external_accounts` | §1.5.4 | -| Platform P2PKH (credits) | DIP-17 | `m/9'/coin'/17'/acct'/class'/i` | `platform_payment_accounts` | §1.6 | - ---- - -## Risk Analysis - -| Risk | Mitigation | -|---|---| -| `IdentityManager` fields not yet `Arc>`-wrapped | Refactor in PR-1; add `last_scanned_index` field; confirm tests pass | -| `AddressProvider` API mismatch — actual trait uses push-based callbacks, not `apply_balance()` | Use confirmed trait definition from `rs-sdk/src/platform/address_sync/provider.rs`; implement `pending_addresses`/`on_address_found`/`on_address_absent` | -| AES decryption bug in `add_incoming_contact_request` | Fix in PR-3 — `decrypt_extended_public_key` before `ExtendedPubKey::decode`; add unit test proving plaintext roundtrip | -| DIP-9 auth key path missing `key_type'` segment | Fix in PR-2 — use full path `m/9'/coin'/5'/0'/key_type'/identity_index'/key_index'`; note: existing deployed wallets may have used the old path (key_type' omitted = effectively key_type'=0') — document deviation | -| DIP-14 `ser_256(i)` endianness | Add unit test against DIP-14 Appendix A vectors before any contact request is submitted | -| BLS key derivation semantics | Use raw 32-byte seed from BIP32 derivation as BLS secret key (not scalar addition mod bls12381 group order) — matches DashSync iOS | -| DB migration corrupts existing wallets | Version byte in DB; fallback read → convert; test against real DB fixture | -| Asset lock proof: InstantLock timeout | Implement 60s timeout before falling back to ChainLock polling — confirm ChainLocked height is known to Platform before using Chain proof | -| `PlatformWallet` not `Send+Sync` | Add `static_assertions::assert_impl_all!(PlatformWallet: Send, Sync)` | -| `Arc>` write starvation under concurrent SPV + Platform sync | SPV writes are short (tx update); Platform sync holds read lock briefly for balance reads — test under load | -| **Wallet + ManagedWalletInfo separation** — both are mutable (Wallet: accounts added during contact establishment; MWI: UTXOs/balances during sync). Original design assumed Wallet was immutable but it isn't. Two separate `RwLock`s create lock ordering risk and prevent atomic state updates. | Investigate merging in PR-6. Consider single struct behind one `RwLock`. | -| **Read starvation during block processing** — SPV `process_block()` holds write lock on both Wallet and ManagedWalletInfo for the entire block. During this time, CoreWallet read methods (`balance()`, `utxos()`, `all_address_info()`) are blocked. UI shows stale data until the block is fully processed. | Consider: (a) process transactions individually (release lock between txs), (b) use snapshot/MVCC pattern (clone state, process, swap), (c) accept the latency for now (blocks process in ms). | -| **Non-atomic state updates across structs** — Wallet, ManagedWalletInfo, and IdentityManager are separate structs behind separate locks. Operations that touch multiple (e.g., adding a DashPay account to Wallet + updating MWI addresses + updating IdentityManager contacts) cannot be atomic. A crash mid-operation leaves inconsistent state. | Investigate: (a) merge structs (PR-6), (b) WAL/journaling for multi-struct updates, (c) accept eventual consistency with recovery on restart. | -| `contactRequest` documents are immutable | Do not expose update/delete API; note in `send_contact_request` docs that retries create new documents | -| **`blocking_read()` deadlock risk in Signer::sign()** | DPP's `Signer` trait has sync `sign()` method but we use `tokio::sync::RwLock`. `blocking_read()` will deadlock if wallet write lock is held by same task. Document constraint: never call `sign()` while holding wallet write lock. Consider `std::sync::RwLock` for wallet in future. | -| **Signer code duplication** (IdentitySigner vs ManagedIdentitySigner) | Both have identical `sign()`/`sign_create_witness()`/`can_sign_with()` bodies. Extract shared `sign_with_key_bytes()` helper. Low priority — no correctness impact. | -| **ShieldedWallet spending ops incomplete** | `unshield()`, `transfer()`, `withdraw()` return runtime error — MerklePath witness deserialization not implemented. Output-only ops (`shield`, `shield_from_asset_lock`) work. Fix when integrating with evo-tool's SQLite `ClientPersistentCommitmentTree`. | -| **`rs-platform-wallet-ffi` broken type paths** | FFI crate references old type paths (`platform_wallet_info`, `identity_manager`, `managed_identity`) that were refactored. Fix in PR-19 by updating FFI imports to match new module structure. | -| **Auto-accept `account_reference` behavior change** | Platform-wallet uses `account_index` (0) as `account_reference`, not DIP-15 calculated value. Documented in evo-tool code. QR codes are session-scoped so old codes expire anyway. | - ---- - -## Sources & References - -### DIPs - -- [DIP-0013: Identities in HD Wallets](https://github.com/dashpay/dips/blob/master/dip-0013.md) — auth, registration, top-up funding paths -- [DIP-0014: Extended Key Derivation (256-bit)](https://github.com/dashpay/dips/blob/master/dip-0014.md) — CKDpriv256/CKDpub256 spec and test vectors -- [DIP-0015: DashPay](https://github.com/dashpay/dips/blob/master/dip-0015.md) — contact request structure, ECDH, AES-CBC encryption, account reference, DashPay payment paths -- [DIP-0017: Dash Platform P2PKH Addresses](https://github.com/dashpay/dips/blob/master/dip-0017.md) — platform payment addresses at `m/9'/coin'/17'/account'/key_class'/index` - ---- - -## TODO - -- [x] **`manager` feature gates `PlatformWalletManager`** — DONE: manager module gated at lib.rs level. -- [ ] **Revisit events** — Remove fallback `WalletEvent` enum (only exists for `not(manager)` — is there a real use case without manager?). Remove duplicate `TransactionStatusChanged` from `PlatformWalletEvent` (already in `WalletEvent`). Review whether `TransactionStatus` enum is still needed or should use `TransactionContext` from dashcore. -- [ ] **Fix `rs-platform-wallet-ffi` broken type paths** — FFI crate references old module paths (`platform_wallet_info`, `identity_manager`, `managed_identity`) that were refactored. Update imports to match new module structure. -- [ ] **Signer code duplication** — `IdentitySigner` and `ManagedIdentitySigner` have identical `sign()`/`sign_create_witness()`/`can_sign_with()` bodies. Extract shared `sign_with_key_bytes()` helper. -- [ ] **ShieldedWallet spending ops** — `unshield()`, `transfer()`, `withdraw()` return runtime error. Need `MerklePath` witness resolution from `ShieldedStore`. Fix when integrating with evo-tool's SQLite `ClientPersistentCommitmentTree`. -- [ ] **Finality proof data** — `wait_for_finality()` returns `AssetLockProof::default()`. SPV `SyncEvent::InstantLockReceived` carries the actual `InstantLock` — use it to build proper proof. -- [ ] **Restore git rev dependency** — workspace Cargo.toml currently uses local path deps for dashcore. Restore `git = "..." rev = "..."` once cargo git cache issue is resolved. -- [ ] **`blocking_read()` deadlock risk** — `Signer::sign()` uses `blocking_read()` on tokio `RwLock`. Document constraint or consider `std::sync::RwLock` for wallet. -- [ ] **Expose wallet_info lock accessor** — CoreWallet getters each acquire the lock individually and clone data (e.g. `utxos()` clones entire BTreeSet). Add `pub async fn wallet_info() -> RwLockReadGuard` for callers who need multiple reads in one lock. Stop cloning in getters — return references via the guard. Not urgent: no current caller chains multiple getters. - ---- - -### Key Repositories - -| Repo | Disk Path | Notes | -| ---- | --------- | ----- | -| `rs-platform-wallet` | `packages/rs-platform-wallet/` | Target library (this plan) | -| `rs-platform-encryption` | `packages/rs-platform-encryption/` | DIP-15 crypto — already a dependency, do not duplicate | -| `rs-platform-wallet-ffi` | `packages/rs-platform-wallet-ffi/` | FFI layer — update exports in PR-5 | -| `key-wallet` | `../rust-dashcore/key-wallet/` | UTXO wallet, key derivation, TransactionBuilder, `WalletInterface` (manager feature) | -| `dash-spv` | `../rust-dashcore/dash-spv/` | SPV client, BIP157/158 sync, push-based | -| `rs-sdk` | `packages/rs-sdk/` | DAPI client (`Sdk`, `SdkBuilder`, `AddressProvider`) | -| `dash-evo-tool` | `../dash-evo-tool/` | Integration target | - -### Platform Wallet (current — being replaced) - -- [packages/rs-platform-wallet/src/platform_wallet_info/identity_discovery.rs](packages/rs-platform-wallet/src/platform_wallet_info/identity_discovery.rs) — consolidate into `IdentityWallet::sync()` -- [packages/rs-platform-wallet/src/platform_wallet_info/contact_requests.rs](packages/rs-platform-wallet/src/platform_wallet_info/contact_requests.rs) — consolidate into `DashPayWallet`; fix AES decryption bug -- [packages/rs-platform-wallet/src/platform_wallet_info/key_derivation.rs](packages/rs-platform-wallet/src/platform_wallet_info/key_derivation.rs) — fix `key_type'` path segment -- [packages/rs-platform-wallet/src/wallet/identity/managed_identity/mod.rs](packages/rs-platform-wallet/src/wallet/identity/managed_identity/mod.rs) -- [packages/rs-platform-wallet/src/wallet/dashpay/contact_request.rs](packages/rs-platform-wallet/src/wallet/dashpay/contact_request.rs) -- [packages/rs-platform-wallet/src/wallet/dashpay/established_contact.rs](packages/rs-platform-wallet/src/wallet/dashpay/established_contact.rs) - -### SDK Transitions Used - -**Identity**: -- `PutIdentity` trait — `packages/rs-sdk/src/platform/transition/put_identity.rs` -- `TopUpIdentity` trait — `packages/rs-sdk/src/platform/transition/top_up_identity.rs` -- `WithdrawFromIdentity` trait — `packages/rs-sdk/src/platform/transition/withdraw_from_identity.rs` -- `TransferToIdentity` trait — `packages/rs-sdk/src/platform/transition/transfer.rs` -- `TopUpIdentityFromAddresses` — fund identity from platform addresses -- `TransferToAddresses` — move identity credits to platform addresses - -**Platform addresses**: -- `TransferAddressFunds` — transfer between platform addresses -- `WithdrawAddressFunds` — withdraw platform address credits to Core L1 -- `TopUpAddress` — fund platform address from identity balance -- `AddressProvider` trait — `packages/rs-sdk/src/platform/address_sync/provider.rs` - -**DashPay**: -- Contact requests — `packages/rs-sdk/src/platform/dashpay/contact_request.rs` - -**DPNS**: -- `register_dpns_name`, `resolve_dpns_name_to_identity` - -**Shielded** (feature-gated): -- `ShieldFunds`, `UnshieldFunds`, `TransferShielded`, `WithdrawShielded`, `ShieldFromAssetLock` - -**Token transitions**: -- Transfer, mint, burn, freeze, purchase, claim, balance queries - -**Signing**: -- `Signer` — by value for withdraw/transfer -- `Signer` — implemented on `PlatformAddressWallet` - -### Evo Tool (to be replaced) - -- `dash-evo-tool/src/model/wallet/mod.rs` — current `Wallet` struct (will be deleted in PR-1) -- `dash-evo-tool/src/app.rs` — `AppContext.wallets: RwLock>>>` -- `dash-evo-tool/src/backend_task/dashpay/dip14_derivation.rs` -- `dash-evo-tool/src/backend_task/dashpay/hd_derivation.rs` -- `dash-evo-tool/src/backend_task/dashpay/encryption.rs` -- `dash-evo-tool/src/backend_task/identity/discover_identities.rs` — `AUTH_KEY_LOOKUP_WINDOW = 12` -- `dash-evo-tool/src/backend_task/wallet/fetch_platform_address_balances.rs` diff --git a/packages/rs-platform-wallet/docs/DASHPAY_MIGRATION_PLAN.md b/packages/rs-platform-wallet/docs/DASHPAY_MIGRATION_PLAN.md deleted file mode 100644 index 4acc2f675dc..00000000000 --- a/packages/rs-platform-wallet/docs/DASHPAY_MIGRATION_PLAN.md +++ /dev/null @@ -1,257 +0,0 @@ -# DashPay Migration Plan: Evo-Tool → Platform-Wallet - -## Goal - -Move ALL DashPay logic from evo-tool into platform-wallet's `DashPayWallet`. -Evo-tool becomes a thin UI layer that triggers operations and displays results. -No DashPay state flows from evo-tool into platform-wallet. - -## Current State - -### What DashPayWallet already owns (platform-wallet) -- Contact request send (ECDH key exchange, encrypted xpub, broadcast) -- Contact request sync (fetch received requests from Platform, auto-establish) -- Contact request accept/reject -- Contact account registration (DIP-14 address derivation, key-wallet account) -- Incoming payment address matching (DashpayReceivingFunds account pools) -- DIP-14/15 xpub derivation, account reference calculation -- Auto-accept proof generation/verification -- Encryption/decryption helpers (AES-256-CBC account labels) - -### What evo-tool still owns (needs to move) - -#### Profile Operations -| Operation | Evo-tool file | SDK calls | Moves to | -|-----------|--------------|-----------|----------| -| Load own profile | profile.rs:25-132 | Document::fetch_many (profile by $ownerId) | DashPayWallet::sync() | -| Create profile | profile.rs:134-374 (create path) | sdk.document_create + DocumentCreateTransitionBuilder | DashPayWallet::create_profile() | -| Update profile | profile.rs:134-374 (update path) | sdk.document_replace + DocumentReplaceTransitionBuilder | DashPayWallet::update_profile() | -| Fetch contact profile | profile.rs:432-459 | Document::fetch_many | DashPayWallet::sync() or on-demand | -| Search profiles | profile.rs:461-566 | DPNS query + profile fetch per identity | DashPayWallet::search_profiles() | -| Avatar processing | profile.rs:199-226 | SHA-256 hash + DHash fingerprint | Move to DashPayWallet (pure compute) | - -#### Payment Operations -| Operation | Evo-tool file | SDK calls | Moves to | -|-----------|--------------|-----------|----------| -| Send payment to contact | payments.rs | derive_contact_payment_address + CoreWallet send | DashPayWallet::send_payment() | -| Record sent payment | payments.rs:334-340 via cache_payment | None (local) | Inside send_payment() | -| Record received payment | transaction_processing.rs:81-90 | None (local) | Inside match_incoming_dashpay_address() | -| Load payment history | payments.rs (local DB query) | None | Stays in evo-tool (UI reads from persister DB) | - -#### Contact Operations (partially moved) -| Operation | Evo-tool file | Status | -|-----------|--------------|--------| -| Send contact request | contact_requests.rs | Already delegates to DashPayWallet | -| Accept contact request | contact_requests.rs | Already delegates to DashPayWallet | -| Reject contact request | contact_requests.rs | Already delegates to DashPayWallet | -| Load contacts (enriched) | contacts.rs | Decrypt contactInfo, fetch profiles — needs DashPayWallet | -| Load contact requests | contact_requests.rs | Query Platform — needs DashPayWallet | -| ContactInfo create/update | contact_info.rs | Encrypt + broadcast — needs DashPayWallet | - -## DashPay Contract (DIP-15) - -Three document types: - -### `profile` (one per identity, mutable) -- `displayName` (string, max 25) -- `publicMessage` (string, max 140) -- `avatarUrl` (uri, max 2048) -- `avatarHash` (32-byte SHA-256) -- `avatarFingerprint` (8-byte dHash) -- Indexed by `$ownerId` (unique) -- Requires `$createdAt`, `$updatedAt` - -### `contactRequest` (immutable, cannot be deleted) -- `toUserId` (32-byte Identifier) -- `encryptedPublicKey` (96 bytes: 16-byte IV + AES-256-CBC encrypted xpub) -- `senderKeyIndex`, `recipientKeyIndex` (u32) -- `accountReference` (u32, DIP-15 formula) -- `encryptedAccountLabel` (optional, 48-80 bytes) -- `autoAcceptProof` (optional, 38-102 bytes) -- Requires identity encryption/decryption bounded keys - -### `contactInfo` (private metadata about contacts) -- `encToUserId` (32 bytes, encrypted) -- `rootEncryptionKeyIndex`, `derivationEncryptionKeyIndex` -- `privateData` (CBOR-encoded encrypted: aliasName, note, displayHidden, accounts) - -Contract loaded via: `dpp::system_data_contracts::load_system_data_contract(SystemDataContract::Dashpay, PlatformVersion::latest())` - -## SPV Integration - -Payment address derivation path (DIP-15): -`m/9'/coin'/15'/account'/(sender_id)/(recipient_id)` → BIP32 non-hardened `/index` → P2PKH - -Flow: SPV block → key-wallet `check_core_transaction` advances address pools → -`received_transaction_finality()` matches output via `try_match_incoming_dashpay_address()` → -record PaymentEntry on ManagedIdentity. - -Key insight: key-wallet already manages DashPay address pools via `DashpayReceivingFunds` -account type. SPV detection is pre-computed during `register_contact_account()`. - -## New DashPayWallet Public API - -### Sync (replaces evo-tool's load/fetch operations) -```rust -/// Comprehensive DashPay sync: contact requests + profiles for all -/// managed identities. Call on wallet open and periodic refresh. -pub async fn sync(&self) -> Result -``` -Internally: -1. Call existing `sync_contact_requests()` for each identity -2. Fetch profile documents for each identity (query by $ownerId) -3. Parse into DashPayProfile, cache on ManagedIdentity via set_dashpay_profile() -4. Fetch contact profiles for established contacts -5. Return summary (new contacts, profile updates, etc.) - -### Data Models - -```rust -/// Input for profile create/update. Only caller-provided fields. -/// Platform-wallet computes avatar_hash + avatar_fingerprint from -/// avatar_bytes internally, then drops the bytes. -pub struct ProfileUpdate { - pub display_name: Option, - pub public_message: Option, - pub avatar_url: Option, - /// Raw image bytes pre-downloaded by the app layer (evo-tool). - /// Platform-wallet computes SHA-256 hash + DHash fingerprint from - /// these, includes them in the document, then drops the bytes. - /// `None` = no avatar / remove avatar. - pub avatar_bytes: Option>, -} - -/// Persisted/displayed profile. Output of sync/create/update. -/// No raw bytes — only the computed hashes survive after processing. -pub struct DashPayProfile { - pub display_name: Option, - pub bio: Option, - pub avatar_url: Option, - pub avatar_hash: Option<[u8; 32]>, // SHA-256 of image bytes - pub avatar_fingerprint: Option<[u8; 8]>, // DHash perceptual hash - pub public_message: Option, -} -``` - -NOTE: `avatar_bytes` is removed from `DashPayProfile` — it was transient -(only needed during document creation) and shouldn't be persisted or -carried in memory. Evo-tool's `dashpay_profiles` table column -`avatar_bytes` can be kept for local UI caching but the profile model -doesn't carry it. - -### Profile Mutations (replace evo-tool's create/update) -```rust -/// Create a new DashPay profile on Platform. -/// Computes avatar hash/fingerprint from input.avatar_bytes if present. -/// Builds DocumentCreateTransition, broadcasts, caches result internally. -pub async fn create_profile( - &self, - identity_id: &Identifier, - input: ProfileUpdate, -) -> Result - -/// Update an existing DashPay profile on Platform. -/// Fetches current revision, bumps, broadcasts DocumentReplaceTransition. -/// Computes avatar hash/fingerprint from input.avatar_bytes if present. -pub async fn update_profile( - &self, - identity_id: &Identifier, - input: ProfileUpdate, -) -> Result -``` - -### Search (replace evo-tool's DPNS + profile search) -```rust -/// Search for DashPay profiles by DPNS username prefix. -/// Queries DPNS contract, then fetches profiles for matching identities. -pub async fn search_profiles( - &self, - prefix: &str, -) -> Result)>, PlatformWalletError> -``` -Needs DPNS contract: `load_system_data_contract(SystemDataContract::DPNS, ...)` - -### Payments (replace evo-tool's send + receive paths) -```rust -/// Send a Core payment to a DashPay contact. -/// Resolves contact's receiving address from DIP-14 derivation, -/// builds and broadcasts Core tx via CoreWallet, records PaymentEntry. -pub async fn send_payment( - &self, - from_identity_id: &Identifier, - to_contact_id: &Identifier, - amount_duffs: u64, - memo: Option, -) -> Result -``` - -For received payments: extend `match_incoming_dashpay_address` variants -to also call `record_dashpay_payment()` internally when a match is found. -The caller passes `(txid, value)` and the method handles everything. - -### ContactInfo (replace evo-tool's contact_info.rs) -```rust -/// Create or update encrypted contactInfo document on Platform. -pub async fn update_contact_info( - &self, - identity_id: &Identifier, - contact_id: &Identifier, - alias: Option, - note: Option, - hidden: bool, -) -> Result<(), PlatformWalletError> -``` - -### Load Contacts (replace evo-tool's contacts.rs enriched loading) -```rust -/// Load all established contacts with their profiles and DPNS names. -/// Decrypts contactInfo, fetches profiles for each contact. -pub async fn load_contacts( - &self, - identity_id: &Identifier, -) -> Result, PlatformWalletError> -``` - -## Migration Sequence - -### Phase 1: Profile Sync + Mutations (~200 LOC) -1. Add `fetch_profiles_for_identities()` internal helper to DashPayWallet -2. Add `sync()` that combines contact request sync + profile sync -3. Add `create_profile()` and `update_profile()` with avatar processing -4. Evo-tool profile.rs: delegate to DashPayWallet, remove Platform queries -5. Delete cache_profile from platform_wallet_cache.rs - -### Phase 2: Payment Recording (~100 LOC) -1. Extend `try_match_incoming_dashpay_address` to accept txid+value and record internally -2. Add `send_payment()` to DashPayWallet -3. Evo-tool: payments.rs delegates send, transaction_processing.rs simplified -4. Delete cache_payment + cache_payment_with_pw_blocking - -### Phase 3: Contact Enrichment + ContactInfo (~200 LOC) -1. Add `load_contacts()` with profile + DPNS enrichment -2. Add `update_contact_info()` for encrypted contact metadata -3. Add `search_profiles()` with DPNS integration -4. Evo-tool contacts.rs + contact_info.rs: delegate entirely - -### Phase 4: Cleanup (~-400 LOC from evo-tool) -1. Delete `platform_wallet_cache.rs` -2. Simplify profile.rs, payments.rs, contacts.rs to thin delegation -3. Make `set_dashpay_profile` and `record_dashpay_payment` on ManagedIdentity `pub(crate)` -4. Remove DashPay contract from AppContext (platform-wallet loads it internally) - -## Open Questions - -1. **Avatar processing**: RESOLVED. Evo-tool (app layer) downloads avatar bytes via HTTP - and passes them in `DashPayProfile.avatar_bytes`. Platform-wallet computes SHA-256 hash + - DHash fingerprint from those bytes — it knows DIP-15 requires them. Hash/fingerprint - functions move from evo-tool's `avatar_processing.rs` to platform-wallet. HTTP fetch - (`fetch_image_bytes`) stays in evo-tool. No reqwest dependency in platform-wallet. - -2. **State transition options**: evo-tool passes `app_context.state_transition_options()` for - fee multiplier etc. Platform-wallet needs equivalent configuration. - -3. **Load payment history**: Currently reads from evo-tool's persister DB directly. - This should stay in evo-tool (UI reads persisted data) — no Platform query needed. - -4. **DPNS contract for search**: search_profiles needs both DashPay + DPNS contracts. - Both available via `load_system_data_contract`. diff --git a/packages/rs-platform-wallet/src/changeset/core_bridge.rs b/packages/rs-platform-wallet/src/changeset/core_bridge.rs index 574715eed6b..7d19ffe7372 100644 --- a/packages/rs-platform-wallet/src/changeset/core_bridge.rs +++ b/packages/rs-platform-wallet/src/changeset/core_bridge.rs @@ -18,6 +18,14 @@ //! rows it implies and freeze forever. The unbounded //! persistence channel can never `Lagged`, so that freeze cannot occur. //! +//! # Why persistence lives outside the manager +//! +//! Upstream `WalletManager` deliberately has no per-wallet locks and no +//! built-in persistence. An earlier attempt that put per-wallet +//! `Arc>` locks and a persistence trait inside the manager made +//! SPV sync about 7x slower from lock contention, so persistence is this +//! external consumer instead. Do not move it back into the manager. +//! //! # Why a single consumer, not per-wallet //! //! The persistence channel carries every event for every wallet. Each diff --git a/packages/rs-platform-wallet/src/changeset/traits.rs b/packages/rs-platform-wallet/src/changeset/traits.rs index 04cfd7f0d03..e1538a26263 100644 --- a/packages/rs-platform-wallet/src/changeset/traits.rs +++ b/packages/rs-platform-wallet/src/changeset/traits.rs @@ -213,9 +213,9 @@ impl PersistenceError { /// (an evo-tool wrapper type around `dpp::Identity`) is currently written /// directly by `Database::insert_local_qualified_identity` and /// `Database::update_local_qualified_identity`, called from backend tasks. -/// Moving this blob into the persister is planned as a future commit -/// (evo-tool task #130 / Phase 9c). Until then, the persister does not -/// write or read the `identity.data` column. +/// Moving this blob into the persister is planned as a future evo-tool +/// change. Until then, the persister does not write or read the +/// `identity.data` column. /// - **Platform addresses** and **token balances**: these are dropped on /// flush; backend tasks own their persistence. /// diff --git a/packages/rs-platform-wallet/src/manager/identity_sync.rs b/packages/rs-platform-wallet/src/manager/identity_sync.rs index 54d2fd81af8..855cefa055b 100644 --- a/packages/rs-platform-wallet/src/manager/identity_sync.rs +++ b/packages/rs-platform-wallet/src/manager/identity_sync.rs @@ -9,6 +9,12 @@ //! [`unregister_identity`](Self::unregister_identity), //! [`update_watched_tokens`](Self::update_watched_tokens)). //! +//! The watch list is required, not an optimization: Platform's token +//! balance and info queries take explicit token ids +//! (`GetIdentityTokenBalancesRequestV0.token_ids`), and no query lists the +//! tokens an identity holds. The manager can only sync tokens a caller +//! registered through `update_watched_tokens`. +//! //! Each pass walks every registered identity, snapshots its watched //! token list, then sequentially: //! @@ -19,9 +25,7 @@ //! batches or identities) — see crate-level note on SDK `!Send` //! futures. //! 2. Builds a [`TokenBalanceChangeSet`] from the batch result and -//! forwards it to the persister. The wallet-side write path -//! (`TokenWallet::sync` mutating `PlatformWalletInfo.token_balances` -//! directly) is unrelated and untouched. +//! forwards it to the persister. //! 3. Updates the manager's own per-identity cache row in lockstep, //! so callers reading [`state_for_identity`](Self::state_for_identity) //! after [`sync_now`](Self::sync_now) returns see fresh values. @@ -617,8 +621,7 @@ where // Type-annotate the call site explicitly: `fetch_many` // is generic over the response type, and the inference // chain through `RetrievedObjects` doesn't pick a unique - // implementor without a hint. Same pattern used by - // `TokenWallet::sync`. + // implementor without a hint. let fetched: Result = TokenAmount::fetch_many(self.sdk.as_ref(), query).await; match fetched { diff --git a/packages/rs-platform-wallet/src/wallet/apply.rs b/packages/rs-platform-wallet/src/wallet/apply.rs index 10780172b4a..0f4ec4a8c33 100644 --- a/packages/rs-platform-wallet/src/wallet/apply.rs +++ b/packages/rs-platform-wallet/src/wallet/apply.rs @@ -1,7 +1,7 @@ //! Apply a [`PlatformWalletChangeSet`] onto a [`PlatformWalletInfo`] //! during restore. //! -//! Inverse of the mutation methods that emit changesets in Phase 9a-2: +//! Inverse of the mutation methods that emit changesets: //! given a persisted [`PlatformWalletChangeSet`], it replays each //! sub-changeset onto the in-memory state so the wallet converges to //! the same state the original mutations produced. @@ -18,14 +18,13 @@ //! isn't present in the wallet are logged with `tracing::warn!` and //! skipped — orphans usually mean a stale persisted entry from //! before the owner identity was removed. -//! - **Loud on core failures.** If `key_wallet`'s core apply fails (HD -//! account derivation cascade), the platform apply fails too. Core -//! state must land before any platform-specific bucket runs. +//! - **Core is not replayed.** `cs.core` is dropped. `key_wallet` keeps +//! core state current at runtime, and boot restores it from the +//! persister's `ClientStartState`, not from changeset replay. //! //! # Ordering //! -//! 1. `cs.core` — runs first via `ManagedWalletInfo::apply_changeset`. -//! Wallet account state must exist before balance recompute. +//! 1. `cs.core` — dropped (see the invariant above). //! 2. `cs.identities` — insert/update entries, then `removed`, then //! primary identity fixup. //! 3. `cs.contacts` — sent/incoming inserts, tombstone removes, @@ -42,7 +41,7 @@ //! callback. There is nothing on `PlatformWalletInfo` to apply //! them onto. //! 7. `update_balance()` — recompute the cached `WalletBalance` from -//! the now-restored UTXO set; the returned changeset is discarded. +//! the current UTXO set; the returned changeset is discarded. use key_wallet::wallet::Wallet; @@ -64,6 +63,9 @@ pub enum ApplyError { /// /// Stored as `String` to keep the platform-wallet public API /// decoupled from `key_wallet`'s error enum. + /// + /// Not constructed today: `apply_changeset` drops `cs.core` instead of + /// replaying it (see the module docs). #[error("core wallet apply failed: {0}")] CoreApply(String), @@ -799,7 +801,7 @@ mod tests { } // ---------------------------------------------------------------------- - // Round-trip tests (Phase 9a-4) + // Round-trip tests // // The shape of every test is identical: // 1. Build two empty `PlatformWalletInfo`s — A is the wallet that gets @@ -813,14 +815,14 @@ mod tests { // // These verify the round-trip contract: changesets emitted by mutations // are faithful enough that apply rebuilds the same in-memory state. This - // is what makes the persister adapter (Phase 9a-5) safe — it can + // is what makes the persister adapter safe — it can // serialize the captured changeset and deserialize it back into a // sibling wallet on restart with no information loss. // - // Out of scope: AssetLockManager / TokenWallet / PlatformAddressWallet + // Out of scope: AssetLockManager / token sync / PlatformAddressWallet // mutations are async and require an `Sdk` + broadcaster + Notify, so // they can't run as plain unit tests. Their round-trip coverage will - // come from integration tests (Phase 9a-4 follow-up). The + // come from integration tests (not written yet). The // synthesized-data tests above already cover the apply side; the gap // is verifying the *mutation side* emits a faithful changeset. // ---------------------------------------------------------------------- @@ -1289,7 +1291,7 @@ mod tests { } // ---------------------------------------------------------------------- - // Reviewer test gaps (Phase 9a-3 followup) + // Reviewer test gaps // ---------------------------------------------------------------------- /// Reviewer #6a: removing the sole identity drops it cleanly. diff --git a/packages/rs-platform-wallet/src/wallet/identity/crypto/auto_accept.rs b/packages/rs-platform-wallet/src/wallet/identity/crypto/auto_accept.rs index ed20b65f11e..0f93f00bff8 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/crypto/auto_accept.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/crypto/auto_accept.rs @@ -41,8 +41,11 @@ use crate::error::PlatformWalletError; /// DIP-15 mandates only that the proof's 4-byte timestamp *is* an expiry (and the /// hardened derivation index); it does not prescribe a value. We pick a short /// default because the QR carries a usable (bearer) private key and auto-accept -/// is always-on (no off-switch) — see the security notes in -/// `docs/dashpay/QR_AUTO_ACCEPT_SPEC.md` §6. +/// is always-on (no off-switch). The key in the QR is intrinsic to DIP-15 (the +/// scanner must sign, and the owner cannot pre-sign without the scanner's id); it +/// only authorizes auto-accept, so a leaked QR can at worst produce unwanted +/// contact requests (removable with ignore) until it expires, and the short expiry +/// is the mitigation. pub const AUTO_ACCEPT_TTL_SECS: u32 = 3600; /// `key type` byte for an ECDSA_SECP256K1 auto-accept key/proof (DIP-15). diff --git a/packages/rs-platform-wallet/src/wallet/identity/crypto/dip14.rs b/packages/rs-platform-wallet/src/wallet/identity/crypto/dip14.rs index 9145403be8f..bd914b93606 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/crypto/dip14.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/crypto/dip14.rs @@ -251,6 +251,12 @@ pub fn derive_contact_payment_addresses( /// /// "We recommend a gap limit of 10 at this stage, which means to load 10 /// addresses past the last used address." +/// +/// The wallet does not use this value for contact pools. key-wallet builds +/// the `DashpayReceivingFunds` and `DashpayExternalAccount` address pools +/// with a gap of 20, a deliberate, more conservative choice. Do not shrink +/// those pools to 10 to match the DIP: that narrows the scan window for +/// payments past a run of unused addresses. pub const DEFAULT_CONTACT_GAP_LIMIT: u32 = 10; // --------------------------------------------------------------------------- diff --git a/packages/rs-platform-wallet/src/wallet/identity/crypto/invitation.rs b/packages/rs-platform-wallet/src/wallet/identity/crypto/invitation.rs index 6060013024a..efa2a7b090e 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/crypto/invitation.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/crypto/invitation.rs @@ -27,7 +27,10 @@ //! order-independent (the two legacy wallets differ in param order). //! - `islock` is optional: a missing param **and** the literal string `"null"` //! (which Android emits for chainlock-confirmed invites) both mean "no instant -//! lock" — the claim reconstructs a ChainLock proof instead. +//! lock" — the claim reconstructs a ChainLock proof instead. The hex decodes +//! as the deterministic InstantSend lock; a lock in the older +//! non-deterministic format does not decode, so the claim fails rather than +//! guessing (no live wallet emits that format). //! - `assetlocktx` is kept as the raw hex string; the claim tries it as-given //! then byte-reversed on a fetch miss, mirroring the legacy endianness retry. //! @@ -40,6 +43,28 @@ //! force a large allocation; the WIF is decoded + compression-checked at parse, //! and its network is validated against the wallet at claim (a wrong-network WIF //! is a valid key on the wrong chain, caught before the funding fetch). +//! +//! What the design does and does not protect against: +//! - Every theft reduces to "who holds the link". Platform checks the claim's +//! signature against the key of the asset-lock output, and the new identity's +//! id is derived from the funding outpoint, so someone who watches a claim in +//! flight but lacks the voucher key cannot redirect it, and two racing claims +//! target the same identity (exactly one commits). +//! - The inviter can always re-derive the voucher key, so after handing over a +//! link it can still claim or reclaim the voucher first. Nothing is stolen +//! (the funds were the inviter's), but the invitee is denied onboarding with +//! no sign of why. For the same reason, reclaiming a leaked link is a race the +//! inviter can lose. +//! - Nothing signs the link, so whoever controls the channel it travels over +//! can swap in a different invite. The worst outcome is the invitee sending a +//! contact request to the attacker's identity, which an ordinary contact +//! request achieves anyway. Signing would not help: the channel is the trust +//! root. +//! - Because the identity id comes from the funding outpoint, the inviter knows +//! the invitee's identity id before the invitee claims it. +//! - The legacy wallets wrapped the link in an AppsFlyer OneLink, which sends +//! the plaintext `pk` to AppsFlyer's servers. We parse that host but never +//! emit it. use dashcore::secp256k1::{PublicKey, Secp256k1, SecretKey}; use dashcore::transaction::special_transaction::TransactionPayload; diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs b/packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs index 8f95fed9279..9486dca9bf5 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs @@ -800,6 +800,18 @@ impl DashPayView<'_> { } } +/// High-water rewind window applied to the incremental contact-request query. +/// Re-fetching the last 10 minutes each sweep covers clock skew **and** +/// equal-`$createdAt` documents straddling a page boundary, so it is +/// correctness-load-bearing — NOT a tunable; `0` is invalid. +const SYNC_OVERLAP_MS: u64 = 10 * 60_000; + +/// Lower bound for the incremental `$createdAt >` query: the high-water minus +/// the overlap window. `None` (no cursor yet) ⇒ full fetch. +fn query_lower_bound(high_water: Option) -> Option { + high_water.map(|hw| hw.saturating_sub(SYNC_OVERLAP_MS)) +} + /// Collapse a stream of parsed received contact requests to the single /// newest request per sender, keyed by `sender_id`. /// @@ -815,18 +827,29 @@ impl DashPayView<'_> { /// like a "rotation" away from the tracked state, thrashing it back and /// forth each pass. Collapsing to the newest first makes the sweep a /// fixpoint. -/// High-water rewind window applied to the incremental contact-request query. -/// Re-fetching the last 10 minutes each sweep covers clock skew **and** -/// equal-`$createdAt` documents straddling a page boundary, so it is -/// correctness-load-bearing — NOT a tunable; `0` is invalid. -const SYNC_OVERLAP_MS: u64 = 10 * 60_000; - -/// Lower bound for the incremental `$createdAt >` query: the high-water minus -/// the overlap window. `None` (no cursor yet) ⇒ full fetch. -fn query_lower_bound(high_water: Option) -> Option { - high_water.map(|hw| hw.saturating_sub(SYNC_OVERLAP_MS)) -} - +/// +/// Collapsing per sender is also why a contact has one payment channel even +/// though DIP-15 lets a sender expose several accounts at once. Supporting +/// several was deferred on purpose, and the collapse cannot simply be keyed +/// by `(sender, account_reference)`: +/// - The recipient cannot tell a rotation from a new account. The low 28 bits +/// of `accountReference` are masked with an HMAC of the new xpub under a +/// key only the sender knows, so a rotated channel and a brand-new account +/// look unrelated. Which +/// channel a request belongs to would have to come from the user. +/// - Keying by reference brings back the sweep thrash described above: a +/// rotated sender's old and new docs would both survive and flip the stored +/// channel on every pass. +/// - The receiving account index is a hardened derivation path component, so +/// a locally invented channel index would desync the addresses we advertise +/// from the ones we watch. +/// - Each new reference would become a pending prompt, turning a request +/// flood into queue exhaustion, and "add account" from an established +/// contact can redirect payments, so it needs the same care as accepting a +/// new contact. +/// +/// DIP-15 section 8.4 allows ignoring additional requests, which is what the +/// collapse does. fn newest_received_per_sender( requests: impl IntoIterator, ) -> std::collections::BTreeMap { @@ -3847,6 +3870,13 @@ impl DashPayView<'_, B> { /// /// Ignore is **local-only** — there is no on-chain artifact (syncing it /// would leak who you ignored via the public contact-request indices). + /// If ignore ever syncs across devices, it must be a single list the owner + /// encrypts to themselves, not a `contactInfo` per ignored sender: a + /// `contactInfo` about a non-contact exists publicly and its `$createdAt` + /// lines up with the incoming request, which reveals who was ignored. + /// Ignore also saves no fetch cost: the query has no "sender not in" + /// axis, so an ignored sender's requests are still fetched and verified, + /// then dropped here. /// The ignore is persisted through the existing /// changeset → apply → SQLite pipeline so it survives a relaunch. /// diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/invitation.rs b/packages/rs-platform-wallet/src/wallet/identity/network/invitation.rs index 76ccd55ce9e..2c848be0aee 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/invitation.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/invitation.rs @@ -12,7 +12,6 @@ //! here: after a successful claim the UI asks the invitee whether to establish //! contact with the sender and, if so, calls the existing contact-request path //! ([`send_contact_request_with_external_signer`](IdentityWallet::send_contact_request_with_external_signer)). -//! See `docs/dashpay/DIP15_INVITATIONS_SPEC.md`. use std::collections::BTreeMap; diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/payments.rs b/packages/rs-platform-wallet/src/wallet/identity/network/payments.rs index 940b8da96ec..a5b49b41bc6 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/payments.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/payments.rs @@ -250,10 +250,10 @@ impl DashPayView<'_, B> { /// starts, so a stretch of unused indices cannot stop it. /// /// Unused stretches come from sends that consumed an address and then - /// failed to build; five gap limits (100 addresses at the DIP-15 gap of - /// 20) covers far more consecutive failures than a contact realistically - /// accumulates, and the walk still extends past it whenever a match - /// lands near the frontier. + /// failed to build; five gap limits (100 addresses at key-wallet's gap + /// of 20; DIP-15 recommends 10) covers far more consecutive failures + /// than a contact realistically accumulates, and the walk still + /// extends past it whenever a match lands near the frontier. const HISTORICAL_SEED_GAP_MULTIPLE: u32 = 5; /// The `(owner identity, contact identity)` pair every reconstructed diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/profile.rs b/packages/rs-platform-wallet/src/wallet/identity/network/profile.rs index dbd61fdd628..50a8aecbe10 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/profile.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/profile.rs @@ -542,6 +542,17 @@ impl DashPayView<'_, B> { /// are themselves managed identities are skipped (their own /// `dashpay_profile` is authoritative). Display-only: a failure never /// aborts the sweep. Returns the number of cache entries changed. + /// + /// Fetching pending senders' profiles is an accepted privacy cost: an + /// observer could link the `$ownerId In [...]` query to our inbound set, + /// but the DAPI node that serves our `toUserId == me` query already sees + /// that whole set, so the profile fetch adds little. + /// + /// Profiles are refetched after `CONTACT_PROFILE_REFRESH_MS` rather than by + /// `$updatedAt`: `$ownerId In [...] AND $updatedAt > marker` cannot be + /// proven in one query (an `In` on the first index field plus a range on + /// the second is not a contiguous index range). A per-owner `$updatedAt` + /// query would lose the batching. pub async fn sync_contact_profiles(&self) -> Result { let now_ms = crate::util::now_ms(); let dashpay_contract = super::dashpay_contract()?; diff --git a/packages/rs-platform-wallet/src/wallet/identity/types/dashpay/profile.rs b/packages/rs-platform-wallet/src/wallet/identity/types/dashpay/profile.rs index 83fc5f9a5dc..ab661278f99 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/types/dashpay/profile.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/types/dashpay/profile.rs @@ -100,6 +100,12 @@ pub fn calculate_avatar_hash(image_bytes: &[u8]) -> [u8; 32] { /// 3. Compare each pixel with its right neighbor /// 4. Generate 64-bit hash from comparisons /// +/// Compare fingerprints by Hamming distance, never by equality. The bit +/// layout matches dashj, but the pixel pipeline differs (grayscale weighting, +/// resize filter, 9x9 vs 9x8), so the same image hashed by another client +/// gives a close fingerprint, not an identical one. A cross-client test that +/// expects identical bytes is wrong by construction. +/// /// Returns `Err` if the bytes are not a valid image. pub fn calculate_dhash_fingerprint(image_bytes: &[u8]) -> Result<[u8; 8], String> { let img = diff --git a/packages/rs-platform-wallet/src/wallet/identity/types/key_storage.rs b/packages/rs-platform-wallet/src/wallet/identity/types/key_storage.rs index 8dee1a702b9..634a6459e3f 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/types/key_storage.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/types/key_storage.rs @@ -26,14 +26,27 @@ pub enum PrivateKeyData { } /// Identity lifecycle status on Platform. +/// +/// Intended transitions: `Unknown` -> `PendingCreation` -> `Active`, +/// `PendingCreation` -> `FailedCreation` -> `Active` (after a retry), and +/// `Active` -> `NotFound` -> `Active`. Today the library itself sets only +/// `Unknown` (the default) and `Active` (after loading or discovering the +/// identity on Platform); the other variants exist for hosts and are +/// persisted like the rest. The FFI stores each variant as a byte in +/// declaration order (0 to 4), so never reorder them. #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub enum IdentityStatus { + /// Not checked against Platform yet. #[default] Unknown, + /// Registration submitted, not yet confirmed. PendingCreation, + /// Confirmed on Platform. Active, + /// Registration failed; it can be retried. FailedCreation, + /// Was active, but Platform no longer returns it. NotFound, } diff --git a/packages/swift-sdk/CLAUDE.md b/packages/swift-sdk/CLAUDE.md index 89efa185cf1..041a6fa1951 100644 --- a/packages/swift-sdk/CLAUDE.md +++ b/packages/swift-sdk/CLAUDE.md @@ -69,6 +69,16 @@ possible: add a single FFI entry point that does the whole thing and returns the bytes ready to persist. +Keep the two signer handles separate. The document signer (`VTableSigner` +/ `SignerHandle`) is a vtable that calls back into Swift to sign state +transitions. The wallet-HD signer (`MnemonicResolverHandle`) lets Rust +fetch the mnemonic for one operation, derive, and wipe. Raw-secret DashPay +operations (ECDH, `accountReference`, `contactInfo` encryption) run on the +wallet-HD side inside the FFI crate's Rust and return only results. +Merging the handles would either route the mnemonic through the +document-signing path or move DIP-15 crypto into Swift. What the Keychain +protection does and does not guarantee is written on `WalletStorage`. + ## Concrete precedent The correct shape is `platform_wallet_discover_identities` (and its @@ -93,3 +103,9 @@ If it's deciding anything — how many, which index, which path, which key, which order — move the decision to Rust. If you find a decision that Rust doesn't currently let you ask for by a single call, add the helper in the Rust library first. + +## Parity with the Kotlin SDK + +Capability parity between the two SDKs and example apps is tracked in +`docs/sdk/sdk-parity-manifest.json`. See "Keeping parity with iOS" in +`packages/kotlin-sdk/CLAUDE.md` for the rules and the regeneration command. diff --git a/packages/swift-sdk/Sources/SwiftDashSDK/Core/Wallet/WalletStorage.swift b/packages/swift-sdk/Sources/SwiftDashSDK/Core/Wallet/WalletStorage.swift index e468cc44406..76e530c4d76 100644 --- a/packages/swift-sdk/Sources/SwiftDashSDK/Core/Wallet/WalletStorage.swift +++ b/packages/swift-sdk/Sources/SwiftDashSDK/Core/Wallet/WalletStorage.swift @@ -29,6 +29,17 @@ import Security /// * Biometric-protected seed stash at `wallet.biometric` — not yet /// wired to a caller but kept because it's a different category /// (hardware-protected rather than a legacy PIN construct). +/// +/// What the mnemonic's protection actually is: the items are +/// `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` with no +/// `SecAccessControl` on the read path, and the biometric stash above is +/// unused. So "user present" means "device unlocked": any code in the +/// process can drive the mnemonic resolver while the device is unlocked. +/// Android's default auth-gated Keystore policy is stricter. Each +/// resolver-backed operation rebuilds the full BIP-39 seed and master +/// xprv inside the FFI crate's Rust and wipes them afterwards, so the gain +/// over a resident wallet is a short per-operation window, not "the seed +/// never enters memory". public class WalletStorage { /// Unified keychain service name for the app. Everything the /// SDK writes — per-wallet mnemonics (here), identity private diff --git a/packages/swift-sdk/Sources/SwiftDashSDK/FFI/KeychainSigner.swift b/packages/swift-sdk/Sources/SwiftDashSDK/FFI/KeychainSigner.swift index d41605004fd..a0c1ac657e0 100644 --- a/packages/swift-sdk/Sources/SwiftDashSDK/FFI/KeychainSigner.swift +++ b/packages/swift-sdk/Sources/SwiftDashSDK/FFI/KeychainSigner.swift @@ -601,6 +601,18 @@ public final class KeychainSigner: Signer, @unchecked Sendable { /// Shared by the sign trampoline and tests: consult any scoped /// in-memory registry first, then the existing platform-address / /// breadcrumb / persisted-key paths. + /// + /// Keep the stored-scalar fallback (`lookupIdentityPrivateKey` + + /// `ffiSign`) until a per-device migration stamp, persisted at + /// runtime, records that every identity key row has a derivation path + /// and the old `identity_privkey.*` Keychain items are purged. A + /// release-time check is not enough: a user can skip the version that + /// ran the backfill, so the build that drops the fallback must still + /// run the Keychain-driven backfill on first launch (the Keychain + /// survives a SwiftData store rebuild). Wallets without a mnemonic + /// (watch-only or imported with a bare key) can only sign through the + /// fallback until a mnemonic is imported. Removing it early locks those + /// users out of identities that work today. func signOnDemand( publicKey: Data, keyType: UInt8, diff --git a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Services/ShieldedService.swift b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Services/ShieldedService.swift index 982d064f4df..057fca7a0dd 100644 --- a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Services/ShieldedService.swift +++ b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Services/ShieldedService.swift @@ -119,8 +119,7 @@ class ShieldedService: ObservableObject { // // Surfaces wall-clock of each sync pass so devnet stress tests // (1M shielded notes via `dashpay/drive:3.1-shielded.*`) can be - // measured from the iOS client. See - // `docs/shielded-sync-timing-spec.md` for the design. + // measured from the iOS client. /// Wall-clock of the most recent NON-cooldown completed sync /// pass. Nil until the first such pass after `bind()`. @@ -1041,7 +1040,11 @@ class ShieldedService: ObservableObject { // here is the Swift-side timestamp of when the // event handler runs (≈ when isSyncing flipped // true → false), pairing with `currentSyncStartedAt` - // captured on the false → true edge. Clamp to >= 0 + // captured on the false → true edge. Both edges must + // be Swift `Date()`s: `event.syncUnixSeconds` is whole + // seconds, so pairing it with a `Date()` gives + // negative or inflated durations for sub-second + // passes. Clamp to >= 0 // defensively — should never be negative with // Swift-edge endpoints, but if the start timestamp // is missing (e.g. event arrived without a paired diff --git a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/CoreContentView.swift b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/CoreContentView.swift index c4376359aaf..e6c47d0a07f 100644 --- a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/CoreContentView.swift +++ b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/CoreContentView.swift @@ -582,8 +582,7 @@ var body: some View { // completion, shows the most recent non-cooldown // pass duration. Mono digits keep the number // readable as it ticks during long initial - // syncs (e.g. 10 min at N=1M). See - // `docs/shielded-sync-timing-spec.md`. + // syncs (about 20 min for 1M notes on paloma). if shieldedService.isSyncing, let elapsed = shieldedService.currentSyncElapsed { VStack(alignment: .leading, spacing: 4) { diff --git a/packages/swift-sdk/SwiftExampleApp/docs/shielded-sync-timing-spec.md b/packages/swift-sdk/SwiftExampleApp/docs/shielded-sync-timing-spec.md deleted file mode 100644 index f4d89591de5..00000000000 --- a/packages/swift-sdk/SwiftExampleApp/docs/shielded-sync-timing-spec.md +++ /dev/null @@ -1,353 +0,0 @@ -# Shielded sync timing — SwiftExampleApp spec (revised) - -## Goal - -When the user runs SwiftExampleApp against a devnet whose chain has a -pre-seeded shielded pool (N=1M notes via `dashpay/drive:3.1-shielded.2`), -**they need to see in the UI how long a shielded sync pass took, AND -have a live signal that an in-flight sync is making progress.** - -Primary use case: confirming initial wallet sync against a 1M-note -devnet completes within expected wall-clock (~10 min on M-series), and -that the user can tell from the UI whether sync is alive vs hung during -the long initial pass. - -## Why the goal expanded vs the first draft - -Adversarial review surfaced that a post-hoc-only duration is theatre at -N=1M: the user stares at a "Syncing..." spinner for ten minutes with no -signal "alive vs hung" — exactly the failure mode this exercise is -meant to detect. A live elapsed display is therefore mandatory for the -primary use case, not optional. - -## Scope (two surfaces) - -### Surface 1 — timing display (the primary task) - -The existing "ZK Shielded Sync Status" section in -`CoreContentView.swift` (≈ lines 391–510). One inline addition to that -section, two new `@Published` fields on `ShieldedService`, one console -log line per pass. No existing functionality changes. - -### Surface 2 — TEMPORARY test-wallet import (to make the timing meaningful) - -To validate against `dashpay/drive:3.1-shielded.2` and recover the -seeded 400 000 balance, the iOS app needs to sync wallet A whose -ZIP-32 seed is the **raw bytes `[0x73; 32]`** — not derivable from -any BIP-39 mnemonic. - -This requires: - -1. **New FFI** `platform_wallet_manager_bind_shielded_with_raw_seed` - in `packages/rs-platform-wallet-ffi/src/shielded_sync.rs` — sibling - to the existing `platform_wallet_manager_bind_shielded`, but - accepts a `seed_bytes: *const u8` + `seed_len: usize` instead of - a `MnemonicResolverHandle`. Calls - `wallet.bind_shielded(raw_seed.as_slice(), ...)` directly. -2. **Swift wrapper** `bindShieldedRawSeed(walletId:rawSeed:accounts:)` - in `Sources/SwiftDashSDK/PlatformWallet/...` -3. **Debug-only UI button** "Bind Test Wallet A (Shielded)" in the - existing ZK Shielded Sync Status section. Hardcodes `[0x73; 32]` - and calls the new wrapper. - -**Everything in Surface 2 is tagged with explicit removal TODOs.** -Example tag: -``` -// TODO(shielded-snapshot-devnet-test): remove this FFI entry once -// SwiftExampleApp adopts a proper test-wallet import flow. -// Tracked: dashpay/platform#3714. -``` - -Surface 2 lives behind no `#[cfg]` gate (would complicate the -release build), so the TODO comments are the contract: this surface -is provisional and removed before merging the ultimate version of -PR #3732. - -## Non-goals - -- Not building a separate sync dashboard. -- Not orchestrating sync from Swift — `walletManager.startShieldedSync` - already runs the loop; we observe. -- Not exposing per-cmx mid-pass progress (e.g. "412k/1M scanned"). That - needs a Rust→Swift signal we don't have today. Out of scope. -- Not measuring "whole catch-up cycle" duration as a single value (see - §"Known limitation: catch-up vs per-pass" below). -- Not persisting timing across app launches — display state only. -- Not building a `timeSinceBind` / "cumulative since bind" number — it - grows unbounded and answers no concrete question. - -## Existing surface (recap) - -**Service:** `ShieldedService` (`Core/Services/ShieldedService.swift`) - -Existing `@Published`: -- `isSyncing: Bool` -- `lastSyncTime: Date?` (when the most recent sync **completed**) -- `syncCountSinceLaunch: Int` -- `totalScanned: UInt64`, `totalNewNotes: UInt64`, `totalNewlySpent: UInt64` -- counters, balance, address fields - -**UI:** `CoreContentView.swift` "ZK Shielded Sync Status" section -already shows `ProgressView()` + "Syncing..." while in-flight, -"Last sync: " via `lastSyncTime`, cumulative counters, -balance + Notes Synced watermark, Sync Now / Clear buttons. - -**Underlying flow (Rust → Swift):** -1. `walletManager.$shieldedSyncIsSyncing` publishes `Bool`. Flips true - at sync-pass start, false at completion. -2. `walletManager.$lastShieldedSyncEvent` publishes a - `ShieldedSyncEvent` on each pass completion. - -**Gap:** UI shows COUNTERS and relative completion time, but no -wall-clock duration of a single pass, and no live indication during a -10-minute initial sync. - -## Spec - -### S1. Service-level fields - -Two new `@Published` fields on `ShieldedService` (read by the UI): - -| Field | Type | Semantic | -|---|---|---| -| `lastSyncDuration: TimeInterval?` | seconds | wall-clock of the most recent non-cooldown sync pass (set at completion) | -| `currentSyncElapsed: TimeInterval?` | seconds | running wall-clock of the in-flight sync; ticks while `isSyncing == true`, nil otherwise | - -One new private field: - -| Field | Set when | -|---|---| -| `currentSyncStartedAt: Date?` | `isSyncing` Swift mirror transitions false → true | - -Both `@Published` fields stay nil until they have a real value to -show. Both reset to nil on `bind()` / `reset()` / `clearLocalState`. - -**No `lastBindCompletedAt`, no `lastSyncCompletedAt`, no `timeSinceBind`** — -dropped per Scope reviewer. - -### S2. Pass boundaries — Swift edges only - -Both pass endpoints are observed from the **Swift mirror of -`$shieldedSyncIsSyncing`**, not from Rust event timestamps. - -- **Start:** false → true transition of `isSyncing`. -- **End:** true → false transition of `isSyncing`. - -Rationale: `event.syncUnixSeconds` is integer-second resolution; mixing -it with `Date()` on the Swift edge can render negative or grossly -inflated durations for sub-second steady-state passes. Using the Swift -edge for both endpoints means the Rust↔Swift latency cancels out -symmetrically. - -### S3. Live ticker - -A 1-second `Timer` lives on the `ShieldedService` and: - -- Starts on the false → true transition. -- Tick handler: updates `currentSyncElapsed = Date() − currentSyncStartedAt`. -- Stops + nils `currentSyncElapsed` on the true → false transition. - -One timer source on the service rather than a per-view source — the -view subscribes to `$currentSyncElapsed` like any other published -field. Service is `@MainActor` so timer fires on main thread already. - -### S4. Edge handling (bug-fixes from review) - -- **B1 (clock skew):** Solved by S2 — Swift-edge for both endpoints. -- **B2 (failure leaves start stamped):** `currentSyncStartedAt` is - cleared on EVERY true → false transition, regardless of whether the - emitted `ShieldedSyncEvent` reports success or failure. Same for the - ticker. -- **B3 (`switchTo(walletId:)` silently resets timing):** Documented in - `bind()`'s comment block. UI behaviour after a wallet switch is the - same as a fresh bind — the row reappears after the next pass. -- **B4 (negative or absurd duration):** Clamp to `max(0, …)` in the - view formatter; if `currentSyncStartedAt` is nil at completion (which - shouldn't happen with S2 but is defensible defence-in-depth), set - `lastSyncDuration = nil` and skip the log line. -- **B5 (re-fire of `true`):** Set `currentSyncStartedAt` only when - transitioning **from** `false`. Track the previous mirror value - inside the `.sink` to detect the edge — the existing - `syncStateCancellable` `.sink` is the right place. -- **Cooldown skip:** `result.cooldownSkip == true` events do NOT update - `lastSyncDuration` (zeros are not signal). The ticker stops on the - edge regardless. No noisy log spam: emit the cooldown-skip log only - on the first one in a row; suppress contiguous skips. - -### S5. Console log - -In `handleShieldedSyncEvent`, when `result.success && !result.cooldownSkip`, -emit one line via `SDKLogger.log(.medium)`: - -``` -Shielded sync done pass= elapsed= rate= scanned= new= spent= balance= -``` - -- `.medium` (not `.high`) so devnet operators on default presets see - these without changing log settings. -- `rate` is suppressed when `elapsed ≈ 0` or `scanned == 0`. -- Format kept stable for `xcrun simctl spawn log` scraping. - -Skipped (cooldown) passes log a single `"Shielded sync skipped (cooldown)"` -at `.medium`; contiguous skips suppressed. - -Started passes log `"Shielded sync started"` at `.medium` on the -false → true edge. Paired with the "done" line for offline analysis. - -### S6. UI - -Inside the existing "ZK Shielded Sync Status" section, immediately -under the existing "Queries Since Launch" row (and above the badges): - -**While `isSyncing` is true AND `currentSyncElapsed != nil`:** -``` -Syncing… elapsed: 4.2 s -``` - -**While `isSyncing` is false AND `lastSyncDuration != nil`:** -``` -Last sync duration: 12.4 s -``` - -**Otherwise:** no row (clean state pre-first-sync, matches existing -"Not synced yet" behaviour). - -Layout: same `HStack { Text(label) ; Spacer() ; Text(value).monospacedDigit() }` -pattern as the surrounding rows. Mono digits keep the number readable -as it ticks. - -The existing `ProgressView()` + "Syncing..." spinner stays unchanged — -it's the qualitative "is something happening" affordance; the new row -is the quantitative "how long has it been going" affordance. - -### S7. Reset sites - -All three private/published fields nil'd in: -- `bind()` — before the new bind runs (so post-bind sync gets a clean - baseline, not stale from a prior wallet). -- `reset()` — full teardown. -- `clearLocalState` — global clear. -- True → false edge — both `currentSyncStartedAt` and - `currentSyncElapsed` nil'd (S4). - -### S8. What this does NOT change - -- No new FFI signatures. -- No changes to `rs-platform-wallet-ffi` or `rs-platform-wallet`. -- No changes to `PlatformWalletManager`. -- No SwiftData schema change. -- No new view / screen / sheet / menu entry. - -## Known limitation: catch-up vs per-pass - -At N=1M, the manager loop runs MANY internal passes during initial -catch-up — each is one `ShieldedSyncEvent`. We measure **per-pass** -wall-clock. The user-facing reality is that for an initial catch-up -the "Last sync duration" they see at the end will be the **last -pass**'s time (likely a few seconds — the trailing partial chunk), -NOT the whole catch-up's 10 minutes. - -This is acceptable for the live use case (the live ticker covers the -"is it alive" question), but means the post-hoc number reads smaller -than the user's perceived wall-clock for the first catch-up. The -**console log** mitigates by recording every pass — sum from the log -to get total catch-up time. - -A proper "catch-up completed" signal would require either: -- A Rust-side signal `next_start_index == tree_size` exposed as a - derived `isCaughtUp` event, OR -- Synthesizing it Swift-side from `event.totalScanned` + a tree-size - read. - -Both expand the scope materially. Deferred. The current per-pass -number + live ticker covers the primary use case ("is it alive, how -long is each pass taking"). - -## Architecture conformance (`swift-sdk/CLAUDE.md`) - -- ✅ Persist / load / bridge only. Timing fields are display state - derived from existing Combine publishers — no business logic, no - decisions, no orchestration. -- ✅ No new FFI surface. -- ✅ Timer is a UI-driving mechanism, not a policy loop. The decision - to keep syncing lives on the Rust side; the timer just animates - `currentSyncElapsed` for the view. - -## Test plan - -1. **Smoke (local dashmate devnet):** - - Bind a wallet; observe one sync pass. - - UI shows "Syncing… elapsed: X.Xs" with X ticking visibly. - - On completion: UI shows "Last sync duration: Y.Ys" with Y a - reasonable positive value. - - Console: paired "started" + "done" log lines at `.medium`. - -2. **Reset / clear behaviour:** - - After a successful sync, hit "Clear". UI row disappears. - - Hit "Sync Now". Row reappears live, then settles to post-hoc. - -3. **Cooldown skip:** - - After steady-state, force a cooldown-skip pass. UI does not - update `lastSyncDuration` (stays at the prior value). Console - shows one "skipped (cooldown)" line and no further skips until - the next real pass. - -4. **Failure path (offline):** - - Disconnect the gateway, hit Sync Now. Confirm `lastSyncDuration` - is NOT updated by the failed pass. `currentSyncStartedAt` IS - cleared (verified indirectly: next successful pass shows correct - duration, not absurdly inflated). - -5. **N=1M devnet (validation):** point the app at - `dashpay/drive:3.1-shielded.2` running on devnet. Bind a fresh - wallet: - - Live ticker increments visibly through the long initial pass. - - At the end, console log lines sum to the user-perceived wall-clock. - - Each subsequent pass shows a small (seconds) duration. - -## File touch list - -### Surface 1 (timing, permanent) - -- `packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Services/ShieldedService.swift` - - +1 private field (`currentSyncStartedAt`), +2 `@Published` - fields (`lastSyncDuration`, `currentSyncElapsed`). - - +1 Timer (`syncTickTimer: Timer?`). - - +1 previous-mirror state on the existing `syncStateCancellable.sink` - to detect false → true edges. - - Reset sites (`bind`, `reset`, `clearLocalState`) get the new - fields nil'd. - - `handleShieldedSyncEvent` logs at `.medium` on success path; - cooldown-skip path emits one suppressed log + leaves duration - alone. -- `packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/CoreContentView.swift` - - +1 inline row in the existing "ZK Shielded Sync Status" section - (≈ line 439 area, alongside "Queries Since Launch"). - -### Surface 2 (raw-seed test wallet bind, TEMPORARY) - -All marked with the same removal TODO tag. - -- `packages/rs-platform-wallet-ffi/src/shielded_sync.rs` - - +1 new FFI entry - `platform_wallet_manager_bind_shielded_with_raw_seed` - alongside the existing `platform_wallet_manager_bind_shielded`. - Same parameters EXCEPT replaces `mnemonic_resolver_handle` with - `seed_bytes: *const u8 + seed_len: usize`. -- `packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedBind.swift` (or wherever `bindShielded` lives) - - +1 thin wrapper method - `bindShieldedRawSeed(walletId:rawSeed:accounts:)` that calls - the new FFI. -- `packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/CoreContentView.swift` - - +1 button "Bind Test Wallet A (Shielded)" inside the ZK - Shielded Sync Status section. Hardcodes `[0x73; 32]` and calls - the new wrapper. Button is visible only when the active wallet - has no shielded binding (matches the existing "Sync Now" - affordance's gating). - -### Diff size estimate - -- Surface 1 (timing): ~60 lines additive. -- Surface 2 (raw-seed test wallet): ~70 lines additive. -- Total: ~130 lines, no removals, no API drift to existing - functionality.