refactor(solana): Improve RPC error detection

RPC errors must also be evaluated at the caching/aggregator layer to
avoid rotating to another provider in the event that the first provider
fails. Some failures cannot be resolved and need to be aborted
immediately.

While testing this, it was identified that SolanaError objects can be
mangled somewhere in the call stack, such that isSolanaError() doesn't
resolve true properly. It's unclear why this is the case, but introduce
a secondary option for resolving isSolanaError() via superstruct.

Author: pxrl

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@across-protocol/sdk",
   "author": "UMA Team",
-  "version": "4.3.69",
+  "version": "4.3.70",
   "license": "AGPL-3.0",
   "homepage": "https://docs.across.to/reference/sdk",
   "files": [

src/arch/svm/SpokeUtils.ts

@@ -177,7 +177,7 @@ async function _callGetTimestampForSlotWithRetry(
     const at = "getTimestampForSlot";
     const { __code: code } = err.context;
 
-    switch (err.context.__code) {
+    switch (code) {
       case SVM_SLOT_SKIPPED:
       case SVM_LONG_TERM_STORAGE_SLOT_SKIPPED:
         // No block available for this slot; caller must decide on how to handle this.

src/arch/svm/provider.ts

@@ -1,11 +1,56 @@
+import { isSolanaError as _isSolanaError } from "@solana/kit";
+import { is, type, number, string } from "superstruct";
+
 /**
  * SVM RPC provider error codes
  * See https://www.quicknode.com/docs/solana/error-references
  */
 export {
-  isSolanaError,
   SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_NOT_AVAILABLE as SVM_BLOCK_NOT_AVAILABLE,
   SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SLOT_SKIPPED as SVM_SLOT_SKIPPED,
   SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_SLOT_SKIPPED as SVM_LONG_TERM_STORAGE_SLOT_SKIPPED,
   SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE as SVM_TRANSACTION_PREFLIGHT_FAILURE,
 } from "@solana/kit";
+
+/**
+ * Superstruct schema for validating SolanaError structure.
+ * Handles serialized errors that have lost their prototype chain.
+ * Uses partial validation to allow additional properties in the context object.
+ */
+const SolanaErrorStruct = type({
+  name: string(),
+  context: type({
+    __code: number(),
+  }),
+});
+
+/**
+ * Type definition for SolanaError structure.
+ * Includes common context properties for better type inference.
+ */
+export interface SolanaErrorLike {
+  name: string;
+  context: {
+    __code: number;
+    __serverMessage?: string;
+    statusCode?: number;
+    [key: string]: unknown;
+  };
+  cause?: unknown;
+}
+
+/**
+ * Enhanced type guard to check if an error is a SolanaError.
+ *
+ * This function uses a two-tier approach:
+ * 1. First attempts the official instanceof-based check from @solana/kit
+ * 2. Falls back to structural validation using superstruct for errors that have been
+ *    serialized/deserialized (e.g., when crossing async boundaries or through JSON parsing)
+ *
+ * @param error The error to check
+ * @param code Optional error code to match against context.__code
+ * @returns True if the error is a SolanaError (or has valid SolanaError structure)
+ */
+export function isSolanaError(error: unknown): error is SolanaErrorLike {
+  return _isSolanaError(error) || is(error, SolanaErrorStruct);
+}

src/arch/svm/utils.ts

@@ -28,9 +28,6 @@ import { BigNumber, Address as SdkAddress, biMin, getMessageHash, isDefined, isU
 import { getTimestampForSlot, getSlot, getRelayDataHash } from "./SpokeUtils";
 import { AttestedCCTPMessage, EventName, SVMEventNames, SVMProvider } from "./types";
 import winston from "winston";
-
-export { isSolanaError } from "@solana/kit";
-
 /**
  * Basic void TransactionSigner type
  */

src/providers/solana/quorumFallbackRpcFactory.ts

@@ -1,9 +1,10 @@
+import { Logger } from "winston";
 import { RpcFromTransport, RpcResponse, RpcTransport, SolanaRpcApiFromTransport } from "@solana/kit";
-import { CachedSolanaRpcFactory } from "./cachedRpcFactory";
-import { SolanaBaseRpcFactory, SolanaClusterRpcFactory } from "./baseRpcFactories";
 import { isPromiseFulfilled, isPromiseRejected } from "../../utils/TypeGuards";
 import { compareSvmRpcResults, createSendErrorWithMessage } from "../utils";
-import { Logger } from "winston";
+import { CachedSolanaRpcFactory } from "./cachedRpcFactory";
+import { SolanaBaseRpcFactory, SolanaClusterRpcFactory } from "./baseRpcFactories";
+import { shouldFailImmediate } from "./utils";
 
 // This factory stores multiple Cached RPC factories so that users of this factory can specify multiple RPC providers
 // and the factory will fallback through them if any RPC calls fail. This factory also implements quorum logic amongst
@@ -64,6 +65,11 @@ export class QuorumFallbackSolanaRpcFactory extends SolanaBaseRpcFactory {
               throw error;
             }
 
+            // If one RPC provider reverted, others likely will too. Skip them.
+            if (quorumThreshold === 1 && shouldFailImmediate(method, error)) {
+              throw error;
+            }
+
             const currentFactory = factory.rpcFactory.clusterUrl;
             const nextFactory = fallbackFactories.shift()!;
             this.logger.debug({

src/providers/solana/retryRpcFactory.ts

@@ -1,10 +1,11 @@
+import { Logger } from "winston";
 import { RpcTransport, SOLANA_ERROR__RPC__TRANSPORT_HTTP_ERROR } from "@solana/kit";
 import { getThrowSolanaErrorResponseTransformer } from "@solana/rpc-transformers";
+import { isSolanaError } from "../../arch/svm";
+import { delay } from "../../utils";
 import { SolanaClusterRpcFactory } from "./baseRpcFactories";
 import { RateLimitedSolanaRpcFactory } from "./rateLimitedRpcFactory";
-import { isSolanaError, SVM_SLOT_SKIPPED, SVM_LONG_TERM_STORAGE_SLOT_SKIPPED } from "../../arch/svm";
-import { delay } from "../../utils";
-import { Logger } from "winston";
+import { shouldFailImmediate } from "./utils";
 
 // This factory adds retry logic on top of the RateLimitedSolanaRpcFactory.
 // It follows the same composition pattern as other factories in this module.
@@ -67,7 +68,7 @@ export class RetrySolanaRpcFactory extends SolanaClusterRpcFactory {
         getThrowSolanaErrorResponseTransformer()(response, { methodName: method, params });
         return response;
       } catch (error) {
-        if (retryAttempt++ >= this.retries || this.shouldFailImmediate(method, error)) {
+        if (retryAttempt++ >= this.retries || shouldFailImmediate(method, error)) {
           throw error;
         }
 
@@ -82,29 +83,6 @@ export class RetrySolanaRpcFactory extends SolanaClusterRpcFactory {
     }
   }
 
-  /**
-   * Determine whether a Solana RPC error indicates an unrecoverable error that should not be retried.
-   * @param method RPC method name
-   * @param error Error object from the RPC call
-   * @returns True if the request should be aborted immediately, otherwise false
-   */
-  private shouldFailImmediate(method: string, error: unknown): boolean {
-    if (!isSolanaError(error)) {
-      return false;
-    }
-
-    // JSON-RPC errors: https://www.quicknode.com/docs/solana/error-references
-    const { __code: code } = error.context;
-    switch (method) {
-      case "getBlock":
-      case "getBlockTime":
-        // No block at the requested slot. This may not be correct for blocks > 1 year old.
-        return [SVM_SLOT_SKIPPED, SVM_LONG_TERM_STORAGE_SLOT_SKIPPED].includes(code);
-      default:
-        return false;
-    }
-  }
-
   /**
    * Identify whether an error thrown was the result of an RPC provider 429 response.
    * @param error Error object from the RPC query.

src/providers/solana/utils.ts

@@ -1,4 +1,5 @@
 import { RpcTransport } from "@solana/rpc-spec";
+import { isSolanaError, SVM_SLOT_SKIPPED, SVM_LONG_TERM_STORAGE_SLOT_SKIPPED } from "../../arch/svm";
 
 /**
  * This is the type we pass to define a Solana RPC request "task".
@@ -12,3 +13,26 @@ export interface SolanaRateLimitTask {
   resolve: (result: unknown) => void;
   reject: (err: unknown) => void;
 }
+
+/**
+ * Determine whether a Solana RPC error indicates an unrecoverable error that should not be retried.
+ * @param method RPC method name.
+ * @param error Error object from the RPC call.
+ * @returns True if the request should be aborted immediately, otherwise false.
+ */
+export function shouldFailImmediate(method: string, error: unknown): boolean {
+  if (!isSolanaError(error)) {
+    return false;
+  }
+
+  // JSON-RPC errors: https://www.quicknode.com/docs/solana/error-references
+  const { __code: code } = error.context;
+  switch (method) {
+    case "getBlock":
+    case "getBlockTime":
+      // No block at the requested slot. This may not be correct for blocks > 1 year old.
+      return [SVM_SLOT_SKIPPED, SVM_LONG_TERM_STORAGE_SLOT_SKIPPED].includes(code);
+    default:
+      return false;
+  }
+}

test/isSolanaError.test.ts

@@ -0,0 +1,163 @@
+import { isSolanaError, SolanaErrorLike, SVM_SLOT_SKIPPED } from "../src/arch/svm/provider";
+import { expect } from "./utils";
+
+describe("isSolanaError type guard", () => {
+  it("should detect a properly structured SolanaError object", () => {
+    const error = {
+      name: "SolanaError",
+      context: {
+        __code: SVM_SLOT_SKIPPED,
+        __serverMessage: "Slot was skipped",
+      },
+    };
+
+    expect(isSolanaError(error)).to.be.true;
+  });
+
+  it("should detect a flattened/serialized SolanaError with null prototype", () => {
+    // Create a proper SolanaError-like object
+    const error = {
+      name: "SolanaError",
+      context: {
+        __code: SVM_SLOT_SKIPPED,
+        __serverMessage: "Slot was skipped",
+      },
+      cause: undefined,
+    };
+
+    // Simulate serialization/deserialization which creates null prototype objects
+    const serialized = JSON.stringify(error);
+    const flattened = JSON.parse(serialized);
+
+    // Verify the flattened error has lost its prototype chain
+    expect(Object.getPrototypeOf(flattened)).to.not.equal(Error.prototype);
+
+    // The type guard should still detect it as a SolanaError
+    expect(isSolanaError(flattened)).to.be.true;
+  });
+
+  it("should provide proper type inference for detected errors", () => {
+    const error = {
+      name: "SolanaError",
+      context: {
+        __code: -32009,
+        __serverMessage: "Test error",
+        statusCode: 429,
+      },
+    };
+
+    if (isSolanaError(error)) {
+      // These should all be accessible without type assertions
+      const code: number = error.context.__code;
+      const message: string | undefined = error.context.__serverMessage;
+      const status: number | undefined = error.context.statusCode;
+
+      expect(code).to.equal(-32009);
+      expect(message).to.equal("Test error");
+      expect(status).to.equal(429);
+    } else {
+      throw new Error("Error should have been detected as SolanaError");
+    }
+  });
+
+  it("should reject objects missing the required name field", () => {
+    const error = {
+      context: {
+        __code: SVM_SLOT_SKIPPED,
+      },
+    };
+
+    expect(isSolanaError(error)).to.be.false;
+  });
+
+  it("should reject objects missing the required __code field", () => {
+    const error = {
+      name: "SolanaError",
+      context: {},
+    };
+
+    expect(isSolanaError(error)).to.be.false;
+  });
+
+  it("should reject objects with incorrect field types", () => {
+    const error = {
+      name: "SolanaError",
+      context: {
+        __code: "not a number", // Should be number
+      },
+    };
+
+    expect(isSolanaError(error)).to.be.false;
+  });
+
+  it("should reject non-SolanaError objects", () => {
+    const regularError = new Error("Regular error");
+    expect(isSolanaError(regularError)).to.be.false;
+
+    const randomObject = { foo: "bar" };
+    expect(isSolanaError(randomObject)).to.be.false;
+
+    expect(isSolanaError(null)).to.be.false;
+    expect(isSolanaError(undefined)).to.be.false;
+    expect(isSolanaError("string")).to.be.false;
+    expect(isSolanaError(123)).to.be.false;
+  });
+
+  it("should allow additional properties in context object", () => {
+    const error = {
+      name: "SolanaError",
+      context: {
+        __code: SVM_SLOT_SKIPPED,
+        __serverMessage: "Slot was skipped",
+        statusCode: 500,
+        customField: "custom value",
+        anotherField: { nested: "object" },
+      },
+    };
+
+    expect(isSolanaError(error)).to.be.true;
+  });
+
+  it("should handle errors with cause property", () => {
+    const innerError = new Error("Inner error");
+    const error = {
+      name: "SolanaError",
+      context: {
+        __code: SVM_SLOT_SKIPPED,
+      },
+      cause: innerError,
+    };
+
+    expect(isSolanaError(error)).to.be.true;
+
+    if (isSolanaError(error)) {
+      expect(error.cause).to.equal(innerError);
+    }
+  });
+
+  it("should detect errors that have been serialized and deserialized multiple times", () => {
+    const originalError: SolanaErrorLike = {
+      name: "SolanaError",
+      context: {
+        __code: -32009,
+        __serverMessage: "Block not available",
+        statusCode: 500,
+      },
+    };
+
+    // Serialize and deserialize multiple times
+    let error: unknown = originalError;
+    for (let i = 0; i < 3; i++) {
+      error = JSON.parse(JSON.stringify(error));
+    }
+
+    // Should still be detected as a SolanaError
+    expect(isSolanaError(error)).to.be.true;
+
+    if (isSolanaError(error)) {
+      expect(error.context.__code).to.equal(-32009);
+      expect(error.context.__serverMessage).to.equal("Block not available");
+      expect(error.context.statusCode).to.equal(500);
+    }
+  });
+});