Token template

• Stablecoins: ERC-20 tokens serve as the foundation for stablecoins like USDC, backed by US dollars. To learn more about the USDC contract, see 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Etherscan.
• Loyalty points: ERC-20 tokens can represent on-chain loyalty points to incentivize and reward users for their activities within a platform or ecosystem.
• Governance: ERC-20 tokens can represent governance rights, allowing holders to participate in protocol decisions. Notable examples include tokens utilized by platforms like Uniswap.
• Ownership: ERC-20 tokens can also represent fractional ownership in real-world assets, such as houses, ounces of gold, or company shares.

​

Deployment parameters

​

Template deployment parameters

"templateParameters": {
  "name": "My Token Contract",
  "defaultAdmin": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6",
  "primarySaleRecipient": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6"
}

​

Common functions

• approve [write]
• transfer [write]
• mintTo [write]
• burn [write]
• grantRole [write]
• revokeRole [write]
• balanceOf [read]
• allowance [read]

​

approve [write]

​

Parameters

​

Failure scenarios

• The approve function fails if the spender is the zero address.
  ”ERC20: approve to the zero address”

​

Notes

• If amount is the maximum uint256 value the allowance is not updated when the transferFrom function is called. This is semantically equivalent to an infinite approval.
• There is no balance check on the approve function so token owners may approve allowances greater than their current balance.

function approve(address spender, uint256 amount) public virtual override returns (bool) {
  address owner = _msgSender();
  _approve(owner, spender, amount);
  return true;
}

​

transfer [write]

​

Parameters

​

Failure scenarios

• The to address parameter is checked to ensure it is not the zero address address(0).
  ”ERC20: transfer to the zero address”
• The beforeTokenTransfer hook is called, which checks TOKEN_TRANSFER permissions.
  ”restricted to TRANSFER_ROLE holders”
• The token owner doesn’t have a sufficient balance to transfer the specified token amount.
  ”ERC20: transfer amount exceeds balance”

function transfer(address to, uint256 amount) public virtual override returns (bool) {
  address owner = _msgSender();
  _transfer(owner, to, amount);
  return true;
}

​

mintTo [write]

​

Parameters

​

Failure scenarios

• The function checks if the caller has the MINTER_ROLE. The function will fail if the caller does not have the minter role. Expect to see the following error:
  “not minter.”
• The function ensures that the account address is not the zero address address(0), as this is an invalid address to mint tokens to.
  ”ERC20: mint to the zero address”
• The beforeTokenTransfer hook is called, which checks TOKEN_TRANSFER permissions.
  ”restricted to TRANSFERROLE _holders”

function mintTo(address to, uint256 amount) public virtual {
  require(hasRole(MINTER_ROLE, _msgSender()), "not minter.");
  _mintTo(to, amount);
}

​

burn [write]

​

Parameters

​

Failure scenarios

• The _beforeTokenTransfer  hook is called, which checks TOKEN_TRANSFER permissions.
  ”restricted to TRANSFER_ROLE holders”
• The token owner has no sufficient balance to burn the specified token amount.
  ”ERC20: burn amount exceeds balance”

function burn(uint256 amount) public virtual {
  _burn(_msgSender(), amount);
}

​

Permissions and roles

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

function foo() public {
  require(hasRole(MY_ROLE, msg.sender));
  ...
}

​

grantRole [write]

​

Parameters

​

Failure scenarios

• The onlyRole(getRoleAdmin(role)) modifier ensures that the function caller has the admin role for the specified role. Only addresses with the admin role can grant roles to other accounts.
  ”AccessControl: account ”, StringsUpgradeable.toHexString(account), ” is missing role ”, StringsUpgradeable.toHexString(uint256(role), 32)
• The function checks if the account already has the specified role using the hasRole function. If the account does not have the role, the function continues. There is no error message.

function grantRole(bytes32 role, address account) public virtual override onlyRole(getRoleAdmin(role)) {
  _grantRole(role, account);
}

​

revokeRole [write]

​

Parameters

​

Failure scenarios

• The onlyRole(getRoleAdmin(role)) modifier ensures that the function caller has the admin role for the specified role. Only addresses with the admin role can revoke roles from other accounts.
  ”AccessControl: account ”, StringsUpgradeable.toHexString(account), ” is missing role ”, StringsUpgradeable.toHexString(uint256(role), 32)

function revokeRole(bytes32 role, address account) public virtual override onlyRole(getRoleAdmin(role)) {
  _revokeRole(role, account);
}

​

balanceOf [read]

​

Parameters

function balanceOf(address account) public view virtual override returns (uint256) {
  return _balances[account];
}

​

allowance [read]

​

Parameters

function allowance(address owner, address spender) public view virtual override returns (uint256) {
  return _allowances[owner][spender];
}