> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tac.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Develop Custom Proxy

> Guide how to develop a TAC Proxy

## Documentation

The contents of the *Custom Proxy* page block you are viewing are primarily for informational purposes.
For complete details on Custom Proxy development, please refer to the official documentation linked below:

<CardGroup cols={1}>
  <Card title="Custom Proxy" href="https://www.npmjs.com/package/@tonappchain/evm-ccl" icon="git-commit-horizontal">
    Developer documentation within `@tonappchain/evm-ccl` NPM-package
  </Card>
</CardGroup>

You can also reach out to our developer community in [Telegram](https://t.me/TACbuild) or [Discord](https://discord.gg/tacbuild).

## Installation

Setting up TAC Proxy development requires installing the TAC cross-chain libraries and configuring your Solidity development environment.

TAC Proxy development currently requires Hardhat. Foundry support is planned in future.

<CodeGroup>
  ```bash npm theme={null}
  npm install --save @tonappchain/evm-ccl@latest
  ```

  ```bash yarn theme={null}
  yarn add @tonappchain/evm-ccl@latest
  ```

  ```bash pnpm theme={null}
  pnpm add @tonappchain/evm-ccl@latest
  ```
</CodeGroup>

## Hardhat Environment Setup

Ensure your Hardhat project includes the necessary dependencies:

```json package.json theme={null}
{
  "devDependencies": {
    "@nomicfoundation/hardhat-toolbox": "^5.0.0",
    "hardhat": "^2.22.5",
    "ethers": "^6.13.2",
    "chai": "^4.3.7",
    "ts-node": "^10.9.2",
    "typescript": "^5.6.3",
    "@tonappchain/evm-ccl": "^latest"
  }
}
```

Configure your `hardhat.config.js` for TAC networks:

```javascript hardhat.config.js theme={null}
require("@nomicfoundation/hardhat-toolbox");

module.exports = {
  solidity: {
    version: "0.8.28",
    settings: {
      optimizer: {
        enabled: true,
        runs: 200,
      },
    },
  },
  networks: {
    tac_testnet: {
      url: "https://spb.rpc.tac.build",
      chainId: 2391,
      accounts: [process.env.PRIVATE_KEY || ""],
      gasPrice: 20000000000,
    },
    tac_mainnet: {
      url: "https://rpc.tac.build", 
      chainId: 239,
      accounts: [process.env.PRIVATE_KEY || ""],
      gasPrice: 20000000000,
    },
  },
};
```

## Project Structure Setup

Create an organized project structure for proxy development:

<Steps>
  <Step title="Create Contract Directory" icon="folder-plus">
    Organize your contracts with clear separation between proxy and application logic:

    ```
    contracts/
    ├── proxies/          # TAC proxy contracts
    │   ├── MyProxy.sol
    │   └── MyNFTProxy.sol
    ├── interfaces/       # Custom interfaces
    │   └── IMyDApp.sol
    ├── libraries/        # Utility libraries
    └── mocks/           # Testing contracts
        ├── TestToken.sol
        └── TestNFT.sol
    ```
  </Step>

  <Step title="Setup Testing Environment" icon="test-tube">
    Create a test directory with proper organization:

    ```
    test/
    ├── proxies/          # Proxy-specific tests
    │   ├── MyProxy.test.ts
    │   └── NFTProxy.test.ts
    ├── integration/      # Cross-chain integration tests
    └── helpers/         # Test utilities
        └── tacTestHelpers.ts
    ```
  </Step>

  <Step title="Configure Environment Variables" icon="key">
    Create a `.env` file for sensitive configuration:

    ```bash .env theme={null}
    # Deployment
    PRIVATE_KEY=your_private_key_here

    # Network Configuration
    TAC_TESTNET_RPC=https://spb.rpc.tac.build
    TAC_MAINNET_RPC=https://rpc.tac.build

    # Optional: API Keys
    ETHERSCAN_API_KEY=your_etherscan_api_key
    ```

    <Warning>
      Never commit your `.env` file. Add it to your `.gitignore` immediately.
    </Warning>
  </Step>
</Steps>

## Verify Installation

Create a basic proxy contract to verify your setup:

```solidity contracts/TestProxy.sol theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import { TacProxyV1 } from "@tonappchain/evm-ccl/contracts/proxies/TacProxyV1.sol";
import { TacHeaderV1 } from "@tonappchain/evm-ccl/contracts/core/Structs.sol";

contract TestProxy is TacProxyV1 {
    event MessageReceived(address indexed caller, string message);
    
    constructor(address crossChainLayer) TacProxyV1(crossChainLayer) {}
    
    function receiveMessage(bytes calldata tacHeader, bytes calldata arguments)
        external
        _onlyCrossChainLayer
    {
        TacHeaderV1 memory header = _decodeTacHeader(tacHeader);
        string memory message = abi.decode(arguments, (string));
        
        emit MessageReceived(header.tvmCaller, message);
    }
}
```

Compile to verify setup:

```bash theme={null}
npx hardhat compile
```

<Tip>
  If compilation succeeds, your environment is properly configured for TAC Proxy development.
</Tip>

## Common Setup Issues

<AccordionGroup>
  <Accordion title="Compilation Errors" icon="triangle-alert">
    **Problem**: Import resolution failures or compilation errors

    **Solutions**:

    * Ensure `@tonappchain/evm-ccl` is properly installed
    * Verify Solidity version compatibility (0.8.28+)
    * Check import paths are correct
    * Reset and reinstall dependencies:
      ```bash theme={null}
      rm -rf node_modules package-lock.json
      npm install
      ```
    * Clean and rebuild:
      ```bash theme={null}
      npx hardhat clean && npx hardhat compile
      ```
  </Accordion>

  <Accordion title="Network Connection Issues" icon="wifi-off">
    **Problem**: Unable to connect to TAC network

    **Solutions**:

    * Verify RPC URLs are correct
    * Check network configuration in hardhat.config.js
    * Test connection manually: `curl https://spb.rpc.tac.build`
    * Ensure firewall allows outbound connections

    ```javascript theme={null}
    // Test network connectivity
    const { ethers } = require("hardhat");
    async function testConnection() {
      const provider = new ethers.JsonRpcProvider("https://spb.rpc.tac.build");
      const blockNumber = await provider.getBlockNumber();
      console.log("Connected! Latest block:", blockNumber);
    }
    ```
  </Accordion>

  <Accordion title="Private Key Issues" icon="key">
    **Problem**: Deployment fails with account/key errors

    **Solutions**:

    * Verify private key is in `.env` file
    * Ensure private key starts with `0x` if required by your configuration
    * Check that the account has sufficient TAC tokens for deployment. Get them [here](ecosystem/faucet)
  </Accordion>
</AccordionGroup>

## What's Next?

Environment ready? Let's get to examples:

<CardGroup cols={1}>
  <Card title="Basic Proxy Example" icon="code" href="/proxies/custom-proxy/basic-proxy" />
</CardGroup>