@sudobility/types 1.8.21

package/dist/utils/blockchain/rpc-helpers.d.ts

@@ -0,0 +1,251 @@
+/**
+ * RPC and API endpoint helper utilities
+ *
+ * Provides helper functions to build RPC endpoints and block explorer API URLs
+ * from API keys and chain identifiers.
+ */
+import { Chain, ChainType } from '../../types/business/enums';
+import { Optional } from '../../types/common';
+import type { ChainConfig } from '../../types/blockchain/common';
+/**
+ * Blockchain API keys configuration
+ */
+export interface BlockchainApis {
+    /** Alchemy API key for RPC access (supports both EVM and Solana) */
+    alchemyApiKey: string;
+    /** Etherscan Multichain API key for block explorer API access (EVM only) */
+    etherscanApiKey: string;
+}
+/**
+ * Helper class for building RPC endpoints and block explorer API URLs
+ */
+export declare class RpcHelpers {
+    /**
+     * Check if a chain is an EVM chain
+     * @param chain - Chain identifier to check
+     * @returns True if the chain is an EVM chain
+     */
+    static isEvmChain(chain: Chain): boolean;
+    /**
+     * Check if a chain is a Solana chain
+     * @param chain - Chain identifier to check
+     * @returns True if the chain is a Solana chain
+     */
+    static isSolanaChain(chain: Chain): boolean;
+    /**
+     * Get the chain type (EVM or Solana) for a given chain
+     * @param chain - Chain identifier
+     * @returns ChainType.EVM or ChainType.SOLANA
+     * @throws Error if the chain is not recognized
+     * @example
+     * ```typescript
+     * const type = RpcHelpers.getChainType(Chain.ETH_MAINNET);
+     * // Returns: ChainType.EVM
+     *
+     * const solanaType = RpcHelpers.getChainType(Chain.SOLANA_MAINNET);
+     * // Returns: ChainType.SOLANA
+     * ```
+     */
+    static getChainType(chain: Chain): ChainType;
+    /**
+     * Get the chain ID for a given chain
+     * @param chain - Chain identifier
+     * @returns Numeric chain ID for EVM chains, or negative ID for Solana chains
+     * @throws Error if the chain is not recognized or has no chain ID
+     * @example
+     * ```typescript
+     * const ethChainId = RpcHelpers.getChainId(Chain.ETH_MAINNET);
+     * // Returns: 1
+     *
+     * const polygonChainId = RpcHelpers.getChainId(Chain.POLYGON_MAINNET);
+     * // Returns: 137
+     *
+     * const solanaChainId = RpcHelpers.getChainId(Chain.SOLANA_MAINNET);
+     * // Returns: -101
+     *
+     * const localChainId = RpcHelpers.getChainId(Chain.EVM_LOCAL);
+     * // Returns: 31337
+     * ```
+     */
+    static getChainId(chain: Chain): number;
+    /**
+     * Get the USDC address/mint for a given chain
+     * @param chain - Chain identifier
+     * @returns USDC contract address for EVM chains, or mint address for Solana chains
+     * @throws Error if the chain is not recognized
+     * @example
+     * ```typescript
+     * const ethUSDC = RpcHelpers.getUSDCAddress(Chain.ETH_MAINNET);
+     * // Returns: '0xA0b86a33E6441146a8A8e27c01f0D9B1F5E42E92'
+     *
+     * const polygonUSDC = RpcHelpers.getUSDCAddress(Chain.POLYGON_MAINNET);
+     * // Returns: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
+     *
+     * const solanaUSDC = RpcHelpers.getUSDCAddress(Chain.SOLANA_MAINNET);
+     * // Returns: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+     * ```
+     */
+    static getUSDCAddress(chain: Chain): string;
+    /**
+     * Get the user-friendly display name for a chain
+     * @param chain - Chain identifier
+     * @returns Human-readable chain name
+     * @throws Error if the chain is not recognized
+     * @example
+     * ```typescript
+     * const ethName = RpcHelpers.getUserFriendlyName(Chain.ETH_MAINNET);
+     * // Returns: 'Ethereum'
+     *
+     * const polygonName = RpcHelpers.getUserFriendlyName(Chain.POLYGON_MAINNET);
+     * // Returns: 'Polygon'
+     *
+     * const sepoliaName = RpcHelpers.getUserFriendlyName(Chain.ETH_SEPOLIA);
+     * // Returns: 'Ethereum Sepolia'
+     *
+     * const localName = RpcHelpers.getUserFriendlyName(Chain.EVM_LOCAL);
+     * // Returns: 'Local EVM'
+     * ```
+     */
+    static getUserFriendlyName(chain: Chain): string;
+    /**
+     * Get the list of visible chains for the application
+     * @param isDev - Whether to include development/testnet chains
+     * @returns Array of Chain values to display
+     * @example
+     * ```typescript
+     * const prodChains = RpcHelpers.getVisibleChains(false);
+     * // Returns: [Chain.ETH_MAINNET, Chain.BASE_MAINNET, Chain.POLYGON_MAINNET, Chain.OPTIMISM_MAINNET]
+     *
+     * const devChains = RpcHelpers.getVisibleChains(true);
+     * // Returns: [Chain.ETH_MAINNET, Chain.BASE_MAINNET, Chain.POLYGON_MAINNET, Chain.OPTIMISM_MAINNET, Chain.ETH_SEPOLIA]
+     * ```
+     */
+    static getVisibleChains(isDev: boolean): Chain[];
+    /**
+     * Derive all chain information from a ChainConfig
+     * @param config - Chain configuration with API keys
+     * @returns Object with all derived chain information
+     * @example
+     * ```typescript
+     * const config: ChainConfig = {
+     *   chain: Chain.ETH_MAINNET,
+     *   alchemyApiKey: 'your-alchemy-key',
+     *   etherscanApiKey: 'your-etherscan-key'
+     * };
+     *
+     * const info = RpcHelpers.getChainInfo(config);
+     * // Returns: {
+     * //   chain: Chain.ETH_MAINNET,
+     * //   chainId: 1,
+     * //   chainType: ChainType.EVM,
+     * //   name: 'Ethereum',
+     * //   rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/your-alchemy-key',
+     * //   explorerApiUrl: 'https://api.etherscan.io/api?apikey=your-etherscan-key',
+     * //   explorerUrl: 'https://etherscan.io',
+     * //   usdcAddress: '0xA0b86a33E6441146a8A8e27c01f0D9B1F5E42E92'
+     * // }
+     * ```
+     */
+    static getChainInfo(config: ChainConfig): {
+        chain: Chain;
+        chainId: number;
+        chainType: ChainType;
+        name: string;
+        rpcUrl: Optional<string>;
+        explorerApiUrl: Optional<string>;
+        explorerUrl: Optional<string>;
+        usdcAddress: string;
+    };
+    /**
+     * Build Alchemy RPC URL for any supported chain
+     *
+     * @param alchemyApiKey - Your Alchemy API key
+     * @param chain - Chain identifier from Chain enum
+     * @returns Complete RPC URL, or undefined if API key is empty or chain is unsupported
+     *
+     * @example
+     * ```typescript
+     * const rpcUrl = RpcHelpers.getRpcUrl('your-api-key', Chain.ETH_MAINNET);
+     * // Returns: https://eth-mainnet.g.alchemy.com/v2/your-api-key
+     *
+     * const solanaUrl = RpcHelpers.getRpcUrl('your-api-key', Chain.SOLANA_MAINNET);
+     * // Returns: https://solana-mainnet.g.alchemy.com/v2/your-api-key
+     *
+     * const invalidUrl = RpcHelpers.getRpcUrl('', Chain.ETH_MAINNET);
+     * // Returns: undefined
+     * ```
+     */
+    static getRpcUrl(alchemyApiKey: string, chain: Chain): Optional<string>;
+    /**
+     * Get RPC URL using BlockchainApis configuration
+     *
+     * Convenience overload that uses the BlockchainApis structure.
+     *
+     * @param apis - Blockchain API keys configuration
+     * @param chain - Chain identifier from Chain enum
+     * @returns Complete RPC URL, or undefined if invalid
+     *
+     * @example
+     * ```typescript
+     * const apis = {
+     *   alchemyApiKey: 'your-alchemy-key',
+     *   etherscanApiKey: 'your-etherscan-key'
+     * };
+     *
+     * const ethRpcUrl = RpcHelpers.getRpcUrl(apis, Chain.ETH_MAINNET);
+     * // Returns: https://eth-mainnet.g.alchemy.com/v2/your-alchemy-key
+     * ```
+     */
+    static getRpcUrl(apis: BlockchainApis, chain: Chain): Optional<string>;
+    /**
+     * Get block explorer API URL
+     *
+     * Uses the Etherscan Multichain API key which works across 60+ EVM networks.
+     * The API key is included as a query parameter in the URL.
+     * Note: Solana chains don't have Etherscan-style API endpoints and will return undefined.
+     *
+     * @param etherscanApiKey - Your Etherscan Multichain API key (or BlockchainApis object)
+     * @param chain - Chain identifier from Chain enum
+     * @returns Complete API endpoint URL with API key, or undefined if API key is empty, chain is Solana, or no explorer API available
+     *
+     * @example
+     * ```typescript
+     * // With API key string
+     * const etherscanUrl = RpcHelpers.getExplorerApiUrl('your-api-key', Chain.ETH_MAINNET);
+     * // Returns: https://api.etherscan.io/api?apikey=your-api-key
+     *
+     * // With BlockchainApis object
+     * const apis = {
+     *   alchemyApiKey: 'your-alchemy-key',
+     *   etherscanApiKey: 'your-etherscan-key'
+     * };
+     * const explorerApiUrl = RpcHelpers.getExplorerApiUrl(apis, Chain.POLYGON_MAINNET);
+     * // Returns: https://api.polygonscan.com/api?apikey=your-etherscan-key
+     *
+     * const solanaUrl = RpcHelpers.getExplorerApiUrl('your-api-key', Chain.SOLANA_MAINNET);
+     * // Returns: undefined (Solana doesn't have Etherscan-style API)
+     * ```
+     */
+    static getExplorerApiUrl(etherscanApiKey: string, chain: Chain): Optional<string>;
+    static getExplorerApiUrl(apis: BlockchainApis, chain: Chain): Optional<string>;
+    /**
+     * Get block explorer browser URL
+     *
+     * @param chain - Chain identifier from Chain enum
+     * @returns Browser URL for the explorer, or undefined if no explorer available
+     *
+     * @example
+     * ```typescript
+     * const etherscanUrl = RpcHelpers.getBlockExplorerUrl(Chain.ETH_MAINNET);
+     * // Returns: https://etherscan.io
+     *
+     * const basescanUrl = RpcHelpers.getBlockExplorerUrl(Chain.BASE_MAINNET);
+     * // Returns: https://basescan.org
+     *
+     * const solanaUrl = RpcHelpers.getBlockExplorerUrl(Chain.SOLANA_MAINNET);
+     * // Returns: https://explorer.solana.com
+     * ```
+     */
+    static getBlockExplorerUrl(chain: Chain): Optional<string>;
+}
+//# sourceMappingURL=rpc-helpers.d.ts.map

package/dist/utils/blockchain/rpc-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/blockchain/rpc-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;CACzB;AA0wBD;;GAEG;AACH,qBAAa,UAAU;IACrB;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIxC;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI3C;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS;IAU5C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAQvC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAQ3C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAQhD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,EAAE;IAehD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW;;;;;;;;;;IAgBvC;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;IACvE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;IA0BtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,CAAC,iBAAiB,CACtB,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,KAAK,GACX,QAAQ,CAAC,MAAM,CAAC;IACnB,MAAM,CAAC,iBAAiB,CACtB,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,KAAK,GACX,QAAQ,CAAC,MAAM,CAAC;IA0BnB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;CAQ3D"}