feat: add transaction backfill fallback for queue ID lookups

- Add ENABLE_TX_BACKFILL_FALLBACK env var (default: false)
- Add backfill methods to TransactionDB (getBackfillHash, setBackfill, bulkSetBackfill)
- Add fallback lookup in /transaction/logs endpoint
- Add POST /admin/backfill endpoint for loading backfill data

When enabled, the /transaction/logs endpoint will check a fallback
Redis table (backfill:<queueId>) when the primary transaction cache
misses. This allows recovering transaction logs for queue IDs that
were pruned from the main cache.

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

Author: eabdelmoneim

src/server/routes/admin/backfill.ts

@@ -0,0 +1,57 @@
+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 { standardResponseSchema } from "../../schemas/shared-api-schemas";
+
+const requestBodySchema = Type.Object({
+  entries: Type.Array(
+    Type.Object({
+      queueId: Type.String({ description: "Queue ID (UUID)" }),
+      transactionHash: Type.String({ description: "Transaction hash (0x...)" }),
+    }),
+    { description: "Array of queueId to transactionHash mappings", maxItems: 10000 },
+  ),
+});
+
+const responseBodySchema = Type.Object({
+  result: Type.Object({
+    inserted: Type.Integer({ description: "Number of entries inserted" }),
+    skipped: Type.Integer({
+      description: "Number of entries skipped (already exist)",
+    }),
+  }),
+});
+
+export async function loadBackfillRoute(fastify: FastifyInstance) {
+  fastify.route<{
+    Body: Static<typeof requestBodySchema>;
+    Reply: Static<typeof responseBodySchema>;
+  }>({
+    method: "POST",
+    url: "/admin/backfill",
+    schema: {
+      summary: "Load backfill entries",
+      description:
+        "Load queueId to transactionHash mappings into the backfill table. Uses SETNX to never overwrite existing entries.",
+      tags: ["Admin"],
+      operationId: "loadBackfill",
+      body: requestBodySchema,
+      response: {
+        ...standardResponseSchema,
+        [StatusCodes.OK]: responseBodySchema,
+      },
+      hide: true,
+    },
+    handler: async (request, reply) => {
+      const { entries } = request.body;
+
+      const { inserted, skipped } =
+        await TransactionDB.bulkSetBackfill(entries);
+
+      reply.status(StatusCodes.OK).send({
+        result: { inserted, skipped },
+      });
+    },
+  });
+}

src/server/routes/index.ts

@@ -1,4 +1,5 @@
 import type { FastifyInstance } from "fastify";
+import { loadBackfillRoute } from "./admin/backfill";
 import { getNonceDetailsRoute } from "./admin/nonces";
 import { getTransactionDetails } from "./admin/transaction";
 import { createAccessToken } from "./auth/access-tokens/create";
@@ -297,4 +298,5 @@ export async function withRoutes(fastify: FastifyInstance) {
   // Admin
   await fastify.register(getTransactionDetails);
   await fastify.register(getNonceDetailsRoute);
+  await fastify.register(loadBackfillRoute);
 }

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

@@ -15,6 +15,7 @@ import { resolveContractAbi } from "thirdweb/contract";
 import type { TransactionReceipt } from "thirdweb/transaction";
 import { TransactionDB } from "../../../../shared/db/transactions/db";
 import { getChain } from "../../../../shared/utils/chain";
+import { env } from "../../../../shared/utils/env";
 import { thirdwebClient } from "../../../../shared/utils/sdk";
 import { createCustomError } from "../../../middleware/error";
 import { AddressSchema, TransactionHashSchema } from "../../../schemas/address";
@@ -153,10 +154,19 @@ export async function getTransactionLogs(fastify: FastifyInstance) {
       // Get the transaction hash from the provided input.
       let hash: Hex | undefined;
       if (queueId) {
+        // Primary lookup
         const transaction = await TransactionDB.get(queueId);
         if (transaction?.status === "mined") {
           hash = transaction.transactionHash;
         }
+
+        // Fallback to backfill table if enabled and not found
+        if (!hash && env.ENABLE_TX_BACKFILL_FALLBACK) {
+          const backfillHash = await TransactionDB.getBackfillHash(queueId);
+          if (backfillHash) {
+            hash = backfillHash as Hex;
+          }
+        }
       } else if (transactionHash) {
         hash = transactionHash as Hex;
       }

src/shared/db/transactions/db.ts

@@ -37,6 +37,7 @@ export class TransactionDB {
   private static minedTransactionsKey = "transaction:mined";
   private static cancelledTransactionsKey = "transaction:cancelled";
   private static erroredTransactionsKey = "transaction:errored";
+  private static backfillKey = (queueId: string) => `backfill:${queueId}`;
 
   /**
    * Inserts or replaces a transaction details.
@@ -208,6 +209,55 @@ export class TransactionDB {
 
     return numPruned;
   };
+
+  /**
+   * Gets transaction hash from backfill table.
+   */
+  static getBackfillHash = async (queueId: string): Promise<string | null> => {
+    return redis.get(this.backfillKey(queueId));
+  };
+
+  /**
+   * Sets a backfill entry. Uses SETNX to never overwrite.
+   * @returns true if set, false if already exists
+   */
+  static setBackfill = async (
+    queueId: string,
+    transactionHash: string,
+  ): Promise<boolean> => {
+    const result = await redis.setnx(
+      this.backfillKey(queueId),
+      transactionHash,
+    );
+    return result === 1;
+  };
+
+  /**
+   * Bulk set backfill entries.
+   * @returns { inserted: number, skipped: number }
+   */
+  static bulkSetBackfill = async (
+    entries: Array<{ queueId: string; 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);
+    }
+
+    const results = await pipeline.exec();
+    for (const [err, result] of results ?? []) {
+      if (!err && result === 1) {
+        inserted++;
+      } else {
+        skipped++;
+      }
+    }
+
+    return { inserted, skipped };
+  };
 }
 
 const toSeconds = (timestamp: Date) => timestamp.getTime() / 1000;

src/shared/utils/env.ts

@@ -98,6 +98,8 @@ export const env = createEnv({
 
     SEND_WEBHOOK_QUEUE_CONCURRENCY: z.coerce.number().default(10),
 
+    ENABLE_TX_BACKFILL_FALLBACK: boolEnvSchema(false),
+
     /**
      * Experimental env vars. These may be renamed or removed in future non-major releases.
      */
@@ -177,6 +179,7 @@ export const env = createEnv({
     EXPERIMENTAL__RETRY_PREPARE_USEROP_ERRORS:
       process.env.EXPERIMENTAL__RETRY_PREPARE_USEROP_ERRORS,
     SEND_WEBHOOK_QUEUE_CONCURRENCY: process.env.SEND_WEBHOOK_QUEUE_CONCURRENCY,
+    ENABLE_TX_BACKFILL_FALLBACK: process.env.ENABLE_TX_BACKFILL_FALLBACK,
   },
   onValidationError: (error: ZodError) => {
     console.error(