feat(opencode): record give/grab stage spans on the shared PaymentTrace

bmc08gt · bmc08gt · commit 6527fe7ca830 · 2026-07-07T22:30:06.000-04:00
Wrap the grab (poll give-request, token metadata, account creation, request-grab) and give (resolve exchange data, send request, await grab, submit intent, poll metadata) stages in spans on the shared PaymentTrace, keyed by the rendezvous public key. Restores the PR #660 account-recovery rationale comment folded in during the grab-span refactor. Signed-off-by: Brandon McAnsh <git@bmcreations.dev>
diff --git a/services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/GiveBillTransactor.kt b/services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/GiveBillTransactor.kt
@@ -18,6 +18,9 @@ import com.getcode.solana.keys.PublicKey
 import com.getcode.utils.CodeServerError
 import com.getcode.utils.NotifiableError
 import com.getcode.utils.TraceType
+import com.getcode.utils.payment.PaymentFlow
+import com.getcode.utils.payment.PaymentTraceRegistry
+import com.getcode.utils.payment.spanSuspendOrRun
 import com.getcode.utils.trace
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.cancel
@@ -123,12 +126,15 @@ internal class GiveBillTransactor(
             ?: return logAndFail(GiveTransactorError.Other(message = "No token. Did you call with() first?"))
         val rendezvous = rendezvousKey
             ?: return logAndFail(GiveTransactorError.Other(message = "No rendezvous key. Did you call with() first?"))
+        val correlationId: String = rendezvous.publicKey
+        val paymentTrace = PaymentTraceRegistry.open(correlationId, PaymentFlow.Give)
         val sendingAmount = amount
             ?: return logAndFail(GiveTransactorError.Other(message = "No amount. Did you call with() first?"))
 
-        val initialState = providedVerifiedState
-            ?: verifiedFiatCalculator.resolveVerifiedState(sendingAmount.rate.currency, desiredToken.address)
-            ?: return logAndFail(GiveTransactorError.Other("Failed to get verified state"))
+        val initialState = paymentTrace.spanSuspendOrRun("resolveExchangeData") {
+            providedVerifiedState
+                ?: verifiedFiatCalculator.resolveVerifiedState(sendingAmount.rate.currency, desiredToken.address)
+        } ?: return logAndFail(GiveTransactorError.Other("Failed to get verified state"))
 
         val (verifiedState, exchangeData) = initialState.exchangeDataFor(
             amount = sendingAmount,
@@ -154,7 +160,9 @@ internal class GiveBillTransactor(
         // 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)
+        paymentTrace.spanSuspendOrRun("sendRequestToGiveBill") {
+            messagingController.sendRequestToGiveBill(desiredToken.address, rendezvous, exchangeData)
+        }
             .onSuccess {
                 trace(
                     tag = "Messaging",
@@ -174,8 +182,12 @@ internal class GiveBillTransactor(
         )
 
         // 2. Wait for recipient to grab the bill
-        val transferRequest = messagingController.awaitRequestToGrabBill(scope, rendezvous)
-            ?: return logAndFail(GiveTransactorError.NoGrabReceived())
+        val transferRequest = paymentTrace.spanSuspendOrRun("awaitGrab") {
+            messagingController.awaitRequestToGrabBill(scope, rendezvous)
+        } ?: run {
+            PaymentTraceRegistry.finish(correlationId, success = false)
+            return logAndFail(GiveTransactorError.NoGrabReceived())
+        }
 
 
         // 3. Validate that destination hasn't been tampered with by
@@ -208,25 +220,31 @@ internal class GiveBillTransactor(
 
 
         // 4. Send the funds to destination
-        return transactionController.transfer(
-            scope = scope,
-            amount = amount!!,
-            mint = desiredToken.address,
-            source = sendingVault,
-            destination = transferRequest.account,
-            rendezvous = rendezvous.toPublicKey(),
-            exchangeData = transferExchangeData,
-        ).fold(
+        val outcome = paymentTrace.spanSuspendOrRun("submitIntent") {
+            transactionController.transfer(
+                scope = scope,
+                amount = amount!!,
+                mint = desiredToken.address,
+                source = sendingVault,
+                destination = transferRequest.account,
+                rendezvous = rendezvous.toPublicKey(),
+                exchangeData = transferExchangeData,
+            )
+        }.fold(
             onSuccess = {
-                transactionController.pollIntentMetadata(
-                    owner = sendingVault.authority.keyPair,
-                    intentId = it.id
-                )
+                paymentTrace.spanSuspendOrRun("pollIntentMetadata") {
+                    transactionController.pollIntentMetadata<TransactionMetadata.SendPublicPayment>(
+                        owner = sendingVault.authority.keyPair,
+                        intentId = it.id
+                    )
+                }
             },
             onFailure = {
                 logAndFail(it)
             }
         )
+        PaymentTraceRegistry.finish(correlationId, success = outcome.isSuccess, error = outcome.exceptionOrNull())
+        return outcome
     }
 
     /** Cancels the coroutine scope and clears all held state. */
diff --git a/services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/GrabBillTransactor.kt b/services/opencode/src/main/kotlin/com/getcode/opencode/internal/transactors/GrabBillTransactor.kt
@@ -13,7 +13,8 @@ import com.getcode.opencode.providers.TokenMetadataProvider
 import com.getcode.opencode.model.core.errors.SubmitIntentError
 import com.getcode.utils.CodeServerError
 import com.getcode.utils.NotifiableError
-import com.getcode.utils.timedTraceSuspend
+import com.getcode.utils.payment.PaymentTraceRegistry
+import com.getcode.utils.payment.spanSuspendOrRun
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.cancel
 
@@ -102,69 +103,59 @@ internal class GrabBillTransactor(
     private suspend fun handleMultiMintScan(
         ownerKey: AccountCluster,
         data: OpenCodePayload
-    ): Result<TransactionMetadata.SendPublicPayment> = timedTraceSuspend(
-        message = "handleMultiMintScan",
-        tag = tag,
-    ) { onStep ->
+    ): Result<TransactionMetadata.SendPublicPayment> {
+        val trace = PaymentTraceRegistry.get(data.rendezvous.publicKey)
+
         // 1. Wait for the give request from the sender so we can determine what mint we are operating on
-        val (messageId, giveRequestMint, exchangeData, mintMetadata) = messagingController.pollForGiveRequest(data.rendezvous)
-            .getOrNull()
-            ?: run {
-                onStep("pollForGiveRequest")
-                return@timedTraceSuspend logAndFail(GrabTransactorError.GiveRequestNotFound())
-            }
-        onStep("pollForGiveRequest")
+        val (messageId, giveRequestMint, exchangeData, mintMetadata) = trace.spanSuspendOrRun("pollForGiveRequest") {
+            messagingController.pollForGiveRequest(data.rendezvous).getOrNull()
+        } ?: return logAndFail(GrabTransactorError.GiveRequestNotFound())
 
         // 2. Utilize the mint from the give request to get the Token metadata
-        val token = mintMetadata
-            ?: (tokenProvider.getTokenMetadata(giveRequestMint)
-                .getOrNull()?.token
-                ?: run {
-                    onStep("tokenMetadata")
-                    return@timedTraceSuspend logAndFail(GrabTransactorError.Other(message = "No token found for proposed mint"))
-                })
-        onStep("tokenMetadata")
+        val token = trace.spanSuspendOrRun("tokenMetadata") {
+            mintMetadata ?: tokenProvider.getTokenMetadata(giveRequestMint).getOrNull()?.token
+        } ?: return logAndFail(GrabTransactorError.Other(message = "No token found for proposed mint"))
 
         val tokenizedCluster = ownerKey.withTimelockForToken(token)
 
         // 3. create an account if we don't currently have one for this token
         val needsAccount = !accountController.hasAccountFor(token.address)
         if (needsAccount) {
-            accountController.createUserAccount(
-                ownerForMint = tokenizedCluster,
-                mint = token.address
-            ).recoverCatching { error ->
-                if (error is SubmitIntentError.Denied && error.isUnexpectedOwnerAccount) {
-                    // Safety net: PR #660 mitigates the upstream cause (getUserFlags
-                    // failure preventing account bootstrap), but if the core account
-                    // still isn't set up we recover here by triggering the normal
-                    // bootstrap path before retrying.
-                    accountController.refreshAccountState()
-                    // Retry the original non-core mint account
-                    accountController.createUserAccount(
-                        ownerForMint = tokenizedCluster,
-                        mint = token.address
-                    ).getOrThrow()
-                } else {
-                    throw error
+            val creation = trace.spanSuspendOrRun("createUserAccount", metadata = mapOf("needed" to true)) {
+                accountController.createUserAccount(
+                    ownerForMint = tokenizedCluster,
+                    mint = token.address
+                ).recoverCatching { error ->
+                    if (error is SubmitIntentError.Denied && error.isUnexpectedOwnerAccount) {
+                        // Safety net: PR #660 mitigates the upstream cause (getUserFlags
+                        // failure preventing account bootstrap), but if the core account
+                        // still isn't set up we recover here by triggering the normal
+                        // bootstrap path before retrying.
+                        accountController.refreshAccountState()
+                        // Retry the original non-core mint account
+                        accountController.createUserAccount(
+                            ownerForMint = tokenizedCluster,
+                            mint = token.address
+                        ).getOrThrow()
+                    } else {
+                        throw error
+                    }
                 }
-            }.onFailure {
-                onStep("createUserAccount (needed=true)")
-                return@timedTraceSuspend handleGrabError(it)
             }
+            creation.exceptionOrNull()?.let { return handleGrabError(it) }
         }
-        onStep("createUserAccount (needed=$needsAccount)")
 
         // 4. Send grab request and wait for confirmation
-        val result = requestGrab<TransactionMetadata.SendPublicPayment>(tokenizedCluster, data)
-            .map { it.copy(verifiedExchangeData = exchangeData) }
-            .onSuccess {
-                // 5. Ack the receipt of the give request to clear it from the stream
-                messagingController.ackMessages(data.rendezvous, listOf(messageId))
-            }
-        onStep("requestGrab+ack")
+        val result = trace.spanSuspendOrRun("requestGrab") {
+            requestGrab<TransactionMetadata.SendPublicPayment>(tokenizedCluster, data)
+                .map { it.copy(verifiedExchangeData = exchangeData) }
+                .onSuccess {
+                    // 5. Ack the receipt of the give request to clear it from the stream
+                    messagingController.ackMessages(data.rendezvous, listOf(messageId))
+                }
+        }
 
-        result
+        return result
     }
 
     private fun handleGrabError(error: Throwable): Result<Nothing> {
