You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
132 lines
7.1 KiB
Plaintext
132 lines
7.1 KiB
Plaintext
= Extending Contracts
|
|
|
|
Most of the OpenZeppelin Contracts are expected to be used via https://solidity.readthedocs.io/en/latest/contracts.html#inheritance[inheritance]: you will _inherit_ from them when writing your own contracts.
|
|
|
|
This is the commonly found `is` syntax, like in `contract MyToken is ERC20`.
|
|
|
|
[NOTE]
|
|
====
|
|
Unlike ``contract``s, Solidity ``library``s are not inherited from and instead rely on the https://solidity.readthedocs.io/en/latest/contracts.html#using-for[`using for`] syntax.
|
|
|
|
OpenZeppelin Contracts has some ``library``s: most are in the xref:api:utils.adoc[Utils] directory.
|
|
====
|
|
|
|
== Overriding
|
|
|
|
Inheritance is often used to add the parent contract's functionality to your own contract, but that's not all it can do. You can also _change_ how some parts of the parent behave using _overrides_.
|
|
|
|
For example, imagine you want to change xref:api:access.adoc#AccessControl[`AccessControl`] so that xref:api:access.adoc#AccessControl-revokeRole-bytes32-address-[`revokeRole`] can no longer be called. This can be achieved using overrides:
|
|
|
|
```solidity
|
|
// contracts/ModifiedAccessControl.sol
|
|
// SPDX-License-Identifier: MIT
|
|
pragma solidity ^0.8.0;
|
|
|
|
import "@openzeppelin/contracts/access/AccessControl.sol";
|
|
|
|
contract ModifiedAccessControl is AccessControl {
|
|
// Override the revokeRole function
|
|
function revokeRole(bytes32, address) public override {
|
|
revert("ModifiedAccessControl: cannot revoke roles");
|
|
}
|
|
}
|
|
```
|
|
|
|
The old `revokeRole` is then replaced by our override, and any calls to it will immediately revert. We cannot _remove_ the function from the contract, but reverting on all calls is good enough.
|
|
|
|
=== Calling `super`
|
|
|
|
Sometimes you want to _extend_ a parent's behavior, instead of outright changing it to something else. This is where `super` comes in.
|
|
|
|
The `super` keyword will let you call functions defined in a parent contract, even if they are overridden. This mechanism can be used to add additional checks to a function, emit events, or otherwise add functionality as you see fit.
|
|
|
|
TIP: For more information on how overrides work, head over to the https://solidity.readthedocs.io/en/latest/contracts.html#index-17[official Solidity documentation].
|
|
|
|
Here is a modified version of xref:api:access.adoc#AccessControl[`AccessControl`] where xref:api:access.adoc#AccessControl-revokeRole-bytes32-address-[`revokeRole`] cannot be used to revoke the `DEFAULT_ADMIN_ROLE`:
|
|
|
|
|
|
```solidity
|
|
// contracts/ModifiedAccessControl.sol
|
|
// SPDX-License-Identifier: MIT
|
|
pragma solidity ^0.8.0;
|
|
|
|
import "@openzeppelin/contracts/access/AccessControl.sol";
|
|
|
|
contract ModifiedAccessControl is AccessControl {
|
|
function revokeRole(bytes32 role, address account) public override {
|
|
require(
|
|
role != DEFAULT_ADMIN_ROLE,
|
|
"ModifiedAccessControl: cannot revoke default admin role"
|
|
);
|
|
|
|
super.revokeRole(role, account);
|
|
}
|
|
}
|
|
```
|
|
|
|
The `super.revokeRole` statement at the end will invoke ``AccessControl``'s original version of `revokeRole`, the same code that would've run if there were no overrides in place.
|
|
|
|
NOTE: As of v3.0.0, `view` functions are not `virtual` in OpenZeppelin, and therefore cannot be overridden. We're considering https://github.com/OpenZeppelin/openzeppelin-contracts/issues/2154[lifting this restriction] in an upcoming release. Let us know if this is something you care about!
|
|
|
|
[[using-hooks]]
|
|
== Using Hooks
|
|
|
|
Sometimes, in order to extend a parent contract you will need to override multiple related functions, which leads to code duplication and increased likelihood of bugs.
|
|
|
|
For example, consider implementing safe xref:api:token/ERC20.adoc#ERC20[`ERC20`] transfers in the style of xref:api:token/ERC721.adoc#IERC721Receiver[`IERC721Receiver`]. You may think overriding xref:api:token/ERC20.adoc#ERC20-transfer-address-uint256-[`transfer`] and xref:api:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256-[`transferFrom`] would be enough, but what about xref:api:token/ERC20.adoc#ERC20-_transfer-address-address-uint256-[`_transfer`] and xref:api:token/ERC20.adoc#ERC20-_mint-address-uint256-[`_mint`]? To prevent you from having to deal with these details, we introduced **hooks**.
|
|
|
|
Hooks are simply functions that are called before or after some action takes place. They provide a centralized point to _hook into_ and extend the original behavior.
|
|
|
|
Here's how you would implement the `IERC721Receiver` pattern in `ERC20`, using the xref:api:token/ERC20.adoc#ERC20-_beforeTokenTransfer-address-address-uint256-[`_beforeTokenTransfer`] hook:
|
|
|
|
```solidity
|
|
pragma solidity ^0.8.0;
|
|
|
|
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
|
|
|
|
contract ERC20WithSafeTransfer is ERC20 {
|
|
function _beforeTokenTransfer(address from, address to, uint256 amount)
|
|
internal virtual override
|
|
{
|
|
super._beforeTokenTransfer(from, to, amount);
|
|
|
|
require(_validRecipient(to), "ERC20WithSafeTransfer: invalid recipient");
|
|
}
|
|
|
|
function _validRecipient(address to) private view returns (bool) {
|
|
...
|
|
}
|
|
|
|
...
|
|
}
|
|
```
|
|
|
|
Using hooks this way leads to cleaner and safer code, without having to rely on a deep understanding of the parent's internals.
|
|
|
|
=== Rules of Hooks
|
|
|
|
There's a few guidelines you should follow when writing code that uses hooks in order to prevent issues. They are very simple, but do make sure you follow them:
|
|
|
|
1. Whenever you override a parent's hook, re-apply the `virtual` attribute to the hook. That will allow child contracts to add more functionality to the hook.
|
|
2. **Always** call the parent's hook in your override using `super`. This will make sure all hooks in the inheritance tree are called: contracts like xref:api:token/ERC20.adoc#ERC20Pausable[`ERC20Pausable`] rely on this behavior.
|
|
|
|
```solidity
|
|
contract MyToken is ERC20 {
|
|
function _beforeTokenTransfer(address from, address to, uint256 amount)
|
|
internal virtual override // Add virtual here!
|
|
{
|
|
super._beforeTokenTransfer(from, to, amount); // Call parent hook
|
|
...
|
|
}
|
|
}
|
|
```
|
|
That's it! Enjoy simpler code using hooks!
|
|
|
|
== Security
|
|
|
|
The maintainers of OpenZeppelin Contracts are mainly concerned with the correctness and security of the code as published in the library, and the combinations of base contracts with the official extensions from the library.
|
|
|
|
Custom overrides, and those of hooks in particular, may break some important assumptions and introduce vulnerabilities in otherwise secure code. While we try to ensure the contracts remain secure in the face of a wide range of potential customizations, this is done in a best-effort manner. While we try to document all important assumptions, this should not be relied upon. Custom overrides should be carefully reviewed and checked against the source code of the contract they are customizing so as to fully understand their impact and guarantee their security.
|
|
|
|
The way functions interact internally should not be assumed to stay stable across releases of the library. For example, a function that is used in one context in a particular release may not be used in the same context in the next release. Contracts that override functions should revalidate their assumptions when updating the version of OpenZeppelin Contracts they are built on.
|