feat(validation/rpc): implement Soroban RPC response schema validator

apps/api/src/validation/rpc/stellar/errors.ts

@@ -0,0 +1,6 @@
+export class RpcValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RpcValidationError";
+  }
+}

apps/api/src/validation/rpc/stellar/index.ts

@@ -0,0 +1,3 @@
+export * from "./validator";
+export * from "./types";
+export * from "./errors";

apps/api/src/validation/rpc/stellar/schemas.ts

@@ -0,0 +1,36 @@
+export function isObject(val: any): val is Record<string, any> {
+  return val !== null && typeof val === "object" && !Array.isArray(val);
+}
+
+export function validateBaseRpcShape(payload: any): string | null {
+  if (!isObject(payload)) return "RPC response must be an object";
+
+  if (payload.jsonrpc !== "2.0") {
+    return "Invalid jsonrpc version (expected '2.0')";
+  }
+
+  if (payload.id === undefined) {
+    return "Missing RPC id";
+  }
+
+  const hasResult = "result" in payload;
+  const hasError = "error" in payload;
+
+  if (!hasResult && !hasError) {
+    return "RPC response must contain either result or error";
+  }
+
+  if (hasResult && hasError) {
+    return "RPC response cannot contain both result and error";
+  }
+
+  if (hasError) {
+    const err = payload.error;
+    if (!isObject(err)) return "Invalid error object";
+
+    if (typeof err.code !== "number") return "Error code must be a number";
+    if (typeof err.message !== "string") return "Error message must be a string";
+  }
+
+  return null;
+}

apps/api/src/validation/rpc/stellar/types.ts

@@ -0,0 +1,16 @@
+export type SorobanRpcResponse<T = any> = {
+  jsonrpc: string;
+  id: number | string | null;
+  result?: T;
+  error?: {
+    code: number;
+    message: string;
+    data?: any;
+  };
+};
+
+export type ValidateResult<T> = {
+  valid: boolean;
+  data?: T;
+  error?: string;
+};

apps/api/src/validation/rpc/stellar/validator.ts

@@ -0,0 +1,50 @@
+import { validateBaseRpcShape } from "./schemas";
+import { RpcValidationError } from "./errors";
+import { SorobanRpcResponse, ValidateResult } from "./types";
+
+export class SorobanRpcValidator {
+  /**
+   * Strict validation (throws on failure)
+   */
+  static validateOrThrow<T = any>(payload: any): SorobanRpcResponse<T> {
+    const error = validateBaseRpcShape(payload);
+
+    if (error) {
+      throw new RpcValidationError(error);
+    }
+
+    return payload;
+  }
+
+  /**
+   * Safe validation (returns structured result)
+   */
+  static validate<T = any>(payload: any): ValidateResult<T> {
+    const error = validateBaseRpcShape(payload);
+
+    if (error) {
+      return {
+        valid: false,
+        error,
+      };
+    }
+
+    return {
+      valid: true,
+      data: payload,
+    };
+  }
+
+  /**
+   * Validates only successful RPC responses
+   */
+  static validateResult<T = any>(payload: any): T {
+    const validated = this.validateOrThrow<SorobanRpcResponse<T>>(payload);
+
+    if (validated.error) {
+      throw new RpcValidationError(validated.error.message);
+    }
+
+    return validated.result as T;
+  }
+}