From cbf718d13c9f93449a69b555c49bbfdf96b23af8 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 27 Sep 2026 18:47:48 +0700 Subject: [PATCH 1/3] docs: remove working specs committed under docs/dashpay and docs/sdk CLAUDE.md: a spec, plan or design doc written to drive a change is a working artifact that is never committed, and one that was committed is removed. Twenty such files were committed in July (implementation specs, migration leftovers, a code review log, a PR hardening plan). Remove them; the one fact code comments still pointed at (why a private key in an auto-accept QR is acceptable) moves into the comment, the other pointers are dropped, and the Kotlin workflow no longer watches a deleted path. INTEROP_DESK_CHECK.md stays: it records why it is kept. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/kotlin-sdk-build.yml | 1 - docs/dashpay/BLOCK_SPEC.md | 107 -- docs/dashpay/CONTACTINFO_FORMAT_SPEC.md | 306 ---- .../DASHPAY_STATE_ENCAPSULATION_SPEC.md | 463 ------ docs/dashpay/DIP15_INVITATIONS_SPEC.md | 835 ---------- docs/dashpay/DIP_CONFORMANCE_GAPS.md | 359 ----- .../IDENTITY_KEY_SCALAR_ELIMINATION_SPEC.md | 493 ------ docs/dashpay/INTEROP_DESK_CHECK.md | 4 +- docs/dashpay/KOTLIN_INVITATIONS_SPEC.md | 442 ------ .../KOTLIN_MIGRATION_FOLLOWUPS_SPEC.md | 219 --- docs/dashpay/KOTLIN_MIGRATION_LEFTOVERS.md | 98 -- docs/dashpay/KOTLIN_MIGRATION_SPEC.md | 441 ------ docs/dashpay/MULTI_ACCOUNT_SPEC.md | 330 ---- .../PENDING_CONTACT_CRYPTO_RELOCATION_SPEC.md | 188 --- docs/dashpay/QA_TESTCASES_SPEC.md | 225 --- docs/dashpay/QR_AUTO_ACCEPT_SPEC.md | 270 ---- docs/dashpay/SIGNER_SEED_ELIMINATION_SPEC.md | 666 -------- docs/dashpay/SPEC.md | 1362 ----------------- docs/dashpay/SYNC_CORRECTNESS_SPEC.md | 441 ------ docs/sdk/CODE_REVIEW_NOTES.md | 214 --- docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md | 705 --------- .../PR3999_WALLET_LIFECYCLE_HARDENING_SPEC.md | 652 -------- .../kotlin-sdk/KotlinExampleApp/TEST_PLAN.md | 2 +- .../wallet/DashPayUnlockAndSyncTest.kt | 2 +- .../wallet/WalletManagerRoundTripTest.kt | 2 +- .../src/wallet/identity/crypto/auto_accept.rs | 7 +- .../src/wallet/identity/network/invitation.rs | 1 - 27 files changed, 10 insertions(+), 8825 deletions(-) delete mode 100644 docs/dashpay/BLOCK_SPEC.md delete mode 100644 docs/dashpay/CONTACTINFO_FORMAT_SPEC.md delete mode 100644 docs/dashpay/DASHPAY_STATE_ENCAPSULATION_SPEC.md delete mode 100644 docs/dashpay/DIP15_INVITATIONS_SPEC.md delete mode 100644 docs/dashpay/DIP_CONFORMANCE_GAPS.md delete mode 100644 docs/dashpay/IDENTITY_KEY_SCALAR_ELIMINATION_SPEC.md delete mode 100644 docs/dashpay/KOTLIN_INVITATIONS_SPEC.md delete mode 100644 docs/dashpay/KOTLIN_MIGRATION_FOLLOWUPS_SPEC.md delete mode 100644 docs/dashpay/KOTLIN_MIGRATION_LEFTOVERS.md delete mode 100644 docs/dashpay/KOTLIN_MIGRATION_SPEC.md delete mode 100644 docs/dashpay/MULTI_ACCOUNT_SPEC.md delete mode 100644 docs/dashpay/PENDING_CONTACT_CRYPTO_RELOCATION_SPEC.md delete mode 100644 docs/dashpay/QA_TESTCASES_SPEC.md delete mode 100644 docs/dashpay/QR_AUTO_ACCEPT_SPEC.md delete mode 100644 docs/dashpay/SIGNER_SEED_ELIMINATION_SPEC.md delete mode 100644 docs/dashpay/SPEC.md delete mode 100644 docs/dashpay/SYNC_CORRECTNESS_SPEC.md delete mode 100644 docs/sdk/CODE_REVIEW_NOTES.md delete mode 100644 docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md delete mode 100644 docs/sdk/PR3999_WALLET_LIFECYCLE_HARDENING_SPEC.md 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/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..1a09b788b64 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, 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/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md b/packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md index 13784fd4003..83afece9044 100644 --- a/packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md +++ b/packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md @@ -333,7 +333,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/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/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; From 9ebf988f0e92310b17507f47e8263be2e00d605f Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Mon, 28 Sep 2026 06:04:16 +0700 Subject: [PATCH 2/3] docs: keep the durable facts from the removed specs The specs removed in the previous commit held rationale that existed nowhere else. It now sits next to the code it explains: - invitation threat model on the invitation codec - why multi-account contacts stay deferred on newest_received_per_sender (and that function's doc, which sat above SYNC_OVERLAP_MS, moves back onto it) - ignore stays local, and how a cross-device ignore must work, on ignore_contact_sender and the DashPay contract README - count proofs are public, in the book's count-tree chapter - profile sync privacy cost and why it refetches by time window - avatar fingerprints compare by Hamming distance - when the legacy Keychain signer fallback may be removed - what the iOS Keychain protection does and does not guarantee, and why the two signer handles stay separate - Kotlin parity manifest rules, native-binding test limits, and the Compose handle rule in the Kotlin CLAUDE.md - Room's power-loss residual on DashDatabase.create - two manual QA checks in the Android test plan - a dated addendum and the reference-client anchors in the interop desk check Co-Authored-By: Claude Opus 5.5 --- book/src/drive/document-count-trees.md | 4 ++ docs/dashpay/INTEROP_DESK_CHECK.md | 45 ++++++++++++++++ packages/dashpay-contract/README.md | 5 ++ packages/kotlin-sdk/CLAUDE.md | 26 +++++++++ .../kotlin-sdk/KotlinExampleApp/TEST_PLAN.md | 3 +- .../dashsdk/persistence/DashDatabase.kt | 7 +++ .../src/wallet/identity/crypto/invitation.rs | 27 +++++++++- .../identity/network/contact_requests.rs | 54 ++++++++++++++----- .../src/wallet/identity/network/profile.rs | 11 ++++ .../wallet/identity/types/dashpay/profile.rs | 6 +++ packages/swift-sdk/CLAUDE.md | 16 ++++++ .../Core/Wallet/WalletStorage.swift | 11 ++++ .../SwiftDashSDK/FFI/KeychainSigner.swift | 12 +++++ 13 files changed, 213 insertions(+), 14 deletions(-) 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/INTEROP_DESK_CHECK.md b/docs/dashpay/INTEROP_DESK_CHECK.md index 1a09b788b64..4a42145d843 100644 --- a/docs/dashpay/INTEROP_DESK_CHECK.md +++ b/docs/dashpay/INTEROP_DESK_CHECK.md @@ -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/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 83afece9044..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` 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/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/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/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, From f0a37f858cf9ac7294ec89df6d6d74683c3fefce Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Mon, 28 Sep 2026 06:04:27 +0700 Subject: [PATCH 3/3] docs: remove the committed platform-wallet and shielded-sync plans packages/rs-platform-wallet/PLAN.md, PERSISTENCE_REDESIGN.md, docs/DASHPAY_MIGRATION_PLAN.md and the SwiftExampleApp shielded-sync-timing spec were working plans. Their designs shipped or were replaced, and the code now documents itself in more detail. The few facts found nowhere else move next to the code: - why WalletManager has no per-wallet locks (a 7x SPV slowdown), on the WalletEvent adapter - why tokens need a watch list (no query lists an identity's tokens), on IdentitySyncManager - DashPay contact pools use key-wallet's gap of 20, not DIP-15's 10, on DEFAULT_CONTACT_GAP_LIMIT - what each IdentityStatus variant means and which the library sets - why the shielded sync timer uses Swift Date() at both edges Comments that pointed at the plans lose the pointer or the plan label, and docs that contradicted the code are corrected: apply_changeset drops cs.core rather than replaying it (so ApplyError::CoreApply is never built), TokenWallet no longer exists, and a cold shielded sync of 1M notes takes about 20 minutes, not 10. Co-Authored-By: Claude Opus 5.5 --- .../PERSISTENCE_REDESIGN.md | 1017 ---- packages/rs-platform-wallet/PLAN.md | 5247 ----------------- .../docs/DASHPAY_MIGRATION_PLAN.md | 257 - .../src/changeset/core_bridge.rs | 8 + .../src/changeset/traits.rs | 6 +- .../src/manager/identity_sync.rs | 13 +- .../rs-platform-wallet/src/wallet/apply.rs | 26 +- .../src/wallet/identity/crypto/dip14.rs | 6 + .../src/wallet/identity/network/payments.rs | 8 +- .../src/wallet/identity/types/key_storage.rs | 13 + .../Core/Services/ShieldedService.swift | 9 +- .../Core/Views/CoreContentView.swift | 3 +- .../docs/shielded-sync-timing-spec.md | 353 -- 13 files changed, 63 insertions(+), 6903 deletions(-) delete mode 100644 packages/rs-platform-wallet/PERSISTENCE_REDESIGN.md delete mode 100644 packages/rs-platform-wallet/PLAN.md delete mode 100644 packages/rs-platform-wallet/docs/DASHPAY_MIGRATION_PLAN.md delete mode 100644 packages/swift-sdk/SwiftExampleApp/docs/shielded-sync-timing-spec.md 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/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/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/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/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.