feat: refactor Blockfrost API integration and enhance error handling in governance routes

Author: Andre-Diamond

scripts/ci/README.md

@@ -422,15 +422,15 @@ Bootstrap wallets and write host-mounted artifacts:
 ```powershell
 docker compose -f docker-compose.ci.yml run --rm `
   -e CI_CONTEXT_PATH=/artifacts/ci-wallet-context.json `
-  ci-runner npx --yes tsx scripts/ci/cli/bootstrap.ts
+  ci-runner node .ci-dist/bootstrap.mjs
 ```
 
 Optional: confirm wallets are funded on-chain before running route-chain (uses `CI_CONTEXT_PATH` and `CI_BLOCKFROST_PREPROD_API_KEY`; same total-balance semantics as `walletBalanceSummary` in the route-chain report). Flags: `--json` (machine-readable summary only), `--strict` (exit with status 1 if balance collection fails).
 
 ```powershell
 docker compose -f docker-compose.ci.yml run --rm `
   -e CI_CONTEXT_PATH=/artifacts/ci-wallet-context.json `
-  ci-runner npx --yes tsx scripts/ci/cli/wallet-status.ts
+  ci-runner node .ci-dist/wallet-status.mjs
 ```
 
 Run route-chain smoke scenarios:
@@ -439,7 +439,7 @@ Run route-chain smoke scenarios:
 docker compose -f docker-compose.ci.yml run --rm `
   -e CI_CONTEXT_PATH=/artifacts/ci-wallet-context.json `
   -e CI_ROUTE_CHAIN_REPORT_PATH=/artifacts/ci-route-chain-report.md `
-  ci-runner npx --yes tsx scripts/ci/cli/route-chain.ts
+  ci-runner node .ci-dist/route-chain.mjs
 
 ```
 
@@ -512,15 +512,15 @@ Bootstrap wallets and write host-mounted artifacts:
 ```bash
 docker compose -f docker-compose.ci.yml run --rm \
   -e CI_CONTEXT_PATH=/artifacts/ci-wallet-context.json \
-  ci-runner npx --yes tsx scripts/ci/cli/bootstrap.ts
+  ci-runner node .ci-dist/bootstrap.mjs
 ```
 
 Optional: confirm wallets are funded on-chain before running route-chain (uses `CI_CONTEXT_PATH` and `CI_BLOCKFROST_PREPROD_API_KEY`; same total-balance semantics as `walletBalanceSummary` in the route-chain report). Flags: `--json` (machine-readable summary only), `--strict` (exit with status 1 if balance collection fails).
 
 ```bash
 docker compose -f docker-compose.ci.yml run --rm \
   -e CI_CONTEXT_PATH=/artifacts/ci-wallet-context.json \
-  ci-runner npx --yes tsx scripts/ci/cli/wallet-status.ts
+  ci-runner node .ci-dist/wallet-status.mjs
 ```
 
 Run route-chain smoke scenarios:
@@ -529,7 +529,7 @@ Run route-chain smoke scenarios:
 docker compose -f docker-compose.ci.yml run --rm \
   -e CI_CONTEXT_PATH=/artifacts/ci-wallet-context.json \
   -e CI_ROUTE_CHAIN_REPORT_PATH=/artifacts/ci-route-chain-report.md \
-  ci-runner npx --yes tsx scripts/ci/cli/route-chain.ts
+  ci-runner node .ci-dist/route-chain.mjs
 ```
 
 View generated report on host:

scripts/ci/scenarios/steps/governance.ts

@@ -33,7 +33,7 @@ export function createScenarioGovernanceRoutes(ctx: CIBootstrapContext): Scenari
             sourceCount?: number;
             error?: string;
           }>({
-            url: `${runCtx.apiBaseUrl}/api/v1/governanceActiveProposals?network=0&count=20&page=1&order=desc&details=false`,
+            url: `${runCtx.apiBaseUrl}/api/v1/governanceActiveProposals?network=0&count=20&page=1&order=desc&details=false&debug=true`,
             method: "GET",
             token,
           });

src/__tests__/completeTxWithFreshCostModels.test.ts

@@ -118,6 +118,10 @@ describe("refreshScriptDataHash", () => {
     costModelValues.length = 0;
     setScriptDataHashMock.mockClear();
     hashScriptDataMock.mockClear();
+    delete process.env.BLOCKFROST_API_KEY_PREPROD;
+    delete process.env.BLOCKFROST_API_KEY_MAINNET;
+    delete process.env.CI_BLOCKFROST_PREPROD_API_KEY;
+    delete process.env.CI_BLOCKFROST_MAINNET_API_KEY;
     MockTransaction.configure({ redeemerCount: 0 });
   });
 
@@ -205,4 +209,34 @@ describe("refreshScriptDataHash", () => {
       ),
     ).toThrow(/cost_models_raw/);
   });
+
+  it("uses server-side Blockfrost env names when completing transactions", async () => {
+    process.env.BLOCKFROST_API_KEY_PREPROD = "server-preprod-key";
+    const fetchMock = jest.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ cost_models_raw: { PlutusV3: [10, 20] } }),
+    } as Response);
+    const { completeTxWithFreshCostModels } = await import(
+      "@/lib/completeTxWithFreshCostModels"
+    );
+
+    await expect(
+      completeTxWithFreshCostModels(
+        {
+          complete: async () => "unsigned-tx-hex",
+        } as never,
+        0,
+      ),
+    ).resolves.toBe("unsigned-tx-hex");
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://cardano-preprod.blockfrost.io/api/v0/epochs/latest/parameters",
+      {
+        headers: {
+          project_id: "server-preprod-key",
+        },
+      },
+    );
+    fetchMock.mockRestore();
+  });
 });

src/__tests__/governanceActiveProposals.test.ts

@@ -8,6 +8,7 @@ const applyBotRateLimitMock = jest.fn<(req: NextApiRequest, res: NextApiResponse
 const verifyJwtMock = jest.fn<() => unknown>();
 const isBotJwtMock = jest.fn<() => boolean>();
 const findBotUserMock = jest.fn<() => Promise<unknown>>();
+const getProviderMock = jest.fn();
 const providerGetMock = jest.fn<(path: string) => Promise<unknown>>();
 const parseScopeMock = jest.fn<(scope: string) => string[]>();
 const scopeIncludesMock = jest.fn<(scopes: string[], required: string) => boolean>();
@@ -73,9 +74,7 @@ jest.unstable_mockModule(
   "@/utils/get-provider",
   () => ({
     __esModule: true,
-    getProvider: () => ({
-      get: providerGetMock,
-    }),
+    getProvider: getProviderMock,
   }),
 );
 
@@ -125,6 +124,9 @@ beforeEach(() => {
     id: "bot-1",
     botKey: { scope: JSON.stringify(["multisig:read", "governance:read"]) },
   });
+  getProviderMock.mockReturnValue({
+    get: providerGetMock,
+  });
 });
 
 describe("governanceActiveProposals API", () => {
@@ -310,4 +312,144 @@ describe("governanceActiveProposals API", () => {
     });
     expect(payload.activeCount).toBe(1);
   });
+
+  it("falls back to direct Blockfrost REST when provider list fetch fails without a status", async () => {
+    providerGetMock.mockImplementation(async (path) => {
+      if (path.startsWith("/governance/proposals?")) {
+        throw new Error("Internal Server Error");
+      }
+      if (path === "/governance/proposals/tx-active/0") {
+        return {
+          ratified_epoch: null,
+          enacted_epoch: null,
+          dropped_epoch: null,
+          expired_epoch: null,
+          expiration: 999,
+          deposit: "1000000",
+          return_address: "addr_test1...",
+        };
+      }
+      if (path === "/governance/proposals/tx-active/0/metadata") {
+        throw { status: 404 };
+      }
+      return null;
+    });
+    const originalKey = process.env.BLOCKFROST_API_KEY_PREPROD;
+    process.env.BLOCKFROST_API_KEY_PREPROD = "preprod-key";
+    const fetchSpy = jest.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify([
+          {
+            tx_hash: "tx-active",
+            cert_index: 0,
+            governance_type: "info_action",
+            enacted_epoch: null,
+            dropped_epoch: null,
+            expired_epoch: null,
+            ratified_epoch: null,
+          },
+        ]),
+        { status: 200 },
+      ),
+    );
+
+    try {
+      const req = {
+        method: "GET",
+        headers: { authorization: "Bearer token" },
+        query: { network: "0", count: "20", page: "1", order: "desc", details: "false" },
+      } as unknown as NextApiRequest;
+      const res = createMockResponse();
+
+      await handler(req, res);
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        "https://cardano-preprod.blockfrost.io/api/v0/governance/proposals?count=20&page=1&order=desc",
+        expect.objectContaining({
+          headers: expect.objectContaining({ project_id: "preprod-key" }),
+        }),
+      );
+      expect(res.status).toHaveBeenCalledWith(200);
+      const payload = (res.json as unknown as jest.Mock).mock.calls[0]?.[0] as any;
+      expect(payload.proposals).toHaveLength(1);
+      expect(payload.activeCount).toBe(1);
+    } finally {
+      if (originalKey === undefined) {
+        delete process.env.BLOCKFROST_API_KEY_PREPROD;
+      } else {
+        process.env.BLOCKFROST_API_KEY_PREPROD = originalKey;
+      }
+      fetchSpy.mockRestore();
+    }
+  });
+
+  it("falls back to direct Blockfrost REST when provider construction fails", async () => {
+    getProviderMock.mockImplementation(() => {
+      throw new TypeError("Cannot read properties of undefined (reading 'slice')");
+    });
+    const originalKey = process.env.BLOCKFROST_API_KEY_PREPROD;
+    process.env.BLOCKFROST_API_KEY_PREPROD = "preprod-key";
+    const fetchSpy = jest.spyOn(globalThis, "fetch").mockImplementation(async (url) => {
+      const urlString = String(url);
+      if (urlString.includes("/governance/proposals?")) {
+        return new Response(
+          JSON.stringify([
+            {
+              tx_hash: "tx-active",
+              cert_index: 0,
+              governance_type: "info_action",
+              enacted_epoch: null,
+              dropped_epoch: null,
+              expired_epoch: null,
+              ratified_epoch: null,
+            },
+          ]),
+          { status: 200 },
+        );
+      }
+      if (urlString.includes("/governance/proposals/tx-active/0/metadata")) {
+        return new Response(JSON.stringify({ error: "Not Found", status_code: 404 }), {
+          status: 404,
+        });
+      }
+      if (urlString.includes("/governance/proposals/tx-active/0")) {
+        return new Response(
+          JSON.stringify({
+            ratified_epoch: null,
+            enacted_epoch: null,
+            dropped_epoch: null,
+            expired_epoch: null,
+            expiration: 999,
+            deposit: "1000000",
+            return_address: "addr_test1...",
+          }),
+          { status: 200 },
+        );
+      }
+      return new Response(JSON.stringify({ error: "Unexpected path" }), { status: 500 });
+    });
+
+    try {
+      const req = {
+        method: "GET",
+        headers: { authorization: "Bearer token" },
+        query: { network: "0", count: "20", page: "1", order: "desc", details: "false" },
+      } as unknown as NextApiRequest;
+      const res = createMockResponse();
+
+      await handler(req, res);
+
+      expect(res.status).toHaveBeenCalledWith(200);
+      const payload = (res.json as unknown as jest.Mock).mock.calls[0]?.[0] as any;
+      expect(payload.proposals).toHaveLength(1);
+      expect(payload.activeCount).toBe(1);
+    } finally {
+      if (originalKey === undefined) {
+        delete process.env.BLOCKFROST_API_KEY_PREPROD;
+      } else {
+        process.env.BLOCKFROST_API_KEY_PREPROD = originalKey;
+      }
+      fetchSpy.mockRestore();
+    }
+  });
 });

src/lib/completeTxWithFreshCostModels.ts

@@ -23,8 +23,10 @@ function getBlockfrostProjectId(network: number): string {
   const projectId =
     network === 0
       ? process.env.CI_BLOCKFROST_PREPROD_API_KEY?.trim() ||
+        process.env.BLOCKFROST_API_KEY_PREPROD?.trim() ||
         env.NEXT_PUBLIC_BLOCKFROST_API_KEY_PREPROD?.trim()
       : process.env.CI_BLOCKFROST_MAINNET_API_KEY?.trim() ||
+        process.env.BLOCKFROST_API_KEY_MAINNET?.trim() ||
         env.NEXT_PUBLIC_BLOCKFROST_API_KEY_MAINNET?.trim();
   if (!projectId) {
     throw new Error(`Missing Blockfrost project id for network ${network}`);