Proxy Apps
Smart contracts that translate between TON and EVM, making cross-chain applications feel native to both ecosystems
Proxy Apps are the interface layer that makes hybrid dApps possible. They consist of smart contracts on both TON and TAC EVM that handle the complexities of cross-chain communication, asset management, and protocol translation. From a user’s perspective, proxy apps make EVM applications feel completely native to TON.
How Proxy Apps Work
Proxy apps operate on both sides of the cross-chain bridge, each handling different aspects of the user experience and technical integration.
Proxy apps handling cross-chain interaction between TON users and EVM contracts
TON Side: SDK-Managed Proxies
On the TON side, proxy functionality is handled automatically by the TAC SDK rather than requiring developers to write custom smart contracts.
-
User Transaction Handling: When a TON user initiates a transaction with a hybrid dApp, the SDK formats the request appropriately for cross-chain delivery. This includes encoding method parameters and preparing asset transfer instructions.
-
Asset Locking: The SDK manages the locking of user assets in the TON Adapter contracts. Users simply approve transactions in their familiar TON wallets, while the SDK handles the technical details of cross-chain asset preparation.
-
Status Monitoring: The SDK continuously monitors transaction status and provides real-time updates to the user interface. This allows hybrid dApps to show progress indicators and handle errors gracefully.
-
Message Formatting: All the complex message structuring required by the TON Adapter is handled automatically, including proper encoding of target addresses, method signatures, and parameters.
Developers don’t need to write TON-side proxy contracts - the TAC SDK provides all necessary functionality through JavaScript/TypeScript libraries.
EVM Side: Custom Solidity Contracts
On the TAC EVM side, developers create custom proxy contracts that receive and process cross-chain messages from the TON Adapter.
-
Message Reception: EVM proxy contracts implement specific function signatures that the TON Adapter calls when delivering cross-chain messages. These functions must accept exactly two
bytes
parameters: the TAC header and the application arguments. -
Header Decoding: The first parameter contains encoded metadata about the cross-chain operation, including the original TON user’s address, timestamp information, and unique operation identifiers.
-
Parameter Processing: The second parameter contains application-specific data encoded by the frontend. Proxy contracts decode these parameters to understand what operation the user wants to perform.
-
Target Application Interaction: After processing the cross-chain message, proxy contracts interact with the actual target applications - DEXes, lending protocols, NFT contracts, or any other EVM smart contracts.
EVM Proxy Contract Architecture
Required Function Signature
All EVM proxy contracts must implement functions with this exact signature to receive cross-chain calls:
The function name can be customized, but the parameter structure is fixed by the TON Adapter protocol.
Security Modifiers
_onlyCrossChainLayer Modifier
_onlyCrossChainLayer Modifier
This critical security modifier ensures that only the TON Adapter’s CrossChainLayer contract can call proxy functions. Without this protection, malicious actors could potentially call proxy functions directly and bypass cross-chain validation.
The modifier is inherited from base proxy contract classes and validates that msg.sender
matches the authorized
CrossChainLayer address.
Asset Validation
Asset Validation
Before proxy functions are called, the TON Adapter automatically transfers any bridged assets to the proxy contract. Proxy contracts can trust that these assets are available and properly validated.
However, proxy contracts should still implement proper checks for expected asset amounts and types to ensure they match the intended operation.
TAC Header Structure
The TAC header contains essential metadata about every cross-chain operation:
Proxy contracts decode this header to access information about the original user and operation context.
Development Patterns
Basic Proxy Contract Template
Upgradeable Proxy Contracts
For applications that need upgrade capabilities, TAC provides upgradeable proxy contract templates:
Asset Handling
Proxy contracts must carefully manage assets as they flow between chains and interact with target applications.
Automatic Asset Transfer
-
Pre-Function Execution: Before calling proxy functions, the TON Adapter automatically transfers bridged assets to the proxy contract. This includes both newly minted tokens (from TON) and unlocked tokens (from previous EVM operations).
-
Asset Availability: Proxy contracts can immediately use these assets without additional transfer operations. The amounts are guaranteed to match what was specified in the original cross-chain message.
-
Asset Validation: While the TON Adapter validates assets during message processing, proxy contracts should implement additional checks to ensure received assets match expected parameters.
Target Contract Integration
Return Message Creation
When operations complete successfully, proxy contracts can send assets and data back to TON users through return messages.
-
Asset Preparation: Any tokens being returned must be approved for the CrossChainLayer contract to handle the bridging process.
-
Message Structure: Return messages use the same
OutMessageV1
structure, specifying the target TON address, assets to bridge, and optional payload data. -
Automatic Processing: The TON Adapter handles return messages through the same consensus mechanism, ensuring secure delivery back to TON users.
Proxy Generation and Deployment
For complex applications with unique requirements, developers create custom proxy contracts that implement specific business logic.
-
Complex State Management: Applications with sophisticated state transitions or multi-step operations require custom proxy logic to handle the complexity properly.
-
Integration Requirements: When integrating with multiple protocols or handling complex asset flows, custom proxies provide the flexibility needed for proper implementation.
-
Business Logic: Unique application requirements like custom validation rules, special fee structures, or complex user permissions need custom proxy development.
Testing and Development
Local Testing Environment
TAC provides comprehensive testing utilities for proxy contract development:
Integration Testing
-
Cross-Chain Simulation: The testing SDK simulates the complete cross-chain flow, including sequencer validation and asset bridging operations.
-
Asset Management Testing: Tests verify that assets are properly locked, minted, burned, and unlocked throughout the cross-chain process.
-
Error Scenario Handling: Testing includes failure cases to ensure proxy contracts handle errors gracefully and protect user assets.
What’s Next?
Understanding proxy apps helps you build the interface layer that makes hybrid dApps possible. Explore related concepts to build more sophisticated applications.