Develop Custom 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:

Custom Proxy

Developer documentation within @tonappchain/evm-ccl NPM-package

You can also reach out to our developer community in Telegram or Discord.

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.

npm install --save @tonappchain/evm-ccl@latest

yarn add @tonappchain/evm-ccl@latest

pnpm add @tonappchain/evm-ccl@latest

Hardhat Environment Setup

Ensure your Hardhat project includes the necessary dependencies:

package.json

{
  "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:

hardhat.config.js

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:

Create Contract Directory

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

Setup Testing Environment

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

Configure Environment Variables

Create a .env file for sensitive configuration:

.env

# 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

Never commit your .env file. Add it to your .gitignore immediately.

Verify Installation

Create a basic proxy contract to verify your setup:

contracts/TestProxy.sol

// 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:

npx hardhat compile

If compilation succeeds, your environment is properly configured for TAC Proxy development.

Common Setup Issues

Compilation Errors

Problem: Import resolution failures or compilation errorsSolutions:

Ensure @tonappchain/evm-ccl is properly installed
Verify Solidity version compatibility (0.8.28+)
Check import paths are correct

Reset and reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Clean and rebuild:

npx hardhat clean && npx hardhat compile

Network Connection Issues

Problem: Unable to connect to TAC networkSolutions:

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

// 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);
}

Private Key Issues

Problem: Deployment fails with account/key errorsSolutions:

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

What’s Next?

Environment ready? Let’s get to examples:

Overview

Develop Custom Proxy

Documentation

Custom Proxy

Installation

Hardhat Environment Setup

Project Structure Setup

Verify Installation

Common Setup Issues

What’s Next?

Basic Proxy Example

​Documentation

Custom Proxy

​Installation

​Hardhat Environment Setup

​Project Structure Setup

​Verify Installation

​Common Setup Issues

​What’s Next?

Basic Proxy Example

Documentation

Installation

Hardhat Environment Setup

Project Structure Setup

Verify Installation

Common Setup Issues

What’s Next?