This workshop was recorded on the 15th July 2021 and led by Martin Abbatemarco, Security Researcher at OpenZeppelin. It is the inaugural workshop of a series that covers multiple topics around secure development of smart contracts.
You can watch the video, view the slides, and learn about numerous edge cases that you should be aware of when integrating tokens into a project. Beyond learning specific cases with code examples and real threats in Ethereum’s mainnet, throughout the workshop you will learn more about our approach and mindset for code reviews, which you can translate to your own projects.
The interoperable nature of Ethereum means applications heavily rely on one another. Composability refers to the communication between DEXs, lending pools, aggregators, oracles, and other building blocks, continuously introducing novel and valuable dynamics. In practice, composability often translates to actual code integrations like, calling other people’s contracts from your own. Yet the more DeFi layers we integrate and compose, the more careful we need to be. As the stack grows, so does systemic risk. Thus it becomes fundamental to understand how the dynamics, behaviors, peculiarities and subtleties of other systems can affect our own operations.
One key aspect of composability is token integration. Even the most popular tokens can have deceiving behaviors, often overlooked until it is too late. This workshop aims at raising developer awareness on this front, highlighting numerous considerations to bear in mind when interacting with tokens in mainnet. It should be noted that this workshop is not exhaustive and there may be numerous behaviors not considered here.
As an ice breaker, let’s cover this simple example of a Solidity contract that allows for the depositing of a token. Read it line by line. How many issues, problems, code smells and questions can you come up with after a thorough pass?
After an initial scan, these might be some of the initial questions and triggers:
Regardless of specific issues or security vulnerabilities spotted, the point of this exercise is the importance of asking questions, and being suspicious about every single line of code you review. Besides this healthy skepticism, the focus of an auditor inspecting the piece of code shown will probably be around the kinds of tokens the contract accepts. This notion leads us to the core of the security session: real examples of unexpected behaviors in well-known tokens.
In the workshop we covered more than 20 different behaviors across a wide variety of tokens (USDT, USDC, TUSD, DAI, LINK, WBTC, cTokens, aTokens, OpenZeppelin’s ERC20 implementation, and others). For each behavior we showed code snippets, problems and solutions that developers can use as safeguards against unexpected behaviors. We discussed real issues introduced by the nature of some of these tokens, along with prevention use case measures applied by some of the biggest players in the DeFi ecosystem. Specifically, we covered the following scenarios.
Privileged accounts can control families of tokens. One of the many arbitrary powers these accounts may have is blocking addresses. The USDC and USDT properties are common examples of this behavior. In practice, this means that, upon being blocked, an account will not be allowed to transfer tokens.
As seen in the snippets below for USDC, the token contract inherits from a Blacklistable contract. Therefore it can use the notBlacklisted modifier placed on the transfer function to ensure that both the sender and receiver are allowed to handle USDC tokens.
It’s possible to know whether an account is blocked by querying the token contract itself, using its isBlacklisted function, as seen below.
On a similar note, some tokens that can be paused. USDC, USDT and BNT are examples of this among many others. Although the specifics depend on each implementation, the general idea is that once a token is paused, transfers and approvals are stopped. Normal operation can be resumed by unpausing the token.
Below we include some related code snippets for USDT, where we can see:
whenNotPaused modifierMultiple token standards such as ERC777, ERC721 and ERC1363 implement hooks on either the sender account, the receiver, or both. For example, during a transfer, a common ERC777-compliant token might first call the sender account, then modify token balances, and finally call the receiver account. While such behavior can be useful and valuable for some applications, it might become problematic for others. Examples of the latter can be observed in security incidents and known weaknesses in early versions of popular protocols.
Tokens can even differ in how they handle one of their most fundamental operations – transfers. Depending on which token you’re looking at, you can see instances of transfers not allowed to the token contract itself, the zero address, or the caller’s address. Some tokens even refuse transfers of value zero. As a simple example below, we show a code snippet of BNB, a token that does not allow transfers to the zero address nor transfers of zero value.
A family of tokens may not transfer the entire amount of tokens specified by the caller. As an example, if you transferred 100 tokens, the receiver could only receive 90. Should contracts integrating with this kind of token not consider such behavior, their internal accounting may be corrupted. The following snippet is an example of that scenario, where if a token that takes fees on transfers is used, the value stored in the deposits and accumulated in totalDeposits may differ from the actual amount transferred to the contract.
Examples of tokens that have the potential to take fees on transfers are USDT, or deflationary tokens such as STA (involved in a security incident in Balancer pools).
To prevent internal accounting inconsistencies in these scenarios, projects take different approaches. The snippet below shows how the CErc20 contract of the Compound protocol achieves this in roughly 4 steps:
There are multiple ways of handling success or failure during transfer and approvals. While some tokens revert upon failure, others consistently return boolean flags or have mixed behaviors. Below we include snippets of the transfer functions of ZRX and USDT. In the case of ZRX, the transfer function only returns a boolean flag.
In the case of USDT, we can already see from its declaration that the transfer function does not return any value.
To handle most of these inconsistent behaviors across multiple tokens, you can use the SafeERC20 library available in OpenZeppelin Contracts.
Do not assume that an account cannot have a significant amount of tokens in balance. Flash loans and flash mints are here to stay, and they can allow anybody to own a huge amount of tokens, even if just for a single transaction. You should be aware of these dynamics and test for extreme values in your contracts’ functions when necessary. For more details, you can check out OpenZeppelin Contract’s ERC20FlashMint contract.
There is a family of tokens known for being able to change token balances outside transfer operations. Some examples of this are UBI, AMPL, or aTokens from AAVE. Regardless of the reasons for this particular behavior, in practice, this means that the amount returned by the tokens’ balanceOf function can change across multiple calls, even if the account never sent nor received tokens. You can usually notice this behavior by inspecting the corresponding balanceOf functions, where you’ll find non-standard logic. In the case of UBI, we see the following:
In the case of aTokens:
If you are integrating with similar tokens, and keeping an internal accounting of token balances in your own contracts – make sure that you include specific logic to maintain the accounting up-to-date.
Some tokens allow users to approve an infinite amount of tokens to others. In practice, this means that whenever a transferFrom operation occurs, the amount of tokens approved is not decreased. Although not consistently implemented, this behavior has become far more common in recent years since it favors the token’s UX. You can find it implemented in many popular tokens such as DAI, as seen in the snippet below.
If you have ever read the ERC20 standard, you may have noticed that the functions decimals, name, and symbol are not mandatory for a token to comply with the interface. In practice, these functions are usually just assumed to be implemented. Most if not all well-known tokens include them. Still, out of an abundance of caution to handle unexpected failures, some projects that may integrate with arbitrary tokens were seen to use the try/catch structure to query these functions.
While tokens with 18 decimals are the norm, do not blindly assume that all this applies to all tokens. USDC has 6 decimals, cTokens from Compound and WBTC have 8. Your internal calculations may be inaccurate if you are handling tokens with different numbers of decimals without considering these cases.
The specifics on how to handle tokens with different numbers of decimals may vary depending on each implementation. Yet, if you dive deep into the codebases of most well-known DeFi projects, you are likely going to find examples on how to do it correctly.
The “allowance front-running attack” in ERC20 tokens is already a well-known weakness of the standard. Some tokens, such as OpenZeppelin Contract’s ERC20 implementation, expose additional functionality in their interface that can help mitigate associated risks. Others take a different approach. In the case of USDT, it does not allow approving tokens when the approval amount is already positive. While this behavior is not fundamentally flawed, it does introduce a deviation that can cause interoperability problems if not considered.
Off-chain services may rely on logged events to track token operations. However, not all tokens emit the same events. For example, as shown below, MKR does not emit the usual Transfer events when burning and minting tokens.
If these subtleties are not taken into account, your off-chain accounting might be inaccurate and introduce unexpected errors in your systems.
On top of everything covered in the workshop, it must be noted that some tokens are upgradable. This means that their behavior could change at any point in time. Therefore, when integrating upgradeable tokens, never assume immutability. Instead, you should consistently monitor their upgrade processes and be ready to react quickly to a suspicious or non-compatible upgrade. Examples of upgradeable tokens shown in the workshop are USDC, TUSD and UBI. In USDC, you will find the following upgradeTo function that allows a privileged account to trigger an upgrade.
As upgradeability becomes more popular among Ethereum applications, it is sensible to expect most tokens will include some sort of upgradeability mechanism.
While all general guidelines, specific issues, and security recommendations discussed during the workshop are valuable and relevant in today’s ecosystem, a fundamental aspect of integrating tokens not covered in the workshop is assessing economic risks. There have been multiple cases of protocols failing just due to problems in the underlying assets being used. Risk analysis is of the utmost importance, and responsible teams should aim to have dedicated members studying this aspect of token integration. Even if Solidity smart contracts are implemented flawlessly, price volatility and misalignment of economic incentives often become dangerously problematic and lead to failures.
The Ethereum security community is quite active and collects many of these behaviors in different checklists and repositories. These are some of them:
To see the slides from the webinar click here.
Join the next installment of the security series on August 26th!
Learn more about OpenZeppelin Contracts and sign up for a free Defender account.
See the documentation:
OpenZeppelin Defender Documentation
OpenZeppelin Contracts Documentation