@circle-fin/adapter-ethers-v6 0.0.2-alpha.7 → 1.0.0

package/index.mjs

@@ -2441,6 +2441,11 @@ const baseChainDefinitionSchema = z.object({
     eurcAddress: z.string().nullable(),
     usdcAddress: z.string().nullable(),
     cctp: z.any().nullable(), // We'll accept any CCTP config structure
+    kitContracts: z
+        .object({
+        bridge: z.string().optional(),
+    })
+        .optional(),
 });
 /**
  * Zod schema for validating EVM chain definitions specifically.
@@ -2472,13 +2477,15 @@ const baseChainDefinitionSchema = z.object({
  * }
  * ```
  */
-const evmChainDefinitionSchema = baseChainDefinitionSchema.extend({
+const evmChainDefinitionSchema = baseChainDefinitionSchema
+    .extend({
     type: z.literal('evm'),
     chainId: z.number({
         required_error: 'EVM chains must have a chainId. Please provide a valid EVM chain ID.',
         invalid_type_error: 'EVM chain ID must be a number.',
     }),
-});
+})
+    .strict(); //// Reject any additional properties not defined in the schema
 /**
  * Zod schema for validating non-EVM chain definitions.
  * This schema extends the base schema with non-EVM specific properties.
@@ -2498,7 +2505,7 @@ const nonEvmChainDefinitionSchema = baseChainDefinitionSchema
         'polkadot',
     ]),
 })
-    .strict(); // Reject additional properties like chainId
+    .strict(); // Reject any additional properties not defined in the schema
 /**
  * Discriminated union schema for all chain definitions.
  * This schema validates different chain types based on their 'type' field.
@@ -2980,67 +2987,37 @@ class KitError extends Error {
 }
 
 /**
- * Standardized error codes for INPUT type errors.
+ * Standardized error definitions for INPUT type errors.
+ *
+ * Each entry combines the numeric error code with its corresponding
+ * string name to ensure consistency when creating error instances.
  *
  * Error codes follow a hierarchical numbering scheme where the first digit
  * indicates the error category (1 = INPUT) and subsequent digits provide
  * specific error identification within that category.
  *
+ *
  * @example
  * ```typescript
- * import { InputErrorCode, InputErrorName } from '@core/errors'
+ * import { InputError } from '@core/errors'
  *
  * const error = new KitError({
- *   code: InputErrorCode.NETWORK_MISMATCH,
- *   name: InputErrorName.NETWORK_MISMATCH,
+ *   ...InputError.NETWORK_MISMATCH,
  *   recoverability: 'FATAL',
  *   message: 'Source and destination networks must be different'
  * })
- * ```
- */
-var InputErrorCode;
-(function (InputErrorCode) {
-    /** Network type mismatch between chains (mainnet vs testnet) */
-    InputErrorCode[InputErrorCode["NETWORK_MISMATCH"] = 1001] = "NETWORK_MISMATCH";
-    /** Invalid amount format or value (negative, zero, or malformed) */
-    InputErrorCode[InputErrorCode["INVALID_AMOUNT"] = 1002] = "INVALID_AMOUNT";
-    /** Unsupported or invalid bridge route configuration */
-    InputErrorCode[InputErrorCode["UNSUPPORTED_ROUTE"] = 1003] = "UNSUPPORTED_ROUTE";
-    /** Invalid wallet or contract address format */
-    InputErrorCode[InputErrorCode["INVALID_ADDRESS"] = 1004] = "INVALID_ADDRESS";
-    /** Invalid or unsupported chain identifier */
-    InputErrorCode[InputErrorCode["INVALID_CHAIN"] = 1005] = "INVALID_CHAIN";
-    /** General validation failure for complex validation rules */
-    InputErrorCode[InputErrorCode["VALIDATION_FAILED"] = 1098] = "VALIDATION_FAILED";
-})(InputErrorCode || (InputErrorCode = {}));
-/**
- * Standardized error names for INPUT type errors.
- *
- * These names correspond 1:1 with InputErrorCode and should always
- * be used together to ensure consistency across error instances.
  *
- * @example
- * ```typescript
- * import { InputErrorCode, InputErrorName } from '@core/errors'
- *
- * // Use matching code and name enums
- * const error = new KitError({
- *   code: InputErrorCode.NETWORK_MISMATCH,
- *   name: InputErrorName.NETWORK_MISMATCH,
- *   recoverability: 'FATAL',
- *   message: 'Network mismatch detected'
- * })
+ * // Access code and name individually if needed
+ * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
+ * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
  * ```
  */
-var InputErrorName;
-(function (InputErrorName) {
-    InputErrorName["NETWORK_MISMATCH"] = "INPUT_NETWORK_MISMATCH";
-    InputErrorName["INVALID_AMOUNT"] = "INPUT_INVALID_AMOUNT";
-    InputErrorName["UNSUPPORTED_ROUTE"] = "INPUT_UNSUPPORTED_ROUTE";
-    InputErrorName["INVALID_ADDRESS"] = "INPUT_INVALID_ADDRESS";
-    InputErrorName["INVALID_CHAIN"] = "INPUT_INVALID_CHAIN";
-    InputErrorName["VALIDATION_FAILED"] = "INPUT_VALIDATION_FAILED";
-})(InputErrorName || (InputErrorName = {}));
+const InputError = {
+    /** Unsupported or invalid bridge route configuration */
+    UNSUPPORTED_ROUTE: {
+        code: 1003,
+        name: 'INPUT_UNSUPPORTED_ROUTE',
+    }};
 
 /**
  * Creates error for unsupported bridge route.
@@ -3062,8 +3039,7 @@ var InputErrorName;
  */
 function createUnsupportedRouteError(source, destination) {
     const errorDetails = {
-        code: InputErrorCode.UNSUPPORTED_ROUTE,
-        name: InputErrorName.UNSUPPORTED_ROUTE,
+        ...InputError.UNSUPPORTED_ROUTE,
         recoverability: 'FATAL',
         message: `Route from ${source} to ${destination} is not supported.`,
         cause: {
@@ -3112,26 +3088,6 @@ class Adapter {
      * ```
      */
     capabilities;
-    /**
-     * Default chain for operations when none is explicitly provided.
-     *
-     * This allows adapters to have sensible defaults for chain operations,
-     * reducing the need for explicit chain specification in every call.
-     *
-     * @remarks
-     * This is optional for backward compatibility and because some adapter types
-     * (like developer-controlled adapters) may not have meaningful defaults.
-     *
-     * @example
-     * ```typescript
-     * // User-controlled adapter with default chain
-     * defaultChain = Ethereum
-     *
-     * // Developer-controlled adapter (no default)
-     * defaultChain = undefined
-     * ```
-     */
-    defaultChain;
     /**
      * Registry of available actions for this adapter.
      *
@@ -3203,17 +3159,14 @@ class Adapter {
      * - **Browser wallet adapters**: Request chain switch via EIP-1193 or equivalent
      * - **Multi-entity adapters**: Validate chain support (operations are contextual)
      *
-     * @param chain - The target chain for operations. If not provided, uses the adapter's defaultChain.
+     * @param chain - The target chain for operations.
      * @returns A promise that resolves when the adapter is operating on the specified chain.
      * @throws When the target chain is not supported or chain switching fails.
      *
      * @remarks
-     * This method replaces the pattern of calling `getChain()` to check current chain and then
-     * manually switching. It provides a declarative "ensure this chain" interface for operations.
-     *
-     * **Backward Compatibility**: The default implementation provides basic validation but
-     * doesn't perform actual chain switching. Concrete adapter implementations should override
-     * this method to provide proper chain switching logic.
+     * This method always calls `switchToChain()` to ensure consistency across all adapter types.
+     * The underlying implementations handle idempotent switching efficiently (e.g., browser wallets
+     * gracefully handle switching to the current chain, private key adapters recreate lightweight clients).
      *
      * @example
      * ```typescript
@@ -3227,25 +3180,9 @@ class Adapter {
      * await circleWalletsAdapter.ensureChain(Ethereum)
      * ```
      */
-    async ensureChain(chain) {
-        const targetChain = chain ?? this.defaultChain;
-        if (!targetChain) {
-            return;
-        }
+    async ensureChain(targetChain) {
         this.validateChainSupport(targetChain);
-        // Check if already on the target chain (skip for developer-controlled adapters)
-        if (this.capabilities?.addressContext !== 'developer-controlled') {
-            try {
-                const currentChain = await this.getChain();
-                if (currentChain.chain === targetChain.chain) {
-                    return; // Already on the correct chain
-                }
-            }
-            catch {
-                // If getChain() fails, we'll proceed with switching anyway
-            }
-        }
-        // Delegate actual switching to the concrete implementation
+        // Always delegate to switchToChain - implementations handle idempotent switching
         try {
             await this.switchToChain(targetChain);
         }
@@ -3808,7 +3745,6 @@ base58StringSchema.refine((value) => value.length >= 86 && value.length <= 88, '
 const adapterSchema = z.object({
     prepare: z.function(),
     waitForTransaction: z.function(),
-    getChain: z.function(),
     getAddress: z.function(),
 });
 
@@ -8444,7 +8380,6 @@ const abiSchema = z
  * - A chainType property set to 'evm'
  * - An actionRegistry with registerHandlers method and actionHandlers record
  * - A prepare method for creating chain requests
- * - A getChain method for retrieving chain configuration
  *
  * @throws \{ValidationError\} If validation fails, with details about which properties failed
  *
@@ -8461,7 +8396,6 @@ const abiSchema = z
  *     }
  *   },
  *   prepare: async (request: any) => ({}),
- *   getChain: async () => ({ name: 'Ethereum', type: 'evm' as const })
  * }
  *
  * const result = evmAdapterSchema.safeParse(validAdapter)
@@ -8563,6 +8497,44 @@ const evmTransactionHashSchema = z
     .refine((hash) => /^0x[0-9a-fA-F]{64}$/.test(hash), (hash) => ({
     message: `Transaction hash "${hash}" contains invalid characters. Only hexadecimal characters (0-9, a-f, A-F) are allowed after '0x'.`,
 }));
+/**
+ * Zod schema for validating EVM private keys.
+ *
+ * This schema validates private key strings to ensure they are properly formatted:
+ * - Accepts private keys with or without '0x' prefix
+ * - Automatically normalizes by adding '0x' prefix if missing
+ * - Validates that the key is exactly 64 hexadecimal characters (32 bytes)
+ * - Ensures only valid hexadecimal characters (0-9, a-f, A-F) are used
+ *
+ * @remarks
+ * This is a shared schema used by both ethers.v6 and viem.v2 adapters to ensure
+ * consistent private key validation across all EVM adapters.
+ *
+ * @throws \{ValidationError\} If validation fails, with details about the issue
+ *
+ * @example
+ * ```typescript
+ * import { evmPrivateKeySchema } from '@core/adapter-evm/validation'
+ *
+ * // Both formats are accepted and normalized
+ * const keyWithPrefix = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ * const keyWithoutPrefix = '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ *
+ * const result1 = evmPrivateKeySchema.safeParse(keyWithPrefix)
+ * const result2 = evmPrivateKeySchema.safeParse(keyWithoutPrefix)
+ *
+ * // Both succeed and produce the same normalized result with '0x' prefix
+ * ```
+ */
+const evmPrivateKeySchema = z
+    .string({
+    required_error: 'Private key is required. Please provide a valid private key.',
+    invalid_type_error: 'Private key must be a string. Please provide a valid private key.',
+})
+    .transform((val) => (val.startsWith('0x') ? val : `0x${val}`))
+    .pipe(z.string().regex(/^0x[0-9a-fA-F]{64}$/, {
+    message: 'Private key must be a valid 64-character hex string. Please provide a valid private key with or without "0x" prefix.',
+}));
 
 const assertEvmPreparedChainRequestParamsSymbol = Symbol('assertEvmPreparedChainRequestParams');
 /**
@@ -9331,7 +9303,7 @@ const ethersAdapterOptionsSchema = z.object({
  * Zod schema for validating parameters to create an EthersAdapter from a private key.
  *
  * @remarks
- * - `privateKey` must be a string starting with "0x" and 64 hexadecimal characters.
+ * - `privateKey` can be provided with or without the "0x" prefix. The schema automatically normalizes keys by adding the "0x" prefix if missing before validation.
  * - `getProvider` is optional and, if provided, must be a function accepting an object with a `chain` parameter and returning any value.
  * - `capabilities` is optional and allows partial overrides with smart defaults.
  *
@@ -9339,27 +9311,22 @@ const ethersAdapterOptionsSchema = z.object({
  * ```typescript
  * import { createAdapterFromPrivateKeyParamsSchema } from '@circle-fin/adapter-ethers-v6/validation'
  *
- * const params = {
+ * // Both formats are supported:
+ * const paramsWithPrefix = {
  *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
  * }
  *
- * const result = createAdapterFromPrivateKeyParamsSchema.safeParse(params)
- * if (result.success) {
- *   console.log('Parameters are valid')
- * } else {
- *   console.error('Validation failed:', result.error)
+ * const paramsWithoutPrefix = {
+ *   privateKey: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
  * }
+ *
+ * const result1 = createAdapterFromPrivateKeyParamsSchema.safeParse(paramsWithPrefix)
+ * const result2 = createAdapterFromPrivateKeyParamsSchema.safeParse(paramsWithoutPrefix)
+ * // Both succeed and produce the same normalized result
  * ```
  */
 const createAdapterFromPrivateKeyParamsSchema = z.object({
-    privateKey: z
-        .string({
-        required_error: 'Private key is required. Please provide a valid private key.',
-        invalid_type_error: 'Private key must be a string. Please provide a valid private key.',
-    })
-        .regex(/^0x[0-9a-fA-F]{64}$/, {
-        message: 'Private key must be a 64-character hexadecimal string prefixed with "0x".',
-    }),
+    privateKey: evmPrivateKeySchema,
     getProvider: z
         .function()
         .args(z.object({ chain: z.unknown() }))
@@ -9468,28 +9435,6 @@ z.object({
 function validateEthersAdapterOptions(options) {
     validate(options, ethersAdapterOptionsSchema, 'EthersAdapterOptions');
 }
-/**
- * Validates parameters for creating an Ethers adapter from a private key.
- *
- * This function validates the parameters used by the createAdapterFromPrivateKey
- * factory function for the Ethers adapter.
- *
- * @param params - The parameters to validate. Must include a `privateKey` string and optionally a `getProvider` function and `capabilities`.
- * @throws \{ValidationError\} If validation fails.
- * @example
- * ```typescript
- * import { validateCreateAdapterFromPrivateKeyParams } from '@circle-fin/adapter-ethers-v6/validation'
- *
- * const params = {
- *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
- * }
- *
- * validateCreateAdapterFromPrivateKeyParams(params) // throws if invalid
- * ```
- */
-function validateCreateAdapterFromPrivateKeyParams(params) {
-    validate(params, createAdapterFromPrivateKeyParamsSchema, 'CreateAdapterFromPrivateKeyParams');
-}
 /**
  * Validates parameters for creating an Ethers adapter from an EIP-1193 provider.
  *
@@ -10046,45 +9991,6 @@ class EthersAdapter extends EvmAdapter {
         const address = await signer.getAddress();
         return address;
     }
-    /**
-     * Gets the current chain definition.
-     *
-     * TEMP This method is temporary and will be removed once all adapters migrate to the OperationContext pattern.
-     *
-     * **Migration Guide:**
-     *
-     * With the OperationContext pattern, chain information is provided explicitly in each operation
-     * rather than queried from the adapter. This eliminates ambiguity and enables seamless multi-chain
-     * operations with a single adapter instance.
-     *
-     * **Before (Deprecated):**
-     * ```typescript
-     * const chain = await adapter.getChain()
-     * const prepared = await adapter.prepare(params) // Uses cached chain
-     * ```
-     *
-     * **After (OperationContext):**
-     * ```typescript
-     * // Chain specified explicitly per operation
-     * const prepared = await adapter.prepare(params, { chain: 'Ethereum' })
-     *
-     * // Multi-chain operations with same adapter
-     * const ethPrepared = await adapter.prepare(params, { chain: 'Ethereum' })
-     * const basePrepared = await adapter.prepare(params, { chain: 'Base' })
-     * ```
-     *
-     * @returns A promise that resolves to the first supported chain from capabilities
-     * @throws Error when no supported chains are configured
-     */
-    async getChain() {
-        // Fallback: return first supported chain (deprecated - only for backward compatibility)
-        const firstChain = this.capabilities?.supportedChains?.[0];
-        if (!firstChain) {
-            throw new Error('No supported chains configured. ' +
-                'This method is deprecated - use OperationContext pattern instead.');
-        }
-        return await Promise.resolve(firstChain);
-    }
     /**
      * Waits for a transaction to be mined and confirmed on the blockchain.
      *
@@ -10359,16 +10265,17 @@ class EthersAdapter extends EvmAdapter {
  * ```typescript
  * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
  *
- * // Minimal configuration with lazy initialization
- * const adapter = createAdapterFromPrivateKey({
- *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
- *   // Defaults applied:
- *   // - addressContext: 'user-controlled'
- *   // - supportedChains: all EVM chains (~29 networks)
+ * // Both private key formats are supported (with or without '0x' prefix):
+ * const adapter1 = createAdapterFromPrivateKey({
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // With prefix
+ * })
+ *
+ * const adapter2 = createAdapterFromPrivateKey({
+ *   privateKey: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // Without prefix (automatically normalized)
  * })
  *
  * // Chain specified per-operation via OperationContext
- * const prepared = await adapter.prepare({
+ * const prepared = await adapter1.prepare({
  *   address: '0x...',
  *   abi: contractAbi,
  *   functionName: 'transfer',
@@ -10427,9 +10334,9 @@ class EthersAdapter extends EvmAdapter {
  * ```
  */
 function createAdapterFromPrivateKey(params) {
-    // Validate input parameters at runtime
-    validateCreateAdapterFromPrivateKeyParams(params);
-    const { privateKey, getProvider, capabilities } = params;
+    // Parse and validate input parameters at runtime (normalizes the private key by adding '0x' prefix if missing)
+    const { privateKey } = createAdapterFromPrivateKeyParamsSchema.parse(params);
+    const { getProvider, capabilities } = params;
     // Resolve capabilities with default configuration
     const resolvedCapabilities = createAdapterCapabilities('evm', capabilities);
     // Validate that capabilities are appropriate for private key adapters
@@ -10444,6 +10351,7 @@ function createAdapterFromPrivateKey(params) {
     const getProviderFn = getProvider ?? getDefaultProviderUtil(new Map());
     // Create wallet WITHOUT provider (lazy initialization)
     // The wallet will be connected to a provider when ensureChain is called
+    // Type assertion safe because we normalized the private key in the schema
     const wallet = new Wallet(privateKey);
     // Create and return the adapter
     return new EthersAdapter({
@@ -10552,13 +10460,13 @@ function createAdapterFromPrivateKey(params) {
  * ```typescript
  * // Cross-chain transfer using a single adapter
  * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
- * import { BridgingKit } from '@circle-fin/bridging-kit'
+ * import { BridgeKit } from '@circle-fin/bridge-kit'
  *
  * const adapter = await createAdapterFromProvider({
  *   provider: window.ethereum
  * })
  *
- * const kit = new BridgingKit()
+ * const kit = new BridgeKit()
  *
  * // Use the same adapter for both source and destination
  * const result = await kit.bridge({
@@ -10621,5 +10529,5 @@ const createAdapterFromProvider = async (params) => {
     }, resolvedCapabilities);
 };
 
-export { EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider, validateAdapterCapabilities };
+export { Blockchain, EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider, validateAdapterCapabilities };
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@circle-fin/adapter-ethers-v6",
-  "version": "0.0.2-alpha.7",
+  "version": "1.0.0",
   "main": "./index.cjs.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",
   "dependencies": {
-    "@solana/web3.js": "^1.90.0",
-    "abitype": "1.0.8",
+    "abitype": "^1.1.0",
+    "@solana/web3.js": "^1.98.4",
     "zod": "3.25.67",
     "@ethersproject/address": "^5.8.0",
     "@ethersproject/bytes": "^5.8.0",
@@ -14,7 +14,7 @@
     "bs58": "6.0.0"
   },
   "peerDependencies": {
-    "ethers": "6.15.0"
+    "ethers": "^6.11.0"
   },
   "exports": {
     "./package.json": "./package.json",