feat(programs): add program adapter interface and factory implementation

Author: cctdaniel

governance/xc_admin/packages/xc_admin_common/src/index.ts

@@ -14,3 +14,8 @@ export * from "./chains";
 export * from "./deterministic_stake_accounts";
 export * from "./price_store";
 export { default as lazerIdl } from "./multisig_transaction/idl/lazer.json";
+
+// Export program-related modules
+export * from "./programs/program_adapter";
+export * from "./programs/types";
+export * from "./programs/adapter_factory";

governance/xc_admin/packages/xc_admin_common/src/programs/adapter_factory.ts

@@ -0,0 +1,23 @@
+import { ProgramAdapter } from "./program_adapter";
+import { ProgramType } from "./types";
+
+/**
+ * Factory function to get the appropriate program adapter based on program type.
+ *
+ * @param type The type of program to get the adapter for
+ * @returns The corresponding program adapter
+ * @throws Error if the adapter for the given program type is not implemented
+ */
+export function getProgramAdapter(type: ProgramType): ProgramAdapter {
+  switch (type) {
+    case ProgramType.PYTH_CORE:
+      // Will be implemented in a future commit
+      throw new Error("Pyth Core adapter not yet implemented");
+    case ProgramType.PYTH_LAZER:
+      // Will be implemented in a future commit
+      throw new Error("Pyth Lazer adapter not yet implemented");
+    default:
+      const exhaustiveCheck: never = type;
+      throw new Error(`Unknown program type: ${exhaustiveCheck}`);
+  }
+}

governance/xc_admin/packages/xc_admin_common/src/programs/program_adapter.ts

@@ -0,0 +1,92 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import { PythCluster } from "@pythnetwork/client";
+
+/**
+ * Program adapter interface that defines the contract for interacting with
+ * different Pyth programs (Core, Lazer, etc).
+ *
+ * This adapter pattern allows the frontend to use a consistent interface
+ * while supporting multiple program implementations.
+ */
+export interface ProgramAdapter {
+  /**
+   * Program address on Solana
+   * Each program may have different addresses on different clusters
+   */
+  getProgramAddress(cluster: PythCluster): PublicKey;
+
+  /**
+   * Human-readable name of the program
+   */
+  readonly name: string;
+
+  /**
+   * Brief description of the program
+   */
+  readonly description: string;
+
+  /**
+   * Type identifier for the program
+   */
+  readonly type: string;
+
+  /**
+   * Parse raw on-chain accounts into a standardized configuration object
+   * for the specific program.
+   *
+   * @param accounts Array of account data from the blockchain
+   * @param cluster The Pyth cluster where the accounts were fetched from
+   * @returns Program-specific configuration object
+   */
+  getConfigFromRawAccounts(accounts: any[], cluster: PythCluster): any;
+
+  /**
+   * Format the configuration for downloading as a JSON file
+   *
+   * @param config The program's configuration object
+   * @returns Configuration formatted for download
+   */
+  getDownloadableConfig(config: any): any;
+
+  /**
+   * Validate an uploaded configuration against the current configuration
+   *
+   * @param existingConfig Current configuration
+   * @param uploadedConfig Configuration from an uploaded file
+   * @returns Object with validation result and optional error message
+   */
+  validateUploadedConfig(
+    existingConfig: any,
+    uploadedConfig: any,
+    cluster: PythCluster,
+  ): {
+    isValid: boolean;
+    error?: string;
+    changes?: any;
+  };
+
+  /**
+   * Generate the necessary instructions to apply configuration changes
+   *
+   * @param changes Configuration changes to apply
+   * @param cluster The Pyth cluster where the changes will be applied
+   * @param accounts Additional context needed for generating instructions
+   * @returns Promise resolving to an array of TransactionInstructions
+   */
+  generateInstructions(
+    changes: any,
+    cluster: PythCluster,
+    accounts: {
+      fundingAccount: PublicKey;
+      [key: string]: any;
+    },
+  ): Promise<TransactionInstruction[]>;
+
+  /**
+   * Check if the program is available on the specified cluster
+   *
+   * @param cluster The Pyth cluster to check
+   * @returns True if the program is available on the cluster
+   */
+  isAvailableOnCluster(cluster: PythCluster): boolean;
+}

governance/xc_admin/packages/xc_admin_common/src/programs/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Represents the different Pyth programs supported by the application.
+ */
+export enum ProgramType {
+  /**
+   * Original Pyth oracle program
+   */
+  PYTH_CORE = "PYTH_CORE",
+
+  /**
+   * Next-generation Pyth oracle program
+   */
+  PYTH_LAZER = "PYTH_LAZER",
+}