@circle-fin/provider-cctp-v2 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @circle-fin/provider-cctp-v2
 
+## 1.2.0
+
+### Minor Changes
+
+- Add attestation expiry detection utilities for CCTP v2 fast transfers:
+  - `isAttestationExpired(attestation, currentBlockNumber)` - Check if an attestation has expired based on the destination chain's current block/slot
+  - `getBlocksUntilExpiry(attestation, currentBlockNumber)` - Get the number of blocks remaining until expiry (returns `null` for attestations that never expire)
+  - `isMintFailureRelatedToAttestation(error)` - Detect if a mint failure was caused by attestation expiry to know when to call `reAttest()`
+
+- Add native balance validation for transaction gas fees before bridge tx.
+
 ## 1.1.0
 
 ### Minor Changes

package/index.cjs

@@ -385,8 +385,11 @@ const ArcTestnet = defineChain({
     name: 'Arc Testnet',
     title: 'ArcTestnet',
     nativeCurrency: {
-        name: 'Arc',
-        symbol: 'Arc',
+        name: 'USDC',
+        symbol: 'USDC',
+        // Arc uses native USDC with 18 decimals for gas payments (EVM standard).
+        // Note: The ERC-20 USDC contract at usdcAddress uses 6 decimals.
+        // See: https://docs.arc.network/arc/references/contract-addresses
         decimals: 18,
     },
     chainId: 5042002,
@@ -3644,6 +3647,12 @@ const BalanceError = {
         code: 9001,
         name: 'BALANCE_INSUFFICIENT_TOKEN',
         type: 'BALANCE',
+    },
+    /** Insufficient native token (ETH/SOL/etc) for gas fees */
+    INSUFFICIENT_GAS: {
+        code: 9002,
+        name: 'BALANCE_INSUFFICIENT_GAS',
+        type: 'BALANCE',
     }};
 
 /**
@@ -3866,7 +3875,7 @@ function createValidationErrorFromZod(zodError, context) {
  *
  * @param chain - The blockchain network where the balance check failed
  * @param token - The token symbol (e.g., 'USDC', 'ETH')
- * @param rawError - The original error from the underlying system (optional)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with insufficient token balance details
  *
  * @example
@@ -3879,24 +3888,71 @@ function createValidationErrorFromZod(zodError, context) {
  *
  * @example
  * ```typescript
- * // With raw error for debugging
+ * // With trace context for debugging
  * try {
  *   await transfer(...)
  * } catch (error) {
- *   throw createInsufficientTokenBalanceError('Base', 'USDC', error)
+ *   throw createInsufficientTokenBalanceError('Base', 'USDC', {
+ *     rawError: error,
+ *     balance: '1000000',
+ *     amount: '5000000',
+ *   })
  * }
  * ```
  */
-function createInsufficientTokenBalanceError(chain, token, rawError) {
+function createInsufficientTokenBalanceError(chain, token, trace) {
     return new KitError({
         ...BalanceError.INSUFFICIENT_TOKEN,
         recoverability: 'FATAL',
         message: `Insufficient ${token} balance on ${chain}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
                 token,
-                rawError,
+            },
+        },
+    });
+}
+/**
+ * Creates error for insufficient gas funds.
+ *
+ * This error is thrown when a wallet does not have enough native tokens
+ * (ETH, SOL, etc.) to pay for transaction gas fees. The error is FATAL
+ * as it requires user intervention to add gas funds.
+ *
+ * @param chain - The blockchain network where the gas check failed
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
+ * @returns KitError with insufficient gas details
+ *
+ * @example
+ * ```typescript
+ * import { createInsufficientGasError } from '@core/errors'
+ *
+ * throw createInsufficientGasError('Ethereum')
+ * // Message: "Insufficient gas funds on Ethereum"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createInsufficientGasError('Ethereum', {
+ *   rawError: error,
+ *   gasRequired: '21000',
+ *   gasAvailable: '10000',
+ *   walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+ * })
+ * ```
+ */
+function createInsufficientGasError(chain, trace) {
+    return new KitError({
+        ...BalanceError.INSUFFICIENT_GAS,
+        recoverability: 'FATAL',
+        message: `Insufficient gas funds on ${chain}`,
+        cause: {
+            trace: {
+                ...trace,
+                chain,
             },
         },
     });
@@ -3958,6 +4014,38 @@ function isKitError(error) {
 function isFatalError(error) {
     return isKitError(error) && error.recoverability === 'FATAL';
 }
+/**
+ * Safely extracts error message from any error type.
+ *
+ * This utility handles different error types gracefully, extracting
+ * meaningful messages from Error instances, string errors, or providing
+ * a fallback for unknown error types. Never throws.
+ *
+ * @param error - Unknown error to extract message from
+ * @returns Error message string, or fallback message
+ *
+ * @example
+ * ```typescript
+ * import { getErrorMessage } from '@core/errors'
+ *
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   const message = getErrorMessage(error)
+ *   console.log('Error occurred:', message)
+ *   // Works with Error, KitError, string, or any other type
+ * }
+ * ```
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'An unknown error occurred';
+}
 
 /**
  * Validates data against a Zod schema with enhanced error reporting.
@@ -5389,6 +5477,170 @@ mintAddress) => {
     }
 };
 
+/**
+ * Converts a block number to bigint with validation.
+ *
+ * @param value - The block number value to convert (bigint, number, or string)
+ * @returns The validated block number as a bigint
+ * @throws KitError If the value is invalid (empty string, non-integer, negative, etc.)
+ * @internal
+ */
+const toBlockNumber = (value) => {
+    if (value === null || value === undefined) {
+        throw createValidationFailedError('blockNumber', value, 'cannot be null or undefined');
+    }
+    // Empty string edge case - BigInt('') === 0n which is misleading
+    if (value === '') {
+        throw createValidationFailedError('blockNumber', value, 'cannot be empty string');
+    }
+    // For numbers, validate before BigInt conversion
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || !Number.isInteger(value)) {
+            throw createValidationFailedError('blockNumber', value, 'must be a finite integer');
+        }
+    }
+    let result;
+    try {
+        result = BigInt(value);
+    }
+    catch {
+        throw createValidationFailedError('blockNumber', value, 'cannot be converted to BigInt');
+    }
+    if (result < 0n) {
+        throw createValidationFailedError('blockNumber', result.toString(), 'must be non-negative');
+    }
+    return result;
+};
+/**
+ * Determines whether an attestation has expired based on the current block number.
+ *
+ * An attestation expires when the destination chain's current block number is greater
+ * than or equal to the expiration block specified in the attestation message.
+ * Slow transfers and re-attested messages have `expirationBlock: '0'` and never expire.
+ *
+ * @param attestation - The attestation message containing expiration block information
+ * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
+ * @returns `true` if the attestation has expired, `false` if still valid or never expires
+ * @throws KitError If currentBlockNumber or expirationBlock is invalid
+ *
+ * @example
+ * ```typescript
+ * import { isAttestationExpired } from '@circle-fin/cctp-v2-provider'
+ *
+ * // Check if attestation is expired on EVM chain
+ * const publicClient = await adapter.getPublicClient(destinationChain)
+ * const currentBlock = await publicClient.getBlockNumber()
+ * const expired = isAttestationExpired(attestation, currentBlock)
+ *
+ * if (expired) {
+ *   const freshAttestation = await provider.reAttest(source, burnTxHash)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check on Solana
+ * const slot = await adapter.getConnection(destinationChain).getSlot()
+ * const expired = isAttestationExpired(attestation, slot)
+ * ```
+ */
+const isAttestationExpired = (attestation, currentBlockNumber) => {
+    const currentBlock = toBlockNumber(currentBlockNumber);
+    const expiration = toBlockNumber(attestation.decodedMessage.decodedMessageBody.expirationBlock);
+    // 0n means it never expires (re-attested messages and slow transfers)
+    if (expiration === 0n) {
+        return false;
+    }
+    // Attestation is expired if current block >= expiration block
+    return currentBlock >= expiration;
+};
+/**
+ * Calculates the number of blocks remaining until an attestation expires.
+ *
+ * Returns the difference between the expiration block and the current block number.
+ * Returns `null` if the attestation has `expirationBlock: '0'` (never expires).
+ * Returns `0n` or a negative bigint if the attestation has already expired.
+ *
+ * @param attestation - The attestation message containing expiration block information
+ * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
+ * @returns The number of blocks until expiry as a bigint, or `null` if the attestation never expires
+ * @throws KitError If currentBlockNumber or expirationBlock is invalid
+ *
+ * @example
+ * ```typescript
+ * import { getBlocksUntilExpiry } from '@circle-fin/cctp-v2-provider'
+ *
+ * const publicClient = await adapter.getPublicClient(destinationChain)
+ * const currentBlock = await publicClient.getBlockNumber()
+ * const blocksRemaining = getBlocksUntilExpiry(attestation, currentBlock)
+ *
+ * if (blocksRemaining === null) {
+ *   console.log('Attestation never expires')
+ * } else if (blocksRemaining <= 0n) {
+ *   console.log('Attestation has expired')
+ * } else {
+ *   console.log(`${blocksRemaining} blocks until expiry`)
+ * }
+ * ```
+ */
+const getBlocksUntilExpiry = (attestation, currentBlockNumber) => {
+    const currentBlock = toBlockNumber(currentBlockNumber);
+    const expiration = toBlockNumber(attestation.decodedMessage.decodedMessageBody.expirationBlock);
+    // 0n means it never expires (re-attested messages and slow transfers)
+    if (expiration === 0n) {
+        return null;
+    }
+    // Return the difference (can be negative if expired)
+    return expiration - currentBlock;
+};
+/**
+ * Determines whether a mint failure was caused by an expired attestation.
+ *
+ * This function inspects the error thrown during a mint operation to detect
+ * if the failure is due to the attestation's expiration block being exceeded.
+ * When this returns `true`, the caller should use `reAttest()` to obtain a
+ * fresh attestation before retrying the mint.
+ *
+ * @param error - The error thrown during the mint operation
+ * @returns `true` if the error indicates the attestation has expired, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isMintFailureRelatedToAttestation } from '@circle-fin/cctp-v2-provider'
+ *
+ * try {
+ *   await mintRequest.execute()
+ * } catch (error) {
+ *   if (isMintFailureRelatedToAttestation(error)) {
+ *     // Attestation expired - get a fresh one
+ *     const freshAttestation = await provider.reAttest(source, burnTxHash)
+ *     const newMintRequest = await provider.mint(source, destination, freshAttestation)
+ *     await newMintRequest.execute()
+ *   } else {
+ *     throw error
+ *   }
+ * }
+ * ```
+ */
+const isMintFailureRelatedToAttestation = (error) => {
+    if (error === null || error === undefined) {
+        return false;
+    }
+    const errorString = getErrorMessage(error).toLowerCase();
+    // Check for Solana "MessageExpired" error pattern
+    // Full error: "AnchorError thrown in ...handle_receive_finalized_message.rs:169.
+    //              Error Code: MessageExpired. Error Number: 6016. Error Message: Message has expired."
+    if (errorString.includes('messageexpired')) {
+        return true;
+    }
+    // Check for EVM attestation expiry errors
+    // Contract reverts with: "Message expired and must be re-signed"
+    if (errorString.includes('message') && errorString.includes('expired')) {
+        return true;
+    }
+    return false;
+};
+
 /**
  * Checks if a decoded attestation field matches the corresponding transfer parameter.
  * If the values do not match, appends a descriptive error message to the errors array.
@@ -6232,21 +6484,64 @@ const validateBalanceForTransaction = async (params) => {
         // Extract chain name from operationContext
         const chainName = extractChainInfo(operationContext.chain).name;
         // Create KitError with rich context in trace
-        const error = createInsufficientTokenBalanceError(chainName, token);
-        // Enhance error with additional context for debugging
-        if (error.cause) {
-            const existingTrace = typeof error.cause.trace === 'object' && error.cause.trace
-                ? error.cause.trace
-                : {};
-            error.cause.trace = {
-                ...existingTrace,
-                balance: balance.toString(),
-                amount,
-                tokenAddress,
-                walletAddress: operationContext.address,
-            };
-        }
-        throw error;
+        throw createInsufficientTokenBalanceError(chainName, token, {
+            balance: balance.toString(),
+            amount,
+            tokenAddress,
+            walletAddress: operationContext.address,
+        });
+    }
+};
+
+/**
+ * Validate that the adapter has sufficient native token balance for transaction fees.
+ *
+ * This function checks if the adapter's current native token balance (ETH, SOL, etc.)
+ * is greater than zero. It throws a KitError with code 9002 (BALANCE_INSUFFICIENT_GAS)
+ * if the balance is zero, indicating the wallet cannot pay for transaction fees.
+ *
+ * @param params - The validation parameters containing adapter and operation context.
+ * @returns A promise that resolves to void if validation passes.
+ * @throws {KitError} When the adapter's native balance is zero (code: 9002).
+ *
+ * @example
+ * ```typescript
+ * import { validateNativeBalanceForTransaction } from '@core/adapter'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { isKitError, ERROR_TYPES } from '@core/errors'
+ *
+ * const adapter = createViemAdapterFromPrivateKey({
+ *   privateKey: '0x...',
+ *   chain: 'Ethereum',
+ * })
+ *
+ * try {
+ *   await validateNativeBalanceForTransaction({
+ *     adapter,
+ *     operationContext: { chain: 'Ethereum' },
+ *   })
+ *   console.log('Native balance validation passed')
+ * } catch (error) {
+ *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
+ *     console.error('Insufficient gas funds:', error.message)
+ *   }
+ * }
+ * ```
+ */
+const validateNativeBalanceForTransaction = async (params) => {
+    const { adapter, operationContext } = params;
+    const balancePrepared = await adapter.prepareAction('native.balanceOf', {
+        walletAddress: operationContext.address,
+    }, operationContext);
+    const balance = await balancePrepared.execute();
+    if (BigInt(balance) === 0n) {
+        // Extract chain name from operationContext
+        const chainName = extractChainInfo(operationContext.chain).name;
+        // Create KitError with rich context in trace
+        throw createInsufficientGasError(chainName, {
+            balance: '0',
+            walletAddress: operationContext.address,
+        });
     }
 };
 
@@ -7123,16 +7418,28 @@ class CCTPV2BridgingProvider extends BridgingProvider {
     async bridge(params) {
         // CCTP-specific bridge params validation (includes base validation)
         assertCCTPv2BridgeParams(params);
-        const { source, amount, token } = params;
+        const { source, destination, amount, token } = params;
         // Extract operation context from source wallet context for balance validation
-        const operationContext = this.extractOperationContext(source);
-        // Validate balance for transaction
+        const sourceOperationContext = this.extractOperationContext(source);
+        // Validate USDC balance for transaction on source chain
         await validateBalanceForTransaction({
             adapter: source.adapter,
             amount,
             token,
             tokenAddress: source.chain.usdcAddress,
-            operationContext,
+            operationContext: sourceOperationContext,
+        });
+        // Validate native balance > 0 for gas fees on source chain
+        await validateNativeBalanceForTransaction({
+            adapter: source.adapter,
+            operationContext: sourceOperationContext,
+        });
+        // Extract operation context from destination wallet context
+        const destinationOperationContext = this.extractOperationContext(destination);
+        // Validate native balance > 0 for gas fees on destination chain
+        await validateNativeBalanceForTransaction({
+            adapter: destination.adapter,
+            operationContext: destinationOperationContext,
         });
         return bridge(params, this);
     }
@@ -7792,5 +8099,8 @@ class CCTPV2BridgingProvider extends BridgingProvider {
 }
 
 exports.CCTPV2BridgingProvider = CCTPV2BridgingProvider;
+exports.getBlocksUntilExpiry = getBlocksUntilExpiry;
 exports.getMintRecipientAccount = getMintRecipientAccount;
+exports.isAttestationExpired = isAttestationExpired;
+exports.isMintFailureRelatedToAttestation = isMintFailureRelatedToAttestation;
 //# sourceMappingURL=index.cjs.map

package/index.d.ts

@@ -17,7 +17,7 @@
  */
 
 import { Abi } from 'abitype';
-import { TransactionInstruction, Signer } from '@solana/web3.js';
+import { TransactionInstruction, Signer, AddressLookupTableAccount } from '@solana/web3.js';
 
 /**
  * @packageDocumentation
@@ -644,14 +644,26 @@ interface SolanaPreparedChainRequestParams {
      */
     instructions: TransactionInstruction[];
     /**
-     * Additional signers besides the Adapter’s wallet (e.g. program-derived authorities).
+     * Additional signers besides the Adapter's wallet (e.g. program-derived authorities).
      */
     signers?: Signer[];
     /**
      * Optional override for how many compute units this transaction may consume.
-     * If omitted, the network’s default compute budget applies.
+     * If omitted, the network's default compute budget applies.
      */
     computeUnitLimit?: number;
+    /**
+     * Optional Address Lookup Table accounts for transaction compression.
+     * Used to reduce transaction size by compressing frequently-used addresses.
+     * This is used by @solana/web3.js adapters that have already fetched the ALT data.
+     */
+    addressLookupTableAccounts?: AddressLookupTableAccount[];
+    /**
+     * Optional Address Lookup Table addresses for transaction compression.
+     * Used by adapters that need to fetch ALT data themselves (e.g., @solana/kit adapters).
+     * These are base58-encoded addresses of ALT accounts to use for compression.
+     */
+    addressLookupTableAddresses?: string[];
 }
 /**
  * Solana-specific configuration for transaction estimation.
@@ -1333,6 +1345,34 @@ interface CCTPActionMap {
     readonly v2: CCTPv2ActionMap;
 }
 
+/**
+ * Action map for native token operations (ETH, SOL, MATIC, etc.).
+ *
+ * Native tokens are the primary currency of each blockchain network,
+ * used for paying transaction fees and as a store of value.
+ * These actions operate on the native token without requiring
+ * a separate token contract address.
+ *
+ * @remarks
+ * Native token operations differ from ERC-20/SPL token operations
+ * in that they don't require contract interactions for basic transfers
+ * and balance checks.
+ *
+ * @see {@link ActionMap} for the complete action structure
+ */
+interface NativeActionMap {
+    /**
+     * Get the native token balance (SOL, ETH, etc.) for a wallet address.
+     */
+    balanceOf: ActionParameters & {
+        /**
+         * The address to check the native balance for. If not provided, it will be
+         * automatically derived from the adapter context.
+         */
+        walletAddress?: string | undefined;
+    };
+}
+
 interface TokenActionMap {
     /**
      * Set an allowance for a delegate to spend tokens on behalf of the wallet.
@@ -1564,6 +1604,8 @@ interface USDCActionMap {
 interface ActionMap {
     /** CCTP-specific operations with automatic address resolution. */
     readonly cctp: CCTPActionMap;
+    /** Native token operations (ETH, SOL, MATIC, etc.). */
+    readonly native: NativeActionMap;
     /** General token operations requiring explicit token addresses. */
     readonly token: TokenActionMap;
     /** USDC-specific operations with automatic address resolution. */
@@ -3917,5 +3959,102 @@ rawAddress: string,
 /** The USDC mint address (ignored for EVM chains, required base58 address for Solana) */
 mintAddress: string) => Promise<string>;
 
-export { CCTPV2BridgingProvider, getMintRecipientAccount };
+/** A block number value that can be provided as bigint, number, or string. */
+type BlockNumberInput = bigint | number | string | undefined;
+/**
+ * Determines whether an attestation has expired based on the current block number.
+ *
+ * An attestation expires when the destination chain's current block number is greater
+ * than or equal to the expiration block specified in the attestation message.
+ * Slow transfers and re-attested messages have `expirationBlock: '0'` and never expire.
+ *
+ * @param attestation - The attestation message containing expiration block information
+ * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
+ * @returns `true` if the attestation has expired, `false` if still valid or never expires
+ * @throws KitError If currentBlockNumber or expirationBlock is invalid
+ *
+ * @example
+ * ```typescript
+ * import { isAttestationExpired } from '@circle-fin/cctp-v2-provider'
+ *
+ * // Check if attestation is expired on EVM chain
+ * const publicClient = await adapter.getPublicClient(destinationChain)
+ * const currentBlock = await publicClient.getBlockNumber()
+ * const expired = isAttestationExpired(attestation, currentBlock)
+ *
+ * if (expired) {
+ *   const freshAttestation = await provider.reAttest(source, burnTxHash)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check on Solana
+ * const slot = await adapter.getConnection(destinationChain).getSlot()
+ * const expired = isAttestationExpired(attestation, slot)
+ * ```
+ */
+declare const isAttestationExpired: (attestation: AttestationMessage, currentBlockNumber: BlockNumberInput) => boolean;
+/**
+ * Calculates the number of blocks remaining until an attestation expires.
+ *
+ * Returns the difference between the expiration block and the current block number.
+ * Returns `null` if the attestation has `expirationBlock: '0'` (never expires).
+ * Returns `0n` or a negative bigint if the attestation has already expired.
+ *
+ * @param attestation - The attestation message containing expiration block information
+ * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
+ * @returns The number of blocks until expiry as a bigint, or `null` if the attestation never expires
+ * @throws KitError If currentBlockNumber or expirationBlock is invalid
+ *
+ * @example
+ * ```typescript
+ * import { getBlocksUntilExpiry } from '@circle-fin/cctp-v2-provider'
+ *
+ * const publicClient = await adapter.getPublicClient(destinationChain)
+ * const currentBlock = await publicClient.getBlockNumber()
+ * const blocksRemaining = getBlocksUntilExpiry(attestation, currentBlock)
+ *
+ * if (blocksRemaining === null) {
+ *   console.log('Attestation never expires')
+ * } else if (blocksRemaining <= 0n) {
+ *   console.log('Attestation has expired')
+ * } else {
+ *   console.log(`${blocksRemaining} blocks until expiry`)
+ * }
+ * ```
+ */
+declare const getBlocksUntilExpiry: (attestation: AttestationMessage, currentBlockNumber: BlockNumberInput) => bigint | null;
+/**
+ * Determines whether a mint failure was caused by an expired attestation.
+ *
+ * This function inspects the error thrown during a mint operation to detect
+ * if the failure is due to the attestation's expiration block being exceeded.
+ * When this returns `true`, the caller should use `reAttest()` to obtain a
+ * fresh attestation before retrying the mint.
+ *
+ * @param error - The error thrown during the mint operation
+ * @returns `true` if the error indicates the attestation has expired, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isMintFailureRelatedToAttestation } from '@circle-fin/cctp-v2-provider'
+ *
+ * try {
+ *   await mintRequest.execute()
+ * } catch (error) {
+ *   if (isMintFailureRelatedToAttestation(error)) {
+ *     // Attestation expired - get a fresh one
+ *     const freshAttestation = await provider.reAttest(source, burnTxHash)
+ *     const newMintRequest = await provider.mint(source, destination, freshAttestation)
+ *     await newMintRequest.execute()
+ *   } else {
+ *     throw error
+ *   }
+ * }
+ * ```
+ */
+declare const isMintFailureRelatedToAttestation: (error: unknown) => boolean;
+
+export { CCTPV2BridgingProvider, getBlocksUntilExpiry, getMintRecipientAccount, isAttestationExpired, isMintFailureRelatedToAttestation };
 export type { CCTPV2Config };

package/index.mjs

@@ -379,8 +379,11 @@ const ArcTestnet = defineChain({
     name: 'Arc Testnet',
     title: 'ArcTestnet',
     nativeCurrency: {
-        name: 'Arc',
-        symbol: 'Arc',
+        name: 'USDC',
+        symbol: 'USDC',
+        // Arc uses native USDC with 18 decimals for gas payments (EVM standard).
+        // Note: The ERC-20 USDC contract at usdcAddress uses 6 decimals.
+        // See: https://docs.arc.network/arc/references/contract-addresses
         decimals: 18,
     },
     chainId: 5042002,
@@ -3638,6 +3641,12 @@ const BalanceError = {
         code: 9001,
         name: 'BALANCE_INSUFFICIENT_TOKEN',
         type: 'BALANCE',
+    },
+    /** Insufficient native token (ETH/SOL/etc) for gas fees */
+    INSUFFICIENT_GAS: {
+        code: 9002,
+        name: 'BALANCE_INSUFFICIENT_GAS',
+        type: 'BALANCE',
     }};
 
 /**
@@ -3860,7 +3869,7 @@ function createValidationErrorFromZod(zodError, context) {
  *
  * @param chain - The blockchain network where the balance check failed
  * @param token - The token symbol (e.g., 'USDC', 'ETH')
- * @param rawError - The original error from the underlying system (optional)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with insufficient token balance details
  *
  * @example
@@ -3873,24 +3882,71 @@ function createValidationErrorFromZod(zodError, context) {
  *
  * @example
  * ```typescript
- * // With raw error for debugging
+ * // With trace context for debugging
  * try {
  *   await transfer(...)
  * } catch (error) {
- *   throw createInsufficientTokenBalanceError('Base', 'USDC', error)
+ *   throw createInsufficientTokenBalanceError('Base', 'USDC', {
+ *     rawError: error,
+ *     balance: '1000000',
+ *     amount: '5000000',
+ *   })
  * }
  * ```
  */
-function createInsufficientTokenBalanceError(chain, token, rawError) {
+function createInsufficientTokenBalanceError(chain, token, trace) {
     return new KitError({
         ...BalanceError.INSUFFICIENT_TOKEN,
         recoverability: 'FATAL',
         message: `Insufficient ${token} balance on ${chain}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
                 token,
-                rawError,
+            },
+        },
+    });
+}
+/**
+ * Creates error for insufficient gas funds.
+ *
+ * This error is thrown when a wallet does not have enough native tokens
+ * (ETH, SOL, etc.) to pay for transaction gas fees. The error is FATAL
+ * as it requires user intervention to add gas funds.
+ *
+ * @param chain - The blockchain network where the gas check failed
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
+ * @returns KitError with insufficient gas details
+ *
+ * @example
+ * ```typescript
+ * import { createInsufficientGasError } from '@core/errors'
+ *
+ * throw createInsufficientGasError('Ethereum')
+ * // Message: "Insufficient gas funds on Ethereum"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createInsufficientGasError('Ethereum', {
+ *   rawError: error,
+ *   gasRequired: '21000',
+ *   gasAvailable: '10000',
+ *   walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+ * })
+ * ```
+ */
+function createInsufficientGasError(chain, trace) {
+    return new KitError({
+        ...BalanceError.INSUFFICIENT_GAS,
+        recoverability: 'FATAL',
+        message: `Insufficient gas funds on ${chain}`,
+        cause: {
+            trace: {
+                ...trace,
+                chain,
             },
         },
     });
@@ -3952,6 +4008,38 @@ function isKitError(error) {
 function isFatalError(error) {
     return isKitError(error) && error.recoverability === 'FATAL';
 }
+/**
+ * Safely extracts error message from any error type.
+ *
+ * This utility handles different error types gracefully, extracting
+ * meaningful messages from Error instances, string errors, or providing
+ * a fallback for unknown error types. Never throws.
+ *
+ * @param error - Unknown error to extract message from
+ * @returns Error message string, or fallback message
+ *
+ * @example
+ * ```typescript
+ * import { getErrorMessage } from '@core/errors'
+ *
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   const message = getErrorMessage(error)
+ *   console.log('Error occurred:', message)
+ *   // Works with Error, KitError, string, or any other type
+ * }
+ * ```
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'An unknown error occurred';
+}
 
 /**
  * Validates data against a Zod schema with enhanced error reporting.
@@ -5383,6 +5471,170 @@ mintAddress) => {
     }
 };
 
+/**
+ * Converts a block number to bigint with validation.
+ *
+ * @param value - The block number value to convert (bigint, number, or string)
+ * @returns The validated block number as a bigint
+ * @throws KitError If the value is invalid (empty string, non-integer, negative, etc.)
+ * @internal
+ */
+const toBlockNumber = (value) => {
+    if (value === null || value === undefined) {
+        throw createValidationFailedError('blockNumber', value, 'cannot be null or undefined');
+    }
+    // Empty string edge case - BigInt('') === 0n which is misleading
+    if (value === '') {
+        throw createValidationFailedError('blockNumber', value, 'cannot be empty string');
+    }
+    // For numbers, validate before BigInt conversion
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || !Number.isInteger(value)) {
+            throw createValidationFailedError('blockNumber', value, 'must be a finite integer');
+        }
+    }
+    let result;
+    try {
+        result = BigInt(value);
+    }
+    catch {
+        throw createValidationFailedError('blockNumber', value, 'cannot be converted to BigInt');
+    }
+    if (result < 0n) {
+        throw createValidationFailedError('blockNumber', result.toString(), 'must be non-negative');
+    }
+    return result;
+};
+/**
+ * Determines whether an attestation has expired based on the current block number.
+ *
+ * An attestation expires when the destination chain's current block number is greater
+ * than or equal to the expiration block specified in the attestation message.
+ * Slow transfers and re-attested messages have `expirationBlock: '0'` and never expire.
+ *
+ * @param attestation - The attestation message containing expiration block information
+ * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
+ * @returns `true` if the attestation has expired, `false` if still valid or never expires
+ * @throws KitError If currentBlockNumber or expirationBlock is invalid
+ *
+ * @example
+ * ```typescript
+ * import { isAttestationExpired } from '@circle-fin/cctp-v2-provider'
+ *
+ * // Check if attestation is expired on EVM chain
+ * const publicClient = await adapter.getPublicClient(destinationChain)
+ * const currentBlock = await publicClient.getBlockNumber()
+ * const expired = isAttestationExpired(attestation, currentBlock)
+ *
+ * if (expired) {
+ *   const freshAttestation = await provider.reAttest(source, burnTxHash)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check on Solana
+ * const slot = await adapter.getConnection(destinationChain).getSlot()
+ * const expired = isAttestationExpired(attestation, slot)
+ * ```
+ */
+const isAttestationExpired = (attestation, currentBlockNumber) => {
+    const currentBlock = toBlockNumber(currentBlockNumber);
+    const expiration = toBlockNumber(attestation.decodedMessage.decodedMessageBody.expirationBlock);
+    // 0n means it never expires (re-attested messages and slow transfers)
+    if (expiration === 0n) {
+        return false;
+    }
+    // Attestation is expired if current block >= expiration block
+    return currentBlock >= expiration;
+};
+/**
+ * Calculates the number of blocks remaining until an attestation expires.
+ *
+ * Returns the difference between the expiration block and the current block number.
+ * Returns `null` if the attestation has `expirationBlock: '0'` (never expires).
+ * Returns `0n` or a negative bigint if the attestation has already expired.
+ *
+ * @param attestation - The attestation message containing expiration block information
+ * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
+ * @returns The number of blocks until expiry as a bigint, or `null` if the attestation never expires
+ * @throws KitError If currentBlockNumber or expirationBlock is invalid
+ *
+ * @example
+ * ```typescript
+ * import { getBlocksUntilExpiry } from '@circle-fin/cctp-v2-provider'
+ *
+ * const publicClient = await adapter.getPublicClient(destinationChain)
+ * const currentBlock = await publicClient.getBlockNumber()
+ * const blocksRemaining = getBlocksUntilExpiry(attestation, currentBlock)
+ *
+ * if (blocksRemaining === null) {
+ *   console.log('Attestation never expires')
+ * } else if (blocksRemaining <= 0n) {
+ *   console.log('Attestation has expired')
+ * } else {
+ *   console.log(`${blocksRemaining} blocks until expiry`)
+ * }
+ * ```
+ */
+const getBlocksUntilExpiry = (attestation, currentBlockNumber) => {
+    const currentBlock = toBlockNumber(currentBlockNumber);
+    const expiration = toBlockNumber(attestation.decodedMessage.decodedMessageBody.expirationBlock);
+    // 0n means it never expires (re-attested messages and slow transfers)
+    if (expiration === 0n) {
+        return null;
+    }
+    // Return the difference (can be negative if expired)
+    return expiration - currentBlock;
+};
+/**
+ * Determines whether a mint failure was caused by an expired attestation.
+ *
+ * This function inspects the error thrown during a mint operation to detect
+ * if the failure is due to the attestation's expiration block being exceeded.
+ * When this returns `true`, the caller should use `reAttest()` to obtain a
+ * fresh attestation before retrying the mint.
+ *
+ * @param error - The error thrown during the mint operation
+ * @returns `true` if the error indicates the attestation has expired, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isMintFailureRelatedToAttestation } from '@circle-fin/cctp-v2-provider'
+ *
+ * try {
+ *   await mintRequest.execute()
+ * } catch (error) {
+ *   if (isMintFailureRelatedToAttestation(error)) {
+ *     // Attestation expired - get a fresh one
+ *     const freshAttestation = await provider.reAttest(source, burnTxHash)
+ *     const newMintRequest = await provider.mint(source, destination, freshAttestation)
+ *     await newMintRequest.execute()
+ *   } else {
+ *     throw error
+ *   }
+ * }
+ * ```
+ */
+const isMintFailureRelatedToAttestation = (error) => {
+    if (error === null || error === undefined) {
+        return false;
+    }
+    const errorString = getErrorMessage(error).toLowerCase();
+    // Check for Solana "MessageExpired" error pattern
+    // Full error: "AnchorError thrown in ...handle_receive_finalized_message.rs:169.
+    //              Error Code: MessageExpired. Error Number: 6016. Error Message: Message has expired."
+    if (errorString.includes('messageexpired')) {
+        return true;
+    }
+    // Check for EVM attestation expiry errors
+    // Contract reverts with: "Message expired and must be re-signed"
+    if (errorString.includes('message') && errorString.includes('expired')) {
+        return true;
+    }
+    return false;
+};
+
 /**
  * Checks if a decoded attestation field matches the corresponding transfer parameter.
  * If the values do not match, appends a descriptive error message to the errors array.
@@ -6226,21 +6478,64 @@ const validateBalanceForTransaction = async (params) => {
         // Extract chain name from operationContext
         const chainName = extractChainInfo(operationContext.chain).name;
         // Create KitError with rich context in trace
-        const error = createInsufficientTokenBalanceError(chainName, token);
-        // Enhance error with additional context for debugging
-        if (error.cause) {
-            const existingTrace = typeof error.cause.trace === 'object' && error.cause.trace
-                ? error.cause.trace
-                : {};
-            error.cause.trace = {
-                ...existingTrace,
-                balance: balance.toString(),
-                amount,
-                tokenAddress,
-                walletAddress: operationContext.address,
-            };
-        }
-        throw error;
+        throw createInsufficientTokenBalanceError(chainName, token, {
+            balance: balance.toString(),
+            amount,
+            tokenAddress,
+            walletAddress: operationContext.address,
+        });
+    }
+};
+
+/**
+ * Validate that the adapter has sufficient native token balance for transaction fees.
+ *
+ * This function checks if the adapter's current native token balance (ETH, SOL, etc.)
+ * is greater than zero. It throws a KitError with code 9002 (BALANCE_INSUFFICIENT_GAS)
+ * if the balance is zero, indicating the wallet cannot pay for transaction fees.
+ *
+ * @param params - The validation parameters containing adapter and operation context.
+ * @returns A promise that resolves to void if validation passes.
+ * @throws {KitError} When the adapter's native balance is zero (code: 9002).
+ *
+ * @example
+ * ```typescript
+ * import { validateNativeBalanceForTransaction } from '@core/adapter'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { isKitError, ERROR_TYPES } from '@core/errors'
+ *
+ * const adapter = createViemAdapterFromPrivateKey({
+ *   privateKey: '0x...',
+ *   chain: 'Ethereum',
+ * })
+ *
+ * try {
+ *   await validateNativeBalanceForTransaction({
+ *     adapter,
+ *     operationContext: { chain: 'Ethereum' },
+ *   })
+ *   console.log('Native balance validation passed')
+ * } catch (error) {
+ *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
+ *     console.error('Insufficient gas funds:', error.message)
+ *   }
+ * }
+ * ```
+ */
+const validateNativeBalanceForTransaction = async (params) => {
+    const { adapter, operationContext } = params;
+    const balancePrepared = await adapter.prepareAction('native.balanceOf', {
+        walletAddress: operationContext.address,
+    }, operationContext);
+    const balance = await balancePrepared.execute();
+    if (BigInt(balance) === 0n) {
+        // Extract chain name from operationContext
+        const chainName = extractChainInfo(operationContext.chain).name;
+        // Create KitError with rich context in trace
+        throw createInsufficientGasError(chainName, {
+            balance: '0',
+            walletAddress: operationContext.address,
+        });
     }
 };
 
@@ -7117,16 +7412,28 @@ class CCTPV2BridgingProvider extends BridgingProvider {
     async bridge(params) {
         // CCTP-specific bridge params validation (includes base validation)
         assertCCTPv2BridgeParams(params);
-        const { source, amount, token } = params;
+        const { source, destination, amount, token } = params;
         // Extract operation context from source wallet context for balance validation
-        const operationContext = this.extractOperationContext(source);
-        // Validate balance for transaction
+        const sourceOperationContext = this.extractOperationContext(source);
+        // Validate USDC balance for transaction on source chain
         await validateBalanceForTransaction({
             adapter: source.adapter,
             amount,
             token,
             tokenAddress: source.chain.usdcAddress,
-            operationContext,
+            operationContext: sourceOperationContext,
+        });
+        // Validate native balance > 0 for gas fees on source chain
+        await validateNativeBalanceForTransaction({
+            adapter: source.adapter,
+            operationContext: sourceOperationContext,
+        });
+        // Extract operation context from destination wallet context
+        const destinationOperationContext = this.extractOperationContext(destination);
+        // Validate native balance > 0 for gas fees on destination chain
+        await validateNativeBalanceForTransaction({
+            adapter: destination.adapter,
+            operationContext: destinationOperationContext,
         });
         return bridge(params, this);
     }
@@ -7785,5 +8092,5 @@ class CCTPV2BridgingProvider extends BridgingProvider {
     }
 }
 
-export { CCTPV2BridgingProvider, getMintRecipientAccount };
+export { CCTPV2BridgingProvider, getBlocksUntilExpiry, getMintRecipientAccount, isAttestationExpired, isMintFailureRelatedToAttestation };
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/provider-cctp-v2",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Circle's official Cross-Chain Transfer Protocol v2 provider for native USDC bridging",
   "keywords": [
     "circle",