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

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
@@ -435,6 +435,8 @@ declare enum Blockchain {
     Ink_Testnet = "Ink_Testnet",
     Linea = "Linea",
     Linea_Sepolia = "Linea_Sepolia",
+    Monad = "Monad",
+    Monad_Testnet = "Monad_Testnet",
     NEAR = "NEAR",
     NEAR_Testnet = "NEAR_Testnet",
     Noble = "Noble",
@@ -644,14 +646,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 +1347,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 +1606,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. */
@@ -3365,6 +3409,16 @@ interface CCTPV2Actions {
         method: 'mint';
         values: BridgeStep;
     };
+    /**
+     * Re-attestation action for CCTP v2 transfers.
+     * Used to request a fresh attestation when the original has expired.
+     */
+    reAttest: {
+        protocol: 'cctp';
+        version: 'v2';
+        method: 'reAttest';
+        values: BridgeFetchAttestationStep;
+    };
 }
 /**
  * CCTPv2 bridging provider interface.
@@ -3917,5 +3971,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 };