Release v5.1.0 (rc)

Co-authored-by: Ernesto García <ernestognw@gmail.com>
Co-authored-by: cairo <cairoeth@protonmail.com>

.changeset/chilled-walls-develop.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Clones`: Add version of `clone` and `cloneDeterministic` that support sending value at creation.

.changeset/chilly-humans-warn.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`ProxyAdmin`: Fixed documentation for `UPGRADE_INTERFACE_VERSION` getter.

.changeset/cold-cheetahs-check.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`CircularBuffer`: Add a data structure that stores the last `N` values pushed to it.

.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/cool-mangos-compare.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Math`: add an `invMod` function to get the modular multiplicative inverse of a number in Z/nZ.

.changeset/curvy-crabs-repeat.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`RSA`: Library to verify signatures according to RFC 8017 Signature Verification Operation

.changeset/dirty-cobras-smile.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Arrays`: add a `sort` functions for `address[]`, `bytes32[]` and `uint256[]` memory arrays.

.changeset/eight-eyes-burn.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`GovernorCountingFractional`: Add a governor counting module that allows distributing voting power amongst 3 options (For, Against, Abstain).

.changeset/eleven-planets-relax.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`TransparentUpgradeableProxy`: Make internal `_proxyAdmin()` getter have `view` visibility.

.changeset/flat-turtles-repeat.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Arrays`: deprecate `findUpperBound` in favor of the new `lowerBound`.

.changeset/fluffy-buses-jump.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Comparator`: A library of comparator functions, useful for customizing the behavior of the Heap structure.

.changeset/fluffy-steaks-exist.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`Create2`, `Clones`: Mask `computeAddress` and `cloneDeterministic` outputs to produce a clean value for an `address` type (i.e. only use 20 bytes)

.changeset/forty-dodos-visit.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Strings`: Added a utility function for converting an address to checksummed string.

.changeset/friendly-nails-push.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC1363`: Add implementation of the token payable standard allowing execution of contract code after transfers and approvals.

.changeset/gentle-bulldogs-turn.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`DoubleEndedQueue`: Custom errors replaced with native panic codes.

.changeset/gorgeous-badgers-vanish.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`SlotDerivation`: Add a library of methods for derivating common storage slots.

.changeset/great-pianos-work.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Heap`: A data structure that implements a heap-based priority queue.

.changeset/heavy-baboons-give.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Packing`: Added a new utility for packing, extracting and replacing bytesXX values.

.changeset/kind-planets-cough.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`StorageSlot`: Add primitives for operating on the transient storage space using a typed-slot representation.

.changeset/light-news-listen.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AccessManager`: Allow the `onlyAuthorized` modifier to restrict functions added to the manager.

.changeset/lucky-crews-eat.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Votes`: Set `_moveDelegateVotes` visibility to internal instead of private.

.changeset/nervous-eyes-teach.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Create2`: Bubbles up returndata from a deployed contract that reverted during construction.

.changeset/nervous-pans-grow.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+`SafeCast`: Add `toUint(bool)` for operating on `bool` values as `uint256`.

.changeset/nice-paws-pull.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`SafeERC20`: Add "relaxed" function for interacting with ERC-1363 functions in a way that is compatible with EOAs.

.changeset/odd-files-protect.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Hashes`: A library with commonly used hash functions.

.changeset/odd-lobsters-wash.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`P256`: Library for verification and public key recovery of P256 (aka secp256r1) signatures.

.changeset/poor-chefs-cheat.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC721Utils` and `ERC1155Utils`: Add reusable libraries with functions to perform acceptance checks on `IERC721Receiver` and `IERC1155Receiver` implementers.

.changeset/pre.json

@@ -0,0 +1,51 @@
+{
+  "mode": "pre",
+  "tag": "rc",
+  "initialVersions": {
+    "openzeppelin-solidity": "5.0.2"
+  },
+  "changesets": [
+    "chilled-walls-develop",
+    "chilly-humans-warn",
+    "cold-cheetahs-check",
+    "cool-mangos-compare",
+    "curvy-crabs-repeat",
+    "dirty-cobras-smile",
+    "eight-eyes-burn",
+    "eleven-planets-relax",
+    "flat-turtles-repeat",
+    "fluffy-buses-jump",
+    "fluffy-steaks-exist",
+    "forty-dodos-visit",
+    "friendly-nails-push",
+    "gentle-bulldogs-turn",
+    "gorgeous-badgers-vanish",
+    "great-pianos-work",
+    "heavy-baboons-give",
+    "kind-planets-cough",
+    "light-news-listen",
+    "lucky-crews-eat",
+    "nervous-eyes-teach",
+    "nervous-pans-grow",
+    "nice-paws-pull",
+    "odd-files-protect",
+    "odd-lobsters-wash",
+    "poor-chefs-cheat",
+    "serious-carrots-provide",
+    "shiny-poets-whisper",
+    "silver-swans-promise",
+    "smart-bugs-switch",
+    "spotty-falcons-explain",
+    "spotty-queens-own",
+    "strong-singers-talk",
+    "thick-pumpkins-report",
+    "thin-walls-drop",
+    "twenty-feet-grin",
+    "violet-moons-tell",
+    "warm-sheep-cover",
+    "wise-bobcats-speak",
+    "witty-chicken-smile",
+    "yellow-deers-walk",
+    "yellow-moles-hammer"
+  ]
+}

.changeset/serious-carrots-provide.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC20TemporaryApproval`: Add an ERC-20 extension that implements temporary approval using transient storage, based on ERC7674 (draft).

.changeset/shiny-poets-whisper.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Math`: Add `modExp` function that exposes the `EIP-198` precompile. Includes `uint256` and `bytes memory` versions.

.changeset/silver-swans-promise.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Panic`: Add a library for reverting with panic codes.

.changeset/smart-bugs-switch.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Math`: Custom errors replaced with native panic codes.

.changeset/spotty-falcons-explain.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Math`, `SignedMath`: Add a branchless `ternary` function that computes`cond ? a : b` in constant gas cost.

.changeset/spotty-queens-own.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`MerkleProof`: Add variations of `verify`, `processProof`, `multiProofVerify` and `processMultiProof` (and equivalent calldata version) with support for custom hashing functions.

.changeset/strong-singers-talk.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Errors`: New library of common custom errors.

.changeset/thick-pumpkins-report.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Arrays`: add new functions `lowerBound`, `upperBound`, `lowerBoundMemory` and `upperBoundMemory` for lookups in sorted arrays with potential duplicates.

.changeset/thin-walls-drop.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AccessManager`, `VestingWallet`, `TimelockController` and `ERC2771Forwarder`: Added a public `initializer` function in their corresponding upgradeable variants.

.changeset/twenty-feet-grin.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Base64`: Add `encodeURL` following section 5 of RFC4648 for URL encoding

.changeset/violet-moons-tell.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AccessControlEnumerable`: Add a `getRoleMembers` method to return all accounts that have `role`.

.changeset/warm-sheep-cover.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`MerkleTree`: A data structure that allows inserting elements into a merkle tree and updating its root hash.

.changeset/wise-bobcats-speak.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`VestingWalletCliff`: Add an extension of the `VestingWallet` contract with an added cliff.

.changeset/witty-chicken-smile.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ReentrancyGuardTransient`: Added a variant of `ReentrancyGuard` that uses transient storage.

.changeset/yellow-deers-walk.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`EnumerableMap`: add `UintToBytes32Map`, `AddressToAddressMap`, `AddressToBytes32Map` and `Bytes32ToAddressMap`.

.changeset/yellow-moles-hammer.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`SignatureChecker`: refactor `isValidSignatureNow` to avoid validating ECDSA signatures if there is code deployed at the signer's address.

.codecov.yml

@@ -6,6 +6,10 @@ coverage:
     patch:
       default:
         target: 95%
+        only_pulls: true
     project:
       default:
         threshold: 1%
+ignore:
+  - "test"
+  - "contracts/mocks"

.editorconfig

@@ -17,5 +17,5 @@ indent_size = 4
 [*.js]
 indent_size = 2
 
-[*.adoc]
+[*.{adoc,md}]
 max_line_length = 0

.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": 2018
+    "artifacts": "readonly",
+    "contract": "readonly",
+    "web3": "readonly",
+    "extendEnvironment": "readonly",
+    "expect": "readonly",
   }
 }

.gitattributes

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

.githooks/pre-push

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [ "${CI:-"false"}" != "true" ]; then
+  npm run test:generation
+  npm run lint
+fi

.github/ISSUE_TEMPLATE/bug_report.md

@@ -10,7 +10,7 @@ about: Report a bug in OpenZeppelin Contracts
 
 **💻 Environment**
 
-<!-- Tell us what version of OpenZeppelin Contracts you're using, and how you're using it: Truffle, Remix, etc. -->
+<!-- Tell us what version of OpenZeppelin Contracts you're using, and how you're using it: Hardhat, Remix, etc. -->
 
 **📝 Details**
 

.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/gas-compare/action.yml

@@ -0,0 +1,50 @@
+name: Compare gas costs
+description: Compare gas costs between branches
+inputs:
+  token:
+    description: github token
+    required: true
+  report:
+    description: report to read from
+    required: false
+    default: gasReporterOutput.json
+  out_report:
+    description: report to read
+    required: false
+    default: ${{ github.ref_name }}.gasreport.json
+  ref_report:
+    description: report to read from
+    required: false
+    default: ${{ github.base_ref }}.gasreport.json
+
+runs:
+  using: composite
+  steps:
+    - name: Download reference report
+      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 gasreport
+      env:
+        GITHUB_TOKEN: ${{ inputs.token }}
+      shell: bash
+      continue-on-error: true
+      id: reference
+    - name: Compare reports
+      if: steps.reference.outcome == 'success' && github.event_name == 'pull_request'
+      run: |
+        node scripts/checks/compareGasReports.js ${{ inputs.report }} ${{ inputs.ref_report }} >> $GITHUB_STEP_SUMMARY
+      env:
+        STYLE: markdown
+      shell: bash
+    - name: Rename report for upload
+      if: github.event_name != 'pull_request'
+      run: |
+        mv ${{ inputs.report }} ${{ inputs.out_report }}
+      shell: bash
+    - name: Save report
+      if: github.event_name != 'pull_request'
+      uses: actions/upload-artifact@v3
+      with:
+        name: gasreport
+        path: ${{ inputs.out_report }}

.github/actions/setup/action.yml

@@ -1,20 +1,22 @@
 name: Setup
+description: Common environment setup
 
 runs:
   using: composite
   steps:
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with:
-        node-version: 14.x
-        cache: npm
-    - uses: actions/cache@v3
+        node-version: 20.x
+    - uses: actions/cache@v4
       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:
-        SKIP_COMPILE: true
+    - name: Install Foundry
+      uses: foundry-rs/foundry-toolchain@v1
+      with:
+        version: nightly

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

@@ -0,0 +1,56 @@
+name: Compare storage layouts
+description: Compare storage layouts between branches
+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/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,43 +13,120 @@ concurrency:
   group: checks-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  NODE_OPTIONS: --max_old_space_size=8192
+
 jobs:
   lint:
     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
 
   tests:
     runs-on: ubuntu-latest
+    env:
+      FORCE_COLOR: 1
+      # Needed for "eth-gas-reporter" to produce a "gasReporterOutput.json" as documented in
+      # https://github.com/cgewecke/eth-gas-reporter/blob/v0.2.27/docs/gasReporterOutput.md
+      CI: true
+      GAS: true
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up environment
         uses: ./.github/actions/setup
-      - run: npm run test
-        env:
-          FORCE_COLOR: 1
-          ENABLE_GAS_REPORT: true
-      - run: npm run test:inheritance
-      - run: npm run test:generation
+      - name: Run tests and generate gas report
+        run: npm run test
+      - name: Check linearisation of the inheritance graph
+        run: npm run test:inheritance
+      - name: Check proceduraly generated contracts are up-to-date
+        run: npm run test:generation
+      - name: Compare gas costs
+        uses: ./.github/actions/gas-compare
+        with:
+          token: ${{ github.token }}
+
+  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: Copy non-upgradeable contracts as dependency
+        run: |
+          mkdir -p lib/openzeppelin-contracts
+          cp -rnT contracts lib/openzeppelin-contracts/contracts
+      - 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
+        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@v4
+        with:
+          submodules: recursive
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - name: Run tests
+        run: forge test -vv
 
   coverage:
     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
+      - name: Run coverage
+        run: npm run coverage
+      - uses: codecov/codecov-action@v4
         env:
-          NODE_OPTIONS: --max_old_space_size=4096
-      - uses: codecov/codecov-action@v3
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  harnesses:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - name: Compile harnesses
+        run: |
+          make -C certora apply
+          npm run compile:harnesses
 
   slither:
     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.4.0
+        with:
+          node-version: 18.15
+          slither-version: 0.10.1
+
+  codespell:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run CodeSpell
+        uses: codespell-project/actions-codespell@v2.0
+        with:
+          check_hidden: true
+          check_filenames: true
+          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,86 @@
+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@v5
+        with:
+          python-version: ${{ env.PIP_VERSION }}
+          cache: 'pip'
+          cache-dependency-path: 'fv-requirements.txt'
+      - name: Install python packages
+        run: pip install -r fv-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 }}
+
+  halmos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - name: Install python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PIP_VERSION }}
+          cache: 'pip'
+          cache-dependency-path: 'fv-requirements.txt'
+      - name: Install python packages
+        run: pip install -r fv-requirements.txt
+      - name: Run Halmos
+        run: halmos --match-test '^symbolic|^testSymbolic' -vv

.github/workflows/release-cycle.yml

@@ -0,0 +1,212 @@
+#  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@v7
+        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@v7
+        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@v7
+        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@v7
+        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@v4
+        with:
+          name: ${{ github.ref_name }}
+          path: ${{ steps.pack.outputs.tarball }}
+      - 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: Create Github Release
+        uses: actions/github-script@v7
+        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
+        uses: actions/download-artifact@v4
+        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@v7
+        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,28 @@ 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 "$REMOTE" master # Fetch default branch first for patch to apply cleanly
+          git fetch "$REMOTE" "$REF"
+          git checkout FETCH_HEAD
+        env:
+          REF: ${{ github.ref }}
+          REMOTE: https://github.com/${{ github.repository }}.git
+      - 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 }}
+        env:
+          SUBMODULE_REMOTE: https://github.com/${{ github.repository }}.git
+      - run: git push origin ${{ github.ref_name }}

.gitignore

@@ -29,15 +29,9 @@ npm-debug.log
 # local env variables
 .env
 
-# truffle build directory
-build/
-
 # macOS
 .DS_Store
 
-# truffle
-.node-xmlhttprequest-*
-
 # IntelliJ IDE
 .idea
 
@@ -54,11 +48,19 @@ allFiredEvents
 .coverage_cache
 .coverage_contracts
 
-# hardhat
-cache
-artifacts
+# hardat-exposed
+contracts-exposed
+
+# Hardhat
+/cache
+/artifacts
+
+# Foundry
+/out
+/cache_forge
 
 # Certora
 .certora*
 .last_confs
 certora_*
+.zip-output-url.txt

.gitmodules

@@ -0,0 +1,10 @@
+[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
+[submodule "lib/halmos-cheatcodes"]
+	path = lib/halmos-cheatcodes
+	url = https://github.com/a16z/halmos-cheatcodes

.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

@@ -6,7 +6,7 @@ In the interest of fostering an open and welcoming environment, we as
 contributors and maintainers pledge to making participation in our project and
 our community a harassment-free experience for everyone, regardless of age, body
 size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
+level of experience, education, socioeconomic status, nationality, personal
 appearance, race, religion, or sexual identity and orientation.
 
 ## Our Standards
@@ -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)!

FUNDING.json

@@ -0,0 +1,7 @@
+{
+  "drips": {
+    "ethereum": {
+      "ownedBy": "0xAeb37910f93486C85A1F8F994b67E8187554d664"
+    }
+  }
+}

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.
+  Some standards (e.g. ERC-20) use present tense, and in those cases the
+  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.

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2022 zOS Global Limited and contributors
+Copyright (c) 2016-2024 Zeppelin Group Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -1,8 +1,10 @@
 # <img src="logo.svg" alt="OpenZeppelin" height="40px">
 
-[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-blue)](https://docs.openzeppelin.com/contracts)
 [![NPM Package](https://img.shields.io/npm/v/@openzeppelin/contracts.svg)](https://www.npmjs.org/package/@openzeppelin/contracts)
 [![Coverage Status](https://codecov.io/gh/OpenZeppelin/openzeppelin-contracts/graph/badge.svg)](https://codecov.io/gh/OpenZeppelin/openzeppelin-contracts)
+[![GitPOAPs](https://public-api.gitpoap.io/v1/repo/OpenZeppelin/openzeppelin-contracts/badge)](https://www.gitpoap.io/gh/OpenZeppelin/openzeppelin-contracts)
+[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-yellow)](https://docs.openzeppelin.com/contracts)
+[![Forum](https://img.shields.io/badge/forum-%F0%9F%92%AC-yellow)](https://docs.openzeppelin.com/contracts)
 
 **A library for secure smart contract development.** Build on a solid foundation of community-vetted code.
 
@@ -12,28 +14,43 @@
 
 :mage: **Not sure how to get started?** Check out [Contracts Wizard](https://wizard.openzeppelin.com/) — an interactive smart contract generator.
 
-:building_construction: **Want to scale your decentralized application?** Check out [OpenZeppelin Defender](https://openzeppelin.com/defender) — a secure platform for automating and monitoring your operations.
+:building_construction: **Want to scale your decentralized application?** Check out [OpenZeppelin Defender](https://openzeppelin.com/defender) — a mission-critical developer security platform to code, audit, deploy, monitor, and operate with confidence.
+
+> [!IMPORTANT]
+> OpenZeppelin Contracts uses semantic versioning to communicate backwards compatibility of its API and storage layout. For upgradeable contracts, the storage layout of different major versions should be assumed incompatible, for example, it is unsafe to upgrade from 4.9.3 to 5.0.0. Learn more at [Backwards Compatibility](https://docs.openzeppelin.com/contracts/backwards-compatibility).
 
 ## Overview
 
 ### Installation
 
-```console
+#### Hardhat (npm)
+
+```
 $ npm install @openzeppelin/contracts
 ```
 
-OpenZeppelin Contracts features a [stable API](https://docs.openzeppelin.com/contracts/releases-stability#api-stability), which means your contracts won't break unexpectedly when upgrading to a newer minor version.
+#### Foundry (git)
 
-An alternative to npm is to use the GitHub repository `openzeppelin/openzeppelin-contracts` to retrieve the contracts. When doing this, make sure to specify the tag for a release such as `v4.5.0`, instead of using the `master` branch.
+> [!WARNING]
+> When installing via git, it is a common error to use the `master` branch. This is a development branch that should be avoided in favor of tagged releases. The release process involves security measures that the `master` branch does not guarantee.
+
+> [!WARNING]
+> Foundry installs the latest version initially, but subsequent `forge update` commands will use the `master` branch.
+
+```
+$ forge install OpenZeppelin/openzeppelin-contracts
+```
+
+Add `@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/` in `remappings.txt.`
 
 ### Usage
 
 Once installed, you can use the contracts in the library by importing them:
 
 ```solidity
-pragma solidity ^0.8.0;
+pragma solidity ^0.8.20;
 
-import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
+import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
 
 contract MyCollectible is ERC721 {
     constructor() ERC721("MyCollectible", "MCO") {
@@ -43,20 +60,19 @@ contract MyCollectible is ERC721 {
 
 _If you're new to smart contract development, head to [Developing Smart Contracts](https://docs.openzeppelin.com/learn/developing-smart-contracts) to learn about creating a new project and compiling your contracts._
 
-To keep your system secure, you should **always** use the installed code as-is, and neither copy-paste it from online sources, nor modify it yourself. The library is designed so that only the contracts and functions you use are deployed, so you don't need to worry about it needlessly increasing gas costs.
+To keep your system secure, you should **always** use the installed code as-is, and neither copy-paste it from online sources nor modify it yourself. The library is designed so that only the contracts and functions you use are deployed, so you don't need to worry about it needlessly increasing gas costs.
 
 ## Learn More
 
-The guides in the [docs site](https://docs.openzeppelin.com/contracts) will teach about different concepts, and how to use the related contracts that OpenZeppelin Contracts provides:
+The guides in the [documentation site](https://docs.openzeppelin.com/contracts) will teach about different concepts, and how to use the related contracts that OpenZeppelin Contracts provides:
 
 * [Access Control](https://docs.openzeppelin.com/contracts/access-control): decide who can perform each of the actions on your system.
 * [Tokens](https://docs.openzeppelin.com/contracts/tokens): create tradeable assets or collectives, and distribute them via [Crowdsales](https://docs.openzeppelin.com/contracts/crowdsales).
-* [Gas Station Network](https://docs.openzeppelin.com/contracts/gsn): let your users interact with your contracts without having to pay for gas themselves.
-* [Utilities](https://docs.openzeppelin.com/contracts/utilities): generic useful tools, including non-overflowing math, signature verification, and trustless paying systems.
+* [Utilities](https://docs.openzeppelin.com/contracts/utilities): generic useful tools including non-overflowing math, signature verification, and trustless paying systems.
 
 The [full API](https://docs.openzeppelin.com/contracts/api/token/ERC20) is also thoroughly documented, and serves as a great reference when developing your smart contract application. You can also ask for help or follow Contracts's development in the [community forum](https://forum.openzeppelin.com).
 
-Finally, you may want to take a look at the [guides on our blog](https://blog.openzeppelin.com/guides), which cover several common use cases and good practices.. The following articles provide great background reading, though please note, some of the referenced tools have changed as the tooling in the ecosystem continues to rapidly evolve.
+Finally, you may want to take a look at the [guides on our blog](https://blog.openzeppelin.com/), which cover several common use cases and good practices. The following articles provide great background reading, though please note that some of the referenced tools have changed, as the tooling in the ecosystem continues to rapidly evolve.
 
 * [The Hitchhiker’s Guide to Smart Contracts in Ethereum](https://blog.openzeppelin.com/the-hitchhikers-guide-to-smart-contracts-in-ethereum-848f08001f05) will help you get an overview of the various tools available for smart contract development, and help you set up your environment.
 * [A Gentle Introduction to Ethereum Programming, Part 1](https://blog.openzeppelin.com/a-gentle-introduction-to-ethereum-programming-part-1-783cc7796094) provides very useful information on an introductory level, including many basic concepts from the Ethereum platform.
@@ -64,15 +80,19 @@ Finally, you may want to take a look at the [guides on our blog](https://blog.op
 
 ## Security
 
-This project is maintained by [OpenZeppelin](https://openzeppelin.com), and developed following our high standards for code quality and security. OpenZeppelin Contracts is meant to provide tested and community-audited code, but please use common sense when doing anything that deals with real money! We take no responsibility for your implementation decisions and any security problems you might experience.
+This project is maintained by [OpenZeppelin](https://openzeppelin.com) with the goal of providing a secure and reliable library of smart contract components for the ecosystem. We address security through risk management in various areas such as engineering and open source best practices, scoping and API design, multi-layered review processes, and incident response preparedness.
 
-The core development principles and strategies that OpenZeppelin Contracts is based on include: security in depth, simple and modular code, clarity-driven naming conventions, comprehensive unit testing, pre-and-post-condition sanity checks, code consistency, and regular audits.
+The [OpenZeppelin Contracts Security Center](https://contracts.openzeppelin.com/security) contains more details about the secure development process.
 
-The latest audit was done on October 2018 on version 2.0.0.
+The security policy is detailed in [`SECURITY.md`](./SECURITY.md) as well, and specifies how you can report security vulnerabilities, which versions will receive security patches, and how to stay informed about them. We run a [bug bounty program on Immunefi](https://immunefi.com/bounty/openzeppelin) to reward the responsible disclosure of vulnerabilities.
 
-We have a [**bug bounty program** on Immunefi](https://www.immunefi.com/bounty/openzeppelin). Please report any security issues you find through the Immunefi dashboard, or reach out to security@openzeppelin.com.
+The engineering guidelines we follow to promote project quality can be found in [`GUIDELINES.md`](./GUIDELINES.md).
 
-Critical bug fixes will be backported to past major releases.
+Past audits can be found in [`audits/`](./audits).
+
+Smart contracts are a nascent technology and carry a high level of technical risk and uncertainty. Although OpenZeppelin is well known for its security audits, using OpenZeppelin Contracts is not a substitute for a security audit.
+
+OpenZeppelin Contracts is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. As set out further in the Terms, you acknowledge that you are solely responsible for any use of OpenZeppelin Contracts and you assume all risks associated with any such use.
 
 ## Contribute
 
@@ -81,3 +101,7 @@ OpenZeppelin Contracts exists thanks to its contributors. There are many ways yo
 ## License
 
 OpenZeppelin Contracts is released under the [MIT License](LICENSE).
+
+## Legal
+
+Your use of this Project is governed by the terms found at www.openzeppelin.com/tos (the "Terms").

RELEASING.md

@@ -1,36 +1,45 @@
 # Releasing
 
-> Visit the documentation for [details about release schedule].
+OpenZeppelin Contracts uses a fully automated release process that takes care of compiling, packaging, and publishing the library, all of which is carried out in a clean CI environment (GitHub Actions), implemented in the ([`release-cycle`](.github/workflows/release-cycle.yml)) workflow. This helps to reduce the potential for human error and inconsistencies, and ensures that the release process is ongoing and reliable.
 
-Start on an up-to-date `master` branch.
+## Changesets
 
-Create the release branch with `npm run release start minor`.
+[Changesets](https://github.com/changesets/changesets/) is used as part of our release process for `CHANGELOG.md` management. Each change that is relevant for the codebase is expected to include a changeset.
 
-Publish a release candidate with `npm run release rc`.
+## Branching model
 
-Publish the final release with `npm run release final`.
+The release cycle happens on release branches called `release-vX.Y`. Each of these branches starts as a release candidate (rc) and is eventually promoted to final.
 
-Follow the general [OpenZeppelin Contracts release checklist].
+A release branch can be updated with cherry-picked patches from `master`, or may sometimes be committed to directly in the case of old releases. These commits will lead to a new release candidate or a patch increment depending on the state of the release branch.
 
-[details about release schedule]: https://docs.openzeppelin.com/contracts/releases-stability
-[OpenZeppelin Contracts release checklist]: https://github.com/OpenZeppelin/code-style/blob/master/RELEASE_CHECKLIST.md
+```mermaid
+  %%{init: {'gitGraph': {'mainBranchName': 'master'}} }%%
+  gitGraph
+    commit id: "Feature A"
+    commit id: "Feature B"
+    branch release-vX.Y
+    commit id: "Start release"
+    commit id: "Release vX.Y.0-rc.0"
 
+    checkout master
+    commit id: "Feature C"
+    commit id: "Fix A"
 
-## Merging the release branch
+    checkout release-vX.Y
+    cherry-pick id: "Fix A" tag: ""
+    commit id: "Release vX.Y.0-rc.1"
+    commit id: "Release vX.Y.0"
 
-After the final release, the release branch should be merged back into `master`. This merge must not be squashed because it would lose the tagged release commit. Since the GitHub repo is set up to only allow squashed merges, the merge should be done locally and pushed.
-
-Make sure to have the latest changes from `upstream` in your local release branch.
+    checkout master
+    merge release-vX.Y
+    commit id: "Feature D"
+    commit id: "Patch B"
 
+    checkout release-vX.Y
+    cherry-pick id: "Patch B" tag: ""
+    commit id: "Release vX.Y.1"
+    
+    checkout master
+    merge release-vX.Y
+    commit id: "Feature E"
 ```
-git checkout release-vX.Y.Z
-git pull upstream
-```
-
-```
-git checkout master
-git merge --no-ff release-vX.Y.Z
-git push upstream master
-```
-
-The release branch can then be deleted on GitHub.

SECURITY.md

@@ -1,20 +1,43 @@
 # Security Policy
 
+Security vulnerabilities should be disclosed to the project maintainers through [Immunefi], or alternatively by email to security@openzeppelin.com.
+
+[Immunefi]: https://immunefi.com/bounty/openzeppelin
+
 ## Bug Bounty
 
-We have a [**bug bounty program** on Immunefi](https://www.immunefi.com/bounty/openzeppelin). Please report any security issues you find through the Immunefi dashboard, or reach out to security@openzeppelin.com.
+Responsible disclosure of security vulnerabilities is rewarded through a bug bounty program on [Immunefi].
 
-Critical bug fixes will be backported to past major releases.
+There is a bonus reward for issues introduced in release candidates that are reported before making it into a stable release. Learn more about release candidates at [`RELEASING.md`](./RELEASING.md).
 
-## Supported Versions
+## Security Patches
 
-The recommendation is to use the latest version available.
+Security vulnerabilities will be patched as soon as responsibly possible, and published as an advisory on this repository (see [advisories]) and on the affected npm packages.
 
-| Version | Supported                            |
-| ------- | ------------------------------------ |
-| 4.x     | :white_check_mark::white_check_mark: |
-| 3.4     | :white_check_mark:                   |
-| 2.5     | :white_check_mark:                   |
-| < 2.0   | :x:                                  |
+[advisories]: https://github.com/OpenZeppelin/openzeppelin-contracts/security/advisories
 
-Note that the Solidity language itself only guarantees security updates for the latest release.
+Projects that build on OpenZeppelin Contracts are encouraged to clearly state, in their source code and websites, how to be contacted about security issues in the event that a direct notification is considered necessary. We recommend including it in the NatSpec for the contract as `/// @custom:security-contact security@example.com`.
+
+Additionally, we recommend installing the library through npm and setting up vulnerability alerts such as [Dependabot].
+
+[Dependabot]: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security#what-is-dependabot
+
+### Supported Versions
+
+Security patches will be released for the latest minor of a given major release. For example, if an issue is found in versions >=4.6.0 and the latest is 4.8.0, the patch will be released only in version 4.8.1.
+
+Only critical severity bug fixes will be backported to past major releases.
+
+| Version | Critical security fixes | Other security fixes |
+| ------- | ----------------------- | -------------------- |
+| 5.x     | :white_check_mark:      | :white_check_mark:   |
+| 4.9     | :white_check_mark:      | :x:                  |
+| 3.4     | :white_check_mark:      | :x:                  |
+| 2.5     | :x:                     | :x:                  |
+| < 2.0   | :x:                     | :x:                  |
+
+Note as well that the Solidity language itself only guarantees security updates for the latest release.
+
+## Legal
+
+Smart contracts are a nascent technology and carry a high level of technical risk and uncertainty. OpenZeppelin Contracts is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. Your use of the project is also governed by the terms found at www.openzeppelin.com/tos (the "Terms"). As set out in the Terms, you are solely responsible for any use of OpenZeppelin Contracts and you assume all risks associated with any such use. This Security Policy in no way evidences or represents an on-going duty by any contributor, including OpenZeppelin, to correct any flaws or alert you to all or any of the potential risks of utilizing the project.

audits/2017-03.md

@@ -1,6 +1,6 @@
 # OpenZeppelin Audit
 
-NOTE ON 2021-07-19: This report makes reference to Zeppelin, OpenZeppelin, OpenZeppelin [C]ontracts, the OpenZeppelin team, and OpenZeppelin library. Many of these things have since been renamed and know that this audit applies to what is currently called the OpenZeppelin Contracts which are maintained by the OpenZeppelin Conracts Community.
+NOTE ON 2021-07-19: This report makes reference to Zeppelin, OpenZeppelin, OpenZeppelin Contracts, the OpenZeppelin team, and OpenZeppelin library. Many of these things have since been renamed and know that this audit applies to what is currently called the OpenZeppelin Contracts which are maintained by the OpenZeppelin Contracts Community.
 
 March, 2017
 Authored by Dennis Peterson and Peter Vessenes

audits/README.md

@@ -0,0 +1,17 @@
+# Audits
+
+| Date         | Version | Commit    | Auditor      | Scope                | Links                                                       |
+| ------------ | ------- | --------- | ------------ | -------------------- | ----------------------------------------------------------- |
+| October 2023 | v5.0.0  | `b5a3e69` | OpenZeppelin | v5.0 Changes         | [🔗](./2023-10-v5.0.pdf)                                    |
+| May 2023     | v4.9.0  | `91df66c` | OpenZeppelin | v4.9 Changes         | [🔗](./2023-05-v4.9.pdf)                                    |
+| October 2022 | v4.8.0  | `14f98db` | OpenZeppelin | ERC4626, Checkpoints | [🔗](./2022-10-ERC4626.pdf) [🔗](./2022-10-Checkpoints.pdf) |
+| October 2018 | v2.0.0  | `dac5bcc` | LevelK       | Everything           | [🔗](./2018-10.pdf)                                         |
+| March 2017   | v1.0.4  | `9c5975a` | New Alchemy  | Everything           | [🔗](./2017-03.md)                                          |
+
+# Formal Verification
+
+| Date         | Version | Commit    | Tool    | Scope                                                                                                                            | Links                                |
+| ------------ | ------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| May 2022     | v4.7.0  | `109778c` | Certora | Initializable, GovernorPreventLateQuorum, ERC1155Burnable, ERC1155Pausable, ERC1155Supply, ERC1155Holder, ERC1155Receiver        | [🔗](../certora/reports/2022-05.pdf) |
+| March 2022   | v4.4.0  | `4088540` | Certora | ERC20Votes, ERC20FlashMint, ERC20Wrapper, TimelockController, ERC721Votes, Votes, AccessControl, ERC1155                         | [🔗](../certora/reports/2022-03.pdf) |
+| October 2021 | v4.4.0  | `4088540` | Certora | Governor, GovernorCountingSimple, GovernorProposalThreshold, GovernorTimelockControl, GovernorVotes, GovernorVotesQuorumFraction | [🔗](../certora/reports/2021-10.pdf) |

certora/.gitignore

@@ -0,0 +1 @@
+patched

certora/Makefile

@@ -1,24 +1,54 @@
 default: help
 
-PATCH         = applyHarness.patch
-CONTRACTS_DIR = ../contracts
-MUNGED_DIR    = munged
+SRC   := ../contracts
+DST   := patched
+DIFF  := diff
+SRCS  := $(shell find $(SRC) -type f)
+DSTS  := $(shell find $(DST) -type f)
+DIFFS := $(shell find $(DIFF) -type f)
 
+###############################################################################
+# Apply all patches in the $DIFF folder to the $DST folder
+apply: $(DST) $(patsubst $(DIFF)/%.patch,$(DST)/%,$(subst _,/,$(DIFFS)))
+
+# Reset the $DST folder
+$(DST): FORCE
+	@rm -rf $@
+	@cp -r $(SRC) $@
+
+# Update a solidity file in the $DST directory using the corresponding patch
+$(DST)/%.sol: FORCE | $(DST)
+	@echo Applying patch to $@
+	@patch -p0 -d $(DST) < $(patsubst $(DST)_%,$(DIFF)/%.patch,$(subst /,_,$@))
+
+###############################################################################
+# Record all difference between $SRC and $DST in patches
+record: $(DIFF) $(patsubst %,$(DIFF)/%.patch,$(subst /,_,$(subst $(SRC)/,,$(SRCS)) $(subst $(DST)/,,$(DSTS))))
+
+# Create the $DIFF folder
+$(DIFF): FORCE
+	@rm -rf $@
+	@mkdir $@
+
+# Create the patch file by comparing the source and the destination
+$(DIFF)/%.patch: FORCE | $(DIFF)
+	@echo Generating patch $@
+	@diff -ruN \
+		$(patsubst $(DIFF)/%.patch,$(SRC)/%,$(subst _,/,$@)) \
+		$(patsubst $(DIFF)/%.patch,$(DST)/%,$(subst _,/,$@)) \
+		| sed 's+$(SRC)/++g' \
+		| sed 's+$(DST)/++g' \
+		> $@
+	@[ -s $@ ] || rm $@
+
+###############################################################################
 help:
 	@echo "usage:"
+	@echo "  make apply:  create $(DST) directory by applying the patches to $(SRC)"
+	@echo "  make record: record the patches capturing the differences between $(SRC) and $(DST)"
 	@echo "  make clean:  remove all generated files (those ignored by git)"
-	@echo "  make $(MUNGED_DIR): create $(MUNGED_DIR) directory by applying the patch file to $(CONTRACTS_DIR)"
-	@echo "  make record: record a new patch file capturing the differences between $(CONTRACTS_DIR) and $(MUNGED_DIR)"
-
-munged:  $(wildcard $(CONTRACTS_DIR)/*.sol) $(PATCH)
-	rm -rf $@
-	cp -r $(CONTRACTS_DIR) $@
-	patch -p0 -d $@ < $(PATCH)
-
-record:
-	diff -ruN $(CONTRACTS_DIR) $(MUNGED_DIR) | sed 's+../contracts/++g' | sed 's+munged/++g' > $(PATCH)
 
 clean:
 	git clean -fdX
-	touch $(PATCH)
 
+FORCE: ;

certora/README.md

@@ -1,56 +1,60 @@
 # Running the certora verification tool
 
-These instructions detail the process for running CVT on the OpenZeppelin (Wizard/Governor) contracts.
+These instructions detail the process for running Certora Verification Tool on OpenZeppelin Contracts.
 
-Documentation for CVT and the specification language are available
-[here](https://certora.atlassian.net/wiki/spaces/CPD/overview)
+Documentation for CVT and the specification language are available [here](https://certora.atlassian.net/wiki/spaces/CPD/overview).
+
+## Prerequisites
+
+Follow the [Certora installation guide](https://docs.certora.com/en/latest/docs/user-guide/getting-started/install.html) in order to get the Certora Prover Package and the `solc` executable folder in your path.
+
+> **Note**
+> An API Key is required for local testing. Although the prover will run on a Github Actions' CI environment on selected Pull Requests.
 
 ## Running the verification
 
-The scripts in the `certora/scripts` directory are used to submit verification
-jobs to the Certora verification service. After the job is complete, the results will be available on
-[the Certora portal](https://vaas-stg.certora.com/).
+The Certora Verification Tool proves specs for contracts, which are defined by the `./specs.json` file along with their pre-configured options.
 
-These scripts should be run from the root directory; for example by running
+The verification script `./run.js` is used to submit verification jobs to the Certora Verification service.
 
-```
-sh certora/scripts/verifyAll.sh <meaningful comment>
+You can run it from the root of the repository with the following command:
+
+```bash
+node certora/run.js [[CONTRACT_NAME:]SPEC_NAME] [OPTIONS...]
 ```
 
-The most important of these is `verifyAll.sh`, which checks
-all of the harnessed contracts (`certora/harness/Wizard*.sol`) against all of
-the specifications (`certora/spec/*.spec`).
+Where:
 
-The other scripts run a subset of the specifications or the contracts.  You can
-verify different contracts or specifications by changing the `--verify` option,
-and you can run a single rule or method with the `--rule` or `--method` option.
+- `CONTRACT_NAME` matches the `contract` key in the `./spec.json` file and may be empty. It will run all matching contracts if not provided.
+- `SPEC_NAME` refers to a `spec` key from the `./specs.json` file. It will run every spec if not provided.
+- `OPTIONS` extend the [Certora Prover CLI options](https://docs.certora.com/en/latest/docs/prover/cli/options.html#certora-prover-cli-options) and will respect the preconfigured options in the `specs.json` file.
 
-For example, to verify the `WizardFirstPriority` contract against the
-`GovernorCountingSimple` specification, you could change the `--verify` line of
-the `WizardControlFirstPriortity.sh` script to:
+> **Note**
+> A single spec may be configured to run for multiple contracts, whereas a single contract may run multiple specs.
 
-```
---verify WizardFirstPriority:certora/specs/GovernorCountingSimple.spec \
+Example usage:
+
+```bash
+node certora/run.js AccessControl # Run the AccessControl spec against every contract implementing it
 ```
 
 ## Adapting to changes in the contracts
 
-Some of our rules require the code to be simplified in various ways. Our
-primary tool for performing these simplifications is to run verification on a
-contract that extends the original contracts and overrides some of the methods.
-These "harness" contracts can be found in the `certora/harness` directory.
+Some of our rules require the code to be simplified in various ways. Our primary tool for performing these simplifications is to run verification on a contract that extends the original contracts and overrides some of the methods. These "harness" contracts can be found in the `certora/harness` directory.
 
-This pattern does require some modifications to the original code: some methods
-need to be made virtual or public, for example. These changes are handled by
-applying a patch to the code before verification.
+This pattern does require some modifications to the original code: some methods need to be made virtual or public, for example. These changes are handled by applying a patch
+to the code before verification by running:
 
-When one of the `verify` scripts is executed, it first applies the patch file
-`certora/applyHarness.patch` to the `contracts` directory, placing the output
-in the `certora/munged` directory. We then verify the contracts in the
-`certora/munged` directory.
+```bash
+make -C certora apply
+```
 
-If the original contracts change, it is possible to create a conflict with the
-patch. In this case, the verify scripts will report an error message and output
-rejected changes in the `munged` directory. After merging the changes, run
-`make record` in the `certora` directory; this will regenerate the patch file,
-which can then be checked into git.
+Before running the `certora/run.js` script, it's required to apply the corresponding patches to the `contracts` directory, placing the output in the `certora/patched` directory. Then, the contracts are verified by running the verification for the `certora/patched` directory.
+
+If the original contracts change, it is possible to create a conflict with the patch. In this case, the verify scripts will report an error message and output rejected changes in the `patched` directory. After merging the changes, run `make record` in the `certora` directory; this will regenerate the patch file, which can then be checked into git.
+
+For more information about the `make` scripts available, run:
+
+```bash
+make -C certora help
+```

certora/applyHarness.patch

@@ -1,101 +0,0 @@
-diff -ruN .gitignore .gitignore
---- .gitignore	1969-12-31 19:00:00.000000000 -0500
-+++ .gitignore	2021-12-09 14:46:33.923637220 -0500
-@@ -0,0 +1,2 @@
-+*
-+!.gitignore
-diff -ruN governance/compatibility/GovernorCompatibilityBravo.sol governance/compatibility/GovernorCompatibilityBravo.sol
---- governance/compatibility/GovernorCompatibilityBravo.sol	2021-12-03 15:24:56.523654357 -0500
-+++ governance/compatibility/GovernorCompatibilityBravo.sol	2021-12-09 14:46:33.923637220 -0500
-@@ -245,7 +245,7 @@
-     /**
-      * @dev See {Governor-_quorumReached}. In this module, only forVotes count toward the quorum.
-      */
--    function _quorumReached(uint256 proposalId) internal view virtual override returns (bool) {
-+    function _quorumReached(uint256 proposalId) public view virtual override returns (bool) { // HARNESS: changed to public from internal
-         ProposalDetails storage details = _proposalDetails[proposalId];
-         return quorum(proposalSnapshot(proposalId)) <= details.forVotes;
-     }
-@@ -253,7 +253,7 @@
-     /**
-      * @dev See {Governor-_voteSucceeded}. In this module, the forVotes must be scritly over the againstVotes.
-      */
--    function _voteSucceeded(uint256 proposalId) internal view virtual override returns (bool) {
-+    function _voteSucceeded(uint256 proposalId) public view virtual override returns (bool) { // HARNESS: changed to public from internal
-         ProposalDetails storage details = _proposalDetails[proposalId];
-         return details.forVotes > details.againstVotes;
-     }
-diff -ruN governance/extensions/GovernorCountingSimple.sol governance/extensions/GovernorCountingSimple.sol
---- governance/extensions/GovernorCountingSimple.sol	2021-12-03 15:24:56.523654357 -0500
-+++ governance/extensions/GovernorCountingSimple.sol	2021-12-09 14:46:33.923637220 -0500
-@@ -64,7 +64,7 @@
-     /**
-      * @dev See {Governor-_quorumReached}.
-      */
--    function _quorumReached(uint256 proposalId) internal view virtual override returns (bool) {
-+    function _quorumReached(uint256 proposalId) public view virtual override returns (bool) {
-         ProposalVote storage proposalvote = _proposalVotes[proposalId];
- 
-         return quorum(proposalSnapshot(proposalId)) <= proposalvote.forVotes + proposalvote.abstainVotes;
-@@ -73,7 +73,7 @@
-     /**
-      * @dev See {Governor-_voteSucceeded}. In this module, the forVotes must be strictly over the againstVotes.
-      */
--    function _voteSucceeded(uint256 proposalId) internal view virtual override returns (bool) {
-+    function _voteSucceeded(uint256 proposalId) public view virtual override returns (bool) {
-         ProposalVote storage proposalvote = _proposalVotes[proposalId];
- 
-         return proposalvote.forVotes > proposalvote.againstVotes;
-diff -ruN governance/extensions/GovernorTimelockControl.sol governance/extensions/GovernorTimelockControl.sol
---- governance/extensions/GovernorTimelockControl.sol	2021-12-03 15:24:56.523654357 -0500
-+++ governance/extensions/GovernorTimelockControl.sol	2021-12-09 14:46:33.923637220 -0500
-@@ -111,7 +111,7 @@
-         bytes[] memory calldatas,
-         bytes32 descriptionHash
-     ) internal virtual override {
--        _timelock.executeBatch{value: msg.value}(targets, values, calldatas, 0, descriptionHash);
-+         _timelock.executeBatch{value: msg.value}(targets, values, calldatas, 0, descriptionHash);
-     }
- 
-     /**
-diff -ruN governance/Governor.sol governance/Governor.sol
---- governance/Governor.sol	2021-12-03 15:24:56.523654357 -0500
-+++ governance/Governor.sol	2021-12-09 14:46:56.411503587 -0500
-@@ -38,8 +38,8 @@
- 
-     string private _name;
- 
--    mapping(uint256 => ProposalCore) private _proposals;
--
-+    mapping(uint256 => ProposalCore) public _proposals;
-+ 
-     /**
-      * @dev Restrict access to governor executing address. Some module might override the _executor function to make
-      * sure this modifier is consistent with the execution model.
-@@ -167,12 +167,12 @@
-     /**
-      * @dev Amount of votes already cast passes the threshold limit.
-      */
--    function _quorumReached(uint256 proposalId) internal view virtual returns (bool);
-+    function _quorumReached(uint256 proposalId) public view virtual returns (bool); // HARNESS: changed to public from internal
- 
-     /**
-      * @dev Is the proposal successful or not.
-      */
--    function _voteSucceeded(uint256 proposalId) internal view virtual returns (bool);
-+    function _voteSucceeded(uint256 proposalId) public view virtual returns (bool); // HARNESS: changed to public from internal
- 
-     /**
-      * @dev Register a vote with a given support and voting weight.
-diff -ruN token/ERC20/extensions/ERC20Votes.sol token/ERC20/extensions/ERC20Votes.sol
---- token/ERC20/extensions/ERC20Votes.sol	2021-12-03 15:24:56.527654330 -0500
-+++ token/ERC20/extensions/ERC20Votes.sol	2021-12-09 14:46:33.927637196 -0500
-@@ -84,7 +84,7 @@
-      *
-      * - `blockNumber` must have been already mined
-      */
--    function getPastVotes(address account, uint256 blockNumber) public view returns (uint256) {
-+    function getPastVotes(address account, uint256 blockNumber) public view virtual returns (uint256) {
-         require(blockNumber < block.number, "ERC20Votes: block not yet mined");
-         return _checkpointsLookup(_checkpoints[account], blockNumber);
-     }

certora/diff/access_manager_AccessManager.sol.patch

@@ -0,0 +1,97 @@
+--- access/manager/AccessManager.sol	2023-10-05 12:17:09.694051809 -0300
++++ access/manager/AccessManager.sol	2023-10-05 12:26:18.498688718 -0300
+@@ -6,7 +6,6 @@
+ import {IAccessManaged} from "./IAccessManaged.sol";
+ import {Address} from "../../utils/Address.sol";
+ import {Context} from "../../utils/Context.sol";
+-import {Multicall} from "../../utils/Multicall.sol";
+ import {Math} from "../../utils/math/Math.sol";
+ import {Time} from "../../utils/types/Time.sol";
+ 
+@@ -57,7 +56,8 @@
+  * mindful of the danger associated with functions such as {{Ownable-renounceOwnership}} or
+  * {{AccessControl-renounceRole}}.
+  */
+-contract AccessManager is Context, Multicall, IAccessManager {
++// NOTE: The FV version of this contract doesn't include Multicall because CVL HAVOCs on any `delegatecall`.
++contract AccessManager is Context, IAccessManager {
+     using Time for *;
+ 
+     // Structure that stores the details for a target contract.
+@@ -105,7 +105,7 @@
+ 
+     // Used to identify operations that are currently being executed via {execute}.
+     // This should be transient storage when supported by the EVM.
+-    bytes32 private _executionId;
++    bytes32 internal _executionId; // private → internal for FV
+ 
+     /**
+      * @dev Check that the caller is authorized to perform the operation, following the restrictions encoded in
+@@ -253,6 +253,11 @@
+         _setGrantDelay(roleId, newDelay);
+     }
+ 
++    // Exposed for FV
++    function _getTargetAdminDelayFull(address target) internal view virtual returns (uint32, uint32, uint48) {
++        return _targets[target].adminDelay.getFull();
++    }
++
+     /**
+      * @dev Internal version of {grantRole} without access control. Returns true if the role was newly granted.
+      *
+@@ -287,6 +292,11 @@
+         return newMember;
+     }
+ 
++    // Exposed for FV
++    function _getRoleGrantDelayFull(uint64 roleId) internal view virtual returns (uint32, uint32, uint48) {
++        return _roles[roleId].grantDelay.getFull();
++    }
++
+     /**
+      * @dev Internal version of {revokeRole} without access control. This logic is also used by {renounceRole}.
+      * Returns true if the role was previously granted.
+@@ -586,7 +596,7 @@
+     /**
+      * @dev Check if the current call is authorized according to admin logic.
+      */
+-    function _checkAuthorized() private {
++    function _checkAuthorized() internal virtual { // private → internal virtual for FV
+         address caller = _msgSender();
+         (bool immediate, uint32 delay) = _canCallSelf(caller, _msgData());
+         if (!immediate) {
+@@ -609,7 +619,7 @@
+      */
+     function _getAdminRestrictions(
+         bytes calldata data
+-    ) private view returns (bool adminRestricted, uint64 roleAdminId, uint32 executionDelay) {
++    ) internal view returns (bool adminRestricted, uint64 roleAdminId, uint32 executionDelay) { // private → internal for FV
+         if (data.length < 4) {
+             return (false, 0, 0);
+         }
+@@ -662,7 +672,7 @@
+         address caller,
+         address target,
+         bytes calldata data
+-    ) private view returns (bool immediate, uint32 delay) {
++    ) internal view returns (bool immediate, uint32 delay) { // private → internal for FV
+         if (target == address(this)) {
+             return _canCallSelf(caller, data);
+         } else {
+@@ -716,14 +726,14 @@
+     /**
+      * @dev Extracts the selector from calldata. Panics if data is not at least 4 bytes
+      */
+-    function _checkSelector(bytes calldata data) private pure returns (bytes4) {
++    function _checkSelector(bytes calldata data) internal pure returns (bytes4) { // private → internal for FV
+         return bytes4(data[0:4]);
+     }
+ 
+     /**
+      * @dev Hashing function for execute protection
+      */
+-    function _hashExecutionId(address target, bytes4 selector) private pure returns (bytes32) {
++    function _hashExecutionId(address target, bytes4 selector) internal pure returns (bytes32) { // private → internal for FV
+         return keccak256(abi.encode(target, selector));
+     }
+ }

certora/harnesses/AccessControlDefaultAdminRulesHarness.sol

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {AccessControlDefaultAdminRules} from "../patched/access/extensions/AccessControlDefaultAdminRules.sol";
+
+contract AccessControlDefaultAdminRulesHarness is AccessControlDefaultAdminRules {
+    uint48 private _delayIncreaseWait;
+
+    constructor(
+        uint48 initialDelay,
+        address initialDefaultAdmin,
+        uint48 delayIncreaseWait
+    ) AccessControlDefaultAdminRules(initialDelay, initialDefaultAdmin) {
+        _delayIncreaseWait = delayIncreaseWait;
+    }
+
+    // FV
+    function pendingDefaultAdmin_() external view returns (address) {
+        (address newAdmin, ) = pendingDefaultAdmin();
+        return newAdmin;
+    }
+
+    function pendingDefaultAdminSchedule_() external view returns (uint48) {
+        (, uint48 schedule) = pendingDefaultAdmin();
+        return schedule;
+    }
+
+    function pendingDelay_() external view returns (uint48) {
+        (uint48 newDelay, ) = pendingDefaultAdminDelay();
+        return newDelay;
+    }
+
+    function pendingDelaySchedule_() external view returns (uint48) {
+        (, uint48 schedule) = pendingDefaultAdminDelay();
+        return schedule;
+    }
+
+    function delayChangeWait_(uint48 newDelay) external view returns (uint48) {
+        return _delayChangeWait(newDelay);
+    }
+
+    // Overrides
+    function defaultAdminDelayIncreaseWait() public view override returns (uint48) {
+        return _delayIncreaseWait;
+    }
+}

certora/harnesses/AccessControlHarness.sol

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {AccessControl} from "../patched/access/AccessControl.sol";
+
+contract AccessControlHarness is AccessControl {}

certora/harnesses/AccessManagedHarness.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import "../patched/access/manager/IAccessManager.sol";
+import "../patched/access/manager/AccessManaged.sol";
+
+contract AccessManagedHarness is AccessManaged {
+    bytes internal SOME_FUNCTION_CALLDATA = abi.encodeCall(this.someFunction, ());
+
+    constructor(address initialAuthority) AccessManaged(initialAuthority) {}
+
+    function someFunction() public restricted() {
+        // Sanity for FV: the msg.data when calling this function should be the same as the data used when checking
+        // the schedule. This is a reformulation of `msg.data == SOME_FUNCTION_CALLDATA` that focuses on the operation
+        // hash for this call.
+        require(
+            IAccessManager(authority()).hashOperation(_msgSender(), address(this), msg.data)
+            ==
+            IAccessManager(authority()).hashOperation(_msgSender(), address(this), SOME_FUNCTION_CALLDATA)
+        );
+    }
+
+    function authority_canCall_immediate(address caller) public view returns (bool result) {
+        (result,) = AuthorityUtils.canCallWithDelay(authority(), caller, address(this), this.someFunction.selector);
+    }
+
+    function authority_canCall_delay(address caller) public view returns (uint32 result) {
+        (,result) = AuthorityUtils.canCallWithDelay(authority(), caller, address(this), this.someFunction.selector);
+    }
+
+    function authority_getSchedule(address caller) public view returns (uint48) {
+        IAccessManager manager = IAccessManager(authority());
+        return manager.getSchedule(manager.hashOperation(caller, address(this), SOME_FUNCTION_CALLDATA));
+    }
+}

certora/harnesses/AccessManagerHarness.sol

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import "../patched/access/manager/AccessManager.sol";
+
+contract AccessManagerHarness is AccessManager {
+    // override with a storage slot that can basically take any value.
+    uint32 private _minSetback;
+
+    constructor(address initialAdmin) AccessManager(initialAdmin) {}
+
+    // FV
+    function minSetback() public view override returns (uint32) {
+        return _minSetback;
+    }
+
+    function canCall_immediate(address caller, address target, bytes4 selector) external view returns (bool result) {
+        (result,) = canCall(caller, target, selector);
+    }
+
+    function canCall_delay(address caller, address target, bytes4 selector) external view returns (uint32 result) {
+        (,result) = canCall(caller, target, selector);
+    }
+
+    function canCallExtended(address caller, address target, bytes calldata data) external view returns (bool, uint32) {
+        return _canCallExtended(caller, target, data);
+    }
+
+    function canCallExtended_immediate(address caller, address target, bytes calldata data) external view returns (bool result) {
+        (result,) = _canCallExtended(caller, target, data);
+    }
+
+    function canCallExtended_delay(address caller, address target, bytes calldata data) external view returns (uint32 result) {
+        (,result) = _canCallExtended(caller, target, data);
+    }
+
+    function getAdminRestrictions_restricted(bytes calldata data) external view returns (bool result) {
+        (result,,) = _getAdminRestrictions(data);
+    }
+
+    function getAdminRestrictions_roleAdminId(bytes calldata data) external view returns (uint64 result) {
+        (,result,) = _getAdminRestrictions(data);
+    }
+
+    function getAdminRestrictions_executionDelay(bytes calldata data) external view returns (uint32 result) {
+        (,,result) = _getAdminRestrictions(data);
+    }
+
+    function hasRole_isMember(uint64 roleId, address account) external view returns (bool result) {
+        (result,) = hasRole(roleId, account);
+    }
+
+    function hasRole_executionDelay(uint64 roleId, address account) external view returns (uint32 result) {
+        (,result) = hasRole(roleId, account);
+    }
+
+    function getAccess_since(uint64 roleId, address account) external view returns (uint48 result) {
+        (result,,,) = getAccess(roleId, account);
+    }
+
+    function getAccess_currentDelay(uint64 roleId, address account) external view returns (uint32 result) {
+        (,result,,) = getAccess(roleId, account);
+    }
+
+    function getAccess_pendingDelay(uint64 roleId, address account) external view returns (uint32 result) {
+        (,,result,) = getAccess(roleId, account);
+    }
+
+    function getAccess_effect(uint64 roleId, address account) external view returns (uint48 result) {
+        (,,,result) = getAccess(roleId, account);
+    }
+
+    function getTargetAdminDelay_after(address target) public view virtual returns (uint32 result) {
+        (,result,) = _getTargetAdminDelayFull(target);
+    }
+
+    function getTargetAdminDelay_effect(address target) public view virtual returns (uint48 result) {
+        (,,result) = _getTargetAdminDelayFull(target);
+    }
+
+    function getRoleGrantDelay_after(uint64 roleId) public view virtual returns (uint32 result) {
+        (,result,) = _getRoleGrantDelayFull(roleId);
+    }
+
+    function getRoleGrantDelay_effect(uint64 roleId) public view virtual returns (uint48 result) {
+        (,,result) = _getRoleGrantDelayFull(roleId);
+    }
+
+    function hashExecutionId(address target, bytes4 selector) external pure returns (bytes32) {
+        return _hashExecutionId(target, selector);
+    }
+
+    function executionId() external view returns (bytes32) {
+        return _executionId;
+    }
+
+    // Pad with zeros (and don't revert) if data is too short.
+    function getSelector(bytes calldata data) external pure returns (bytes4) {
+        return bytes4(data);
+    }
+
+    function getFirstArgumentAsAddress(bytes calldata data) external pure returns (address) {
+        return abi.decode(data[0x04:0x24], (address));
+    }
+
+    function getFirstArgumentAsUint64(bytes calldata data) external pure returns (uint64) {
+        return abi.decode(data[0x04:0x24], (uint64));
+    }
+
+    function _checkAuthorized() internal override {
+        // We need this hack otherwise certora will assume _checkSelector(_msgData()) can return anything :/
+        require(msg.sig == _checkSelector(_msgData()));
+        super._checkAuthorized();
+    }
+}

certora/harnesses/DoubleEndedQueueHarness.sol

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {DoubleEndedQueue} from "../patched/utils/structs/DoubleEndedQueue.sol";
+
+contract DoubleEndedQueueHarness {
+    using DoubleEndedQueue for DoubleEndedQueue.Bytes32Deque;
+
+    DoubleEndedQueue.Bytes32Deque private _deque;
+
+    function pushFront(bytes32 value) external {
+        _deque.pushFront(value);
+    }
+
+    function pushBack(bytes32 value) external {
+        _deque.pushBack(value);
+    }
+
+    function popFront() external returns (bytes32 value) {
+        return _deque.popFront();
+    }
+
+    function popBack() external returns (bytes32 value) {
+        return _deque.popBack();
+    }
+
+    function clear() external {
+        _deque.clear();
+    }
+
+    function begin() external view returns (uint128) {
+        return _deque._begin;
+    }
+
+    function end() external view returns (uint128) {
+        return _deque._end;
+    }
+
+    function length() external view returns (uint256) {
+        return _deque.length();
+    }
+
+    function empty() external view returns (bool) {
+        return _deque.empty();
+    }
+
+    function front() external view returns (bytes32 value) {
+        return _deque.front();
+    }
+
+    function back() external view returns (bytes32 value) {
+        return _deque.back();
+    }
+
+    function at_(uint256 index) external view returns (bytes32 value) {
+        return _deque.at(index);
+    }
+}

certora/harnesses/ERC20FlashMintHarness.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import "../patched/token/ERC20/ERC20.sol";
+import "../patched/token/ERC20/extensions/ERC20Permit.sol";
+import "../patched/token/ERC20/extensions/ERC20FlashMint.sol";
+
+contract ERC20FlashMintHarness is ERC20, ERC20Permit, ERC20FlashMint {
+    uint256 someFee;
+    address someFeeReceiver;
+
+    constructor(string memory name, string memory symbol) ERC20(name, symbol) ERC20Permit(name) {}
+
+    function mint(address account, uint256 amount) external {
+        _mint(account, amount);
+    }
+
+    function burn(address account, uint256 amount) external {
+        _burn(account, amount);
+    }
+
+    // public accessor
+    function flashFeeReceiver() public view returns (address) {
+        return someFeeReceiver;
+    }
+
+    // internal hook
+    function _flashFee(address, uint256) internal view override returns (uint256) {
+        return someFee;
+    }
+
+    function _flashFeeReceiver() internal view override returns (address) {
+        return someFeeReceiver;
+    }
+}

certora/harnesses/ERC20PermitHarness.sol

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {ERC20Permit, ERC20} from "../patched/token/ERC20/extensions/ERC20Permit.sol";
+
+contract ERC20PermitHarness is ERC20Permit {
+    constructor(string memory name, string memory symbol) ERC20(name, symbol) ERC20Permit(name) {}
+
+    function mint(address account, uint256 amount) external {
+        _mint(account, amount);
+    }
+
+    function burn(address account, uint256 amount) external {
+        _burn(account, amount);
+    }
+}

certora/harnesses/ERC20VotesHarness.sol

@@ -1,28 +0,0 @@
-import "../munged/token/ERC20/extensions/ERC20Votes.sol";
-
-contract ERC20VotesHarness is ERC20Votes {
-    constructor(string memory name, string memory symbol) ERC20Permit(name) ERC20(name, symbol) {}
-
-    mapping(address => mapping(uint256 => uint256)) public _getPastVotes;
-
-    function _afterTokenTransfer(
-        address from,
-        address to,
-        uint256 amount
-    ) internal virtual override {
-        super._afterTokenTransfer(from, to, amount);
-        _getPastVotes[from][block.number] -= amount;
-        _getPastVotes[to][block.number] += amount;
-    }
-
-    /**
-     * @dev Change delegation for `delegator` to `delegatee`.
-     *
-     * Emits events {DelegateChanged} and {DelegateVotesChanged}.
-     */
-    function _delegate(address delegator, address delegatee) internal virtual override{
-        super._delegate(delegator, delegatee);
-        _getPastVotes[delegator][block.number] -= balanceOf(delegator);
-        _getPastVotes[delegatee][block.number] += balanceOf(delegator);
-    }
-}

certora/harnesses/ERC20WrapperHarness.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {ERC20Permit} from "../patched/token/ERC20/extensions/ERC20Permit.sol";
+import {ERC20Wrapper, IERC20, ERC20} from "../patched/token/ERC20/extensions/ERC20Wrapper.sol";
+
+contract ERC20WrapperHarness is ERC20Permit, ERC20Wrapper {
+    constructor(
+        IERC20 _underlying,
+        string memory _name,
+        string memory _symbol
+    ) ERC20(_name, _symbol) ERC20Permit(_name) ERC20Wrapper(_underlying) {}
+
+    function underlyingTotalSupply() public view returns (uint256) {
+        return underlying().totalSupply();
+    }
+
+    function underlyingBalanceOf(address account) public view returns (uint256) {
+        return underlying().balanceOf(account);
+    }
+
+    function underlyingAllowanceToThis(address account) public view returns (uint256) {
+        return underlying().allowance(account, address(this));
+    }
+
+    function recover(address account) public returns (uint256) {
+        return _recover(account);
+    }
+
+    function decimals() public view override(ERC20Wrapper, ERC20) returns (uint8) {
+        return super.decimals();
+    }
+}

certora/harnesses/ERC3156FlashBorrowerHarness.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+
+import {IERC3156FlashBorrower} from "../patched/interfaces/IERC3156FlashBorrower.sol";
+
+pragma solidity ^0.8.20;
+
+contract ERC3156FlashBorrowerHarness is IERC3156FlashBorrower {
+    bytes32 somethingToReturn;
+
+    function onFlashLoan(address, address, uint256, uint256, bytes calldata) external view override returns (bytes32) {
+        return somethingToReturn;
+    }
+}

certora/harnesses/ERC721Harness.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {ERC721} from "../patched/token/ERC721/ERC721.sol";
+
+contract ERC721Harness is ERC721 {
+    constructor(string memory name, string memory symbol) ERC721(name, symbol) {}
+
+    function mint(address account, uint256 tokenId) external {
+        _mint(account, tokenId);
+    }
+
+    function safeMint(address to, uint256 tokenId) external {
+        _safeMint(to, tokenId);
+    }
+
+    function safeMint(address to, uint256 tokenId, bytes memory data) external {
+        _safeMint(to, tokenId, data);
+    }
+
+    function burn(uint256 tokenId) external {
+        _burn(tokenId);
+    }
+
+    function unsafeOwnerOf(uint256 tokenId) external view returns (address) {
+        return _ownerOf(tokenId);
+    }
+
+    function unsafeGetApproved(uint256 tokenId) external view returns (address) {
+        return _getApproved(tokenId);
+    }
+}

certora/harnesses/ERC721ReceiverHarness.sol

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import "../patched/interfaces/IERC721Receiver.sol";
+
+contract ERC721ReceiverHarness is IERC721Receiver {
+    function onERC721Received(address, address, uint256, bytes calldata) external pure returns (bytes4) {
+        return this.onERC721Received.selector;
+    }
+}

certora/harnesses/EnumerableMapHarness.sol

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {EnumerableMap} from "../patched/utils/structs/EnumerableMap.sol";
+
+contract EnumerableMapHarness {
+    using EnumerableMap for EnumerableMap.Bytes32ToBytes32Map;
+
+    EnumerableMap.Bytes32ToBytes32Map private _map;
+
+    function set(bytes32 key, bytes32 value) public returns (bool) {
+        return _map.set(key, value);
+    }
+
+    function remove(bytes32 key) public returns (bool) {
+        return _map.remove(key);
+    }
+
+    function contains(bytes32 key) public view returns (bool) {
+        return _map.contains(key);
+    }
+
+    function length() public view returns (uint256) {
+        return _map.length();
+    }
+
+    function key_at(uint256 index) public view returns (bytes32) {
+        (bytes32 key,) = _map.at(index);
+        return key;
+    }
+
+    function value_at(uint256 index) public view returns (bytes32) {
+        (,bytes32 value) = _map.at(index);
+        return value;
+    }
+
+    function tryGet_contains(bytes32 key) public view returns (bool) {
+        (bool contained,) = _map.tryGet(key);
+        return contained;
+    }
+
+    function tryGet_value(bytes32 key) public view returns (bytes32) {
+        (,bytes32 value) = _map.tryGet(key);
+        return value;
+    }
+
+    function get(bytes32 key) public view returns (bytes32) {
+        return _map.get(key);
+    }
+
+    function _positionOf(bytes32 key) public view returns (uint256) {
+        return _map._keys._inner._positions[key];
+    }
+}