From 2e71a778e74754016f803e0940c18bec166ca972 Mon Sep 17 00:00:00 2001 From: HashEngineering Date: Thu, 12 Nov 2026 12:57:09 -0800 Subject: [PATCH 1/7] docs: plan DashConnect's move from kotlin-platform to the Kotlin SDK Maps every kotlin-platform call DashConnect makes to its Kotlin SDK 5.1.0-int36 replacement, or to the dashpay/platform PR it needs. The dash-st: decoder has shipped (StateTransitionParser). Contract-group reads and Platform time are still missing. Also covers key registration through addMissingKeys (kotlin-platform#43), the signer, and when the identity-key backfill from #1693 can go. Co-Authored-By: Claude Opus 5.5 --- docs/dashconnect-kotlin-sdk-migration.md | 223 +++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 docs/dashconnect-kotlin-sdk-migration.md diff --git a/docs/dashconnect-kotlin-sdk-migration.md b/docs/dashconnect-kotlin-sdk-migration.md new file mode 100644 index 0000000000..50dcf11803 --- /dev/null +++ b/docs/dashconnect-kotlin-sdk-migration.md @@ -0,0 +1,223 @@ +# DashConnect: moving from kotlin-platform to the Kotlin SDK + +Status: plan, 2026-10-28. Branch: `docs/dashconnect-sdk-migration` (based on `feat/kotlin-sdk-phase-1`). + +Updated 2026-11-12 for SDK 5.1.0-int36. `feat/kotlin-sdk-phase-1`, and so this branch, pins +`dashSdkVersion = '5.1.0-int36-20261106.165805-1'`. The `dash-st:` decoder (PR-1) ships in int36, so PR-1 is done and +the int32 backport question is settled. PR-2 and PR-3 still block. Key registration through +`BlockchainIdentity.addMissingKeys` and the identity-key backfill are now covered too. + +DashConnect v2 (merged from #1604) sends every Platform read and write through the legacy +kotlin-platform SDK (`org.dashj.platform.*`, `libsdklib.so`, dpp `5.0.1`). The new Kotlin SDK +(`org.dashfoundation.dashsdk`, `dash-sdk-android` 5.1.0-int36) is not called by any +DashConnect code. This plan moves DashConnect onto the new SDK and marks the points where +`dashpay/platform` needs a PR first. + +## Scope + +All Platform calls live in `wallet/src/de/schildbach/wallet/ui/more/connections/`: + +| File | Lines | kotlin-platform use | +|---|---|---| +| `AppConnectSession.kt` | 857 | Almost all of it: reads, writes, signer callbacks | +| `PlatformDashConnectRepository.kt` | 212 | `platform.names.getByOwnerId` for the display name | +| `AppConnectKeyState.kt`, `AppConnectGroupConsent.kt`, `AppConnectPlan.kt`, `IdentityUpdateBatches.kt` | 429 | Types only: `IdentityPublicKey`, `Identifier`, `Purpose`, `SecurityLevel`, contract bounds | + +Outside that folder, DashConnect also reaches two wallet services that sign through the old +SDK and dashj: `IdentityRepository.ensureCriticalAuthenticationKey` (key registration, see +[Key registration](#key-registration)) and `PlatformRepo.requireIdentityChainKeys` (the +identity-key backfill, see [Signing](#signing)). + +The protocol code (`protocol/`, about 840 lines: QR parsing, ECDH and AES-GCM, DIP-13 +derivation) uses dashj and BouncyCastle, not an SDK. The UI, ViewModel and grant store +(`DashConnectConfig`) use neither SDK. None of this changes. + +## Call map + +The "new SDK" column was read from the int36 AAR's class signatures (javap). Behaviour is +inferred from names and parameter names and has not been run. + +### Writes + +| Today (`AppConnectSession.kt`) | New SDK | Gap | +|---|---|---| +| `dashsdk.platformMobilePutPutIdentityUpdateSdk`: add app keys at login (:426), disable them at revoke and shared-profile revoke (`submitIdentityUpdate`, :651) | `identity.IdentityUpdates.update(walletHandle, identityId, addKeys, disableKeyIds, signerHandle)` (also `addKey`, `disableKeys`, `updateKeyLimits`) | Today the MASTER key is chosen by the caller (:418, :647); the SDK call has no key parameter. Check which key it signs with (**PR-5** if it cannot be pinned). `IdentityPubkey` already carries `ContractBounds.ContractGroup` / `SingleContract` / `SingleContractDocumentType`, `totalBudget` and `expiresAt`. | +| `dashsdk.platformMobilePutPutDocumentSdk`: login response (:553) | `documents.DocumentTransactions.create(walletHandle, ownerId, contractId, type, propertiesJson, signerHandle, maxContestFund)` | Still no `signingKeyId` in int36; today the HIGH key is chosen (:529). **PR-5** if the SDK's choice differs. | +| `dashsdk.deleteDocumentSdk`: response cleanup (:572) | `DocumentTransactions.delete(walletHandle, ownerId, contractId, type, documentId, signingKeyId, signerHandle)` | None. | +| `dashsdk.submitTokenPurchaseSdk` (:186) | `tokens.Tokens.purchase(identityId, tokenContractId, tokenPosition, amount, expectedTotalCost, signingKeyId, signerHandle)` | None. The wallet rebuilds the purchase from decoded fields, as v2 requires. | +| `IdentityRepository.ensureCriticalAuthenticationKey` (:206), which ends in `BlockchainIdentity.addMissingKeys` | `IdentityUpdates.addKey` / `update`, after the wallet's own missing-key check | See [Key registration](#key-registration). | + +### Reads + +| Today | New SDK | Gap | +|---|---|---| +| `client.getIdentity` (:84) | `queries.Identities.fetch` / `fetchPublicKeys` | None. | +| `client.getIdentityKeyRemainingBudget` (:797, :833) | `Identities.fetchKeysRemainingBudgets(identityId, keyIds)` | None. | +| `client.getCurrentContractKeyId` (:344, :539) | `Identities.fetchContractKeys(identityIds, contractId, purposes, documentTypeName)` | Probably equivalent; confirm on testnet that it returns the current proved key ID. **PR-4** if not. | +| `client.getDataContract` (:261, :271, :705, :722) | `queries.Contracts.fetch` / `fetchWithSerialization` | None. | +| `client.getProtocolVersion` (`requireProtocolVersion`, :104; called at :120, :219, :315) | `queries.SystemQueries.refreshProtocolVersion` | None. | +| `platform.documents.get` (:512) | `queries.Documents.search` / `fetch` | None. | +| `platform.names.getByOwnerId` (repository :188) | `queries.Dpns.usernames(identityId, limit)` | None. | +| `client.getContractGroup` (:266) | — | **PR-2**. int36's `queries.Groups` has only `info` / `actions` / `actionSigners`, which are for token multisig groups, not contract-group members. | +| `client.getContractGroupOwner` (:709) | — | **PR-2** | +| `client.getPlatformTime` (13 calls) | — | **PR-3**. int36's `SystemQueries` has `epochsInfo` and `refreshProtocolVersion` but no block time. | +| `dashsdk.prepareTokenPurchaseSdk` (:121, :152) | `identity.StateTransitionParser.parse(ByteArray): ParsedStateTransition` | Done in int36 (PR-1). See below. | + +`StateTransitionParser.parse` returns a `ParsedStateTransition` with `isSigned`, `complete`, +`ownerId` and `kind`. The kinds are `Batch`, `CreditTransfer`, `DataContractCreate`, +`DataContractUpdate`, `IdentityUpdate` and `Other`. `Batch.getTransitions()` returns +`ParsedBatchedTransition.Document` / `.Token`, and `Token` exposes `tokenId`, +`tokenContractPosition`, `action`, `amount`, `tokenCount`, `recipientId`, `dataContractId`, +`complete` and `details`. + +It is a parser only. The wallet still enforces the rules `prepare_token_purchase_sdk` +enforces today: unsigned, a single direct purchase, no trailing bytes (`complete`), and a +token ID that matches the request. The agreed total price has no typed field on `Token`; it +may only be in the `details` string. Check that before relying on it, and add a typed field +upstream if it is missing. + +### Signing + +Today every write passes a kotlin-platform `Signer`. Login (:392), revoke (:618) and +shared-profile revoke (:687) wrap dashj's `WalletSignerCallback`; the token purchase (:162) +signs directly with the key it finds on dashj's identity chain. Between them they sign with +the identity keys on dashj's BLOCKCHAIN_IDENTITY chain and with the per-app keys DashConnect +derives (DIP-13 sub-features 6 and 7). + +Because those signers only find keys issued on dashj's identity chain, approve (:313), +revoke (:604), purchase (:150) and `revokeSharedProfileKeys` (:683) run the identity-key +backfill before signing, through `AppConnectSession.readSigningIdentity` (:90). It calls +`PlatformRepo.requireIdentityChainKeys` (`PlatformRepo.kt:603`, which runs +`issueIdentityChainKeys`, :606, serialized by `identityChainBackfillLock`, :133). +`setupPurchaseSigningKey` (:193) reads the identity through `readIdentity` instead; its +backfill runs inside `addMissingKeys` only when keys look missing (see +[Key registration](#key-registration)). The backfill came from dash-wallet #1693, now merged into `feat/kotlin-sdk-phase-1`. An identity +the Kotlin SDK created reaches dashj without its keys issued on that chain. + +The new SDK takes a `signerHandle`. `ffi.NativeSignerBridge` is public and abstract +(`signAsync(keyData, keyType, data, requestHandle)` and `canSignWith(keyData, keyType)`). A +host-side signer is registered with `SignerNative.createSigner(bridge)` and answers with +`completeSign`. The SDK's own `KeystoreSigner` already holds the identity keys the SDK +created, so on the SDK path most of the backfill is no longer needed. It does not know +DashConnect's per-app keys. An identity update that adds a key also needs a signature from +the new key, so a custom signer must still hold the app key's private key while a login +runs. + +The backfill can be removed only once nothing signs identity keys through dashj: not +DashConnect, not key registration, and not DashPay. + +### Key registration + +`IdentityRepository.addMissingKeys` (`IdentityRepository.kt:666`) registers the missing +DashPay keys (transfer, encryption) and, for a purchase, the CRITICAL authentication key. +It reaches the old SDK's `BlockchainIdentity.addMissingKeys` (:715), an old-SDK identity +update signed through `WalletSignerCallback`. Two paths reach it: + +- DashPay's `upgradeIdentity` (:642). +- DashConnect purchase setup: `AppConnectSession.setupPurchaseSigningKey` (:193) calls + `ensureCriticalAuthenticationKey` (:197, `IdentityRepository.kt:655`). + +On the SDK path this becomes `IdentityUpdates.addKey` (or `update` for several keys at +once). The wallet decides which keys are missing itself, against the identity it has just +refetched, and builds the `IdentityPubkey`s from its own derivation. + +That also removes the race in +[kotlin-platform#43](https://github.com/dashpay/kotlin-platform/issues/43): the old SDK +refetches the identity and decides from keys not yet issued on the dashj chain, so it can +register a duplicate paid key. Today's guard is the strict backfill before the check: +`addMissingKeys` calls `requireIdentityChainKeys` only when keys look missing +(`IdentityRepository.kt:680`), then checks again. The SDK path does not need it. + +## Platform PRs needed (`dashpay/platform`) + +The wallet's base branch builds against `dash-sdk-android` 5.1.0-int36 (recipe +`HashEngineering/dash-wallet-qa` `recipes/platform/5.1.0-int36.yaml`). Each open PR below +needs to land on the line the next int build is cut from. + +| PR | What | Where to start | Status upstream | +|---|---|---|---| +| **PR-1** | The `dash-st:` state-transition decoder for Kotlin. | — | **Done.** Ships in int36 as `identity.StateTransitionParser`. The wallet still adds its own checks (see [Reads](#reads)). Open item: whether the agreed total price is exposed other than in `details`. | +| **PR-2** | Contract-group queries for Kotlin: the owner, and a proof-verified snapshot of members and administration at one block. | Port #5421 (`rs-sdk-ffi/src/group/queries/contract_group_info.rs`, Swift-only today) to `rs-unified-sdk-jni` and `queries.*`. Snapshot logic: kotlin-platform `platform-mobile/src/app_connect.rs` `fetch_contract_group_snapshot_with_sdk`, `fetch_group_members`, `fetch_contract_group_owner_with_sdk`. Server queries from #4792. | New work. No open PR. Still missing in int36. | +| **PR-3** | Platform block time. | kotlin-platform `app_connect.rs` `fetch_platform_time_with_sdk`: `Identity::fetch_with_metadata(...)` returning `metadata.time_ms`. Either expose it as `Identities.fetchWithTime` (or similar), or return response metadata from existing queries. | New work. No open PR. Still missing in int36. | +| **PR-4** (only if needed) | The current proved contract-key ID for an identity, contract and purpose. | kotlin-platform `app_connect.rs` `fetch_current_contract_key_id_with_sdk`. | Only if `Identities.fetchContractKeys` doesn't return the same thing. | +| **PR-5** (only if needed) | Let the caller choose the signing key on `IdentityUpdates.update` and `DocumentTransactions.create`. | `DocumentTransactions.delete` already takes `signingKeyId`; follow that. | Only if the SDK's own key choice is wrong for DashConnect (MASTER for identity updates, HIGH for the response document). Neither takes a key in int36. | + +PR-2 and PR-3 block the migration. PR-4 and PR-5 depend on what the checks in phase 0 find. + +## Phases + +### Phase 0: confirm the gaps (wallet, no Platform PR) + +- Check `Identities.fetchContractKeys` against `getCurrentContractKeyId` on testnet (decides PR-4). +- Check which key `IdentityUpdates.update` and `DocumentTransactions.create` sign with (decides PR-5). +- Check whether `StateTransitionParser` exposes the agreed total price other than in `details`. +- Check whether the SDK already has DIP-13 sub-feature (app key) derivation. If it does, a later step can move app-key derivation out of dashj. + +### Phase 1: Platform PRs and SDK bump + +Open PR-2 and PR-3 (and PR-4 and PR-5 if phase 0 calls for them) in `dashpay/platform` and +publish a new `dash-sdk-android` build from the 5.1 line, then bump `dashSdkVersion` and +`gradle/verification-metadata.xml`. + +### Phase 2: a seam in the wallet + +Add a `ConnectPlatform` interface covering the roughly 15 operations in the call map, with +two implementations: + +- `LegacyConnectPlatform`: today's kotlin-platform calls, moved out of `AppConnectSession` + unchanged. +- `SdkConnectPlatform`: the new SDK calls. + +`AppConnectSession` only talks to `ConnectPlatform`. Choose the implementation by cutover +state, because every new-SDK write needs the SDK `walletHandle` and the SDK wallet exists +only after the cutover. Before the cutover, writes stay on the legacy path. Unit tests run +`AppConnectSession` against a fake `ConnectPlatform`. + +### Phase 3: signer + +Add `ConnectSigner : NativeSignerBridge` for what `KeystoreSigner` cannot sign: the +DashConnect app keys (DIP-13 sub-features 6 and 7), including the new key's own signature +during login. Identity keys the SDK created are signed by `KeystoreSigner`; `ConnectSigner` +falls back to the dashj identity chain (after `requireIdentityChainKeys`) only for keys the +SDK does not hold. It keeps today's per-sign `authorize()` and `checkScope()` hooks and is +closed after each operation. + +### Phase 4: move reads, then writes + +1. Reads: identity, contracts, protocol version, documents, DPNS name, key budget, contract key ID, and the `dash-st:` decoder (`StateTransitionParser` plus the wallet's checks). +2. PR-2 and PR-3 reads: contract group, contract-group owner, Platform time. +3. Writes, smallest blast radius first: delete the response document, create it, identity update (login, then revoke), key registration (`addKey` with the wallet's own missing-key check), token purchase. + +Each step changes one `SdkConnectPlatform` method and keeps the legacy one for the +pre-cutover path. The retry, receipt and "outcome unknown" handling in +`AppConnectSession` stays as it is; only the transport changes. Map the new SDK's errors +(`DashSdkError` and others) onto the same "submitted / unknown / failed" outcomes. + +### Phase 5: remove the legacy path + +When DashConnect no longer runs before the cutover, delete `LegacyConnectPlatform` and the +`org.dashj.platform` imports from `ui/more/connections`. `libsdklib.so` stays in the APK +while DashPay (`PlatformRepo`, `PlatformSyncService` and others) still uses kotlin-platform. +The identity-key backfill (`requireIdentityChainKeys`) stays until nothing signs identity +keys through dashj. + +## Testing + +- Unit: the existing DashConnect suites against a fake `ConnectPlatform`; a `ConnectSigner` + test that signs with an app key and falls back to a seeded dashj identity chain; decoder + vectors from `wallet/test/app-connect-vectors.json` through `StateTransitionParser` plus + the wallet's checks; a key-registration test that adds nothing when the refetched + identity already has the key. +- Device (testnet, PV14): login, the Connections list, revoke, reconnect, Reset Wallet and + same-seed restore. These passed on the legacy path on 2026-10-28 (Pixel 9 emulator, + identity created by the Kotlin SDK) and must pass again on the new one. +- Token purchase has never run on a live network on either path. It needs a testnet token + with a direct-purchase price and a `dash-st:` link generator. + +## Open questions + +- Who owns PR-2 and PR-3 in `dashpay/platform`? Roman (romchornyi) has no open PR for + them; #5421 (contract-group owner, Swift) is PastaPastaPasta's. +- Should DashConnect keep running before the cutover? If not, phase 2 needs no legacy + implementation and phase 5 is immediate. If it does, its writes stay on kotlin-platform + until then, because SDK writes need the SDK `walletHandle`. From 959241deb66439311adbd2271ca564de50e525bb Mon Sep 17 00:00:00 2001 From: HashEngineering Date: Sat, 14 Nov 2026 10:00:35 -0800 Subject: [PATCH 2/7] docs: mark the dash-st: decoder as available but unverified StateTransitionParser is in the int36 AAR, but nothing has run it, and its token transition has no typed field for the agreed price. PR-1 now closes only when phase 0 shows a typed price and correct parsing of the test vectors. Co-Authored-By: Claude Opus 5.5 --- docs/dashconnect-kotlin-sdk-migration.md | 29 +++++++++++++++--------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/dashconnect-kotlin-sdk-migration.md b/docs/dashconnect-kotlin-sdk-migration.md index 50dcf11803..19651d8289 100644 --- a/docs/dashconnect-kotlin-sdk-migration.md +++ b/docs/dashconnect-kotlin-sdk-migration.md @@ -3,8 +3,11 @@ Status: plan, 2026-10-28. Branch: `docs/dashconnect-sdk-migration` (based on `feat/kotlin-sdk-phase-1`). Updated 2026-11-12 for SDK 5.1.0-int36. `feat/kotlin-sdk-phase-1`, and so this branch, pins -`dashSdkVersion = '5.1.0-int36-20261106.165805-1'`. The `dash-st:` decoder (PR-1) ships in int36, so PR-1 is done and -the int32 backport question is settled. PR-2 and PR-3 still block. Key registration through +`dashSdkVersion = '5.1.0-int36-20261106.165805-1'`. The `dash-st:` decoder (PR-1, +`StateTransitionParser` from v5.1-dev `97f51a2bb`, Rust #4273/#4584) is in the int36 AAR, so the int32 backport is +no longer needed. PR-1 is available but unverified: nobody has run it on a real `dash-st:` link or on the test +vectors, and it closes only once phase 0 shows it exposes the agreed price as a typed field and parses the vectors +correctly. PR-2 and PR-3 still block. Key registration through `BlockchainIdentity.addMissingKeys` and the identity-key backfill are now covered too. DashConnect v2 (merged from #1604) sends every Platform read and write through the legacy @@ -61,20 +64,23 @@ inferred from names and parameter names and has not been run. | `client.getContractGroup` (:266) | — | **PR-2**. int36's `queries.Groups` has only `info` / `actions` / `actionSigners`, which are for token multisig groups, not contract-group members. | | `client.getContractGroupOwner` (:709) | — | **PR-2** | | `client.getPlatformTime` (13 calls) | — | **PR-3**. int36's `SystemQueries` has `epochsInfo` and `refreshProtocolVersion` but no block time. | -| `dashsdk.prepareTokenPurchaseSdk` (:121, :152) | `identity.StateTransitionParser.parse(ByteArray): ParsedStateTransition` | Done in int36 (PR-1). See below. | +| `dashsdk.prepareTokenPurchaseSdk` (:121, :152) | `identity.StateTransitionParser.parse(ByteArray): ParsedStateTransition` | Available in int36, unverified (PR-1). No typed field for the agreed price yet. See below. | `StateTransitionParser.parse` returns a `ParsedStateTransition` with `isSigned`, `complete`, `ownerId` and `kind`. The kinds are `Batch`, `CreditTransfer`, `DataContractCreate`, `DataContractUpdate`, `IdentityUpdate` and `Other`. `Batch.getTransitions()` returns `ParsedBatchedTransition.Document` / `.Token`, and `Token` exposes `tokenId`, `tokenContractPosition`, `action`, `amount`, `tokenCount`, `recipientId`, `dataContractId`, -`complete` and `details`. +`complete` and `details`. All of this comes from the class signatures; the parser has not +been run on a real `dash-st:` link or on the vectors in `wallet/test/app-connect-vectors.json`. It is a parser only. The wallet still enforces the rules `prepare_token_purchase_sdk` enforces today: unsigned, a single direct purchase, no trailing bytes (`complete`), and a -token ID that matches the request. The agreed total price has no typed field on `Token`; it -may only be in the `details` string. Check that before relying on it, and add a typed field -upstream if it is missing. +token ID that matches the request. That is wallet work in phase 4. The agreed total price, +which `prepareTokenPurchaseSdk` returns today, has no typed field on `Token`; it may only be +in the `details` string. PR-1 closes only when the parser exposes the agreed price as a +typed field and parses the test vectors correctly. If the price is missing, PR-1 becomes a +small Platform PR that adds it. ### Signing @@ -136,13 +142,14 @@ needs to land on the line the next int build is cut from. | PR | What | Where to start | Status upstream | |---|---|---|---| -| **PR-1** | The `dash-st:` state-transition decoder for Kotlin. | — | **Done.** Ships in int36 as `identity.StateTransitionParser`. The wallet still adds its own checks (see [Reads](#reads)). Open item: whether the agreed total price is exposed other than in `details`. | +| **PR-1** | The `dash-st:` state-transition decoder for Kotlin. | `identity.StateTransitionParser` (v5.1-dev `97f51a2bb`, Rust #4273/#4584). If the price is missing, add a typed agreed-price field to `ParsedBatchedTransition.Token`. | **Available in int36, unverified.** Not yet run on a real `dash-st:` link or the test vectors. **Closes only when the parser exposes the agreed total price as a typed field and parses `wallet/test/app-connect-vectors.json` correctly** (phase 0). If the price is missing, this becomes a small Platform PR that adds it. The wallet's own checks are wallet work in phase 4 (see [Reads](#reads)). | | **PR-2** | Contract-group queries for Kotlin: the owner, and a proof-verified snapshot of members and administration at one block. | Port #5421 (`rs-sdk-ffi/src/group/queries/contract_group_info.rs`, Swift-only today) to `rs-unified-sdk-jni` and `queries.*`. Snapshot logic: kotlin-platform `platform-mobile/src/app_connect.rs` `fetch_contract_group_snapshot_with_sdk`, `fetch_group_members`, `fetch_contract_group_owner_with_sdk`. Server queries from #4792. | New work. No open PR. Still missing in int36. | | **PR-3** | Platform block time. | kotlin-platform `app_connect.rs` `fetch_platform_time_with_sdk`: `Identity::fetch_with_metadata(...)` returning `metadata.time_ms`. Either expose it as `Identities.fetchWithTime` (or similar), or return response metadata from existing queries. | New work. No open PR. Still missing in int36. | | **PR-4** (only if needed) | The current proved contract-key ID for an identity, contract and purpose. | kotlin-platform `app_connect.rs` `fetch_current_contract_key_id_with_sdk`. | Only if `Identities.fetchContractKeys` doesn't return the same thing. | | **PR-5** (only if needed) | Let the caller choose the signing key on `IdentityUpdates.update` and `DocumentTransactions.create`. | `DocumentTransactions.delete` already takes `signingKeyId`; follow that. | Only if the SDK's own key choice is wrong for DashConnect (MASTER for identity updates, HIGH for the response document). Neither takes a key in int36. | -PR-2 and PR-3 block the migration. PR-4 and PR-5 depend on what the checks in phase 0 find. +PR-2 and PR-3 block the migration. PR-1 is conditional on the phase 0 price and vector +check. PR-4 and PR-5 depend on what the other checks in phase 0 find. ## Phases @@ -150,12 +157,12 @@ PR-2 and PR-3 block the migration. PR-4 and PR-5 depend on what the checks in ph - Check `Identities.fetchContractKeys` against `getCurrentContractKeyId` on testnet (decides PR-4). - Check which key `IdentityUpdates.update` and `DocumentTransactions.create` sign with (decides PR-5). -- Check whether `StateTransitionParser` exposes the agreed total price other than in `details`. +- Run `StateTransitionParser` on a real `dash-st:` link and on the vectors in `wallet/test/app-connect-vectors.json`, and check that it exposes the agreed total price as a typed field, not only in `details` (decides PR-1). PR-1 closes only if both hold; if the price is missing, PR-1 becomes a small Platform PR that adds it. - Check whether the SDK already has DIP-13 sub-feature (app key) derivation. If it does, a later step can move app-key derivation out of dashj. ### Phase 1: Platform PRs and SDK bump -Open PR-2 and PR-3 (and PR-4 and PR-5 if phase 0 calls for them) in `dashpay/platform` and +Open PR-2 and PR-3 (and PR-1, PR-4 and PR-5 if phase 0 calls for them) in `dashpay/platform` and publish a new `dash-sdk-android` build from the 5.1 line, then bump `dashSdkVersion` and `gradle/verification-metadata.xml`. From 57df8ef28738649b3849d694199728906642e398 Mon Sep 17 00:00:00 2001 From: HashEngineering Date: Tue, 17 Nov 2026 09:07:28 -0800 Subject: [PATCH 3/7] docs: add 2026-11-17 upstream status to the DashConnect SDK plan int36 already has #5491 (fetchContractKeys returns the proved keys) and #5649 (DIP-13 connect key derivation). #5421's proved owner read shrinks PR-2 to a Kotlin binding plus the member query. PR-3 still has no PR. Also notes #5823, #5588, #5961 and #5683. Co-Authored-By: Claude Opus 5.5 --- docs/dashconnect-kotlin-sdk-migration.md | 56 +++++++++++++++++++----- 1 file changed, 44 insertions(+), 12 deletions(-) diff --git a/docs/dashconnect-kotlin-sdk-migration.md b/docs/dashconnect-kotlin-sdk-migration.md index 19651d8289..447fdd6391 100644 --- a/docs/dashconnect-kotlin-sdk-migration.md +++ b/docs/dashconnect-kotlin-sdk-migration.md @@ -10,6 +10,11 @@ vectors, and it closes only once phase 0 shows it exposes the agreed price as a correctly. PR-2 and PR-3 still block. Key registration through `BlockchainIdentity.addMissingKeys` and the identity-key backfill are now covered too. +Updated 2026-11-17 for recent `dashpay/platform` PRs (see +[Upstream status](#upstream-status-2026-11-17)). int36 is built from `v5.1-dev @ 9766bab24a` and already has +#5491 (`fetchContractKeys` returns the proved keys, so PR-4 is probably not needed) and #5649 (the SDK derives +DashConnect app keys). PR-2 shrinks to a JNI binding of #5421 plus the member query. PR-3 still has no PR. + DashConnect v2 (merged from #1604) sends every Platform read and write through the legacy kotlin-platform SDK (`org.dashj.platform.*`, `libsdklib.so`, dpp `5.0.1`). The new Kotlin SDK (`org.dashfoundation.dashsdk`, `dash-sdk-android` 5.1.0-int36) is not called by any @@ -56,13 +61,13 @@ inferred from names and parameter names and has not been run. |---|---|---| | `client.getIdentity` (:84) | `queries.Identities.fetch` / `fetchPublicKeys` | None. | | `client.getIdentityKeyRemainingBudget` (:797, :833) | `Identities.fetchKeysRemainingBudgets(identityId, keyIds)` | None. | -| `client.getCurrentContractKeyId` (:344, :539) | `Identities.fetchContractKeys(identityIds, contractId, purposes, documentTypeName)` | Probably equivalent; confirm on testnet that it returns the current proved key ID. **PR-4** if not. | +| `client.getCurrentContractKeyId` (:344, :539) | `Identities.fetchContractKeys(identityIds, contractId, purposes, documentTypeName)` | Returns the proved contract keys since #5491 (in int36; before it always returned `{}`). Probably equivalent; the phase 0 testnet check still decides it. **PR-4** only if not. | | `client.getDataContract` (:261, :271, :705, :722) | `queries.Contracts.fetch` / `fetchWithSerialization` | None. | | `client.getProtocolVersion` (`requireProtocolVersion`, :104; called at :120, :219, :315) | `queries.SystemQueries.refreshProtocolVersion` | None. | | `platform.documents.get` (:512) | `queries.Documents.search` / `fetch` | None. | | `platform.names.getByOwnerId` (repository :188) | `queries.Dpns.usernames(identityId, limit)` | None. | -| `client.getContractGroup` (:266) | — | **PR-2**. int36's `queries.Groups` has only `info` / `actions` / `actionSigners`, which are for token multisig groups, not contract-group members. | -| `client.getContractGroupOwner` (:709) | — | **PR-2** | +| `client.getContractGroup` (:266) | — | **PR-2** (member list). int36's `queries.Groups` has only `info` / `actions` / `actionSigners`, which are for token multisig groups, not contract-group members. Nothing upstream returns the group's contracts and tokens yet. | +| `client.getContractGroupOwner` (:709) | — | **PR-2** (binding only). #5421's proved `dash_sdk_contract_group_get_info` returns `{ownerId, adminIds, name?, description?}` in rs-sdk-ffi and Swift; it has no Kotlin/JNI binding. | | `client.getPlatformTime` (13 calls) | — | **PR-3**. int36's `SystemQueries` has `epochsInfo` and `refreshProtocolVersion` but no block time. | | `dashsdk.prepareTokenPurchaseSdk` (:121, :152) | `identity.StateTransitionParser.parse(ByteArray): ParsedStateTransition` | Available in int36, unverified (PR-1). No typed field for the agreed price yet. See below. | @@ -88,7 +93,10 @@ Today every write passes a kotlin-platform `Signer`. Login (:392), revoke (:618) shared-profile revoke (:687) wrap dashj's `WalletSignerCallback`; the token purchase (:162) signs directly with the key it finds on dashj's identity chain. Between them they sign with the identity keys on dashj's BLOCKCHAIN_IDENTITY chain and with the per-app keys DashConnect -derives (DIP-13 sub-features 6 and 7). +derives (DIP-13 sub-features 6 and 7). Since #5649 (in int36) the SDK can derive those app +keys too: `PlatformWalletManager.deriveConnectKey` (`ConnectSubFeature`, over +`IdentityNative.deriveConnectKeyV2WithResolver`), plus `deriveLegacyAppEncryptionKey` for the +pre-rotation path. Because those signers only find keys issued on dashj's identity chain, approve (:313), revoke (:604), purchase (:150) and `revokeSharedProfileKeys` (:683) run the identity-key @@ -134,6 +142,12 @@ register a duplicate paid key. Today's guard is the strict backfill before the c `addMissingKeys` calls `requireIdentityChainKeys` only when keys look missing (`IdentityRepository.kt:680`), then checks again. The SDK path does not need it. +Upstream, #5683 (open, v5.2-dev) makes the SDK refetch the identity before it builds an +identity update. It is the same multi-device class of problem as kotlin-platform#43, on the +SDK side: another device may have added or disabled keys since the wallet last read the +identity. The wallet's own refetch-then-check above still applies; #5683 would cover the +SDK's half once it lands. + ## Platform PRs needed (`dashpay/platform`) The wallet's base branch builds against `dash-sdk-android` 5.1.0-int36 (recipe @@ -143,22 +157,36 @@ needs to land on the line the next int build is cut from. | PR | What | Where to start | Status upstream | |---|---|---|---| | **PR-1** | The `dash-st:` state-transition decoder for Kotlin. | `identity.StateTransitionParser` (v5.1-dev `97f51a2bb`, Rust #4273/#4584). If the price is missing, add a typed agreed-price field to `ParsedBatchedTransition.Token`. | **Available in int36, unverified.** Not yet run on a real `dash-st:` link or the test vectors. **Closes only when the parser exposes the agreed total price as a typed field and parses `wallet/test/app-connect-vectors.json` correctly** (phase 0). If the price is missing, this becomes a small Platform PR that adds it. The wallet's own checks are wallet work in phase 4 (see [Reads](#reads)). | -| **PR-2** | Contract-group queries for Kotlin: the owner, and a proof-verified snapshot of members and administration at one block. | Port #5421 (`rs-sdk-ffi/src/group/queries/contract_group_info.rs`, Swift-only today) to `rs-unified-sdk-jni` and `queries.*`. Snapshot logic: kotlin-platform `platform-mobile/src/app_connect.rs` `fetch_contract_group_snapshot_with_sdk`, `fetch_group_members`, `fetch_contract_group_owner_with_sdk`. Server queries from #4792. | New work. No open PR. Still missing in int36. | +| **PR-2** | Contract-group queries for Kotlin: a binding for the owner read, plus the member query (the group's contracts and tokens, which consent needs), as a proof-verified snapshot at one block. | Bind #5421 (`rs-sdk-ffi/src/group/queries/contract_group_info.rs`, `dash_sdk_contract_group_get_info`, merged 2026-10-15, Swift-only today) in `rs-unified-sdk-jni` and `queries.*`; the owner half needs no new Rust. Snapshot logic: kotlin-platform `platform-mobile/src/app_connect.rs` `fetch_contract_group_snapshot_with_sdk`, `fetch_group_members`, `fetch_contract_group_owner_with_sdk`. Server queries from #4792. | Owner read exists in Rust (#5421) but has no Kotlin binding; the member list has nothing upstream. Now a binding plus the member query. No open PR. | | **PR-3** | Platform block time. | kotlin-platform `app_connect.rs` `fetch_platform_time_with_sdk`: `Identity::fetch_with_metadata(...)` returning `metadata.time_ms`. Either expose it as `Identities.fetchWithTime` (or similar), or return response metadata from existing queries. | New work. No open PR. Still missing in int36. | -| **PR-4** (only if needed) | The current proved contract-key ID for an identity, contract and purpose. | kotlin-platform `app_connect.rs` `fetch_current_contract_key_id_with_sdk`. | Only if `Identities.fetchContractKeys` doesn't return the same thing. | -| **PR-5** (only if needed) | Let the caller choose the signing key on `IdentityUpdates.update` and `DocumentTransactions.create`. | `DocumentTransactions.delete` already takes `signingKeyId`; follow that. | Only if the SDK's own key choice is wrong for DashConnect (MASTER for identity updates, HIGH for the response document). Neither takes a key in int36. | +| **PR-4** (only if needed) | The current proved contract-key ID for an identity, contract and purpose. | kotlin-platform `app_connect.rs` `fetch_current_contract_key_id_with_sdk`. | Probably not needed: #5491 (in int36) makes `fetchContractKeys` return the proved keys. Still decided by the phase 0 testnet check. | +| **PR-5** (only if needed) | Let the caller choose the signing key on `IdentityUpdates.update` and `DocumentTransactions.create`. | `DocumentTransactions.delete` already takes `signingKeyId`; follow that. Likely built on #5588 (open: public, protocol-14-aware signing-key selection) and #5961. | Only if the SDK's own key choice is wrong for DashConnect (MASTER for identity updates, HIGH for the response document). Neither takes a key in int36. | PR-2 and PR-3 block the migration. PR-1 is conditional on the phase 0 price and vector check. PR-4 and PR-5 depend on what the other checks in phase 0 find. +### Upstream status (2026-11-17) + +| PR | State | What it means here | +|---|---|---| +| #5491 (romchornyi) | Merged 2026-10-23, in int36 | `fetchContractKeys` returns the proved contract keys (before: always `{}`). PR-4 probably not needed; phase 0 decides. | +| #5649 (PastaPastaPasta) | Merged 2026-10-29, in int36 | `PlatformWalletManager.deriveConnectKey` / `ConnectSubFeature` (`wallet/PlatformWalletManager.kt` :651–:717) derives app keys at `m/9'/coin'/5'/'/0'/identityId'/leaf'[/purpose'/rotation']`: 6 is session authentication, 7 is app encryption with a hardened `rotation'`. `deriveLegacyAppEncryptionKey` covers the old 8-level path. Answers phase 0's derivation question; see phase 0 and phase 3. | +| #5421 (PastaPastaPasta) | Merged 2026-10-15, rs-sdk-ffi and Swift only | Proved `dash_sdk_contract_group_get_info` returns `{ownerId, adminIds, name?, description?}`. PR-2's owner half needs only a Kotlin/JNI binding. | +| #5823 (QuantumExplorer) | Merged 2026-11-10, **after** int36 (needs an SDK bump) | Proven `Sdk::state_transition_outcome` and unproven DAPI `getRecentStateTransitionStatus`. Not one of PR-1 to PR-5, but an option for `AppConnectSession`'s "outcome unknown" handling on the SDK path (see phase 4). Kotlin bindings not checked. | +| #5588 | Open, v5.2-dev | Public, protocol-14-aware signing-key selection. The likely basis for PR-5. | +| #5961 | Open, stacked on #5588 | Don't pick a budgeted or expiring key for data contract create or update. | +| #5683 | Open, v5.2-dev | Refetch the identity before building an identity update; see [Key registration](#key-registration). | +| PR-3 | Nothing | No merged or open PR for Platform block time. | +| PR-2 member list | Nothing | Nothing beyond #5421. | + ## Phases ### Phase 0: confirm the gaps (wallet, no Platform PR) -- Check `Identities.fetchContractKeys` against `getCurrentContractKeyId` on testnet (decides PR-4). +- Check `Identities.fetchContractKeys` against `getCurrentContractKeyId` on testnet (decides PR-4). Since #5491 it returns the proved keys, so PR-4 is probably not needed. - Check which key `IdentityUpdates.update` and `DocumentTransactions.create` sign with (decides PR-5). - Run `StateTransitionParser` on a real `dash-st:` link and on the vectors in `wallet/test/app-connect-vectors.json`, and check that it exposes the agreed total price as a typed field, not only in `details` (decides PR-1). PR-1 closes only if both hold; if the price is missing, PR-1 becomes a small Platform PR that adds it. -- Check whether the SDK already has DIP-13 sub-feature (app key) derivation. If it does, a later step can move app-key derivation out of dashj. +- The SDK does derive app keys (#5649, `PlatformWalletManager.deriveConnectKey`). Check instead that it derives the same keys the wallet derives today for sub-features 6 and 7, at the same rotation level, and that keys registered on the legacy (pre-rotation) path are still found through `deriveLegacyAppEncryptionKey`. If both hold, phase 3 can take app keys from the SDK. ### Phase 1: Platform PRs and SDK bump @@ -186,7 +214,8 @@ Add `ConnectSigner : NativeSignerBridge` for what `KeystoreSigner` cannot sign: DashConnect app keys (DIP-13 sub-features 6 and 7), including the new key's own signature during login. Identity keys the SDK created are signed by `KeystoreSigner`; `ConnectSigner` falls back to the dashj identity chain (after `requireIdentityChainKeys`) only for keys the -SDK does not hold. It keeps today's per-sign `authorize()` and `checkScope()` hooks and is +SDK does not hold. Once the phase 0 derivation check passes, `ConnectSigner` takes the app +keys from the SDK (`PlatformWalletManager.deriveConnectKey`, #5649) instead of dashj. It keeps today's per-sign `authorize()` and `checkScope()` hooks and is closed after each operation. ### Phase 4: move reads, then writes @@ -199,6 +228,9 @@ Each step changes one `SdkConnectPlatform` method and keeps the legacy one for t pre-cutover path. The retry, receipt and "outcome unknown" handling in `AppConnectSession` stays as it is; only the transport changes. Map the new SDK's errors (`DashSdkError` and others) onto the same "submitted / unknown / failed" outcomes. +An option after an SDK bump past int36: #5823's proven `state_transition_outcome` (or the +unproven `getRecentStateTransitionStatus`) could back the "unknown" case on the SDK path. +Its Kotlin bindings have not been checked. ### Phase 5: remove the legacy path @@ -223,8 +255,8 @@ keys through dashj. ## Open questions -- Who owns PR-2 and PR-3 in `dashpay/platform`? Roman (romchornyi) has no open PR for - them; #5421 (contract-group owner, Swift) is PastaPastaPasta's. +- Who owns PR-2 and PR-3 in `dashpay/platform`? Nobody has an open PR for them as of + 2026-11-17; #5421 (contract-group owner, rs-sdk-ffi and Swift) is PastaPastaPasta's. - Should DashConnect keep running before the cutover? If not, phase 2 needs no legacy implementation and phase 5 is immediate. If it does, its writes stay on kotlin-platform until then, because SDK writes need the SDK `walletHandle`. From 7ad77ae2c3fd54277935e8ca893313a5eccdc3af Mon Sep 17 00:00:00 2001 From: HashEngineering Date: Tue, 17 Nov 2026 09:15:25 -0800 Subject: [PATCH 4/7] docs: compare the DashConnect SDK plan with dashwallet-ios iOS (develop b2f006996, SwiftDashSDK at platform dabbec09c9) takes Platform time from the proved keys read (#5715), reads only a contract group's owner and admins (#5421), deletes loginKeyResponse by its values (#5419), and signs new app keys through a delegating signer. The remaining Platform work is mostly Kotlin bindings of that Rust: PR-3 is now a binding of #5715, PR-6 (new) binds #5419, PR-2 shrinks to #5421 if Android adopts iOS's consent model, and PR-5 is probably not needed. Co-Authored-By: Claude Opus 5.5 --- docs/dashconnect-kotlin-sdk-migration.md | 120 ++++++++++++++++++----- 1 file changed, 94 insertions(+), 26 deletions(-) diff --git a/docs/dashconnect-kotlin-sdk-migration.md b/docs/dashconnect-kotlin-sdk-migration.md index 447fdd6391..ac9d17d735 100644 --- a/docs/dashconnect-kotlin-sdk-migration.md +++ b/docs/dashconnect-kotlin-sdk-migration.md @@ -15,6 +15,13 @@ Updated 2026-11-17 for recent `dashpay/platform` PRs (see #5491 (`fetchContractKeys` returns the proved keys, so PR-4 is probably not needed) and #5649 (the SDK derives DashConnect app keys). PR-2 shrinks to a JNI binding of #5421 plus the member query. PR-3 still has no PR. +Updated 2026-11-17 again from how dashwallet-ios does DashConnect (`develop` @ `b2f006996`, SwiftDashSDK pinned +to platform `dabbec09c9`; see [How dashwallet-ios does it](#how-dashwallet-ios-does-it-2026-11-17)). The Rust for +PR-3 already exists (#5715, which returns `blockTimeMs`), so PR-3 becomes a Kotlin/JNI binding. New **PR-6**: the +response document is index-only, so it is deleted by its values (#5419), which Kotlin has no binding for. PR-2 can +shrink to the #5421 binding alone if Android adopts iOS's consent model (an open question). PR-5 is probably not +needed for the calls it named. + DashConnect v2 (merged from #1604) sends every Platform read and write through the legacy kotlin-platform SDK (`org.dashj.platform.*`, `libsdklib.so`, dpp `5.0.1`). The new Kotlin SDK (`org.dashfoundation.dashsdk`, `dash-sdk-android` 5.1.0-int36) is not called by any @@ -49,9 +56,9 @@ inferred from names and parameter names and has not been run. | Today (`AppConnectSession.kt`) | New SDK | Gap | |---|---|---| -| `dashsdk.platformMobilePutPutIdentityUpdateSdk`: add app keys at login (:426), disable them at revoke and shared-profile revoke (`submitIdentityUpdate`, :651) | `identity.IdentityUpdates.update(walletHandle, identityId, addKeys, disableKeyIds, signerHandle)` (also `addKey`, `disableKeys`, `updateKeyLimits`) | Today the MASTER key is chosen by the caller (:418, :647); the SDK call has no key parameter. Check which key it signs with (**PR-5** if it cannot be pinned). `IdentityPubkey` already carries `ContractBounds.ContractGroup` / `SingleContract` / `SingleContractDocumentType`, `totalBudget` and `expiresAt`. | -| `dashsdk.platformMobilePutPutDocumentSdk`: login response (:553) | `documents.DocumentTransactions.create(walletHandle, ownerId, contractId, type, propertiesJson, signerHandle, maxContestFund)` | Still no `signingKeyId` in int36; today the HIGH key is chosen (:529). **PR-5** if the SDK's choice differs. | -| `dashsdk.deleteDocumentSdk`: response cleanup (:572) | `DocumentTransactions.delete(walletHandle, ownerId, contractId, type, documentId, signingKeyId, signerHandle)` | None. | +| `dashsdk.platformMobilePutPutIdentityUpdateSdk`: add app keys at login (:426), disable them at revoke and shared-profile revoke (`submitIdentityUpdate`, :651) | `identity.IdentityUpdates.update(walletHandle, identityId, addKeys, disableKeyIds, signerHandle)` (also `addKey`, `disableKeys`, `updateKeyLimits`) | Today the MASTER key is chosen by the caller (:418, :647); the SDK call has no key parameter. Rust picks the MASTER key itself (`rs-platform-wallet .../network/update.rs:150`), as on iOS, so **PR-5** is probably not needed here. The new app keys must also sign: a delegating signer (phase 3). `IdentityPubkey` already carries `ContractBounds.ContractGroup` / `SingleContract` / `SingleContractDocumentType`, `totalBudget` and `expiresAt`. | +| `dashsdk.platformMobilePutPutDocumentSdk`: login response (:553) | `documents.DocumentTransactions.create(walletHandle, ownerId, contractId, type, propertiesJson, signerHandle, maxContestFund)` | Still no `signingKeyId` in int36; today the HIGH key is chosen (:529). Rust `select_document_signing_key` picks an AUTH ECDSA key at the document type's security level, and iOS relies on it, so **PR-5** is probably not needed here. | +| `dashsdk.deleteDocumentSdk`: response cleanup (:572), which passes the whole document (`doc.toNative()`) | `DocumentTransactions.delete(walletHandle, ownerId, contractId, type, documentId, signingKeyId, signerHandle)`: delete by ID only | **PR-6**. `loginKeyResponse` is index-only; iOS deletes it by its values (#5419, `platform_wallet_document_delete_by_values`), which has no Kotlin binding in int36. | | `dashsdk.submitTokenPurchaseSdk` (:186) | `tokens.Tokens.purchase(identityId, tokenContractId, tokenPosition, amount, expectedTotalCost, signingKeyId, signerHandle)` | None. The wallet rebuilds the purchase from decoded fields, as v2 requires. | | `IdentityRepository.ensureCriticalAuthenticationKey` (:206), which ends in `BlockchainIdentity.addMissingKeys` | `IdentityUpdates.addKey` / `update`, after the wallet's own missing-key check | See [Key registration](#key-registration). | @@ -66,9 +73,9 @@ inferred from names and parameter names and has not been run. | `client.getProtocolVersion` (`requireProtocolVersion`, :104; called at :120, :219, :315) | `queries.SystemQueries.refreshProtocolVersion` | None. | | `platform.documents.get` (:512) | `queries.Documents.search` / `fetch` | None. | | `platform.names.getByOwnerId` (repository :188) | `queries.Dpns.usernames(identityId, limit)` | None. | -| `client.getContractGroup` (:266) | — | **PR-2** (member list). int36's `queries.Groups` has only `info` / `actions` / `actionSigners`, which are for token multisig groups, not contract-group members. Nothing upstream returns the group's contracts and tokens yet. | +| `client.getContractGroup` (:266) | — | **PR-2** (member list). int36's `queries.Groups` has only `info` / `actions` / `actionSigners`, which are for token multisig groups, not contract-group members. Nothing upstream returns the group's contracts and tokens yet. iOS reads no member list (see [How dashwallet-ios does it](#how-dashwallet-ios-does-it-2026-11-17)). | | `client.getContractGroupOwner` (:709) | — | **PR-2** (binding only). #5421's proved `dash_sdk_contract_group_get_info` returns `{ownerId, adminIds, name?, description?}` in rs-sdk-ffi and Swift; it has no Kotlin/JNI binding. | -| `client.getPlatformTime` (13 calls) | — | **PR-3**. int36's `SystemQueries` has `epochsInfo` and `refreshProtocolVersion` but no block time. | +| `client.getPlatformTime` (13 calls) | — | **PR-3** (binding only). int36's `SystemQueries` has `epochsInfo` and `refreshProtocolVersion` but no block time. #5715's `platform_wallet_fetch_identity_public_keys` returns `blockTimeMs`, which is what iOS uses; it has no Kotlin binding. | | `dashsdk.prepareTokenPurchaseSdk` (:121, :152) | `identity.StateTransitionParser.parse(ByteArray): ParsedStateTransition` | Available in int36, unverified (PR-1). No typed field for the agreed price yet. See below. | `StateTransitionParser.parse` returns a `ParsedStateTransition` with `isSigned`, `complete`, @@ -148,6 +155,41 @@ SDK side: another device may have added or disabled keys since the wallet last r identity. The wallet's own refetch-then-check above still applies; #5683 would cover the SDK's half once it lands. +## How dashwallet-ios does it (2026-11-17) + +dashpay/dashwallet-ios `develop` @ `b2f006996` (2026-11-17), on SwiftDashSDK pinned to platform `dabbec09c9`. +Almost all of it is in `DashWallet/Sources/Models/DashConnect/PlatformDashConnectDataSource.swift` (PDS below) and +`AppConnectV2Login.swift` (V2L). Most rows come from reading the Swift and Rust code; the exceptions are marked. +The Platform PR facts (#5715 and #5419 merged and in int36's base `v5.1-dev @ 9766bab24a`, neither bound in +Kotlin) were checked against the int36 sources. + +| Operation | iOS | Kotlin int36 | +|---|---|---| +| Identity update (login, disconnect) | `ManagedPlatformWallet.updateIdentity(..., signer:)` → `platform_wallet_update_identity_with_signer` (PDS:2204-2209 login, PDS:3481-3490 disconnect). Rust picks the MASTER key (`rs-platform-wallet .../network/update.rs:150`). Wrapped in `signer.withAdditionalSigningKeys(derivedKeys)` (platform#4273) so the new app keys can sign; they are never stored. | `IdentityUpdates.update` reaches the same Rust, so MASTER is chosen the same way. `KeystoreSigner` has no `withAdditionalSigningKeys`, but `NativeSignerBridge` is public, so the wallet can write a delegating signer without an SDK change. | +| Response document create | No key ID passed; Rust `select_document_signing_key` picks AUTH ECDSA at the document type's security level. | `DocumentTransactions.create` is the same FFI. | +| Response document delete | Delete by values (`platform_wallet_document_delete_by_values`, #5419), because `loginKeyResponse` is `indexOnly` (PDS:2490-2498). The key is chosen in app code: `selectDocumentSigningKeyId` (PDS:3884-3934), enabled AUTH ECDSA, HIGH before CRITICAL, lowest ID. | Delete by ID only. Android passes the whole document to kotlin-platform `deleteDocumentSdk` today (`AppConnectSession.kt` ~:572). **New gap, PR-6.** | +| Platform time | No time endpoint. The proof-metadata block time of the keys read, `FetchedIdentityPublicKeys.blockTimeMs` (`platform_wallet_fetch_identity_public_keys`, #5715), becomes `snapshot.platformTime` (PDS:1054). It feeds request freshness, binding terms and expiry, and connection expiry. | No `blockTimeMs` anywhere; #5715 is not bound. | +| Contract group | Owner and `adminIds` only, through `dash_sdk_contract_group_get_info` (#5421). No member list. A group with admins, or whose admins can't be shown, is treated as administered (sentinel owner, V2L:49-52, PDS:725-730 and 816-823), and the sheet warns that others can add contracts the key will act in (`DashConnectPermissionText.swift:103-107`). | #5421 not bound. Android's approve sheet lists members (`VerifiedContractGroup` / `AppConnectGroupConsent`). | +| Current contract key | Raw `dash_sdk_identities_fetch_contract_keys` (PDS:4117-4126), retried up to 3 times for a lagging node. | `fetchContractKeys` wraps the same call. | +| App keys | SDK `deriveConnectKey` (sub-features 6 and 7) and `deriveLegacyAppEncryptionKey`. The rotation search is app code (V2L:496-540): rotation 0, 1, 2… until a key is not on the identity, capped at that purpose's key count, then the legacy path on testnet/devnet only. | Same SDK calls (#5649). The rotation search is wallet work. | +| Contract bounds | Not in the proved keys read. Read from iOS's persisted key rows (PDS:3727-3757). | Not in the proved keys read either; read them from the SDK's persisted rows. | +| Token purchase (`dash-st:`) | `wallet.parseStateTransition` (PDS:265-318). Accepts only a complete batch with one token DirectPurchase, checks the owner and `calculateTokenId`, reads decimals from the live contract, requires a username, then calls `tokenPurchase(..., expectedTotalCost:)` (PDS:2665-2831). `signingKeyId` is left at its default (0) and the signer picks a CRITICAL key: **inferred from the comment at PDS:2809-2811**, not from the Rust. | Matching APIs: `StateTransitionParser.parse`, `Tokens.purchase`. | +| Outcome handling | Does not use #5823. Records an intent before submit; writes have a 60 s timeout and never retry (`AppConnectWriteExecutor`). A consensus error means Refused; any other failure leads to reading again (the identity, or the response document by `appEphemeralPubKeyHash`). A failed purchase is reported `outcomeUnknown`, with no retry. | `DashSdkError.consensusError` exists, so the same design ports. | + +Takeaways: + +- The remaining Platform work is mostly Kotlin/JNI bindings of Rust that already exists: #5421 (PR-2), #5715 + (PR-3) and #5419 (PR-6). +- For identity update and document create, the SDK chooses the key, on iOS and Kotlin alike. What DashConnect needs + is a delegating signer that adds the app keys (wallet code, phase 3) and an app-chosen key for delete (which the + by-values delete takes). PR-5 is probably not needed for those calls. +- #5715 also gives a typed keys read with limits and `expired_at_proof_time`. The Swift KDoc notes that freshness + needs the SDK built with a proof-time tolerance; check that for the Android build. +- iOS's `fetchContractKeys` use supports PR-4 being unnecessary; the testnet check in phase 0 still decides it. +- Whether PR-2 needs a member query is a product decision: see [Open questions](#open-questions). +- The rotation search and the token-purchase checks are app code on iOS and will be wallet code on Android. +- iOS-style outcome handling (no #5823, no retry, read again on a non-consensus failure) ports with what int36 has. + ## Platform PRs needed (`dashpay/platform`) The wallet's base branch builds against `dash-sdk-android` 5.1.0-int36 (recipe @@ -157,13 +199,17 @@ needs to land on the line the next int build is cut from. | PR | What | Where to start | Status upstream | |---|---|---|---| | **PR-1** | The `dash-st:` state-transition decoder for Kotlin. | `identity.StateTransitionParser` (v5.1-dev `97f51a2bb`, Rust #4273/#4584). If the price is missing, add a typed agreed-price field to `ParsedBatchedTransition.Token`. | **Available in int36, unverified.** Not yet run on a real `dash-st:` link or the test vectors. **Closes only when the parser exposes the agreed total price as a typed field and parses `wallet/test/app-connect-vectors.json` correctly** (phase 0). If the price is missing, this becomes a small Platform PR that adds it. The wallet's own checks are wallet work in phase 4 (see [Reads](#reads)). | -| **PR-2** | Contract-group queries for Kotlin: a binding for the owner read, plus the member query (the group's contracts and tokens, which consent needs), as a proof-verified snapshot at one block. | Bind #5421 (`rs-sdk-ffi/src/group/queries/contract_group_info.rs`, `dash_sdk_contract_group_get_info`, merged 2026-10-15, Swift-only today) in `rs-unified-sdk-jni` and `queries.*`; the owner half needs no new Rust. Snapshot logic: kotlin-platform `platform-mobile/src/app_connect.rs` `fetch_contract_group_snapshot_with_sdk`, `fetch_group_members`, `fetch_contract_group_owner_with_sdk`. Server queries from #4792. | Owner read exists in Rust (#5421) but has no Kotlin binding; the member list has nothing upstream. Now a binding plus the member query. No open PR. | -| **PR-3** | Platform block time. | kotlin-platform `app_connect.rs` `fetch_platform_time_with_sdk`: `Identity::fetch_with_metadata(...)` returning `metadata.time_ms`. Either expose it as `Identities.fetchWithTime` (or similar), or return response metadata from existing queries. | New work. No open PR. Still missing in int36. | -| **PR-4** (only if needed) | The current proved contract-key ID for an identity, contract and purpose. | kotlin-platform `app_connect.rs` `fetch_current_contract_key_id_with_sdk`. | Probably not needed: #5491 (in int36) makes `fetchContractKeys` return the proved keys. Still decided by the phase 0 testnet check. | -| **PR-5** (only if needed) | Let the caller choose the signing key on `IdentityUpdates.update` and `DocumentTransactions.create`. | `DocumentTransactions.delete` already takes `signingKeyId`; follow that. Likely built on #5588 (open: public, protocol-14-aware signing-key selection) and #5961. | Only if the SDK's own key choice is wrong for DashConnect (MASTER for identity updates, HIGH for the response document). Neither takes a key in int36. | - -PR-2 and PR-3 block the migration. PR-1 is conditional on the phase 0 price and vector -check. PR-4 and PR-5 depend on what the other checks in phase 0 find. +| **PR-2** | Contract-group queries for Kotlin: a binding for the owner read, plus the member query (the group's contracts and tokens, which consent needs), as a proof-verified snapshot at one block. | Bind #5421 (`rs-sdk-ffi/src/group/queries/contract_group_info.rs`, `dash_sdk_contract_group_get_info`, merged 2026-10-15, Swift-only today) in `rs-unified-sdk-jni` and `queries.*`; the owner half needs no new Rust. Snapshot logic: kotlin-platform `platform-mobile/src/app_connect.rs` `fetch_contract_group_snapshot_with_sdk`, `fetch_group_members`, `fetch_contract_group_owner_with_sdk`. Server queries from #4792. | Owner read exists in Rust (#5421) but has no Kotlin binding; the member list has nothing upstream. Now a binding plus the member query. No open PR. **If Android adopts iOS's consent model** (owner and admins plus a warning, no member list), PR-2 is the #5421 binding alone; see [Open questions](#open-questions). | +| **PR-3** | Platform block time: bind #5715 in Kotlin/JNI. | #5715's `platform_wallet_fetch_identity_public_keys` returns `blockTimeMs` from the proof metadata; iOS uses it as `snapshot.platformTime` (PDS:1054). No new Rust. It also gives a typed keys read with limits and `expired_at_proof_time`. Freshness needs the SDK built with a proof-time tolerance (Swift KDoc). | Rust merged (#5715, in int36's base); no Kotlin binding. No open PR for the binding. | +| **PR-4** (only if needed) | The current proved contract-key ID for an identity, contract and purpose. | kotlin-platform `app_connect.rs` `fetch_current_contract_key_id_with_sdk`. | Probably not needed: #5491 (in int36) makes `fetchContractKeys` return the proved keys, and iOS reads the current key from the same raw call (PDS:4117-4126, up to 3 tries). Still decided by the phase 0 testnet check. | +| **PR-5** (probably not needed) | Let the caller choose the signing key on `IdentityUpdates.update` and `DocumentTransactions.create`. | If ever needed, it lands on #5588 (open: public, protocol-14-aware signing-key selection) and #5961. | Probably not needed for these two calls: Rust picks MASTER for the identity update and AUTH ECDSA at the document type's security level for create, on iOS and Kotlin alike. The real needs are a delegating signer (wallet code, phase 3) and an app-chosen key for delete (PR-6). Phase 0 still confirms the keys on testnet. | +| **PR-6** | Delete an index-only document by its values, for Kotlin: bind #5419. | #5419's `platform_wallet_document_delete_by_values` (merged, in int36's base); iOS passes the document's properties and a `signingKeyId` (PDS:2490-2498), and chooses the key in app code (`selectDocumentSigningKeyId`, PDS:3884-3934). | Rust merged; no Kotlin binding in int36. `DocumentTransactions.delete` is delete-by-ID only, so the SDK path cannot delete `loginKeyResponse` until this lands. No open PR. | + +The remaining Platform work is now mostly Kotlin/JNI bindings of Rust that already exists: +#5421 (PR-2), #5715 (PR-3) and #5419 (PR-6). PR-3 and PR-6 block the migration; PR-2 blocks +it too, as a binding alone or with the member query depending on the consent decision. PR-1 +is conditional on the phase 0 price and vector check. PR-4 and PR-5 are probably not needed +and depend on what the other checks in phase 0 find. ### Upstream status (2026-11-17) @@ -172,25 +218,29 @@ check. PR-4 and PR-5 depend on what the other checks in phase 0 find. | #5491 (romchornyi) | Merged 2026-10-23, in int36 | `fetchContractKeys` returns the proved contract keys (before: always `{}`). PR-4 probably not needed; phase 0 decides. | | #5649 (PastaPastaPasta) | Merged 2026-10-29, in int36 | `PlatformWalletManager.deriveConnectKey` / `ConnectSubFeature` (`wallet/PlatformWalletManager.kt` :651–:717) derives app keys at `m/9'/coin'/5'/'/0'/identityId'/leaf'[/purpose'/rotation']`: 6 is session authentication, 7 is app encryption with a hardened `rotation'`. `deriveLegacyAppEncryptionKey` covers the old 8-level path. Answers phase 0's derivation question; see phase 0 and phase 3. | | #5421 (PastaPastaPasta) | Merged 2026-10-15, rs-sdk-ffi and Swift only | Proved `dash_sdk_contract_group_get_info` returns `{ownerId, adminIds, name?, description?}`. PR-2's owner half needs only a Kotlin/JNI binding. | -| #5823 (QuantumExplorer) | Merged 2026-11-10, **after** int36 (needs an SDK bump) | Proven `Sdk::state_transition_outcome` and unproven DAPI `getRecentStateTransitionStatus`. Not one of PR-1 to PR-5, but an option for `AppConnectSession`'s "outcome unknown" handling on the SDK path (see phase 4). Kotlin bindings not checked. | +| #5715 | Merged, in int36's base | `platform_wallet_fetch_identity_public_keys` returns the keys and `blockTimeMs`. iOS's Platform time. PR-3 is its Kotlin binding. | +| #5419 | Merged, in int36's base | `platform_wallet_document_delete_by_values`: delete an index-only document by its values. iOS deletes `loginKeyResponse` with it. PR-6 is its Kotlin binding. | +| #5823 (QuantumExplorer) | Merged 2026-11-10, **after** int36 (needs an SDK bump) | Proven `Sdk::state_transition_outcome` and unproven DAPI `getRecentStateTransitionStatus`. Not one of the PRs above, and iOS does not use it (see phase 4). An option only. Kotlin bindings not checked. | | #5588 | Open, v5.2-dev | Public, protocol-14-aware signing-key selection. The likely basis for PR-5. | | #5961 | Open, stacked on #5588 | Don't pick a budgeted or expiring key for data contract create or update. | | #5683 | Open, v5.2-dev | Refetch the identity before building an identity update; see [Key registration](#key-registration). | -| PR-3 | Nothing | No merged or open PR for Platform block time. | -| PR-2 member list | Nothing | Nothing beyond #5421. | +| PR-3, PR-6 | Rust merged | #5715 and #5419 are merged; no open PR binds them in Kotlin. | +| PR-2 member list | Nothing | Nothing beyond #5421. iOS does without one. | ## Phases ### Phase 0: confirm the gaps (wallet, no Platform PR) - Check `Identities.fetchContractKeys` against `getCurrentContractKeyId` on testnet (decides PR-4). Since #5491 it returns the proved keys, so PR-4 is probably not needed. -- Check which key `IdentityUpdates.update` and `DocumentTransactions.create` sign with (decides PR-5). +- Check on testnet which key `IdentityUpdates.update` and `DocumentTransactions.create` sign with. From the Rust and iOS, expect MASTER for the update and an AUTH ECDSA key at the document type's security level for create, which would mean PR-5 is not needed. +- Check that a delegating `NativeSignerBridge` can add the app keys for one identity update, the way iOS's `withAdditionalSigningKeys` does (phase 3). +- Check whether Android's SDK build has the proof-time tolerance that #5715's freshness check needs (see PR-3). - Run `StateTransitionParser` on a real `dash-st:` link and on the vectors in `wallet/test/app-connect-vectors.json`, and check that it exposes the agreed total price as a typed field, not only in `details` (decides PR-1). PR-1 closes only if both hold; if the price is missing, PR-1 becomes a small Platform PR that adds it. - The SDK does derive app keys (#5649, `PlatformWalletManager.deriveConnectKey`). Check instead that it derives the same keys the wallet derives today for sub-features 6 and 7, at the same rotation level, and that keys registered on the legacy (pre-rotation) path are still found through `deriveLegacyAppEncryptionKey`. If both hold, phase 3 can take app keys from the SDK. ### Phase 1: Platform PRs and SDK bump -Open PR-2 and PR-3 (and PR-1, PR-4 and PR-5 if phase 0 calls for them) in `dashpay/platform` and +Open PR-2, PR-3 and PR-6 (and PR-1, PR-4 and PR-5 if phase 0 calls for them) in `dashpay/platform` and publish a new `dash-sdk-android` build from the 5.1 line, then bump `dashSdkVersion` and `gradle/verification-metadata.xml`. @@ -218,19 +268,32 @@ SDK does not hold. Once the phase 0 derivation check passes, `ConnectSigner` tak keys from the SDK (`PlatformWalletManager.deriveConnectKey`, #5649) instead of dashj. It keeps today's per-sign `authorize()` and `checkScope()` hooks and is closed after each operation. +`ConnectSigner` is a delegating signer, like iOS's `signer.withAdditionalSigningKeys(derivedKeys)` +(platform#4273): it answers for the app keys derived for this operation and passes every other +key to `KeystoreSigner`. The app keys are held only for the operation and never stored. +`KeystoreSigner` has no such method in int36, but `NativeSignerBridge` is public, so this +needs no SDK change. + +The rotation search is wallet code, as on iOS (V2L:496-540): derive rotation 0, 1, 2… until a +key is not on the identity, capped at that purpose's key count, then try the legacy path +(`deriveLegacyAppEncryptionKey`) on testnet and devnet only. + ### Phase 4: move reads, then writes 1. Reads: identity, contracts, protocol version, documents, DPNS name, key budget, contract key ID, and the `dash-st:` decoder (`StateTransitionParser` plus the wallet's checks). -2. PR-2 and PR-3 reads: contract group, contract-group owner, Platform time. -3. Writes, smallest blast radius first: delete the response document, create it, identity update (login, then revoke), key registration (`addKey` with the wallet's own missing-key check), token purchase. +2. PR-2 and PR-3 reads: contract group, contract-group owner, Platform time (the `blockTimeMs` of the keys read, as iOS does). Contract bounds come from the SDK's persisted key rows, not the proved keys read. +3. Writes, smallest blast radius first: delete the response document (needs PR-6: by values, with a key the wallet chooses as iOS's `selectDocumentSigningKeyId` does), create it, identity update (login, then revoke), key registration (`addKey` with the wallet's own missing-key check), token purchase. Each step changes one `SdkConnectPlatform` method and keeps the legacy one for the -pre-cutover path. The retry, receipt and "outcome unknown" handling in -`AppConnectSession` stays as it is; only the transport changes. Map the new SDK's errors -(`DashSdkError` and others) onto the same "submitted / unknown / failed" outcomes. -An option after an SDK bump past int36: #5823's proven `state_transition_outcome` (or the -unproven `getRecentStateTransitionStatus`) could back the "unknown" case on the SDK path. -Its Kotlin bindings have not been checked. +pre-cutover path. Map the new SDK's errors (`DashSdkError` and others) onto the same +"submitted / unknown / failed" outcomes. iOS shows a design that ports with int36 as it is: +record an intent before submit, a 60 s timeout per write and no retry +(`AppConnectWriteExecutor`); a consensus error (`DashSdkError.consensusError` in Kotlin) +means Refused, any other failure means read again (the identity, or the response document +by `appEphemeralPubKeyHash`), and a failed purchase is reported "outcome unknown" with no +retry. #5823's proven `state_transition_outcome` (or the unproven +`getRecentStateTransitionStatus`, after an SDK bump past int36) is not needed for that; +iOS does not use it. Its Kotlin bindings have not been checked. ### Phase 5: remove the legacy path @@ -255,8 +318,13 @@ keys through dashj. ## Open questions -- Who owns PR-2 and PR-3 in `dashpay/platform`? Nobody has an open PR for them as of +- Who owns PR-2, PR-3 and PR-6 in `dashpay/platform`? Nobody has an open PR for them as of 2026-11-17; #5421 (contract-group owner, rs-sdk-ffi and Swift) is PastaPastaPasta's. +- Contract-group consent (product decision): keep Android's member list + (`VerifiedContractGroup` / `AppConnectGroupConsent`), which needs PR-2's member query, or + adopt iOS's model: show the owner and admins only, treat a group with admins (or whose admins + can't be shown) as administered, and warn that others can add contracts the key will act in + (`DashConnectPermissionText.swift:103-107`). The second shrinks PR-2 to the #5421 binding. - Should DashConnect keep running before the cutover? If not, phase 2 needs no legacy implementation and phase 5 is immediate. If it does, its writes stay on kotlin-platform until then, because SDK writes need the SDK `walletHandle`. From 6cf97a0f2397a45a288c73eb7049ca3a82d5b077 Mon Sep 17 00:00:00 2001 From: HashEngineering Date: Tue, 17 Nov 2026 09:24:20 -0800 Subject: [PATCH 5/7] docs: record the DashConnect SDK migration decisions HashEngineering writes the Kotlin bindings for PR-2 (#5421), PR-3 (#5715) and PR-6 (#5419). Android adopts the iOS contract-group consent model: owner and admins only, with a warning, so no member query. DashConnect does not run before the cutover, so there is one SDK implementation behind a single, temporary gate, and kotlin-platform leaves ui/more/connections in the same change. Co-Authored-By: Claude Opus 5.5 --- docs/dashconnect-kotlin-sdk-migration.md | 150 ++++++++++++++--------- 1 file changed, 94 insertions(+), 56 deletions(-) diff --git a/docs/dashconnect-kotlin-sdk-migration.md b/docs/dashconnect-kotlin-sdk-migration.md index ac9d17d735..da4853a0c4 100644 --- a/docs/dashconnect-kotlin-sdk-migration.md +++ b/docs/dashconnect-kotlin-sdk-migration.md @@ -22,12 +22,35 @@ response document is index-only, so it is deleted by its values (#5419), which K shrink to the #5421 binding alone if Android adopts iOS's consent model (an open question). PR-5 is probably not needed for the calls it named. +Updated 2026-11-17 with the maintainer's answers to the three open questions (see [Decisions](#decisions-2026-11-17)). +HashEngineering writes the Kotlin/JNI bindings for PR-2 (#5421), PR-3 (#5715) and PR-6 (#5419). Android adopts +iOS's contract-group consent model, so PR-2 is the #5421 binding alone and there is no member query. DashConnect does +not run before the cutover: one SDK implementation, no legacy path, and the kotlin-platform calls go in the same +change. + DashConnect v2 (merged from #1604) sends every Platform read and write through the legacy kotlin-platform SDK (`org.dashj.platform.*`, `libsdklib.so`, dpp `5.0.1`). The new Kotlin SDK (`org.dashfoundation.dashsdk`, `dash-sdk-android` 5.1.0-int36) is not called by any DashConnect code. This plan moves DashConnect onto the new SDK and marks the points where `dashpay/platform` needs a PR first. +## Decisions (2026-11-17) + +The maintainer answered the plan's three open questions: + +1. **Bindings.** HashEngineering writes the Kotlin/JNI bindings: PR-2 (#5421), PR-3 (#5715) and PR-6 (#5419). + PR-1, PR-4 and PR-5 stay as they are; they depend on the phase 0 checks. +2. **Contract-group consent: the iOS model.** The wallet reads the group's owner and `adminIds` only (#5421). A + group with admins, or whose admins can't be read, is treated as administered, and the approve sheet warns that + others can add contracts the key will act in, as iOS does. There is no member query. Android's consent code and + approve sheet move from listing members to owner/admins plus that warning (see + [Phase 4](#phase-4-move-reads-then-writes)). +3. **DashConnect does not run before the cutover.** Before it, DashConnect is unavailable: hidden or disabled, with a + reason. There is one SDK implementation and no legacy path, and the kotlin-platform calls in + `ui/more/connections` go away in the same change that ships it. The cutover itself will eventually be removed or + greatly simplified, so this gate is temporary: it is a single check that is easy to delete (see + [Phase 2](#phase-2-one-sdk-implementation-and-the-cutover-gate)). + ## Scope All Platform calls live in `wallet/src/de/schildbach/wallet/ui/more/connections/`: @@ -73,7 +96,7 @@ inferred from names and parameter names and has not been run. | `client.getProtocolVersion` (`requireProtocolVersion`, :104; called at :120, :219, :315) | `queries.SystemQueries.refreshProtocolVersion` | None. | | `platform.documents.get` (:512) | `queries.Documents.search` / `fetch` | None. | | `platform.names.getByOwnerId` (repository :188) | `queries.Dpns.usernames(identityId, limit)` | None. | -| `client.getContractGroup` (:266) | — | **PR-2** (member list). int36's `queries.Groups` has only `info` / `actions` / `actionSigners`, which are for token multisig groups, not contract-group members. Nothing upstream returns the group's contracts and tokens yet. iOS reads no member list (see [How dashwallet-ios does it](#how-dashwallet-ios-does-it-2026-11-17)). | +| `client.getContractGroup` (:266) | The owner and `adminIds` read in the next row | **PR-2**. With the iOS consent model ([Decisions](#decisions-2026-11-17)) the wallet no longer reads the group's members; consent uses the owner and `adminIds` from #5421. | | `client.getContractGroupOwner` (:709) | — | **PR-2** (binding only). #5421's proved `dash_sdk_contract_group_get_info` returns `{ownerId, adminIds, name?, description?}` in rs-sdk-ffi and Swift; it has no Kotlin/JNI binding. | | `client.getPlatformTime` (13 calls) | — | **PR-3** (binding only). int36's `SystemQueries` has `epochsInfo` and `refreshProtocolVersion` but no block time. #5715's `platform_wallet_fetch_identity_public_keys` returns `blockTimeMs`, which is what iOS uses; it has no Kotlin binding. | | `dashsdk.prepareTokenPurchaseSdk` (:121, :152) | `identity.StateTransitionParser.parse(ByteArray): ParsedStateTransition` | Available in int36, unverified (PR-1). No typed field for the agreed price yet. See below. | @@ -119,13 +142,16 @@ The new SDK takes a `signerHandle`. `ffi.NativeSignerBridge` is public and abstr (`signAsync(keyData, keyType, data, requestHandle)` and `canSignWith(keyData, keyType)`). A host-side signer is registered with `SignerNative.createSigner(bridge)` and answers with `completeSign`. The SDK's own `KeystoreSigner` already holds the identity keys the SDK -created, so on the SDK path most of the backfill is no longer needed. It does not know +created, so DashConnect on the SDK path does not need the backfill. It does not know DashConnect's per-app keys. An identity update that adds a key also needs a signature from the new key, so a custom signer must still hold the app key's private key while a login runs. -The backfill can be removed only once nothing signs identity keys through dashj: not -DashConnect, not key registration, and not DashPay. +DashConnect stops signing through dashj in the change that ships it on the SDK, because the +kotlin-platform calls in `ui/more/connections` go away with it ([Decisions](#decisions-2026-11-17)). +From then on DashConnect does not need the backfill. The backfill itself can be removed only +once nothing else signs identity keys through dashj: DashPay still reaches it through +`addMissingKeys` (see [Key registration](#key-registration)) until that path moves too. ### Key registration @@ -169,7 +195,7 @@ Kotlin) were checked against the int36 sources. | Response document create | No key ID passed; Rust `select_document_signing_key` picks AUTH ECDSA at the document type's security level. | `DocumentTransactions.create` is the same FFI. | | Response document delete | Delete by values (`platform_wallet_document_delete_by_values`, #5419), because `loginKeyResponse` is `indexOnly` (PDS:2490-2498). The key is chosen in app code: `selectDocumentSigningKeyId` (PDS:3884-3934), enabled AUTH ECDSA, HIGH before CRITICAL, lowest ID. | Delete by ID only. Android passes the whole document to kotlin-platform `deleteDocumentSdk` today (`AppConnectSession.kt` ~:572). **New gap, PR-6.** | | Platform time | No time endpoint. The proof-metadata block time of the keys read, `FetchedIdentityPublicKeys.blockTimeMs` (`platform_wallet_fetch_identity_public_keys`, #5715), becomes `snapshot.platformTime` (PDS:1054). It feeds request freshness, binding terms and expiry, and connection expiry. | No `blockTimeMs` anywhere; #5715 is not bound. | -| Contract group | Owner and `adminIds` only, through `dash_sdk_contract_group_get_info` (#5421). No member list. A group with admins, or whose admins can't be shown, is treated as administered (sentinel owner, V2L:49-52, PDS:725-730 and 816-823), and the sheet warns that others can add contracts the key will act in (`DashConnectPermissionText.swift:103-107`). | #5421 not bound. Android's approve sheet lists members (`VerifiedContractGroup` / `AppConnectGroupConsent`). | +| Contract group | Owner and `adminIds` only, through `dash_sdk_contract_group_get_info` (#5421). No member list. A group with admins, or whose admins can't be shown, is treated as administered (sentinel owner, V2L:49-52, PDS:725-730 and 816-823), and the sheet warns that others can add contracts the key will act in (`DashConnectPermissionText.swift:103-107`). | #5421 not bound (PR-2). Android's approve sheet lists members today (`VerifiedContractGroup` / `AppConnectGroupConsent`); it moves to iOS's model ([Decisions](#decisions-2026-11-17)). | | Current contract key | Raw `dash_sdk_identities_fetch_contract_keys` (PDS:4117-4126), retried up to 3 times for a lagging node. | `fetchContractKeys` wraps the same call. | | App keys | SDK `deriveConnectKey` (sub-features 6 and 7) and `deriveLegacyAppEncryptionKey`. The rotation search is app code (V2L:496-540): rotation 0, 1, 2… until a key is not on the identity, capped at that purpose's key count, then the legacy path on testnet/devnet only. | Same SDK calls (#5649). The rotation search is wallet work. | | Contract bounds | Not in the proved keys read. Read from iOS's persisted key rows (PDS:3727-3757). | Not in the proved keys read either; read them from the SDK's persisted rows. | @@ -186,7 +212,7 @@ Takeaways: - #5715 also gives a typed keys read with limits and `expired_at_proof_time`. The Swift KDoc notes that freshness needs the SDK built with a proof-time tolerance; check that for the Android build. - iOS's `fetchContractKeys` use supports PR-4 being unnecessary; the testnet check in phase 0 still decides it. -- Whether PR-2 needs a member query is a product decision: see [Open questions](#open-questions). +- Android adopts iOS's consent model, so PR-2 needs no member query ([Decisions](#decisions-2026-11-17)). - The rotation search and the token-purchase checks are app code on iOS and will be wallet code on Android. - iOS-style outcome handling (no #5823, no retry, read again on a non-consensus failure) ports with what int36 has. @@ -196,18 +222,18 @@ The wallet's base branch builds against `dash-sdk-android` 5.1.0-int36 (recipe `HashEngineering/dash-wallet-qa` `recipes/platform/5.1.0-int36.yaml`). Each open PR below needs to land on the line the next int build is cut from. -| PR | What | Where to start | Status upstream | -|---|---|---|---| -| **PR-1** | The `dash-st:` state-transition decoder for Kotlin. | `identity.StateTransitionParser` (v5.1-dev `97f51a2bb`, Rust #4273/#4584). If the price is missing, add a typed agreed-price field to `ParsedBatchedTransition.Token`. | **Available in int36, unverified.** Not yet run on a real `dash-st:` link or the test vectors. **Closes only when the parser exposes the agreed total price as a typed field and parses `wallet/test/app-connect-vectors.json` correctly** (phase 0). If the price is missing, this becomes a small Platform PR that adds it. The wallet's own checks are wallet work in phase 4 (see [Reads](#reads)). | -| **PR-2** | Contract-group queries for Kotlin: a binding for the owner read, plus the member query (the group's contracts and tokens, which consent needs), as a proof-verified snapshot at one block. | Bind #5421 (`rs-sdk-ffi/src/group/queries/contract_group_info.rs`, `dash_sdk_contract_group_get_info`, merged 2026-10-15, Swift-only today) in `rs-unified-sdk-jni` and `queries.*`; the owner half needs no new Rust. Snapshot logic: kotlin-platform `platform-mobile/src/app_connect.rs` `fetch_contract_group_snapshot_with_sdk`, `fetch_group_members`, `fetch_contract_group_owner_with_sdk`. Server queries from #4792. | Owner read exists in Rust (#5421) but has no Kotlin binding; the member list has nothing upstream. Now a binding plus the member query. No open PR. **If Android adopts iOS's consent model** (owner and admins plus a warning, no member list), PR-2 is the #5421 binding alone; see [Open questions](#open-questions). | -| **PR-3** | Platform block time: bind #5715 in Kotlin/JNI. | #5715's `platform_wallet_fetch_identity_public_keys` returns `blockTimeMs` from the proof metadata; iOS uses it as `snapshot.platformTime` (PDS:1054). No new Rust. It also gives a typed keys read with limits and `expired_at_proof_time`. Freshness needs the SDK built with a proof-time tolerance (Swift KDoc). | Rust merged (#5715, in int36's base); no Kotlin binding. No open PR for the binding. | -| **PR-4** (only if needed) | The current proved contract-key ID for an identity, contract and purpose. | kotlin-platform `app_connect.rs` `fetch_current_contract_key_id_with_sdk`. | Probably not needed: #5491 (in int36) makes `fetchContractKeys` return the proved keys, and iOS reads the current key from the same raw call (PDS:4117-4126, up to 3 tries). Still decided by the phase 0 testnet check. | -| **PR-5** (probably not needed) | Let the caller choose the signing key on `IdentityUpdates.update` and `DocumentTransactions.create`. | If ever needed, it lands on #5588 (open: public, protocol-14-aware signing-key selection) and #5961. | Probably not needed for these two calls: Rust picks MASTER for the identity update and AUTH ECDSA at the document type's security level for create, on iOS and Kotlin alike. The real needs are a delegating signer (wallet code, phase 3) and an app-chosen key for delete (PR-6). Phase 0 still confirms the keys on testnet. | -| **PR-6** | Delete an index-only document by its values, for Kotlin: bind #5419. | #5419's `platform_wallet_document_delete_by_values` (merged, in int36's base); iOS passes the document's properties and a `signingKeyId` (PDS:2490-2498), and chooses the key in app code (`selectDocumentSigningKeyId`, PDS:3884-3934). | Rust merged; no Kotlin binding in int36. `DocumentTransactions.delete` is delete-by-ID only, so the SDK path cannot delete `loginKeyResponse` until this lands. No open PR. | +| PR | What | Owner | Where to start | Status upstream | +|---|---|---|---|---| +| **PR-1** | The `dash-st:` state-transition decoder for Kotlin. | — (depends on phase 0) | `identity.StateTransitionParser` (v5.1-dev `97f51a2bb`, Rust #4273/#4584). If the price is missing, add a typed agreed-price field to `ParsedBatchedTransition.Token`. | **Available in int36, unverified.** Not yet run on a real `dash-st:` link or the test vectors. **Closes only when the parser exposes the agreed total price as a typed field and parses `wallet/test/app-connect-vectors.json` correctly** (phase 0). If the price is missing, this becomes a small Platform PR that adds it. The wallet's own checks are wallet work in phase 4 (see [Reads](#reads)). | +| **PR-2** | Contract-group owner and admins for Kotlin: bind #5421. | HashEngineering | Bind #5421 (`rs-sdk-ffi/src/group/queries/contract_group_info.rs`, `dash_sdk_contract_group_get_info`, merged 2026-10-15, Swift-only today) in `rs-unified-sdk-jni` and `queries.*`. No new Rust. | Rust merged (#5421); no Kotlin binding. No open PR for the binding. The binding alone, since Android adopts iOS's consent model (owner and admins plus a warning, no member list; see [Decisions](#decisions-2026-11-17)). | +| **PR-3** | Platform block time: bind #5715 in Kotlin/JNI. | HashEngineering | #5715's `platform_wallet_fetch_identity_public_keys` returns `blockTimeMs` from the proof metadata; iOS uses it as `snapshot.platformTime` (PDS:1054). No new Rust. It also gives a typed keys read with limits and `expired_at_proof_time`. Freshness needs the SDK built with a proof-time tolerance (Swift KDoc). | Rust merged (#5715, in int36's base); no Kotlin binding. No open PR for the binding. | +| **PR-4** (only if needed) | The current proved contract-key ID for an identity, contract and purpose. | — (depends on phase 0) | kotlin-platform `app_connect.rs` `fetch_current_contract_key_id_with_sdk`. | Probably not needed: #5491 (in int36) makes `fetchContractKeys` return the proved keys, and iOS reads the current key from the same raw call (PDS:4117-4126, up to 3 tries). Still decided by the phase 0 testnet check. | +| **PR-5** (probably not needed) | Let the caller choose the signing key on `IdentityUpdates.update` and `DocumentTransactions.create`. | — (depends on phase 0) | If ever needed, it lands on #5588 (open: public, protocol-14-aware signing-key selection) and #5961. | Probably not needed for these two calls: Rust picks MASTER for the identity update and AUTH ECDSA at the document type's security level for create, on iOS and Kotlin alike. The real needs are a delegating signer (wallet code, phase 3) and an app-chosen key for delete (PR-6). Phase 0 still confirms the keys on testnet. | +| **PR-6** | Delete an index-only document by its values, for Kotlin: bind #5419. | HashEngineering | #5419's `platform_wallet_document_delete_by_values` (merged, in int36's base); iOS passes the document's properties and a `signingKeyId` (PDS:2490-2498), and chooses the key in app code (`selectDocumentSigningKeyId`, PDS:3884-3934). | Rust merged; no Kotlin binding in int36. `DocumentTransactions.delete` is delete-by-ID only, so the SDK path cannot delete `loginKeyResponse` until this lands. No open PR. | The remaining Platform work is now mostly Kotlin/JNI bindings of Rust that already exists: -#5421 (PR-2), #5715 (PR-3) and #5419 (PR-6). PR-3 and PR-6 block the migration; PR-2 blocks -it too, as a binding alone or with the member query depending on the consent decision. PR-1 +#5421 (PR-2), #5715 (PR-3) and #5419 (PR-6), all three written by HashEngineering. All three +block the migration. PR-1 is conditional on the phase 0 price and vector check. PR-4 and PR-5 are probably not needed and depend on what the other checks in phase 0 find. @@ -217,15 +243,14 @@ and depend on what the other checks in phase 0 find. |---|---|---| | #5491 (romchornyi) | Merged 2026-10-23, in int36 | `fetchContractKeys` returns the proved contract keys (before: always `{}`). PR-4 probably not needed; phase 0 decides. | | #5649 (PastaPastaPasta) | Merged 2026-10-29, in int36 | `PlatformWalletManager.deriveConnectKey` / `ConnectSubFeature` (`wallet/PlatformWalletManager.kt` :651–:717) derives app keys at `m/9'/coin'/5'/'/0'/identityId'/leaf'[/purpose'/rotation']`: 6 is session authentication, 7 is app encryption with a hardened `rotation'`. `deriveLegacyAppEncryptionKey` covers the old 8-level path. Answers phase 0's derivation question; see phase 0 and phase 3. | -| #5421 (PastaPastaPasta) | Merged 2026-10-15, rs-sdk-ffi and Swift only | Proved `dash_sdk_contract_group_get_info` returns `{ownerId, adminIds, name?, description?}`. PR-2's owner half needs only a Kotlin/JNI binding. | +| #5421 (PastaPastaPasta) | Merged 2026-10-15, rs-sdk-ffi and Swift only | Proved `dash_sdk_contract_group_get_info` returns `{ownerId, adminIds, name?, description?}`. PR-2 is its Kotlin/JNI binding. | | #5715 | Merged, in int36's base | `platform_wallet_fetch_identity_public_keys` returns the keys and `blockTimeMs`. iOS's Platform time. PR-3 is its Kotlin binding. | | #5419 | Merged, in int36's base | `platform_wallet_document_delete_by_values`: delete an index-only document by its values. iOS deletes `loginKeyResponse` with it. PR-6 is its Kotlin binding. | | #5823 (QuantumExplorer) | Merged 2026-11-10, **after** int36 (needs an SDK bump) | Proven `Sdk::state_transition_outcome` and unproven DAPI `getRecentStateTransitionStatus`. Not one of the PRs above, and iOS does not use it (see phase 4). An option only. Kotlin bindings not checked. | | #5588 | Open, v5.2-dev | Public, protocol-14-aware signing-key selection. The likely basis for PR-5. | | #5961 | Open, stacked on #5588 | Don't pick a budgeted or expiring key for data contract create or update. | | #5683 | Open, v5.2-dev | Refetch the identity before building an identity update; see [Key registration](#key-registration). | -| PR-3, PR-6 | Rust merged | #5715 and #5419 are merged; no open PR binds them in Kotlin. | -| PR-2 member list | Nothing | Nothing beyond #5421. iOS does without one. | +| PR-2, PR-3, PR-6 | Rust merged | #5421, #5715 and #5419 are merged; no open PR binds them in Kotlin yet. HashEngineering writes the bindings. | ## Phases @@ -234,37 +259,39 @@ and depend on what the other checks in phase 0 find. - Check `Identities.fetchContractKeys` against `getCurrentContractKeyId` on testnet (decides PR-4). Since #5491 it returns the proved keys, so PR-4 is probably not needed. - Check on testnet which key `IdentityUpdates.update` and `DocumentTransactions.create` sign with. From the Rust and iOS, expect MASTER for the update and an AUTH ECDSA key at the document type's security level for create, which would mean PR-5 is not needed. - Check that a delegating `NativeSignerBridge` can add the app keys for one identity update, the way iOS's `withAdditionalSigningKeys` does (phase 3). +- Check that after the cutover `KeystoreSigner` holds the identity keys of an identity dashj created before it, since `ConnectSigner` has no dashj fallback (phase 3). - Check whether Android's SDK build has the proof-time tolerance that #5715's freshness check needs (see PR-3). - Run `StateTransitionParser` on a real `dash-st:` link and on the vectors in `wallet/test/app-connect-vectors.json`, and check that it exposes the agreed total price as a typed field, not only in `details` (decides PR-1). PR-1 closes only if both hold; if the price is missing, PR-1 becomes a small Platform PR that adds it. - The SDK does derive app keys (#5649, `PlatformWalletManager.deriveConnectKey`). Check instead that it derives the same keys the wallet derives today for sub-features 6 and 7, at the same rotation level, and that keys registered on the legacy (pre-rotation) path are still found through `deriveLegacyAppEncryptionKey`. If both hold, phase 3 can take app keys from the SDK. ### Phase 1: Platform PRs and SDK bump -Open PR-2, PR-3 and PR-6 (and PR-1, PR-4 and PR-5 if phase 0 calls for them) in `dashpay/platform` and +Open PR-2, PR-3 and PR-6 (HashEngineering's bindings; and PR-1, PR-4 and PR-5 if phase 0 calls for them) in `dashpay/platform` and publish a new `dash-sdk-android` build from the 5.1 line, then bump `dashSdkVersion` and `gradle/verification-metadata.xml`. -### Phase 2: a seam in the wallet +### Phase 2: one SDK implementation and the cutover gate -Add a `ConnectPlatform` interface covering the roughly 15 operations in the call map, with -two implementations: +DashConnect does not run before the cutover ([Decisions](#decisions-2026-11-17)), so there is +no two-implementation seam and no `LegacyConnectPlatform`. `AppConnectSession` calls the SDK +through a `ConnectPlatform` covering the roughly 15 operations in the call map, with one +implementation, `SdkConnectPlatform`, or calls the SDK directly. If `ConnectPlatform` stays an +interface, its only reason is testing: unit tests run `AppConnectSession` against a fake. -- `LegacyConnectPlatform`: today's kotlin-platform calls, moved out of `AppConnectSession` - unchanged. -- `SdkConnectPlatform`: the new SDK calls. - -`AppConnectSession` only talks to `ConnectPlatform`. Choose the implementation by cutover -state, because every new-SDK write needs the SDK `walletHandle` and the SDK wallet exists -only after the cutover. Before the cutover, writes stay on the legacy path. Unit tests run -`AppConnectSession` against a fake `ConnectPlatform`. +Every new-SDK write needs the SDK `walletHandle`, and the SDK wallet exists only after the +cutover. Before the cutover DashConnect is unavailable: hidden or disabled, with a reason. The +cutover itself will eventually be removed or greatly simplified, so this gate is temporary. +Make it a single check in one place (`ConnectAvailability`, which already gates DashConnect on +the build and the Platform protocol version, is the natural home) that is easy to delete with +the cutover. ### Phase 3: signer Add `ConnectSigner : NativeSignerBridge` for what `KeystoreSigner` cannot sign: the DashConnect app keys (DIP-13 sub-features 6 and 7), including the new key's own signature -during login. Identity keys the SDK created are signed by `KeystoreSigner`; `ConnectSigner` -falls back to the dashj identity chain (after `requireIdentityChainKeys`) only for keys the -SDK does not hold. Once the phase 0 derivation check passes, `ConnectSigner` takes the app +during login. Identity keys are signed by `KeystoreSigner`. There is no fallback to the dashj +identity chain and no `requireIdentityChainKeys` call: DashConnect runs only after the cutover, +on the SDK alone. Once the phase 0 derivation check passes, `ConnectSigner` takes the app keys from the SDK (`PlatformWalletManager.deriveConnectKey`, #5649) instead of dashj. It keeps today's per-sign `authorize()` and `checkScope()` hooks and is closed after each operation. @@ -281,11 +308,13 @@ key is not on the identity, capped at that purpose's key count, then try the leg ### Phase 4: move reads, then writes 1. Reads: identity, contracts, protocol version, documents, DPNS name, key budget, contract key ID, and the `dash-st:` decoder (`StateTransitionParser` plus the wallet's checks). -2. PR-2 and PR-3 reads: contract group, contract-group owner, Platform time (the `blockTimeMs` of the keys read, as iOS does). Contract bounds come from the SDK's persisted key rows, not the proved keys read. -3. Writes, smallest blast radius first: delete the response document (needs PR-6: by values, with a key the wallet chooses as iOS's `selectDocumentSigningKeyId` does), create it, identity update (login, then revoke), key registration (`addKey` with the wallet's own missing-key check), token purchase. +2. PR-2 and PR-3 reads: contract-group owner and `adminIds` (#5421), Platform time (the `blockTimeMs` of the keys read, as iOS does). Contract bounds come from the SDK's persisted key rows, not the proved keys read. +3. Contract-group consent (wallet work from the consent decision): `AppConnectGroupConsent`, the `VerifiedContractGroup` usage in `AppConnectSession` and `AppConnectPlan` (including `requireGroupScopes` and the approve sheet's `consentText`), and the stored group scopes move from listing members to the owner and admins plus a warning. A group with admins, or whose admins can't be read, is treated as administered, and the sheet warns that others can add contracts the key will act in, as iOS does. The sheet change needs a design or copy decision against the Figma first (iOS's wording is `DashConnectPermissionText.swift:103-107`); see [Open questions](#open-questions). +4. Writes, smallest blast radius first: delete the response document (needs PR-6: by values, with a key the wallet chooses as iOS's `selectDocumentSigningKeyId` does), create it, identity update (login, then revoke), key registration (`addKey` with the wallet's own missing-key check), token purchase. -Each step changes one `SdkConnectPlatform` method and keeps the legacy one for the -pre-cutover path. Map the new SDK's errors (`DashSdkError` and others) onto the same +The steps are an order of work, not separate releases. There is no legacy path to keep, so +DashConnect ships on the SDK only once every call has moved, and the kotlin-platform calls +are removed in the same change (phase 5). Map the new SDK's errors (`DashSdkError` and others) onto the same "submitted / unknown / failed" outcomes. iOS shows a design that ports with int36 as it is: record an intent before submit, a 60 s timeout per write and no retry (`AppConnectWriteExecutor`); a consensus error (`DashSdkError.consensusError` in Kotlin) @@ -297,34 +326,43 @@ iOS does not use it. Its Kotlin bindings have not been checked. ### Phase 5: remove the legacy path -When DashConnect no longer runs before the cutover, delete `LegacyConnectPlatform` and the -`org.dashj.platform` imports from `ui/more/connections`. `libsdklib.so` stays in the APK -while DashPay (`PlatformRepo`, `PlatformSyncService` and others) still uses kotlin-platform. -The identity-key backfill (`requireIdentityChainKeys`) stays until nothing signs identity -keys through dashj. +This ships with phase 4, not later: DashConnect does not run before the cutover, so there is +nothing to keep. The change that moves DashConnect onto the SDK also removes the +kotlin-platform calls and the `org.dashj.platform` imports from `ui/more/connections`, +including DashConnect's call into `IdentityRepository.ensureCriticalAuthenticationKey`. +`libsdklib.so` stays in the APK while DashPay (`PlatformRepo`, `PlatformSyncService` and +others) still uses kotlin-platform. + +DashConnect then no longer needs the identity-key backfill (`requireIdentityChainKeys`). The +backfill may still be needed for DashPay, which reaches it through `addMissingKeys` +(`upgradeIdentity`), until that path moves to the SDK too. + +The cutover gate from phase 2 is deleted when the cutover itself is removed or simplified. ## Testing - Unit: the existing DashConnect suites against a fake `ConnectPlatform`; a `ConnectSigner` - test that signs with an app key and falls back to a seeded dashj identity chain; decoder + test that signs with an app key and passes identity keys to `KeystoreSigner`; decoder vectors from `wallet/test/app-connect-vectors.json` through `StateTransitionParser` plus the wallet's checks; a key-registration test that adds nothing when the refetched - identity already has the key. + identity already has the key; consent tests that a group with admins, and a group whose + admins can't be read, are both treated as administered and carry the warning; a gate test + that DashConnect is unavailable, with its reason, before the cutover. - Device (testnet, PV14): login, the Connections list, revoke, reconnect, Reset Wallet and same-seed restore. These passed on the legacy path on 2026-10-28 (Pixel 9 emulator, - identity created by the Kotlin SDK) and must pass again on the new one. + identity created by the Kotlin SDK) and must pass again on the new one, after the cutover. + Before the cutover, check that DashConnect is hidden or disabled with its reason. - Token purchase has never run on a live network on either path. It needs a testnet token with a direct-purchase price and a `dash-st:` link generator. ## Open questions -- Who owns PR-2, PR-3 and PR-6 in `dashpay/platform`? Nobody has an open PR for them as of - 2026-11-17; #5421 (contract-group owner, rs-sdk-ffi and Swift) is PastaPastaPasta's. -- Contract-group consent (product decision): keep Android's member list - (`VerifiedContractGroup` / `AppConnectGroupConsent`), which needs PR-2's member query, or - adopt iOS's model: show the owner and admins only, treat a group with admins (or whose admins - can't be shown) as administered, and warn that others can add contracts the key will act in - (`DashConnectPermissionText.swift:103-107`). The second shrinks PR-2 to the #5421 binding. -- Should DashConnect keep running before the cutover? If not, phase 2 needs no legacy - implementation and phase 5 is immediate. If it does, its writes stay on kotlin-platform - until then, because SDK writes need the SDK `walletHandle`. +The three questions of 2026-10-28 are answered (see [Decisions](#decisions-2026-11-17)). What +is left is design, not architecture: + +- The approve sheet under the iOS consent model: its layout and copy for the owner, the admins + and the "others can add contracts the key will act in" warning need a decision against the + Figma. iOS's wording is `DashConnectPermissionText.swift:103-107`; do not port it without + that decision. +- How DashConnect looks before the cutover: hidden, or disabled with a reason, and that + reason's copy. From bfe1d09b842624855fac855fe357d7c4873b3b23 Mon Sep 17 00:00:00 2001 From: HashEngineering Date: Tue, 17 Nov 2026 10:44:18 -0800 Subject: [PATCH 6/7] docs: hide DashConnect before the cutover Record the decision that DashConnect's entry points (Tools row, three scan paths, deep links) are hidden before the cutover rather than shown disabled, and drop it from the open questions. Co-Authored-By: Claude Opus 5.5 --- docs/dashconnect-kotlin-sdk-migration.md | 42 +++++++++++++++++------- 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/docs/dashconnect-kotlin-sdk-migration.md b/docs/dashconnect-kotlin-sdk-migration.md index da4853a0c4..53ecd70e43 100644 --- a/docs/dashconnect-kotlin-sdk-migration.md +++ b/docs/dashconnect-kotlin-sdk-migration.md @@ -36,7 +36,7 @@ DashConnect code. This plan moves DashConnect onto the new SDK and marks the poi ## Decisions (2026-11-17) -The maintainer answered the plan's three open questions: +The maintainer answered the plan's three open questions, and settled how DashConnect looks before the cutover: 1. **Bindings.** HashEngineering writes the Kotlin/JNI bindings: PR-2 (#5421), PR-3 (#5715) and PR-6 (#5419). PR-1, PR-4 and PR-5 stay as they are; they depend on the phase 0 checks. @@ -45,11 +45,12 @@ The maintainer answered the plan's three open questions: others can add contracts the key will act in, as iOS does. There is no member query. Android's consent code and approve sheet move from listing members to owner/admins plus that warning (see [Phase 4](#phase-4-move-reads-then-writes)). -3. **DashConnect does not run before the cutover.** Before it, DashConnect is unavailable: hidden or disabled, with a - reason. There is one SDK implementation and no legacy path, and the kotlin-platform calls in +3. **DashConnect does not run before the cutover.** There is one SDK implementation and no legacy path, and the kotlin-platform calls in `ui/more/connections` go away in the same change that ships it. The cutover itself will eventually be removed or greatly simplified, so this gate is temporary: it is a single check that is easy to delete (see [Phase 2](#phase-2-one-sdk-implementation-and-the-cutover-gate)). +4. **Before the cutover DashConnect is hidden** (decided 2026-11-17). Its entry points are hidden entirely: no + disabled row and no explanatory copy. So a pre-cutover state needs no new strings and no design. ## Scope @@ -279,11 +280,29 @@ implementation, `SdkConnectPlatform`, or calls the SDK directly. If `ConnectPlat interface, its only reason is testing: unit tests run `AppConnectSession` against a fake. Every new-SDK write needs the SDK `walletHandle`, and the SDK wallet exists only after the -cutover. Before the cutover DashConnect is unavailable: hidden or disabled, with a reason. The -cutover itself will eventually be removed or greatly simplified, so this gate is temporary. -Make it a single check in one place (`ConnectAvailability`, which already gates DashConnect on -the build and the Platform protocol version, is the natural home) that is easy to delete with -the cutover. +cutover. Before the cutover DashConnect is hidden. The cutover itself will eventually be removed +or greatly simplified, so this gate is temporary. Make it a single check in one place +(`ConnectAvailability`, which already gates DashConnect on the build and the Platform protocol +version, is the natural home) that is easy to delete with the cutover. + +The gate hides every entry point, not just the screen: + +- The Connections row in Tools (`ToolsScreen.kt:332`). It already shows only when + `ConnectAvailability.availability` is true (`ToolsViewModel.kt:189`), so the gate goes into + that value. +- Scanned DashConnect QR codes (`dash-key:`, `dash-st:`, `dashpay://connect`). Three scan paths + send them to the Connections screen: home (`WalletFragment.kt:324`), the address input + (`DashAddressInputFragment.kt:45`) and Payments' Pay (`PaymentsPayFragment.kt:163`). Each + checks `Constants.SUPPORTS_CONNECT` today; each should check the gate instead. +- Links opened from a browser or another app. The manifest routes `dash-key:`, `dash-st:` and + `dashpay://connect` to `MainActivity` (`AndroidManifest.xml:131-152`), and `handleIntent` + sends them to the Connections screen (`MainActivity.kt:546-557`). The intent filters stay, + since the manifest can't follow a runtime gate, so `handleIntent` checks it. + +Before the cutover a scanned or opened DashConnect URI is treated as unsupported, not routed +to a screen that says DashConnect is off. A scanned QR falls through to the normal +unrecognised-QR error, as it already does where the build has DashConnect off. An opened link +is ignored: the wallet opens to its home screen. ### Phase 3: signer @@ -347,11 +366,12 @@ The cutover gate from phase 2 is deleted when the cutover itself is removed or s the wallet's checks; a key-registration test that adds nothing when the refetched identity already has the key; consent tests that a group with admins, and a group whose admins can't be read, are both treated as administered and carry the warning; a gate test - that DashConnect is unavailable, with its reason, before the cutover. + that DashConnect is unavailable before the cutover. - Device (testnet, PV14): login, the Connections list, revoke, reconnect, Reset Wallet and same-seed restore. These passed on the legacy path on 2026-10-28 (Pixel 9 emulator, identity created by the Kotlin SDK) and must pass again on the new one, after the cutover. - Before the cutover, check that DashConnect is hidden or disabled with its reason. + Before the cutover, check that the Connections row is hidden, that a scanned DashConnect QR + gets the unrecognised-QR error, and that an opened DashConnect link lands on the home screen. - Token purchase has never run on a live network on either path. It needs a testnet token with a direct-purchase price and a `dash-st:` link generator. @@ -364,5 +384,3 @@ is left is design, not architecture: and the "others can add contracts the key will act in" warning need a decision against the Figma. iOS's wording is `DashConnectPermissionText.swift:103-107`; do not port it without that decision. -- How DashConnect looks before the cutover: hidden, or disabled with a reason, and that - reason's copy. From 10779e38010030b030cdc8ea6682ee89dfa6187a Mon Sep 17 00:00:00 2001 From: HashEngineering Date: Tue, 17 Nov 2026 10:48:36 -0800 Subject: [PATCH 7/7] docs: toast for DashConnect links opened before the cutover A DashConnect link opened from a browser or another app before the cutover opens the wallet and shows a not-supported toast. No existing string fits, so one new string (Figma copy) is needed; it is removed with the cutover gate. Co-Authored-By: Claude Opus 5.5 --- docs/dashconnect-kotlin-sdk-migration.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/dashconnect-kotlin-sdk-migration.md b/docs/dashconnect-kotlin-sdk-migration.md index 53ecd70e43..c03b93d6ac 100644 --- a/docs/dashconnect-kotlin-sdk-migration.md +++ b/docs/dashconnect-kotlin-sdk-migration.md @@ -50,7 +50,13 @@ The maintainer answered the plan's three open questions, and settled how DashCon greatly simplified, so this gate is temporary: it is a single check that is easy to delete (see [Phase 2](#phase-2-one-sdk-implementation-and-the-cutover-gate)). 4. **Before the cutover DashConnect is hidden** (decided 2026-11-17). Its entry points are hidden entirely: no - disabled row and no explanatory copy. So a pre-cutover state needs no new strings and no design. + disabled row and no explanatory copy. So a pre-cutover state needs no design and no new strings, with one + exception (decided 2026-11-17): a DashConnect link opened from a browser or another app shows a short toast that + the link isn't supported yet ([Phase 2](#phase-2-one-sdk-implementation-and-the-cutover-gate)). No existing + string fits: `send_coins_error_not_supported` (`wallet/res/values/strings.xml:79`) is about payments and funds, + `dash_connect_unavailable_message` (`wallet/res/values/strings_app_connect.xml:4`) gives the wrong reason, and + `invalid_link` (`wallet/res/values/strings-dashpay.xml:430`) says the link is invalid. So the toast needs one new + string in every locale, with its wording taken from the designer's Figma copy, not written by us. ## Scope @@ -302,7 +308,8 @@ The gate hides every entry point, not just the screen: Before the cutover a scanned or opened DashConnect URI is treated as unsupported, not routed to a screen that says DashConnect is off. A scanned QR falls through to the normal unrecognised-QR error, as it already does where the build has DashConnect off. An opened link -is ignored: the wallet opens to its home screen. +opens the wallet as usual and shows a short toast that the link isn't supported yet (the one +new string, see [Decisions](#decisions-2026-11-17)); it is not routed anywhere. ### Phase 3: signer @@ -356,7 +363,8 @@ DashConnect then no longer needs the identity-key backfill (`requireIdentityChai backfill may still be needed for DashPay, which reaches it through `addMissingKeys` (`upgradeIdentity`), until that path moves to the SDK too. -The cutover gate from phase 2 is deleted when the cutover itself is removed or simplified. +The cutover gate from phase 2 is deleted when the cutover itself is removed or simplified, +and the pre-cutover toast and its string go with it. ## Testing @@ -371,7 +379,7 @@ The cutover gate from phase 2 is deleted when the cutover itself is removed or s same-seed restore. These passed on the legacy path on 2026-10-28 (Pixel 9 emulator, identity created by the Kotlin SDK) and must pass again on the new one, after the cutover. Before the cutover, check that the Connections row is hidden, that a scanned DashConnect QR - gets the unrecognised-QR error, and that an opened DashConnect link lands on the home screen. + gets the unrecognised-QR error, and that an opened DashConnect link lands on the home screen and shows the not-supported toast. - Token purchase has never run on a live network on either path. It needs a testnet token with a direct-purchase price and a `dash-st:` link generator.