Token integration checklist The following checklist provides recommendations for interactions with arbitrary tokens. Every unchecked item should be justified, and its associated risks, understood.
Last updated April 2023, commit 565d767... Check the Github repo for the most up-to-date version of this particular checklist.
For convenience, all Slither utilities can be run directly on a token address, such as the following:
Copy slither-check-erc 0xdac17f958d2ee523a2206206994597c13d831ec7 TetherToken --erc erc20
slither-check-erc 0x06012c8cf97BEaD5deAe237070F9587f8E7A266d KittyCore --erc erc721
To follow this checklist, use the below output from Slither for the token:
Copy - slither-check-erc [target] [contractName] [optional: --erc ERC_NUMBER]
- slither [target] --print human-summary
- slither [target] --print contract-summary
- slither-prop . --contract ContractName # requires configuration, and use of Echidna and Manticore
General considerations
The contract has a security review. Avoid interacting with contracts that lack a security review. Check the length of the assessment (i.e., the level of effort), the reputation of the security firm, and the number and severity of the findings.
You have contacted the developers. You may need to alert their team to an incident. Look for appropriate contacts on blockchain-security-contacts .
They have a security mailing list for critical announcements. Their team should advise users (like you!) when critical issues are found or when upgrades occur.
Contract composition
The contract avoids unneeded complexity. The token should be a simple contract; a token with complex code requires a higher standard of review. Use Slither’s human-summary
printer to identify complex code.
The contract uses SafeMath
. Contracts that do not use SafeMath
require a higher standard of review. Inspect the contract by hand for SafeMath
usage.
The contract has only a few non–token-related functions. Non-token-related functions increase the likelihood of an issue in the contract. Use Slither’s contract-summary
printer to broadly review the code used in the contract.
The token only has one address. Tokens with multiple entry points for balance updates can break internal bookkeeping based on the address (e.g., balances[token_address][msg.sender]
may not reflect the actual balance).
Owner privileges
The token is not upgradeable. Upgradeable contracts may change their rules over time. Use Slither’s human-summary
printer to determine whether the contract is upgradeable.
The owner has limited minting capabilities. Malicious or compromised owners can abuse minting capabilities. Use Slither’s human-summary
printer to review minting capabilities, and consider manually reviewing the code.
The token is not pausable. Malicious or compromised owners can trap contracts relying on pausable tokens. Identify pausable code by hand.
The owner cannot blacklist the contract. Malicious or compromised owners can trap contracts relying on tokens with a blacklist. Identify blacklisting features by hand.
The team behind the token is known and can be held responsible for abuse. Contracts with anonymous development teams or teams that reside in legal shelters require a higher standard of review.
ERC20 tokens
ERC20 conformity checks
Slither includes a utility, slither-check-erc
, that reviews the conformance of a token to many related ERC standards. Use slither-check-erc
to review the following:
Transfer
and transferFrom
return a boolean. Several tokens do not return a boolean on these functions. As a result, their calls in the contract might fail.
The name
, decimals
, and symbol
functions are present if used. These functions are optional in the ERC20 standard and may not be present.
Decimals
returns a uint8
. Several tokens incorrectly return a uint256
. In such cases, ensure that the value returned is below 255.
The token mitigates the known ERC20 race condition . The ERC20 standard has a known ERC20 race condition that must be mitigated to prevent attackers from stealing tokens.
Slither includes a utility, slither-prop
, that generates unit tests and security properties that can discover many common ERC flaws. Use slither-prop to review the following:
The contract passes all unit tests and security properties from slither-prop
. Run the generated unit tests and then check the properties with Echidna and Manticore .
Risks of ERC20 Extensions
The behavior of certain contracts may differ from the original ERC specification. Conduct a manual review of the following conditions:
The token is not an ERC777 token and has no external function call in transfer
or transferFrom
. External calls in the transfer functions can lead to reentrancies.
Transfer
and transferFrom
should not take a fee. Deflationary tokens can lead to unexpected behavior.
Potential interest earned from the token is taken into account. Some tokens distribute interest to token holders. This interest may be trapped in the contract if not taken into account.
Token scarcity
Reviews of token scarcity issues must be executed manually. Check for the following conditions:
The supply is owned by more than a few users. If a few users own most of the tokens, they can influence operations based on the tokens’ repartition.
The total supply is sufficient. Tokens with a low total supply can be easily manipulated.
The tokens are located in more than a few exchanges. If all the tokens are in one exchange, a compromise of the exchange could compromise the contract relying on the token.
Users understand the risks associated with a large amount of funds or flash loans. Contracts relying on the token balance must account for attackers with a large amount of funds or attacks executed through flash loans.
The token does not allow flash minting. Flash minting can lead to substantial swings in the balance and the total supply, which necessitate strict and comprehensive overflow checks in the operation of the token.
ERC721 tokens
ERC721 Conformity Checks
The behavior of certain contracts may differ from the original ERC specification. Conduct a manual review of the following conditions:
Transfers of tokens to the 0x0 address revert. Several tokens allow transfers to 0x0 and consider tokens transferred to that address to have been burned; however, the ERC721 standard requires that such transfers revert.
safeTransferFrom
functions are implemented with the correct signature. Several token contracts do not implement these functions. A transfer of NFTs to one of those contracts can result in a loss of assets.
The name
, decimals
, and symbol
functions are present if used. These functions are optional in the ERC721 standard and may not be present.
If it is used, decimals
returns a uint8(0)
. Other values are invalid.
The name
and symbol
functions can return an empty string. This behavior is allowed by the standard.
The ownerOf
function reverts if the tokenId
is invalid or is set to a token that has already been burned. The function cannot return 0x0. This behavior is required by the standard, but it is not always properly implemented.
A transfer of an NFT clears its approvals. This is required by the standard.
The token ID of an NFT cannot be changed during its lifetime. This is required by the standard.
Common Risks of the ERC721 Standard
To mitigate the risks associated with ERC721 contracts, conduct a manual review of the following conditions:
The onERC721Received
callback is taken into account. External calls in the transfer functions can lead to reentrancies, especially when the callback is not explicit (e.g., in safeMint
calls).
When an NFT is minted, it is safely transferred to a smart contract. If there is a minting function, it should behave similarly to safeTransferFrom and properly handle the minting of new tokens to a smart contract. This will prevent a loss of assets.
The burning of a token clears its approvals. If there is a burning function, it should clear the token’s previous approvals.