> ## Documentation Index
> Fetch the complete documentation index at: https://docs.initia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# InitiaCustomERC20

GitHub:
[InitiaCustomERC20](https://github.com/initia-labs/initia-evm-contracts/blob/main/src/InitiaCustomERC20.sol)

## Overview

The `InitiaCustomERC20` contract is a custom implementation of the ERC20 token
standard. It includes additional access control mechanisms and registry
functionalities to allow for better integration with the rollup's underlying
Cosmos SDK stack.

This is the main ERC20 token contract that developers should use to create their
own custom ERC20 tokens on the MiniEVM.

## Inheritance

* `IERC20`: Interface for ERC20 standard functions.
* `Ownable`: Provides ownership control.
* `ERC20Registry`: Handles ERC20 registry functionalities.
* `ERC165`: Supports interface identification.
* `ERC20ACL`: Provides access control mechanisms.

## State Variables

* `mapping(address => uint256) public balanceOf`: Tracks the balance of each
  address.
* `mapping(address => mapping(address => uint256)) public allowance`: Tracks the
  allowance each address has given to another address.
* `string public name`: The name of the token.
* `string public symbol`: The symbol of the token.
* `uint8 public decimals`: The number of decimals the token uses.
* `uint256 public totalSupply`: The total supply of the token.

## Constructor

Initializes the contract with the token's name, symbol, and decimals. It also
registers the ERC20 token with the ERC20Registry.

```solidity theme={null}
constructor(string memory _name, string memory _symbol, uint8 _decimals) register_erc20 {
    name = _name;
    symbol = _symbol;
    decimals = _decimals;
}
```

#### Parameters

| Name        | Type            | Description                            |
| ----------- | --------------- | -------------------------------------- |
| `_name`     | `string memory` | The name of the token.                 |
| `_symbol`   | `string memory` | The symbol of the token.               |
| `_decimals` | `uint8`         | The number of decimals the token uses. |

## Functions

### `supportsInterface`

Checks if the contract supports a given interface.

```solidity theme={null}
function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165) returns (bool)
```

#### Parameters

| Name          | Type     | Description               |
| ------------- | -------- | ------------------------- |
| `interfaceId` | `bytes4` | The interface identifier. |

#### Returns

| Type   | Description                                              |
| ------ | -------------------------------------------------------- |
| `bool` | `true` if the interface is supported, `false` otherwise. |

### `_transfer`

Transfers tokens from one address to another and registers the recipient's ERC20
store if necessary.

```solidity theme={null}
function _transfer(address sender, address recipient, uint256 amount) internal register_erc20_store(recipient)
```

#### Parameters

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `sender`    | `address` | The address sending the tokens.   |
| `recipient` | `address` | The address receiving the tokens. |
| `amount`    | `uint256` | The amount of tokens to transfer. |

### `_mint`

Mints new tokens and assigns them to an address, registering the recipient's
ERC20 store if necessary.

```solidity theme={null}
function _mint(address to, uint256 amount) internal register_erc20_store(to)
```

#### Parameters

| Name     | Type      | Description                       |
| -------- | --------- | --------------------------------- |
| `to`     | `address` | The address receiving the tokens. |
| `amount` | `uint256` | The amount of tokens to mint.     |

### `_burn`

Burns tokens from an address.

```solidity theme={null}
function _burn(address from, uint256 amount) internal
```

#### Parameters

| Name     | Type      | Description                              |
| -------- | --------- | ---------------------------------------- |
| `from`   | `address` | The address whose tokens will be burned. |
| `amount` | `uint256` | The amount of tokens to burn.            |

### `transfer`

Transfers tokens to a recipient, ensuring the recipient is not a blocked
address.

```solidity theme={null}
function transfer(address recipient, uint256 amount) external transferable(recipient) returns (bool)
```

#### Parameters

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `recipient` | `address` | The address receiving the tokens. |
| `amount`    | `uint256` | The amount of tokens to transfer. |

#### Returns

| Type   | Description                            |
| ------ | -------------------------------------- |
| `bool` | `true` if the transfer was successful. |

### `approve`

Approves an address to spend a specified amount of tokens on behalf of the
caller.

```solidity theme={null}
function approve(address spender, uint256 amount) external returns (bool)
```

#### Parameters

| Name      | Type      | Description                              |
| --------- | --------- | ---------------------------------------- |
| `spender` | `address` | The address allowed to spend the tokens. |
| `amount`  | `uint256` | The amount of tokens to approve.         |

#### Returns

| Type   | Description                            |
| ------ | -------------------------------------- |
| `bool` | `true` if the approval was successful. |

### `transferFrom`

Transfers tokens from one address to another on behalf of the sender, ensuring
the recipient is not a blocked address.

```solidity theme={null}
function transferFrom(address sender, address recipient, uint256 amount) external transferable(recipient) returns (bool)
```

#### Parameters

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `sender`    | `address` | The address sending the tokens.   |
| `recipient` | `address` | The address receiving the tokens. |
| `amount`    | `uint256` | The amount of tokens to transfer. |

#### Returns

| Type   | Description                            |
| ------ | -------------------------------------- |
| `bool` | `true` if the transfer was successful. |

### `mint`

Mints new tokens to a specified address, ensuring the recipient is not a blocked
address. This function can only be called by the owner.

```solidity theme={null}
function mint(address to, uint256 amount) external mintable(to) onlyOwner
```

#### Parameters

| Name     | Type      | Description                       |
| -------- | --------- | --------------------------------- |
| `to`     | `address` | The address receiving the tokens. |
| `amount` | `uint256` | The amount of tokens to mint.     |

### `burn`

Burns tokens from a specified address, ensuring the sender is not a module
address. This function can only be called by the owner.

```solidity theme={null}
function burn(address from, uint256 amount) external burnable(from) onlyOwner
```

#### Parameters

| Name     | Type      | Description                          |
| -------- | --------- | ------------------------------------ |
| `from`   | `address` | The address whose tokens are burned. |
| `amount` | `uint256` | The amount of tokens to burn.        |

### `sudoTransfer`

Transfers tokens from one address to another, bypassing the usual access control
checks. This function can only be called by the chain signer.

```solidity theme={null}
function sudoTransfer(address sender, address recipient, uint256 amount) external onlyChain
```

#### Parameters

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `sender`    | `address` | The address sending the tokens.   |
| `recipient` | `address` | The address receiving the tokens. |
| `amount`    | `uint256` | The amount of tokens to transfer. |