ERC20
An ERC20 token contract keeps track of fungible tokens: any one token is exactly equal to any other token; no tokens have special rights or behavior associated with them. This makes ERC20 tokens useful for things like a medium of exchange currency, voting rights, staking, and more.
Constructor
new ERC20(config: IContractConfig);
| Param | Type | Description |
|---|---|---|
| config | IContractConfig |
Properties
address
Returns
Type: Address
decimals
The number of decimals used to get its user representation. For example, if decimals equals 2, a balance of 505 tokens should be displayed to a user as 5.05 (505 / 10 ** 2).
Requires erc20.fetch() to be called.
Due to the size of the numbers, you have to use BigInts to avoid number overflow. For example, instead of using 10 as value, use 10n.
Tokens usually opt for a value of 18, imitating the relationship between Ether and Wei. This is the default value for ERC20, unless it has been overridden.
Examples
const balance = await erc20.balanceOf(account);
// balance should be displayed to user as following:
const userBalance = balance / (10n ** erc20.decimals); // be careful to use BigInts
// or you could use built-in function
const userBalance = erc20.toHumanUnits(balance); // be sure to pass lower unitsReturns
Type: number
name
The name of the token.
Requires erc20.fetch() to be called.
Returns
Type: string
symbol
The symbol of the token, usually a shorter version of the name. (BTC, ETH...).
Requires erc20.fetch() to be called.
Returns
Type: string
Methods
allowance(owner, spender)
Get the remaining number of tokens that spender will be allowed to spend on behalf of owner through transferFrom. This is zero by default.
This value changes when approve or transferFrom are called.
Parameters
Name Type Description owner string The address who allow to spend tokens on behalf of spenderspender string The address allowed to spend tokens on behalf of ownerExamples
const owner = "0x0000000...";
const spender = "0x11111...";
// check allowance of spender on owner's balance;
const allowance = await erc20.allowance(owner, spender);
// value is returned in lower unit of tokens (see ERC20.decimals);
console.log(allowance) // 100000000nReturns Allowance of
spenderoverownerin lower unitsType: Promise<number>
approve(args)
Sets a value amount of tokens as the allowance of spender over the caller's tokens.
This function update the state of the blockchain so it will cost gas to be executed.
Beware that changing an allowance with this method brings the risk that someone may use both the old and the new allowance by unfortunate transaction ordering. One possible solution is to first reduce the spender's allowance to 0 and set the desired value afterwards.
Parameters
Name Type Description args IERC20ApproveParams The parameters to be passed into approvefunction of the ERC20 contract.Examples
const me = "0x000...";
const allowedSpender = "0x111...";
// allow to "spender" to spend 10 tokens
const transaction = await erc20.approve({
spender: allowedSpender,
value: erc20.toLowerUnits(10n) // use lower units (see ERC20.decimals)
}).execute();
// wait for 3 confirmations
const receipt = await transaction.waitForResult(3);Returns a ContractOperation instance.
Type: ContractOperation
balanceOf(account)
Check the amount of tokens that an account has in its balance.
Parameters
Name Type Description account string The account to check for. Examples
const account = "0x000...";
// balance are in lower units (see ERC20.decimals)
const accountBalance = await erc20.balanceOf(account);Returns The value of tokens owned by
account.Type: Promise<bigint>
fetch()
Fetch the token's name, symbol and decimals.
Returns
Type: Promise<void>
toHumanUnits(value)
Convert a token's lower units into human readable units.
Parameters
Name Type Description value bigint The value to convert into human readable units. Examples
// You want to convert 45300000000000000000n USDT into human units.
// assume that `erc20` is an instance of the USDT token
// and that the token has 18 decimals.
const lowerUnits = erc20.toHumanUnits(45300000000000000000n) // returns 45.3Returns The converted value in human readable units.
Type: number
toLowerUnits(value)
Convert a token's units into it's lower units.
Parameters
Name Type Description value number bigint Examples
// You want to convert 45.3 USDT into lower units.
// assume that `erc20` is an instance of the USDT token
// and that the token has 18 decimals.
const lowerUnits = erc20.toLowerUnits(45.3) // returns 45300000000000000000nReturns The converted value in lower units.
Type: bigint
totalSupply()
Return the total supply of tokens, which is the amount of tokens that exist in total.
Examples
// supply is displayed in lower units (see ERC20.decimals)
const supply = await token.totalSupply()Returns The value of tokens in existence.
Type: Promise<bigint>
transfer(args)
Moves a value amount of tokens from the caller's account to to.
This function update the state of the blockchain so it will cost gas to be executed.
Parameters
Name Type Description args IERC20TransferFromParams The parameters to be passed into transferfunction of the ERC20 contract.Examples
const receiver = "0x000...";
const me = "0x111..."
// send 5 tokens to the receiver
const transaction = await token.transfer({
from: me,
to: receiver,
value: token.toLowerUnits(5)
}).execute();
// wait for 3 confirmations
const receipt = await transaction.waitForResult(3);Returns a ContractOperation instance.
Type: ContractOperation
transferFrom(args)
Moves a value amount of tokens from from to to using the allowance mechanism. value is then deducted from the caller's allowance.
This function update the state of the blockchain so it will cost gas to be executed.
Parameters
Name Type Description args IERC20TransferFromParams The parameters to be passed into transferFromfunction of the ERC20 contract.Examples
const receiver = "0x000...";
const sender = "0x111...";
// caller needs to have at least 5 tokens in allowance over "sender" account
const transaction = await erc20.transferFrom({
from: sender,
to: receiver,
value: erc20.toLowerUnits(5)
}).execute();
// wait for 3 confirmations
const receipt = await result.waitForResult(3);Returns a ContractOperation instance.
Type: ContractOperation
Events
Approval
Emits
Type: Log & { args: IERC20ApprovalEventParams }
Transfer
Emits
Type: Log & { args: IERC20TransferEventParams }