Reorganize the repo structure (#2503)

Co-authored-by: Francisco Giordano <frangio.1@gmail.com>

CHANGELOG.md

@@ -13,6 +13,17 @@
  * `ERC721`: remove enumerability of tokens from the base implementation. This feature is now provided separately through the `ERC721Enumerable` extension. ([#2511](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2511))
  * `AccessControl`: removed enumerability by default for a more lightweight contract. It is now opt-in through `AccessControlEnumerable`. ([#2512](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2512))
  * Meta Transactions: add `ERC2771Context` and a `MinimalForwarder` for meta-transactions. ([#2508](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2508))
+ * Overall reorganisation of the contract folder to improve clarity and discoverability. ([#2503](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2503))
+
+### How to upgrade from 3.x
+
+Since this version has moved a few contracts to different directories, users upgrading from a previous version will need to adjust their import statements. To make this easier, the package includes a script that will migrate import statements automatically. After upgrading to the latest version of the package, run:
+
+```
+npx openzeppelin-contracts-migrate-imports
+```
+
+Make sure you're using git or another version control system to be able to recover from any potential error in our script.
 
 ## 3.4.0 (2021-02-02)
 

contracts/access/AccessControlEnumerable.sol

@@ -3,7 +3,7 @@
 pragma solidity ^0.8.0;
 
 import "./AccessControl.sol";
-import "../utils/EnumerableSet.sol";
+import "../utils/structs/EnumerableSet.sol";
 
 /**
  * @dev Extension of {AccessControl} that allows enumerating the members of each role.

contracts/access/README.adoc

@@ -7,7 +7,6 @@ This directory provides ways to restrict who can access the functions of a contr
 
 - {AccessControl} provides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts.
 - {Ownable} is a simpler mechanism with a single owner "role" that can be assigned to a single account. This simpler mechanism can be useful for quick tests but projects with production concerns are likely to outgrow it.
-- {TimelockController} is used in combination with one of the above two mechanisms. By assigning a role to an instance of the `TimelockController` contract, the access to the functions controlled by that role will be delayed by some amount of time.
 
 == Authorization
 
@@ -16,88 +15,3 @@ This directory provides ways to restrict who can access the functions of a contr
 {{AccessControl}}
 
 {{AccessControlEnumerable}}
-
-== Timelock
-
-{{TimelockController}}
-
-[[timelock-terminology]]
-==== Terminology
-
-* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution (see xref:access-control.adoc#operation_lifecycle[operation lifecycle]). If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content.
-* *Operation status:*
-** *Unset:* An operation that is not part of the timelock mechanism.
-** *Pending:* An operation that has been scheduled, before the timer expires.
-** *Ready:* An operation that has been scheduled, after the timer expires.
-** *Done:* An operation that has been executed.
-* *Predecessor*: An (optional) dependency between operations. An operation can depend on another operation (its predecessor), forcing the execution order of these two operations.
-* *Role*:
-** *Proposer:* An address (smart contract or EOA) that is in charge of scheduling (and cancelling) operations.
-** *Executor:* An address (smart contract or EOA) that is in charge of executing operations.
-
-[[timelock-operation]]
-==== Operation structure
-
-Operation executed by the xref:api:access.adoc#TimelockController[`TimelockControler`] can contain one or multiple subsequent calls. Depending on whether you need to multiple calls to be executed atomically, you can either use simple or batched operations.
-
-Both operations contain:
-
-* *Target*, the address of the smart contract that the timelock should operate on.
-* *Value*, in wei, that should be sent with the transaction. Most of the time this will be 0. Ether can be deposited before-end or passed along when executing the transaction.
-* *Data*, containing the encoded function selector and parameters of the call. This can be produced using a number of tools. For example, a maintenance operation granting role `ROLE` to `ACCOUNT` can be encode using web3js as follows:
-
-```javascript
-const data = timelock.contract.methods.grantRole(ROLE, ACCOUNT).encodeABI()
-```
-
-* *Predecessor*, that specifies a dependency between operations. This dependency is optional. Use `bytes32(0)` if the operation does not have any dependency.
-* *Salt*, used to disambiguate two otherwise identical operations. This can be any random value.
-
-In the case of batched operations, `target`, `value` and `data` are specified as arrays, which must be of the same length.
-
-[[timelock-operation-lifecycle]]
-==== Operation lifecycle
-
-Timelocked operations are identified by a unique id (their hash) and follow a specific lifecycle:
-
-`Unset` -> `Pending` -> `Pending` + `Ready` -> `Done`
-
-* By calling xref:api:access.adoc#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-[`schedule`] (or xref:api:access.adoc#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-[`scheduleBatch`]), a proposer moves the operation from the `Unset` to the `Pending` state. This starts a timer that must be longer than the minimum delay. The timer expires at a timestamp accessible through the xref:api:access.adoc#TimelockController-getTimestamp-bytes32-[`getTimestamp`] method.
-* Once the timer expires, the operation automatically gets the `Ready` state. At this point, it can be executed.
-* By calling xref:api:access.adoc#TimelockController-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-[`execute`] (or xref:api:access.adoc#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-[`executeBatch`]), an executor triggers the operation's underlying transactions and moves it to the `Done` state. If the operation has a predecessor, it has to be in the `Done` state for this transition to succeed.
-* xref:api:access.adoc#TimelockController-TimelockController-cancel-bytes32-[`cancel`] allows proposers to cancel any `Pending` operation. This resets the operation to the `Unset` state. It is thus possible for a proposer to re-schedule an operation that has been cancelled. In this case, the timer restarts when the operation is re-scheduled.
-
-Operations status can be queried using the functions:
-
-* xref:api:access.adoc#TimelockController-isOperationPending-bytes32-[`isOperationPending(bytes32)`]
-* xref:api:access.adoc#TimelockController-isOperationReady-bytes32-[`isOperationReady(bytes32)`]
-* xref:api:access.adoc#TimelockController-isOperationDone-bytes32-[`isOperationDone(bytes32)`]
-
-[[timelock-roles]]
-==== Roles
-
-[[timelock-admin]]
-===== Admin
-
-The admins are in charge of managing proposers and executors. For the timelock to be self-governed, this role should only be given to the timelock itself. Upon deployment, both the timelock and the deployer have this role. After further configuration and testing, the deployer can renounce this role such that all further maintenance operations have to go through the timelock process.
-
-This role is identified by the *TIMELOCK_ADMIN_ROLE* value: `0x5f58e3a2316349923ce3780f8d587db2d72378aed66a8261c916544fa6846ca5`
-
-[[timelock-proposer]]
-===== Proposer
-
-The proposers are in charge of scheduling (and cancelling) operations. This is a critical role, that should be given to governing entities. This could be an EOA, a multisig, or a DAO.
-
-WARNING: *Proposer fight:* Having multiple proposers, while providing redundancy in case one becomes unavailable, can be dangerous. As proposer have their say on all operations, they could cancel operations they disagree with, including operations to remove them for the proposers.
-
-This role is identified by the *PROPOSER_ROLE* value: `0xb09aa5aeb3702cfd50b6b62bc4532604938f21248a27a1d5ca736082b6819cc1`
-
-[[timelock-executor]]
-===== Executor
-
-The executors are in charge of executing the operations scheduled by the proposers once the timelock expires. Logic dictates that multisig or DAO that are proposers should also be executors in order to guarantee operations that have been scheduled will eventually be executed. However, having additional executor can reduce the cost (the executing transaction does not require validation by the multisig or DAO that proposed it), while ensuring whoever is in charge of execution cannot trigger actions that have not been scheduled by the proposers.
-
-This role is identified by the *EXECUTOR_ROLE* value: `0xd8aa0f3194971a2a116679f7c2090f6939c8d4e01a2a8d7e41d55e5351469e63`
-
-
-WARNING: A live contract without at least one proposer and one executor is locked. Make sure these roles are filled by reliable entities before the deployer renounces its administrative rights in favour of the timelock contract itself. See the {AccessControl} documentation to learn more about role management.

contracts/cryptography/README.adoc

@@ -1,16 +0,0 @@
-= Cryptography
-
-[.readme-notice]
-NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/cryptography
-
-This collection of libraries provides simple and safe ways to use different cryptographic primitives.
-
-The following related EIPs are in draft status and can be found in the drafts directory.
-
-- {EIP712}
-
-== Libraries
-
-{{ECDSA}}
-
-{{MerkleProof}}

contracts/drafts/README.adoc

@@ -1,15 +0,0 @@
-= Draft EIPs
-
-This directory contains implementations of EIPs that are still in Draft status.
-
-Due to their nature as drafts, the details of these contracts may change and we cannot guarantee their xref:ROOT:releases-stability.adoc[stability]. Minor releases of OpenZeppelin Contracts may contain breaking changes for the contracts in this directory, which will be duly announced in the https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/CHANGELOG.md[changelog]. The EIPs included here are used by projects in production and this may make them less likely to change significantly.
-
-== Cryptography
-
-{{EIP712}}
-
-== ERC 20
-
-{{IERC20Permit}}
-
-{{ERC20Permit}}

contracts/governance/README.adoc

@@ -0,0 +1,91 @@
+= Governance
+
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/access
+
+This directory includes primitives for on-chain governance. We currently only offer the {TimelockController} contract, that can be used as a component in a governance systems to introduce a delay between a proposal and its execution.
+
+== Timelock
+
+{{TimelockController}}
+
+[[timelock-terminology]]
+==== Terminology
+
+* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution (see xref:access-control.adoc#operation_lifecycle[operation lifecycle]). If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content.
+* *Operation status:*
+** *Unset:* An operation that is not part of the timelock mechanism.
+** *Pending:* An operation that has been scheduled, before the timer expires.
+** *Ready:* An operation that has been scheduled, after the timer expires.
+** *Done:* An operation that has been executed.
+* *Predecessor*: An (optional) dependency between operations. An operation can depend on another operation (its predecessor), forcing the execution order of these two operations.
+* *Role*:
+** *Proposer:* An address (smart contract or EOA) that is in charge of scheduling (and cancelling) operations.
+** *Executor:* An address (smart contract or EOA) that is in charge of executing operations.
+
+[[timelock-operation]]
+==== Operation structure
+
+Operation executed by the xref:api:access.adoc#TimelockController[`TimelockControler`] can contain one or multiple subsequent calls. Depending on whether you need to multiple calls to be executed atomically, you can either use simple or batched operations.
+
+Both operations contain:
+
+* *Target*, the address of the smart contract that the timelock should operate on.
+* *Value*, in wei, that should be sent with the transaction. Most of the time this will be 0. Ether can be deposited before-end or passed along when executing the transaction.
+* *Data*, containing the encoded function selector and parameters of the call. This can be produced using a number of tools. For example, a maintenance operation granting role `ROLE` to `ACCOUNT` can be encode using web3js as follows:
+
+```javascript
+const data = timelock.contract.methods.grantRole(ROLE, ACCOUNT).encodeABI()
+```
+
+* *Predecessor*, that specifies a dependency between operations. This dependency is optional. Use `bytes32(0)` if the operation does not have any dependency.
+* *Salt*, used to disambiguate two otherwise identical operations. This can be any random value.
+
+In the case of batched operations, `target`, `value` and `data` are specified as arrays, which must be of the same length.
+
+[[timelock-operation-lifecycle]]
+==== Operation lifecycle
+
+Timelocked operations are identified by a unique id (their hash) and follow a specific lifecycle:
+
+`Unset` -> `Pending` -> `Pending` + `Ready` -> `Done`
+
+* By calling xref:api:access.adoc#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-[`schedule`] (or xref:api:access.adoc#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-[`scheduleBatch`]), a proposer moves the operation from the `Unset` to the `Pending` state. This starts a timer that must be longer than the minimum delay. The timer expires at a timestamp accessible through the xref:api:access.adoc#TimelockController-getTimestamp-bytes32-[`getTimestamp`] method.
+* Once the timer expires, the operation automatically gets the `Ready` state. At this point, it can be executed.
+* By calling xref:api:access.adoc#TimelockController-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-[`execute`] (or xref:api:access.adoc#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-[`executeBatch`]), an executor triggers the operation's underlying transactions and moves it to the `Done` state. If the operation has a predecessor, it has to be in the `Done` state for this transition to succeed.
+* xref:api:access.adoc#TimelockController-TimelockController-cancel-bytes32-[`cancel`] allows proposers to cancel any `Pending` operation. This resets the operation to the `Unset` state. It is thus possible for a proposer to re-schedule an operation that has been cancelled. In this case, the timer restarts when the operation is re-scheduled.
+
+Operations status can be queried using the functions:
+
+* xref:api:access.adoc#TimelockController-isOperationPending-bytes32-[`isOperationPending(bytes32)`]
+* xref:api:access.adoc#TimelockController-isOperationReady-bytes32-[`isOperationReady(bytes32)`]
+* xref:api:access.adoc#TimelockController-isOperationDone-bytes32-[`isOperationDone(bytes32)`]
+
+[[timelock-roles]]
+==== Roles
+
+[[timelock-admin]]
+===== Admin
+
+The admins are in charge of managing proposers and executors. For the timelock to be self-governed, this role should only be given to the timelock itself. Upon deployment, both the timelock and the deployer have this role. After further configuration and testing, the deployer can renounce this role such that all further maintenance operations have to go through the timelock process.
+
+This role is identified by the *TIMELOCK_ADMIN_ROLE* value: `0x5f58e3a2316349923ce3780f8d587db2d72378aed66a8261c916544fa6846ca5`
+
+[[timelock-proposer]]
+===== Proposer
+
+The proposers are in charge of scheduling (and cancelling) operations. This is a critical role, that should be given to governing entities. This could be an EOA, a multisig, or a DAO.
+
+WARNING: *Proposer fight:* Having multiple proposers, while providing redundancy in case one becomes unavailable, can be dangerous. As proposer have their say on all operations, they could cancel operations they disagree with, including operations to remove them for the proposers.
+
+This role is identified by the *PROPOSER_ROLE* value: `0xb09aa5aeb3702cfd50b6b62bc4532604938f21248a27a1d5ca736082b6819cc1`
+
+[[timelock-executor]]
+===== Executor
+
+The executors are in charge of executing the operations scheduled by the proposers once the timelock expires. Logic dictates that multisig or DAO that are proposers should also be executors in order to guarantee operations that have been scheduled will eventually be executed. However, having additional executor can reduce the cost (the executing transaction does not require validation by the multisig or DAO that proposed it), while ensuring whoever is in charge of execution cannot trigger actions that have not been scheduled by the proposers.
+
+This role is identified by the *EXECUTOR_ROLE* value: `0xd8aa0f3194971a2a116679f7c2090f6939c8d4e01a2a8d7e41d55e5351469e63`
+
+
+WARNING: A live contract without at least one proposer and one executor is locked. Make sure these roles are filled by reliable entities before the deployer renounces its administrative rights in favour of the timelock contract itself. See the {AccessControl} documentation to learn more about role management.

contracts/governance/TimelockController.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./AccessControl.sol";
+import "../access/AccessControl.sol";
 
 /**
  * @dev Contract module which acts as a timelocked controller. When set as the

contracts/introspection/README.adoc

@@ -1,33 +0,0 @@
-= Introspection
-
-[.readme-notice]
-NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/introspection
-
-This set of interfaces and contracts deal with https://en.wikipedia.org/wiki/Type_introspection[type introspection] of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_.
-
-Ethereum contracts have no native concept of an interface, so applications must usually simply trust they are not making an incorrect call. For trusted setups this is a non-issue, but often unknown and untrusted third-party addresses need to be interacted with. There may even not be any direct calls to them! (e.g. `ERC20` tokens may be sent to a contract that lacks a way to transfer them out of it, locking them forever). In these cases, a contract _declaring_ its interface can be very helpful in preventing errors.
-
-There are two main ways to approach this.
-
-* Locally, where a contract implements `IERC165` and declares an interface, and a second one queries it directly via `ERC165Checker`.
-* Globally, where a global and unique registry (`IERC1820Registry`) is used to register implementers of a certain interface (`IERC1820Implementer`). It is then the registry that is queried, which allows for more complex setups, like contracts implementing interfaces for externally-owned accounts.
-
-Note that, in all cases, accounts simply _declare_ their interfaces, but they are not required to actually implement them. This mechanism can therefore be used to both prevent errors and allow for complex interactions (see `ERC777`), but it must not be relied on for security.
-
-== Local
-
-{{IERC165}}
-
-{{ERC165}}
-
-{{ERC165Storage}}
-
-{{ERC165Checker}}
-
-== Global
-
-{{IERC1820Registry}}
-
-{{IERC1820Implementer}}
-
-{{ERC1820Implementer}}

contracts/math/README.adoc

@@ -1,14 +0,0 @@
-= Math
-
-[.readme-notice]
-NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/math
-
-These are math-related utilities.
-
-== Libraries
-
-{{SafeMath}}
-
-{{SignedSafeMath}}
-
-{{Math}}

contracts/metatx/MinimalForwarder.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "../cryptography/ECDSA.sol";
-import "../drafts/EIP712.sol";
+import "../utils/cryptography/ECDSA.sol";
+import "../utils/cryptography/draft-EIP712.sol";
 
 /*
  * @dev Simple minimal forwarder to be used together with an ERC2771 compatible contract. See {ERC2771Context}.

contracts/metatx/README.adoc

@@ -1,7 +1,7 @@
 = Meta Transactions
 
 [.readme-notice]
-NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/math
+NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/metatx
 
 == Core
 

contracts/mocks/ConditionalEscrowMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../payment/escrow/ConditionalEscrow.sol";
+import "../utils/escrow/ConditionalEscrow.sol";
 
 // mock class using ConditionalEscrow
 contract ConditionalEscrowMock is ConditionalEscrow {

contracts/mocks/Create2Impl.sol

@@ -3,7 +3,7 @@
 pragma solidity ^0.8.0;
 
 import "../utils/Create2.sol";
-import "../introspection/ERC1820Implementer.sol";
+import "../utils/introspection/ERC1820Implementer.sol";
 
 contract Create2Impl {
     function deploy(uint256 value, bytes32 salt, bytes memory code) public {

contracts/mocks/ECDSAMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../cryptography/ECDSA.sol";
+import "../utils/cryptography/ECDSA.sol";
 
 contract ECDSAMock {
     using ECDSA for bytes32;

contracts/mocks/EIP712External.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "../drafts/EIP712.sol";
-import "../cryptography/ECDSA.sol";
+import "../utils/cryptography/draft-EIP712.sol";
+import "../utils/cryptography/ECDSA.sol";
 
 contract EIP712External is EIP712 {
     constructor(string memory name, string memory version) EIP712(name, version) {}

contracts/mocks/ERC1155BurnableMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC1155/ERC1155Burnable.sol";
+import "../token/ERC1155/extensions/ERC1155Burnable.sol";
 
 contract ERC1155BurnableMock is ERC1155Burnable {
     constructor(string memory uri) ERC1155(uri) { }

contracts/mocks/ERC1155PausableMock.sol

@@ -3,7 +3,7 @@
 pragma solidity ^0.8.0;
 
 import "./ERC1155Mock.sol";
-import "../token/ERC1155/ERC1155Pausable.sol";
+import "../token/ERC1155/extensions/ERC1155Pausable.sol";
 
 contract ERC1155PausableMock is ERC1155Mock, ERC1155Pausable {
     constructor(string memory uri) ERC1155Mock(uri) { }

contracts/mocks/ERC1155ReceiverMock.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "../introspection/ERC165.sol";
 import "../token/ERC1155/IERC1155Receiver.sol";
+import "../utils/introspection/ERC165.sol";
 
 contract ERC1155ReceiverMock is IERC1155Receiver, ERC165 {
     bytes4 private _recRetval;

contracts/mocks/ERC165/ERC165InterfacesSupported.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../../introspection/IERC165.sol";
+import "../../utils/introspection/IERC165.sol";
 
 /**
  * https://eips.ethereum.org/EIPS/eip-214#specification

contracts/mocks/ERC165CheckerMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../introspection/ERC165Checker.sol";
+import "../utils/introspection/ERC165Checker.sol";
 
 contract ERC165CheckerMock {
     using ERC165Checker for address;

contracts/mocks/ERC165Mock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../introspection/ERC165.sol";
+import "../utils/introspection/ERC165.sol";
 
 contract ERC165Mock is ERC165 {
 }

contracts/mocks/ERC165StorageMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../introspection/ERC165Storage.sol";
+import "../utils/introspection/ERC165Storage.sol";
 
 contract ERC165StorageMock is ERC165Storage {
     function registerInterface(bytes4 interfaceId) public {

contracts/mocks/ERC1820ImplementerMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../introspection/ERC1820Implementer.sol";
+import "../utils/introspection/ERC1820Implementer.sol";
 
 contract ERC1820ImplementerMock is ERC1820Implementer {
     function registerInterfaceForAddress(bytes32 interfaceHash, address account) public {

contracts/mocks/ERC20BurnableMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC20/ERC20Burnable.sol";
+import "../token/ERC20/extensions/ERC20Burnable.sol";
 
 contract ERC20BurnableMock is ERC20Burnable {
     constructor (

contracts/mocks/ERC20CappedMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC20/ERC20Capped.sol";
+import "../token/ERC20/extensions/ERC20Capped.sol";
 
 contract ERC20CappedMock is ERC20Capped {
     constructor (string memory name, string memory symbol, uint256 cap)

contracts/mocks/ERC20PausableMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC20/ERC20Pausable.sol";
+import "../token/ERC20/extensions/ERC20Pausable.sol";
 
 // mock class using ERC20Pausable
 contract ERC20PausableMock is ERC20Pausable {

contracts/mocks/ERC20PermitMock.sol

@@ -2,7 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "../drafts/ERC20Permit.sol";
+
+import "../token/ERC20/extensions/draft-ERC20Permit.sol";
 
 contract ERC20PermitMock is ERC20Permit {
     constructor (

contracts/mocks/ERC20SnapshotMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC20/ERC20Snapshot.sol";
+import "../token/ERC20/extensions/ERC20Snapshot.sol";
 
 
 contract ERC20SnapshotMock is ERC20Snapshot {

contracts/mocks/ERC721BurnableMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC721/ERC721Burnable.sol";
+import "../token/ERC721/extensions/ERC721Burnable.sol";
 
 contract ERC721BurnableMock is ERC721Burnable {
     constructor(string memory name, string memory symbol) ERC721(name, symbol) { }

contracts/mocks/ERC721EnumerableMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC721/ERC721Enumerable.sol";
+import "../token/ERC721/extensions/ERC721Enumerable.sol";
 
 /**
  * @title ERC721Mock

contracts/mocks/ERC721PausableMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC721/ERC721Pausable.sol";
+import "../token/ERC721/extensions/ERC721Pausable.sol";
 
 /**
  * @title ERC721PausableMock

contracts/mocks/ERC777SenderRecipientMock.sol

@@ -2,12 +2,12 @@
 
 pragma solidity ^0.8.0;
 
-import "../utils/Context.sol";
 import "../token/ERC777/IERC777.sol";
 import "../token/ERC777/IERC777Sender.sol";
 import "../token/ERC777/IERC777Recipient.sol";
-import "../introspection/IERC1820Registry.sol";
-import "../introspection/ERC1820Implementer.sol";
+import "../utils/Context.sol";
+import "../utils/introspection/IERC1820Registry.sol";
+import "../utils/introspection/ERC1820Implementer.sol";
 
 contract ERC777SenderRecipientMock is Context, IERC777Sender, IERC777Recipient, ERC1820Implementer {
     event TokensToSendCalled(
@@ -150,4 +150,3 @@ contract ERC777SenderRecipientMock is Context, IERC777Sender, IERC777Recipient,
         token.burn(amount, data);
     }
 }
-

contracts/mocks/EnumerableMapMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../utils/EnumerableMap.sol";
+import "../utils/structs/EnumerableMap.sol";
 
 contract EnumerableMapMock {
     using EnumerableMap for EnumerableMap.UintToAddressMap;

contracts/mocks/EnumerableSetMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../utils/EnumerableSet.sol";
+import "../utils/structs/EnumerableSet.sol";
 
 // Bytes32Set
 contract EnumerableBytes32SetMock {

contracts/mocks/InitializableMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../proxy/Initializable.sol";
+import "../utils/Initializable.sol";
 
 /**
  * @title InitializableMock

contracts/mocks/MathMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../math/Math.sol";
+import "../utils/math/Math.sol";
 
 contract MathMock {
     function max(uint256 a, uint256 b) public pure returns (uint256) {

contracts/mocks/MerkleProofWrapper.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import { MerkleProof } from "../cryptography/MerkleProof.sol";
+import "../utils/cryptography/MerkleProof.sol";
 
 contract MerkleProofWrapper {
     function verify(bytes32[] memory proof, bytes32 root, bytes32 leaf) public pure returns (bool) {

contracts/mocks/MultipleInheritanceInitializableMocks.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../proxy/Initializable.sol";
+import "../utils/Initializable.sol";
 
 // Sample contracts showing upgradeability with multiple inheritance.
 // Child contract inherits from Father and Mother contracts, and Father extends from Gramps.

contracts/mocks/PausableMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../utils/Pausable.sol";
+import "../security/Pausable.sol";
 
 contract PausableMock is Pausable {
     bool public drasticMeasureTaken;

contracts/mocks/PullPaymentMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../payment/PullPayment.sol";
+import "../security/PullPayment.sol";
 
 // mock class using PullPayment
 contract PullPaymentMock is PullPayment {

contracts/mocks/ReentrancyMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../utils/ReentrancyGuard.sol";
+import "../security/ReentrancyGuard.sol";
 import "./ReentrancyAttack.sol";
 
 contract ReentrancyMock is ReentrancyGuard {

contracts/mocks/RegressionImplementation.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../proxy/Initializable.sol";
+import "../utils/Initializable.sol";
 
 contract Implementation1 is Initializable {
   uint internal _value;

contracts/mocks/SafeCastMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../utils/SafeCast.sol";
+import "../utils/math/SafeCast.sol";
 
 contract SafeCastMock {
     using SafeCast for uint;

contracts/mocks/SafeERC20Helper.sol

@@ -4,7 +4,7 @@ pragma solidity ^0.8.0;
 
 import "../utils/Context.sol";
 import "../token/ERC20/IERC20.sol";
-import "../token/ERC20/SafeERC20.sol";
+import "../token/ERC20/utils/SafeERC20.sol";
 
 contract ERC20ReturnFalseMock is Context {
     uint256 private _allowance;

contracts/mocks/SafeMathMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../math/SafeMath.sol";
+import "../utils/math/SafeMath.sol";
 
 contract SafeMathMock {
     function tryAdd(uint256 a, uint256 b) public pure returns (bool flag, uint256 value) {

contracts/mocks/SignedSafeMathMock.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../math/SignedSafeMath.sol";
+import "../utils/math/SignedSafeMath.sol";
 
 contract SignedSafeMathMock {
     function mul(int256 a, int256 b) public pure returns (int256) {

contracts/mocks/SingleInheritanceInitializableMocks.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../proxy/Initializable.sol";
+import "../utils/Initializable.sol";
 
 /**
  * @title MigratableMockV1

contracts/payment/README.adoc

@@ -1,22 +0,0 @@
-= Payment
-
-[.readme-notice]
-NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/payment
-
-Utilities related to sending and receiving payments. Examples are {PullPayment}, which implements the best security practices when sending funds to third parties, and {PaymentSplitter} to receive incoming payments among a number of beneficiaries.
-
-TIP: When transferring funds to and from untrusted third parties, there is always a security risk of reentrancy. If you would like to learn more about this and ways to protect against it, check out our blog post https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].
-
-== Utilities
-
-{{PaymentSplitter}}
-
-{{PullPayment}}
-
-== Escrow
-
-{{Escrow}}
-
-{{ConditionalEscrow}}
-
-{{RefundEscrow}}

contracts/presets/README.adoc

@@ -1,22 +0,0 @@
-= Presets
-
-[.readme-notice]
-NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/presets
-
-These contracts integrate different Ethereum standards (ERCs) with custom extensions and modules, showcasing common configurations that are ready to deploy **without having to write any Solidity code**.
-
-They can be used as-is for quick prototyping and testing, but are **also suitable for production environments**.
-
-TIP: Intermediate and advanced users can use these as starting points when writing their own contracts, extending them with custom functionality as they see fit.
-
-== Tokens
-
-{{ERC20PresetMinterPauser}}
-
-{{ERC721PresetMinterPauserAutoId}}
-
-{{ERC1155PresetMinterPauser}}
-
-{{ERC20PresetFixedSupply}}
-
-{{ERC777PresetFixedSupply}}

contracts/proxy/README.adoc

@@ -21,8 +21,12 @@ CAUTION: Using upgradeable proxies correctly and securely is a difficult task th
 
 {{UpgradeableProxy}}
 
+== Transparent Proxy
+
 {{TransparentUpgradeableProxy}}
 
+{{ProxyAdmin}}
+
 == Beacon
 
 {{BeaconProxy}}
@@ -34,9 +38,3 @@ CAUTION: Using upgradeable proxies correctly and securely is a difficult task th
 == Minimal Clones
 
 {{Clones}}
-
-== Utilities
-
-{{Initializable}}
-
-{{ProxyAdmin}}

contracts/proxy/beacon/BeaconProxy.sol

@@ -2,9 +2,9 @@
 
 pragma solidity ^0.8.0;
 
-import "./Proxy.sol";
-import "../utils/Address.sol";
 import "./IBeacon.sol";
+import "../Proxy.sol";
+import "../../utils/Address.sol";
 
 /**
  * @dev This contract implements a proxy that gets the implementation address for each call from a {UpgradeableBeacon}.

contracts/proxy/beacon/UpgradeableBeacon.sol

@@ -3,8 +3,8 @@
 pragma solidity ^0.8.0;
 
 import "./IBeacon.sol";
-import "../access/Ownable.sol";
-import "../utils/Address.sol";
+import "../../access/Ownable.sol";
+import "../../utils/Address.sol";
 
 /**
  * @dev This contract is used in conjunction with one or more instances of {BeaconProxy} to determine their

contracts/proxy/transparent/ProxyAdmin.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "../access/Ownable.sol";
 import "./TransparentUpgradeableProxy.sol";
+import "../../access/Ownable.sol";
 
 /**
  * @dev This is an auxiliary contract meant to be assigned as the admin of a {TransparentUpgradeableProxy}. For an

contracts/proxy/transparent/TransparentUpgradeableProxy.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./UpgradeableProxy.sol";
+import "../UpgradeableProxy.sol";
 
 /**
  * @dev This contract implements a proxy that is upgradeable by an admin.

contracts/security/Pausable.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./Context.sol";
+import "../utils/Context.sol";
 
 /**
  * @dev Contract module which allows children to implement an emergency stop

contracts/security/PullPayment.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./escrow/Escrow.sol";
+import "../utils/escrow/Escrow.sol";
 
 /**
  * @dev Simple implementation of a

contracts/security/README.adoc

@@ -0,0 +1,20 @@
+= Security
+
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/security
+
+These contracts aim to cover common security practices.
+
+* {PullPayment}: A pattern that can be used to avoid reentrancy attacks.
+* {ReentrancyGuard}: A modifier that can prevent reentrancy during certain functions.
+* {Pausable}: A common emergency response mechanism that can pause functionality while a remediation is pending.
+
+TIP: For an overview on reentrancy and the possible mechanisms to prevent it, read our article https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].
+
+== Contracts
+
+{{PullPayment}}
+
+{{ReentrancyGuard}}
+
+{{Pausable}}

contracts/token/ERC1155/ERC1155.sol

@@ -3,11 +3,11 @@
 pragma solidity ^0.8.0;
 
 import "./IERC1155.sol";
-import "./IERC1155MetadataURI.sol";
 import "./IERC1155Receiver.sol";
-import "../../utils/Context.sol";
-import "../../introspection/ERC165.sol";
+import "./extensions/IERC1155MetadataURI.sol";
 import "../../utils/Address.sol";
+import "../../utils/Context.sol";
+import "../../utils/introspection/ERC165.sol";
 
 /**
  *

contracts/token/ERC1155/IERC1155.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../../introspection/IERC165.sol";
+import "../../utils/introspection/IERC165.sol";
 
 /**
  * @dev Required interface of an ERC1155 compliant contract, as defined in the

contracts/token/ERC1155/IERC1155Receiver.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../../introspection/IERC165.sol";
+import "../../utils/introspection/IERC165.sol";
 
 /**
  * _Available since v3.1._

contracts/token/ERC1155/README.adoc

@@ -32,6 +32,12 @@ NOTE: This core set of contracts is designed to be unopinionated, allowing devel
 
 {{ERC1155Burnable}}
 
-== Convenience
+== Presets
+
+These contracts are preconfigured combinations of the above features. They can be used through inheritance or as models to copy and paste their source code.
+
+{{ERC1155PresetMinterPauser}}
+
+== Utilities
 
 {{ERC1155Holder}}

contracts/token/ERC1155/extensions/ERC1155Burnable.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./ERC1155.sol";
+import "../ERC1155.sol";
 
 /**
  * @dev Extension of {ERC1155} that allows token holders to destroy both their

contracts/token/ERC1155/extensions/ERC1155Pausable.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "./ERC1155.sol";
-import "../../utils/Pausable.sol";
+import "../ERC1155.sol";
+import "../../../security/Pausable.sol";
 
 /**
  * @dev ERC1155 token with pausable token transfers, minting and burning.

contracts/token/ERC1155/extensions/IERC1155MetadataURI.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./IERC1155.sol";
+import "../IERC1155.sol";
 
 /**
  * @dev Interface of the optional ERC1155MetadataExtension interface, as defined

contracts/token/ERC1155/presets/ERC1155PresetMinterPauser.sol

@@ -2,11 +2,11 @@
 
 pragma solidity ^0.8.0;
 
-import "../access/AccessControlEnumerable.sol";
-import "../utils/Context.sol";
-import "../token/ERC1155/ERC1155.sol";
-import "../token/ERC1155/ERC1155Burnable.sol";
-import "../token/ERC1155/ERC1155Pausable.sol";
+import "../ERC1155.sol";
+import "../extensions/ERC1155Burnable.sol";
+import "../extensions/ERC1155Pausable.sol";
+import "../../../access/AccessControlEnumerable.sol";
+import "../../../utils/Context.sol";
 
 /**
  * @dev {ERC1155} token, including:

contracts/token/ERC1155/utils/ERC1155Receiver.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "./IERC1155Receiver.sol";
-import "../../introspection/ERC165.sol";
+import "../IERC1155Receiver.sol";
+import "../../../utils/introspection/ERC165.sol";
 
 /**
  * @dev _Available since v3.1._

contracts/token/ERC20/ERC20.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "../../utils/Context.sol";
 import "./IERC20.sol";
+import "../../utils/Context.sol";
 
 /**
  * @dev Implementation of the {IERC20} interface.

contracts/token/ERC20/README.adoc

@@ -48,6 +48,22 @@ NOTE: This core set of contracts is designed to be unopinionated, allowing devel
 
 {{ERC20Capped}}
 
+== Draft EIPs
+
+The following EIPs are still in Draft status. Due to their nature as drafts, the details of these contracts may change and we cannot guarantee their xref:ROOT:releases-stability.adoc[stability]. Minor releases of OpenZeppelin Contracts may contain breaking changes for the contracts in this directory, which will be duly announced in the https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/CHANGELOG.md[changelog]. The EIPs included here are used by projects in production and this may make them less likely to change significantly.
+
+{{IERC20Permit}}
+
+{{ERC20Permit}}
+
+== Presets
+
+These contracts are preconfigured combinations of the above features. They can be used through inheritance or as models to copy and paste their source code.
+
+{{ERC20PresetMinterPauser}}
+
+{{ERC20PresetFixedSupply}}
+
 == Utilities
 
 {{SafeERC20}}

contracts/token/ERC20/extensions/ERC20Burnable.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "../../utils/Context.sol";
-import "./ERC20.sol";
+import "../ERC20.sol";
+import "../../../utils/Context.sol";
 
 /**
  * @dev Extension of {ERC20} that allows token holders to destroy both their own

contracts/token/ERC20/extensions/ERC20Capped.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./ERC20.sol";
+import "../ERC20.sol";
 
 /**
  * @dev Extension of {ERC20} that adds a cap to the supply of tokens.

contracts/token/ERC20/extensions/ERC20Pausable.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "./ERC20.sol";
-import "../../utils/Pausable.sol";
+import "../ERC20.sol";
+import "../../../security/Pausable.sol";
 
 /**
  * @dev ERC20 token with pausable token transfers, minting and burning.

contracts/token/ERC20/extensions/ERC20Snapshot.sol

@@ -2,9 +2,9 @@
 
 pragma solidity ^0.8.0;
 
-import "../../utils/Arrays.sol";
-import "../../utils/Counters.sol";
-import "./ERC20.sol";
+import "../ERC20.sol";
+import "../../../utils/Arrays.sol";
+import "../../../utils/Counters.sol";
 
 /**
  * @dev This contract extends an ERC20 token with a snapshot mechanism. When a snapshot is created, the balances and

contracts/token/ERC20/extensions/draft-ERC20Permit.sol

@@ -2,11 +2,11 @@
 
 pragma solidity ^0.8.0;
 
-import "../token/ERC20/ERC20.sol";
-import "./IERC20Permit.sol";
-import "../cryptography/ECDSA.sol";
-import "../utils/Counters.sol";
-import "./EIP712.sol";
+import "./draft-IERC20Permit.sol";
+import "../ERC20.sol";
+import "../../../utils/cryptography/draft-EIP712.sol";
+import "../../../utils/cryptography/ECDSA.sol";
+import "../../../utils/Counters.sol";
 
 /**
  * @dev Implementation of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in

contracts/token/ERC20/presets/ERC20PresetFixedSupply.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-import "../token/ERC20/ERC20Burnable.sol";
+import "../extensions/ERC20Burnable.sol";
 
 /**
  * @dev {ERC20} token, including:

contracts/token/ERC20/presets/ERC20PresetMinterPauser.sol

@@ -2,11 +2,11 @@
 
 pragma solidity ^0.8.0;
 
-import "../access/AccessControlEnumerable.sol";
-import "../utils/Context.sol";
-import "../token/ERC20/ERC20.sol";
-import "../token/ERC20/ERC20Burnable.sol";
-import "../token/ERC20/ERC20Pausable.sol";
+import "../ERC20.sol";
+import "../extensions/ERC20Burnable.sol";
+import "../extensions/ERC20Pausable.sol";
+import "../../../access/AccessControlEnumerable.sol";
+import "../../../utils/Context.sol";
 
 /**
  * @dev {ERC20} token, including:

contracts/token/ERC20/utils/SafeERC20.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "./IERC20.sol";
-import "../../utils/Address.sol";
+import "../IERC20.sol";
+import "../../../utils/Address.sol";
 
 /**
  * @title SafeERC20

contracts/token/ERC721/ERC721.sol

@@ -2,13 +2,14 @@
 
 pragma solidity ^0.8.0;
 
-import "../../utils/Context.sol";
 import "./IERC721.sol";
-import "./IERC721Metadata.sol";
 import "./IERC721Receiver.sol";
-import "../../introspection/ERC165.sol";
+import "./extensions/IERC721Metadata.sol";
+import "./extensions/IERC721Enumerable.sol";
 import "../../utils/Address.sol";
+import "../../utils/Context.sol";
 import "../../utils/Strings.sol";
+import "../../utils/introspection/ERC165.sol";
 
 /**
  * @dev Implementation of https://eips.ethereum.org/EIPS/eip-721[ERC721] Non-Fungible Token Standard, including

contracts/token/ERC721/IERC721.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../../introspection/IERC165.sol";
+import "../../utils/introspection/IERC165.sol";
 
 /**
  * @dev Required interface of an ERC721 compliant contract.

contracts/token/ERC721/README.adoc

@@ -39,6 +39,12 @@ NOTE: This core set of contracts is designed to be unopinionated, allowing devel
 
 {{ERC721Burnable}}
 
-== Convenience
+== Presets
+
+These contracts are preconfigured combinations of the above features. They can be used through inheritance or as models to copy and paste their source code.
+
+{{ERC721PresetMinterPauserAutoId}}
+
+== Utilities
 
 {{ERC721Holder}}

contracts/token/ERC721/extensions/ERC721Burnable.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "../../utils/Context.sol";
-import "./ERC721.sol";
+import "../ERC721.sol";
+import "../../../utils/Context.sol";
 
 /**
  * @title ERC721 Burnable Token

contracts/token/ERC721/extensions/ERC721Enumerable.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./ERC721.sol";
+import "../ERC721.sol";
 import "./IERC721Enumerable.sol";
 
 /**

contracts/token/ERC721/extensions/ERC721Pausable.sol

@@ -2,8 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import "./ERC721.sol";
-import "../../utils/Pausable.sol";
+import "../ERC721.sol";
+import "../../../security/Pausable.sol";
 
 /**
  * @dev ERC721 token with pausable token transfers, minting and burning.

contracts/token/ERC721/extensions/IERC721Enumerable.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./IERC721.sol";
+import "../IERC721.sol";
 
 /**
  * @title ERC-721 Non-Fungible Token Standard, optional enumeration extension

contracts/token/ERC721/extensions/IERC721Metadata.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./IERC721.sol";
+import "../IERC721.sol";
 
 /**
  * @title ERC-721 Non-Fungible Token Standard, optional metadata extension

contracts/token/ERC721/presets/ERC721PresetMinterPauserAutoId.sol

@@ -2,13 +2,13 @@
 
 pragma solidity ^0.8.0;
 
-import "../access/AccessControlEnumerable.sol";
-import "../utils/Context.sol";
-import "../utils/Counters.sol";
-import "../token/ERC721/ERC721.sol";
-import "../token/ERC721/ERC721Enumerable.sol";
-import "../token/ERC721/ERC721Burnable.sol";
-import "../token/ERC721/ERC721Pausable.sol";
+import "../ERC721.sol";
+import "../extensions/ERC721Enumerable.sol";
+import "../extensions/ERC721Burnable.sol";
+import "../extensions/ERC721Pausable.sol";
+import "../../../access/AccessControlEnumerable.sol";
+import "../../../utils/Context.sol";
+import "../../../utils/Counters.sol";
 
 /**
  * @dev {ERC721} token, including:

contracts/token/ERC721/utils/ERC721Holder.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "./IERC721Receiver.sol";
+import "../IERC721Receiver.sol";
 
   /**
    * @dev Implementation of the {IERC721Receiver} interface.

contracts/token/ERC777/ERC777.sol

@@ -2,13 +2,13 @@
 
 pragma solidity ^0.8.0;
 
-import "../../utils/Context.sol";
 import "./IERC777.sol";
 import "./IERC777Recipient.sol";
 import "./IERC777Sender.sol";
-import "../../token/ERC20/IERC20.sol";
+import "../ERC20/IERC20.sol";
 import "../../utils/Address.sol";
-import "../../introspection/IERC1820Registry.sol";
+import "../../utils/Context.sol";
+import "../../utils/introspection/IERC1820Registry.sol";
 
 /**
  * @dev Implementation of the {IERC777} interface.

contracts/token/ERC777/README.adoc

@@ -22,3 +22,9 @@ Additionally there are interfaces used to develop contracts that react to token
 {{IERC777Sender}}
 
 {{IERC777Recipient}}
+
+== Presets
+
+These contracts are preconfigured combinations of features. They can be used through inheritance or as models to copy and paste their source code.
+
+{{ERC777PresetFixedSupply}}

contracts/token/ERC777/presets/ERC777PresetFixedSupply.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-import "../token/ERC777/ERC777.sol";
+import "../ERC777.sol";
 
 /**
  * @dev {ERC777} token, including:

contracts/utils/Arrays.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.0;
 
-import "../math/Math.sol";
+import "./math/Math.sol";
 
 /**
  * @dev Collection of functions related to array types.

contracts/utils/Initializable.sol

@@ -3,7 +3,7 @@
 // solhint-disable-next-line compiler-version
 pragma solidity ^0.8.0;
 
-import "../utils/Address.sol";
+import "./Address.sol";
 
 /**
  * @dev This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed

contracts/utils/PaymentSplitter.sol

@@ -2,9 +2,9 @@
 
 pragma solidity ^0.8.0;
 
-import "../utils/Context.sol";
-import "../math/SafeMath.sol";
-import "../utils/Address.sol";
+import "./Address.sol";
+import "./Context.sol";
+import "./math/SafeMath.sol";
 
 /**
  * @title PaymentSplitter

contracts/utils/README.adoc

@@ -5,11 +5,6 @@ NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/
 
 Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives.
 
-Security tools include:
-
- * {Pausable}: provides a simple way to halt activity in your contracts (often in response to an external threat).
- * {ReentrancyGuard}: protects you from https://blog.openzeppelin.com/reentrancy-after-istanbul/[reentrant calls].
-
 The {Address}, {Arrays} and {Strings} libraries provide more operations related to these native data types, while {SafeCast} adds ways to safely convert between the different signed and unsigned numeric types.
 
 For new data types:
@@ -27,26 +22,69 @@ As of v3.0, {EnumerableMap} supports `uint256 -> address` (`UintToAddressMap`),
 
 Finally, {Create2} contains all necessary utilities to safely use the https://blog.openzeppelin.com/getting-the-most-out-of-create2/[`CREATE2` EVM opcode], without having to deal with low-level assembly.
 
-== Contracts
+== Math
 
-{{Pausable}}
+{{Math}}
 
-{{ReentrancyGuard}}
+{{SafeCast}}
+
+{{SafeMath}}
+
+{{SignedSafeMath}}
+
+== Cryptography
+
+{{ECDSA}}
+
+{{MerkleProof}}
+
+{{EIP712}}
+
+== Introspection
+
+This set of interfaces and contracts deal with https://en.wikipedia.org/wiki/Type_introspection[type introspection] of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_.
+
+Ethereum contracts have no native concept of an interface, so applications must usually simply trust they are not making an incorrect call. For trusted setups this is a non-issue, but often unknown and untrusted third-party addresses need to be interacted with. There may even not be any direct calls to them! (e.g. `ERC20` tokens may be sent to a contract that lacks a way to transfer them out of it, locking them forever). In these cases, a contract _declaring_ its interface can be very helpful in preventing errors.
+
+There are two main ways to approach this.
+
+* Locally, where a contract implements `IERC165` and declares an interface, and a second one queries it directly via `ERC165Checker`.
+* Globally, where a global and unique registry (`IERC1820Registry`) is used to register implementers of a certain interface (`IERC1820Implementer`). It is then the registry that is queried, which allows for more complex setups, like contracts implementing interfaces for externally-owned accounts.
+
+Note that, in all cases, accounts simply _declare_ their interfaces, but they are not required to actually implement them. This mechanism can therefore be used to both prevent errors and allow for complex interactions (see `ERC777`), but it must not be relied on for security.
+
+{{IERC165}}
+
+{{ERC165}}
+
+{{ERC165Storage}}
+
+{{ERC165Checker}}
+
+{{IERC1820Registry}}
+
+{{IERC1820Implementer}}
+
+{{ERC1820Implementer}}
+
+== Data Structures
+
+{{EnumerableMap}}
+
+{{EnumerableSet}}
 
 == Libraries
 
+{{Create2}}
+
 {{Address}}
 
 {{Arrays}}
 
 {{Counters}}
 
-{{Create2}}
-
-{{EnumerableMap}}
-
-{{EnumerableSet}}
-
-{{SafeCast}}
-
 {{Strings}}
+
+== Other
+
+{{Initializable}}

contracts/utils/cryptography/ECDSA.sol

@@ -47,7 +47,7 @@ library ECDSA {
     }
 
     /**
-     * @dev Overload of {ECDSA-recover-bytes32-bytes-} that receives the `v`,
+     * @dev Overload of {ECDSA-recover} that receives the `v`,
      * `r` and `s` signature fields separately.
      */
     function recover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) internal pure returns (address) {