feat(platform-wallet): own the shielded-tip payment decisions in the wallet

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/FundingNative.kt

@@ -17,16 +17,28 @@ package org.dashfoundation.dashsdk.ffi
  */
 internal object FundingNative {
     external fun tipAccountIndex(identityIndex: Int): Int
+    external fun parseShieldedTipAmount(text: String): Long
     external fun prepareShieldedTipAddress(
         manager: Long, walletId: ByteArray, resolver: Long, identityId: ByteArray,
     ): ByteArray
     external fun resolveShieldedTip(wallet: Long, username: String): ByteArray
-    /** A non-null [sourceIdentityId] spends that identity's tip account; otherwise [sourceAccount]. */
+    /**
+     * A non-null [sourceIdentityId] spends that identity's tip account; otherwise [sourceAccount].
+     * [outDisposition] (one element) receives Rust's retry decision, also when this throws.
+     */
     external fun sendShieldedTip(
         manager: Long, walletId: ByteArray, resolver: Long, sourceIdentityId: ByteArray?, sourceAccount: Int,
         username: String, expectedId: ByteArray, expectedAddress: ByteArray,
-        amount: Long, memo: String?,
+        amount: Long, memo: String?, outDisposition: IntArray,
     )
+    /** 152 bytes: identity, address, change kind, previous identity, previous address, unresolved. */
+    external fun reviewShieldedTip(manager: Long, walletId: ByteArray, username: String): ByteArray
+    external fun abandonUnresolvedShieldedTips(manager: Long, walletId: ByteArray, acknowledge: Boolean): Int
+    external fun refreshShieldedAccounts(manager: Long, walletId: ByteArray, resolver: Long)
+    /** `[state, account, credits]`; state 0 unverified, 1 unavailable, 2 available. */
+    external fun identityTipBalance(manager: Long, walletId: ByteArray, identityId: ByteArray): LongArray
+    /** `[account, verified]` for a wallet identity's dedicated tip account. */
+    external fun identityTipAccount(wallet: Long, identityId: ByteArray): IntArray
 
 
     external fun shieldedIdentityDebitRecoveryRecords(

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/tokens/Dashpay.kt

@@ -44,6 +44,15 @@ class Dashpay internal constructor(private val walletHandle: Long,
         ShieldedTipRecipient(bytes.copyOfRange(0, 32), bytes.copyOfRange(32, 75))
     }
 
+    /** The identity's dedicated tip account, and whether Rust has verified its slot this session. */
+    suspend fun identityTipAccount(identityId: ByteArray): IdentityTipAccount = gate.op {
+        val values = mapNativeErrors {
+            org.dashfoundation.dashsdk.ffi.FundingNative.identityTipAccount(walletHandle, identityId)
+        }
+        check(values.size == 2) { "Invalid tip account response" }
+        IdentityTipAccount(values[0], values[1] != 0)
+    }
+
     /**
      * Send a contact request to [recipientIdentityId], signing the document
      * state-transition with [signerHandle] and keying the contact crypto

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/tokens/ShieldedTipRecipient.kt

@@ -39,3 +39,82 @@ sealed class ShieldedTipSource {
         }
     }
 }
+
+/** Rust's decision whether a failed tip may be sent again. */
+enum class ShieldedTipDisposition {
+    /** Nothing was broadcast, or it was definitively rejected: review and send again. */
+    NOT_SENT,
+
+    /** The payment may have executed or may still execute: do not send it again. */
+    UNRESOLVED;
+
+    internal companion object {
+        /** The native `SHIELDED_TIP_DISPOSITION_NOT_SENT`; every other value is unresolved. */
+        const val NATIVE_NOT_SENT = 1
+
+        fun fromNative(value: Int): ShieldedTipDisposition =
+            if (value == NATIVE_NOT_SENT) NOT_SENT else UNRESOLVED
+    }
+}
+
+/** A tip send that failed; [disposition] says whether it may be sent again. */
+class ShieldedTipFailure(val disposition: ShieldedTipDisposition, cause: Throwable) :
+    Exception(cause.message, cause)
+
+/** How a tip recipient compares with the one last confirmed for the same name from this wallet. */
+sealed class ShieldedTipRecipientChange {
+    object New : ShieldedTipRecipientChange()
+    object Unchanged : ShieldedTipRecipientChange()
+    class Changed(val previous: ShieldedTipRecipient) : ShieldedTipRecipientChange()
+}
+
+/**
+ * What a user confirms before tipping a name. [unresolved] means an earlier payment to
+ * this address is unsettled, and a send is refused until shielded sync settles it.
+ */
+class ShieldedTipReview(
+    val recipient: ShieldedTipRecipient,
+    val change: ShieldedTipRecipientChange,
+    val unresolved: Boolean,
+) {
+    internal companion object {
+        fun fromNative(bytes: ByteArray): ShieldedTipReview {
+            check(bytes.size == 152) { "Invalid tip review response" }
+            val recipient = ShieldedTipRecipient(bytes.copyOfRange(0, 32), bytes.copyOfRange(32, 75))
+            val change = when (bytes[75].toInt()) {
+                0 -> ShieldedTipRecipientChange.New
+                1 -> ShieldedTipRecipientChange.Unchanged
+                else -> ShieldedTipRecipientChange.Changed(
+                    ShieldedTipRecipient(bytes.copyOfRange(76, 108), bytes.copyOfRange(108, 151)),
+                )
+            }
+            return ShieldedTipReview(recipient, change, bytes[151].toInt() != 0)
+        }
+    }
+}
+
+/**
+ * A wallet identity's dedicated tip account. Show its balance as the identity's only
+ * when [verified]: unverified, the account may belong to another identity.
+ */
+data class IdentityTipAccount(val account: Int, val verified: Boolean)
+
+/** An identity's tip balance as the wallet can vouch for it; decided by Rust. */
+sealed class IdentityTipBalance {
+    /** This session has not proved the identity holds its slot. */
+    object Unverified : IdentityTipBalance()
+
+    /** Verified, but the account's ledger is not established yet. */
+    data class Unavailable(val account: Int) : IdentityTipBalance()
+
+    /** Spendable credits of the identity's tip account. */
+    data class Available(val account: Int, val credits: Long) : IdentityTipBalance()
+
+    internal companion object {
+        fun fromNative(values: LongArray): IdentityTipBalance = when (values[0]) {
+            2L -> Available(values[1].toInt(), values[2])
+            1L -> Unavailable(values[1].toInt())
+            else -> Unverified
+        }
+    }
+}

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/PlatformWalletManager.kt

@@ -2015,29 +2015,101 @@ class PlatformWalletManager(
     // — the caller must NOT retry (the spent notes stay reserved Rust-side;
     // the next shielded sync reconciles the outcome).
 
+    /** Exact credits for a tip amount typed in DASH, parsed by Rust; throws on ambiguous input. */
+    fun parseShieldedTipAmount(text: String): Long =
+        mapNativeErrors { FundingNative.parseShieldedTipAmount(text) }
+
     /** Dedicated account index derived by Rust's wallet convention. */
     fun shieldedTipAccountIndex(identityIndex: Int): Int = mapNativeErrors { FundingNative.tipAccountIndex(identityIndex) }
 
     suspend fun prepareShieldedTipAddress(walletId: ByteArray, identityId: ByteArray): ByteArray = teardownGate.op {
         mapNativeErrors { FundingNative.prepareShieldedTipAddress(managerHandle, walletId, mnemonicResolver.nativeHandle, identityId) }
     }
 
-    /** Send only if fresh resolution still matches the recipient shown in confirmation. */
+    /**
+     * Rebind [walletId]'s shielded accounts after identity discovery: Rust keeps the wallet's
+     * ordinary accounts and adds the tip accounts of newly discovered identities.
+     */
+    suspend fun refreshShieldedAccounts(walletId: ByteArray) = teardownGate.op {
+        mapNativeErrors {
+            FundingNative.refreshShieldedAccounts(managerHandle, walletId, mnemonicResolver.nativeHandle)
+        }
+    }
+
+    /**
+     * An identity's tip balance as the wallet can vouch for it. Throws (busy) instead of
+     * waiting while a scan holds the shielded store; read it again after sync.
+     */
+    suspend fun identityTipBalance(
+        walletId: ByteArray, identityId: ByteArray,
+    ): org.dashfoundation.dashsdk.tokens.IdentityTipBalance = teardownGate.op {
+        val values = mapNativeErrors { FundingNative.identityTipBalance(managerHandle, walletId, identityId) }
+        check(values.size == 3) { "Invalid tip balance response" }
+        org.dashfoundation.dashsdk.tokens.IdentityTipBalance.fromNative(values)
+    }
+
+    /**
+     * Allow new tips although earlier ones from this wallet are unresolved. Pass the user's
+     * acknowledgement that those tips may still execute; returns how many were released.
+     */
+    suspend fun abandonUnresolvedShieldedTips(
+        walletId: ByteArray, acknowledgePossibleExecution: Boolean,
+    ): Int = teardownGate.op {
+        mapNativeErrors {
+            FundingNative.abandonUnresolvedShieldedTips(managerHandle, walletId, acknowledgePossibleExecution)
+        }
+    }
+
+    /**
+     * Resolve [username] for the user to confirm: its recipient, whether it changed since this
+     * wallet last confirmed the name, and whether an earlier payment to it is unresolved.
+     */
+    suspend fun reviewShieldedTip(
+        walletId: ByteArray, username: String,
+    ): org.dashfoundation.dashsdk.tokens.ShieldedTipReview = teardownGate.op {
+        org.dashfoundation.dashsdk.tokens.ShieldedTipReview.fromNative(
+            mapNativeErrors { FundingNative.reviewShieldedTip(managerHandle, walletId, username) },
+        )
+    }
+
+    /**
+     * Send only if fresh resolution still matches the recipient shown in confirmation. Every
+     * failure is thrown as [org.dashfoundation.dashsdk.tokens.ShieldedTipFailure] carrying Rust's
+     * decision whether the tip may be sent again; one raised before the native send is not sent.
+     */
     suspend fun sendShieldedTip(
         walletId: ByteArray, username: String,
         recipient: org.dashfoundation.dashsdk.tokens.ShieldedTipRecipient,
         amount: Long, source: org.dashfoundation.dashsdk.tokens.ShieldedTipSource,
         memo: String? = null,
-    ): Unit = teardownGate.op {
-        require(amount > 0) { "amount must be positive, got $amount" }
-        val (sourceIdentityId, sourceAccount) = when (source) {
-            is org.dashfoundation.dashsdk.tokens.ShieldedTipSource.Identity -> source.identityId to 0
-            is org.dashfoundation.dashsdk.tokens.ShieldedTipSource.Account -> null to source.index
-        }
-        mapNativeErrors {
-            FundingNative.sendShieldedTip(managerHandle, walletId, mnemonicResolver.nativeHandle,
-                sourceIdentityId, sourceAccount, username, recipient.identityId, recipient.address,
-                amount, memo)
+    ) {
+        // A failure before JNI is entered sent nothing; JNI overwrites this with Rust's decision.
+        val disposition = intArrayOf(
+            org.dashfoundation.dashsdk.tokens.ShieldedTipDisposition.NATIVE_NOT_SENT,
+        )
+        try {
+            // Not cancellable once started: the native send cannot be interrupted, and a
+            // cancelled caller must still receive its outcome and Rust's disposition.
+            kotlinx.coroutines.withContext(kotlinx.coroutines.NonCancellable) {
+                teardownGate.op {
+                    require(amount > 0) { "amount must be positive, got $amount" }
+                    val (sourceIdentityId, sourceAccount) = when (source) {
+                        is org.dashfoundation.dashsdk.tokens.ShieldedTipSource.Identity -> source.identityId to 0
+                        is org.dashfoundation.dashsdk.tokens.ShieldedTipSource.Account -> null to source.index
+                    }
+                    mapNativeErrors {
+                        FundingNative.sendShieldedTip(managerHandle, walletId, mnemonicResolver.nativeHandle,
+                            sourceIdentityId, sourceAccount, username, recipient.identityId, recipient.address,
+                            amount, memo, disposition)
+                    }
+                }
+            }
+        } catch (error: kotlinx.coroutines.CancellationException) {
+            throw error
+        } catch (error: Exception) {
+            throw org.dashfoundation.dashsdk.tokens.ShieldedTipFailure(
+                org.dashfoundation.dashsdk.tokens.ShieldedTipDisposition.fromNative(disposition[0]), error,
+            )
         }
     }
 

packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/tokens/ShieldedTipReviewTest.kt

@@ -0,0 +1,42 @@
+package org.dashfoundation.dashsdk.tokens
+
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/** Marshalling of the native tip review and retry decision; the decisions themselves are Rust's. */
+class ShieldedTipReviewTest {
+    private fun review(change: Int, unresolved: Boolean): ByteArray =
+        ByteArray(32) { 1 } + ByteArray(43) { 2 } + byteArrayOf(change.toByte()) +
+            ByteArray(32) { 3 } + ByteArray(43) { 4 } + byteArrayOf(if (unresolved) 1 else 0)
+
+    @Test
+    fun shouldDecodeEachRecipientChange() {
+        val new = ShieldedTipReview.fromNative(review(0, unresolved = false))
+        assertEquals(ShieldedTipRecipientChange.New, new.change)
+        assertArrayEquals(ByteArray(32) { 1 }, new.recipient.identityId)
+        assertArrayEquals(ByteArray(43) { 2 }, new.recipient.address)
+        assertFalse(new.unresolved)
+
+        assertEquals(
+            ShieldedTipRecipientChange.Unchanged,
+            ShieldedTipReview.fromNative(review(1, unresolved = true)).change,
+        )
+
+        val changed = ShieldedTipReview.fromNative(review(2, unresolved = true))
+        val previous = (changed.change as ShieldedTipRecipientChange.Changed).previous
+        assertArrayEquals(ByteArray(32) { 3 }, previous.identityId)
+        assertArrayEquals(ByteArray(43) { 4 }, previous.address)
+        assertTrue(changed.unresolved)
+    }
+
+    @Test
+    fun shouldTreatAnyDispositionButNotSentAsUnresolved() {
+        assertEquals(ShieldedTipDisposition.NOT_SENT, ShieldedTipDisposition.fromNative(1))
+        for (value in listOf(0, 2, -1)) {
+            assertEquals(ShieldedTipDisposition.UNRESOLVED, ShieldedTipDisposition.fromNative(value))
+        }
+    }
+}