ETH-TON bridge

[tolya-yanot]

Transfer TON Coins between TON and Ethereum network in decentralized way.

[EmelyanenkoK]

This version of the bridge has been improved - see comment below

Summary

Bridge allows to transfer in decentralized way TON Coins between TON Network and Ethereum Network.

Bridge can also work with any EVM-compatible network without modifications and with other networks with minimal modifications.

Glossary

• TON Coin - native coin of TON Network;

• TONCOIN Token - ERC20-compatible token in Ethereum Network;

• TON Bridge smart-contract - smart-contract in TON Network with code https://github.com/newton-blockchain/bridge-func;

• Ethereum Bridge smart-contract - smart-contract in Ethereum Network with code https://github.com/newton-blockchain/bridge-solidity;

• Bridge oracle - Instance of the software serving the bridge; Each instance stores it's public/private pairs of keys for both TON and Ethereum networks. It also should control wallet-type contract on TON network with enough amount of TON Coins to pay network fees;

• Bridge config - TON Network сonfig containing information needed for the bridge to work - such as the current list of oracles and the size of their stakes;
  TON Config is described here.
  The main thing is that the config can only be changed if 3/4 of the TON network validators vote for it.

TON -> Ethereum transfer

1. User sends native TON Coins to TON bridge smart-contract. In the payload of the message, user specifies his Ethereum address where he would like to receive coins;
   Transfer 123 TON Coins to 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF Ethereum address will be:

   ton://transfer/kf9gj99uxzzI40JMyf07i6QRtoBre9sWJ2COapiurSNT0Zop? 
   amount=123000000000&text=swapTo#0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
   

   where kf9gj99uxzzI40JMyf07i6QRtoBre9sWJ2COapiurSNT0Zop is address of TON Bridge smart-contract.

2. TON bridge contract checks incoming message and emit special log message with next payload:

   destination_address // 160 bit, destination address in Ethereum
   amount // 64 bit, amount to receive in Ethereum after fee deducting
   

   TON transaction that emitted log message also contain next information: transaction hash and LT, TON Coins sender address;

3. Each bridge oracle constantly monitor log messages and sign correct transfer requests by his private key; This signature can be acceptable on Ethereum side of the bridge;

4. Bridge oracle submit signature of transfer parameters (amount, destination address, metadata) to Bridge contract of TON side (since it is more economically efficient to accumulate signatures on TON side);

   Technically bridge oracle sends message to TON Bridge smart contract with op = 5 and with voteId and r,s,v numbers of signature; voteId is hash of destination address, amount, sender address and TON transaction hash and LT;

5. As soon as 2/3 of all oracles have submitted signature, user submit it to Ethereum smart-contract by calling the method voteForMinting;

   User get oracles signatures by calling get_external_voting_data get-method of TON smart-contract;

6. Ethereum smart-contract checks signatures, extract signed transfer parameters, mints specified amount of ERC-20 TONCOIN tokens and sends them to the specified user address;

Ethereum -> TON transfer

1. User burns ERC20 TONCOIN tokens by calling burn method of Ethereum bridge smart-contract. In the payload of the message, user specifies tokens amount to burn and user's TON address where he would like to receive coins;

2. Ethereum bridge smart-contract emit special SwapEthToTon event with transfer parameters: sender Ethereum address, destinations TON address, and amount before fee deducting;

   Hash of Ethereum transaction that emitted event also used;

3. Each bridge oracle constantly monitor events and for correct transfer requests sends authorization message for TON side of the bridge;

   Technically bridge oracle sends message to TON Bridge smart contract with op = 4 and Ethereum transaction hash, destinations TON address, and amount before fee deducting;

4. Upon collection of the minimal number of authorizations (2/3 of all oracles), TON side of the bridge extracts transfer parameters from authorized message and release TON coins minus fee to destination address

   Status of authorizations can be obtained by calling get_ton_voting_status get-method of TON smart-contract;

How to become an oracle

1. Oracle need to stake TON coins and specify public keys in smart-contract of TON side of the bridge.
   To do it, oracle should send message with op = 1, as well as Ed25569 (TON) and Secp256k1 (Ethereum) public keys, desired amount of tokens for stake should be attached to this message.

2. During oracles rotaion, TON network validators retrieve information about oracles from the smart-contract and choose desirable ones.

3. TON network validators generate proposal for new oracles set and vote for it. Oracle set params, which include list of oracle and minimal size of the stake is stored in -71 or 71 config parameter of the network.

4. TON bridge smart-contract detects update of 71 config parameters and update information. It also starts process of collection of signatures to update oracle set on Ethereum side of the bridge.

5. Once enough amount of (Ethereum) signatures for new set are collected in TON contract, one of new Oracles should call method voteForNewOracleSet and provide collected set of signatures; thus updating oracle set on Ethereum side of the bridge.

Cheating or malfunctioning oracles

1. If the oracle signs/authorizes wrong parameters of the transfer (e.g. wrong amount of TON Coins), do not signs/authorizes those at all or do not participate in oracle rotation procedure it is considered as cheating.

2. Since all oracle's authorization process occurse publicly on TON blockchain, such a cheating transaction will be visible to everyone and is the reason for the oracle's fine.

3. Since the execution of the transfer requires confirmation of at least 2/3 of all oracles, the cheating transaction will not be executed.

4. Having a cheating transaction, other oracles may vote in the TON-side bridge smart contract to fine cheating oracle and completely remove it from the oracle set.

5. To punish malfunctioning oracle, other oracles generate punishing message which contains

   • code of operation op=1
   • oracle set of misbehaving oracle (note that one oracle may present in many sets)
   • oracle id of misbehaving oracle
   • suggested fine amount
   • malfunctioning info/proofs
     then envelope this message to general ton_on_vote message (message with op=4 and voting_entity body) and send it to TON contract.

6. Upon receiving authorizations from 2/3 of current oracle set, contract execute punishment by subtraction fine from staked amount. If entire stake is fined, oracle gets removed from the set.

Bridge Fee

TON side contract of the bridge controls fee collection. Currently fee consist of two parts: flat fee equal to 5 TON Coins and proportional fee equal to 0.15% of transferred amount.

1. TON -> Ethereum transfers: Upon receiving TON->Ethereum transfer request, TON contract subtract fee and amount in log message already contains amount of TONCOIN Token after fee collection which should be mint on Ethereum side. Transfers less that 5 TON Coins will be rejected by contract.
2. Ethereum -> TON: Upon collection enough amount of authorizations for incoming transfer, contract parses incoming message, determine incoming amount and then subtract fee from that.
3. Collected fee for both incoming and outcoming transfers is divided to two parts: for each transfer 2 TON Coins is withheld by contract itself to cover processing gas costs. Other 3 TON Coins from flat fee and entire proportional fee is accumulated to fee pool of oracles set. This pool is distributed to oracles during oracle set rotation.

[tolya-yanot]

Summary

Bridge allows to transfer in decentralized way TON Coins between TON Network and Ethereum Network.

Bridge can also work with any EVM-compatible network without modifications and with other networks with minimal modifications.

V2 Bridge code was revisited to rebuild it in modular way.

Glossary

• TON Coin - native coin of TON Network;

• TONCOIN Token - ERC20-compatible token in Ethereum Network;

• TON Bridge smart-contract - smart-contract in TON Network with code https://github.com/newton-blockchain/bridge-func/blob/master/func/bridge_code.fc;

• TON Bridge governing contract - multisignature smart contract in TON controlled by oracles with code https://github.com/newton-blockchain/bridge-func/blob/master/func/multisig-code.fc

• TON Bridge signature collector contract - smart contract which stores signatures required for minting TONCOIN Tokens in other networks. https://github.com/newton-blockchain/bridge-func/blob/master/func/votes-collector.fc

• Ethereum Bridge smart-contract - smart-contract in Ethereum Network with code https://github.com/newton-blockchain/bridge-solidity;

• Bridge oracle - Instance of the software serving the bridge; Each instance stores it's public/private pairs of keys for both TON and Ethereum networks. It also should control wallet-type contract on TON network with enough amount of TON Coins to pay network fees;

• Bridge config - TON Network сonfig containing information needed for the bridge to work - such as the current list of oracles and the size of their stakes;
  TON Config is described here.
  The main thing is that the config can only be changed if 3/4 of the TON network validators vote for it.

TON -> Ethereum transfer

1. User sends native TON Coins to TON bridge smart-contract. In the payload of the message, user specifies his Ethereum address where he would like to receive coins;
   Transfer 123 TON Coins to 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF Ethereum address will be:

   ton://transfer/kf9gj99uxzzI40JMyf07i6QRtoBre9sWJ2COapiurSNT0Zop? 
   amount=123000000000&text=swapTo#0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
   

   where kf9gj99uxzzI40JMyf07i6QRtoBre9sWJ2COapiurSNT0Zop is address of TON Bridge smart-contract.

2. TON bridge contract checks incoming message and emit special log message with next payload:

   destination_address // 160 bit, destination address in Ethereum
   amount // 64 bit, amount to receive in Ethereum after fee deducting
   

   TON transaction that emitted log message also contain next information: transaction hash and LT, TON Coins sender address;

3. Each bridge oracle constantly monitor log messages and sign correct transfer requests by his private key; This signature can be acceptable on Ethereum side of the bridge;

4. Bridge oracle submit signature of transfer parameters (amount, destination address, metadata) to TON Bridge signature collector contract (since it is more economically efficient to accumulate signatures on TON side);

   Technically bridge oracle sends message to TON Bridge signature collector contract with op = 5 and with voteId and r,s,v numbers of signature; voteId is hash of destination address, amount, sender address and TON transaction hash and LT;

5. As soon as 2/3 of all oracles have submitted signature, user submit it to Ethereum smart-contract by calling the method voteForMinting;

   User get oracles signatures by calling get_external_voting_data get-method of TON Bridge signature collector contract;

6. Ethereum smart-contract checks signatures, extract signed transfer parameters, mints specified amount of ERC-20 TONCOIN tokens and sends them to the specified user address;

Ethereum -> TON transfer

1. User burns ERC20 TONCOIN tokens by calling burn method of Ethereum bridge smart-contract. In the payload of the message, user specifies tokens amount to burn and user's TON address where he would like to receive coins;

2. Ethereum bridge smart-contract emit special SwapEthToTon event with transfer parameters: sender Ethereum address, destinations TON address, and amount before fee deducting;

   Hash of Ethereum transaction that emitted event and event sequence number in transaction (since one tx may contain a few burns) are also used;

3. Each bridge oracle constantly monitors events and for correct transfer requests generate query with minting parameters and sends authorization message for this query to TON Bridge governing contract;

   Status of authorizations can be obtained by calling check_query_signatures get-method of TON smart-contract;

4. Upon collection of the minimal number of authorizations (2/3 of all oracles), TON Bridge governing contract sends minting query to TON Bridge smart-contract which releases TON coins minus fee to destination address

   Technically query contains op = 4 (which reserved for queries approved by consensus of oracles), inner operation id equal to 0 (swap) and Ethereum transaction hash and internal event index, destination's TON address, and amount before fee deducting;

Stakes

1. Each oracle puts a significant amount of TON coins (stake) on the governing smart contract;

2. The initial stake is 100k TON coins;

3. Governance smart contract allows to send messages only to the bridge smart contract if its address is in the TON config;

4. Governance smart contract freezes all funds for an initial period, sufficient for its inclusion in the TON config. This timeout is available by calling the get_lock_timeout get-method;

5. Oracles can withdraw their stakes only after another governor is assigned in the TON config (by consensus of network validators);

Cheating or malfunctioning oracles

1. If the oracle signs/authorizes wrong parameters of the transfer (e.g. wrong amount of TON Coins), do not signs/authorizes those at all or do not participate in oracle rotation procedure it is considered as cheating.

2. Since all oracle's authorization process occurse publicly on TON blockchain, such a cheating transaction will be visible to everyone and is the reason for the oracle's fine.

3. Since the execution of the transfer requires confirmation of at least 2/3 of all oracles, the cheating transaction will not be executed.

4. Having in their hands confirmation of cheating, oracles will fine the bad oracle when withdrawing stakes from the governance smart contract

Bridge Fee

TON side contract of the bridge controls fee collection. Currently fee consist of two parts: flat fee equal to 5 TON Coins and proportional fee equal to 0.25% of transferred amount.

1. TON -> Ethereum transfers: Upon receiving TON->Ethereum transfer request, TON contract subtract fee and amount in log message already contains amount of TONCOIN Token after fee collection which should be mint on Ethereum side. Transfers less that 5 TON Coins will be rejected by contract.

2. Ethereum -> TON: Upon collection enough amount of authorizations for incoming transfer, contract parses incoming message, determine incoming amount and then subtract fee from that.