Trustless Bridge Architecture (TVM ↔ TVM)

Documentation on the architecture of the Trustless cross-chain bridge for token transfers between TVM networks.

Principal Scheme

Glossary

Native and Alien Tokens

Term	Description
Native token	A token that was originally created and exists in this network. When transferred to another network — locked in the Proxy contract.
Alien token	A wrapped representation of a token from another network. Created (mint) in the destination network during incoming transfer. Burned during reverse transfer.

Example:

• USDT on TON network is a Native token for TON
• When transferring USDT from TON to Tycho:
  • On TON: USDT is locked in NativeProxy (remains Native)
  • On Tycho: wUSDT is minted (Alien token)

Transfer Structure

Important to Understand

Each cross-chain transfer consists of two parts:

1. Source network part — locking/burning tokens and emitting an event
2. Destination network part — verification and minting/unlocking tokens

Event Contract

For each transfer, a separate Event contract is deployed in the destination network. It performs two key functions:

1. Double-spending protection — a contract with a unique address (derived from transaction data) guarantees that one transaction can only be processed once
2. Participation in Merge logic — the Event contract determines which token the user receives (derive or canon) based on MergePool settings

System Components

On-chain Components (Smart Contracts)

LiteClient

Light client contract storing information about key blocks of the other network.

Stored data:

• current_seq_no — current key block sequence number
• current_epoch_since/until — validator epoch start/end timestamps
• current_cutoff_weight — minimum signature weight (2/3 + 1 of total validator weight)
• current_validators_set — validator set with public keys and weights

Operations:

• new_key_block — processing new key block, signature verification, validator set update
• check_block — block signature verification against current validator set

TransactionChecker

Contract for verifying transactions from another network via Merkle proofs.

Operations:

• check_transaction — transaction verification:
  1. Extracts transaction and block Merkle proofs
  2. Verifies that transaction exists in the block
  3. Sends request to LiteClient for block signature verification
  4. On successful verification sends response::transaction_checked

ProxyMultiVaultNative (NativeProxy)

Proxy contract for working with native tokens (jettons).

Main functions:

• Receives native tokens (lock) during outgoing transfers
• Sends native tokens (unlock) during incoming transfers
• Emits events for transfers to other networks
• Manages fees and daily limits

Key methods:

• transferNotification — callback when receiving jetton tokens, initiates outgoing transfer
• onTvmEventConfirmedExtended — processing confirmed event (completing incoming transfer)

ProxyMultiVaultAlien (AlienProxy)

Proxy contract for working with alien tokens.

Main functions:

• Mints alien tokens during incoming transfers
• Processes callback after burning alien tokens and initiates outgoing transfer
• Manages deployment of new alien tokens
• Works with MergePool/MergeRouter for token consolidation

Key methods:

• onTvmEventConfirmedExtended — minting alien tokens during incoming transfer
• onAcceptTokensBurn — callback from jetton contract after token burning
• deployTvmAlienToken — deploying new alien token

EventConfiguration (TvmTvmEventConfiguration)

Event configuration contract managing event contract deployment.

Stored data:

• TransactionChecker address
• Event contract code
• Proxy contract address
• Configuration parameters

Key methods:

• deployEvent — deploying new event contract for incoming transfer processing

MultiVaultTvmTvmEvent (Alien / Native)

Event contracts for processing specific transfers.

Lifecycle (enum Status):

Code	Status	Description
0	Initializing	Initial state
1	Pending	Awaiting verification via TransactionChecker
2	Confirmed	Transfer confirmed, proxy called, tokens delivered
3	Rejected	Transfer rejected
4	Cancelled	Transfer cancelled by user
5	LimitReached	Daily limit exceeded, awaiting approval
6	LiquidityRequested	Liquidity requested
7	LiquidityProvided	Liquidity provided
8	Verified	Transaction verified (trustless)

Key methods:

• processProof — transaction proof processing, calling TransactionChecker
• onTrustlessVerify — callback from TransactionChecker on successful verification
• _onConfirm — calling proxy to complete transfer

MergePool / MergeRouter

Contracts for consolidating alien tokens from different networks into a single representation (canon token).

MergeRouter:

• Routing to corresponding MergePool for token

MergePool:

• Stores derive-token to canon-token mapping
• Conversion between decimals of different representations

Off-chain Components (Backend)

Sync Service

Background service for synchronizing key blocks between networks.

Important

Sync Service runs in background mode and synchronizes key blocks periodically, not for each transfer. This is necessary to maintain current validator set in LiteClient.

Functions:

• Monitors key blocks in source network
• Uploads current validator set information to destination network's LiteClient contract
• Calls new_key_block on LiteClient to update validator set

Proof API

Light node synchronizing blocks and providing API for building proof chain.

Functions:

• Builds Merkle tree proof for transaction
• Builds block proof
• Endpoint: GET /v1/proof_chain/{address}/{lt} — returns BOC with proof chain

Bridge API

Event indexer for specific TVM network.

Functions:

• Event indexing from proxy contracts
• Transfer status tracking
• Providing data for event contract deployment

Bridge Aggregator API

Aggregator over all APIs for working with transfers.

Functions:

• Preparing payload for transfers
• Combining transfer history from all networks
• Transfer status tracking regardless of networks

---

Transfer Flows

Lock Native → Mint Alien

This flow describes transferring a native token from source network to destination network where it becomes an alien token.

Step-by-step Description

Step 1-2: Initiation and locking

User sends jetton tokens to NativeProxy. The payload specifies recipient address and target network. Proxy locks tokens and emits TvmTvmNative event.

Step 3: Event contract deployment

Proof API generates transaction Merkle proof. EventConfiguration deploys event contract with proof data in destination network.

Step 4-5: Verification

Event contract calls TransactionChecker for transaction verification. TransactionChecker verifies Merkle proof and requests LiteClient for block signature verification.

Step 6-7: Confirmation

On successful verification, TransactionChecker calls onTrustlessVerify(true) on Event contract. Status changes to Verified. Then Event contract calls _onConfirm(), which:

• Changes status to Confirmed
• Sends onTvmEventConfirmedExtended to AlienProxy

Step 8-9: Minting

AlienProxy receives confirmation, checks limits, charges fee and mints alien tokens to recipient.

---

Burn Alien → Unlock Native

Reverse flow: returning alien token to original network where native tokens are unlocked.

Step-by-step Description

Step 1-2: User burns alien tokens via AlienProxy. Proxy emits TvmTvmAlien event.

Step 3-5: Event contract deployment and verification similar to previous flow.

Step 6-7: Event contract receives confirmation, status changes Verified → Confirmed.

Step 8-9: NativeProxy receives confirmation and unlocks native tokens to recipient.

---

Lock Native → Unlock Native

Flow for transferring native token between networks where the token is native in both networks.

Implementation Detail

The transfer is technically executed via the Alien flow, but AlienProxy performs a check: if native-native scenario is configured for the token (entry exists in predeployedTokens), AlienProxy doesn't mint the token but proxies the call to NativeProxy.

Step-by-step Description

Step 1-2: User sends native tokens to NativeProxy in source network. Tokens are locked, TvmTvmNative event is emitted.

Step 3-5: In destination network, MultiVaultTvmTvmEventAlien (not Native!) is deployed via AlienEventConfiguration. Verification happens via TransactionChecker.

Step 6-7: Event contract calls receivePredeployedToken on AlienProxy. If token is registered in predeployedTokens, PredeployedTokenData with nativeProxyTokenWallet address is returned.

Step 8-9: After verification, Event contract calls onTvmEventConfirmedExtended on AlienProxy, passing nativeProxyTokenWallet in metadata.

Step 10: AlienProxy checks nativeProxyTokenWallet.hasValue(). If true — doesn't mint, but proxies call to NativeProxy via proxyMultiVaultNative.onTvmEventConfirmedExtended().

Step 11: NativeProxy receives call (accepts from AlienProxy or directly from EventConfig), unlocks native tokens and sends to recipient.

When is this flow used?

Lock Native → Unlock Native is used when token is configured as native in both networks via predeployedTokens in AlienProxy. This is possible for:

• Wrapped native tokens (e.g., wTON)
• Tokens specifically configured by administrator

Configuration happens via registering PredeployedTokenData in tvmConfiguration.predeployedTokens mapping.