Release v5.0.0 (rc) (#4614)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

.changeset/afraid-walls-smell.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC1155Receiver`: Removed in favor of `ERC1155Holder`.

.changeset/angry-ties-switch.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`TimelockController`: Changed the role architecture to use `DEFAULT_ADMIN_ROLE` as the admin for all roles, instead of the bespoke `TIMELOCK_ADMIN_ROLE` that was used previously. This aligns with the general recommendation for `AccessControl` and makes the addition of new roles easier. Accordingly, the `admin` parameter and timelock will now be granted `DEFAULT_ADMIN_ROLE` instead of `TIMELOCK_ADMIN_ROLE`. ([#3799](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3799))

.changeset/big-plums-cover.md

@@ -0,0 +1,4 @@
+---
+'openzeppelin-solidity': major
+---
+Use `abi.encodeCall` in place of `abi.encodeWithSelector` and `abi.encodeWithSignature` for improved type-checking of parameters

.changeset/blue-horses-do.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC2771Forwarder`: Added `deadline` for expiring transactions, batching, and more secure handling of `msg.value`.

.changeset/blue-scissors-design.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Math`: Make `ceilDiv` to revert on 0 division even if the numerator is 0

.changeset/brave-lobsters-punch.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Governor`: Refactored internals to implement common queuing logic in the core module of the Governor. Added `queue` and `_queueOperations` functions that act at different levels. Modules that implement queuing via timelocks are expected to override `_queueOperations` to implement the timelock-specific logic. Added `_executeOperations` as the equivalent for execution.

.changeset/bright-tomatoes-sing.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC20`, `ERC721`, `ERC1155`: Deleted `_beforeTokenTransfer` and `_afterTokenTransfer` hooks, added a new internal `_update` function for customizations, and refactored all extensions using those hooks to use `_update` instead. ([#3838](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3838), [#3876](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3876), [#4377](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4377))

.changeset/chilled-spiders-attack.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC1155Supply`: add a `totalSupply()` function that returns the total amount of token circulating, this change will restrict the total tokens minted across all ids to 2\*\*256-1 .

.changeset/clever-bats-kick.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`Ownable`: Prevent using address(0) as the initial owner.

.changeset/clever-pumas-beg.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Ownable`: Add an `initialOwner` parameter to the constructor, making the ownership initialization explicit.

.changeset/config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "OpenZeppelin/openzeppelin-contracts"
+    }
+  ],
+  "commit": false,
+  "access": "public",
+  "baseBranch": "master"
+}

.changeset/eight-peaches-guess.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Proxy`: Removed redundant `receive` function.

.changeset/eighty-crabs-listen.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+Optimize `Strings.equal`

.changeset/eighty-lemons-shake.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC721`: `_approve` no longer allows approving the owner of the tokenId. `_setApprovalForAll` no longer allows setting address(0) as an operator.

.changeset/empty-cheetahs-hunt.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC721URIStorage`: Allow setting the token URI prior to minting.

.changeset/empty-taxis-kiss.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`UUPSUpgradeable`, `TransparentUpgradeableProxy` and `ProxyAdmin`: Removed `upgradeTo` and `upgrade` functions, and made `upgradeToAndCall` and `upgradeAndCall` ignore the data argument if it is empty. It is no longer possible to invoke the receive function (or send value with empty data) along with an upgrade.

.changeset/fair-humans-peel.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC721URIStorage`, `ERC721Royalty`: Stop resetting token-specific URI and royalties when burning.

.changeset/fifty-owls-retire.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Address`: Removed the ability to customize error messages. A common custom error is always used if the underlying revert reason cannot be bubbled up.

.changeset/flat-bottles-wonder.md

@@ -0,0 +1,7 @@
+---
+'openzeppelin-solidity': minor
+---
+
+Replace some uses of `abi.encodePacked` with clearer alternatives (e.g. `bytes.concat`, `string.concat`). (#4504)[https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4504]
+
+pr: #4296

.changeset/fluffy-countries-buy.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Arrays`: Optimize `findUpperBound` by removing redundant SLOAD.

.changeset/four-adults-knock.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`ECDSA`: Use unchecked arithmetic for the `tryRecover` function that receives the `r` and `vs` short-signature fields separately.

.changeset/fresh-birds-kiss.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Checkpoints`: library moved from `utils` to `utils/structs`

.changeset/green-pumpkins-end.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`SafeERC20`: Removed `safePermit` in favor of documentation-only `permit` recommendations.

.changeset/grumpy-bulldogs-call.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Governor`: Optimized use of storage for proposal data

.changeset/grumpy-worms-tease.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC1967Utils`: Refactor the `ERC1967Upgrade` abstract contract as a library.

.changeset/happy-falcons-walk.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`TransparentUpgradeableProxy`: Admin is now stored in an immutable variable (set during construction) to avoid unnecessary storage reads on every proxy call. This removed the ability to ever change the admin. Transfer of the upgrade capability is exclusively handled through the ownership of the `ProxyAdmin`.

.changeset/healthy-gorillas-applaud.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`VestingWallet`: Use `Ownable` instead of an immutable `beneficiary`.

.changeset/heavy-drinks-fail.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC20`: Remove `Approval` event previously emitted in `transferFrom` to indicate that part of the allowance was consumed. With this change, allowances are no longer reconstructible from events. See the code for guidelines on how to re-enable this event if needed.

.changeset/hip-beds-provide.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+Move the logic to validate ERC-1822 during an upgrade from `ERC1967Utils` to `UUPSUpgradeable`.

.changeset/hip-goats-fail.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`VestingWallet`: Fix revert during 1 second time window when duration is 0.

.changeset/hot-coins-judge.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Arrays`: Add `unsafeMemoryAccess` helpers to read from a memory array without checking the length.

.changeset/hot-dingos-kiss.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`MessageHashUtils`: Add a new library for creating message digest to be used along with signing or recovery such as  ECDSA or ERC-1271. These functions are moved from the `ECDSA` library.

.changeset/hot-plums-approve.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`GovernorTimelockControl`: Clean up timelock id on execution for gas refund.

.changeset/large-humans-remain.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`MerkleProof`: Use custom error to report invalid multiproof instead of reverting with overflow panic.

.changeset/lazy-rice-joke.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Initializable`: Use intermediate variables to improve readability.

.changeset/little-falcons-build.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`EIP712`: Add internal getters for the name and version strings

.changeset/loud-shrimps-play.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`TimelockController`: Add a state getter that returns an `OperationState` enum.

.changeset/lovely-geckos-hide.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+Replace revert strings and require statements with custom errors.

.changeset/mean-walls-watch.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Nonces`: Added a new contract to keep track of user nonces. Used for signatures in `ERC20Permit`, `ERC20Votes`, and `ERC721Votes`. ([#3816](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3816))

.changeset/mighty-donuts-smile.md

@@ -0,0 +1,6 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`Governor`: Add validation in ERC1155 and ERC721 receiver hooks to ensure Governor is the executor.
+

.changeset/orange-apes-draw.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+Switched to using explicit Solidity import statements. Some previously available symbols may now have to be separately imported.

.changeset/pink-suns-mix.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`Math`: Optimized stack operations in `mulDiv`.

.changeset/popular-deers-raise.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Governor`: Add support for casting votes with ERC-1271 signatures by using a `bytes memory signature` instead of `r`, `s` and `v` arguments in the `castVoteBySig` and `castVoteWithReasonAndParamsBySig` functions.

.changeset/pre.json

@@ -0,0 +1,85 @@
+{
+  "mode": "pre",
+  "tag": "rc",
+  "initialVersions": {
+    "openzeppelin-solidity": "4.9.2"
+  },
+  "changesets": [
+    "afraid-walls-smell",
+    "angry-ties-switch",
+    "big-plums-cover",
+    "blue-horses-do",
+    "blue-scissors-design",
+    "brave-lobsters-punch",
+    "bright-tomatoes-sing",
+    "chilled-spiders-attack",
+    "clever-bats-kick",
+    "clever-pumas-beg",
+    "eight-peaches-guess",
+    "eighty-crabs-listen",
+    "eighty-lemons-shake",
+    "empty-cheetahs-hunt",
+    "empty-taxis-kiss",
+    "fair-humans-peel",
+    "fifty-owls-retire",
+    "flat-bottles-wonder",
+    "fluffy-countries-buy",
+    "four-adults-knock",
+    "fresh-birds-kiss",
+    "green-pumpkins-end",
+    "grumpy-bulldogs-call",
+    "grumpy-worms-tease",
+    "happy-falcons-walk",
+    "healthy-gorillas-applaud",
+    "heavy-drinks-fail",
+    "hip-beds-provide",
+    "hip-goats-fail",
+    "hot-coins-judge",
+    "hot-dingos-kiss",
+    "hot-plums-approve",
+    "large-humans-remain",
+    "lazy-rice-joke",
+    "little-falcons-build",
+    "loud-shrimps-play",
+    "lovely-geckos-hide",
+    "mean-walls-watch",
+    "mighty-donuts-smile",
+    "orange-apes-draw",
+    "pink-suns-mix",
+    "popular-deers-raise",
+    "proud-seals-complain",
+    "proud-spiders-attend",
+    "purple-cats-cheer",
+    "quiet-trainers-kick",
+    "red-dots-fold",
+    "rotten-insects-wash",
+    "serious-books-lie",
+    "short-eels-enjoy",
+    "silly-bees-beam",
+    "six-frogs-turn",
+    "sixty-numbers-reply",
+    "slimy-penguins-attack",
+    "smooth-books-wink",
+    "smooth-cougars-jump",
+    "spicy-sheep-eat",
+    "spotty-hotels-type",
+    "strong-poems-thank",
+    "swift-bags-divide",
+    "swift-numbers-cry",
+    "tasty-tomatoes-turn",
+    "tender-shirts-turn",
+    "thick-pumpkins-exercise",
+    "thin-camels-matter",
+    "tough-drinks-hammer",
+    "two-wasps-punch",
+    "unlucky-beans-obey",
+    "violet-dancers-cough",
+    "violet-melons-press",
+    "warm-guests-rule",
+    "wet-bears-heal",
+    "wild-beds-visit",
+    "wild-peas-remain",
+    "wild-rockets-rush",
+    "wild-windows-trade"
+  ]
+}

.changeset/proud-seals-complain.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`BeaconProxy`: Use an immutable variable to store the address of the beacon. It is no longer possible for a `BeaconProxy` to upgrade by changing to another beacon.

.changeset/proud-spiders-attend.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC721`: Renamed `_requireMinted` to `_requireOwned` and added a return value with the current owner. Implemented `ownerOf` in terms of `_requireOwned`.

.changeset/purple-cats-cheer.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`GovernorTimelockControl`: Add the Governor instance address as part of the TimelockController operation `salt` to avoid operation id collisions between governors using the same TimelockController.

.changeset/quiet-trainers-kick.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AccessManager`: Added a new contract for managing access control of complex systems in a consolidated location.

.changeset/red-dots-fold.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+Overrides are now used internally for a number of functions that were previously hardcoded to their default implementation in certain locations: `ERC1155Supply.totalSupply`, `ERC721.ownerOf`, `ERC721.balanceOf` and `ERC721.totalSupply` in `ERC721Enumerable`, `ERC20.totalSupply` in `ERC20FlashMint`, and `ERC1967._getImplementation` in `ERC1967Proxy`.

.changeset/rotten-insects-wash.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ProxyAdmin`: Removed `getProxyAdmin` and `getProxyImplementation` getters. ([#3820](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3820))

.changeset/serious-books-lie.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`ERC1155`: Optimize array allocation.

.changeset/short-eels-enjoy.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+Bump minimum compiler version required to 0.8.20

.changeset/silly-bees-beam.md

@@ -0,0 +1,7 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC20Votes`: Changed internal vote accounting to reusable `Votes` module previously used by `ERC721Votes`. Removed implicit `ERC20Permit` inheritance. Note that the `DOMAIN_SEPARATOR` getter was previously guaranteed to be available for `ERC20Votes` contracts, but is no longer available unless `ERC20Permit` is explicitly used; ERC-5267 support is included in `ERC20Votes` with `EIP712` and is recommended as an alternative.
+
+pr: #3816

.changeset/six-frogs-turn.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC20`: Remove the non-standard `increaseAllowance` and `decreaseAllowance` functions.

.changeset/sixty-numbers-reply.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Governor`: Add `voter` and `nonce` parameters in signed ballots, to avoid forging signatures for random addresses, prevent signature replay, and allow invalidating signatures. Add `voter` as a new parameter in the `castVoteBySig` and `castVoteWithReasonAndParamsBySig` functions.

.changeset/slimy-penguins-attack.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`TransparentUpgradeableProxy`: Removed `admin` and `implementation` getters, which were only callable by the proxy owner and thus not very useful. ([#3820](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3820))

.changeset/smooth-books-wink.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ERC1155`: Remove check for address zero in `balanceOf`.

.changeset/smooth-cougars-jump.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`ReentrancyGuard`, `Pausable`: Moved to `utils` directory.

.changeset/spicy-sheep-eat.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`access`: Move `AccessControl` extensions to a dedicated directory.

.changeset/spotty-hotels-type.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`ERC721Consecutive`: Add a `_firstConsecutiveId` internal function that can be overridden to change the id of the first token minted through `_mintConsecutive`.

.changeset/strong-poems-thank.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`DoubleEndedQueue`: refactor internal structure to use `uint128` instead of `int128`. This has no effect on the library interface.

.changeset/swift-bags-divide.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`Governor`: Add a mechanism to restrict the address of the proposer using a suffix in the description.

.changeset/swift-numbers-cry.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Governor`, `Initializable`, and `UUPSUpgradeable`: Use internal functions in modifiers to optimize bytecode size.

.changeset/tasty-tomatoes-turn.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Strings`: Rename `toString(int256)` to `toStringSigned(int256)`.

.changeset/tender-shirts-turn.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`BeaconProxy`: Reject value in initialization unless a payable function is explicitly invoked.

.changeset/thick-pumpkins-exercise.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Initializable`: Use the namespaced storage pattern to avoid putting critical variables in slot 0. Allow reinitializer versions greater than 256.

.changeset/thin-camels-matter.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC1155`: Bubble errors triggered in the `onERC1155Received` and `onERC1155BatchReceived` hooks.

.changeset/tough-drinks-hammer.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`ERC1155`: Optimize array accesses by skipping bounds checking when unnecessary.

.changeset/two-wasps-punch.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AccessControl`: Add a boolean return value to the internal `_grantRole` and `_revokeRole` functions indicating whether the role was granted or revoked.

.changeset/unlucky-beans-obey.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`ERC2771Context`: Return the forwarder address whenever the `msg.data` of a call originating from a trusted forwarder is not long enough to contain the request signer address (i.e. `msg.data.length` is less than 20 bytes), as specified by ERC-2771.

.changeset/violet-dancers-cough.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+Remove the `override` specifier from functions that only override a single interface function.

.changeset/violet-melons-press.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`GovernorTimelockAccess`: Added a module to connect a governor with an instance of `AccessManager`, allowing the governor to make calls that are delay-restricted by the manager using the normal `queue` workflow.

.changeset/warm-guests-rule.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`ERC2771Context`: Prevent revert in `_msgData()` when a call originating from a trusted forwarder is not long enough to contain the request signer address (i.e. `msg.data.length` is less than 20 bytes). Return the full calldata in that case.

.changeset/wet-bears-heal.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+Upgradeable contracts now use namespaced storage (EIP-7201).

.changeset/wild-beds-visit.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`GovernorStorage`: Added a new governor extension that stores the proposal details in storage, with an interface that operates on `proposalId`, as well as proposal enumerability. This replaces the old `GovernorCompatibilityBravo` module.

.changeset/wild-peas-remain.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Votes`: Use Trace208 for checkpoints. This enables EIP-6372 clock support for keys but reduces the max supported voting power to uint208.

.changeset/wild-rockets-rush.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`Math`: Renamed members of `Rounding` enum, and added a new rounding mode for "away from zero".

.changeset/wild-windows-trade.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': major
+---
+
+`SafeERC20`: Refactor `safeDecreaseAllowance` and `safeIncreaseAllowance` to support USDT-like tokens.

.eslintrc

@@ -1,62 +1,20 @@
 {
+  "root": true,
   "extends" : [
-    "standard"
-  ],
-  "plugins": [
-    "mocha"
+    "eslint:recommended",
+    "prettier",
   ],
   "env": {
-    "browser" : true,
-    "node"    : true,
-    "mocha"   : true,
-    "jest"    : true,
+    "es2022": true,
+    "browser": true,
+    "node": true,
+    "mocha": true,
   },
   "globals" : {
-    "artifacts": false,
-    "contract": false,
-    "assert": false,
-    "web3": false,
-    "usePlugin": false,
-    "extendEnvironment": false,
-  },
-  "rules": {
-
-    // Strict mode
-    "strict": ["error", "global"],
-
-    // Code style
-    "array-bracket-spacing": ["off"],
-    "camelcase": ["error", {"properties": "always"}],
-    "comma-dangle": ["error", "always-multiline"],
-    "comma-spacing": ["error", {"before": false, "after": true}],
-    "dot-notation": ["error", {"allowKeywords": true, "allowPattern": ""}],
-    "eol-last": ["error", "always"],
-    "eqeqeq": ["error", "smart"],
-    "generator-star-spacing": ["error", "before"],
-    "indent": ["error", 2],
-    "linebreak-style": ["error", "unix"],
-    "max-len": ["error", 120, 2],
-    "no-debugger": "off",
-    "no-dupe-args": "error",
-    "no-dupe-keys": "error",
-    "no-mixed-spaces-and-tabs": ["error", "smart-tabs"],
-    "no-redeclare": ["error", {"builtinGlobals": true}],
-    "no-trailing-spaces": ["error", { "skipBlankLines": false }],
-    "no-undef": "error",
-    "no-use-before-define": "off",
-    "no-var": "error",
-    "object-curly-spacing": ["error", "always"],
-    "prefer-const": "error",
-    "quotes": ["error", "single"],
-    "semi": ["error", "always"],
-    "space-before-function-paren": ["error", "always"],
-
-    "mocha/no-exclusive-tests": ["error"],
-
-    "promise/always-return": "off",
-    "promise/avoid-new": "off",
-  },
-  "parserOptions": {
-    "ecmaVersion": 2020
+    "artifacts": "readonly",
+    "contract": "readonly",
+    "web3": "readonly",
+    "extendEnvironment": "readonly",
+    "expect": "readonly",
   }
 }

.gitattributes

@@ -1 +0,0 @@
-*.sol linguist-language=Solidity

.github/PULL_REQUEST_TEMPLATE.md

@@ -17,4 +17,4 @@ Fixes #???? <!-- Fill in with issue number -->
 
 - [ ] Tests
 - [ ] Documentation
-- [ ] Changelog entry
+- [ ] Changeset entry (run `npx changeset add`)

.github/actions/setup/action.yml

@@ -5,15 +5,14 @@ runs:
   steps:
     - uses: actions/setup-node@v3
       with:
-        node-version: 14.x
-        cache: npm
+        node-version: 16.x
     - uses: actions/cache@v3
       id: cache
       with:
         path: '**/node_modules'
         key: npm-v3-${{ hashFiles('**/package-lock.json') }}
     - name: Install dependencies
-      run: npm ci --prefer-offline
+      run: npm ci
       shell: bash
       if: steps.cache.outputs.cache-hit != 'true'
       env:

.github/actions/storage-layout/action.yml

@@ -0,0 +1,55 @@
+name: Compare storage layouts
+inputs:
+  token:
+    description: github token
+    required: true
+  buildinfo:
+    description: compilation artifacts
+    required: false
+    default: artifacts/build-info/*.json
+  layout:
+    description: extracted storage layout
+    required: false
+    default: HEAD.layout.json
+  out_layout:
+    description: storage layout to upload
+    required: false
+    default: ${{ github.ref_name }}.layout.json
+  ref_layout:
+    description: storage layout for the reference branch
+    required: false
+    default: ${{ github.base_ref }}.layout.json
+
+runs:
+  using: composite
+  steps:
+    - name: Extract layout
+      run: |
+        node scripts/checks/extract-layout.js ${{ inputs.buildinfo }} > ${{ inputs.layout }}
+      shell: bash
+    - name: Download reference
+      if: github.event_name == 'pull_request'
+      run: |
+        RUN_ID=`gh run list --repo ${{ github.repository }} --branch ${{ github.base_ref }} --workflow ${{ github.workflow }} --limit 100 --json 'conclusion,databaseId,event' --jq 'map(select(.conclusion=="success" and .event!="pull_request"))[0].databaseId'`
+        gh run download ${RUN_ID} --repo ${{ github.repository }} -n layout
+      env:
+        GITHUB_TOKEN: ${{ inputs.token }}
+      shell: bash
+      continue-on-error: true
+      id: reference
+    - name: Compare layouts
+      if: steps.reference.outcome == 'success' && github.event_name == 'pull_request'
+      run: |
+        node scripts/checks/compare-layout.js --head ${{ inputs.layout }} --ref ${{ inputs.ref_layout }}
+      shell: bash
+    - name: Rename artifacts for upload
+      if: github.event_name != 'pull_request'
+      run: |
+        mv ${{ inputs.layout }} ${{ inputs.out_layout }}
+      shell: bash
+    - name: Save artifacts
+      if: github.event_name != 'pull_request'
+      uses: actions/upload-artifact@v3
+      with:
+        name: layout
+        path: ${{ inputs.out_layout }}

.github/workflows/actionlint.yml

@@ -0,0 +1,18 @@
+name: lint workflows
+
+on:
+  pull_request:
+    paths:
+      - '.github/**/*.ya?ml'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Add problem matchers
+        run: |
+          # https://github.com/rhysd/actionlint/blob/3a2f2c7/docs/usage.md#problem-matchers
+          curl -LO https://raw.githubusercontent.com/rhysd/actionlint/main/.github/actionlint-matcher.json
+          echo "::add-matcher::actionlint-matcher.json"
+      - uses: docker://rhysd/actionlint:latest

.github/workflows/changelog.yml

@@ -1,28 +0,0 @@
-name: changelog
-
-on:
-  pull_request:
-    types:
-      - opened
-      - synchronize
-      - labeled
-      - unlabeled
-
-concurrency:
-  group: changelog-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    if: ${{ !contains(github.event.pull_request.labels.*.name, 'ignore-changelog') }}
-    steps:
-      - uses: actions/checkout@v3
-      - name: Check diff
-        run: |
-          git fetch origin ${{ github.base_ref }} --depth=1
-          if git diff --exit-code origin/${{ github.base_ref }} -- CHANGELOG.md ; then
-            echo 'Missing changelog entry'
-            exit 1
-          fi
-

.github/workflows/changeset.yml

@@ -0,0 +1,28 @@
+name: changeset
+
+on:
+  pull_request:
+    branches:
+      - master
+    types:
+      - opened
+      - synchronize
+      - labeled
+      - unlabeled
+
+concurrency:
+  group: changeset-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'ignore-changeset') }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Include history so Changesets finds merge-base
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - name: Check changeset
+        run: npx changeset status --since=origin/${{ github.base_ref }}

.github/workflows/checks.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - master
+      - next-v*
       - release-v*
   pull_request: {}
   workflow_dispatch: {}
@@ -12,12 +13,14 @@ concurrency:
   group: checks-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  NODE_OPTIONS: --max_old_space_size=5120
+
 jobs:
   lint:
-    if: github.repository != 'OpenZeppelin/openzeppelin-contracts-upgradeable'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up environment
         uses: ./.github/actions/setup
       - run: npm run lint
@@ -28,7 +31,7 @@ jobs:
       FORCE_COLOR: 1
       GAS: true
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Run tests and generate gas report
@@ -36,18 +39,40 @@ jobs:
       - name: Check linearisation of the inheritance graph
         run: npm run test:inheritance
       - name: Check proceduraly generated contracts are up-to-date
-        if: github.repository != 'OpenZeppelin/openzeppelin-contracts-upgradeable'
         run: npm run test:generation
       - name: Compare gas costs
         uses: ./.github/actions/gas-compare
+        if: github.base_ref == 'master'
         with:
           token: ${{ github.token }}
 
-  foundry-tests:
-    if: github.repository != 'OpenZeppelin/openzeppelin-contracts-upgradeable'
+  tests-upgradeable:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_COLOR: 1
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Include history so patch conflicts are resolved automatically
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - name: Transpile to upgradeable
+        run: bash scripts/upgradeable/transpile.sh
+      - name: Run tests
+        run: npm run test
+      - name: Check linearisation of the inheritance graph
+        run: npm run test:inheritance
+      - name: Check storage layout
+        uses: ./.github/actions/storage-layout
+        if: github.base_ref == 'master'
+        continue-on-error: ${{ contains(github.event.pull_request.labels.*.name, 'breaking change') }}
+        with:
+          token: ${{ github.token }}
+
+  tests-foundry:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: recursive
       - name: Install Foundry
@@ -58,33 +83,34 @@ jobs:
         run: forge test -vv
 
   coverage:
-    if: github.repository != 'OpenZeppelin/openzeppelin-contracts-upgradeable'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up environment
         uses: ./.github/actions/setup
       - run: npm run coverage
-        env:
-          NODE_OPTIONS: --max_old_space_size=4096
       - uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
 
   slither:
-    if: github.repository != 'OpenZeppelin/openzeppelin-contracts-upgradeable'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up environment
         uses: ./.github/actions/setup
-      - uses: crytic/slither-action@v0.1.1
+      - run: rm foundry.toml
+      - uses: crytic/slither-action@v0.3.0
+        with:
+          node-version: 18.15
 
   codespell:
-    if: github.repository != 'OpenZeppelin/openzeppelin-contracts-upgradeable'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Run CodeSpell
-        uses: codespell-project/actions-codespell@v1.0
+        uses: codespell-project/actions-codespell@v2.0
         with:
+          check_hidden: true
           check_filenames: true
-          skip: package-lock.json
+          skip: package-lock.json,*.pdf

.github/workflows/docs.yml

@@ -4,11 +4,14 @@ on:
   push:
     branches: [release-v*]
 
+permissions:
+  contents: write
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up environment
         uses: ./.github/actions/setup
       - run: bash scripts/git-user-config.sh

.github/workflows/formal-verification.yml

@@ -0,0 +1,68 @@
+name: formal verification
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - labeled
+  workflow_dispatch: {}
+
+env:
+  PIP_VERSION: '3.10'
+  JAVA_VERSION: '11'
+  SOLC_VERSION: '0.8.20'
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  apply-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Apply patches
+        run: make -C certora apply
+
+  verify:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'formal-verification')
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - name: identify specs that need to be run
+        id: arguments
+        run: |
+          if [[ ${{ github.event_name }} = 'pull_request' ]];
+          then
+            RESULT=$(git diff ${{ github.event.pull_request.head.sha }}..${{ github.event.pull_request.base.sha }} --name-only certora/specs/*.spec | while IFS= read -r file; do [[ -f $file ]] && basename "${file%.spec}"; done | tr "\n" " ")
+          else
+            RESULT='--all'
+          fi
+          echo "result=$RESULT" >> "$GITHUB_OUTPUT"
+      - name: Install python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PIP_VERSION }}
+          cache: 'pip'
+      - name: Install python packages
+        run: pip install -r requirements.txt
+      - name: Install java
+        uses: actions/setup-java@v3
+        with:
+          distribution: temurin
+          java-version: ${{ env.JAVA_VERSION }}
+      - name: Install solc
+        run: |
+          wget https://github.com/ethereum/solidity/releases/download/v${{ env.SOLC_VERSION }}/solc-static-linux
+          sudo mv solc-static-linux /usr/local/bin/solc
+          chmod +x /usr/local/bin/solc
+      - name: Verify specification
+        run: |
+          make -C certora apply
+          node certora/run.js ${{ steps.arguments.outputs.result }} >> "$GITHUB_STEP_SUMMARY"
+        env:
+          CERTORAKEY: ${{ secrets.CERTORAKEY }}

.github/workflows/release-cycle.yml

@@ -0,0 +1,218 @@
+#  D: Manual Dispatch
+#  M: Merge release PR
+#  C: Commit
+#  ┌───────────┐     ┌─────────────┐     ┌────────────────┐
+#  │Development├──D──►RC-Unreleased│  ┌──►Final-Unreleased│
+#  └───────────┘     └─┬─────────▲─┘  │  └─┬────────────▲─┘
+#                      │         │    │    │            │
+#                      M         C    D    M            C
+#                      │         │    │    │            │
+#                     ┌▼─────────┴┐   │   ┌▼────────────┴┐
+#                     │RC-Released├───┘   │Final-Released│
+#                     └───────────┘       └──────────────┘
+name: Release Cycle
+
+on:
+  push:
+    branches:
+      - release-v*
+  workflow_dispatch: {}
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  state:
+    name: Check state
+    permissions:
+      pull-requests: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - id: state
+        name: Get state
+        uses: actions/github-script@v6
+        env:
+          TRIGGERING_ACTOR: ${{ github.triggering_actor }}
+        with:
+          result-encoding: string
+          script: await require('./scripts/release/workflow/state.js')({ github, context, core })
+    outputs:
+      # Job Flags
+      start: ${{ steps.state.outputs.start }}
+      changesets: ${{ steps.state.outputs.changesets }}
+      promote: ${{ steps.state.outputs.promote }}
+      publish: ${{ steps.state.outputs.publish }}
+      merge: ${{ steps.state.outputs.merge }}
+
+      # Global variables
+      is_prerelease: ${{ steps.state.outputs.is_prerelease }}
+
+  start:
+    needs: state
+    name: Start new release candidate
+    permissions:
+      contents: write
+      actions: write
+    if: needs.state.outputs.start == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - run: bash scripts/git-user-config.sh
+      - id: start
+        name: Create branch with release candidate
+        run: bash scripts/release/workflow/start.sh
+      - name: Re-run workflow
+        uses: actions/github-script@v6
+        env:
+          REF: ${{ steps.start.outputs.branch }}
+        with:
+          script: await require('./scripts/release/workflow/rerun.js')({ github, context })
+
+  promote:
+    needs: state
+    name: Promote to final release
+    permissions:
+      contents: write
+      actions: write
+    if: needs.state.outputs.promote == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - run: bash scripts/git-user-config.sh
+      - name: Exit prerelease state
+        if: needs.state.outputs.is_prerelease == 'true'
+        run: bash scripts/release/workflow/exit-prerelease.sh
+      - name: Re-run workflow
+        uses: actions/github-script@v6
+        with:
+          script: await require('./scripts/release/workflow/rerun.js')({ github, context })
+
+  changesets:
+    needs: state
+    name: Update PR to release
+    permissions:
+      contents: write
+      pull-requests: write
+    if: needs.state.outputs.changesets == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # To get all tags
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - name: Set release title
+        uses: actions/github-script@v6
+        with:
+          result-encoding: string
+          script: await require('./scripts/release/workflow/set-changesets-pr-title.js')({ core })
+      - name: Create PR
+        uses: changesets/action@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PRERELEASE: ${{ needs.state.outputs.is_prerelease }}
+        with:
+          version: npm run version
+          title: ${{ env.TITLE }}
+          commit: ${{ env.TITLE }}
+          body: | # Wait for support on this https://github.com/changesets/action/pull/250
+            This is an automated PR for releasing ${{ github.repository }}
+            Check [CHANGELOG.md](${{ github.repository }}/CHANGELOG.md)
+
+  publish:
+    needs: state
+    name: Publish to npm
+    environment: npm
+    permissions:
+      contents: write
+    if: needs.state.outputs.publish == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - id: pack
+        name: Pack
+        run: bash scripts/release/workflow/pack.sh
+        env:
+          PRERELEASE: ${{ needs.state.outputs.is_prerelease }}
+      - name: Upload tarball artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ github.ref_name }}
+          path: ${{ steps.pack.outputs.tarball }}
+      - name: Tag
+        run: npx changeset tag
+      - name: Publish
+        run: bash scripts/release/workflow/publish.sh
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          TARBALL: ${{ steps.pack.outputs.tarball }}
+          TAG: ${{ steps.pack.outputs.tag }}
+      - name: Push tags
+        run: git push --tags
+      - name: Create Github Release
+        uses: actions/github-script@v6
+        env:
+          PRERELEASE: ${{ needs.state.outputs.is_prerelease }}
+        with:
+          script: await require('./scripts/release/workflow/github-release.js')({ github, context })
+    outputs:
+      tarball_name: ${{ steps.pack.outputs.tarball_name }}
+
+  integrity_check:
+    needs: publish
+    name: Tarball Integrity Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download tarball artifact
+        id: artifact
+        # Replace with actions/upload-artifact@v3 when
+        # https://github.com/actions/download-artifact/pull/194 gets released
+        uses: actions/download-artifact@e9ef242655d12993efdcda9058dee2db83a2cb9b
+        with:
+          name: ${{ github.ref_name }}
+      - name: Check integrity
+        run: bash scripts/release/workflow/integrity-check.sh
+        env:
+          TARBALL: ${{ steps.artifact.outputs.download-path }}/${{ needs.publish.outputs.tarball_name }}
+
+  merge:
+    needs: state
+    name: Create PR back to master
+    permissions:
+      contents: write
+      pull-requests: write
+    if: needs.state.outputs.merge == 'true'
+    runs-on: ubuntu-latest
+    env:
+      MERGE_BRANCH: merge/${{ github.ref_name }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # All branches
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - run: bash scripts/git-user-config.sh
+      - name: Create branch to merge
+        run: |
+          git checkout -B "$MERGE_BRANCH" "$GITHUB_REF_NAME"
+          git push -f origin "$MERGE_BRANCH"
+      - name: Create PR back to master
+        uses: actions/github-script@v6
+        with:
+          script: |
+            await github.rest.pulls.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              head: process.env.MERGE_BRANCH,
+              base: 'master',
+              title: '${{ format('Merge {0} branch', github.ref_name) }}'
+            });

.github/workflows/upgradeable.yml

@@ -1,4 +1,4 @@
-name: Upgradeable Trigger
+name: transpile upgradeable
 
 on:
   push:
@@ -7,17 +7,24 @@ on:
       - release-v*
 
 jobs:
-  trigger:
+  transpile:
+    environment: push-upgradeable
     runs-on: ubuntu-latest
     steps:
-      - id: app
-        uses: getsentry/action-github-app-token@v1
+      - uses: actions/checkout@v4
         with:
-          app_id: ${{ secrets.UPGRADEABLE_APP_ID }}
-          private_key: ${{ secrets.UPGRADEABLE_APP_PK }}
-      - run: |
-          curl -X POST \
-            https://api.github.com/repos/OpenZeppelin/openzeppelin-contracts-upgradeable/dispatches \
-            -H 'Accept: application/vnd.github.v3+json' \
-            -H 'Authorization: token ${{ steps.app.outputs.token }}' \
-            -d '{ "event_type": "Update", "client_payload": { "ref": "${{ github.ref }}" } }'
+          repository: OpenZeppelin/openzeppelin-contracts-upgradeable
+          fetch-depth: 0
+          token: ${{ secrets.GH_TOKEN_UPGRADEABLE }}
+      - name: Fetch current non-upgradeable branch
+        run: |
+          git fetch "https://github.com/${{ github.repository }}.git" "$REF"
+          git checkout FETCH_HEAD
+        env:
+          REF: ${{ github.ref }}
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - run: bash scripts/git-user-config.sh
+      - name: Transpile to upgradeable
+        run: bash scripts/upgradeable/transpile-onto.sh ${{ github.ref_name }} origin/${{ github.ref_name }}
+      - run: git push origin ${{ github.ref_name }}

.gitignore

@@ -54,11 +54,18 @@ allFiredEvents
 .coverage_cache
 .coverage_contracts
 
-# hardhat
-cache
-artifacts
+# hardat-exposed
+contracts-exposed
+
+# Hardhat
+/cache
+/artifacts
+
+# Foundry
+/out
 
 # Certora
 .certora*
 .last_confs
 certora_*
+.zip-output-url.txt

.gitmodules

@@ -1,3 +1,7 @@
 [submodule "lib/forge-std"]
+	branch = v1
 	path = lib/forge-std
 	url = https://github.com/foundry-rs/forge-std
+[submodule "lib/erc4626-tests"]
+	path = lib/erc4626-tests
+	url = https://github.com/a16z/erc4626-tests.git

.prettierrc

@@ -1,14 +1,15 @@
 {
+  "printWidth": 120,
   "singleQuote": true,
   "trailingComma": "all",
+  "arrowParens": "avoid",
   "overrides": [
     {
       "files": "*.sol",
       "options": {
-        "singleQuote": false,
-        "printWidth": 120,
-        "explicitTypes": "always"
+        "singleQuote": false
       }
     }
-  ]
+  ],
+  "plugins": ["prettier-plugin-solidity"]
 }

.solcover.js

@@ -1,15 +1,13 @@
 module.exports = {
-    norpc: true,
-    testCommand: 'npm test',
-    compileCommand: 'npm run compile',
-    skipFiles: [
-        'mocks',
-    ],
-    providerOptions: {
-        default_balance_ether: '10000000000000000000000000',
-    },
-    mocha: {
-        fgrep: '[skip-on-coverage]',
-        invert: true,
-    },
-}
+  norpc: true,
+  testCommand: 'npm test',
+  compileCommand: 'npm run compile',
+  skipFiles: ['mocks'],
+  providerOptions: {
+    default_balance_ether: '10000000000000000000000000',
+  },
+  mocha: {
+    fgrep: '[skip-on-coverage]',
+    invert: true,
+  },
+};

.solhint.json

@@ -1,14 +0,0 @@
-{
-  "rules": {
-    "no-unused-vars": "error",
-    "const-name-snakecase": "error",
-    "contract-name-camelcase": "error",
-    "event-name-camelcase": "error",
-    "func-name-mixedcase": "error",
-    "func-param-name-mixedcase": "error",
-    "modifier-name-mixedcase": "error",
-    "private-vars-leading-underscore": "error",
-    "var-name-mixedcase": "error",
-    "imports-on-top": "error"
-  }
-}

CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at maintainers@openzeppelin.org. All
+reported by contacting the project team at contact@openzeppelin.com. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

CONTRIBUTING.md

@@ -1,64 +1,36 @@
-Contributing to OpenZeppelin Contracts
-=======
+# Contributing Guidelines
 
-We really appreciate and value contributions to OpenZeppelin Contracts. Please take 5' to review the items listed below to make sure that your contributions are merged as soon as possible.
+There are many ways to contribute to OpenZeppelin Contracts.
 
-## Contribution guidelines
+## Troubleshooting
 
-Smart contracts manage value and are highly vulnerable to errors and attacks. We have very strict [guidelines], please make sure to review them!
+You can help other users in the community to solve their smart contract issues in the [OpenZeppelin Forum].
 
-## Creating Pull Requests (PRs)
+[OpenZeppelin Forum]: https://forum.openzeppelin.com/
 
-As a contributor, you are expected to fork this repository, work on your own fork and then submit pull requests. The pull requests will be reviewed and eventually merged into the main repo. See ["Fork-a-Repo"](https://help.github.com/articles/fork-a-repo/) for how this works.
+## Opening an issue
 
-## A typical workflow
+You can [open an issue] to suggest a feature or report a minor bug. For serious bugs please do not open an issue, instead refer to our [security policy] for appropriate steps.
 
-1) Make sure your fork is up to date with the main repository:
+If you believe your issue may be due to user error and not a problem in the library, consider instead posting a question on the [OpenZeppelin Forum].
 
-```
-cd openzeppelin-contracts
-git remote add upstream https://github.com/OpenZeppelin/openzeppelin-contracts.git
-git fetch upstream
-git pull --rebase upstream master
-```
-NOTE: The directory `openzeppelin-contracts` represents your fork's local copy.
+Before opening an issue, be sure to search through the existing open and closed issues, and consider posting a comment in one of those instead.
 
-2) Branch out from `master` into `fix/some-bug-#123`:
-(Postfixing #123 will associate your PR with the issue #123 and make everyone's life easier =D)
-```
-git checkout -b fix/some-bug-#123
-```
+When requesting a new feature, include as many details as you can, especially around the use cases that motivate it. Features are prioritized according to the impact they may have on the ecosystem, so we appreciate information showing that the impact could be high.
 
-3) Make your changes, add your files, commit, and push to your fork.
+[security policy]: https://github.com/OpenZeppelin/openzeppelin-contracts/security
+[open an issue]: https://github.com/OpenZeppelin/openzeppelin-contracts/issues/new/choose
 
-```
-git add SomeFile.js
-git commit "Fix some bug #123"
-git push origin fix/some-bug-#123
-```
+## Submitting a pull request
 
-4) Run tests, linter, etc. This can be done by running local continuous integration and make sure it passes.
+If you would like to contribute code or documentation you may do so by forking the repository and submitting a pull request.
 
-```bash
-npm test
-npm run lint
-```
+Any non-trivial code contribution must be first discussed with the maintainers in an issue (see [Opening an issue](#opening-an-issue)). Only very minor changes are accepted without prior discussion.
 
-5) Go to [github.com/OpenZeppelin/openzeppelin-contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) in your web browser and issue a new pull request.
+Make sure to read and follow the [engineering guidelines](./GUIDELINES.md). Run linter and tests to make sure your pull request is good before submitting it.
 
-*IMPORTANT* Read the PR template very carefully and make sure to follow all the instructions. These instructions
-refer to some very important conditions that your PR must meet in order to be accepted, such as making sure that all tests pass, JS linting tests pass, Solidity linting tests pass, etc.
+Changelog entries should be added to each pull request by using [Changesets](https://github.com/changesets/changesets/).
 
-6) Maintainers will review your code and possibly ask for changes before your code is pulled in to the main repository. We'll check that all tests pass, review the coding style, and check for general code correctness. If everything is OK, we'll merge your pull request and your code will be part of OpenZeppelin Contracts.
+When opening the pull request you will be presented with a template and a series of instructions. Read through it carefully and follow all the steps. Expect a review and feedback from the maintainers afterwards.
 
-*IMPORTANT* Please pay attention to the maintainer's feedback, since it's a necessary step to keep up with the standards OpenZeppelin Contracts attains to.
-
-## All set!
-
-If you have any questions, feel free to post them to github.com/OpenZeppelin/openzeppelin-contracts/issues.
-
-Finally, if you're looking to collaborate and want to find easy tasks to start, look at the issues we marked as ["Good first issue"](https://github.com/OpenZeppelin/openzeppelin-contracts/labels/good%20first%20issue).
-
-Thanks for your time and code!
-
-[guidelines]: GUIDELINES.md
+If you're looking for a good place to start, look for issues labelled ["good first issue"](https://github.com/OpenZeppelin/openzeppelin-contracts/labels/good%20first%20issue)!

GUIDELINES.md

@@ -1,105 +1,148 @@
-Design Guidelines
-=======
+# Engineering Guidelines
 
-These are some global design goals in OpenZeppelin Contracts.
+## Testing
 
-#### D0 - Security in Depth
-We strive to provide secure, tested, audited code. To achieve this, we need to match intention with function. Thus, documentation, code clarity, community review and security discussions are fundamental.
+Code must be thoroughly tested with quality unit tests.
 
-#### D1 - Simple and Modular
-Simpler code means easier audits, and better understanding of what each component does. We look for small files, small contracts, and small functions. If you can separate a contract into two independent functionalities you should probably do it.
+We defer to the [Moloch Testing Guide](https://github.com/MolochVentures/moloch/tree/master/test#readme) for specific recommendations, though not all of it is relevant here. Note the introduction:
 
-#### D2 - Naming Matters
+> Tests should be written, not only to verify correctness of the target code, but to be comprehensively reviewed by other programmers. Therefore, for mission critical Solidity code, the quality of the tests are just as important (if not more so) than the code itself, and should be written with the highest standards of clarity and elegance.
 
-We take our time with picking names. Code is going to be written once, and read hundreds of times. Renaming for clarity is encouraged.
+Every addition or change to the code must come with relevant and comprehensive tests.
 
-#### D3 - Tests
+Refactors should avoid simultaneous changes to tests.
 
-Write tests for all your code. We encourage Test Driven Development so we know when our code is right. Even though not all code in the repository is tested at the moment, we aim to test every line of code in the future.
+Flaky tests are not acceptable.
 
-#### D4 - Check preconditions and post-conditions
+The test suite should run automatically for every change in the repository, and in pull requests tests must pass before merging.
 
-A very important way to prevent vulnerabilities is to catch a contract’s inconsistent state as early as possible. This is why we want functions to check pre- and post-conditions for executing its logic. When writing code, ask yourself what you are expecting to be true before and after the function runs, and express it in code.
+The test suite coverage must be kept as close to 100% as possible, enforced in pull requests.
 
-#### D5 - Code Consistency
+In some cases unit tests may be insufficient and complementary techniques should be used:
 
-Consistency on the way classes are used is paramount to an easier understanding of the library. The codebase should be as unified as possible. Read existing code and get inspired before you write your own. Follow the style guidelines. Don’t hesitate to ask for help on how to best write a specific piece of code.
+1. Property-based tests (aka. fuzzing) for math-heavy code.
+2. Formal verification for state machines.
 
-#### D6 - Regular Audits
-Following good programming practices is a way to reduce the risk of vulnerabilities, but professional code audits are still needed. We will perform regular code audits on major releases, and hire security professionals to provide independent review.
+## Code style
 
-# Style Guidelines
+Solidity code should be written in a consistent format enforced by a linter, following the official [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html). See below for further [Solidity Conventions](#solidity-conventions).
 
-The design guidelines have quite a high abstraction level. These style guidelines are more concrete and easier to apply, and also more opinionated. We value clean code and consistency, and those are prerequisites for us to include new code in the repository. Before proposing a change, please read these guidelines and take some time to familiarize yourself with the style of the existing codebase.
+The code should be simple and straightforward, prioritizing readability and understandability. Consistency and predictability should be maintained across the codebase. In particular, this applies to naming, which should be systematic, clear, and concise.
 
-## Solidity code
+Sometimes these guidelines may be broken if doing so brings significant efficiency gains, but explanatory comments should be added.
 
-In order to be consistent with all the other Solidity projects, we follow the
-[official recommendations documented in the Solidity style guide](http://solidity.readthedocs.io/en/latest/style-guide.html).
+Modularity should be pursued, but not at the cost of the above priorities.
 
-Any exception or additions specific to our project are documented below.
+## Documentation
 
-* Try to avoid acronyms and abbreviations.
+For contributors, project guidelines and processes must be documented publicly.
+
+For users, features must be abundantly documented. Documentation should include answers to common questions, solutions to common problems, and recommendations for critical decisions that the user may face.
+
+All changes to the core codebase (excluding tests, auxiliary scripts, etc.) must be documented in a changelog, except for purely cosmetic or documentation changes.
+
+## Peer review
+
+All changes must be submitted through pull requests and go through peer code review.
+
+The review must be approached by the reviewer in a similar way as if it was an audit of the code in question (but importantly it is not a substitute for and should not be considered an audit).
+
+Reviewers should enforce code and project guidelines.
+
+External contributions must be reviewed separately by multiple maintainers.
+
+## Automation
+
+Automation should be used as much as possible to reduce the possibility of human error and forgetfulness.
+
+Automations that make use of sensitive credentials must use secure secret management, and must be strengthened against attacks such as [those on GitHub Actions worklows](https://github.com/nikitastupin/pwnhub).
+
+Some other examples of automation are:
+
+- Looking for common security vulnerabilities or errors in our code (eg. reentrancy analysis).
+- Keeping dependencies up to date and monitoring for vulnerable dependencies.
+
+## Pull requests
+
+Pull requests are squash-merged to keep the `master` branch history clean. The title of the pull request becomes the commit message, so it should be written in a consistent format:
+
+1) Begin with a capital letter.
+2) Do not end with a period.
+3) Write in the imperative: "Add feature X" and not "Adds feature X" or "Added feature X".
+
+This repository does not follow conventional commits, so do not prefix the title with "fix:" or "feat:".
+
+Work in progress pull requests should be submitted as Drafts and should not be prefixed with "WIP:".
+
+Branch names don't matter, and commit messages within a pull request mostly don't matter either, although they can help the review process.
+
+# Solidity Conventions
+
+In addition to the official Solidity Style Guide we have a number of other conventions that must be followed.
 
 * All state variables should be private.
 
-* Private state variables should have an underscore prefix.
+  Changes to state should be accompanied by events, and in some cases it is not correct to arbitrarily set state. Encapsulating variables as private and only allowing modification via setters enables us to ensure that events and other rules are followed reliably and prevents this kind of user error.
 
-    ```
-    contract TestContract {
+* Internal or private state variables or functions should have an underscore prefix.
+
+  ```solidity
+  contract TestContract {
       uint256 private _privateVar;
       uint256 internal _internalVar;
-    }
-    ```
+      function _testInternal() internal { ... }
+      function _testPrivate() private { ... }
+  }
+  ```
 
-* Parameters must not be prefixed with an underscore.
+* Functions should be declared virtual, with few exceptions listed below. The
+  contract logic should be written considering that these functions may be
+  overridden by developers, e.g. getting a value using an internal getter rather
+  than reading directly from a state variable.
 
-    ```
-    function test(uint256 testParameter1, uint256 testParameter2) {
-    ...
-    }
-    ```
+  If function A is an "alias" of function B, i.e. it invokes function B without
+  significant additional logic, then function A should not be virtual so that
+  any user overrides are implemented on B, preventing inconsistencies.
 
-* Internal and private functions should have an underscore prefix.
+* Events should generally be emitted immediately after the state change that they
+  represent, and should be named in the past tense. Some exceptions may be made for gas
+  efficiency if the result doesn't affect observable ordering of events.
 
-    ```
-    function _testInternal() internal {
-      ...
-    }
-    ```
-
-    ```
-    function _testPrivate() private {
-      ...
-    }
-    ```
-
-* Events should be emitted immediately after the state change that they
-  represent, and consequently they should be named in past tense.
-
-    ```
-    function _burn(address who, uint256 value) internal {
+  ```solidity
+  function _burn(address who, uint256 value) internal {
       super._burn(who, value);
       emit TokensBurned(who, value);
-    }
-    ```
+  }
+  ```
 
   Some standards (e.g. ERC20) use present tense, and in those cases the
-  standard specification prevails.
+  standard specification is used.
   
 * Interface names should have a capital I prefix.
 
-    ```
-    interface IERC777 {
-    ```
+  ```solidity
+  interface IERC777 {
+  ```
 
+* Contracts not intended to be used standalone should be marked abstract
+  so they are required to be inherited to other contracts.
 
-## Tests
+  ```solidity
+  abstract contract AccessControl is ..., {
+  ```
 
-* Tests Must be Written Elegantly
+* Unchecked arithmetic blocks should contain comments explaining why overflow is guaranteed not to happen. If the reason is immediately apparent from the line above the unchecked block, the comment may be omitted.
 
-    Tests are a good way to show how to use the library, and maintaining them is extremely necessary. Don't write long tests, write helper functions to make them be as short and concise as possible (they should take just a few lines each), and use good variable names.
+* Custom errors should be declared following the [EIP-6093](https://eips.ethereum.org/EIPS/eip-6093) rationale whenever reasonable. Also, consider the following:
+  
+  * The domain prefix should be picked in the following order:
+    1. Use `ERC<number>` if the error is a violation of an ERC specification.
+    2. Use the name of the underlying component where it belongs (eg. `Governor`, `ECDSA`, or `Timelock`).
 
-* Tests Must not be Random
+  * The location of custom errors should be decided in the following order:
+    1. Take the errors from their underlying ERCs if they're already defined.
+    2. Declare the errors in the underlying interface/library if the error makes sense in its context.
+    3. Declare the error in the implementation if the underlying interface/library is not suitable to do so (eg. interface/library already specified in an ERC).
+    4. Declare the error in an extension if the error only happens in such extension or child contracts.
 
-    Inputs for tests should not be generated randomly. Accounts used to create test contracts are an exception, those can be random. Also, the type and structure of outputs should be checked.
+  * Custom error names should not be declared twice along the library to avoid duplicated identifier declarations when inheriting from multiple contracts.