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

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -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. */
@@ -2614,15 +2656,39 @@ interface BridgeResult {
  *
  * This interface provides detailed information about the expected costs
  * for a transfer, including gas fees on different chains and protocol fees.
+ * It also includes the input context (token, amount, source, destination) to
+ * provide a complete view of the transfer being estimated.
  *
  * @example
  * ```typescript
  * const estimate: EstimateResult = await provider.estimate(source, dest, '100')
+ * console.log('Estimating transfer of', estimate.amount, estimate.token)
+ * console.log('From', estimate.source.chain.name, 'to', estimate.destination.chain.name)
  * console.log('Total gas fees:', estimate.gasFees.length)
  * console.log('Protocol fees:', estimate.fees.length)
  * ```
  */
 interface EstimateResult {
+    /** The token being transferred */
+    token: 'USDC';
+    /** The amount being transferred */
+    amount: string;
+    /** Information about the source chain and address */
+    source: {
+        /** The source wallet/contract address */
+        address: string;
+        /** The source blockchain network */
+        chain: Blockchain;
+    };
+    /** Information about the destination chain and address */
+    destination: {
+        /** The destination wallet/contract address */
+        address: string;
+        /** The destination blockchain network */
+        chain: Blockchain;
+        /** Optional custom recipient address for minted funds. */
+        recipientAddress?: string;
+    };
     /** Array of gas fees required for the transfer on different blockchains */
     gasFees: {
         /** The name of the step */
@@ -3373,6 +3439,20 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
      * @returns A promise that resolves to the attestation message.
      */
     fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
+    /**
+     * Requests a fresh attestation for an expired attestation.
+     *
+     * This method is used when the original attestation has expired before the mint
+     * transaction could be completed. It fetches the existing attestation data to
+     * extract the nonce, requests re-attestation from Circle's API, and then polls
+     * for the fresh attestation.
+     *
+     * @param source - The source wallet context containing the chain definition and wallet address.
+     * @param txHash - The transaction hash of the original burn transaction.
+     * @param config - Optional polling configuration overrides.
+     * @returns A promise that resolves to the fresh attestation message.
+     */
+    reAttest<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Mints the amount of tokens for the destination wallet.
      *
@@ -3685,6 +3765,56 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * ```
      */
     fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, transactionHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
+    /**
+     * Requests a fresh attestation for an expired attestation.
+     *
+     * This method is used when the original attestation has expired before the mint
+     * transaction could be completed. It performs three steps:
+     * 1. Fetches the existing attestation data to extract the nonce
+     * 2. Requests re-attestation from Circle's API using the nonce
+     * 3. Polls for the fresh attestation and returns it
+     *
+     * @typeParam TFromAdapterCapabilities - The type representing the capabilities of the source adapter
+     * @param source - The source wallet context containing the chain definition and wallet address
+     * @param transactionHash - The transaction hash of the original burn transaction
+     * @param config - Optional polling configuration overrides for timeout, retries, and delay
+     * @returns A promise that resolves to the fresh attestation message
+     * @throws {Error} With "Failed to re-attest: No nonce found for transaction" if the original
+     *   attestation cannot be found or has no nonce
+     * @throws {Error} With "Failed to re-attest: No attestation found after re-attestation request"
+     *   if the fresh attestation cannot be retrieved
+     * @throws {Error} With "Failed to re-attest: {details}" for other errors
+     *
+     * @example
+     * ```typescript
+     * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+     * import { Chains } from '@core/chains'
+     *
+     * const provider = new CCTPV2BridgingProvider()
+     *
+     * // After a mint fails due to expired attestation, request a fresh one
+     * const source = {
+     *   adapter: viemAdapter,
+     *   chain: Chains.EthereumSepolia,
+     *   address: '0x1234...'
+     * }
+     *
+     * try {
+     *   const freshAttestation = await provider.reAttest(
+     *     source,
+     *     '0xabc123...', // Original burn transaction hash
+     *     { timeout: 10000, maxRetries: 5 }
+     *   )
+     *
+     *   // Use the fresh attestation to retry the mint
+     *   const mintRequest = await provider.mint(source, destination, freshAttestation)
+     *   const result = await mintRequest.execute()
+     * } catch (error) {
+     *   console.error('Re-attestation failed:', error.message)
+     * }
+     * ```
+     */
+    reAttest<TFromAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, transactionHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Checks if both source and destination chains support CCTP v2 transfers.
      *
@@ -3829,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 };