CustomToken

Git Source

Inherits: Initializable, AccessControlUpgradeable, PausableUpgradeable, ReentrancyGuardUpgradeable, ERC20PermitUpgradeable, Versioned

Author: See https://github.com/agglayer/vault-bridge

A Custom Token is an optional ERC-20 token on Layer Ys to represent the 'native' version of the original underlying token from Layer X on Layer Y, ideally (or, simply, the upgraded version of the bridged vbToken).

A base contract used to create Custom Tokens.

@note IMPORTANT: Custom Token MUST be used as the new implementation for the bridged vbToken or be custom mapped to the corresponding vbToken on LxLy Bridge on Layer Y, and MUST give the minting and burning permission to LxLy Bridge and Native Converter. It MAY have a transfer fee.

State Variables

_CUSTOM_TOKEN_STORAGE

The storage slot at which Custom Token storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.CustomToken.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _CUSTOM_TOKEN_STORAGE = hex"0300d81ec8b5c42d6bd2cedd81ce26f1003c52753656b7512a8eef168b702500";

PAUSER_ROLE

bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

Functions

onlyLxlyBridgeAndNativeConverter

Checks if the sender is LxLy Bridge or Native Converter.

This modifier is used to restrict the minting and burning of Custom Token.

modifier onlyLxlyBridgeAndNativeConverter();

__CustomToken_init

Preserves the name and symbol of the bridged vbToken.

function __CustomToken_init(
    address owner_,
    uint8 originalUnderlyingTokenDecimals_,
    address lxlyBridge_,
    address nativeConverter_
) internal onlyInitializing;

Parameters

Name	Type	Description
`owner_`	`address`
`originalUnderlyingTokenDecimals_`	`uint8`	The number of decimals of the original underlying token on Layer X. Custom Token will have the same number of decimals as the original underlying token.
`lxlyBridge_`	`address`
`nativeConverter_`	`address`	The address of Native Converter for this Custom Token.

decimals

The number of decimals of Custom Token.

The number of decimals is the same as that of the original underlying token on Layer X.

function decimals() public view override returns (uint8);

lxlyBridge

LxLy Bridge, which connects AggLayer networks.

function lxlyBridge() public view returns (address);

nativeConverter

The address of Native Converter for this Custom Token.

function nativeConverter() public view returns (address);

_getCustomTokenStorage

Returns a pointer to the ERC-7201 storage namespace.

function _getCustomTokenStorage() private pure returns (CustomTokenStorage storage $);

transfer

Pausable ERC-20 transfer function.

function transfer(address to, uint256 value) public override whenNotPaused returns (bool);

transferFrom

Pausable ERC-20 transferFrom function.

function transferFrom(address from, address to, uint256 value) public override whenNotPaused returns (bool);

approve

Pausable ERC-20 approve function.

function approve(address spender, uint256 value) public override whenNotPaused returns (bool);

permit

Pausable ERC-20 Permit permit function.

function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)
    public
    override
    whenNotPaused;

mint

Mints Custom Tokens to the recipient.

This function can be called by LxLy Bridge and Native Converter only.

function mint(address account, uint256 value) external whenNotPaused onlyLxlyBridgeAndNativeConverter nonReentrant;

Parameters

Name	Type	Description
`account`	`address`	@note CAUTION! Minting to `address(0)` will result in no tokens minted! This is to enable vbToken on Layer X to bridge tokens to address zero on Layer Y at the end of the process of migrating backing from Native Converter to Layer X. Please refer to `NativeConverter.sol` for more information.
`value`	`uint256`

burn

Burns Custom Tokens from a holder.

This function can be called by LxLy Bridge and Native Converter only.

function burn(address account, uint256 value) external whenNotPaused onlyLxlyBridgeAndNativeConverter nonReentrant;

pause

Prevents usage of functions with the whenNotPaused modifier.

This function can be called by a pauser only.

function pause() external onlyRole(PAUSER_ROLE) nonReentrant;

unpause

Allows usage of functions with the whenNotPaused modifier.

This function can be called by the owner only.

function unpause() external onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;

Events

NotMinted

event NotMinted(uint256 indexed value);

Errors

Unauthorized

error Unauthorized();

InvalidOwner

error InvalidOwner();

InvalidOriginalUnderlyingTokenDecimals

error InvalidOriginalUnderlyingTokenDecimals();

InvalidLxLyBridge

error InvalidLxLyBridge();

InvalidNativeConverter

error InvalidNativeConverter();

Structs

CustomTokenStorage

Storage of Custom Token contract.

It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions when using with upgradeable contracts.

Note: storage-location: erc7201:agglayer.vault-bridge.CustomToken.storage

struct CustomTokenStorage {
    uint8 decimals;
    address lxlyBridge;
    address nativeConverter;
}

Technical Reference