How bridging FA tokens works

The process of bridging FA tokens is similar to the process of bridging tez. In short, the bridge uses tickets to send tokens from the source network to the target network.

Contracts

The bridging process relies on smart contracts that convert tokens to tickets and transfer the tickets between Tezos and Etherlink. These contracts are an implementation of the TZIP-029 standard for bridging between Tezos and Etherlink.

Each FA token needs its own copy of these contracts to be able to bridge the token:

• Ticketer contract: Stores tokens and issues tickets that represent them
• Token bridge helper contract: Accepts requests to bridge tokens on layer 1, uses the ticketer contract to get tickets for them, and sends the tickets to Etherlink
• ERC-20 proxy contract: Stores tickets and mints ERC-20 tokens that are equivalent to the FA tokens in layer 1

You can run these transactions using the bridge, as described in Bridging FA tokens between Tezos layer 1 and Etherlink. For information about how to run these transactions without using the bridge, see Sending FA bridging transactions. Examples of these contracts and tools to deploy them are available in the repository https://github.com/baking-bad/etherlink-bridge.

Depositing tokens from layer 1 to Etherlink

The process of bridging FA-compatible tokens from layer 1 to Etherlink (also known as depositing tokens) follows these general steps:

1. A Tezos user gives the token bridge helper contract access to their tokens.

   • For FA1.2 tokens, the user gives the helper contract an allowance of tokens.
   • For FA2 tokens, the user makes the helper contract an operator of their tokens.

   For information about token access control, see Token standards on docs.tezos.com.

2. The user calls the helper contract's deposit entrypoint. The request includes the amount of tokens to bridge, the address of the Etherlink Smart Rollup, and the user's Etherlink wallet address, but not the tokens themselves.

3. The token bridge helper contract stores the address of the Etherlink Smart Rollup and the user's Etherlink address temporarily.

4. The helper contract (as an operator of the user's tokens or with an allowance of the user's tokens) calls the token contract to transfer the tokens from the user's account to its account.

5. The helper contract calls the ticketer contract's deposit entrypoint and includes the tokens.

6. The ticketer contract stores the tokens and creates a ticket that represents the receipt of the tokens.

7. The ticketer contract sends the ticket back to the helper contract.

8. The helper contract forwards the ticket to the Smart Rollup inbox and clears its storage for the next transfer.

9. The Etherlink Smart Rollup kernel receives the ticket and puts it and information about it (including the addresses of the proxy contract and the user's Etherlink wallet address) in the delayed inbox.

10. The sequencer reads the ticket and information about it from the delayed inbox, leaves the ticket in control of the Smart Rollup itself, and calls the null address precompiled contract (0x000...000) with the information.

11. The null address precompile sends the information about the deposit to the FA bridging precompiled contract (0xff0...0002), which then emits a QueuedDeposit event which contains the depositId information needed to complete the transfer.

12. Any user can call the FA bridging precompiled contract's claim function, which causes the contract to call the ERC-20 proxy contract. For tokens supported by the bridge, an automated program calls the claim function for you.

13. The ERC-20 proxy contract mints the equivalent tokens and sends them to the user's Etherlink account.

This diagram is an overview of the process of bridging tokens from layer 1 to Etherlink:

Withdrawing tokens from Etherlink to layer 1

The process of bridging FA-compatible tokens from Etherlink to layer 1 (also known as withdrawing tokens) follows these general steps:

1. The user calls the FA bridging precompiled contract on Etherlink and includes this information:

   • The address of the ERC-20 proxy contract that manages the tokens
   • The user's layer 1 address or the address of a contract to send the tokens to
   • The amount of tokens to bridge
   • The address of the ticketer contract on layer 1
   • The content of the ticket to remove from the proxy contract (not the ticket itself)

2. The precompiled contract generates calls the withdrawal endpoint of the ERC-20 proxy contract.

3. The proxy contract sends the information about the withdrawal to the helper contract by putting it in a transaction in the Smart Rollup outbox. This transaction includes the target layer 1 address.

   This outbox message becomes part of Etherlink's commitment to its state.

4. When the commitment that contains the transaction is cemented on layer 1, anyone can run the transaction by running the Octez client execute outbox message command.

5. The helper contract receives the ticket from the originally deposited tokens and target address and stores the address.

6. The helper contract sends the ticket to the ticketer contract's withdraw entrypoint.

7. The ticketer contract burns the ticket and sends the tokens to the helper contract.

8. The helper contract sends the tokens to the target layer 1 address.

This diagram is an overview of the process of bridging tokens from Etherlink to layer 1: