@circle-fin/provider-cctp-v2 1.0.0 → 1.0.1

package/README.md

@@ -232,8 +232,10 @@ const destAdapter = new ViemAdapter({
 // Monitor transfer events
 kit.on('*', (event) => console.log('Event:', event)) // subscribe to all events
 kit.on('approve', (event) => console.log('Approval:', event.values.txHash))
-kit.on('depositForBurn', (event) => console.log('Burn:', event.values.txHash))
-kit.on('attestation', (event) => console.log('Burn:', event.attestation))
+kit.on('burn', (event) => console.log('Burn:', event.values.txHash))
+kit.on('fetchAttestation', (event) =>
+  console.log('Attestation:', event.values.data),
+)
 kit.on('mint', (event) => console.log('Mint:', event.values.txHash))
 
 // Execute transfer

package/index.cjs.js

@@ -54,6 +54,7 @@ var Blockchain;
     Blockchain["Algorand_Testnet"] = "Algorand_Testnet";
     Blockchain["Aptos"] = "Aptos";
     Blockchain["Aptos_Testnet"] = "Aptos_Testnet";
+    Blockchain["Arc_Testnet"] = "Arc_Testnet";
     Blockchain["Arbitrum"] = "Arbitrum";
     Blockchain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
     Blockchain["Avalanche"] = "Avalanche";
@@ -274,6 +275,48 @@ const BRIDGE_CONTRACT_EVM_TESTNET = '0xC5567a5E3370d4DBfB0540025078e283e36A363d'
  */
 const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0';
 
+/**
+ * Arc Testnet chain definition
+ * @remarks
+ * This represents the test network for the Arc blockchain,
+ * Circle's EVM-compatible Layer-1 designed for stablecoin finance
+ * and asset tokenization. Arc uses USDC as the native gas token and
+ * features the Malachite Byzantine Fault Tolerant (BFT) consensus
+ * engine for sub-second finality.
+ */
+const ArcTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Arc_Testnet,
+    name: 'Arc Testnet',
+    title: 'ArcTestnet',
+    nativeCurrency: {
+        name: 'Arc',
+        symbol: 'Arc',
+        decimals: 18,
+    },
+    chainId: 5042002,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.arcscan.app/tx/{hash}',
+    rpcEndpoints: ['https://rpc.testnet.arc.network/'],
+    eurcAddress: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
+    usdcAddress: '0x3600000000000000000000000000000000000000',
+    cctp: {
+        domain: 26,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * Arbitrum Mainnet chain definition
  * @remarks
@@ -1565,26 +1608,26 @@ const Sonic = defineChain({
 });
 
 /**
- * Sonic Blaze Testnet chain definition
+ * Sonic Testnet chain definition
  * @remarks
  * This represents the official test network for the Sonic blockchain.
  */
 const SonicTestnet = defineChain({
     type: 'evm',
     chain: Blockchain.Sonic_Testnet,
-    name: 'Sonic Blaze Testnet',
-    title: 'Sonic Blaze Testnet',
+    name: 'Sonic Testnet',
+    title: 'Sonic Testnet',
     nativeCurrency: {
         name: 'Sonic',
         symbol: 'S',
         decimals: 18,
     },
-    chainId: 57054,
+    chainId: 14601,
     isTestnet: true,
     explorerUrl: 'https://testnet.sonicscan.org/tx/{hash}',
-    rpcEndpoints: ['https://rpc.blaze.soniclabs.com'],
+    rpcEndpoints: ['https://rpc.testnet.soniclabs.com'],
     eurcAddress: null,
-    usdcAddress: '0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6',
+    usdcAddress: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
     cctp: {
         domain: 13,
         contracts: {
@@ -2101,6 +2144,7 @@ var Chains = {
     AptosTestnet: AptosTestnet,
     Arbitrum: Arbitrum,
     ArbitrumSepolia: ArbitrumSepolia,
+    ArcTestnet: ArcTestnet,
     Avalanche: Avalanche,
     AvalancheFuji: AvalancheFuji,
     Base: Base,
@@ -2575,69 +2619,133 @@ class BridgingProvider {
 }
 
 /**
- * Sets and gets the Stablecoin Kits SDK user agent string for HTTP requests.
- *
- * The user agent string is formatted as:
- *   name/version (platform)
- *
- * - name: The SDK or kit name, set at runtime.
- * - version: The SDK version, set at runtime.
- * - platform: The runtime environment, e.g., "node/nodeVersion" or "browser/browserName".
+ * Detect the runtime environment and return a shortened identifier.
  *
- * @remarks
- * The kit should call setKitIdentifier(name, version) once at startup.
- * A custom user agent will be automatically added to all HTTP requests made by the SDK.
- * This user agent includes the kit name, version, and platform information to help with
- * debugging and analytics.
- *
- * @example
- * ```typescript
- * setKitIdentifier('bridge-kit', '1.2.3')
- * getUserAgent() // "bridge-kit/1.2.3 (node/18.16.0)"
- * ```
- *
- * @returns The Stablecoin Kits SDK user agent string.
+ * @returns Runtime string, e.g., "node/18", "browser/Chrome", or "unknown"
  */
-let cachedUserAgent;
-function getRuntime() {
+const getRuntime = () => {
+    // Node.js environment
     if (typeof process !== 'undefined' &&
         typeof process.versions === 'object' &&
         typeof process.versions.node === 'string') {
-        return `node/${process.versions.node}`;
+        // Shorten to major version only
+        const majorVersion = process.versions.node.split('.')[0] ?? 'unknown';
+        return `node/${majorVersion}`;
     }
-    // Detect browser environment
+    // Browser environment
     if (typeof window !== 'undefined' && typeof navigator !== 'undefined') {
         const userAgent = navigator.userAgent;
         const browserMatchers = {
-            'browser/Edge': (ua) => ua.includes('Edg'),
-            'browser/Chrome': (ua) => ua.includes('Chrome') && !ua.includes('Edg'),
-            'browser/Firefox': (ua) => ua.includes('Firefox'),
-            'browser/Safari': (ua) => ua.includes('Safari') && !ua.includes('Chrome'),
-            'browser/InternetExplorer': (ua) => ua.includes('MSIE') || ua.includes('Trident'),
-            'browser/Opera': (ua) => ua.includes('Opera') || ua.includes('OPR'),
-            'browser/Brave': (ua) => ua.includes('Brave'),
+            Edge: (ua) => ua.includes('Edg'),
+            Chrome: (ua) => ua.includes('Chrome') && !ua.includes('Edg'),
+            Firefox: (ua) => ua.includes('Firefox'),
+            Safari: (ua) => ua.includes('Safari') && !ua.includes('Chrome'),
+            Opera: (ua) => ua.includes('Opera') || ua.includes('OPR'),
         };
         for (const [browserName, matcher] of Object.entries(browserMatchers)) {
             if (matcher(userAgent))
-                return browserName;
+                return `browser/${browserName}`;
         }
         return 'browser/unknown';
     }
     return 'unknown';
-}
+};
 /**
- * Get the user agent string for Stablecoin Kits SDK (universal, sync).
+ * Shorten package names by removing common prefixes.
  *
- * @returns The user agent string, e.g., "bridge-kit/1.2.3 (node/18.16.0)"
+ * @param fullName - Full package name, e.g., "\@circle-fin/bridge-kit"
+ * @returns Shortened name, e.g., "bridge-kit"
  */
-function getUserAgent() {
-    if (cachedUserAgent !== undefined)
-        return cachedUserAgent;
-    const name = 'unknown';
-    const version = 'unknown';
-    cachedUserAgent = `${name}/${version} (${getRuntime()})`;
-    return cachedUserAgent;
-}
+const shortenPackageName = (fullName) => {
+    return fullName.replace('@circle-fin/', '');
+};
+/**
+ * Format a component (name/version) with length optimizations.
+ *
+ * @param nameWithVersion - Component identifier, e.g., "\@circle-fin/bridge-kit/1.2.3"
+ * @returns Formatted component, e.g., "bridge-kit/1.2"
+ */
+const formatComponent = (nameWithVersion) => {
+    // Find the last / to split name and version
+    // This handles scoped packages like @circle-fin/bridge-kit/1.0.0 correctly
+    const lastSlashIndex = nameWithVersion.lastIndexOf('/');
+    if (lastSlashIndex === -1) {
+        // No version, just a name
+        return shortenPackageName(nameWithVersion);
+    }
+    const name = nameWithVersion.substring(0, lastSlashIndex);
+    const version = nameWithVersion.substring(lastSlashIndex + 1);
+    if (name === '')
+        return '';
+    if (version === '')
+        return shortenPackageName(name);
+    return `${shortenPackageName(name)}/${version}`;
+};
+/**
+ * Create a new request context from global state.
+ *
+ * Reads the current external prefix and kit identifier from globalThis.
+ * This is used internally by HTTP utilities.
+ *
+ * @returns A new request context
+ * @internal
+ */
+const createRequestContext = () => {
+    const context = {};
+    if (typeof globalThis !== 'undefined') {
+        if (globalThis.__STABLECOIN_KITS_EXTERNAL_PREFIX__ !== undefined) {
+            context.externalPrefix = globalThis.__STABLECOIN_KITS_EXTERNAL_PREFIX__;
+        }
+        if (globalThis.__STABLECOIN_KITS_CURRENT_KIT__ !== undefined) {
+            context.kit = globalThis.__STABLECOIN_KITS_CURRENT_KIT__;
+        }
+    }
+    return context;
+};
+/**
+ * Build a user agent string from a request context.
+ *
+ * Formats the context into a user agent string with automatic optimizations
+ * (shortened package names and truncated versions). The current implementation
+ * tracks a single kit globally.
+ *
+ * Format: `[external-prefix] kit (runtime)`
+ *
+ * @param context - Request context or undefined to use the global context
+ * @returns Formatted user agent string
+ *
+ * @example
+ * ```typescript
+ * // With application prefix and kit
+ * const ua = getUserAgent(context)
+ * // → "my-app/1.0 bridge-kit/1.2 (node/18)"
+ *
+ * // Kit only (no application prefix set)
+ * const ua = getUserAgent()
+ * // → "bridge-kit/1.2 (node/18)"
+ * ```
+ */
+const getUserAgent = (context) => {
+    const ctx = createRequestContext();
+    const runtime = getRuntime();
+    // Build user agent string
+    const parts = [];
+    // Add external prefix if set
+    if (ctx.externalPrefix !== undefined) {
+        const formatted = formatComponent(ctx.externalPrefix);
+        if (formatted)
+            parts.push(formatted);
+    }
+    // Add kit if set
+    if (ctx.kit !== undefined) {
+        const formatted = formatComponent(ctx.kit);
+        if (formatted)
+            parts.push(formatted);
+    }
+    // Add runtime
+    parts.push(`(${runtime})`);
+    return parts.join(' ');
+};
 
 /**
  * Default configuration values for the API polling utility.
@@ -3586,9 +3694,9 @@ const customFeeSchema = zod.z
  *   token: 'USDC',
  *   config: {
  *     transferSpeed: 'FAST',
- *     maxFee: '1000000'
+ *     maxFee: '1.5', // Decimal format
  *     customFee: {
- *       value: '1000000',
+ *       value: '0.5', // Decimal format
  *       recipientAddress: '0x1234567890123456789012345678901234567890'
  *     }
  *   }
@@ -3615,7 +3723,12 @@ const bridgeParamsSchema = zod.z.object({
         transferSpeed: zod.z.nativeEnum(TransferSpeed).optional(),
         maxFee: zod.z
             .string()
-            .regex(/^\d+$/, 'Max fee must be a numeric string')
+            .pipe(createDecimalStringValidator({
+            allowZero: true,
+            regexMessage: 'maxFee must be a numeric string with optional decimal places (e.g., "1", "0.5", "1.5")',
+            attributeName: 'maxFee',
+            maxDecimals: 6,
+        })(zod.z.string()))
             .optional(),
         customFee: customFeeSchema.optional(),
     }),
@@ -3772,8 +3885,8 @@ const CCTPv2MinFinalityThreshold = {
  */
 const DEFAULT_CONFIG = {
     timeout: 2_000, // 2 seconds
-    maxRetries: 30 * 20, // 2 seconds * 30 * 20 = 20 minutes (to account for slow transfers maximum time based on confirmations)
-    retryDelay: 500,
+    maxRetries: 30 * 20, // 30 * 20 * 2 seconds (from the retry delay) = 20 minutes (to account for slow transfers maximum time based on confirmations)
+    retryDelay: 2_000, // 2 seconds
     headers: {
         'Content-Type': 'application/json',
     },
@@ -4205,6 +4318,10 @@ class KitError extends Error {
     }
 }
 
+/**
+ * Minimum error code for INPUT type errors.
+ * INPUT errors represent validation failures and invalid parameters.
+ */
 /**
  * Standardized error definitions for INPUT type errors.
  *
@@ -4690,8 +4807,6 @@ async function bridgeApproval({ params, provider, }) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.approve(params.source, approvalAmount),
-        // We need to wait for the approval to be confirmed on chain before the transfer can be executed
-        confirmations: 2,
     });
 }
 
@@ -4705,8 +4820,8 @@ async function bridgeApproval({ params, provider, }) {
  * @param params - The bridge parameters containing source, destination, amount and optional config
  * @param sourceChain - The source chain definition where the burn will occur
  * @returns Promise resolving to the bridge step with transaction details
- * @throws {ValidationError} If the parameters are invalid
- * @throws {BridgeError} If the burn transaction fails
+ * @throws \{ValidationError\} If the parameters are invalid
+ * @throws \{BridgeError\} If the burn transaction fails
  *
  * @example
  * ```typescript
@@ -4715,16 +4830,11 @@ async function bridgeApproval({ params, provider, }) {
  * ```
  */
 async function bridgeBurn({ params, provider, }) {
-    const transferSpeed = params.config?.transferSpeed ?? TransferSpeed.FAST;
     return await executePreparedChainRequest({
         name: 'burn',
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.burn(params),
-        confirmations: transferSpeed === TransferSpeed.FAST
-            ? params.source.chain.cctp.contracts.v2.fastConfirmations
-            : params.source.chain.cctp.contracts.v2.confirmations,
-        timeout: transferSpeed === TransferSpeed.FAST ? undefined : 1_200_000, // 20 minutes (max timeout for cctpv2 slow transfers)
     });
 }
 
@@ -4736,16 +4846,18 @@ async function bridgeBurn({ params, provider, }) {
  * and authorizes the minting of equivalent tokens.
  *
  * @param params - The bridge parameters containing source, destination, amount and optional config
- * @param sourceChain - The source chain definition where the burn occurred
- * @param burnTransactionHash - The hash of the burn transaction
- * @returns Promise resolving to the bridge step with transaction details
- * @throws {ValidationError} If the parameters are invalid
- * @throws {BridgeError} If the attestation fetch fails
+ * @param txHash - The hash of the burn transaction
+ * @returns Promise resolving to the bridge step with attestation data
+ * @throws \{ValidationError\} If the parameters are invalid
+ * @throws \{BridgeError\} If the attestation fetch fails
  *
  * @example
  * ```typescript
- * const attestationStep = await fetchAttestation(params, sourceChain, burnTxHash)
- * console.log('Attestation:', attestationStep.attestation)
+ * const attestationStep = await bridgeFetchAttestation(
+ *   { params, provider },
+ *   burnTxHash
+ * )
+ * console.log('Attestation data:', attestationStep.data)
  * ```
  */
 async function bridgeFetchAttestation({ params, provider, }, txHash) {
@@ -4754,7 +4866,17 @@ async function bridgeFetchAttestation({ params, provider, }, txHash) {
         state: 'pending',
     };
     try {
-        const attestation = await provider.fetchAttestation(params.source, txHash);
+        /**
+         * Give slow transfers a longer retry delay of 30 seconds to account for the longer time it takes to get the
+         * attestation so that we do not hit the rate limit of the IRIS API or the retry limit of the API polling utility.
+         * We only do this for slow transfers on source chains that have greater than 20 confirmations (5 minutes of blocktime
+         * on the slowest blocktime chains) so that we do not slow down the attestation polling for lower confirmation chains.
+         */
+        const apiPollingConfig = params.config?.transferSpeed === TransferSpeed.SLOW &&
+            params.source.chain.cctp.contracts.v2.confirmations > 20
+            ? { retryDelay: 30_000 }
+            : undefined;
+        const attestation = await provider.fetchAttestation(params.source, txHash, apiPollingConfig);
         step = {
             ...step,
             state: 'success',
@@ -4762,10 +4884,18 @@ async function bridgeFetchAttestation({ params, provider, }, txHash) {
         };
     }
     catch (err) {
+        let errorMessage = 'Unknown attestation error';
+        if (err instanceof Error) {
+            errorMessage = err.message;
+        }
+        else if (typeof err === 'string') {
+            errorMessage = err;
+        }
         step = {
             ...step,
             state: 'error',
             error: err,
+            errorMessage,
             data: undefined,
         };
     }
@@ -4801,8 +4931,6 @@ async function bridgeMint({ params, provider, }, attestation) {
         adapter: params.destination.adapter,
         chain: params.destination.chain,
         request: await provider.mint(params.source, params.destination, attestation),
-        // We will wait for the mint to be confirmed on chain before we will return is as success
-        confirmations: 2,
     });
 }
 
@@ -4888,6 +5016,56 @@ function handleStepError(stepName, error, result) {
     });
 }
 
+/**
+ * Dispatch a bridge step event through the provider's action dispatcher.
+ *
+ * Constructs the appropriate action payload and dispatches it to any registered
+ * event listeners. Handles type-safe dispatching for different step types.
+ *
+ * @param name - The step name (approve, burn, fetchAttestation, or mint).
+ * @param step - The completed bridge step containing transaction details and explorerUrl.
+ * @param provider - The CCTP v2 provider with action dispatcher.
+ *
+ * @example
+ * ```typescript
+ * const step: BridgeStep = {
+ *   name: 'burn',
+ *   state: 'success',
+ *   txHash: '0xabc...',
+ *   explorerUrl: 'https://sepolia.etherscan.io/tx/0xabc...',
+ *   data: { ... }
+ * }
+ * dispatchStepEvent('burn', step, provider)
+ * ```
+ */
+function dispatchStepEvent(name, step, provider) {
+    if (!provider.actionDispatcher) {
+        return;
+    }
+    const actionValues = {
+        protocol: 'cctp',
+        version: 'v2',
+        values: step,
+    };
+    switch (name) {
+        case 'approve':
+        case 'burn':
+        case 'mint':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name,
+            });
+            break;
+        case 'fetchAttestation':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name,
+                values: step,
+            });
+            break;
+    }
+}
+
 /**
  * Execute a cross-chain USDC bridge using the CCTP v2 protocol.
  *
@@ -4944,34 +5122,19 @@ async function bridge(params, provider) {
         try {
             const step = await executor(params, provider, context);
             if (step.state === 'error') {
-                // Include error details from the step in the thrown error
-                const errorDetails = step.errorMessage ?? 'Unknown error';
+                // Include error details from the step in the thrown error. Fall back to step.error.
+                let fallbackErrorMessage = 'Unknown error';
+                if (step.error instanceof Error) {
+                    fallbackErrorMessage = step.error.message;
+                }
+                else if (typeof step.error === 'string') {
+                    fallbackErrorMessage = step.error;
+                }
+                const errorDetails = step.errorMessage ?? fallbackErrorMessage;
                 throw new Error(`${name} step failed: ${errorDetails}`);
             }
             context = updateContext?.(step);
-            const actionValues = {
-                protocol: 'cctp',
-                version: 'v2',
-                values: step,
-            };
-            // use a switch statement for type safety to separate the different step types
-            switch (name) {
-                case 'approve':
-                case 'burn':
-                case 'mint':
-                    provider.actionDispatcher?.dispatch(name, {
-                        ...actionValues,
-                        method: name,
-                    });
-                    break;
-                case 'fetchAttestation':
-                    provider.actionDispatcher?.dispatch(name, {
-                        ...actionValues,
-                        method: name,
-                        values: step,
-                    });
-                    break;
-            }
+            dispatchStepEvent(name, step, provider);
             result.steps.push(step);
         }
         catch (error) {
@@ -5638,12 +5801,7 @@ async function retry(result, context, provider) {
                 throw new Error(errorMessage);
             }
             stepContext = updateContext?.(step);
-            provider.actionDispatcher?.dispatch(name, {
-                protocol: 'cctp',
-                version: 'v2',
-                method: name,
-                values: step.data,
-            });
+            dispatchStepEvent(name, step, provider);
             result.steps.push(step);
         }
         catch (error) {
@@ -6212,7 +6370,9 @@ class CCTPV2BridgingProvider extends BridgingProvider {
      *   - `source`: The source wallet context with chain definition and adapter
      *   - `destination`: The destination wallet context with chain definition and adapter
      *   - `amount`: The bridge amount in minor units (e.g., "1000000" for 1 USDC)
-     *   - `config`: Optional bridge configuration including transferSpeed and maxFee settings
+     *   - `config`: Optional bridge configuration including transferSpeed and maxFee settings.
+     *     When used via BridgeKit, fee values are automatically converted from human-readable
+     *     format (e.g., "1") to smallest units (e.g., "1000000").
      * @returns The maximum fee to be used for the bridge operation in minor units
      *
      * @example
@@ -6220,9 +6380,12 @@ class CCTPV2BridgingProvider extends BridgingProvider {
      * const maxFee = await provider.getMaxFee({
      *   source: { adapter: sourceAdapter, chain: Chains.Ethereum, address: '0x...' },
      *   destination: { adapter: destAdapter, chain: Chains.Base, address: '0x...' },
-     *   amount: '1000000', // 1 USDC
+     *   amount: '1000000', // 1 USDC in minor units
      *   token: 'USDC',
-     *   config: { transferSpeed: TransferSpeed.FAST }
+     *   config: {
+     *     transferSpeed: TransferSpeed.FAST,
+     *     maxFee: '1000000' // Provider receives values in smallest units
+     *   }
      * })
      * console.log('Max fee:', maxFee)
      * ```
@@ -6253,7 +6416,7 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             maxFee = baseFee + baseFee / 10n;
         }
         else {
-            // Use the max fee from the config
+            // Use the max fee from the config (converted to minor units by BridgeKit)
             maxFee = BigInt(config.maxFee);
         }
         return maxFee;
@@ -6359,4 +6522,5 @@ class CCTPV2BridgingProvider extends BridgingProvider {
 }
 
 exports.CCTPV2BridgingProvider = CCTPV2BridgingProvider;
+exports.getMintRecipientAccount = getMintRecipientAccount;
 //# sourceMappingURL=index.cjs.js.map