Wire iOS managed identity top-up from asset lock + converge the 3 top-up paths (v4.1-dev) #4092

Summary

Converge identity top-up from an asset lock onto a single managed path used by both iOS and Android, and wire it on iOS (currently unimplemented). Land it as a standalone PR against v4.1-dev so the shared, iOS-affecting change is reviewed on its own rather than buried inside the large Kotlin-SDK PR (#3999).

Background — three fragmented paths today

There are currently three ways to top up an identity from a Core asset lock, at different layers, and none is shared:

The DPP-SDK primitive is IS-only (registration has both ..._with_instant_lock and ..._with_chain_lock; top-up only ever got the IS variant) and pushes all asset-lock creation / funding / proof acquisition onto the caller. The managed library orchestrator is the correct "from asset lock" abstraction.

The good news — most of the work already exists upstream

• The managed orchestrator IdentityWallet::top_up_identity_with_funding is already in v4.1-dev (packages/rs-platform-wallet/src/wallet/identity/network/registration.rs:388). It does the full lifecycle: build/resolve the asset lock, IS→CL fallback, retries, persist balance.
• iOS already uses the registration twin platform_wallet_register_identity_with_funding_signer (packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift:3598), so the managed-funding-signer pattern is proven on iOS.
• PR feat(sdk): add Kotlin SDK and KotlinExampleApp (Android port of SwiftExampleApp) #3999's top-up FFI export is a thin ~110-line wrapper over the already-upstream orchestrator (packages/rs-platform-wallet-ffi/src/identity_top_up.rs, calls .top_up_identity_with_funding(AssetLockFunding::FromWalletBalance { … })) — no reimplementation.

Current iOS state

• Direct one-call top-up: SDK method exists but is unwired — topUpIdentity() → identityTopUp() → dash_sdk_identity_topup_with_instant_lock has zero callers; the example-app catalog handler executeIdentityTopUp (packages/swift-sdk/SwiftExampleApp/.../Views/TransitionDetailView.swift:611) is a notImplemented stub (has been since feat(sdk): epic: rs-sdk-ffi and ios support #2756; old UI leaned out in refactor(swift-sdk): lean down stale app and SDK layers #3539 / chore(swift-sdk): swift and unified sdk generation rewrite #3401).
• Working today only via the two-step route: fund a platform address from an asset lock (topUpAddressFromAssetLock) → topUpIdentityFromAddresses (Addresses.swift:1263, live at AddressQueriesView.swift:2628).
• resumeIdentityWithAssetLock (ManagedPlatformWallet.swift:3656) is registration-resume, not top-up.

Proposed work (standalone PR against v4.1-dev)

1. Add the managed FFI export platform_wallet_top_up_identity_with_funding_signer to v4.1-dev (extract the ~110-line wrapper from feat(sdk): add Kotlin SDK and KotlinExampleApp (Android port of SwiftExampleApp) #3999's identity_top_up.rs; the orchestrator it wraps is already upstream).
2. Wire iOS: a Swift ManagedPlatformWallet.topUpIdentityWithFunding(...) mirroring the existing registerIdentityWithFunding, and implement the executeIdentityTopUp stub (or a dedicated Top-Up-from-Core view) to call it. Add Swift SDK + example-app UI.
3. Tests: mirror the registration-with-funding coverage (unit + the example-app flow); assert the target identity's credit balance rises by ~the funded amount, with IS→CL fallback exercised.
4. Decide whether to retire the now-redundant IS-only dash_sdk_identity_topup_with_instant_lock (unwired on iOS) or keep it as a documented low-level primitive.

Sequencing with PR #3999 (important)

• After this PR merges to v4.1-dev, rebase feat(sdk): add Kotlin SDK and KotlinExampleApp (Android port of SwiftExampleApp) #3999 and remove its duplicate copy of the export (identity_top_up.rs +110) — keep only feat(sdk): add Kotlin SDK and KotlinExampleApp (Android port of SwiftExampleApp) #3999's Android JNI/Kotlin wiring. The v4.1-dev PR owns the canonical export; otherwise the rebase produces a duplicate/conflict.

Acceptance criteria

• platform_wallet_top_up_identity_with_funding_signer exists in v4.1-dev and delegates to top_up_identity_with_funding (no reimplementation).
• iOS can top up an existing identity directly from a Core asset lock in one managed call (create lock from wallet balance, IS→CL fallback), via a wired UI — executeIdentityTopUp no longer notImplemented.
• Both iOS and Android use the same FFI export for managed Core-funded identity top-up.
• Tests cover the happy path + IS→CL fallback; existing two-step address route still works.
• Retire-or-keep decision recorded for dash_sdk_identity_topup_with_instant_lock.
• feat(sdk): add Kotlin SDK and KotlinExampleApp (Android port of SwiftExampleApp) #3999 dedup follow-up noted (drop its export copy on rebase).

References

• Orchestrator (upstream): packages/rs-platform-wallet/src/wallet/identity/network/registration.rs:388 (top_up_identity_with_funding)
• Managed export (in feat(sdk): add Kotlin SDK and KotlinExampleApp (Android port of SwiftExampleApp) #3999): packages/rs-platform-wallet-ffi/src/identity_top_up.rs (platform_wallet_top_up_identity_with_funding_signer, commit 7a1d04792f)
• iOS registration twin (pattern to mirror): packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift:3598
• iOS unwired stub: packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/TransitionDetailView.swift:611
• Raw IS-only primitive: packages/rs-sdk-ffi/src/identity/topup.rs (dash_sdk_identity_topup_with_instant_lock)
• Related: PR feat(sdk): add Kotlin SDK and KotlinExampleApp (Android port of SwiftExampleApp) #3999 (Kotlin SDK), feat(platform-wallet): dip-13 dashpay invitations #4041 (FromExistingAssetLock reclaim variant)