chore(ocp): document Transactor's; update verified state resolution to requery right before transfers

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

Author: bmc08gt

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

@@ -72,6 +72,30 @@ internal class GiveBillTransactor(
         data = payloadInfo.codeData.toList()
     }
 
+    /**
+     * Presents a cash bill and waits for a recipient to claim it via peer-to-peer
+     * messaging, then executes the on-chain transfer.
+     *
+     * Flow:
+     *  1. Resolve a [VerifiedState] for the currency/token pair using a fallback
+     *     chain: provided state -> local proto store -> live mint data fetch.
+     *  2. Compute exchange data from the verified state (fails if the rate has
+     *     expired past [exchangeDataTimeout]).
+     *  3. Publish a "give bill" request on the rendezvous messaging stream,
+     *     advertising the token mint and exchange data to potential recipients.
+     *  4. Block until a "grab bill" response arrives on the same rendezvous stream.
+     *  5. Verify the grab request's destination signature against the rendezvous
+     *     key to ensure the destination hasn't been tampered with.
+     *  6. Guard against duplicate transfers (same receiving account seen twice).
+     *  7. Transfer funds from the sender's token vault to the recipient's
+     *     destination account.
+     *  8. Poll for the intent metadata confirmation from the server.
+     *
+     * Preconditions: [with] must be called first to set the token, amount, owner,
+     * and (optionally) a pre-resolved [VerifiedState].
+     *
+     * @return the confirmed [TransactionMetadata.SendPublicPayment] on success.
+     */
     suspend fun start(): Result<TransactionMetadata.SendPublicPayment> {
         val ownerKey = owner
             ?: return logAndFail(GiveTransactorError.Other(message = "No owner key. Did you call with() first?"))
@@ -99,8 +123,10 @@ internal class GiveBillTransactor(
             billExchangeDataTimeout = exchangeDataTimeout
         ) ?: return logAndFail(GiveTransactorError.ExchangeRateExpiredException())
 
-        // 1. Send request to "give" the bill to the recipient
-        // This provides the recipient with the desired token mint of the cash
+        // 1. Send request to "give" the bill to the recipient.
+        // This provides the recipient with the desired token mint of the cash.
+        // If this fails, bail out immediately — the receiver never got the
+        // advertisement so the stream will never deliver a grab request.
         messagingController.sendRequestToGiveBill(desiredToken.address, rendezvous, exchangeData)
             .onSuccess {
                 trace(
@@ -109,12 +135,9 @@ internal class GiveBillTransactor(
                     type = TraceType.Log
                 )
             }.onFailure { cause ->
-                trace(
-                    tag = "Messaging",
-                    message = "Failed to send request to give bill for ${desiredToken.symbol}",
-                    type = TraceType.Error,
-                    error = cause
-                )
+                return logAndFail(cause) {
+                    "token" to desiredToken.symbol
+                }
             }
 
         trace(
@@ -150,6 +173,23 @@ internal class GiveBillTransactor(
 
         receivingAccount = transferRequest.account
 
+        /**
+         * At transfer time:
+         * 1. If providedVerifiedState exists → use it (caller knows best)
+         * 2. Otherwise → try fresh from proto store
+         * 3. Otherwise → fall back to the upfront-resolved state
+         */
+        val transferVerifiedState = providedVerifiedState
+            ?: verifiedProtoManager.getVerifiedStateFor(sendingAmount.rate.currency, desiredToken.address)
+            ?: verifiedState
+
+        val transferExchangeData = transferVerifiedState.exchangeDataFor(
+            amount = sendingAmount,
+            mint = desiredToken.address,
+            billExchangeDataTimeout = exchangeDataTimeout
+        ) ?: exchangeData
+
+
         // 4. Send the funds to destination
         return transactionController.transfer(
             scope = scope,
@@ -158,7 +198,7 @@ internal class GiveBillTransactor(
             source = sendingVault,
             destination = transferRequest.account,
             rendezvous = rendezvous.toPublicKey(),
-            exchangeData = exchangeData,
+            exchangeData = transferExchangeData,
         ).fold(
             onSuccess = {
                 transactionController.pollIntentMetadata(

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

@@ -30,6 +30,31 @@ internal class GrabBillTransactor(
         this.payload = payload
     }
 
+    /**
+     * Claims a cash bill from a sender, handling both legacy single-mint and
+     * multi-mint payment flows.
+     *
+     * Flow (dispatched by [PayloadKind]):
+     *
+     *  **Legacy Cash** — sends a grab request directly, then polls for the
+     *  intent confirmation.
+     *
+     *  **MultiMintCash:**
+     *   1. Poll the rendezvous messaging stream for the sender's "give" request
+     *      to learn which token mint and exchange data to use.
+     *   2. Resolve token metadata for the proposed mint.
+     *   3. Create a user account for that token if one doesn't exist yet.
+     *   4. Send a "grab bill" request back to the sender with this account's
+     *      vault as the destination.
+     *   5. Poll for intent confirmation, copying in the verified exchange data
+     *      received from the give request.
+     *   6. Acknowledge the give-request message to clear it from the stream.
+     *
+     * Preconditions: [with] must be called first to set the owner cluster and
+     * the scanned [OpenCodePayload].
+     *
+     * @return the confirmed [TransactionMetadata.PublicPayment] on success.
+     */
     suspend fun start(): Result<TransactionMetadata.PublicPayment> {
         val ownerKey = owner
             ?: return logAndFail(GrabTransactorError.Other(message = "No owner cluster available. Did you call with() first?"))

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

@@ -39,6 +39,31 @@ internal class ReceiveGiftCardTransactor(
         )
     }
 
+    /**
+     * Claims a gift card by its entropy — looks up the on-chain state, validates
+     * eligibility, and transfers the balance into the receiver's vault.
+     *
+     * Flow:
+     *  1. Derive the gift card's owner key pair from the entropy-based mnemonic.
+     *  2. Query the server for the gift card's account info.
+     *  3. Pre-claim checks:
+     *     - Fail if already claimed.
+     *     - Fail if expired or in an unknown state.
+     *     - If the current user is the issuer and [claimIfOwned] is false,
+     *       return [ReceiveGiftTransactorError.UsersGiftCard] so the caller
+     *       can prompt for confirmation.
+     *  4. Resolve the token mint and metadata from the gift card's account info.
+     *  5. Create a user account for that token if one doesn't exist yet.
+     *  6. Submit a receive-remotely intent to transfer the gift card balance
+     *     into the receiver's token vault.
+     *
+     * Preconditions: [with] must be called first to set the owner cluster and
+     * the gift card's base-58 entropy string.
+     *
+     * @param claimIfOwned when `true`, allows claiming even if the current user
+     *   issued the gift card (self-claim).
+     * @return the claimed [Token] and its [LocalFiat] value on success.
+     */
     suspend fun start(claimIfOwned: Boolean): Result<Pair<Token, LocalFiat>> {
         val requestingOwner = owner
             ?: return logAndFail(ReceiveGiftTransactorError.Other(message = "No owner key. Did you call with() first?"))

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

@@ -44,6 +44,20 @@ internal class SendGiftCardTransactor(
         data = payloadInfo.codeData.toList()
     }
 
+    /**
+     * Funds a gift card for remote sending — submits a remote-send intent so the
+     * gift card can later be claimed by a recipient via link or QR code.
+     *
+     * Flow:
+     *  1. Resolve the sender's token vault (timelock account for the target token).
+     *  2. Submit a remote-send intent to the server, transferring funds from
+     *     the sender's vault into the pre-created [GiftCardAccount].
+     *
+     * Preconditions: [with] must be called first to set the gift card account,
+     * amount, token, and owner cluster.
+     *
+     * @return the [IntentRemoteSend] details on success.
+     */
     suspend fun start(): Result<IntentRemoteSend> {
        val rendezvous = rendezvousKey
             ?: return logAndFail(GiveTransactorError.Other(message = "No rendezvous key. Did you call with() first?"))