Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 16 additions & 5 deletions docs/sdk/sdk-parity-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@
"platform_wallet_token_update_config": "packages/rs-platform-wallet-ffi/src/tokens/update_config.rs",
"platform_wallet_top_up_external_identity_from_addresses_with_signer": "packages/rs-platform-wallet-ffi/src/identity_top_up.rs",
"platform_wallet_top_up_from_addresses_with_signer": "packages/rs-platform-wallet-ffi/src/identity_top_up.rs",
"platform_wallet_top_up_identity_from_addresses_with_signer": "packages/rs-platform-wallet-ffi/src/identity_top_up.rs",
"platform_wallet_topup_identity_with_existing_asset_lock_signer": "packages/rs-platform-wallet-ffi/src/identity_registration_funded_with_signer.rs",
"platform_wallet_tracked_asset_locks_free": "packages/rs-platform-wallet-ffi/src/manager_diagnostics.rs",
"platform_wallet_tracked_asset_locks_list": "packages/rs-platform-wallet-ffi/src/manager_diagnostics.rs",
Expand Down Expand Up @@ -1435,7 +1436,8 @@
"area": "shared_policy",
"shared_apis": [
"platform_address_wallet_addresses_with_balances",
"platform_wallet_top_up_from_addresses_with_signer"
"platform_wallet_top_up_from_addresses_with_signer",
"platform_wallet_top_up_identity_from_addresses_with_signer"
],
"required_persistence_capabilities": [],
"hosts": {
Expand Down Expand Up @@ -1474,21 +1476,22 @@
"title": "Top up an identity the wallet does not manage from Platform addresses",
"area": "correctness",
"shared_apis": [
"platform_wallet_top_up_external_identity_from_addresses_with_signer"
"platform_wallet_top_up_external_identity_from_addresses_with_signer",
"platform_wallet_top_up_identity_from_addresses_with_signer"
],
"required_persistence_capabilities": [],
"hosts": {
"swift": {
"sdk": "supported",
"example_app": "unsupported",
"restart": "not_applicable",
"reason": "ManagedPlatformWallet.topUpExternalIdentityFromAddresses bridges the export; the example app has no screen that pays to someone else's identity."
"reason": "ManagedPlatformWallet.topUpIdentityFromAddresses (and the deprecated topUpExternalIdentityFromAddresses) bridges the export; the example app has no screen that pays to someone else's identity."
},
"kotlin": {
"sdk": "unsupported",
"sdk": "supported",
"example_app": "unsupported",
"restart": "not_applicable",
"reason": "No JNI bridge or Kotlin wrapper for the external identity top-up yet."
"reason": "IdentityCredits.topUpIdentityFromAddresses bridges the export through JNI; the example app has no screen that pays to someone else's identity."
}
},
"verification": [
Expand All @@ -1499,6 +1502,14 @@
"id": "testMarshalsArgumentsAndReturnsTheBalanceTheExportWrites",
"command": "cd packages/swift-sdk && xcodebuild test -scheme SwiftDashSDK -destination 'platform=iOS Simulator,name=iPhone 17 Pro' -only-testing:SwiftDashSDKTests/ExternalIdentityTopUpTests",
"covers_restart": false
},
{
"host": "kotlin",
"kind": "unit",
"file": "packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/credits/IdentityAddressTopUpTest.kt",
"id": "top up of any identity marshals to its own bridge and returns its balance",
"command": "cd packages/kotlin-sdk && ./gradlew :sdk:testDebugUnitTest",
"covers_restart": false
}
]
},
Expand Down
2 changes: 1 addition & 1 deletion packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ Most Platform actions have hard preconditions. Establish these fixtures before s
| ID-03 | View identity (info / balance / revision / keys) | Platform | Essential | ✅ | | `IdentityDetailScreen`, `KeysListScreen`, `KeyDetailScreen`. |
| ID-04 | Transfer credits identity → identity | Platform | Essential | ✅ | | `IdentityDetailScreen` → **Transfer Credits** (dialog, `TransferCreditsScreen`) → `platform_wallet_transfer_credits_with_signer` (Keystore-signed). Recipient entered via `RecipientPicker` (local identity / paste base58 id / DPNS name). |
| ID-05 | Top up identity (asset lock) | Cross | Common | ✅ | | `IdentityDetailScreen` → **Top Up from Core** (`TopUpIdentityFromCoreScreen`) → `platform_wallet_top_up_identity_with_funding_signer`. Builds + broadcasts a new Core asset lock (same mechanism as ID-01), signed by the asset lock's Core key. |
| ID-06 | Top up identity (from Platform addresses) | Cross | Common | ✅ | | `IdentityDetailScreen` → **Top Up from Platform addresses** (`TopUpIdentityScreen`) → `platform_wallet_top_up_from_addresses_with_signer`. Requires the wallet's Platform-payment addresses to hold credits first — fund them via `WalletDetailScreen` → Platform Balance → **Top Up from Core** (`FundFromAssetLockScreen`). |
| ID-06 | Top up identity (from Platform addresses) | Cross | Common | ✅ | | `IdentityDetailScreen` → **Top Up from Platform addresses** (`TopUpIdentityScreen`) → `IdentityCredits.topUpIdentityFromAddresses` → `platform_wallet_top_up_identity_from_addresses_with_signer`. Requires the wallet's Platform-payment addresses to hold credits first — fund them via `WalletDetailScreen` → Platform Balance → **Top Up from Core** (`FundFromAssetLockScreen`). |
| ID-07 | Update identity — add public key | Platform | Common | ✅ | | `AddIdentityKeyScreen` (from `KeysListScreen`) → `updateIdentity(addPublicKeys:)`. |
| ID-08 | Create identity (from Platform addresses) | Cross | Common | ✅ | | `CreateIdentityScreen` → funding source **Platform address** → `IdentityRegistration.registerFromAddresses` → `platform_wallet_register_identity_with_signer` (Keystore-signed; one signer drives both the identity-key and platform-address roles). Derives + persists the canonical key set (as ID-01), then greedily packs the wallet's balance-carrying Platform-payment addresses; nonces auto-fetched Rust-side. Requires funded Platform addresses first (fund via `WalletDetailScreen` → Platform Balance → **Top Up from Core**). |
| ID-09 | Set / edit local alias | Platform | Common | ✅ | | `IdentityDetailScreen` (Add Alias). Local only — persists across relaunch; no broadcast. |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ import org.dashfoundation.example.util.hexToBytes
* ([org.dashfoundation.dashsdk.wallet.ManagedPlatformWallet.addressesWithBalances]),
* greedily packs them up to the requested amount (largest-balance-first,
* matching Swift's `buildInputs`), then credits the identity through
* `platform_wallet_top_up_from_addresses_with_signer`
* ([org.dashfoundation.dashsdk.credits.IdentityCredits.topUpFromAddresses]).
* `platform_wallet_top_up_identity_from_addresses_with_signer`
* ([org.dashfoundation.dashsdk.credits.IdentityCredits.topUpIdentityFromAddresses]).
*/
@OptIn(ExperimentalMaterial3Api::class)
@Composable
Expand Down Expand Up @@ -139,7 +139,7 @@ fun TopUpIdentityScreen(identityIdHex: String, navController: NavHostController)
"$amt credits."
return@launch
}
mgr.identityCredits.topUpFromAddresses(
mgr.identityCredits.topUpIdentityFromAddresses(
walletHandle = w.handle,
identityId = idBytes,
inputs = inputs,
Expand Down
4 changes: 2 additions & 2 deletions packages/kotlin-sdk/PARITY_SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Capabilities tracked: **31**
| --- | --- | ---: | ---: | ---: | ---: |
| Swift | SDK | 18 | 11 | 1 | 1 |
| Swift | Example app | 5 | 14 | 3 | 9 |
| Kotlin | SDK | 14 | 14 | 2 | 1 |
| Kotlin | SDK | 15 | 14 | 1 | 1 |
| Kotlin | Example app | 6 | 13 | 2 | 10 |

## Restart coverage
Expand Down Expand Up @@ -42,7 +42,7 @@ Capabilities tracked: **31**
| `persistence.dashpay_payment_history` | partial / not-applicable / required | not-applicable / not-applicable / not_applicable |
| `network.masternode_discovery` | partial / not-applicable / not_applicable | partial / not-applicable / not_applicable |
| `identity.platform_address_auto_funding` | partial / partial / not_applicable | partial / partial / not_applicable |
| `identity.external_top_up_from_addresses` | supported / unsupported / not_applicable | unsupported / unsupported / not_applicable |
| `identity.external_top_up_from_addresses` | supported / unsupported / not_applicable | supported / unsupported / not_applicable |
| `tokens.authorization_decisions` | partial / partial / not_applicable | partial / partial / not_applicable |
| `tokens.direct_purchase_quote` | partial / partial / not_applicable | partial / partial / not_applicable |
| `protocol.address_validation` | supported / supported / not_applicable | partial / partial / not_applicable |
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package org.dashfoundation.dashsdk.credits

import org.dashfoundation.dashsdk.wallet.op
import org.dashfoundation.dashsdk.wallet.opReturningCompletedResult

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
Expand All @@ -19,10 +20,19 @@ internal fun interface ResumeTopUpNativeCall {
): Long
}

internal fun interface AddressTopUpNativeCall {
fun call(
walletHandle: Long,
identityId: ByteArray,
inputsBlob: ByteArray,
signerHandle: Long,
): Long
}

/**
* One Platform-address funding input for an identity top-up — port of the
* `IdentityAddressInput` tuple the Swift `TopUpIdentityView` packs. Encodes
* to the flat blob [CreditsNative.topUpFromAddresses] consumes.
* to the flat blob [CreditsNative.topUpIdentityFromAddresses] consumes.
*
* @property addressType 0 = P2PKH, 1 = P2SH.
* @property hash the 20-byte address hash.
Expand Down Expand Up @@ -81,6 +91,11 @@ class IdentityCredits internal constructor(
private val gate: org.dashfoundation.dashsdk.wallet.TeardownGate? = null,
private val resumeTopUpNative: ResumeTopUpNativeCall =
ResumeTopUpNativeCall(CreditsNative::topUpIdentityWithExistingAssetLock),
private val addressTopUpNative: AddressTopUpNativeCall =
AddressTopUpNativeCall(CreditsNative::topUpIdentityFromAddresses),
@Suppress("DEPRECATION")
private val managedAddressTopUpNative: AddressTopUpNativeCall =
AddressTopUpNativeCall(CreditsNative::topUpFromAddresses),
) {

/**
Expand Down Expand Up @@ -212,17 +227,55 @@ class IdentityCredits internal constructor(
}

/**
* Top up [identityId] (32 bytes) from Platform-address [inputs],
* signed via [signerHandle]. Returns the post-transition balance.
* Top up [identityId] (32 bytes) from Platform-address [inputs], whoever
* owns the identity (one of the wallet's or someone else's), signed via
* [signerHandle]. Rust fetches the identity from Platform, never adds it
* to the wallet, and updates the balance of an identity the wallet
* manages, so the caller does not decide whether it is its own. Returns
* the identity's post-transition balance.
*
* Cancellation: a top-up that completed natively still returns its
* balance to a cancelled caller (see `TeardownGate.opReturningCompletedResult`).
*/
suspend fun topUpIdentityFromAddresses(
walletHandle: Long,
identityId: ByteArray,
inputs: List<FundingInput>,
signerHandle: Long,
): Long = gate.opReturningCompletedResult {
mapNativeErrors {
addressTopUpNative.call(
walletHandle,
identityId,
FundingInput.encode(inputs),
signerHandle,
)
}
}

/**
* Top up [identityId] (32 bytes), an identity the wallet manages, from
* Platform-address [inputs], signed via [signerHandle]. Returns the
* post-transition balance.
*
* **Deprecated:** use [topUpIdentityFromAddresses], which tops up any
* identity and updates a managed one's balance the same way; this one
* differs only in refusing an identity the wallet does not manage.
*
* Cancellation: as for [topUpIdentityFromAddresses].
*/
@Deprecated(
"Use topUpIdentityFromAddresses, which tops up any identity.",
ReplaceWith("topUpIdentityFromAddresses(walletHandle, identityId, inputs, signerHandle)"),
)
suspend fun topUpFromAddresses(
walletHandle: Long,
identityId: ByteArray,
inputs: List<FundingInput>,
signerHandle: Long,
): Long = gate.op {
): Long = gate.opReturningCompletedResult {
mapNativeErrors {
CreditsNative.topUpFromAddresses(
managedAddressTopUpNative.call(
walletHandle,
identityId,
FundingInput.encode(inputs),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,14 +69,38 @@ internal object CreditsNative {
)

/**
* Top up [identityId] (32 bytes) from Platform-address inputs, signed
* per-address via [signerHandle] (the platform-address signer).
* Returns the post-transition credit balance.
* Top up [identityId] (32 bytes), whoever owns the identity, from
* Platform-address inputs, signed per-address via [signerHandle] (the
* platform-address signer). Rust fetches the identity from Platform,
* never adds it to the wallet, and updates the balance of an identity
* the wallet manages. Returns the identity's post-transition credit
* balance.
*
* @param inputsBlob big-endian: `u32 rowCount` then per row
* `u8 addressType (0 P2PKH / 1 P2SH), u8[20] hash, u64 credits`.
* Built by [org.dashfoundation.dashsdk.credits.FundingInput.encode].
*/
external fun topUpIdentityFromAddresses(
walletHandle: Long,
identityId: ByteArray,
inputsBlob: ByteArray,
signerHandle: Long,
): Long

/**
* Top up [identityId] (32 bytes), an identity the wallet manages, from
* Platform-address inputs, signed per-address via [signerHandle] (the
* platform-address signer). Returns the post-transition credit balance.
*
* **Deprecated:** use [topUpIdentityFromAddresses], which tops up any
* identity; this one refuses an identity the wallet does not manage.
*
* @param inputsBlob as for [topUpIdentityFromAddresses].
*/
@Deprecated(
"Use topUpIdentityFromAddresses, which tops up any identity.",
ReplaceWith("topUpIdentityFromAddresses(walletHandle, identityId, inputsBlob, signerHandle)"),
)
external fun topUpFromAddresses(
walletHandle: Long,
identityId: ByteArray,
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
package org.dashfoundation.dashsdk.credits

import java.util.concurrent.CountDownLatch
import java.util.concurrent.TimeUnit
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.test.runTest
import kotlinx.coroutines.withTimeout
import org.dashfoundation.dashsdk.wallet.TeardownGate
import org.junit.Assert.assertArrayEquals
import org.junit.Assert.assertEquals
import org.junit.Assert.assertTrue
import org.junit.Test

class IdentityAddressTopUpTest {

/**
* The top-up of any identity hands its arguments, the funding rows
* encoded, to its own JNI bridge and returns the balance it reports;
* whether the identity is the wallet's own is not decided here.
*/
@Test
fun `top up of any identity marshals to its own bridge and returns its balance`() = runTest {
val calls = mutableListOf<List<Any>>()
val credits = IdentityCredits(
addressTopUpNative = AddressTopUpNativeCall { wallet, identity, blob, signer ->
calls += listOf(wallet, identity, blob, signer)
777L
},
)
val identityId = ByteArray(32) { 9 }
val inputs = listOf(
FundingInput(addressType = 0, hash = ByteArray(20) { 7 }, credits = 1_000),
FundingInput(addressType = 1, hash = ByteArray(20) { 8 }, credits = 7),
)

val balance = credits.topUpIdentityFromAddresses(
walletHandle = 42,
identityId = identityId,
inputs = inputs,
signerHandle = 5,
)

assertEquals(777L, balance)
assertEquals(1, calls.size)
val (wallet, identity, blob, signer) = calls.single()
assertEquals(42L, wallet)
assertArrayEquals(identityId, identity as ByteArray)
assertArrayEquals(FundingInput.encode(inputs), blob as ByteArray)
assertEquals(5L, signer)
}

/**
* A top-up that completed natively after its caller was cancelled still
* hands the balance back, so the caller can tell the credits moved and
* does not retry the payment. Holds for the deprecated managed-only
* route too.
*/
@Suppress("DEPRECATION")
@Test
fun `a cancelled caller still receives a completed top-up's balance`() = runBlocking {
for (route in listOf(TopUpRoute.ANY_IDENTITY, TopUpRoute.MANAGED_DEPRECATED))
for (gate in listOf(TeardownGate(), null)) {
val entered = CountDownLatch(1)
val release = CountDownLatch(1)
val received = CompletableDeferred<Long>()
val native = AddressTopUpNativeCall { _, _, _, _ ->
entered.countDown()
// The blocking JNI call does not observe cancellation; it
// completes only after the caller has been cancelled.
release.await()
777L
}
val unused = AddressTopUpNativeCall { _, _, _, _ -> error("wrong bridge") }
val credits = when (route) {
TopUpRoute.ANY_IDENTITY ->
IdentityCredits(gate = gate, addressTopUpNative = native, managedAddressTopUpNative = unused)
TopUpRoute.MANAGED_DEPRECATED ->
IdentityCredits(gate = gate, addressTopUpNative = unused, managedAddressTopUpNative = native)
}
val identityId = ByteArray(32) { 9 }
val inputs = listOf(FundingInput(addressType = 0, hash = ByteArray(20) { 7 }, credits = 1_000))

val op = launch(Dispatchers.Default) {
val balance = when (route) {
TopUpRoute.ANY_IDENTITY ->
credits.topUpIdentityFromAddresses(42, identityId, inputs, 5)
TopUpRoute.MANAGED_DEPRECATED ->
credits.topUpFromAddresses(42, identityId, inputs, 5)
}
received.complete(balance)
}
assertTrue("native top-up never started", entered.await(5, TimeUnit.SECONDS))
op.cancel()
release.countDown()
withTimeout(5_000) { op.join() }

assertTrue(op.isCancelled)
assertTrue("$route: completed top-up balance was dropped", received.isCompleted)
assertEquals(777L, received.await())
gate?.let { withTimeout(5_000) { it.closeAndAwait() } }
}
}

private enum class TopUpRoute { ANY_IDENTITY, MANAGED_DEPRECATED }
}
Loading
Loading