> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/circlefin/evm-cctp-contracts/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions about EVM CCTP Contracts

## General Questions

<AccordionGroup>
  <Accordion title="What is CCTP?">
    Cross-Chain Transfer Protocol (CCTP) is Circle's permissionless on-chain utility that enables native USDC to be transferred securely between blockchain networks.

    Instead of traditional lock-and-mint bridge mechanisms, CCTP uses a burn-and-mint approach:

    1. USDC is burned on the source chain
    2. Circle's attestation service signs the burn message
    3. USDC is minted on the destination chain

    This ensures that USDC remains native and fungible across all supported chains.
  </Accordion>

  <Accordion title="Which chains are supported?">
    CCTP supports multiple EVM-compatible chains. Supported chains are identified by domain IDs configured in the contracts.

    Common domains include:

    * Ethereum mainnet and testnets
    * Avalanche C-Chain
    * Arbitrum
    * Optimism
    * Base
    * Polygon PoS

    Check Circle's official documentation for the complete and up-to-date list of supported chains and their domain IDs.
  </Accordion>

  <Accordion title="How long does a cross-chain transfer take?">
    Transfer time varies by chain due to different finality requirements:

    * **Fast chains** (e.g., Avalanche): 1-2 minutes
    * **Medium chains** (e.g., Polygon): 5-10 minutes
    * **Slower chains** (e.g., Ethereum): 15-20 minutes

    The process includes:

    1. Source chain transaction confirmation
    2. Block finality waiting period
    3. Attestation service signing (usually quick)
    4. Destination chain transaction submission

    V2 introduces finality thresholds that can reduce wait times for unfinalized messages with appropriate fee incentives.
  </Accordion>

  <Accordion title="What are attesters?">
    Attesters are Circle-operated nodes that validate and sign burn messages. They provide the cryptographic proof needed to mint USDC on the destination chain.

    Key points:

    * Multiple attesters create decentralization
    * Threshold signatures ensure security (e.g., 2-of-3)
    * Attesters verify the burn transaction occurred
    * Attestation service coordinates attester signatures

    The attester manager role can enable/disable attesters and set signature thresholds.
  </Accordion>
</AccordionGroup>

## Version Comparison

<AccordionGroup>
  <Accordion title="What's the difference between V1 and V2?">
    V2 introduces significant enhancements over V1:

    **V2 New Features:**

    * **Fee support**: Protocol fees for transfers, with fee recipient role
    * **Hook execution**: Custom logic execution on destination chain via `depositForBurnWithHook`
    * **Finality thresholds**: Configurable finality levels (finalized, confirmed, unfinalized)
    * **Denylist**: Address denylist functionality for compliance
    * **CREATE2 deployment**: Deterministic addresses across chains for easier integration
    * **Min fee controller**: Separate role for managing minimum fee percentages
    * **Enhanced message format**: Additional fields for new functionality

    **V1 Features:**

    * Basic burn-and-mint functionality
    * Simple `depositForBurn` and `depositForBurnWithCaller`
    * Role-based access control
    * Pausability and rescuability

    **Migration considerations:**

    * V1 and V2 use different message versions (0 vs 1)
    * V2 contracts are not backward compatible with V1 messages
    * Both versions can coexist on the same chain
  </Accordion>

  <Accordion title="Should I use V1 or V2?">
    **Use V2 if you need:**

    * Fee-based transfers
    * Hook functionality for custom destination logic
    * Different finality guarantees
    * Address denylist support
    * Future-proof integration

    **Use V1 if:**

    * You need a simpler, battle-tested implementation
    * You don't need advanced V2 features
    * You're integrating with existing V1 deployments

    **Recommendation**: New integrations should generally use V2 for enhanced functionality and future compatibility.
  </Accordion>
</AccordionGroup>

## Function Selection

<AccordionGroup>
  <Accordion title="When should I use depositForBurn vs depositForBurnWithCaller?">
    **V1 Functions:**

    `depositForBurn(amount, destinationDomain, mintRecipient, burnToken)`

    * Anyone can call `receiveMessage` on the destination chain
    * Simpler, more permissionless
    * Use when you don't need to control who submits the destination transaction

    `depositForBurnWithCaller(amount, destinationDomain, mintRecipient, burnToken, destinationCaller)`

    * Only the specified `destinationCaller` can call `receiveMessage`
    * More control over execution
    * Use when you need to restrict destination execution (e.g., specific relayer)

    **V2 Functions:**

    V2 unifies these into `depositForBurn` with a `destinationCaller` parameter:

    * Set `destinationCaller` to `bytes32(0)` for permissionless execution
    * Set `destinationCaller` to specific address for restricted execution
  </Accordion>

  <Accordion title="When should I use depositForBurnWithHook? (V2 only)">
    Use `depositForBurnWithHook` when you need to execute custom logic on the destination chain after minting.

    **Use cases:**

    * Automatic swaps after receiving USDC
    * Depositing into DeFi protocols
    * Forwarding funds to another contract
    * Complex multi-step operations

    **Requirements:**

    * `hookData` must be non-empty
    * Destination contract must implement hook handler interface
    * Additional gas required on destination for hook execution

    **Example:**

    ```solidity theme={null}
    bytes memory hookData = abi.encode(
        targetContract,
        targetFunction,
        targetParams
    );

    tokenMessenger.depositForBurnWithHook(
        amount,
        destinationDomain,
        mintRecipient,
        burnToken,
        destinationCaller,
        maxFee,
        minFinalityThreshold,
        hookData
    );
    ```
  </Accordion>

  <Accordion title="What is minFinalityThreshold in V2?">
    The `minFinalityThreshold` parameter in V2 specifies the minimum level of finality required before attesters will sign the message.

    **Threshold levels:**

    * `2000+`: Finalized (fully confirmed, highest security)
    * `1000-1999`: Confirmed (strong but not final)
    * `500-999`: Unfinalized (faster but requires fees)

    **Trade-offs:**

    * **Higher threshold**: Slower but more secure, no fees required
    * **Lower threshold**: Faster but requires higher fees, small reorg risk

    **Minimum for TokenMessenger**: 500 (TOKEN\_MESSENGER\_MIN\_FINALITY\_THRESHOLD)

    **Use cases:**

    * Time-sensitive transfers: Use 500-999 with appropriate fees
    * High-value transfers: Use 2000+ for maximum security
    * Standard transfers: Use 1000 for balanced speed and security
  </Accordion>
</AccordionGroup>

## Features and Mechanisms

<AccordionGroup>
  <Accordion title="How does the pause mechanism work?">
    CCTP contracts include an emergency pause mechanism:

    **Pause functionality:**

    * Pauser role can call `pause()` to stop operations
    * Pauser role can call `unpause()` to resume operations
    * Only affects state-changing functions (marked with `whenNotPaused`)
    * View functions continue to work during pause

    **What gets paused:**

    * `depositForBurn` / `depositForBurnWithCaller` (V1)
    * `depositForBurn` / `depositForBurnWithHook` (V2)
    * `sendMessage` (MessageTransmitter)
    * `receiveMessage` (MessageTransmitter)

    **What still works:**

    * Reading contract state
    * Querying balances and allowances
    * Checking pause status

    **Checking pause status:**

    ```solidity theme={null}
    bool isPaused = messageTransmitter.paused();
    ```
  </Accordion>

  <Accordion title="How do fees work in V2?">
    V2 introduces a flexible fee system:

    **Fee structure:**

    * Fees are paid in the same token being transferred (USDC)
    * Fees are deducted from the transfer amount on destination
    * Fee recipient receives minted fees separately

    **Fee parameters:**

    * `maxFee`: Maximum fee sender is willing to pay
    * `minFee`: Minimum fee percentage set by protocol (basis points)
    * `feeExecuted`: Actual fee charged (recorded in message)

    **Calculating minimum fee:**

    ```javascript theme={null}
    const minFeeAmount = await tokenMessenger.methods
        .getMinFeeAmount(amount)
        .call();
    ```

    **Fee validation:**

    ```solidity theme={null}
    require(maxFee < amount, "Max fee must be less than amount");
    require(maxFee >= minFeeAmount, "Insufficient max fee");
    ```

    **Fee distribution:**

    * Recipient receives: `amount - feeExecuted`
    * Fee recipient receives: `feeExecuted`
  </Accordion>

  <Accordion title="What is the denylist in V2?">
    V2 includes a denylist mechanism for regulatory compliance:

    **How it works:**

    * Denylister role can add/remove addresses
    * Checks both `msg.sender` and `tx.origin`
    * Denylisted addresses cannot call `depositForBurn` functions
    * Reverts with "Denylistable: account is on denylist"

    **Checking denylist status:**

    ```javascript theme={null}
    const isDenylisted = await tokenMessenger.methods
        .isDenylisted(address)
        .call();
    ```

    **Impact:**

    * Prevents initiating new transfers
    * Does not affect receiving USDC from other addresses
    * Does not freeze existing USDC balances
  </Accordion>

  <Accordion title="How does CREATE2 deployment work in V2?">
    V2 uses CREATE2 for deterministic contract addresses across chains:

    **Benefits:**

    * Same contract addresses on all chains
    * Easier integration (one address to remember)
    * Simplified remote resource configuration
    * Predictable deployment planning

    **Components:**

    * `Create2Factory`: Deploys contracts deterministically
    * Salt-based addressing: Same salt = same address
    * Cross-chain coordination: Deploy in same order everywhere

    **Predicting addresses:**

    ```bash theme={null}
    forge script scripts/v2/PredictCreate2Deployments.s.sol \
        --sig "tokenMessengerV2Proxy(address)" \
        <create2FactoryAddress>
    ```
  </Accordion>
</AccordionGroup>

## Development and Testing

<AccordionGroup>
  <Accordion title="How do I test CCTP locally?">
    Use Foundry's testing framework:

    **Unit tests:**

    ```bash theme={null}
    forge test
    ```

    **Integration tests with Anvil:**

    ```bash theme={null}
    make anvil-test
    ```

    **Debug tests:**

    ```bash theme={null}
    forge test -vv  # Show console.log output
    forge test -vvv  # Show stack traces
    ```

    Test examples are available in the `test/` directory, including V1 and V2 test suites.
  </Accordion>

  <Accordion title="What are the gas costs?">
    Gas costs vary by chain and operation:

    **Typical costs:**

    * `depositForBurn`: \~100-200k gas
    * `depositForBurnWithHook` (V2): \~150-300k gas (depends on hook)
    * `receiveMessage`: \~100-200k gas
    * Token approval: \~50k gas

    **Factors affecting gas:**

    * Chain gas price
    * Message body size
    * Hook complexity (V2)
    * First-time operations (e.g., first approval)

    Always estimate gas before transactions and add a buffer for safety.
  </Accordion>

  <Accordion title="Can I use CCTP on testnets?">
    Yes! CCTP is available on various testnets:

    **Common testnets:**

    * Ethereum Sepolia
    * Avalanche Fuji
    * Arbitrum Sepolia
    * Optimism Sepolia
    * Base Sepolia

    **Testnet attestation service:**

    ```
    https://iris-api-sandbox.circle.com/attestations/{messageHash}
    ```

    **Getting testnet USDC:**

    * Use Circle's testnet faucet
    * Check chain-specific faucets
    * Bridge from other testnets using CCTP
  </Accordion>
</AccordionGroup>

## Need More Help?

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Common issues and solutions
  </Card>

  <Card title="Security" icon="shield-halved" href="/resources/security">
    Security best practices and reporting
  </Card>
</CardGroup>