feat: extend backfill fallback to support /transaction/status endpoint

- Add BackfillEntry interface with status field ("mined" | "errored")
- Update TransactionDB to store/retrieve JSON format for backfill entries
- Add backfill fallback lookup to /transaction/status routes
- Update /transaction/logs to use new getBackfill method
- Update admin backfill schema to accept status field
- Maintain backwards compatibility for plain string tx hash entries

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: eabdelmoneim

src/server/routes/admin/backfill.ts

@@ -20,10 +20,15 @@ const loadRequestBodySchema = Type.Object({
   entries: Type.Array(
     Type.Object({
       queueId: Type.String({ description: "Queue ID (UUID)" }),
-      transactionHash: Type.String({ description: "Transaction hash (0x...)" }),
+      status: Type.Union([Type.Literal("mined"), Type.Literal("errored")], {
+        description: "Transaction status: 'mined' for successful transactions, 'errored' for failed ones",
+      }),
+      transactionHash: Type.Optional(
+        Type.String({ description: "Transaction hash (0x...). Required for mined transactions." }),
+      ),
     }),
     {
-      description: "Array of queueId to transactionHash mappings",
+      description: "Array of queueId to status/transactionHash mappings",
       maxItems: 10000,
     },
   ),

src/server/routes/transaction/blockchain/get-logs.ts

@@ -167,9 +167,9 @@ export async function getTransactionLogs(fastify: FastifyInstance) {
         // see https://github.com/thirdweb-dev/solutions-customer-scripts/blob/main/amex/scripts/load-backfill-via-api.ts
         // Fallback to backfill table if enabled and not found
         if (!hash && env.ENABLE_TX_BACKFILL_FALLBACK) {
-          const backfillHash = await TransactionDB.getBackfillHash(queueId);
-          if (backfillHash && isHex(backfillHash)) {
-            hash = backfillHash as Hex;
+          const backfill = await TransactionDB.getBackfill(queueId);
+          if (backfill?.status === "mined" && backfill.transactionHash && isHex(backfill.transactionHash)) {
+            hash = backfill.transactionHash as Hex;
           }
         }
       } else if (transactionHash) {

src/server/routes/transaction/status.ts

@@ -2,13 +2,85 @@ import { type Static, Type } from "@sinclair/typebox";
 import type { FastifyInstance } from "fastify";
 import { StatusCodes } from "http-status-codes";
 import { TransactionDB } from "../../../shared/db/transactions/db";
+import { env } from "../../../shared/utils/env";
 import { createCustomError } from "../../middleware/error";
 import { standardResponseSchema } from "../../schemas/shared-api-schemas";
 import {
   TransactionSchema,
   toTransactionSchema,
 } from "../../schemas/transaction";
 
+/**
+ * Creates a minimal transaction response from backfill data.
+ * Used when the transaction is not found in Redis but exists in the backfill table.
+ */
+const createBackfillResponse = (
+  queueId: string,
+  backfill: { status: "mined" | "errored"; transactionHash?: string },
+): Static<typeof TransactionSchema> => {
+  const baseResponse: Static<typeof TransactionSchema> = {
+    queueId,
+    status: backfill.status,
+    chainId: null,
+    fromAddress: null,
+    toAddress: null,
+    data: null,
+    extension: null,
+    value: null,
+    nonce: null,
+    gasLimit: null,
+    gasPrice: null,
+    maxFeePerGas: null,
+    maxPriorityFeePerGas: null,
+    transactionType: null,
+    transactionHash: null,
+    queuedAt: null,
+    sentAt: null,
+    minedAt: null,
+    cancelledAt: null,
+    deployedContractAddress: null,
+    deployedContractType: null,
+    errorMessage: null,
+    sentAtBlockNumber: null,
+    blockNumber: null,
+    retryCount: 0,
+    retryGasValues: null,
+    retryMaxFeePerGas: null,
+    retryMaxPriorityFeePerGas: null,
+    signerAddress: null,
+    accountAddress: null,
+    accountSalt: null,
+    accountFactoryAddress: null,
+    target: null,
+    sender: null,
+    initCode: null,
+    callData: null,
+    callGasLimit: null,
+    verificationGasLimit: null,
+    preVerificationGas: null,
+    paymasterAndData: null,
+    userOpHash: null,
+    functionName: null,
+    functionArgs: null,
+    onChainTxStatus: null,
+    onchainStatus: null,
+    effectiveGasPrice: null,
+    cumulativeGasUsed: null,
+    batchOperations: null,
+  };
+
+  if (backfill.status === "mined" && backfill.transactionHash) {
+    return {
+      ...baseResponse,
+      transactionHash: backfill.transactionHash,
+      onchainStatus: "success",
+      onChainTxStatus: 1,
+    };
+  }
+
+  return baseResponse;
+};
+
 // INPUT
 const requestSchema = Type.Object({
   queueId: Type.String({
@@ -75,6 +147,16 @@ export async function getTransactionStatusRoute(fastify: FastifyInstance) {
 
       const transaction = await TransactionDB.get(queueId);
       if (!transaction) {
+        // Fallback to backfill table if enabled
+        if (env.ENABLE_TX_BACKFILL_FALLBACK) {
+          const backfill = await TransactionDB.getBackfill(queueId);
+          if (backfill) {
+            return reply.status(StatusCodes.OK).send({
+              result: createBackfillResponse(queueId, backfill),
+            });
+          }
+        }
+
         throw createCustomError(
           "Transaction not found.",
           StatusCodes.BAD_REQUEST,
@@ -122,6 +204,16 @@ export async function getTransactionStatusQueryParamRoute(
 
       const transaction = await TransactionDB.get(queueId);
       if (!transaction) {
+        // Fallback to backfill table if enabled
+        if (env.ENABLE_TX_BACKFILL_FALLBACK) {
+          const backfill = await TransactionDB.getBackfill(queueId);
+          if (backfill) {
+            return reply.status(StatusCodes.OK).send({
+              result: createBackfillResponse(queueId, backfill),
+            });
+          }
+        }
+
         throw createCustomError(
           "Transaction not found.",
           StatusCodes.BAD_REQUEST,

src/shared/db/transactions/db.ts

@@ -2,6 +2,15 @@ import superjson from "superjson";
 import { MAX_REDIS_BATCH_SIZE, redis } from "../../utils/redis/redis";
 import type { AnyTransaction } from "../../utils/transaction/types";
 
+/**
+ * Backfill entry stored as JSON in Redis.
+ * Used for transaction status and logs fallback lookup.
+ */
+export interface BackfillEntry {
+  status: "mined" | "errored";
+  transactionHash?: string; // Only present for mined transactions
+}
+
 /**
  * Schemas
  *
@@ -211,10 +220,30 @@ export class TransactionDB {
   };
 
   /**
+   * Gets backfill entry from backfill table.
+   * Returns parsed JSON or handles backwards compatibility for plain string tx hashes.
+   */
+  static getBackfill = async (queueId: string): Promise<BackfillEntry | null> => {
+    const val = await redis.get(this.backfillKey(queueId));
+    if (!val) return null;
+    try {
+      return JSON.parse(val) as BackfillEntry;
+    } catch {
+      // Backwards compatibility: treat plain string as mined tx hash
+      return { status: "mined", transactionHash: val };
+    }
+  };
+
+  /**
+   * @deprecated Use getBackfill instead
    * Gets transaction hash from backfill table.
    */
   static getBackfillHash = async (queueId: string): Promise<string | null> => {
-    return redis.get(this.backfillKey(queueId));
+    const backfill = await this.getBackfill(queueId);
+    if (backfill?.status === "mined" && backfill.transactionHash) {
+      return backfill.transactionHash;
+    }
+    return null;
   };
 
   /**
@@ -225,9 +254,10 @@ export class TransactionDB {
     queueId: string,
     transactionHash: string,
   ): Promise<boolean> => {
+    const entry: BackfillEntry = { status: "mined", transactionHash };
     const result = await redis.setnx(
       this.backfillKey(queueId),
-      transactionHash,
+      JSON.stringify(entry),
     );
     return result === 1;
   };
@@ -237,14 +267,15 @@ export class TransactionDB {
    * @returns { inserted: number, skipped: number }
    */
   static bulkSetBackfill = async (
-    entries: Array<{ queueId: string; transactionHash: string }>,
+    entries: Array<{ queueId: string; status: "mined" | "errored"; transactionHash?: string }>,
   ): Promise<{ inserted: number; skipped: number }> => {
     let inserted = 0;
     let skipped = 0;
 
     const pipeline = redis.pipeline();
-    for (const { queueId, transactionHash } of entries) {
-      pipeline.setnx(this.backfillKey(queueId), transactionHash);
+    for (const { queueId, status, transactionHash } of entries) {
+      const entry: BackfillEntry = { status, transactionHash };
+      pipeline.setnx(this.backfillKey(queueId), JSON.stringify(entry));
     }
 
     const results = await pipeline.exec();