更新合约文档，翻译为中文以增强可读性，包括 AccessControl、Ownable、ERC20 和 IERC20 的相关说明。修正了一些注释以确保准确性和一致性。

Co-authored-by: Hadrien Croubois <hadrien.croubois@gmail.com>

.changeset/all-geese-stand.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': patch
+---
+
+Add constructors to the different signers.

.changeset/clean-ways-push.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AccountERC7579`: Extension of `Account` that implements support for ERC-7579 modules of type executor, validator, and fallback handler.

.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/dull-students-eat.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Memory`: Add library with utilities to manipulate memory

.changeset/eight-radios-check.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Checkpoints`: Add a new checkpoint variant `Checkpoint256` using `uint256` type for the value and key.

.changeset/fine-frogs-bake.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`EnumerableMap`: Add `keys(uint256,uint256)` that returns a subset (slice) of the keys in the map.

.changeset/full-ways-help.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`EIP7702Utils`: Add a library for checking if an address has an EIP-7702 delegation in place.

.changeset/funny-years-yawn.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Account`: Added a simple ERC-4337 account implementation with minimal logic to process user operations.

.changeset/hot-grapes-lie.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`EnumerableSet`: Add `values(uint256,uint256)` that returns a subset (slice) of the values in the set.

.changeset/lazy-poets-cheer.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`SignerERC7702`: Implementation of `AbstractSigner` for Externally Owned Accounts (EOAs). Useful with ERC-7702.

.changeset/long-hornets-mate.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`EnumerableMap`: Add support for `BytesToBytesMap` type.

.changeset/lucky-donuts-scream.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC7739`: An abstract contract to validate signatures following the rehashing scheme from `ERC7739Utils`.

.changeset/major-feet-write.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Bytes`: Add `reverseBytes32`, `reverseBytes16`, `reverseBytes8`, `reverseBytes4`, and `reverseBytes2` functions to reverse byte order for converting between little-endian and big-endian representations.

.changeset/new-days-tease.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Strings`: Add `toHexString(bytes)`.

.changeset/nice-rings-wish.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC7913P256Verifier` and `ERC7913RSAVerifier`: Ready to use ERC-7913 verifiers that implement key verification for P256 (secp256r1) and RSA keys.

.changeset/pink-dolls-shop.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`EnumerableSet`: Add support for `StringSet` and `BytesSet` types.

.changeset/popular-geese-tan.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`GovernorNoncesKeyed`: Extension of `Governor` that adds support for keyed nonces when voting by sig.

.changeset/proud-tables-sip.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC7739Utils`: Add a library that implements a defensive rehashing mechanism to prevent replayability of smart contract signatures based on the ERC-7739.

.changeset/public-crabs-heal.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`MultiSignerERC7913Weighted`: Extension of `MultiSignerERC7913` that supports assigning different weights to each signer, enabling more flexible governance schemes.

.changeset/quiet-kiwis-feel.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`SignerERC7913`: Abstract signer that verifies signatures using the ERC-7913 workflow.

.changeset/rare-shirts-unite.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Arrays`: Add `unsafeAccess`, `unsafeMemoryAccess` and `unsafeSetLength` for `bytes[]` and `string[]`.

.changeset/rich-cows-repair.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`InteroperableAddress`: Add a library for formatting and parsing ERC-7930 interoperable addresses.

.changeset/ripe-bears-hide.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC20Bridgeable`: Implementation of ERC-7802 that makes an ERC-20 compatible with crosschain bridges.

.changeset/rotten-apes-lie.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`IERC7821`, `ERC7821`: Interface and logic for minimal batch execution. No support for additional `opData` is included.

.changeset/social-walls-obey.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`MultiSignerERC7913`: Implementation of `AbstractSigner` that supports multiple ERC-7913 signers with a threshold-based signature verification system.

.changeset/sour-pens-shake.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`SignatureChecker`: Add support for ERC-7913 signatures alongside existing ECDSA and ERC-1271 signature verification.

.changeset/strong-points-change.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AccountERC7579Hooked`: Extension of `AccountERC7579` that implements support for ERC-7579 hook modules.

.changeset/tame-bears-mix.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AbstractSigner`, `SignerECDSA`, `SignerP256`, and `SignerRSA`: Add an abstract contract and various implementations for contracts that deal with signature verification.

.changeset/violet-turtles-like.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ECDSA`: Add `recoverCalldata` and `tryRecoverCalldata`, variants of `recover` and `tryRecover` that are more efficient when signatures are in calldata.

.changeset/wet-dodos-reply.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Blockhash`: Add a library that provides access to historical block hashes using EIP-2935's history storage, extending the standard 256-block limit to 8191 blocks.

.changeset/whole-plums-speak.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`SignatureChecker`: Add `isValidSignatureNowCalldata(address,bytes32,bytes calldata)` for efficient processing of calldata signatures.

.changeset/wild-baths-buy.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`IERC7786`: Add the (draft) interface for ERC-7786 "Cross-Chain Messaging Gateway"

.circleci/config.yml

@@ -1,82 +0,0 @@
-version: 2
-# 2.1 does not yet support local run
-# unless with workaround. For simplicity just use it.
-# https://github.com/CircleCI-Public/circleci-cli/issues/79
-
-aliases:
-  - &defaults
-    docker:
-      - image: circleci/node:8
-
-  - &npm_install_if_necessary
-    run:
-      name: Install npm dependencies
-      command: |
-        if [ ! -d node_modules ]; then
-          npm ci
-        fi
-
-  - &cache_key_node_modules
-    key: v1-node_modules-{{ checksum "package-lock.json" }}
-
-jobs:
-  dependencies:
-    <<: *defaults
-    steps:
-      - checkout
-      - restore_cache:
-          <<: *cache_key_node_modules
-      - *npm_install_if_necessary
-      - save_cache:
-          paths:
-            - node_modules
-          <<: *cache_key_node_modules
-
-  lint:
-    <<: *defaults
-    steps:
-      - checkout
-      - restore_cache:
-          <<: *cache_key_node_modules
-      - *npm_install_if_necessary
-      - run:
-          name: Linter
-          command: npm run lint
-  test:
-    <<: *defaults
-    steps:
-      - checkout
-      - restore_cache:
-          <<: *cache_key_node_modules
-      - *npm_install_if_necessary
-      - run:
-          name: Unit tests
-          command: npm run test
-  coverage:
-    docker:
-      - image: circleci/node:8
-    steps:
-      - checkout
-      - restore_cache:
-          <<: *cache_key_node_modules
-      - *npm_install_if_necessary
-      - run:
-          name: Unit tests with coverage report
-          command: npm run coverage
-
-      # TODO(xinbenlv, #1839): run SOLC_NIGHTLY to be run but allow it to fail.
-
-workflows:
-  version: 2
-  everything:
-    jobs:
-      - dependencies
-      - lint:
-          requires:
-            - dependencies
-      - test:
-          requires:
-            - dependencies
-      - coverage:
-          requires:
-            - dependencies

.codecov.yml

@@ -1,3 +1,16 @@
 comment: off
+github_checks:
+  annotations: false
 coverage:
-  range: "100...100"
+  status:
+    patch:
+      default:
+        target: 95%
+        only_pulls: true
+    project:
+      default:
+        threshold: 1%
+ignore:
+  - "test"
+  - "contracts/mocks"
+  - "contracts/vendor"

.editorconfig

@@ -6,13 +6,16 @@ root = true
 [*]
 charset = utf-8
 end_of_line = lf
-indent_size = 4
 indent_style = space
 insert_final_newline = true
-trim_trailing_whitespace = true
+trim_trailing_whitespace = false
+max_line_length = 120
 
 [*.sol]
 indent_size = 4
 
 [*.js]
 indent_size = 2
+
+[*.{adoc,md}]
+max_line_length = 0

.eslintrc

@@ -1,58 +0,0 @@
-{
-  "extends" : [
-    "standard",
-    "plugin:promise/recommended",
-  ],
-  "plugins": [
-    "mocha-no-only",
-    "promise",
-  ],
-  "env": {
-    "browser" : true,
-    "node"    : true,
-    "mocha"   : true,
-    "jest"    : true,
-  },
-  "globals" : {
-    "artifacts": false,
-    "contract": false,
-    "assert": false,
-    "web3": false,
-  },
-  "rules": {
-
-    // Strict mode
-    "strict": ["error", "global"],
-
-    // Code style
-    "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-only/mocha-no-only": ["error"],
-
-    "promise/always-return": "off",
-    "promise/avoid-new": "off",
-  }
-}

.gitattributes

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

.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# List of approvers/reviewers for OpenZeppelin Contracts
+#
+# Get in touch with us via the OpenZeppelin Forum
+#  https://forum.openzeppelin.com/
+# 
+# Learn about CODEOWNERS file format: 
+#  https://help.github.com/en/articles/about-code-owners
+
+# These owners will be the default owners for everything in the repo.
+* @OpenZeppelin/contracts

.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/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,4 @@
+contact_links:
+  - name: Questions & Support Requests
+    url: https://forum.openzeppelin.com/c/support/contracts/18
+    about: Ask in the OpenZeppelin Forum

.github/ISSUE_TEMPLATE/feature_request.md

@@ -10,5 +10,5 @@ about: Suggest an idea for OpenZeppelin Contracts
 **📝 Details**
 <!-- Please describe your feature request in detail. -->
 
-<!-- Make sure that you have reviewed the OpenZeppelin Contributor Guidelines. -->
+<!-- Make sure that you have reviewed the OpenZeppelin Contracts Contributor Guidelines. -->
 <!-- https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/CONTRIBUTING.md -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,22 +1,20 @@
-<!-- 0. 🎉 Thank you for submitting a PR! -->
+<!-- Thank you for your interest in contributing to OpenZeppelin! -->
 
-<!-- 1. Does this close any open issues? Please list them below. -->
+<!-- Consider opening an issue for discussion prior to submitting a PR. -->
+<!-- New features will be merged faster if they were first discussed and designed with the team. -->
 
-<!-- Keep in mind that new features have a better chance of being merged fast if
-they were first discussed and designed with the maintainers. If there is no
-corresponding issue, please consider opening one for discussion first! -->
+Fixes #???? <!-- Fill in with issue number -->
 
-Fixes #
+<!-- Describe the changes introduced in this pull request. -->
+<!-- Include any context necessary for understanding the PR's purpose. -->
 
-<!-- 2. Describe the changes introduced in this pull request. -->
-<!--    Include any context necessary for understanding the PR's purpose. -->
 
-<!-- 3. Before submitting, please make sure that you have:
-  - reviewed the OpenZeppelin Contributor Guidelines
-    (https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/CONTRIBUTING.md),
-  - added tests where applicable to test new functionality,
-  - made sure that your contracts are well-documented,
-  - run the Solidity linter (`npm run lint:sol`) and fixed any issues,
-  - run the JS linter and fixed any issues (`npm run lint:fix`), and
-  - updated the changelog, if applicable.
--->
+#### PR Checklist
+
+<!-- Before merging the pull request all of the following must be complete. -->
+<!-- Feel free to submit a PR or Draft PR even if some items are pending. -->
+<!-- Some of the items may not apply. -->
+
+- [ ] Tests
+- [ ] Documentation
+- [ ] Changeset entry (run `npx changeset add`)

.github/actions/gas-compare/action.yml

@@ -0,0 +1,51 @@
+name: Compare gas costs
+description: Compare gas costs between branches
+inputs:
+  token:
+    description: GitHub token, required to access GitHub API
+    required: true
+  report:
+    description: Path to the report to compare
+    required: false
+    default: gasReporterOutput.json
+  out_report:
+    description: Path to save the output report
+    required: false
+    default: ${{ github.ref_name }}.gasreport.json
+  ref_report:
+    description: Path to the reference report for comparison
+    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@v4
+      with:
+        name: gasreport
+        overwrite: true
+        path: ${{ inputs.out_report }}

.github/actions/setup/action.yml

@@ -0,0 +1,22 @@
+name: Setup
+description: Common environment setup
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 22.x
+    - uses: actions/cache@v4
+      id: cache
+      with:
+        path: '**/node_modules'
+        key: npm-v3-${{ hashFiles('**/package-lock.json') }}
+    - name: Install dependencies
+      run: npm ci
+      shell: bash
+      if: steps.cache.outputs.cache-hit != 'true'
+    - name: Install Foundry
+      uses: foundry-rs/foundry-toolchain@v1
+      with:
+        version: stable

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

@@ -0,0 +1,57 @@
+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@v4
+      with:
+        name: layout
+        overwrite: true
+        path: ${{ inputs.out_layout }}

.github/stale.yml

@@ -1,66 +0,0 @@
-# Configuration for probot-stale - https://github.com/probot/stale
-
-# Number of days of inactivity before an Issue or Pull Request becomes stale
-daysUntilStale: 15
-
-# Number of days of inactivity before an Issue or Pull Request with the stale label is closed.
-# Set to false to disable. If disabled, issues still need to be closed manually, but will remain marked as stale.
-daysUntilClose: 15
-
-# Issues or Pull Requests with these labels will never be considered stale. Set to `[]` to disable
-exemptLabels:
-  - on hold
-
-# Set to true to ignore issues in a project (defaults to false)
-exemptProjects: false
-
-# Set to true to ignore issues in a milestone (defaults to false)
-exemptMilestones: false
-
-# Set to true to ignore issues with an assignee (defaults to false)
-exemptAssignees: false
-
-# Label to use when marking as stale
-staleLabel: stale
-
-# Comment to post when marking as stale. Set to `false` to disable
-markComment: >
-  Hi all!
-
-  This Pull Request has not had any recent activity, is it still relevant? If so, what is blocking it?
-  Is there anything we can do to help move it forward?
-
-  Thanks!
-
-
-# Comment to post when removing the stale label.
-# unmarkComment: >
-#   Your comment here.
-
-# Comment to post when closing a stale Issue or Pull Request.
-closeComment: >
-  Hi folks!
-
-  This Pull Request is being closed as there was no response to the previous prompt.
-  However, please leave a comment whenever you're ready to resume, so it can be reopened.
-
-  Thanks again!
-
-
-# Limit the number of actions per hour, from 1-30. Default is 30
-limitPerRun: 30
-
-# Limit to only `issues` or `pulls`
-only: pulls
-
-# Optionally, specify configuration settings that are specific to just 'issues' or 'pulls':
-# pulls:
-#   daysUntilStale: 30
-#   markComment: >
-#     This pull request has been automatically marked as stale because it has not had
-#     recent activity. It will be closed if no further activity occurs. Thank you
-#     for your contributions.
-
-# issues:
-#   exemptLabels:
-#     - confirmed

.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

@@ -0,0 +1,132 @@
+name: checks
+
+on:
+  push:
+    branches:
+      - master
+      - next-v*
+      - release-v*
+  pull_request: {}
+  workflow_dispatch: {}
+
+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@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@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - 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 pragma validity
+        run: npm run test:pragma -- --concurrency 1
+      - name: Check procedurally 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 pragma validity
+        run: npm run test:pragma -- --concurrency 1
+      - 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 -vvv
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - name: Run coverage
+        run: npm run coverage
+      - uses: codecov/codecov-action@v5
+        env:
+          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@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - uses: crytic/slither-action@v0.4.1
+
+  codespell:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run CodeSpell
+        uses: codespell-project/actions-codespell@v2.1
+        with:
+          check_hidden: true
+          check_filenames: true
+          skip: package-lock.json,*.pdf,vendor

.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Build Docs
+
+on:
+  push:
+    branches: [release-v*]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - run: bash scripts/git-user-config.sh
+      - run: node scripts/update-docs-branch.js
+      - run: git push --all origin 

.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.11'
+  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@v4
+        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,214 @@
+#  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
+      id-token: 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 }}
+          NPM_CONFIG_PROVENANCE: true
+      - 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

@@ -0,0 +1,34 @@
+name: transpile upgradeable
+
+on:
+  push:
+    branches:
+      - master
+      - release-v*
+
+jobs:
+  transpile:
+    environment: push-upgradeable
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          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,22 +29,39 @@ npm-debug.log
 # local env variables
 .env
 
-# truffle build directory
-build/
-
 # macOS
 .DS_Store
 
-# truffle
-.node-xmlhttprequest-*
-
 # IntelliJ IDE
 .idea
 
 # docs artifacts
 docs/modules/api
-openzeppelin-docs
+build/site
 
 # only used to package @openzeppelin/contracts
 contracts/build/
 contracts/README.md
+
+# temporary artifact from solidity-coverage
+allFiredEvents
+.coverage_artifacts
+.coverage_cache
+.coverage_contracts
+
+# 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

.husky/pre-commit

@@ -0,0 +1,2 @@
+npm run test:generation
+npx lint-staged

.mocharc.js

@@ -0,0 +1,4 @@
+module.exports = {
+  require: 'hardhat/register',
+  timeout: 4000,
+};

.prettierrc

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

.solcover.js

@@ -1,9 +1,21 @@
 module.exports = {
-    norpc: true,
-    testCommand: 'node --max-old-space-size=4096 ../node_modules/.bin/truffle test --network coverage',
-    compileCommand: 'node --max-old-space-size=4096 ../node_modules/.bin/truffle compile --network coverage',
-    skipFiles: [
-        'lifecycle/Migrations.sol',
-        'mocks'
-    ]
-}
+  norpc: true,
+  testCommand: 'npm test',
+  compileCommand: 'npm run compile',
+  skipFiles: ['mocks'],
+  providerOptions: {
+    default_balance_ether: '10000000000000000000000000',
+  },
+  mocha: {
+    fgrep: '[skip-on-coverage]',
+    invert: true,
+  },
+  // Work around stack too deep for coverage
+  configureYulOptimizer: true,
+  solcOptimizerDetails: {
+    yul: true,
+    yulDetails: {
+      optimizerSteps: '',
+    },
+  },
+};

.solhint.json

@@ -1,14 +0,0 @@
-{
-  "extends": "solhint:recommended",
-  "rules": {
-    "indent": ["error", 4],
-    "func-order": "off",
-    "bracket-align": "off",
-    "compiler-fixed": "off",
-    "no-simple-event-func-name": "off",
-    "separate-by-one-line-in-contract": "off",
-    "two-lines-top-level-separator": "off",
-    "mark-callable-contracts": "off",
-    "compiler-version": ["error", "^0.5.0"]
-  }
-}

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.

CODE_STYLE.md

@@ -1,69 +0,0 @@
-# Code Style
-
-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 this
-document and take some time to familiarize yourself with the style of the
-existing codebase.
-
-## Solidity code
-
-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).
-
-Any exception or additions specific to our project are documented below.
-
-### Naming
-
-* Try to avoid acronyms and abbreviations.
-
-* All state variables should be private.
-
-* Private state variables should have an underscore prefix.
-
-    ```
-    contract TestContract {
-      uint256 private _privateVar;
-      uint256 internal _internalVar;
-    }
-    ```
-
-* Parameters must not be prefixed with an underscore.
-
-    ```
-    function test(uint256 testParameter1, uint256 testParameter2) {
-    ...
-    }
-    ```
-
-* Internal and private functions should have an underscore prefix.
-
-    ```
-    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 {
-      super._burn(_who, _value);
-      emit TokensBurned(_who, _value);
-    }
-    ```
-
-  Some standards (e.g. ERC20) use present tense, and in those cases the
-  standard specification prevails.
-  
-* Interface names should have a capital I prefix.
-
-    ```
-    interface IERC777 {
-    ```

CONTRIBUTING.md

@@ -1,71 +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.
 
-or you can simply run CircleCI locally
-```bash
-circleci local execute --job build
-circleci local execute --job test
-```
-*Note*: requires installing CircleCI and docker locally on your machine.
+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.
 
-5) Go to [github.com/OpenZeppelin/openzeppelin-contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) in your web browser and issue a new pull request.
+Changelog entries should be added to each pull request by using [Changesets](https://github.com/changesets/changesets/).
 
-*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.
+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.
 
-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.
-
-*IMPORTANT* Please pay attention to the maintainer's feedback, since its a necessary step to keep up with the standards OpenZeppelin 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)!

DOCUMENTATION.md

@@ -1,19 +0,0 @@
-We're building an improved documentation website. It's still in development and
-contributions will be really appreciated.
-
-All of the content for the site is in this repository. The guides are in the
-[docs](/docs) directory, and the API Reference is extracted from comments in
-the source code. If you want to help improve the content, this is the
-repository you should be contributing to.
-
-[`solidity-docgen`](https://github.com/OpenZeppelin/solidity-docgen) is the
-program that extracts the API Reference from source code.
-
-The [`openzeppelin-docsite`](https://github.com/OpenZeppelin/openzeppelin-docsite)
-repository hosts the configuration for Docusaurus, the static site generator
-that we use.
-
-To run the docsite locally you should run `npm run docsite start` on this
-repository. This will live reload as the guides are edited, but not with
-changes to the source code comments, for that you need to restart the server.
-This should be improved eventually (contributions welcome!).

FUNDING.json

@@ -0,0 +1,10 @@
+{
+  "drips": {
+    "ethereum": {
+      "ownedBy": "0xAeb37910f93486C85A1F8F994b67E8187554d664"
+    }
+  },
+  "opRetro": {
+    "projectId": "0x939241afa4c4b9e1dda6b8250baa8f04fa8b0debce738cfd324c0b18f9926d25"
+  }
+}

GUIDELINES.md

@@ -1,64 +1,155 @@
-Design Guidelines
-=======
+# Engineering Guidelines
 
-These are some global design goals in OpenZeppelin.
+## 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 is just as important (if not more so) than the code itself, and should be written to 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.
+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.
 
-### General
+Sometimes these guidelines may be broken if doing so brings significant efficiency gains, but explanatory comments should be added.
 
-#### G0 - Default to Solidity's official style guide.
+Modularity should be pursued, but not at the cost of the above priorities.
 
-Follow the official Solidity style guide: https://solidity.readthedocs.io/en/latest/style-guide.html
+## Documentation
 
-#### G1 - No Magic Constants
+For contributors, project guidelines and processes must be documented publicly.
 
-Avoid constants in the code as much as possible. Magic strings are also magic constants.
+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.
 
-#### G2 - Code that Fails Early
+All changes to the core codebase (excluding tests, auxiliary scripts, etc.) must be documented in a changelog, except for purely cosmetic or documentation changes.
 
-We ask our code to fail as soon as possible when an unexpected input was provided or unexpected state was found.
+## Peer review
 
-#### G3 - Internal Amounts Must be Signed Integers and Represent the Smallest Units.
+All changes must be submitted through pull requests and go through peer code review.
 
-Avoid representation errors by always dealing with weis when handling ether. GUIs can convert to more human-friendly representations. Use Signed Integers (int) to prevent underflow problems.
+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.
 
-### Testing
+External contributions must be reviewed separately by multiple maintainers.
 
-#### T1 - Tests Must be Written Elegantly
+## Automation
 
-Style guidelines are not relaxed for tests. Tests are a good way to show how to use the library, and maintaining them is extremely necessary.
+Automation should be used as much as possible to reduce the possibility of human error and forgetfulness.
 
-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.
+Automations that make use of sensitive credentials must use secure secret management, and must be strengthened against attacks such as [those on GitHub Actions workflows](https://github.com/nikitastupin/pwnhub).
 
-#### T2 - Tests Must not be Random
+Some other examples of automation are:
 
-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.
+- 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.
+
+  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.
+
+* 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 { ... }
+  }
+  ```
+
+* 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.
+
+  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.
+
+* 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.
+
+  ```solidity
+  function _burn(address who, uint256 value) internal {
+      super._burn(who, value);
+      emit TokensBurned(who, value);
+  }
+  ```
+
+  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.
+
+  ```solidity
+  interface IERC777 {
+  ```
+
+* Contracts not intended to be used standalone should be marked abstract
+  so they are required to be inherited to other contracts.
+
+  ```solidity
+  abstract contract AccessControl is ..., {
+  ```
+
+* Return values are generally not named, unless they are not immediately clear or there are multiple return values.
+
+  ```solidity
+  function expiration() public view returns (uint256) { // Good
+  function hasRole() public view returns (bool isMember, uint32 currentDelay) { // Good
+  ```
+
+* 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.
+
+* 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`).
+
+  * 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.
+
+  * 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-2019 zOS Global Limited
+Copyright (c) 2016-2025 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,64 +1,108 @@
-# <img src="logo.png" alt="OpenZeppelin" height="40px">
+# <img src="logo.svg" alt="OpenZeppelin" height="40px">
 
+[![Github Release](https://img.shields.io/github/v/tag/OpenZeppelin/openzeppelin-contracts.svg?filter=v*&sort=semver&label=github)](https://github.com/OpenZeppelin/openzeppelin-contracts/releases/latest)
 [![NPM Package](https://img.shields.io/npm/v/@openzeppelin/contracts.svg)](https://www.npmjs.org/package/@openzeppelin/contracts)
-[![Build Status](https://circleci.com/gh/OpenZeppelin/openzeppelin-contracts.svg?style=shield)](https://circleci.com/gh/OpenZeppelin/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://forum.openzeppelin.com/)
 
-**OpenZeppelin Contracts is a library for secure smart contract development.** It provides implementations of standards like ERC20 and ERC721 which you can deploy as-is or extend to suit your needs, as well as Solidity components to build custom contracts and more complex decentralized systems.
+**A library for secure smart contract development.** Build on a solid foundation of community-vetted code.
 
-## Install
+ * Implementations of standards like [ERC20](https://docs.openzeppelin.com/contracts/erc20) and [ERC721](https://docs.openzeppelin.com/contracts/erc721).
+ * Flexible [role-based permissioning](https://docs.openzeppelin.com/contracts/access-control) scheme.
+ * Reusable [Solidity components](https://docs.openzeppelin.com/contracts/utilities) to build custom contracts and complex decentralized systems.
+
+: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 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
+
+#### Hardhat (npm)
 
 ```
-npm install @openzeppelin/contracts
+$ npm install @openzeppelin/contracts
 ```
 
-OpenZeppelin Contracts features a stable API, which means your contracts won't break unexpectedly when upgrading to a newer minor version. You can read ṫhe details in our [API Stability] document.
+#### Foundry (git)
 
-## Usage
+> [!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.
 
-To write your custom contracts, import ours and extend them through inheritance.
+> [!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.5.0;
+pragma solidity ^0.8.20;
 
-import "@openzeppelin/contracts/token/ERC721/ERC721Full.sol";
-import "@openzeppelin/contracts/token/ERC721/ERC721Mintable.sol";
+import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
 
-contract MyNFT is ERC721Full, ERC721Mintable {
-  constructor() ERC721Full("MyNFT", "MNFT") public {
-  }
+contract MyCollectible is ERC721 {
+    constructor() ERC721("MyCollectible", "MCO") {
+    }
 }
 ```
 
-> You need an ethereum development framework for the above import statements to work! Check out these guides for [Truffle], [Embark] or [Buidler].
+_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._
 
-On our site you will find a few [guides] to learn about the different parts of OpenZeppelin, as well as [documentation for the API][API docs]. Keep in mind that the API docs are work in progress, and don’t hesitate to ask questions in [our forum][forum].
+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 [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).
+* [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' 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/), 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.
+* For a more in-depth dive, you may read the guide [Designing the Architecture for Your Ethereum Application](https://blog.openzeppelin.com/designing-the-architecture-for-your-ethereum-application-9cec086f8317), which discusses how to better structure your application and its relationship to the real world.
 
 ## Security
 
-This project is maintained by [OpenZeppelin], and developed following our high standards for code quality and security. OpenZeppelin 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 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.
 
-Please report any security issues you find to security@openzeppelin.org.
+The engineering guidelines we follow to promote project quality can be found in [`GUIDELINES.md`](./GUIDELINES.md).
+
+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
 
-OpenZeppelin exists thanks to its contributors. There are many ways you can participate and help build high quality software. Check out the [contribution guide]!
+OpenZeppelin Contracts exists thanks to its contributors. There are many ways you can participate and help build high quality software. Check out the [contribution guide](CONTRIBUTING.md)!
 
 ## License
 
-OpenZeppelin is released under the [MIT License](LICENSE).
+OpenZeppelin Contracts is released under the [MIT License](LICENSE).
 
+## Legal
 
-[API docs]: https://docs.openzeppelin.com/contracts/api/token/erc20
-[guides]: https://docs.openzeppelin.com/contracts
-[API Stability]: https://docs.openzeppelin.com/contracts/api-stability
-[forum]: https://forum.openzeppelin.com
-[OpenZeppelin]: https://openzeppelin.com
-[contribution guide]: CONTRIBUTING.md
-[Truffle]: https://truffleframework.com/docs/truffle/quickstart
-[Embark]: https://embark.status.im/docs/quick_start.html
-[Buidler]: https://buidler.dev/guides/#getting-started
+Your use of this Project is governed by the terms found at www.openzeppelin.com/tos (the "Terms").

RELEASING.md

@@ -1,99 +1,45 @@
 # Releasing
 
-This document describes our release process, and contains the steps to be followed by an OpenZeppelin maintainer at the several stages of a release.
+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 consistent and reliable.
 
-We release a new version of OpenZeppelin monthly. Release cycles are tracked in the [issue milestones](https://github.com/OpenZeppelin/openzeppelin-contracts/milestones).
+## Changesets
 
-Each release has at least one release candidate published first, intended for community review and any critical fixes that may come out of it. At the moment we leave 1 week between the first release candidate and the final release.
+[Changesets](https://github.com/changesets/changesets/) are 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.
 
-Before starting make sure to verify the following items.
-* Your local `master` branch is in sync with your `upstream` remote (it may have another name depending on your setup).
-* Your repo is clean, particularly with no untracked files in the contracts and tests directories. Verify with `git clean -n`.
+## Branching model
 
+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.
 
-## Creating the release branch
+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.
 
-We'll refer to a release `vX.Y.Z`.
+```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"
+
+    checkout release-vX.Y
+    cherry-pick id: "Fix A" tag: ""
+    commit id: "Release vX.Y.0-rc.1"
+    commit id: "Release vX.Y.0"
+
+    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 master
-git checkout -b release-vX.Y.Z
-```
-
-## Creating a release candidate
-
-Once in the release branch, change the version string in `package.json`, `package-lock.json` and `ethpm.json` to `X.Y.Z-rc.R`. (This will be `X.Y.Z-rc.1` for the first release candidate.) Commit these changes and tag the commit as `vX.Y.Z-rc.R`.
-
-```
-git add package.json package-lock.json ethpm.json
-git commit -m "Release candidate vX.Y.Z-rc.R"
-git tag -a vX.Y.Z-rc.R
-git push upstream release-vX.Y.Z
-git push upstream vX.Y.Z-rc.R
-```
-
-Draft the release notes in our [GitHub releases](https://github.com/OpenZeppelin/openzeppelin-contracts/releases). Make sure to mark it as a pre-release! Try to be consistent with our previous release notes in the title and format of the text. Release candidates don't need a detailed changelog, but make sure to include a link to GitHub's compare page.
-
-Once the CI run for the new tag is green, publish on npm under the `next` tag. You should see the contracts compile automatically.
-
-```
-npm publish --tag next
-```
-
-Publish the release notes on GitHub and the forum, and ask our community manager to announce the release candidate on at least Twitter.
-
-## Creating the final release
-
-Make sure to have the latest changes from `upstream` in your local release branch.
-
-```
-git checkout release-vX.Y.Z
-git pull upstream
-```
-
-Before starting the release process, make one final commit to CHANGELOG.md, including the date of the release.
-
-Change the version string in `package.json`, `package-lock.json` and `ethpm.json` removing the "-rc.R" suffix. Commit these changes and tag the commit as `vX.Y.Z`.
-
-```
-git add package.json package-lock.json ethpm.json
-git commit -m "Release vX.Y.Z"
-git tag -a vX.Y.Z
-git push upstream release-vX.Y.Z
-git push upstream vX.Y.Z
-```
-
-Draft the release notes in GitHub releases. Try to be consistent with our previous release notes in the title and format of the text. Make sure to include a detailed changelog.
-
-Once the CI run for the new tag is green, publish on npm. You should see the contracts compile automatically.
-
-```
-npm publish
-```
-
-Publish the release notes on GitHub and ask our community manager to announce the release!
-
-Delete the `next` tag in the npm package as there is no longer a release candidate.
-
-```
-npm dist-tag rm --otp $2FA_CODE @openzeppelin/contracts next
-```
-
-## Merging the release branch
-
-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.
-
-```
-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

@@ -0,0 +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
+
+Responsible disclosure of security vulnerabilities is rewarded through a bug bounty program on [Immunefi].
+
+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).
+
+## Security Patches
+
+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.
+
+[advisories]: https://github.com/OpenZeppelin/openzeppelin-contracts/security/advisories
+
+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
+
+Blockchain is a nascent technology and carries a high level of risk and uncertainty. OpenZeppelin makes certain software available under open source licenses, which disclaim all warranties in relation to the project and which limits the liability of OpenZeppelin. Subject to any particular licensing terms, your use of the project is governed by the terms found at [www.openzeppelin.com/tos](https://www.openzeppelin.com/tos) (the "Terms"). As set out in the Terms, you are solely responsible for any use of the project and you assume all risks associated with any such use. This Security Policy in no way evidences or represents an ongoing duty by any contributor, including OpenZeppelin, to correct any issues or vulnerabilities or alert you to all or any of the risks of utilizing the project.

audits/2017-03.md

@@ -1,5 +1,7 @@
 # OpenZeppelin Audit
 
+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
 
@@ -18,7 +20,7 @@ The git commit hash we evaluated is:
 
 # Disclaimer
 
-The audit makes no statements or warrantees about utility of the code, safety of the code, suitability of the business model, regulatory regime for the business model, or any other statements about fitness of the contracts to purpose, or their bugfree status. The audit documentation is for discussion purposes only.
+The audit makes no statements or warranties about utility of the code, safety of the code, suitability of the business model, regulatory regime for the business model, or any other statements about fitness of the contracts to purpose, or their bug free status. The audit documentation is for discussion purposes only.
 
 # Executive Summary
 
@@ -88,7 +90,7 @@ We are still working through the confirmation protocol in `Shareable.sol`, but w
 This bug has a number of causes that need to be addressed:
 
 1. `resetSpentToday` and `confirm` together do not limit the days on which the function can be called or (it appears) the number of times it can be called.
-1. Once a call has been confirmed and `execute`d it appears that it can be re-executed. This is not good.
+1. Once a call has been confirmed and executed it appears that it can be re-executed. This is not good.
 3. `confirmandCheck` doesn't seem to have logic about whether or not the function in question has been called.
 4. Even if it did, `revoke` would need updates and logic to deal with revocation requests after a function call had been completed.
 
@@ -107,7 +109,7 @@ It would be nice to see how many payments are pending. This would imply a bit of
 
 ## Shareable Contract
 
-We do not believe the `Shareable.sol` contract is ready for primetime. It is missing functions, and as written may be vulnerable to a reordering attack -- an attack in which a miner or other party "racing" with a smart contract participant inserts their own information into a list or mapping.
+We do not believe the `Shareable.sol` contract is ready for prime time. It is missing functions, and as written may be vulnerable to a reordering attack -- an attack in which a miner or other party "racing" with a smart contract participant inserts their own information into a list or mapping.
 
 The confirmation and revocation code needs to be looked over with a very careful eye imagining extraordinarily bad behavior by shared owners before this contract can be called safe.
 
@@ -131,7 +133,7 @@ I presume that the goal of this contract is to allow and annotate a migration to
 
 We like these pauses! Note that these allow significant griefing potential by owners, and that this might not be obvious to participants in smart contracts using the OpenZeppelin framework. We would recommend that additional sample logic be added to for instance the TokenContract showing safer use of the pause and resume functions. In particular, we would recommend a timelock after which anyone could unpause the contract.
 
-The modifers use the pattern `if(bool){_;}`. This is fine for functions that return false upon failure, but could be problematic for functions expected to throw upon failure. See our comments above on standardizing on `throw` or `return(false)`.
+The modifiers use the pattern `if(bool){_;}`. This is fine for functions that return false upon failure, but could be problematic for functions expected to throw upon failure. See our comments above on standardizing on `throw` or `return(false)`.
 
 ## Ownership
 
@@ -157,7 +159,7 @@ Allows owner to set a public string of contract information. No issues.
 
 This needs some work. Doesn't check if `_required <= len(_owners)` for instance, that would be a bummer. What if _required were like `MAX - 1`?
 
-I have a general concern about the difference between `owners`, `_owners`, and `owner` in `Ownable.sol`. I recommend "Owners" be renamed. In general we do not recomment single character differences in variable names, although a preceding underscore is not uncommon in Solidity code.
+I have a general concern about the difference between `owners`, `_owners`, and `owner` in `Ownable.sol`. I recommend "Owners" be renamed. In general we do not recommend single character differences in variable names, although a preceding underscore is not uncommon in Solidity code.
 
 Line 34: "this contract only has six types of events"...actually only two.
 
@@ -222,7 +224,7 @@ Transfer() and transferFrom() use SafeMath functions, which will cause them to t
 
 ### SimpleToken
 
-Sample instantiation of StandardToken. Note that in this sample, decimals is 18 and supply only 10,000, so the supply is a small fraction of a single nominal token.
+Sample instantiation of StandardToken. Note that in this sample, decimals is 18 and supply is only 10,000, so the supply is a small fraction of a single nominal token.
 
 ### CrowdsaleToken
 

audits/README.md

@@ -0,0 +1,20 @@
+# Audits
+
+| Date          | Version | Commit                                                                           | Auditor      | Scope                | Links                                                       |
+| ------------- | ------- | -------------------------------------------------------------------------------- | ------------ | -------------------- | ----------------------------------------------------------- |
+| April 2025    | v5.3.0  | [`d4b2e98`](https://github.com/openzeppelin/openzeppelin-contracts/tree/d4b2e98) | OpenZeppelin | v5.3 Changes         | [🔗](./2025-04-v5.3.pdf)                                    |
+| December 2024 | v5.2.0  | [`98d28f9`](https://github.com/openzeppelin/openzeppelin-contracts/tree/98d28f9) | OpenZeppelin | v5.2 Changes         | [🔗](./2024-12-v5.2.pdf)                                    |
+| October 2024  | v5.1.0  | [`aba9ff6`](https://github.com/openzeppelin/openzeppelin-contracts/tree/aba9ff6) | OpenZeppelin | v5.1 Changes         | [🔗](./2024-10-v5.1.pdf)                                    |
+| October 2023  | v5.0.0  | [`b5a3e69`](https://github.com/openzeppelin/openzeppelin-contracts/tree/b5a3e69) | OpenZeppelin | v5.0 Changes         | [🔗](./2023-10-v5.0.pdf)                                    |
+| May 2023      | v4.9.0  | [`91df66c`](https://github.com/openzeppelin/openzeppelin-contracts/tree/91df66c) | OpenZeppelin | v4.9 Changes         | [🔗](./2023-05-v4.9.pdf)                                    |
+| October 2022  | v4.8.0  | [`14f98db`](https://github.com/openzeppelin/openzeppelin-contracts/tree/14f98db) | OpenZeppelin | ERC4626, Checkpoints | [🔗](./2022-10-ERC4626.pdf) [🔗](./2022-10-Checkpoints.pdf) |
+| October 2018  | v2.0.0  | [`dac5bcc`](https://github.com/openzeppelin/openzeppelin-contracts/tree/dac5bcc) | LevelK       | Everything           | [🔗](./2018-10.pdf)                                         |
+| March 2017    | v1.0.4  | [`9c5975a`](https://github.com/openzeppelin/openzeppelin-contracts/tree/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

@@ -0,0 +1,54 @@
+default: help
+
+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)"
+
+clean:
+	git clean -fdX
+
+FORCE: ;

certora/README.md

@@ -0,0 +1,60 @@
+# Running the certora verification tool
+
+These instructions detail the process for running Certora Verification Tool on OpenZeppelin Contracts.
+
+Documentation for CVT and the specification language is 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 Certora Verification Tool proves specs for contracts, which are defined by the `./specs.json` file along with their pre-configured options.
+
+The verification script `./run.js` is used to submit verification jobs to the Certora Verification service.
+
+You can run it from the root of the repository with the following command:
+
+```bash
+node certora/run.js [[CONTRACT_NAME:]SPEC_NAME] [OPTIONS...]
+```
+
+Where:
+
+- `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.
+
+> **Note**
+> A single spec may be configured to run for multiple contracts, whereas a single contract may run multiple specs.
+
+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.
+
+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:
+
+```bash
+make -C certora apply
+```
+
+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/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/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];
+    }
+}

certora/harnesses/EnumerableSetHarness.sol

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {EnumerableSet} from "../patched/utils/structs/EnumerableSet.sol";
+
+contract EnumerableSetHarness {
+    using EnumerableSet for EnumerableSet.Bytes32Set;
+
+    EnumerableSet.Bytes32Set private _set;
+
+    function add(bytes32 value) public returns (bool) {
+        return _set.add(value);
+    }
+
+    function remove(bytes32 value) public returns (bool) {
+        return _set.remove(value);
+    }
+
+    function contains(bytes32 value) public view returns (bool) {
+        return _set.contains(value);
+    }
+
+    function length() public view returns (uint256) {
+        return _set.length();
+    }
+
+    function at_(uint256 index) public view returns (bytes32) {
+        return _set.at(index);
+    }
+
+    function _positionOf(bytes32 value) public view returns (uint256) {
+        return _set._inner._positions[value];
+    }
+}

certora/harnesses/InitializableHarness.sol

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Initializable} from "../patched/proxy/utils/Initializable.sol";
+
+contract InitializableHarness is Initializable {
+    function initialize()           public initializer      {}
+    function reinitialize(uint64 n) public reinitializer(n) {}
+    function disable()              public { _disableInitializers(); }
+
+    function nested_init_init()                       public initializer      { initialize();    }
+    function nested_init_reinit(uint64 m)             public initializer      { reinitialize(m); }
+    function nested_reinit_init(uint64 n)             public reinitializer(n) { initialize();    }
+    function nested_reinit_reinit(uint64 n, uint64 m) public reinitializer(n) { reinitialize(m); }
+
+    function version() public view returns (uint64) {
+        return _getInitializedVersion();
+    }
+
+    function initializing() public view returns (bool) {
+        return _isInitializing();
+    }
+}

certora/harnesses/NoncesHarness.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Nonces} from "../patched/utils/Nonces.sol";
+
+contract NoncesHarness is Nonces {
+    function useNonce(address account) external returns (uint256) {
+        return _useNonce(account);
+    }
+
+    function useCheckedNonce(address account, uint256 nonce) external {
+        _useCheckedNonce(account, nonce);
+    }
+}