refactor(oc): introduce BillPresentationData to bundle code data + nonce

Replace separate `data` and `usedNonce` properties on GiveBillTransactor
with a single BillPresentationData model, threading it through
BillTransactionManager, BillController, and RealSessionController. This
makes the pairing explicit and prevents accidental misuse when a bill is
re-presented with the same nonce after a cancelled share-sheet.

Also adds KDoc across the full give/grab/send/receive flow where it was
missing — transactors, BillTransactionManager, BillController, and
supporting types.

Signed-off-by: Brandon McAnsh <git@bmcreations.dev>

Author: bmc08gt

apps/flipcash/core/src/main/kotlin/com/flipcash/app/core/bill/BillState.kt

@@ -124,6 +124,7 @@ sealed interface Bill {
         override val data: List<Byte> = emptyList(),
         val kind: Kind = Kind.cash,
         val verifiedState: VerifiedState? = null,
+        val nonce: List<Byte> = emptyList(),
     ) : Bill {
         override val canFlip: Boolean = false
     }

apps/flipcash/core/src/main/kotlin/com/flipcash/app/core/internal/bill/BillController.kt

@@ -5,6 +5,7 @@ import com.flipcash.app.userflags.UserFlagsCoordinator
 import com.flipcash.services.user.UserManager
 import com.getcode.opencode.internal.manager.VerifiedState
 import com.getcode.opencode.model.accounts.AccountCluster
+import com.getcode.opencode.internal.transactors.BillPresentationData
 import com.getcode.opencode.managers.BillTransactionManager
 import com.getcode.opencode.model.accounts.GiftCardAccount
 import com.getcode.opencode.model.core.OpenCodePayload
@@ -17,6 +18,11 @@ import kotlinx.coroutines.flow.update
 import javax.inject.Inject
 import javax.inject.Singleton
 
+/**
+ * UI-facing facade for bill transactions. Owns the [BillState] flow and
+ * delegates to [BillTransactionManager] for all four payment flows (give,
+ * grab, send cash link, receive cash link).
+ */
 @Singleton
 class BillController @Inject constructor(
     private val transactionManager: BillTransactionManager,
@@ -37,12 +43,18 @@ class BillController @Inject constructor(
         transactionManager.reset()
     }
 
+    /**
+     * Initiates the **give** flow — presents a bill and waits for a recipient to
+     * grab it. Delegates to [BillTransactionManager.awaitGrabFromRecipient],
+     * injecting the configured exchange-data timeout from user flags.
+     */
     fun awaitGrab(
         amount: LocalFiat,
         token: Token,
         owner: AccountCluster,
         verifiedState: VerifiedState?,
-        present: (List<Byte>) -> Unit,
+        nonce: List<Byte>? = null,
+        present: (BillPresentationData) -> Unit,
         onGrabbed: suspend (LocalFiat) -> Unit,
         onTimeout: () -> Unit,
         onError: (Throwable) -> Unit,
@@ -52,6 +64,7 @@ class BillController @Inject constructor(
         owner = owner,
         verifiedState = verifiedState,
         billExchangeDataTimeout = userFlags.resolvedFlags.value.billExchangeDataTimeout.effectiveValue,
+        nonce = nonce,
         present = present,
         onGrabbed = onGrabbed,
         onTimeout = onTimeout,
@@ -60,13 +73,15 @@ class BillController @Inject constructor(
 
     fun cancelAwaitForGrab() = transactionManager.cancelAwaitForGrab()
 
+    /** Initiates the **grab** flow — claims a scanned bill from a sender. */
     fun attemptGrab(
         owner: AccountCluster,
         payload: OpenCodePayload,
         onGrabbed: suspend (Token, LocalFiat, VerifiedState?) -> Unit,
         onError: (Throwable) -> Unit,
     ) = transactionManager.attemptGrabFromSender(owner, payload, onGrabbed, onError)
 
+    /** Initiates the **send cash link** flow — funds a gift card for remote sending. */
     fun fundGiftCard(
         giftCard: GiftCardAccount,
         amount: LocalFiat,
@@ -76,6 +91,7 @@ class BillController @Inject constructor(
         onError: (Throwable) -> Unit,
     ) = transactionManager.fundGiftCard(giftCard, amount, owner, token, onFunded, onError)
 
+    /** Initiates the **receive cash link** flow — claims a gift card by entropy. */
     fun receiveGiftCard(
         entropy: String,
         owner: AccountCluster,

apps/flipcash/shared/session/src/main/kotlin/com/flipcash/app/session/internal/RealSessionController.kt

@@ -358,6 +358,7 @@ class RealSessionController @Inject constructor(
             amount = bill.amount,
             token = bill.token,
             verifiedState = (bill as? Bill.Cash)?.verifiedState,
+            nonce = (bill as? Bill.Cash)?.nonce?.takeIf { it.isNotEmpty() },
             owner = owner,
             onGrabbed = { amount ->
                 tokenCoordinator.subtract(bill.token, amount)
@@ -383,7 +384,7 @@ class RealSessionController @Inject constructor(
                     message = resources.getString(R.string.error_description_CashReturnedToWallet)
                 )
             },
-            present = { data ->
+            present = { (data, nonce) ->
                 if (!bill.didReceive) {
                     trace(
                         tag = "Session",
@@ -398,7 +399,7 @@ class RealSessionController @Inject constructor(
                         type = TraceType.User,
                     )
                 }
-                presentBillToUser(data, bill)
+                presentBillToUser(data, nonce, bill)
             },
         )
     }
@@ -818,7 +819,7 @@ class RealSessionController @Inject constructor(
         )
     }
 
-    private fun presentBillToUser(data: List<Byte>, bill: Bill) {
+    private fun presentBillToUser(data: List<Byte>, nonce: List<Byte>, bill: Bill) {
         if (billController.state.value.bill != null) return
 
         billController.update {
@@ -830,6 +831,7 @@ class RealSessionController @Inject constructor(
                     confirmationDelay = bill.confirmationDelay,
                     token = bill.token,
                     verifiedState = (bill as? Bill.Cash)?.verifiedState,
+                    nonce = nonce,
                 ),
                 valuation = PaymentValuation(bill.amount.nativeAmount),
             )

apps/flipcash/shared/session/src/test/kotlin/com/flipcash/app/session/internal/SessionControllerGiftCardErrorTest.kt

@@ -170,6 +170,7 @@ class SessionControllerGiftCardErrorTest {
                 token = any(),
                 owner = any(),
                 verifiedState = any(),
+                nonce = any(),
                 present = any(),
                 onGrabbed = any(),
                 onTimeout = any(),

services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/BillPresentationData.kt

@@ -0,0 +1,13 @@
+package com.getcode.opencode.internal.transactors
+
+/**
+ * Bundles the scannable code data with the nonce used to derive it.
+ *
+ * Keeping these paired ensures the same nonce is reused when a bill is
+ * re-presented (e.g. after a cancelled share-sheet), preserving the
+ * original rendezvous key so the sender's messaging stream stays valid.
+ */
+data class BillPresentationData(
+    val data: List<Byte>,
+    val nonce: List<Byte>,
+)

services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/GiveBillTransactor.kt

@@ -25,6 +25,15 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.cancel
 import kotlin.time.Duration
 
+/**
+ * Transactor for the **give** side of a peer-to-peer cash bill.
+ *
+ * Lifecycle: call [with] to configure the bill parameters and generate
+ * a rendezvous payload, then [start] to advertise the bill on the
+ * messaging stream and block until a recipient grabs it and the on-chain
+ * transfer completes. Call [dispose] to tear down the coroutine scope
+ * and clear state when the bill is dismissed or times out.
+ */
 internal class GiveBillTransactor(
     private val currencyController: CurrencyController,
     private val messagingController: MessagingController,
@@ -43,15 +52,23 @@ internal class GiveBillTransactor(
 
     private var providedVerifiedState: VerifiedState? = null
 
-    var data: List<Byte> = emptyList()
+    var presentationData: BillPresentationData = BillPresentationData(emptyList(), emptyList())
         private set
 
+    /**
+     * Configures this transactor for a new bill and generates the rendezvous
+     * payload. Must be called before [start].
+     *
+     * @param providedNonce optional nonce to reuse from a previous presentation
+     *   of the same bill. When `null` a fresh random nonce is generated.
+     */
     fun with(
         token: Token,
         amount: LocalFiat,
         owner: AccountCluster,
         billExchangeDataTimeout: Duration?,
-        verifiedState: VerifiedState?
+        verifiedState: VerifiedState?,
+        providedNonce: List<Byte>? = null,
     ) {
         this.token = token
         this.amount = amount
@@ -61,14 +78,16 @@ internal class GiveBillTransactor(
 
         receivingAccount = null
 
+        val resolvedNonce = providedNonce ?: nonce
+
         val payloadResult = payloadFactory.create(
             kind = PayloadKind.MultiMintCash,
             value = amount.nativeAmount,
-            nonce = nonce
+            nonce = resolvedNonce
         )
 
         rendezvousKey = payloadResult.rendezvous
-        data = payloadResult.codeData
+        presentationData = BillPresentationData(data = payloadResult.codeData, nonce = resolvedNonce)
     }
 
     /**
@@ -196,13 +215,14 @@ internal class GiveBillTransactor(
         )
     }
 
+    /** Cancels the coroutine scope and clears all held state. */
     fun dispose() {
         owner = null
-        data = emptyList()
+        presentationData = BillPresentationData(emptyList(), emptyList())
         rendezvousKey = null
         receivingAccount = null
         token = null
-
+        providedVerifiedState = null
         scope.cancel()
     }
 

services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/GrabBillTransactor.kt

@@ -15,6 +15,15 @@ import com.getcode.utils.NotifiableError
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.cancel
 
+/**
+ * Transactor for the **grab** side of a peer-to-peer cash bill.
+ *
+ * Lifecycle: call [with] to set the owner and scanned payload, then
+ * [start] to claim the bill from the sender. For multi-mint payloads
+ * this involves polling the rendezvous stream, creating a token account
+ * if needed, and sending the grab request back. Call [dispose] to tear
+ * down state when finished.
+ */
 internal class GrabBillTransactor(
     private val accountController: AccountController,
     private val messagingController: MessagingController,
@@ -25,6 +34,7 @@ internal class GrabBillTransactor(
     private var owner: AccountCluster? = null
     private var payload: OpenCodePayload? = null
 
+    /** Configures this transactor with the owner and scanned payload. Must be called before [start]. */
     fun with(owner: AccountCluster, payload: OpenCodePayload) {
         this.owner = owner
         this.payload = payload
@@ -72,6 +82,7 @@ internal class GrabBillTransactor(
         }
     }
 
+    /** Cancels the coroutine scope and clears all held state. */
     fun dispose() {
         owner = null
         payload = null

services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/PayloadFactory.kt

@@ -6,11 +6,20 @@ import com.getcode.opencode.model.core.PayloadKind
 import com.getcode.opencode.model.financial.Fiat
 import javax.inject.Inject
 
+/**
+ * The output of [PayloadFactory.create] — a rendezvous key pair derived from
+ * the payload and the encoded scannable code data.
+ */
 data class PayloadResult(
     val rendezvous: KeyPair,
     val codeData: List<Byte>,
 )
 
+/**
+ * Creates an [OpenCodePayload][com.getcode.opencode.model.core.OpenCodePayload]
+ * from the given parameters and returns the derived rendezvous key pair and
+ * encoded code data. Extracted as a functional interface for testability.
+ */
 fun interface PayloadFactory {
     fun create(kind: PayloadKind, value: Fiat, nonce: List<Byte>): PayloadResult
 }

services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/ReceiveGiftCardTransactor.kt

@@ -18,6 +18,14 @@ import com.getcode.utils.CodeServerError
 import com.getcode.utils.NotifiableError
 import com.getcode.utils.timedTraceSuspend
 
+/**
+ * Transactor for **receiving (claiming) a cash link** (gift card).
+ *
+ * Lifecycle: call [with] to set the owner and gift card entropy, then
+ * [start] to look up the gift card on-chain, validate eligibility, and
+ * transfer the balance into the receiver's vault. Call [dispose] to
+ * clear state when finished.
+ */
 internal class ReceiveGiftCardTransactor(
     private val accountController: AccountController,
     private val transactionController: TransactionController,
@@ -32,6 +40,7 @@ internal class ReceiveGiftCardTransactor(
 
     private var giftCardOwner: AccountCluster? = null
 
+    /** Configures this transactor with the owner and gift card entropy. Must be called before [start]. */
     fun with(owner: AccountCluster, entropy: String) {
         this.owner = owner
         mnemonic = mnemonicManager.fromEntropyBase58(entropy)
@@ -145,6 +154,7 @@ internal class ReceiveGiftCardTransactor(
         }
     }
 
+    /** Clears all held state. */
     fun dispose() {
         owner = null
         giftCardAccount = null

services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/SendGiftCardTransactor.kt

@@ -14,6 +14,13 @@ import com.getcode.opencode.utils.nonce
 import com.getcode.utils.CodeServerError
 import com.getcode.utils.NotifiableError
 
+/**
+ * Transactor for **sending a cash link** (gift card).
+ *
+ * Lifecycle: call [with] to set the gift card account, amount, token,
+ * and owner, then [start] to submit the remote-send intent that funds
+ * the gift card on-chain. Call [dispose] to clear state when finished.
+ */
 internal class SendGiftCardTransactor(
     private val transactionController: TransactionController,
     private val payloadFactory: PayloadFactory,
@@ -25,6 +32,7 @@ internal class SendGiftCardTransactor(
 
     private var rendezvousKey: KeyPair? = null
 
+    /** Configures this transactor for a new gift card send. Must be called before [start]. */
     fun with(giftCard: GiftCardAccount, amount: LocalFiat, token: Token, owner: AccountCluster) {
         this.giftCardAccount = giftCard
         this.token = token
@@ -84,6 +92,7 @@ internal class SendGiftCardTransactor(
 
     }
 
+    /** Clears all held state. */
     fun dispose() {
         amount = null
         giftCardAccount = null