> ## 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.

# Installation

> Set up the development environment for EVM CCTP Contracts

# Installation & Setup

This guide covers setting up the development environment to work with the EVM CCTP Contracts.

## Prerequisites

Before installing, ensure you have the following tools:

* [Git](https://git-scm.org/downloads) (for submodule management)
* [Node.js](https://nodejs.org/) and Yarn
* [Foundry](https://book.getfoundry.sh/) (recommended version: 0.2.0)
* [Solidity](https://soliditylang.org/) compiler (version 0.7.6)

## Quick Installation

<Steps>
  <Step title="Clone and Initialize Submodules">
    First, initialize and download all required libraries:

    ```bash theme={null}
    git submodule update --init --recursive
    ```

    This downloads dependencies like OpenZeppelin contracts and other libraries used by CCTP.
  </Step>

  <Step title="Install Dependencies">
    Install Node.js dependencies:

    ```bash theme={null}
    yarn install
    ```
  </Step>

  <Step title="Install Foundry">
    Install Foundry CLI from the [official website](https://book.getfoundry.sh/getting-started/installation.html#on-linux-and-macos).

    For Linux and macOS:

    ```bash theme={null}
    curl -L https://foundry.paradigm.xyz | bash
    foundryup
    ```

    <Note>
      To install a specific version of Foundry, see the [versioning guide](https://github.com/foundry-rs/foundry/blob/3f13a986e69c18ea19ce634fea00f4df6b3666b0/foundryup/README.md#usage).
    </Note>
  </Step>
</Steps>

## VSCode IDE Setup

For the best development experience in Visual Studio Code:

<Steps>
  <Step title="Install Solidity Extension">
    Install the [Solidity extension](https://marketplace.visualstudio.com/items?itemName=juanblanco.solidity) from the VSCode marketplace.
  </Step>

  <Step title="Configure Compiler Version">
    1. Navigate to any `.sol` file in the project
    2. Right-click and select **Solidity: Change global compiler version (Remote)**
    3. Select version **0.7.6**

    <Note>
      The CCTP contracts are compiled with Solidity 0.7.6. Using a different version may cause compilation errors.
    </Note>
  </Step>

  <Step title="Install Solhint Extension">
    Install the [Solhint extension](https://marketplace.visualstudio.com/items?itemName=idrabenia.solidity-solhint) for linting support.

    Run the linter:

    ```bash theme={null}
    yarn lint
    ```
  </Step>
</Steps>

## Verify Installation

Test that everything is set up correctly:

### Run Unit Tests

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

For verbose output with console logs:

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

<Note>
  Log verbosity is controlled by the `-v` flag. Use `-vvvvv` for maximum verbosity. Learn more in the [Foundry documentation](https://book.getfoundry.sh/forge/tests.html#logs-and-traces).
</Note>

### Run Integration Tests

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

This sets up an Anvil test node in a Docker container and runs integration tests.

## Alternative Installation: Docker + Foundry

If you prefer using Docker for a containerized environment:

<Steps>
  <Step title="Build Foundry Docker Image">
    ```bash theme={null}
    make build
    ```
  </Step>

  <Step title="Run Foundry Commands in Docker">
    Execute any [forge](https://book.getfoundry.sh/reference/forge/), [anvil](https://book.getfoundry.sh/reference/anvil/), or [cast](https://book.getfoundry.sh/reference/cast/) command:

    ```bash theme={null}
    docker run --rm foundry "<COMMAND>"
    ```

    For example:

    ```bash theme={null}
    docker run --rm foundry "forge test"
    ```

    <Warning>
      Some machines (including those with M1 chips) may encounter issues building the Docker image locally. This is a [known issue](https://book.getfoundry.sh/tutorials/foundry-docker).
    </Warning>
  </Step>

  <Step title="Use Makefile Shortcuts">
    The repository includes predefined commands in the `Makefile` for common operations:

    ```bash theme={null}
    make test        # Run tests in Docker
    make anvil-test  # Run integration tests
    ```
  </Step>
</Steps>

## Development Tools

### Testing

<CodeGroup>
  ```bash Unit Tests theme={null}
  forge test
  ```

  ```bash Docker Tests theme={null}
  make test
  ```

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

  ```bash Verbose Output theme={null}
  forge test -vv
  ```
</CodeGroup>

### Linting

```bash theme={null}
yarn lint
```

This lints all `.sol` files in the `src` and `test` directories.

### Static Analysis

Run Mythril security analysis on specific contracts:

```bash theme={null}
make analyze-message-transmitter
make analyze-token-messenger-minter
```

Or analyze individual files:

```bash theme={null}
myth -v4 analyze $FILE_PATH --solc-json mythril.config.json --solv 0.7.6
```

<Note>
  Static analysis can take several minutes to complete.
</Note>

## Continuous Integration

The repository uses GitHub Actions for automated testing and linting. The workflow configuration is located in `.github/workflows/ci.yml`.

### Security Scanning

Manually trigger Olympix.ai security scanning:

1. Navigate to the **Actions** tab on GitHub
2. Select **Olympix Scan** from the left sidebar
3. Choose the branch and click **Run workflow**

## Troubleshooting

<AccordionGroup>
  <Accordion title="Submodule errors">
    If you encounter missing dependencies, re-run:

    ```bash theme={null}
    git submodule update --init --recursive
    ```
  </Accordion>

  <Accordion title="Compiler version mismatch">
    Ensure you're using Solidity 0.7.6. Check your VSCode settings or run:

    ```bash theme={null}
    solc --version
    ```
  </Accordion>

  <Accordion title="Docker build failures on M1 Macs">
    This is a known issue with Foundry's Docker image. Consider using Foundry directly via `foundryup` instead of Docker.
  </Accordion>

  <Accordion title="Test failures">
    Ensure all dependencies are installed:

    ```bash theme={null}
    yarn install
    git submodule update --init --recursive
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Execute your first cross-chain USDC transfer
  </Card>

  <Card title="Deployment Guide" icon="upload" href="/guides/deployment">
    Learn how to deploy CCTP contracts to your chain
  </Card>
</CardGroup>