@circle-fin/provider-cctp-v2 1.6.2 → 1.7.0

package/index.d.ts

@@ -166,6 +166,43 @@ interface BaseChainDefinition {
      * ```
      */
     kitContracts?: KitContracts;
+    /**
+     * Optional Gateway contract configuration for Gateway protocol support.
+     *
+     * @description When provided, the chain supports the Gateway protocol for
+     * cross-chain transfers. Gateway provides an alternative bridging mechanism
+     * with its own set of smart contracts (GatewayWallet and GatewayMinter).
+     *
+     * Use the {@link isGatewayV1Supported} type guard to check if a chain
+     * supports Gateway v1 before accessing these properties.
+     *
+     * @example
+     * ```typescript
+     * // Chain with Gateway v1 support
+     * const chainWithGateway: ChainDefinition = {
+     *   // ... other properties
+     *   gateway: {
+     *     domain: 6,
+     *     forwarderSupported: { source: true, destination: true },
+     *     contracts: {
+     *       v1: {
+     *         wallet: '0x1234567890abcdef1234567890abcdef12345678',
+     *         minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+     *       }
+     *     }
+     *   }
+     * }
+     *
+     * // Check Gateway support
+     * if (isGatewayV1Supported(chainWithGateway)) {
+     *   console.log('Gateway wallet:', chainWithGateway.gateway.contracts.v1.wallet)
+     * }
+     * ```
+     *
+     * @see {@link GatewayConfig} for the structure of Gateway configuration.
+     * @see {@link isGatewayV1Supported} for checking Gateway v1 support.
+     */
+    gateway?: GatewayConfig;
 }
 /**
  * Represents chain definitions for Ethereum Virtual Machine (EVM) compatible blockchains.
@@ -447,6 +484,128 @@ interface CCTPConfig {
  * ```
  */
 type KitContractType = 'bridge' | 'adapter';
+/**
+ * Configuration for Gateway v1 contracts.
+ *
+ * @description Contains the addresses for the GatewayWallet and GatewayMinter
+ * smart contracts that enable Gateway functionality on a chain.
+ *
+ * @example
+ * ```typescript
+ * import type { GatewayV1Contracts } from '@core/chains'
+ *
+ * const v1Contracts: GatewayV1Contracts = {
+ *   wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *   minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ * }
+ * ```
+ */
+interface GatewayV1Contracts {
+    /**
+     * The address of the GatewayWallet smart contract.
+     *
+     * @description The GatewayWallet contract manages wallet operations
+     * for Gateway transactions.
+     *
+     * Address format varies by blockchain:
+     * - EVM chains: 40-character hexadecimal with 0x prefix (e.g., "0x1234...")
+     * - Solana: Base58-encoded 32-byte address (e.g., "9WzDX...")
+     *
+     * @example "0x1234567890abcdef1234567890abcdef12345678"
+     */
+    wallet: string;
+    /**
+     * The address of the GatewayMinter smart contract.
+     *
+     * @description The GatewayMinter contract handles minting operations
+     * for Gateway transactions.
+     *
+     * Address format varies by blockchain:
+     * - EVM chains: 40-character hexadecimal with 0x prefix (e.g., "0x1234...")
+     * - Solana: Base58-encoded 32-byte address (e.g., "9WzDX...")
+     *
+     * @example "0xabcdef1234567890abcdef1234567890abcdef12"
+     */
+    minter: string;
+}
+/**
+ * Versioned map of Gateway contract configurations.
+ *
+ * @description Maps protocol versions to their contract addresses, following
+ * the same pattern as {@link CCTPContracts}. Each version is optional so that
+ * chains can support any combination of Gateway protocol versions.
+ *
+ * @example
+ * ```typescript
+ * import type { GatewayContracts } from '@core/chains'
+ *
+ * const contracts: GatewayContracts = {
+ *   v1: {
+ *     wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *     minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ *   }
+ * }
+ * ```
+ */
+type GatewayContracts = Partial<{
+    v1: GatewayV1Contracts;
+}>;
+/**
+ * Configuration for the Gateway protocol on a blockchain.
+ *
+ * @description Contains the Gateway domain identifier and version-specific
+ * contract configurations. Follows the same structure as {@link CCTPConfig}:
+ * a domain number plus a versioned contracts map.
+ *
+ * @example
+ * ```typescript
+ * import type { GatewayConfig } from '@core/chains'
+ *
+ * const gatewayConfig: GatewayConfig = {
+ *   domain: 0,
+ *   forwarderSupported: { source: true, destination: true },
+ *   contracts: {
+ *     v1: {
+ *       wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *       minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface GatewayConfig {
+    /**
+     * The Gateway domain identifier for this chain.
+     *
+     * @description Similar to CCTP domains, this number uniquely identifies
+     * the chain within the Gateway protocol.
+     *
+     * @example 0 for Ethereum, 6 for Base
+     */
+    domain: number;
+    /**
+     * Version-specific Gateway contract addresses.
+     *
+     * @description Contains the addresses for each supported Gateway protocol
+     * version, following the same pattern as {@link CCTPContracts}.
+     */
+    contracts: GatewayContracts;
+    /**
+     * Indicate whether the chain supports the Forwarding Service as a source
+     * and/or destination within the Gateway protocol.
+     *
+     * @example
+     * ```typescript
+     * forwarderSupported: { source: true, destination: true }
+     * ```
+     */
+    forwarderSupported: {
+        /** Whether this chain can be used as a source in forwarded transfers. */
+        source: boolean;
+        /** Whether this chain can be used as a destination in forwarded transfers. */
+        destination: boolean;
+    };
+}
 /**
  * Kit-specific contract addresses for enhanced chain functionality.
  *
@@ -521,6 +680,8 @@ declare enum Blockchain {
     Noble_Testnet = "Noble_Testnet",
     Optimism = "Optimism",
     Optimism_Sepolia = "Optimism_Sepolia",
+    Pharos = "Pharos",
+    Pharos_Testnet = "Pharos_Testnet",
     Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
     Polkadot_Westmint = "Polkadot_Westmint",
     Plume = "Plume",
@@ -761,10 +922,39 @@ type EvmPreparedChainRequestParams = {
     functionName: string;
     /** The arguments to pass to the function. */
     args: unknown[];
+    /**
+     * Specific block number to read contract state at (read-only calls only).
+     * Used for historical reads, e.g. checking delegate status at Gateway's
+     * processed height rather than the latest block. Ignored for write
+     * operations (transactions).
+     */
+    blockNumber?: bigint;
 } & Partial<EvmEstimateOverrides>;
+/**
+ * Parameters for preparing an EIP-712 typed data signing request (EVM).
+ * When executed, returns the signature hex string.
+ */
+interface EvmSignTypedDataPreparedChainRequestParams {
+    type: 'evm-sign-typed-data';
+    typedData: {
+        types: Record<string, unknown[]>;
+        domain: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    };
+}
 /**
  * Solana-specific parameters for preparing a transaction.
- * @interface SolanaPreparedChainRequestParams
+ *
+ * @example
+ * ```typescript
+ * import type { SolanaPreparedChainRequestParams } from '@core/adapter'
+ *
+ * const params: SolanaPreparedChainRequestParams = {
+ *   instructions: [transferInstruction],
+ *   addressLookupTables: [],
+ * }
+ * ```
  */
 interface SolanaPreparedChainRequestParams {
     /**
@@ -805,6 +995,24 @@ interface SolanaPreparedChainRequestParams {
      */
     addressLookupTableAddresses?: string[];
 }
+/**
+ * Parameters for preparing a message signing request (Solana).
+ * When executed, returns the signature.
+ *
+ * @example
+ * ```typescript
+ * import type { SolanaSignMessagePreparedChainRequestParams } from '@core/adapter'
+ *
+ * const params: SolanaSignMessagePreparedChainRequestParams = {
+ *   type: 'solana-sign-message',
+ *   message: new TextEncoder().encode('Sign this message'),
+ * }
+ * ```
+ */
+interface SolanaSignMessagePreparedChainRequestParams {
+    type: 'solana-sign-message';
+    message: Uint8Array;
+}
 /**
  * Solana-specific configuration for transaction estimation.
  * @interface SolanaEstimateOverrides
@@ -877,7 +1085,7 @@ interface NoopPreparedChainRequest {
  * Union type for all supported contract execution parameters.
  * Currently only supports EVM chains, but can be extended for other chains.
  */
-type PreparedChainRequestParams = EvmPreparedChainRequestParams | SolanaPreparedChainRequestParams;
+type PreparedChainRequestParams = EvmPreparedChainRequestParams | EvmSignTypedDataPreparedChainRequestParams | SolanaPreparedChainRequestParams | SolanaSignMessagePreparedChainRequestParams;
 /**
  * Response from waiting for a transaction to be mined and confirmed on the blockchain.
  *
@@ -2228,6 +2436,18 @@ interface USDCActionMap {
      * This is a read-only operation.
      */
     balanceOf: Omit<BaseUSDCActions['balanceOf'], 'tokenAddress'>;
+    /**
+     * Get the EIP-712 domain name of the USDC contract on the current chain.
+     *
+     * Automatically uses the USDC contract address for the current chain.
+     * This is a read-only operation with no parameters.
+     */
+    name: ActionParameters & {
+        /**
+         * Optional chain override; defaults to the operation context chain.
+         */
+        chain?: ChainDefinition;
+    };
 }
 
 /**
@@ -2270,6 +2490,252 @@ interface USDTActionMap {
     transfer: BaseUSDTActions['transfer'];
 }
 
+/**
+ * Versioned wrapper for Gateway action namespaces.
+ *
+ * Follows the same pattern as {@link CCTPActionMap}: each version is a
+ * nested namespace so that action keys read `gateway.v1.deposit`, etc.
+ *
+ * @see {@link GatewayV1ActionMap} for v1 action definitions
+ */
+interface GatewayActionMap {
+    /** Gateway protocol v1 operations. */
+    readonly v1: GatewayV1ActionMap;
+}
+/**
+ * Action map for Circle Gateway Wallet v1 contract operations.
+ *
+ * Mirrors the GatewayWallet interface: deposit variants, delegate management,
+ * and balance queries.
+ *
+ * @see https://developers.circle.com/gateway/references/contract-interfaces-and-events
+ * @see https://developers.circle.com/gateway/references/solana-programs
+ */
+interface GatewayV1ActionMap {
+    /**
+     * Deposit tokens after approving the Gateway contract. Balance is credited to the caller.
+     *
+     * Corresponds to `deposit(address token, uint256 value)`.
+     */
+    deposit: ActionParameters & {
+        /** Token contract address (e.g. USDC). */
+        token: string;
+        /** Amount in token's smallest unit. */
+        value: bigint;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Deposit tokens on behalf of another address after approving. Balance is credited to `depositor`.
+     *
+     * Corresponds to `depositFor(address token, address depositor, uint256 value)`.
+     */
+    depositFor: ActionParameters & {
+        /** Token contract address. */
+        token: string;
+        /** Address that will own the resulting balance. */
+        depositor: string;
+        /** Amount in token's smallest unit. */
+        value: bigint;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Deposit with EIP-2612 permit (gasless approval via signature).
+     *
+     * Corresponds to `depositWithPermit(token, owner, value, deadline, signature)` (bytes)
+     * or the overload with (v, r, s). Use `signature` for EIP-7597 (SCA); use (v, r, s) for EOA.
+     */
+    depositWithPermit: ActionParameters & {
+        /** Token contract address. */
+        token: string;
+        /** Depositor's address (owner in permit). */
+        owner: string;
+        /** Amount in token's smallest unit. */
+        value: bigint;
+        /** Permit deadline (Unix timestamp) or max uint256 for no expiration. */
+        deadline: bigint;
+        /** Signature as bytes (EIP-7597) or omit and use v, r, s. */
+        signature?: `0x${string}`;
+        /** ECDSA v (when not using signature bytes). */
+        v?: number;
+        /** ECDSA r (when not using signature bytes). */
+        r?: `0x${string}`;
+        /** ECDSA s (when not using signature bytes). */
+        s?: `0x${string}`;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Deposit with EIP-3009 transferWithAuthorization (receiveWithAuthorization).
+     *
+     * Corresponds to `depositWithAuthorization(token, from, value, validAfter, validBefore, nonce, signature)`
+     * or the overload with (v, r, s).
+     */
+    depositWithAuthorization: ActionParameters & {
+        /** Token contract address. */
+        token: string;
+        /** Depositor's address (from in authorization). */
+        from: string;
+        /** Amount in token's smallest unit. */
+        value: bigint;
+        /** Unix timestamp after which the authorization is valid. */
+        validAfter: bigint;
+        /** Unix timestamp before which the authorization is valid. */
+        validBefore: bigint;
+        /** Unique nonce (bytes32). */
+        nonce: `0x${string}`;
+        /** Signature as bytes (EIP-7598) or omit and use v, r, s. */
+        signature?: `0x${string}`;
+        /** ECDSA v (when not using signature bytes). */
+        v?: number;
+        /** ECDSA r (when not using signature bytes). */
+        r?: `0x${string}`;
+        /** ECDSA s (when not using signature bytes). */
+        s?: `0x${string}`;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Grant spending rights to a delegate on the caller's Gateway account.
+     *
+     * Corresponds to `addDelegate(address token, address delegate)`.
+     */
+    addDelegate: ActionParameters & {
+        /** Token contract address (e.g. USDC). */
+        token: string;
+        /** Address to authorize as a delegate. */
+        delegate: string;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Revoke spending rights from a delegate on the caller's Gateway account.
+     *
+     * Corresponds to `removeDelegate(address token, address delegate)`.
+     */
+    removeDelegate: ActionParameters & {
+        /** Token contract address (e.g. USDC). */
+        token: string;
+        /** Address to revoke as a delegate. */
+        delegate: string;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Check whether an address is authorized as a delegate for a depositor's balance.
+     *
+     * Corresponds to `isAuthorizedForBalance(address token, address depositor, address addr)`.
+     */
+    isDelegate: ActionParameters & {
+        /** Token contract address (e.g. USDC). */
+        token: string;
+        /** The depositor (balance owner) address. */
+        depositor: string;
+        /** The address to check for delegate status. */
+        delegate: string;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+        /** EVM: specific block number to read state at (for finality-aware checks). */
+        blockNumber?: bigint;
+        /** Solana: commitment level for the account read. */
+        commitment?: 'confirmed' | 'finalized';
+    };
+    /**
+     * Start a delayed fund removal from a Gateway account.
+     *
+     * Corresponds to `initiateWithdrawal(address token, uint256 value)` (EVM)
+     * or the `initiate_withdrawal` instruction (Solana).
+     */
+    initiateWithdrawal: ActionParameters & {
+        /** Token contract address (e.g. USDC). */
+        token: string;
+        /** Amount in token's smallest unit. */
+        value: bigint;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Complete a fund removal after the withdrawal delay has elapsed.
+     *
+     * Corresponds to `withdraw(address token)` (EVM) or the `withdraw`
+     * instruction (Solana). No amount parameter -- the contract returns the
+     * full pending withdrawal balance.
+     */
+    withdraw: ActionParameters & {
+        /** Token contract address (e.g. USDC). */
+        token: string;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Read the pending withdrawal balance for a depositor.
+     *
+     * Corresponds to `withdrawingBalance(address token, address depositor)` (EVM)
+     * or reading `withdrawing_amount` from the `GatewayDeposit` PDA (Solana).
+     */
+    withdrawingBalance: ActionParameters & {
+        /** Token contract address (e.g. USDC). */
+        token: string;
+        /** The depositor whose pending withdrawal to query. */
+        depositor: string;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Read the block number at which a pending withdrawal can be completed.
+     *
+     * Corresponds to `withdrawalBlock(address token, address depositor)` (EVM)
+     * or reading `withdrawal_block` from the `GatewayDeposit` PDA (Solana).
+     */
+    withdrawalBlock: ActionParameters & {
+        /** Token contract address (e.g. USDC). */
+        token: string;
+        /** The depositor whose withdrawal block to query. */
+        depositor: string;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Execute gatewayBurn on the Gateway Wallet contract.
+     * Burns tokens from a source chain as part of a cross-chain spend.
+     *
+     * Corresponds to `gatewayBurn(bytes calldataBytes, bytes signature)`.
+     */
+    gatewayBurn: ActionParameters & {
+        /** ABI-encoded burn intent calldata. */
+        calldataBytes: `0x${string}`;
+        /** Signature over the burn intent(s). */
+        signature: `0x${string}`;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Execute gatewayMint on the Gateway Minter contract.
+     * Mints tokens on the destination chain to complete a cross-chain spend.
+     *
+     * Corresponds to `gatewayMint(bytes attestationPayload, bytes signature)`.
+     */
+    gatewayMint: ActionParameters & {
+        /** Attestation payload from the Gateway API. */
+        attestation: `0x${string}`;
+        /** Signature over the attestation. */
+        signature: `0x${string}`;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+    /**
+     * Sign burn intents using EIP-712 typed data (EVM) or binary encoding (Solana).
+     * Returns the signature needed for the Gateway API transfer call.
+     */
+    signBurnIntents: ActionParameters & {
+        /** EIP-712 typed data for EVM, or binary-encoded data for Solana. */
+        typedData: unknown;
+        /** Chain with Gateway v1 (optional; defaults to operation context chain). */
+        chain?: ChainDefinition;
+    };
+}
+
 /**
  * Native token-related action maps for the bridge kit.
  *
@@ -2324,14 +2790,16 @@ interface NativeActionMap {
 interface ActionMap {
     /** CCTP-specific operations with automatic address resolution. */
     readonly cctp: CCTPActionMap;
+    /** Gateway Wallet operations, versioned (e.g. gateway.v1.deposit). */
+    readonly gateway: GatewayActionMap;
+    /** 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. */
     readonly usdc: USDCActionMap;
     /** USDT-specific operations with automatic address resolution. */
     readonly usdt: USDTActionMap;
-    /** Native token operations. */
-    readonly native: NativeActionMap;
     /** Swap operations for DEX aggregator integrations. */
     readonly swap: SwapActionMap;
 }
@@ -3234,6 +3702,7 @@ declare module './types' {
         POL: true;
         PLUME: true;
         MON: true;
+        cirBTC: true;
     }
 }
 
@@ -4428,6 +4897,63 @@ TChainDefinition extends ChainDefinition = ChainDefinition> {
      */
     invocationMeta?: InvocationMeta;
 }
+/**
+ * Machine-readable classification of a {@link BridgeStep} error.
+ *
+ * Consumers may use this field for UX decisions (e.g. distinguish a user
+ * rejection from a wallet capability error) without string-matching on
+ * {@link BridgeStep.errorMessage}. The original human-readable error
+ * message is always preserved for display/logging.
+ *
+ * @remarks
+ * The categories map to the most common failure shapes observed across
+ * the EIP-5792 batched bridge path and the sequential bridge path:
+ *
+ * - `user_rejected` — user declined a wallet request (JSON-RPC `4001`).
+ * - `atomic_unsupported` — wallet reported it cannot perform EIP-5792
+ *   atomic batching on this chain. Covers JSON-RPC `5700` (unsupported
+ *   capabilities), `5710` (chain not supported for the requested
+ *   capability), and `5750` (atomicity requires a wallet upgrade which
+ *   the user declined), or equivalent viem-wrapped messages.
+ * - `batch_too_large` — wallet rejected the batch for exceeding its
+ *   size limit (JSON-RPC `5740`).
+ * - `duplicate_batch_id` — wallet reported a duplicate batchId
+ *   (JSON-RPC `5720`).
+ * - `unknown_bundle` — wallet reported an unknown bundle id during
+ *   status polling (JSON-RPC `5730`).
+ * - `polling_timeout` — SDK polled `wallet_getCallsStatus` until the
+ *   configured timeout without receiving a terminal status.
+ * - `failed_offchain` — wallet reported EIP-5792 `statusCode: 400`
+ *   (batch not included onchain, wallet will not retry).
+ * - `reverted_onchain` — wallet reported EIP-5792 `statusCode: 500`
+ *   (batch reverted completely onchain).
+ * - `partial_reverted` — wallet reported EIP-5792 `statusCode: 600`
+ *   (batch reverted partially onchain).
+ * - `chain_revert` — transaction was mined but reverted on-chain
+ *   (sequential path).
+ * - `unknown` — error did not match any of the above categories.
+ *
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeStep } from '@core/provider'
+ *
+ * const step: BridgeStep = {
+ *   name: 'approve',
+ *   state: 'error',
+ *   errorMessage: 'User rejected the request',
+ *   errorCategory: 'user_rejected',
+ * }
+ *
+ * if (step.errorCategory === 'user_rejected') {
+ *   // silent abort: user intentionally cancelled
+ * } else if (step.errorCategory === 'atomic_unsupported') {
+ *   // hint the user about switching to step-by-step signing
+ * }
+ * ```
+ */
+type BridgeStepErrorCategory = 'user_rejected' | 'atomic_unsupported' | 'batch_too_large' | 'duplicate_batch_id' | 'unknown_bundle' | 'polling_timeout' | 'failed_offchain' | 'reverted_onchain' | 'partial_reverted' | 'chain_revert' | 'unknown';
 /**
  * A step in the bridge process.
  *
@@ -4484,6 +5010,21 @@ interface BridgeStep {
     errorMessage?: string;
     /** Optional raw error object (can be Viem/Ethers/Chain error) */
     error?: unknown;
+    /**
+     * Optional machine-readable classification of the error.
+     *
+     * Present when the step is in `state: 'error'` and the SDK was able to
+     * categorize the failure. See {@link BridgeStepErrorCategory} for the
+     * list of categories and how they map to underlying error shapes.
+     *
+     * @remarks
+     * The human-readable {@link errorMessage} is always preserved for
+     * logging and display; this field is additive and should be preferred
+     * over string-matching `errorMessage` for machine decisions.
+     *
+     * @since 2.0.0
+     */
+    errorCategory?: BridgeStepErrorCategory;
 }
 /**
  * Result object returned after a successful cross-chain bridge operation.