Merge pull request #201 from IntersectMBO/fix/cert-redeemer-evaluation

fix(evaluation): normalize Blockfrost JSONWSP v5 redeemer tags and fail fast on unmatched results

Author: solidsnakedev

.changeset/fix-cert-redeemer-evaluation.md

@@ -0,0 +1,5 @@
+---
+"@evolution-sdk/evolution": patch
+---
+
+Script transactions with certificate or withdrawal redeemers evaluated via Blockfrost no longer spam warning logs or loop indefinitely. Blockfrost's Ogmios v5 JSONWSP format returns `"certificate:N"` and `"withdrawal:N"` as redeemer pointer keys; these are now normalized to the canonical `"cert"` and `"reward"` tags before evaluation matching. Unmatched redeemer tags from any evaluator now fail immediately instead of silently leaving ExUnits at zero.

packages/evolution/src/sdk/builders/phases/Evaluation.ts

@@ -162,8 +162,11 @@ const resolveDeferredRedeemers = (
         const utxo = refToUtxo.get(key)
 
         if (index === undefined || !utxo) {
-          yield* Effect.logWarning(`[Evaluation] Could not resolve self redeemer for ${key} - UTxO not in transaction`)
-          continue
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Self redeemer for ${key} could not be resolved: UTxO is not present in the transaction inputs`
+            })
+          )
         }
 
         const indexedInput: IndexedInput = { index, utxo }
@@ -196,8 +199,11 @@ const resolveDeferredRedeemers = (
         }
 
         if (batchInputs.length === 0) {
-          yield* Effect.logWarning(`[Evaluation] Batch redeemer for ${key} has no resolved inputs`)
-          continue
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Batch redeemer for ${key} has no resolved inputs: none of the specified UTxOs are present in the transaction`
+            })
+          )
         }
 
         // Sort by index for consistent ordering
@@ -559,10 +565,11 @@ export const executeEvaluation = (): Effect.Effect<
         // For spend redeemers, map input index to UTxO reference
         const utxoRef = inputIndexMapping.get(evalRedeemer.redeemer_index)
         if (!utxoRef) {
-          yield* Effect.logWarning(
-            `[Evaluation] Could not map input index ${evalRedeemer.redeemer_index} to UTxO reference`
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned spend result at index ${evalRedeemer.redeemer_index} but no UTxO exists at that position in the transaction`
+            })
           )
-          continue
         }
 
         const redeemer = evaluatedRedeemers.get(utxoRef)
@@ -578,14 +585,21 @@ export const executeEvaluation = (): Effect.Effect<
               `mem=${evalRedeemer.ex_units.mem}, steps=${evalRedeemer.ex_units.steps}`
           )
         } else {
-          yield* Effect.logWarning(`[Evaluation] No redeemer found in state for UTxO ${utxoRef}`)
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned spend result for ${utxoRef} but no redeemer exists in builder state for that UTxO`
+            })
+          )
         }
       } else if (evalRedeemer.redeemer_tag === "mint") {
         // For mint redeemers, map mint index to policy ID hex
         const policyIdHex = mintIndexMapping.get(evalRedeemer.redeemer_index)
         if (!policyIdHex) {
-          yield* Effect.logWarning(`[Evaluation] Could not map mint index ${evalRedeemer.redeemer_index} to policy ID`)
-          continue
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned mint result at index ${evalRedeemer.redeemer_index} but no policy exists at that position in the transaction`
+            })
+          )
         }
 
         const redeemer = evaluatedRedeemers.get(policyIdHex)
@@ -601,14 +615,21 @@ export const executeEvaluation = (): Effect.Effect<
               `mem=${evalRedeemer.ex_units.mem}, steps=${evalRedeemer.ex_units.steps}`
           )
         } else {
-          yield* Effect.logWarning(`[Evaluation] No redeemer found in state for policy ${policyIdHex}`)
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned mint result for policy ${policyIdHex} but no redeemer exists in builder state for that policy`
+            })
+          )
         }
       } else if (evalRedeemer.redeemer_tag === "cert") {
         // For certificate redeemers, map index to credential key
         const certKey = certIndexMapping.get(evalRedeemer.redeemer_index)
         if (!certKey) {
-          yield* Effect.logWarning(`[Evaluation] Could not map cert index ${evalRedeemer.redeemer_index} to credential`)
-          continue
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned cert result at index ${evalRedeemer.redeemer_index} but no certificate exists at that position in the transaction`
+            })
+          )
         }
 
         const redeemer = evaluatedRedeemers.get(certKey)
@@ -624,16 +645,21 @@ export const executeEvaluation = (): Effect.Effect<
               `mem=${evalRedeemer.ex_units.mem}, steps=${evalRedeemer.ex_units.steps}`
           )
         } else {
-          yield* Effect.logWarning(`[Evaluation] No redeemer found in state for cert ${certKey}`)
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned cert result for ${certKey} but no redeemer exists in builder state for that credential`
+            })
+          )
         }
       } else if (evalRedeemer.redeemer_tag === "reward") {
         // For withdrawal redeemers, map index to credential key
         const rewardKey = withdrawalIndexMapping.get(evalRedeemer.redeemer_index)
         if (!rewardKey) {
-          yield* Effect.logWarning(
-            `[Evaluation] Could not map withdrawal index ${evalRedeemer.redeemer_index} to credential`
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned reward result at index ${evalRedeemer.redeemer_index} but no withdrawal exists at that position in the transaction`
+            })
           )
-          continue
         }
 
         const redeemer = evaluatedRedeemers.get(rewardKey)
@@ -649,14 +675,21 @@ export const executeEvaluation = (): Effect.Effect<
               `mem=${evalRedeemer.ex_units.mem}, steps=${evalRedeemer.ex_units.steps}`
           )
         } else {
-          yield* Effect.logWarning(`[Evaluation] No redeemer found in state for withdrawal ${rewardKey}`)
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned reward result for ${rewardKey} but no redeemer exists in builder state for that withdrawal`
+            })
+          )
         }
       } else if (evalRedeemer.redeemer_tag === "vote") {
         // For vote redeemers, map index to voter key
         const voterKey = voteIndexMapping.get(evalRedeemer.redeemer_index)
         if (!voterKey) {
-          yield* Effect.logWarning(`[Evaluation] Could not map vote index ${evalRedeemer.redeemer_index} to voter`)
-          continue
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned vote result at index ${evalRedeemer.redeemer_index} but no voter exists at that position in the transaction`
+            })
+          )
         }
 
         const redeemer = evaluatedRedeemers.get(voterKey)
@@ -675,12 +708,20 @@ export const executeEvaluation = (): Effect.Effect<
               `mem=${evalRedeemer.ex_units.mem}, steps=${evalRedeemer.ex_units.steps}`
           )
         } else {
-          yield* Effect.logWarning(`[Evaluation] No redeemer found in state for vote ${voterKey}`)
+          return yield* Effect.fail(
+            new TransactionBuilderError({
+              message: `Evaluator returned vote result for ${voterKey} but no redeemer exists in builder state for that voter`
+            })
+          )
         }
       } else {
-        // Unknown redeemer type
-        yield* Effect.logWarning(
-          `[Evaluation] Unknown redeemer type ${evalRedeemer.redeemer_tag} not yet supported for matching`
+        // Unknown redeemer type returned by the evaluator — fail immediately.
+        // Silently ignoring this would leave the redeemer at exUnits = 0, which
+        // looks "unevaluated" to Balance and triggers an infinite retry loop.
+        return yield* Effect.fail(
+          new TransactionBuilderError({
+            message: `Evaluator returned unknown redeemer tag "${evalRedeemer.redeemer_tag}" at index ${evalRedeemer.redeemer_index}. This is likely a provider bug or an unsupported evaluator format.`
+          })
         )
       }
     }

packages/evolution/src/sdk/provider/internal/Blockfrost.ts

@@ -274,9 +274,12 @@ export const transformJsonwspOgmiosEvaluationResult = (
   const result: Array<EvalRedeemer> = []
 
   for (const [key, budget] of Object.entries(evaluationResult)) {
-    // Parse "spend:0", "mint:1", etc.
-    const [tag, indexStr] = key.split(":")
+    // Parse "spend:0", "mint:1", "certificate:0", "withdrawal:0", etc.
+    // Blockfrost uses Ogmios v5 JSONWSP which returns "certificate" and "withdrawal";
+    // normalize to the SDK's canonical tags "cert" and "reward" (Ogmios v6 / CDDL names).
+    const [rawTag, indexStr] = key.split(":")
     const index = parseInt(indexStr, 10)
+    const tag = rawTag === "certificate" ? "cert" : rawTag === "withdrawal" ? "reward" : rawTag
 
     result.push({
       ex_units: new Redeemer.ExUnits({