Thanos development story — 2

L2 Native token feature

Published in

Tokamak Network

5 min readAug 22, 2024

The L2 Native token feature allows depositing an L1 ERC20 token and using it as a native token on Layer 2. The L2 Native Token feature have been developing based on Optimism Ecotone’s core smart contracts.

Let’s first go to the idea behind updating smart contract for L2 Native token and then explain about important modifications of core smart contracts such as OptimismPortal, L1CrossDomainMessenger, L1StandardBridge.

Thanos Development Story Series

Concept for supporting the L2 native token feature

First, let’s talk about how to make a deposit transaction to L2. In Thanos, there is a component that written in Go that called op-node. op-node will listen the TransactionDeposited event that is raised within the OptimismPortal smart contract, parses data from this event and make an L2 deposit transaction.

event TransactionDeposited(address indexed from, address indexed to, uint256 indexed version, bytes opaqueData);

This event provides information such as from, to, version and opaque data. And here is how opaque data is packed

bytes memory opaqueData = abi.encodePacked(_mint, _value, _gasLimit, _isCreation, _data);

Let’s explain all the fields:

from: The address of the sender for the L2 deposit transaction.
to: The target address for the L2 deposit transaction.
version: This indicates which version of the deposit function is being used.
_mint: This specifies how many tokens are minted on L2 and assigned to the sender.
_value: This is the amount of the native token on L2 that sent along with the transaction to the target address.
_gasLimit: The minimum gas limit to ensure that the call to the “to” address does not run out of gas. This ensures that there is enough gas to complete the L2 transaction.
_isCreation: If true, it signifies that the transaction is for creating a new smart contract.
_data: This is the data payload sent with the transaction, usually containing the function signature and parameters needed to execute a function on the target contract.

So, it leads to some idea below to update the smart contracts for supporting the L2 native token feature:

Update the way to deal with ERC20 instead of ETH in the OptimismPortal.depositTransaction() function, for example using the transferFrom() function instead of msg.value.
According what changes in OptimismPortal, the high-level smart contracts such as L1CrossDomainMessenger or L1StandardBridge need to be update as well.

Properties of L2 native token

For a token to be used as an L2 native token, it MUST satisfy the ERC20 standard and the following additional requirements:

Token decimals MUST be 18. The native token on L2 has 18 decimals, so it is essential to ensure no loss of precision when depositing or withdrawing a token with a different number of decimals.
Have no transfer fee.
Must not have rebasing logic.
Must not have out of band methods for updating balance or allowance

OptimismPortal

Base on the idea above, the depositTransaction() interface need to be changed:

The global variable msg.value is not used any more in Thanos, so there is other parameter that called _mint appear as the function’s input. For dealing with ERC20, the OptimismPortal contract uses transferFrom() logic to collect token when the depositTransaction() function is called, so that senders must first approve() the address of OptimismPortal.

In the finalizeWithdrawalTransaction(), Thanos uses approve() logic and receivers have to use transferFrom() to withdraw their token.

L1CrossDomainMessenger

L1CrossDomainMessenger introduces a new function that called sendNativeTokenMessage(). The logic of this function is similar to the sendMessage() function, except the sendNativeTokenMessage() is used to handle L2 native token as an ERC20 token. Let’s see the function interface:

Fig. interface of sendNativeTokenMessage()

Senders MUST first approve() the address of L1CrossDomainMessenger so that L1CrossDomainMessenger.sendNativeTokenMessage() can use transferFrom() to collect L2’s native token.

And L1CrossDomainMessenger MUST approve() address of the OptimismPortal, so that the OptimismPortal can use transferFrom to collect L1CrossDomainMessenger ’s token when depositTransaction() is called.

L1StandardBridge and L2StandardBridge

Those contracts are intended for use by end-users to deposit and withdraw conveniently.

There are 2 new functions that added to L2StandardBridge to withdraw native token:

withdrawNativeToken()
withdrawNativeTokenTo()

Those StandardBridges support three deposit and three withdrawal scenarios.

Deposit L2 native token
Deposit ETH
Deposit ERC20 (not L2 native token)
Withdraw L2 native token
Withdraw ETH
Withdraw ERC20 (not L2 native token)

Deposit flows

Deposit L2 native token

The native token of L2 must be locked in OptimismPortal. And the flow of deposit L2 native token is almost the same as Optimism Ecotone’s depositETH() except using some other function interfaces (but provides the same logic) and an ERC20 is used instead of ETH
Transferring token by using the function transferFrom() in the destination contracts/EOAs

Deposit ETH

ETH is locked in the L1StandardBridge
On the Thanos Ecotone, users receive ERC20 token that represents ETH

Deposit ERC20 (not L2 native token)

The flow is the same as Optimism Ecotone ’s depositERC20, except it does not allow using L2 Native Token

Withdrawal flows

Withdraw L2 native token

It is almost the same as withdraw ETH in case Optimism. The main different thing is on Thanos Ecotone, users will receive L2 Native Token instead of ETH.

Withdraw ETH

L2’s ETH is an ERC20 instead of native ETH as in Optimism Ecotone
Users will receive ETH from L1StandardBridge instead of OptimismPortal as in Optimism Ecotone. (On Thanos Ecotone, ETH is also locked at L1StandardBridge when depositing)

Withdraw ERC20 (not L2 native token)

It is almost the same as withdraw ETH in case Optimism. The main different thing is on Thanos Ecotone, users will receive L2 Native Token instead of ETH.