Why Proxy Contracts?
Regular smart contracts can only be called by users on the same blockchain. TAC Proxy contracts solve a different problem: they let TON users call your EVM functions directly. Without proxies:- TON user bridges tokens to TAC
- User switches to MetaMask
- User interacts with your dApp
- User bridges tokens back to TON
- TON user calls your function directly from TON wallet
- ✨ Everything else happens automatically
Your First Proxy Contract
Let’s start with the absolute minimum proxy contract:Understanding the Structure
Required Imports
TacProxyV1
: The base contract that handles all cross-chain communicationTacHeaderV1
: Data structure containing information about the TON user
Inheritance
TacProxyV1
to receive cross-chain calls.
Constructor Parameter
crossChainLayer
address is TAC’s infrastructure contract that will call your functions. You get this address from TAC documentation or contract addresses page.
Function Signature (Critical!)
bytes calldata tacHeader
- Encoded TacHeaderV1 containing TON user informationbytes calldata arguments
- Your custom ABI-encoded parametersexternal
- Must be externally callable_onlyCrossChainLayer
- Security modifier that ensures only CrossChainLayer can call this function
Step-by-Step Walkthrough
Step 1: Decode the Header
header.tvmCaller
- TON user’s address. !!! Important !!! It is always base64 mainnet bounceable format and starts with “EQ” (like “EQAbc123…”)header.operationId
- Unique ID for this operationheader.timestamp
- When the TON transaction happened
Step 2: Decode Your Parameters
arguments
contain whatever data the TON user sent. You decide what format this should be - it could be:
- A single string:
abi.decode(arguments, (string))
- Multiple values:
abi.decode(arguments, (uint256, address, bool))
- A struct:
abi.decode(arguments, (MyCustomStruct))
Step 3: Execute Your Logic
- Store data in state variables
- Call other contracts
- Perform calculations
- Transfer tokens
Sending Responses Back to TON
Sometimes you want to send tokens back to the TON user. Use theOutMessageV1
structure:
Deployment
Deploy your basic proxy like any other contract:What’s Next?
You now understand the basics of TAC Proxy contracts. Ready for more complex patterns?Upgradeable Proxy Contracts
Learn when and how to build contracts that can be upgraded over time
Understanding Message Flow
Deep dive into how cross-chain messages work under the hood
Start simple: Build and test basic proxy contracts before moving to
upgradeable patterns. Most use cases don’t actually need upgradeability.