# `TokenBridge`

Contract to manage cross-chain ERC-20 bridging.

### CONTRACT_VERSION

```solidity
string CONTRACT_VERSION
```

_This is the ABI version and not the reinitialize version._

### SET_MESSAGE_SERVICE_ROLE

```solidity
bytes32 SET_MESSAGE_SERVICE_ROLE
```

Role used for setting the message service address.

### SET_RESERVED_TOKEN_ROLE

```solidity
bytes32 SET_RESERVED_TOKEN_ROLE
```

Role used for setting a reserved token address.

### REMOVE_RESERVED_TOKEN_ROLE

```solidity
bytes32 REMOVE_RESERVED_TOKEN_ROLE
```

Role used for removing a reserved token address.

### SET_CUSTOM_CONTRACT_ROLE

```solidity
bytes32 SET_CUSTOM_CONTRACT_ROLE
```

Role used for setting a custom token contract address.

### EMPTY

```solidity
address EMPTY
```

EMPTY means a token is not present in the mapping.

### RESERVED_STATUS

```solidity
address RESERVED_STATUS
```

RESERVED means a token is reserved and cannot be bridged.

### NATIVE_STATUS

```solidity
address NATIVE_STATUS
```

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

### DEPLOYED_STATUS

```solidity
address DEPLOYED_STATUS
```

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

### _PERMIT_SELECTOR

```solidity
bytes4 _PERMIT_SELECTOR
```

_The permit selector to be used when decoding the permit._

### tokenBeacon

```solidity
address tokenBeacon
```

The token beacon for deployed tokens.

### nativeToBridgedToken

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

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

### bridgedToNativeToken

```solidity
mapping(address => address) bridgedToNativeToken
```

The bridged token address mapped to the native token address.

### sourceChainId

```solidity
uint256 sourceChainId
```

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

### targetChainId

```solidity
uint256 targetChainId
```

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

### isNewToken

```solidity
modifier isNewToken(address _token)
```

_Ensures the token has not been bridged before._

### nonZeroAddress

```solidity
modifier nonZeroAddress(address _addr)
```

_Ensures the address is not address(0)._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| _addr | address | Address to check. |

### nonZeroAmount

```solidity
modifier nonZeroAmount(uint256 _amount)
```

_Ensures the amount is not 0._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| _amount | uint256 | amount to check. |

### nonZeroChainId

```solidity
modifier nonZeroChainId(uint256 _chainId)
```

_Ensures the chainId is not 0._

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| _chainId | uint256 | chainId to check. |

### constructor

```solidity
constructor() public
```

_Disable constructor for safety_

### initialize

```solidity
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. |

### bridgeToken

```solidity
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 ERC-20. If the token is bridged for the first time an ERC-20
  (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 ERC-20s,
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

```solidity
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 ERC-20 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

```solidity
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 chainId |
| _tokenMetadata | bytes | Additional data used to deploy the bridged token if it   doesn't exist already. |

### setMessageService

```solidity
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

```solidity
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

```solidity
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. |

### deployBridgedToken

```solidity
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

```solidity
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

```solidity
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

```solidity
function setCustomContract(address _nativeToken, address _targetContract) external
```

_Linea can set a custom ERC-20 contract for specific ERC-20.
  For security purposes, 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

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

_Provides a safe ERC-20.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

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

_Provides a safe ERC-20.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

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

Provides a safe ERC-20.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

```solidity
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

```solidity
function _permit(address _token, bytes _permitData) internal
```

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

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| _token | address | ERC-20 token address |
| _permitData | bytes | Raw data of the call `permit` of the token |

