TokenBridge

Contract to manage cross-chain ERC20 bridging.

CONTRACT_VERSION

string CONTRACT_VERSION

This is the ABI version and not the reinitialize version.

SET_MESSAGE_SERVICE_ROLE

bytes32 SET_MESSAGE_SERVICE_ROLE

Role used for setting the message service address.

SET_REMOTE_TOKENBRIDGE_ROLE

bytes32 SET_REMOTE_TOKENBRIDGE_ROLE

Role used for setting the remote token bridge address.

SET_RESERVED_TOKEN_ROLE

bytes32 SET_RESERVED_TOKEN_ROLE

Role used for setting a reserved token address.

REMOVE_RESERVED_TOKEN_ROLE

bytes32 REMOVE_RESERVED_TOKEN_ROLE

Role used for removing a reserved token address.

SET_CUSTOM_CONTRACT_ROLE

bytes32 SET_CUSTOM_CONTRACT_ROLE

Role used for setting a custom token contract address.

EMPTY

address EMPTY

EMPTY means a token is not present in the mapping.

RESERVED_STATUS

address RESERVED_STATUS

RESERVED means a token is reserved and cannot be bridged.

NATIVE_STATUS

address NATIVE_STATUS

NATIVE means a token is native to the current local chain.

DEPLOYED_STATUS

address DEPLOYED_STATUS

DEPLOYED means the bridged token contract has been deployed on the remote chain.

_PERMIT_SELECTOR

bytes4 _PERMIT_SELECTOR

The permit selector to be used when decoding the permit.

tokenBeacon

address tokenBeacon

The token beacon for deployed tokens.

nativeToBridgedToken

mapping(uint256 => mapping(address => address)) nativeToBridgedToken

The chainId mapped to a native token address which is then mapped to the bridged token address.

bridgedToNativeToken

mapping(address => address) bridgedToNativeToken

The bridged token address mapped to the native token address.

sourceChainId

uint256 sourceChainId

The current layer's chainId from where the bridging is triggered.

targetChainId

uint256 targetChainId

The targeted layer's chainId where the bridging is received.

isNewToken

modifier isNewToken(address _token)

Ensures the token has not been bridged before.

nonZeroAddress

modifier nonZeroAddress(address _addr)

Ensures the address is not address(0).

Parameters

Name	Type	Description
_addr	address	Address to check.

nonZeroAmount

modifier nonZeroAmount(uint256 _amount)

Ensures the amount is not 0.

Parameters

Name	Type	Description
_amount	uint256	amount to check.

constructor

constructor() public

Disable constructor for safety

initialize

function initialize(struct ITokenBridge.InitializationData _initializationData) external

Initializes TokenBridge and underlying service dependencies - used for new networks only.

Contract will be used as proxy implementation.

Parameters

Name	Type	Description
_initializationData	struct ITokenBridge.InitializationData	The initial data used for initializing the TokenBridge contract.

reinitializePauseTypesAndPermissions

function reinitializePauseTypesAndPermissions(address _defaultAdmin, struct IPermissionsManager.RoleAddress[] _roleAddresses, struct IPauseManager.PauseTypeRole[] _pauseTypeRoles, struct IPauseManager.PauseTypeRole[] _unpauseTypeRoles) external

Sets permissions for a list of addresses and their roles as well as initialises the PauseManager pauseType:role mappings.

This function is a reinitializer and can only be called once per version. Should be called using an upgradeAndCall transaction to the ProxyAdmin.

Parameters

Name	Type	Description
_defaultAdmin	address	The default admin account's address.
_roleAddresses	struct IPermissionsManager.RoleAddress[]	The list of addresses and roles to assign permissions to.
_pauseTypeRoles	struct IPauseManager.PauseTypeRole[]	The list of pause types to associate with roles.
_unpauseTypeRoles	struct IPauseManager.PauseTypeRole[]	The list of unpause types to associate with roles.

bridgeToken

function bridgeToken(address _token, uint256 _amount, address _recipient) public payable

This function is the single entry point to bridge tokens to the other chain, both for native and already bridged tokens. You can use it to bridge any ERC20. If the token is bridged for the first time an ERC20 (BridgedToken.sol) will be automatically deployed on the target chain.

User should first allow the bridge to transfer tokens on his behalf. Alternatively, you can use BridgeTokenWithPermit to do so in a single transaction. If you want the transfer to be automatically executed on the destination chain. You should send enough ETH to pay the postman fees. Note that Linea can reserve some tokens (which use a dedicated bridge). In this case, the token cannot be bridged. Linea can only reserve tokens that have not been bridged yet. Linea can pause the bridge for security reason. In this case new bridge transaction would revert. Note: If, when bridging an unbridged token and decimals are unknown, the call will revert to prevent mismatched decimals. Only those ERC20s, with a decimals function are supported.

Parameters

Name	Type	Description
_token	address	The address of the token to be bridged.
_amount	uint256	The amount of the token to be bridged.
_recipient	address	The address that will receive the tokens on the other chain.

bridgeTokenWithPermit

function bridgeTokenWithPermit(address _token, uint256 _amount, address _recipient, bytes _permitData) external payable

Similar to bridgeToken function but allows to pass additional permit data to do the ERC20 approval in a single transaction. _permit can fail silently, don't rely on this function passing as a form of authentication

There is no need for validation at this level as the validation on pausing, and empty values exists on the "bridgeToken" call.

Parameters

Name	Type	Description
_token	address	The address of the token to be bridged.
_amount	uint256	The amount of the token to be bridged.
_recipient	address	The address that will receive the tokens on the other chain.
_permitData	bytes	The permit data for the token, if applicable.

completeBridging

function completeBridging(address _nativeToken, uint256 _amount, address _recipient, uint256 _chainId, bytes _tokenMetadata) external

It can only be called from the Message Service. To finalize the bridging process, a user or postman needs to use the claimMessage function of the Message Service to trigger the transaction.

Parameters

Name	Type	Description
_nativeToken	address	The address of the token on its native chain.
_amount	uint256	The amount of the token to be received.
_recipient	address	The address that will receive the tokens.
_chainId	uint256	The token's origin layer chaindId
_tokenMetadata	bytes	Additional data used to deploy the bridged token if it doesn't exist already.

setMessageService

function setMessageService(address _messageService) external

Change the address of the Message Service. SET_MESSAGE_SERVICE_ROLE is required to execute.

Parameters

Name	Type	Description
_messageService	address	The address of the new Message Service.

confirmDeployment

function confirmDeployment(address[] _tokens) external payable

Change the status to DEPLOYED to the tokens passed in parameter Will call the method setDeployed on the other chain using the message Service

Parameters

Name	Type	Description
_tokens	address[]	Array of bridged tokens that have been deployed.

setDeployed

function setDeployed(address[] _nativeTokens) external

Change the status of tokens to DEPLOYED. New bridge transaction will not contain token metadata, which save gas. Can only be called from the Message Service. A user or postman needs to use the claimMessage function of the Message Service to trigger the transaction.

Parameters

Name	Type	Description
_nativeTokens	address[]	Array of native tokens for which the DEPLOYED status must be set.

setRemoteTokenBridge

function setRemoteTokenBridge(address _remoteTokenBridge) external

Sets the address of the remote token bridge. Can only be called once. SET_REMOTE_TOKENBRIDGE_ROLE is required to execute.

Parameters

Name	Type	Description
_remoteTokenBridge	address	The address of the remote token bridge to be set.

deployBridgedToken

function deployBridgedToken(address _nativeToken, bytes _tokenMetadata, uint256 _chainId) internal returns (address bridgedTokenAddress)

Deploy a new EC20 contract for bridged token using a beacon proxy pattern. To adapt to future requirements, Linea can update the implementation of all (existing and future) contracts by updating the beacon. This update is subject to a delay by a time lock. Contracts are deployed using CREATE2 so deployment address is deterministic.

Parameters

Name	Type	Description
_nativeToken	address	The address of the native token on the source chain.
_tokenMetadata	bytes	The encoded metadata for the token.
_chainId	uint256	The chain id on which the token will be deployed, used to calculate the salt

Return Values

Name	Type	Description
bridgedTokenAddress	address	The address of the newly deployed BridgedToken contract.

setReserved

function setReserved(address _token) external

Make sure that _token is native to the current chain where you are calling this function from

Linea can reserve tokens. In this case, the token cannot be bridged. Linea can only reserve tokens that have not been bridged before. SET_RESERVED_TOKEN_ROLE is required to execute.

Parameters

Name	Type	Description
_token	address	The address of the token to be set as reserved.

removeReserved

function removeReserved(address _token) external

Removes a token from the reserved list. REMOVE_RESERVED_TOKEN_ROLE is required to execute.

Parameters

Name	Type	Description
_token	address	The address of the token to be removed from the reserved list.

setCustomContract

function setCustomContract(address _nativeToken, address _targetContract) external

Linea can set a custom ERC20 contract for specific ERC20. For security purpose, Linea can only call this function if the token has not been bridged yet. SET_CUSTOM_CONTRACT_ROLE is required to execute.

Parameters

Name	Type	Description
_nativeToken	address	The address of the token on the source chain.
_targetContract	address	The address of the custom contract.

_safeName

function _safeName(address _token) internal view returns (string tokenName)

Provides a safe ERC20.name version which returns 'NO_NAME' as fallback string.

Parameters

Name	Type	Description
_token	address	The address of the ERC-20 token contract

Return Values

Name	Type	Description
tokenName	string	Returns the string of the token name.

_safeSymbol

function _safeSymbol(address _token) internal view returns (string symbol)

Provides a safe ERC20.symbol version which returns 'NO_SYMBOL' as fallback string

Parameters

Name	Type	Description
_token	address	The address of the ERC-20 token contract

Return Values

Name	Type	Description
symbol	string	Returns the string of the symbol.

_safeDecimals

function _safeDecimals(address _token) internal view returns (uint8)

Provides a safe ERC20.decimals version which reverts when decimals are unknown Note Tokens with (decimals > 255) are not supported

Parameters

Name	Type	Description
_token	address	The address of the ERC-20 token contract

Return Values

Name	Type	Description
[0]	uint8	Returns the token's decimals value.

_returnDataToString

function _returnDataToString(bytes _data) internal pure returns (string decodedString)

Converts returned data to string. Returns 'NOT_VALID_ENCODING' as fallback value.

Parameters

Name	Type	Description
_data	bytes	returned data.

Return Values

Name	Type	Description
decodedString	string	The decoded string data.

_permit

function _permit(address _token, bytes _permitData) internal

Call the token permit method of extended ERC20 Only support tokens implementing ERC-2612

Parameters

Name	Type	Description
_token	address	ERC20 token address
_permitData	bytes	Raw data of the call permit of the token