diff --git a/.github/workflows/generate-api-docs-community-contracts.yml b/.github/workflows/generate-api-docs-community-contracts.yml index 01f4fd5d..0e4de49a 100644 --- a/.github/workflows/generate-api-docs-community-contracts.yml +++ b/.github/workflows/generate-api-docs-community-contracts.yml @@ -26,7 +26,10 @@ on: type: string default: 'commit' # TODO: Update if using tags -# TODO: Configure these environment variables for your contract +permissions: + contents: write + pull-requests: write + env: SOURCE_REPO: 'OpenZeppelin/openzeppelin-community-contracts' SOURCE_REPO_URL: 'https://github.com/OpenZeppelin/openzeppelin-community-contracts.git' @@ -105,6 +108,11 @@ jobs: --branch "${{ inputs.tag_name }}" \ --api-output "${{ steps.config.outputs.output-dir }}" + - name: Validate generated documentation + run: | + pnpm run postinstall + pnpm run lint:links + - name: Create Pull Request for documentation changes id: create_pr env: diff --git a/.github/workflows/generate-api-docs-confidential-contracts.yml b/.github/workflows/generate-api-docs-confidential-contracts.yml new file mode 100644 index 00000000..c9f17c25 --- /dev/null +++ b/.github/workflows/generate-api-docs-confidential-contracts.yml @@ -0,0 +1,165 @@ +# Docs Repository Receiver - Non-Versioned Paths +# Receives trigger from openzeppelin-confidential-contracts and generates API docs + +name: Generate API Docs - Confidential Contracts + +on: + workflow_dispatch: + inputs: + tag_name: + description: 'Tag name or commit SHA to generate docs from' + required: true + type: string + default: 'v0.4.0' + trigger_type: + description: 'Trigger type (tag or commit)' + required: false + type: string + default: 'tag' + +permissions: + contents: write + pull-requests: write + +env: + SOURCE_REPO: 'OpenZeppelin/openzeppelin-confidential-contracts' + SOURCE_REPO_URL: 'https://github.com/OpenZeppelin/openzeppelin-confidential-contracts.git' + BASE_OUTPUT_PATH: 'content/confidential-contracts' + USE_VERSIONED_PATHS: 'false' + +jobs: + generate-docs: + runs-on: ubuntu-latest + + steps: + - name: Log trigger information + run: | + echo "๐Ÿš€ API Documentation Generation Triggered" + echo "๐Ÿ“ฆ Repository: ${{ env.SOURCE_REPO }}" + echo "๐Ÿท๏ธ Tag/Ref: ${{ inputs.tag_name }}" + echo "๐Ÿ“‹ Trigger type: ${{ inputs.trigger_type }}" + + - name: Checkout docs repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Setup pnpm + uses: pnpm/action-setup@v4 + with: + version: 10.17.1 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Determine output directory + id: config + run: | + TAG_NAME="${{ inputs.tag_name }}" + TRIGGER_TYPE="${{ inputs.trigger_type }}" + BASE_PATH="${{ env.BASE_OUTPUT_PATH }}" + USE_VERSIONED="${{ env.USE_VERSIONED_PATHS }}" + + if [[ "$USE_VERSIONED" == "false" ]]; then + OUTPUT_DIR="${BASE_PATH}/api" + echo "๐Ÿ“ Using non-versioned path" + elif [[ "$TRIGGER_TYPE" == "commit" ]]; then + OUTPUT_DIR="${BASE_PATH}/latest/api" + echo "๐Ÿ”„ Using latest path for commit-based trigger" + else + if [[ "$TAG_NAME" =~ v([0-9]+) ]]; then + MAJOR_VERSION="${BASH_REMATCH[1]}" + OUTPUT_DIR="${BASE_PATH}/${MAJOR_VERSION}.x/api" + echo "๐Ÿ“Š Detected version: ${MAJOR_VERSION}.x" + else + OUTPUT_DIR="${BASE_PATH}/latest/api" + echo "โš ๏ธ Non-standard tag format, using latest" + fi + fi + + echo "๐Ÿ“‚ Output directory: $OUTPUT_DIR" + echo "output-dir=$OUTPUT_DIR" >> $GITHUB_OUTPUT + + - name: Generate API Documentation + run: | + echo "๐Ÿ”„ Generating API documentation..." + + node scripts/generate-api-docs.js \ + --repo "${{ env.SOURCE_REPO_URL }}" \ + --branch "${{ inputs.tag_name }}" \ + --api-output "${{ steps.config.outputs.output-dir }}" + + - name: Validate generated documentation + run: | + pnpm run postinstall + pnpm run lint:links + + - name: Create Pull Request for documentation changes + id: create_pr + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + git config --local user.email "docs-automation@openzeppelin.com" + git config --local user.name "OpenZeppelin Docs Bot" + + if [ -n "$(git status --porcelain)" ]; then + echo "๐Ÿ“ Creating branch and committing documentation changes..." + + BRANCH_NAME="docs/api-update-${{ env.SOURCE_REPO }}-${{ inputs.tag_name }}" + BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/\//-/g' | sed 's/OpenZeppelin-//g') + + git checkout -b "$BRANCH_NAME" + git add . + git commit -m "Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }} + + - Repository: ${{ env.SOURCE_REPO }} + - Ref: ${{ inputs.tag_name }} + - Trigger: ${{ inputs.trigger_type }} + - Output: ${{ steps.config.outputs.output-dir }} + - Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC') + + Auto-generated via workflow_dispatch" + + git push origin "$BRANCH_NAME" + + gh pr create --title "[CI] Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}" \ + --body "## API Documentation Update + + This Pull Request updates the API documentation. + + ### Source Information + - **Repository:** ${{ env.SOURCE_REPO }} + - **Reference:** ${{ inputs.tag_name }} + - **Trigger Type:** ${{ inputs.trigger_type }} + - **Output Directory:** ${{ steps.config.outputs.output-dir }} + - **Timestamp:** $(date -u '+%Y-%m-%d %H:%M:%S UTC') + + Auto-generated via workflow_dispatch" \ + --base main \ + --head "$BRANCH_NAME" || echo "โš ๏ธ Pull Request creation failed" + + echo "โœ… Pull Request created successfully" + echo "pr-created=true" >> $GITHUB_OUTPUT + else + echo "โ„น๏ธ No changes detected - documentation is up to date" + echo "pr-created=false" >> $GITHUB_OUTPUT + fi + + - name: Create job summary + run: | + echo "## ๐Ÿ“š API Documentation Generation Complete" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Source Information" >> $GITHUB_STEP_SUMMARY + echo "- **Repository:** ${{ env.SOURCE_REPO }}" >> $GITHUB_STEP_SUMMARY + echo "- **Reference:** ${{ inputs.tag_name }}" >> $GITHUB_STEP_SUMMARY + echo "- **Trigger Type:** ${{ inputs.trigger_type }}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Output" >> $GITHUB_STEP_SUMMARY + echo "- **Directory:** ${{ steps.config.outputs.output-dir }}" >> $GITHUB_STEP_SUMMARY + echo "- **Status:** โœ… Complete" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/generate-api-docs-contracts.yml b/.github/workflows/generate-api-docs-contracts.yml new file mode 100644 index 00000000..c1d9ad57 --- /dev/null +++ b/.github/workflows/generate-api-docs-contracts.yml @@ -0,0 +1,166 @@ +# Docs Repository Receiver - Versioned Paths +# Receives trigger from openzeppelin-contracts and generates API docs + +name: Generate API Docs - Contracts + +on: + workflow_dispatch: + inputs: + tag_name: + description: 'Tag name or commit SHA to generate docs from' + required: true + type: string + default: 'v5.6.1' + trigger_type: + description: 'Trigger type (tag or commit)' + required: false + type: string + default: 'tag' + +permissions: + contents: write + pull-requests: write + +env: + SOURCE_REPO: 'OpenZeppelin/openzeppelin-contracts' + SOURCE_REPO_URL: 'https://github.com/OpenZeppelin/openzeppelin-contracts.git' + BASE_OUTPUT_PATH: 'content/contracts' + USE_VERSIONED_PATHS: 'true' + +jobs: + generate-docs: + runs-on: ubuntu-latest + + steps: + - name: Log trigger information + run: | + echo "๐Ÿš€ API Documentation Generation Triggered" + echo "๐Ÿ“ฆ Repository: ${{ env.SOURCE_REPO }}" + echo "๐Ÿท๏ธ Tag/Ref: ${{ inputs.tag_name }}" + echo "๐Ÿ“‹ Trigger type: ${{ inputs.trigger_type }}" + + - name: Checkout docs repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Setup pnpm + uses: pnpm/action-setup@v4 + with: + version: 10.17.1 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Determine output directory + id: config + run: | + TAG_NAME="${{ inputs.tag_name }}" + TRIGGER_TYPE="${{ inputs.trigger_type }}" + BASE_PATH="${{ env.BASE_OUTPUT_PATH }}" + USE_VERSIONED="${{ env.USE_VERSIONED_PATHS }}" + + if [[ "$USE_VERSIONED" == "false" ]]; then + OUTPUT_DIR="${BASE_PATH}/api" + echo "๐Ÿ“ Using non-versioned path" + elif [[ "$TRIGGER_TYPE" == "commit" ]]; then + OUTPUT_DIR="${BASE_PATH}/latest/api" + echo "๐Ÿ”„ Using latest path for commit-based trigger" + else + # Extract major version from tag (v5.6.1 -> 5, v5.6.0 -> 5) + if [[ "$TAG_NAME" =~ v([0-9]+) ]]; then + MAJOR_VERSION="${BASH_REMATCH[1]}" + OUTPUT_DIR="${BASE_PATH}/${MAJOR_VERSION}.x/api" + echo "๐Ÿ“Š Detected version: ${MAJOR_VERSION}.x" + else + OUTPUT_DIR="${BASE_PATH}/latest/api" + echo "โš ๏ธ Non-standard tag format, using latest" + fi + fi + + echo "๐Ÿ“‚ Output directory: $OUTPUT_DIR" + echo "output-dir=$OUTPUT_DIR" >> $GITHUB_OUTPUT + + - name: Generate API Documentation + run: | + echo "๐Ÿ”„ Generating API documentation..." + + node scripts/generate-api-docs.js \ + --repo "${{ env.SOURCE_REPO_URL }}" \ + --branch "${{ inputs.tag_name }}" \ + --api-output "${{ steps.config.outputs.output-dir }}" + + - name: Validate generated documentation + run: | + pnpm run postinstall + pnpm run lint:links + + - name: Create Pull Request for documentation changes + id: create_pr + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + git config --local user.email "docs-automation@openzeppelin.com" + git config --local user.name "OpenZeppelin Docs Bot" + + if [ -n "$(git status --porcelain)" ]; then + echo "๐Ÿ“ Creating branch and committing documentation changes..." + + BRANCH_NAME="docs/api-update-${{ env.SOURCE_REPO }}-${{ inputs.tag_name }}" + BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/\//-/g' | sed 's/OpenZeppelin-//g') + + git checkout -b "$BRANCH_NAME" + git add . + git commit -m "Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }} + + - Repository: ${{ env.SOURCE_REPO }} + - Ref: ${{ inputs.tag_name }} + - Trigger: ${{ inputs.trigger_type }} + - Output: ${{ steps.config.outputs.output-dir }} + - Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC') + + Auto-generated via workflow_dispatch" + + git push origin "$BRANCH_NAME" + + gh pr create --title "[CI] Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}" \ + --body "## API Documentation Update + + This Pull Request updates the API documentation. + + ### Source Information + - **Repository:** ${{ env.SOURCE_REPO }} + - **Reference:** ${{ inputs.tag_name }} + - **Trigger Type:** ${{ inputs.trigger_type }} + - **Output Directory:** ${{ steps.config.outputs.output-dir }} + - **Timestamp:** $(date -u '+%Y-%m-%d %H:%M:%S UTC') + + Auto-generated via workflow_dispatch" \ + --base main \ + --head "$BRANCH_NAME" || echo "โš ๏ธ Pull Request creation failed" + + echo "โœ… Pull Request created successfully" + echo "pr-created=true" >> $GITHUB_OUTPUT + else + echo "โ„น๏ธ No changes detected - documentation is up to date" + echo "pr-created=false" >> $GITHUB_OUTPUT + fi + + - name: Create job summary + run: | + echo "## ๐Ÿ“š API Documentation Generation Complete" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Source Information" >> $GITHUB_STEP_SUMMARY + echo "- **Repository:** ${{ env.SOURCE_REPO }}" >> $GITHUB_STEP_SUMMARY + echo "- **Reference:** ${{ inputs.tag_name }}" >> $GITHUB_STEP_SUMMARY + echo "- **Trigger Type:** ${{ inputs.trigger_type }}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Output" >> $GITHUB_STEP_SUMMARY + echo "- **Directory:** ${{ steps.config.outputs.output-dir }}" >> $GITHUB_STEP_SUMMARY + echo "- **Status:** โœ… Complete" >> $GITHUB_STEP_SUMMARY diff --git a/.gitignore b/.gitignore index f6be50b5..aa877a79 100644 --- a/.gitignore +++ b/.gitignore @@ -26,6 +26,9 @@ yarn-error.log* package-lock.json yarn.lock +# temp dirs from generate-api-docs.js +temp-*/ + # others .env*.local .vercel diff --git a/README.md b/README.md index 6dcab4a1..84b491fb 100644 --- a/README.md +++ b/README.md @@ -61,49 +61,88 @@ docs/ For detailed information about the codebase structure, navigation system, and component architecture, see [CONTRIBUTING.md](CONTRIBUTING.md) -## Solidity Docgen +## API Reference Generation -Any library using Solidity Docgen can utilize the `docgen` templates and config file in their repo to generate markdown API references for the docs. To get started follow the instructions below: +API reference pages are auto-generated from source contract repositories and placed in the `content/` directory. The generation is handled by `scripts/generate-api-docs.js`, which supports two modes depending on the source repo's language. -### 1. Add the templates to your repo +### Solidity Repos -Inside this docs repo is the [`docgen`](https://github.com/OpenZeppelin/docs/tree/main/docgen) folder which contains [`templates-md`](https://github.com/OpenZeppelin/docs/tree/main/docgen/templates-md) and [`config-md.js`](https://github.com/OpenZeppelin/docs/blob/main/docgen/config-md.js). Copy both of these items into your `docs` folder in your repo. Once there open the [`templates-md/helpers.js`](https://github.com/OpenZeppelin/docs/blob/main/docgen/templates-md/helpers.js) file and update the `API_DOCS_PATH` constant to match your export path. Also open [`templates-md/contract.hbs`](https://github.com/OpenZeppelin/docs/blob/main/docgen/templates-md/contract.hbs) to modify the solidity import path and the github link. +For Solidity repos using [solidity-docgen](https://github.com/OpenZeppelin/solidity-docgen), the script **injects canonical MDX templates** from this repo's [`docgen/templates-md/`](https://github.com/OpenZeppelin/docs/tree/main/docgen/templates-md) into the cloned source repo before running docgen. Source repos do not need MDX templates committed. -```js -const API_DOCS_PATH = 'contracts/5.x/api'; -// const API_DOCS_PATH = 'community-contracts/api'; -// const API_DOCS_PATH = 'confidential-contracts/api'; -// const API_DOCS_PATH = 'uniswap-hooks/api'; -``` +The script automatically: +- Copies `docgen/templates-md/` and `docgen/config-md.js` into the source repo +- Sets `API_DOCS_PATH` based on the output directory +- Updates the GitHub source link and import path for the source repo +- Patches `hardhat.config.js` to use the MDX config +- Runs `npm run prepare-docs` to generate MDX files +- Copies the output to the specified `content/` directory -### 2. Update the `hardhat.config.js` file +**Run locally:** -With the `config-md.js` file now in the `docs` folder, update your `hardhat.config.js` to use the new config file. +```bash +# openzeppelin-contracts +node scripts/generate-api-docs.js \ + --repo https://github.com/OpenZeppelin/openzeppelin-contracts.git \ + --branch v5.6.1 \ + --api-output content/contracts/5.x/api -```js -{ - // other config options - docgen: require('./docs/config-md'), -} -``` +# community-contracts +node scripts/generate-api-docs.js \ + --repo https://github.com/OpenZeppelin/openzeppelin-community-contracts.git \ + --branch master \ + --api-output content/community-contracts/api -Once added make sure these are accessible in your branches going forward. If you are generating an API reference for previous branches you will need to repeat steps 1 and 2 for those branches. +# confidential-contracts +node scripts/generate-api-docs.js \ + --repo https://github.com/OpenZeppelin/openzeppelin-confidential-contracts.git \ + --branch v0.4.0 \ + --api-output content/confidential-contracts/api +``` -### 3. Run the `generate-api-docs.js` script +### Non-Solidity Repos -With your remote repo setup with the new template files you can run the `scripts/generate-api-docs.js` script. Be sure to pass in the correct arguements for your docs +For repos using other languages (Cairo, Move, Rust, etc.) that generate MDX through their own tooling, use the `--pre-generated` flag to skip docgen and copy pre-built MDX files directly: ```bash node scripts/generate-api-docs.js \ - --repo https://github.com/OpenZeppelin/openzeppelin-community-contracts.git \ - --branch release-v5.5 \ - --api-output content/contracts/5.x/api \ - --examples-output examples + --repo https://github.com/OpenZeppelin/cairo-contracts.git \ + --branch v3.0.0 \ + --api-output content/contracts-cairo/3.x/api \ + --pre-generated docs/api ``` -### Automated Setup +### Canonical Templates + +The MDX templates that control API reference output live in [`docgen/templates-md/`](https://github.com/OpenZeppelin/docs/tree/main/docgen/templates-md): + +- `helpers.js` - Reference resolution, link generation, callout processing, natspec handling +- `contract.hbs` - Contract page layout (heading, GitHub link, import, function/event/error cards) +- `page.hbs` - Page wrapper with frontmatter +- `properties.js` - Solidity AST property helpers (anchors, inheritance, function lists) +- `config-md.js` - Solidity docgen configuration + +Changes to these templates affect all source repos on the next generation run. + +### Automated Workflow + +The generation runs automatically via GitHub Actions: + +1. **Source repo** pushes a release tag (e.g., `v5.6.1`) or commits to a tracked branch +2. **Source trigger workflow** (`.github/workflows/docs.yml` in the source repo) calls this repo's receiver workflow via `gh workflow run` +3. **Receiver workflow** (`.github/workflows/generate-api-docs-{name}.yml`) runs `generate-api-docs.js`, validates links, and creates a PR + +Receiver workflows in this repo: +- `generate-api-docs-contracts.yml` - versioned paths (`content/contracts/{major}.x/api`) +- `generate-api-docs-community-contracts.yml` - non-versioned (`content/community-contracts/api`) +- `generate-api-docs-confidential-contracts.yml` - non-versioned (`content/confidential-contracts/api`) + +Source repos need a `DOCS_REPO_TOKEN` secret (GitHub PAT with `repo` + `workflow` scopes) for the trigger workflow to call this repo. + +### Versioning -In the case you want to setup an automated GitHub workflow to create these API docs visit the [docs-api-generation-workflows](https://github.com/OpenZeppelin/docs-api-generation-workflows) for more info. This repo (`OpenZeppelin/docs`) is the `Docs Receiver` side of the equation. +- Major version changes (e.g., 4.x to 5.x) create a new versioned directory +- Minor and patch releases within a major version regenerate the same directory +- Non-versioned repos (community-contracts, confidential-contracts) use a flat `api/` path ## Content Management diff --git a/content/community-contracts/api/access.mdx b/content/community-contracts/api/access.mdx index 6f9659b3..3280f887 100644 --- a/content/community-contracts/api/access.mdx +++ b/content/community-contracts/api/access.mdx @@ -15,16 +15,16 @@ This directory contains utility contracts to restrict access control in smart co
-## `AccessManagerLight` +## `AccessManagerLight` - +
```solidity -import "@openzeppelin/community-contracts/access/manager/AccessManagerLight.sol"; +import "@openzeppelin/community-contracts/contracts/access/manager/AccessManagerLight.sol"; ``` Light version of an AccessManager contract that defines `bytes8` roles @@ -64,7 +64,6 @@ manage the roles of other users. - [PUBLIC_ROLE()](#AccessManagerLight-PUBLIC_ROLE-uint8) - [ADMIN_MASK()](#AccessManagerLight-ADMIN_MASK-Masks-Mask) - [PUBLIC_MASK()](#AccessManagerLight-PUBLIC_MASK-Masks-Mask) -#### IAuthority [!toc] @@ -75,7 +74,6 @@ manage the roles of other users. - [GroupRemoved(user, group)](#AccessManagerLight-GroupRemoved-address-uint8-) - [GroupAdmins(group, admins)](#AccessManagerLight-GroupAdmins-uint8-Masks-Mask-) - [RequirementsSet(target, selector, groups)](#AccessManagerLight-RequirementsSet-address-bytes4-Masks-Mask-) -#### IAuthority [!toc] @@ -83,7 +81,6 @@ manage the roles of other users.

Errors

- [MissingPermissions(user, permissions, requirement)](#AccessManagerLight-MissingPermissions-address-Masks-Mask-Masks-Mask-) -#### IAuthority [!toc]
@@ -461,3 +458,4 @@ Internal version of [`AccessManagerLight._setRequirements`](#AccessManagerLight- + diff --git a/content/community-contracts/api/account.mdx b/content/community-contracts/api/account.mdx index 6fe89546..bc1f6c66 100644 --- a/content/community-contracts/api/account.mdx +++ b/content/community-contracts/api/account.mdx @@ -60,22 +60,22 @@ This directory includes contracts to build accounts for ERC-4337. These include:
-## `ERC7579DelayedExecutor` +## `ERC7579DelayedExecutor` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579DelayedExecutor.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579DelayedExecutor.sol"; ``` Extension of [`ERC7579Executor`](#ERC7579Executor) that allows scheduling and executing delayed operations with expiration. This module enables time-delayed execution patterns for smart accounts. -==== Operation Lifecycle +#### Operation Lifecycle 1. Scheduling: Operations are scheduled via [`ERC7579DelayedExecutor.schedule`](#ERC7579DelayedExecutor-schedule-address-bytes32-bytes32-bytes-) with a specified delay period. The delay period is set during [`ERC7579DelayedExecutor.onInstall`](#ERC7579DelayedExecutor-onInstall-bytes-) and can be customized via [`ERC7579DelayedExecutor.setDelay`](#ERC7579DelayedExecutor-setDelay-uint32-). Each @@ -90,7 +90,7 @@ Operations can be executed via [`ERC7579Executor.execute`](#ERC7579Executor-exec executable. If an operation is not executed within the expiration period, it becomes `Expired` and can't be executed. Expired operations must be rescheduled with a different salt. -==== Delay Management +#### Delay Management Accounts can set their own delay periods during installation or via [`ERC7579DelayedExecutor.setDelay`](#ERC7579DelayedExecutor-setDelay-uint32-). The delay period is enforced even between installas and uninstalls to prevent @@ -98,7 +98,7 @@ immediate downgrades. When setting a new delay period, the new delay takes effec after a transition period defined by the current delay or [`ERC7579DelayedExecutor.minSetback`](#ERC7579DelayedExecutor-minSetback--), whichever is longer. -==== Authorization +#### Authorization Authorization for scheduling and canceling operations is controlled through the [`ERC7579DelayedExecutor._validateSchedule`](#ERC7579DelayedExecutor-_validateSchedule-address-bytes32-bytes32-bytes-) and [`ERC7579DelayedExecutor._validateCancel`](#ERC7579DelayedExecutor-_validateCancel-address-bytes32-bytes32-bytes-) functions. These functions can be overridden to implement custom @@ -137,10 +137,13 @@ useful to pre-schedule operations for non-deployed accounts (e.g. subscriptions) - [_cancel(account, mode, executionCalldata, salt)](#ERC7579DelayedExecutor-_cancel-address-bytes32-bytes-bytes32-) - [_validateStateBitmap(operationId, allowedStates)](#ERC7579DelayedExecutor-_validateStateBitmap-bytes32-bytes32-) - [_encodeStateBitmap(operationState)](#ERC7579DelayedExecutor-_encodeStateBitmap-enum-ERC7579DelayedExecutor-OperationState-) -#### ERC7579Executor [!toc] +
+ERC7579Executor + - [isModuleType(moduleTypeId)](#ERC7579Executor-isModuleType-uint256-) - [execute(account, salt, mode, data)](#ERC7579Executor-execute-address-bytes32-bytes32-bytes-) -#### IERC7579Module [!toc] + +
@@ -151,9 +154,12 @@ useful to pre-schedule operations for non-deployed accounts (e.g. subscriptions) - [ERC7579ExecutorOperationCanceled(account, operationId)](#ERC7579DelayedExecutor-ERC7579ExecutorOperationCanceled-address-bytes32-) - [ERC7579ExecutorDelayUpdated(account, newDelay, effectTime)](#ERC7579DelayedExecutor-ERC7579ExecutorDelayUpdated-address-uint32-uint48-) - [ERC7579ExecutorExpirationUpdated(account, newExpiration)](#ERC7579DelayedExecutor-ERC7579ExecutorExpirationUpdated-address-uint32-) -#### ERC7579Executor [!toc] +
+ERC7579Executor + - [ERC7579ExecutorOperationExecuted(account, salt, mode, executionCalldata)](#ERC7579Executor-ERC7579ExecutorOperationExecuted-address-bytes32-bytes32-bytes-) -#### IERC7579Module [!toc] + +
@@ -162,8 +168,6 @@ useful to pre-schedule operations for non-deployed accounts (e.g. subscriptions)
- [ERC7579ExecutorUnexpectedOperationState(operationId, currentState, allowedStates)](#ERC7579DelayedExecutor-ERC7579ExecutorUnexpectedOperationState-bytes32-enum-ERC7579DelayedExecutor-OperationState-bytes32-) - [ERC7579ExecutorModuleNotInstalled()](#ERC7579DelayedExecutor-ERC7579ExecutorModuleNotInstalled--) -#### ERC7579Executor [!toc] -#### IERC7579Module [!toc]
@@ -795,16 +799,16 @@ The module is not installed on the account.
-## `ERC7579Executor` +## `ERC7579Executor` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579Executor.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579Executor.sol"; ``` Basic implementation for ERC-7579 executor modules that provides execution functionality @@ -828,9 +832,13 @@ security features, see [`ERC7579DelayedExecutor`](#ERC7579DelayedExecutor). - [execute(account, salt, mode, data)](#ERC7579Executor-execute-address-bytes32-bytes32-bytes-) - [_validateExecution(account, salt, mode, data)](#ERC7579Executor-_validateExecution-address-bytes32-bytes32-bytes-) - [_execute(account, mode, salt, executionCalldata)](#ERC7579Executor-_execute-address-bytes32-bytes32-bytes-) -#### IERC7579Module [!toc] +
+IERC7579Module + - [onInstall(data)](#IERC7579Module-onInstall-bytes-) - [onUninstall(data)](#IERC7579Module-onUninstall-bytes-) + +
@@ -838,7 +846,6 @@ security features, see [`ERC7579DelayedExecutor`](#ERC7579DelayedExecutor).

Events

- [ERC7579ExecutorOperationExecuted(account, salt, mode, executionCalldata)](#ERC7579Executor-ERC7579ExecutorOperationExecuted-address-bytes32-bytes32-bytes-) -#### IERC7579Module [!toc]
@@ -958,16 +965,16 @@ Emitted when an operation is executed.
-## `ERC7579Multisig` +## `ERC7579Multisig` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579Multisig.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579Multisig.sol"; ``` Implementation of an [`ERC7579Validator`](#ERC7579Validator) that uses ERC-7913 signers for multisignature @@ -1001,12 +1008,14 @@ a social recovery operation. - [_validateReachableThreshold(account)](#ERC7579Multisig-_validateReachableThreshold-address-) - [_validateSignatures(account, hash, signingSigners, signatures)](#ERC7579Multisig-_validateSignatures-address-bytes32-bytes---bytes---) - [_validateThreshold(account, validatingSigners)](#ERC7579Multisig-_validateThreshold-address-bytes---) -#### ERC7579Validator [!toc] +
+ERC7579Validator + - [isModuleType(moduleTypeId)](#ERC7579Validator-isModuleType-uint256-) - [validateUserOp(userOp, userOpHash)](#ERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-) - [isValidSignatureWithSender(, hash, signature)](#ERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-) -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -1016,9 +1025,6 @@ a social recovery operation. - [ERC7913SignerAdded(account, signer)](#ERC7579Multisig-ERC7913SignerAdded-address-bytes-) - [ERC7913SignerRemoved(account, signer)](#ERC7579Multisig-ERC7913SignerRemoved-address-bytes-) - [ERC7913ThresholdSet(account, threshold)](#ERC7579Multisig-ERC7913ThresholdSet-address-uint64-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] @@ -1030,9 +1036,6 @@ a social recovery operation. - [ERC7579MultisigInvalidSigner(signer)](#ERC7579Multisig-ERC7579MultisigInvalidSigner-bytes-) - [ERC7579MultisigZeroThreshold()](#ERC7579Multisig-ERC7579MultisigZeroThreshold--) - [ERC7579MultisigUnreachableThreshold(signers, threshold)](#ERC7579Multisig-ERC7579MultisigUnreachableThreshold-uint64-uint64-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] @@ -1338,7 +1341,7 @@ Requirements:
-Validates the current threshold is reachable with the number of [`ERC7579Multisig._signersSetByAccount`](#ERC7579Multisig-_signersSetByAccount-mapping-address----struct-EnumerableSet-BytesSet-). +Validates the current threshold is reachable with the number of `signers`. Requirements: @@ -1532,16 +1535,16 @@ The `threshold` is unreachable given the number of `signers`.
-## `ERC7579MultisigConfirmation` +## `ERC7579MultisigConfirmation` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579MultisigConfirmation.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579MultisigConfirmation.sol"; ``` Extension of [`ERC7579Multisig`](#ERC7579Multisig) that requires explicit confirmation signatures @@ -1561,14 +1564,19 @@ explicitly agreed to their roles.
- [_signableConfirmationHash(account, deadline)](#ERC7579MultisigConfirmation-_signableConfirmationHash-address-uint256-) - [_addSigners(account, newSigners)](#ERC7579MultisigConfirmation-_addSigners-address-bytes---) -#### EIP712 [!toc] +
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC7579Multisig [!toc] + +
+
+ERC7579Multisig + - [onInstall(initData)](#ERC7579Multisig-onInstall-bytes-) - [onUninstall()](#ERC7579Multisig-onUninstall-bytes-) - [getSigners(account, start, end)](#ERC7579Multisig-getSigners-address-uint64-uint64-) @@ -1584,28 +1592,36 @@ explicitly agreed to their roles. - [_validateReachableThreshold(account)](#ERC7579Multisig-_validateReachableThreshold-address-) - [_validateSignatures(account, hash, signingSigners, signatures)](#ERC7579Multisig-_validateSignatures-address-bytes32-bytes---bytes---) - [_validateThreshold(account, validatingSigners)](#ERC7579Multisig-_validateThreshold-address-bytes---) -#### ERC7579Validator [!toc] + +
+
+ERC7579Validator + - [isModuleType(moduleTypeId)](#ERC7579Validator-isModuleType-uint256-) - [validateUserOp(userOp, userOpHash)](#ERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-) - [isValidSignatureWithSender(, hash, signature)](#ERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-) -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +

Events

-#### EIP712 [!toc] -#### IERC5267 [!toc] +
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC7579Multisig [!toc] + +
+
+ERC7579Multisig + - [ERC7913SignerAdded(account, signer)](#ERC7579Multisig-ERC7913SignerAdded-address-bytes-) - [ERC7913SignerRemoved(account, signer)](#ERC7579Multisig-ERC7913SignerRemoved-address-bytes-) - [ERC7913ThresholdSet(account, threshold)](#ERC7579Multisig-ERC7913ThresholdSet-address-uint64-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -1614,17 +1630,16 @@ explicitly agreed to their roles.
- [ERC7579MultisigInvalidConfirmationSignature(signer)](#ERC7579MultisigConfirmation-ERC7579MultisigInvalidConfirmationSignature-bytes-) - [ERC7579MultisigExpiredConfirmation(deadline)](#ERC7579MultisigConfirmation-ERC7579MultisigExpiredConfirmation-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC7579Multisig [!toc] +
+ERC7579Multisig + - [ERC7579MultisigAlreadyExists(signer)](#ERC7579Multisig-ERC7579MultisigAlreadyExists-bytes-) - [ERC7579MultisigNonexistentSigner(signer)](#ERC7579Multisig-ERC7579MultisigNonexistentSigner-bytes-) - [ERC7579MultisigInvalidSigner(signer)](#ERC7579Multisig-ERC7579MultisigInvalidSigner-bytes-) - [ERC7579MultisigZeroThreshold()](#ERC7579Multisig-ERC7579MultisigZeroThreshold--) - [ERC7579MultisigUnreachableThreshold(signers, threshold)](#ERC7579Multisig-ERC7579MultisigUnreachableThreshold-uint64-uint64-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -1711,16 +1726,16 @@ Error thrown when a confirmation signature has expired
-## `ERC7579MultisigStorage` +## `ERC7579MultisigStorage` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579MultisigStorage.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579MultisigStorage.sol"; ``` Extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows storing presigned approvals in storage. @@ -1739,7 +1754,9 @@ and the validation will check the storage mapping instead of cryptographic verif - [presigned(account, signer, hash)](#ERC7579MultisigStorage-presigned-address-bytes-bytes32-) - [presign(account, signer, hash, signature)](#ERC7579MultisigStorage-presign-address-bytes-bytes32-bytes-) - [_validateSignatures(account, hash, signingSigners, signatures)](#ERC7579MultisigStorage-_validateSignatures-address-bytes32-bytes---bytes---) -#### ERC7579Multisig [!toc] +
+ERC7579Multisig + - [onInstall(initData)](#ERC7579Multisig-onInstall-bytes-) - [onUninstall()](#ERC7579Multisig-onUninstall-bytes-) - [getSigners(account, start, end)](#ERC7579Multisig-getSigners-address-uint64-uint64-) @@ -1755,12 +1772,16 @@ and the validation will check the storage mapping instead of cryptographic verif - [_setThreshold(account, newThreshold)](#ERC7579Multisig-_setThreshold-address-uint64-) - [_validateReachableThreshold(account)](#ERC7579Multisig-_validateReachableThreshold-address-) - [_validateThreshold(account, validatingSigners)](#ERC7579Multisig-_validateThreshold-address-bytes---) -#### ERC7579Validator [!toc] + +
+
+ERC7579Validator + - [isModuleType(moduleTypeId)](#ERC7579Validator-isModuleType-uint256-) - [validateUserOp(userOp, userOpHash)](#ERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-) - [isValidSignatureWithSender(, hash, signature)](#ERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-) -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -1768,28 +1789,30 @@ and the validation will check the storage mapping instead of cryptographic verif

Events

- [ERC7579MultisigStoragePresigned(account, hash, signer)](#ERC7579MultisigStorage-ERC7579MultisigStoragePresigned-address-bytes32-bytes-) -#### ERC7579Multisig [!toc] +
+ERC7579Multisig + - [ERC7913SignerAdded(account, signer)](#ERC7579Multisig-ERC7913SignerAdded-address-bytes-) - [ERC7913SignerRemoved(account, signer)](#ERC7579Multisig-ERC7913SignerRemoved-address-bytes-) - [ERC7913ThresholdSet(account, threshold)](#ERC7579Multisig-ERC7913ThresholdSet-address-uint64-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +

Errors

-#### ERC7579Multisig [!toc] +
+ERC7579Multisig + - [ERC7579MultisigAlreadyExists(signer)](#ERC7579Multisig-ERC7579MultisigAlreadyExists-bytes-) - [ERC7579MultisigNonexistentSigner(signer)](#ERC7579Multisig-ERC7579MultisigNonexistentSigner-bytes-) - [ERC7579MultisigInvalidSigner(signer)](#ERC7579Multisig-ERC7579MultisigInvalidSigner-bytes-) - [ERC7579MultisigZeroThreshold()](#ERC7579Multisig-ERC7579MultisigZeroThreshold--) - [ERC7579MultisigUnreachableThreshold(signers, threshold)](#ERC7579Multisig-ERC7579MultisigUnreachableThreshold-uint64-uint64-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -1851,7 +1874,7 @@ invalid signers won't be executable. See [`ERC7579Multisig._validateSignatures`] See [`ERC7579Multisig._validateSignatures`](#ERC7579Multisig-_validateSignatures-address-bytes32-bytes---bytes---). If a signature is empty, it indicates a presignature and the validation will check the storage mapping -instead of cryptographic verification. See [`ERC7579Multisig._signersSetByAccount`](#ERC7579Multisig-_signersSetByAccount-mapping-address----struct-EnumerableSet-BytesSet-) for more details. +instead of cryptographic verification. See `sign` for more details. @@ -1878,16 +1901,16 @@ Emitted when a signer signs a hash
-## `ERC7579MultisigWeighted` +## `ERC7579MultisigWeighted` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579MultisigWeighted.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579MultisigWeighted.sol"; ``` Extension of [`ERC7579Multisig`](#ERC7579Multisig) that supports weighted signatures. @@ -1922,7 +1945,9 @@ signatures with a total weight of at least 4 (e.g., one with weight 1 and one wi - [_removeSigners(account, oldSigners)](#ERC7579MultisigWeighted-_removeSigners-address-bytes---) - [_validateReachableThreshold(account)](#ERC7579MultisigWeighted-_validateReachableThreshold-address-) - [_validateThreshold(account, validatingSigners)](#ERC7579MultisigWeighted-_validateThreshold-address-bytes---) -#### ERC7579Multisig [!toc] +
+ERC7579Multisig + - [getSigners(account, start, end)](#ERC7579Multisig-getSigners-address-uint64-uint64-) - [getSignerCount(account)](#ERC7579Multisig-getSignerCount-address-) - [isSigner(account, signer)](#ERC7579Multisig-isSigner-address-bytes-) @@ -1933,12 +1958,16 @@ signatures with a total weight of at least 4 (e.g., one with weight 1 and one wi - [_rawERC7579Validation(account, hash, signature)](#ERC7579Multisig-_rawERC7579Validation-address-bytes32-bytes-) - [_setThreshold(account, newThreshold)](#ERC7579Multisig-_setThreshold-address-uint64-) - [_validateSignatures(account, hash, signingSigners, signatures)](#ERC7579Multisig-_validateSignatures-address-bytes32-bytes---bytes---) -#### ERC7579Validator [!toc] + +
+
+ERC7579Validator + - [isModuleType(moduleTypeId)](#ERC7579Validator-isModuleType-uint256-) - [validateUserOp(userOp, userOpHash)](#ERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-) - [isValidSignatureWithSender(, hash, signature)](#ERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-) -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -1946,13 +1975,14 @@ signatures with a total weight of at least 4 (e.g., one with weight 1 and one wi

Events

- [ERC7579MultisigWeightChanged(account, signer, weight)](#ERC7579MultisigWeighted-ERC7579MultisigWeightChanged-address-bytes-uint64-) -#### ERC7579Multisig [!toc] +
+ERC7579Multisig + - [ERC7913SignerAdded(account, signer)](#ERC7579Multisig-ERC7913SignerAdded-address-bytes-) - [ERC7913SignerRemoved(account, signer)](#ERC7579Multisig-ERC7913SignerRemoved-address-bytes-) - [ERC7913ThresholdSet(account, threshold)](#ERC7579Multisig-ERC7913ThresholdSet-address-uint64-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -1961,15 +1991,16 @@ signatures with a total weight of at least 4 (e.g., one with weight 1 and one wi
- [ERC7579MultisigInvalidWeight(signer, weight)](#ERC7579MultisigWeighted-ERC7579MultisigInvalidWeight-bytes-uint64-) - [ERC7579MultisigMismatchedLength()](#ERC7579MultisigWeighted-ERC7579MultisigMismatchedLength--) -#### ERC7579Multisig [!toc] +
+ERC7579Multisig + - [ERC7579MultisigAlreadyExists(signer)](#ERC7579Multisig-ERC7579MultisigAlreadyExists-bytes-) - [ERC7579MultisigNonexistentSigner(signer)](#ERC7579Multisig-ERC7579MultisigNonexistentSigner-bytes-) - [ERC7579MultisigInvalidSigner(signer)](#ERC7579Multisig-ERC7579MultisigInvalidSigner-bytes-) - [ERC7579MultisigZeroThreshold()](#ERC7579Multisig-ERC7579MultisigZeroThreshold--) - [ERC7579MultisigUnreachableThreshold(signers, threshold)](#ERC7579Multisig-ERC7579MultisigUnreachableThreshold-uint64-uint64-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -2250,16 +2281,16 @@ Thrown when the arrays lengths don't match.
-## `ERC7579SelectorExecutor` +## `ERC7579SelectorExecutor` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579SelectorExecutor.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579SelectorExecutor.sol"; ``` Implementation of an [`ERC7579Executor`](#ERC7579Executor) that allows authorizing specific function selectors @@ -2281,11 +2312,14 @@ in the set will be allowed to execute. - [_addSelectors(account, newSelectors)](#ERC7579SelectorExecutor-_addSelectors-address-bytes4---) - [_removeSelectors(account, oldSelectors)](#ERC7579SelectorExecutor-_removeSelectors-address-bytes4---) - [_validateExecution(account, , , data)](#ERC7579SelectorExecutor-_validateExecution-address-bytes32-bytes32-bytes-) -#### ERC7579Executor [!toc] +
+ERC7579Executor + - [isModuleType(moduleTypeId)](#ERC7579Executor-isModuleType-uint256-) - [execute(account, salt, mode, data)](#ERC7579Executor-execute-address-bytes32-bytes32-bytes-) - [_execute(account, mode, salt, executionCalldata)](#ERC7579Executor-_execute-address-bytes32-bytes32-bytes-) -#### IERC7579Module [!toc] + +
@@ -2294,9 +2328,12 @@ in the set will be allowed to execute.
- [ERC7579ExecutorSelectorAuthorized(account, selector)](#ERC7579SelectorExecutor-ERC7579ExecutorSelectorAuthorized-address-bytes4-) - [ERC7579ExecutorSelectorRemoved(account, selector)](#ERC7579SelectorExecutor-ERC7579ExecutorSelectorRemoved-address-bytes4-) -#### ERC7579Executor [!toc] +
+ERC7579Executor + - [ERC7579ExecutorOperationExecuted(account, salt, mode, executionCalldata)](#ERC7579Executor-ERC7579ExecutorOperationExecuted-address-bytes32-bytes32-bytes-) -#### IERC7579Module [!toc] + +
@@ -2304,8 +2341,6 @@ in the set will be allowed to execute.

Errors

- [ERC7579ExecutorSelectorNotAuthorized(selector)](#ERC7579SelectorExecutor-ERC7579ExecutorSelectorNotAuthorized-bytes4-) -#### ERC7579Executor [!toc] -#### IERC7579Module [!toc]
@@ -2381,7 +2416,7 @@ Clears all selectors. This function has unbounded gas costs and may become uncallable if the set grows too large. -See [`EnumerableSetExtended.clear`](./utils#EnumerableSetExtended-clear-struct-EnumerableSetExtended-Bytes32x2Set-). +See [`EnumerableSetExtended.clear`](/community-contracts/api/utils#EnumerableSetExtended-clear-struct-EnumerableSetExtended-Bytes32x2Set-). @@ -2529,16 +2564,16 @@ Error thrown when attempting to execute a non-authorized selector
-## `ERC7579Signature` +## `ERC7579Signature` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579Signature.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579Signature.sol"; ``` Implementation of [`ERC7579Validator`](#ERC7579Validator) module using ERC-7913 signature verification. @@ -2561,12 +2596,14 @@ backup. - [setSigner(signer_)](#ERC7579Signature-setSigner-bytes-) - [_setSigner(account, signer_)](#ERC7579Signature-_setSigner-address-bytes-) - [_rawERC7579Validation(account, hash, signature)](#ERC7579Signature-_rawERC7579Validation-address-bytes32-bytes-) -#### ERC7579Validator [!toc] +
+ERC7579Validator + - [isModuleType(moduleTypeId)](#ERC7579Validator-isModuleType-uint256-) - [validateUserOp(userOp, userOpHash)](#ERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-) - [isValidSignatureWithSender(, hash, signature)](#ERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-) -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] + +
@@ -2574,9 +2611,6 @@ backup.

Events

- [ERC7579SignatureSignerSet(account, signer)](#ERC7579Signature-ERC7579SignatureSignerSet-address-bytes-) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc]
@@ -2584,9 +2618,6 @@ backup.

Errors

- [ERC7579SignatureInvalidSignerLength()](#ERC7579Signature-ERC7579SignatureInvalidSignerLength--) -#### ERC7579Validator [!toc] -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc]
@@ -2748,16 +2779,16 @@ Thrown when the signer length is less than 20 bytes.
-## `ERC7579Validator` +## `ERC7579Validator` - +
```solidity -import "@openzeppelin/community-contracts/account/modules/ERC7579Validator.sol"; +import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579Validator.sol"; ``` Abstract validator module for ERC-7579 accounts. @@ -2811,10 +2842,13 @@ function execute( - [validateUserOp(userOp, userOpHash)](#ERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-) - [isValidSignatureWithSender(, hash, signature)](#ERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-) - [_rawERC7579Validation(account, hash, signature)](#ERC7579Validator-_rawERC7579Validation-address-bytes32-bytes-) -#### IERC7579Validator [!toc] -#### IERC7579Module [!toc] +
+IERC7579Module + - [onInstall(data)](#IERC7579Module-onInstall-bytes-) - [onUninstall(data)](#IERC7579Module-onUninstall-bytes-) + +
@@ -2899,16 +2933,16 @@ handle cryptographic verification to prevent unauthorized access.
-## `PaymasterCore` +## `PaymasterCore` - +
```solidity -import "@openzeppelin/community-contracts/account/paymaster/PaymasterCore.sol"; +import "@openzeppelin/community-contracts/contracts/account/paymaster/PaymasterCore.sol"; ``` A simple ERC4337 paymaster implementation. This base implementation only includes the minimal logic to validate @@ -2951,7 +2985,6 @@ See [Paymaster's unstaked reputation rules](https://eips.ethereum.org/EIPS/eip-7 - [withdrawStake(to)](#PaymasterCore-withdrawStake-address-payable-) - [_checkEntryPoint()](#PaymasterCore-_checkEntryPoint--) - [_authorizeWithdraw()](#PaymasterCore-_authorizeWithdraw--) -#### IPaymaster [!toc] @@ -2959,7 +2992,6 @@ See [Paymaster's unstaked reputation rules](https://eips.ethereum.org/EIPS/eip-7

Errors

- [PaymasterUnauthorized(sender)](#PaymasterCore-PaymasterUnauthorized-address-) -#### IPaymaster [!toc]
@@ -3247,16 +3279,16 @@ Unauthorized call to the paymaster.
-## `PaymasterERC20` +## `PaymasterERC20` - +
```solidity -import "@openzeppelin/community-contracts/account/paymaster/PaymasterERC20.sol"; +import "@openzeppelin/community-contracts/contracts/account/paymaster/PaymasterERC20.sol"; ``` Extension of [`PaymasterCore`](#PaymasterCore) that enables users to pay gas with ERC-20 tokens. @@ -3288,7 +3320,9 @@ The contract follows a pre-charge and refund model: - [_tokenPriceDenominator()](#PaymasterERC20-_tokenPriceDenominator--) - [_erc20Cost(cost, feePerGas, tokenPrice)](#PaymasterERC20-_erc20Cost-uint256-uint256-uint256-) - [withdrawTokens(token, recipient, amount)](#PaymasterERC20-withdrawTokens-contract-IERC20-address-uint256-) -#### PaymasterCore [!toc] +
+PaymasterCore + - [entryPoint()](#PaymasterCore-entryPoint--) - [validatePaymasterUserOp(userOp, userOpHash, maxCost)](#PaymasterCore-validatePaymasterUserOp-struct-PackedUserOperation-bytes32-uint256-) - [postOp(mode, context, actualGasCost, actualUserOpFeePerGas)](#PaymasterCore-postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) @@ -3299,7 +3333,8 @@ The contract follows a pre-charge and refund model: - [withdrawStake(to)](#PaymasterCore-withdrawStake-address-payable-) - [_checkEntryPoint()](#PaymasterCore-_checkEntryPoint--) - [_authorizeWithdraw()](#PaymasterCore-_authorizeWithdraw--) -#### IPaymaster [!toc] + +
@@ -3307,8 +3342,6 @@ The contract follows a pre-charge and refund model:

Events

- [UserOperationSponsored(userOpHash, token, tokenAmount, tokenPrice)](#PaymasterERC20-UserOperationSponsored-bytes32-address-uint256-uint256-) -#### PaymasterCore [!toc] -#### IPaymaster [!toc]
@@ -3316,9 +3349,12 @@ The contract follows a pre-charge and refund model:

Errors

- [PaymasterERC20FailedRefund(token, prefundAmount, actualAmount, prefundContext)](#PaymasterERC20-PaymasterERC20FailedRefund-contract-IERC20-uint256-uint256-bytes-) -#### PaymasterCore [!toc] +
+PaymasterCore + - [PaymasterUnauthorized(sender)](#PaymasterCore-PaymasterUnauthorized-address-) -#### IPaymaster [!toc] + +
@@ -3438,7 +3474,7 @@ The values returned by this internal function are: * `token`: Address of the ERC-20 token used for payment to the paymaster. * `tokenPrice`: Price of the token in native currency, scaled by `_tokenPriceDenominator()`. -==== Calculating the token price +#### Calculating the token price Given gas fees are paid in native currency, developers can use the `ERC20 price unit / native price unit` ratio to calculate the price of an ERC20 token price in native currency. However, the token may have a different number of decimals @@ -3563,16 +3599,16 @@ and the `actualAmount` of `token`.
-## `PaymasterERC20Guarantor` +## `PaymasterERC20Guarantor` - +
```solidity -import "@openzeppelin/community-contracts/account/paymaster/PaymasterERC20Guarantor.sol"; +import "@openzeppelin/community-contracts/contracts/account/paymaster/PaymasterERC20Guarantor.sol"; ``` Extension of [`PaymasterERC20`](#PaymasterERC20) that enables third parties to guarantee user operations. @@ -3600,7 +3636,9 @@ logic based on the specific requirements of the application. - [_refund(token, tokenPrice, actualGasCost, actualUserOpFeePerGas, prefunder, prefundAmount, prefundContext)](#PaymasterERC20Guarantor-_refund-contract-IERC20-uint256-uint256-uint256-address-uint256-bytes-) - [_fetchGuarantor(userOp)](#PaymasterERC20Guarantor-_fetchGuarantor-struct-PackedUserOperation-) - [_guaranteedPostOpCost()](#PaymasterERC20Guarantor-_guaranteedPostOpCost--) -#### PaymasterERC20 [!toc] +
+PaymasterERC20 + - [_validatePaymasterUserOp(userOp, userOpHash, maxCost)](#PaymasterERC20-_validatePaymasterUserOp-struct-PackedUserOperation-bytes32-uint256-) - [_postOp(, context, actualGasCost, actualUserOpFeePerGas)](#PaymasterERC20-_postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) - [_fetchDetails(userOp, userOpHash)](#PaymasterERC20-_fetchDetails-struct-PackedUserOperation-bytes32-) @@ -3608,7 +3646,11 @@ logic based on the specific requirements of the application. - [_tokenPriceDenominator()](#PaymasterERC20-_tokenPriceDenominator--) - [_erc20Cost(cost, feePerGas, tokenPrice)](#PaymasterERC20-_erc20Cost-uint256-uint256-uint256-) - [withdrawTokens(token, recipient, amount)](#PaymasterERC20-withdrawTokens-contract-IERC20-address-uint256-) -#### PaymasterCore [!toc] + +
+
+PaymasterCore + - [entryPoint()](#PaymasterCore-entryPoint--) - [validatePaymasterUserOp(userOp, userOpHash, maxCost)](#PaymasterCore-validatePaymasterUserOp-struct-PackedUserOperation-bytes32-uint256-) - [postOp(mode, context, actualGasCost, actualUserOpFeePerGas)](#PaymasterCore-postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) @@ -3619,7 +3661,8 @@ logic based on the specific requirements of the application. - [withdrawStake(to)](#PaymasterCore-withdrawStake-address-payable-) - [_checkEntryPoint()](#PaymasterCore-_checkEntryPoint--) - [_authorizeWithdraw()](#PaymasterCore-_authorizeWithdraw--) -#### IPaymaster [!toc] + +
@@ -3627,21 +3670,30 @@ logic based on the specific requirements of the application.

Events

- [UserOperationGuaranteed(userOpHash, guarantor, prefundAmount)](#PaymasterERC20Guarantor-UserOperationGuaranteed-bytes32-address-uint256-) -#### PaymasterERC20 [!toc] +
+PaymasterERC20 + - [UserOperationSponsored(userOpHash, token, tokenAmount, tokenPrice)](#PaymasterERC20-UserOperationSponsored-bytes32-address-uint256-uint256-) -#### PaymasterCore [!toc] -#### IPaymaster [!toc] + +

Errors

-#### PaymasterERC20 [!toc] +
+PaymasterERC20 + - [PaymasterERC20FailedRefund(token, prefundAmount, actualAmount, prefundContext)](#PaymasterERC20-PaymasterERC20FailedRefund-contract-IERC20-uint256-uint256-bytes-) -#### PaymasterCore [!toc] + +
+
+PaymasterCore + - [PaymasterUnauthorized(sender)](#PaymasterCore-PaymasterUnauthorized-address-) -#### IPaymaster [!toc] + +
@@ -3752,16 +3804,16 @@ Emitted when a user operation identified by `userOpHash` is guaranteed by a `gua
-## `PaymasterERC721Owner` +## `PaymasterERC721Owner` - +
```solidity -import "@openzeppelin/community-contracts/account/paymaster/PaymasterERC721Owner.sol"; +import "@openzeppelin/community-contracts/contracts/account/paymaster/PaymasterERC721Owner.sol"; ``` Extension of [`PaymasterCore`](#PaymasterCore) that supports account based on ownership of an ERC-721 token. @@ -3776,7 +3828,9 @@ during construction (or via [`PaymasterERC721Owner._setToken`](#PaymasterERC721O - [token()](#PaymasterERC721Owner-token--) - [_setToken(token_)](#PaymasterERC721Owner-_setToken-contract-IERC721-) - [_validatePaymasterUserOp(userOp, , )](#PaymasterERC721Owner-_validatePaymasterUserOp-struct-PackedUserOperation-bytes32-uint256-) -#### PaymasterCore [!toc] +
+PaymasterCore + - [entryPoint()](#PaymasterCore-entryPoint--) - [validatePaymasterUserOp(userOp, userOpHash, maxCost)](#PaymasterCore-validatePaymasterUserOp-struct-PackedUserOperation-bytes32-uint256-) - [postOp(mode, context, actualGasCost, actualUserOpFeePerGas)](#PaymasterCore-postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) @@ -3788,7 +3842,8 @@ during construction (or via [`PaymasterERC721Owner._setToken`](#PaymasterERC721O - [withdrawStake(to)](#PaymasterCore-withdrawStake-address-payable-) - [_checkEntryPoint()](#PaymasterCore-_checkEntryPoint--) - [_authorizeWithdraw()](#PaymasterCore-_authorizeWithdraw--) -#### IPaymaster [!toc] + +
@@ -3796,17 +3851,18 @@ during construction (or via [`PaymasterERC721Owner._setToken`](#PaymasterERC721O

Events

- [PaymasterERC721OwnerTokenSet(token)](#PaymasterERC721Owner-PaymasterERC721OwnerTokenSet-contract-IERC721-) -#### PaymasterCore [!toc] -#### IPaymaster [!toc]

Errors

-#### PaymasterCore [!toc] +
+PaymasterCore + - [PaymasterUnauthorized(sender)](#PaymasterCore-PaymasterUnauthorized-address-) -#### IPaymaster [!toc] + +
@@ -3904,16 +3960,16 @@ Emitted when the paymaster token is set.
-## `PaymasterSigner` +## `PaymasterSigner` - +
```solidity -import "@openzeppelin/community-contracts/account/paymaster/PaymasterSigner.sol"; +import "@openzeppelin/community-contracts/contracts/account/paymaster/PaymasterSigner.sol"; ``` Extension of [`PaymasterCore`](#PaymasterCore) that adds signature validation. See `SignerECDSA`, `SignerP256` or `SignerRSA`. @@ -3932,7 +3988,9 @@ contract MyPaymasterECDSASigner is PaymasterSigner, SignerECDSA { - [_signableUserOpHash(userOp, validAfter, validUntil)](#PaymasterSigner-_signableUserOpHash-struct-PackedUserOperation-uint48-uint48-) - [_validatePaymasterUserOp(userOp, , )](#PaymasterSigner-_validatePaymasterUserOp-struct-PackedUserOperation-bytes32-uint256-) - [_decodePaymasterUserOp(userOp)](#PaymasterSigner-_decodePaymasterUserOp-struct-PackedUserOperation-) -#### PaymasterCore [!toc] +
+PaymasterCore + - [entryPoint()](#PaymasterCore-entryPoint--) - [validatePaymasterUserOp(userOp, userOpHash, maxCost)](#PaymasterCore-validatePaymasterUserOp-struct-PackedUserOperation-bytes32-uint256-) - [postOp(mode, context, actualGasCost, actualUserOpFeePerGas)](#PaymasterCore-postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) @@ -3944,40 +4002,48 @@ contract MyPaymasterECDSASigner is PaymasterSigner, SignerECDSA { - [withdrawStake(to)](#PaymasterCore-withdrawStake-address-payable-) - [_checkEntryPoint()](#PaymasterCore-_checkEntryPoint--) - [_authorizeWithdraw()](#PaymasterCore-_authorizeWithdraw--) -#### IPaymaster [!toc] -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### AbstractSigner [!toc] + +
+
+AbstractSigner + - [_rawSignatureValidation(hash, signature)](#AbstractSigner-_rawSignatureValidation-bytes32-bytes-) + +

Events

-#### PaymasterCore [!toc] -#### IPaymaster [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] +
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### AbstractSigner [!toc] + +

Errors

-#### PaymasterCore [!toc] +
+PaymasterCore + - [PaymasterUnauthorized(sender)](#PaymasterCore-PaymasterUnauthorized-address-) -#### IPaymaster [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### AbstractSigner [!toc] + +
@@ -4039,3 +4105,4 @@ Decodes the user operation's data from `paymasterAndData`. + diff --git a/content/community-contracts/api/crosschain.mdx b/content/community-contracts/api/crosschain.mdx index 2ecb1370..fe69d513 100644 --- a/content/community-contracts/api/crosschain.mdx +++ b/content/community-contracts/api/crosschain.mdx @@ -5,7 +5,6 @@ description: "Smart contract crosschain utilities and implementations" Gateways are contracts that enable cross-chain communication. These can either be a message source or a destination according to ERC-7786. -* [`ERC7786Receiver`](#ERC7786Receiver): ERC-7786 cross-chain message receiver. * [`ERC7786OpenBridge`](#ERC7786OpenBridge): ERC-7786 "N out of M" gateway. Sends a message through M gateways and executes on the destination if N received it. Developers can access interoperability protocols through gateway adapters. The library includes the following gateway adapters: @@ -16,10 +15,6 @@ Developers can access interoperability protocols through gateway adapters. The l [`ERC7786OpenBridge`](#ERC7786OpenBridge) -## Clients - -[`ERC7786Receiver`](#ERC7786Receiver) - ## Adapters ### Axelar @@ -30,19 +25,19 @@ Developers can access interoperability protocols through gateway adapters. The l
-## `ERC7786OpenBridge` +## `ERC7786OpenBridge` - +
```solidity -import "@openzeppelin/community-contracts/crosschain/ERC7786OpenBridge.sol"; +import "@openzeppelin/community-contracts/contracts/crosschain/ERC7786OpenBridge.sol"; ``` -N of M gateway: Sends your message through M independent gateways. It will be delivered to the receiver by an +N of M gateway: Sends your message through M independent gateways. It will be delivered to the recipient by an equivalent bridge on the destination chain if N of the M gateways agree.
@@ -67,20 +62,26 @@ equivalent bridge on the destination chain if N of the M gateways agree. - [_removeGateway(gateway)](#ERC7786OpenBridge-_removeGateway-address-) - [_setThreshold(newThreshold)](#ERC7786OpenBridge-_setThreshold-uint8-) - [_registerRemoteBridge(bridge)](#ERC7786OpenBridge-_registerRemoteBridge-bytes-) -#### Pausable [!toc] +
+Pausable + - [paused()](#Pausable-paused--) - [_requireNotPaused()](#Pausable-_requireNotPaused--) - [_requirePaused()](#Pausable-_requirePaused--) - [_pause()](#Pausable-_pause--) - [_unpause()](#Pausable-_unpause--) -#### Ownable [!toc] + +
+
+Ownable + - [owner()](#Ownable-owner--) - [_checkOwner()](#Ownable-_checkOwner--) - [renounceOwnership()](#Ownable-renounceOwnership--) - [transferOwnership(newOwner)](#Ownable-transferOwnership-address-) - [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-) -#### IERC7786Receiver [!toc] -#### IERC7786GatewaySource [!toc] + +
@@ -95,14 +96,25 @@ equivalent bridge on the destination chain if N of the M gateways agree. - [GatewayRemoved(gateway)](#ERC7786OpenBridge-GatewayRemoved-address-) - [ThresholdUpdated(threshold)](#ERC7786OpenBridge-ThresholdUpdated-uint8-) - [RemoteRegistered(remote)](#ERC7786OpenBridge-RemoteRegistered-bytes-) -#### Pausable [!toc] +
+Pausable + - [Paused(account)](#Pausable-Paused-address-) - [Unpaused(account)](#Pausable-Unpaused-address-) -#### Ownable [!toc] + +
+
+Ownable + - [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-) -#### IERC7786Receiver [!toc] -#### IERC7786GatewaySource [!toc] -- [MessageSent(sendId, sender, receiver, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) + +
+
+IERC7786GatewaySource + +- [MessageSent(sendId, sender, recipient, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) + +
@@ -118,15 +130,26 @@ equivalent bridge on the destination chain if N of the M gateways agree. - [ERC7786OpenBridgeThresholdViolation()](#ERC7786OpenBridge-ERC7786OpenBridgeThresholdViolation--) - [ERC7786OpenBridgeInvalidExecutionReturnValue()](#ERC7786OpenBridge-ERC7786OpenBridgeInvalidExecutionReturnValue--) - [RemoteAlreadyRegistered(remote)](#ERC7786OpenBridge-RemoteAlreadyRegistered-bytes-) -#### Pausable [!toc] +
+Pausable + - [EnforcedPause()](#Pausable-EnforcedPause--) - [ExpectedPause()](#Pausable-ExpectedPause--) -#### Ownable [!toc] + +
+
+Ownable + - [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-) -#### IERC7786Receiver [!toc] -#### IERC7786GatewaySource [!toc] + +
+
+IERC7786GatewaySource + - [UnsupportedAttribute(selector)](#IERC7786GatewaySource-UnsupportedAttribute-bytes4-) + +
@@ -210,21 +233,21 @@ This function revert if: chain. * someone tries re-execute a message that was already successfully delivered. This includes gateways that call this function a second time with a message that was already executed. -* the execution of the message (on the [`IERC7786Receiver`](./interfaces#IERC7786Receiver) receiver) is successful but fails to return the +* the execution of the message (on the `IERC7786Recipient` recipient) is successful but fails to return the executed value. This function does not revert if: * A known gateway delivers a message for the first time, and that message was already executed. In that case the message is NOT re-executed, and the correct "magic value" is returned. -* The execution of the message (on the [`IERC7786Receiver`](./interfaces#IERC7786Receiver) receiver) reverts. In that case a [`ERC7786OpenBridge.ExecutionFailed`](#ERC7786OpenBridge-ExecutionFailed-bytes32-) +* The execution of the message (on the `IERC7786Recipient` recipient) reverts. In that case a [`ERC7786OpenBridge.ExecutionFailed`](#ERC7786OpenBridge-ExecutionFailed-bytes32-) event is emitted. This function emits: * [`ERC7786OpenBridge.Received`](#ERC7786OpenBridge-Received-bytes32-address-) when a known ERC-7786 gateway delivers a message for the first time. -* [`ERC7786OpenBridge.ExecutionSuccess`](#ERC7786OpenBridge-ExecutionSuccess-bytes32-) when a message is successfully delivered to the receiver. -* [`ERC7786OpenBridge.ExecutionFailed`](#ERC7786OpenBridge-ExecutionFailed-bytes32-) when a message delivery to the receiver reverted (for example because of OOG error). +* [`ERC7786OpenBridge.ExecutionSuccess`](#ERC7786OpenBridge-ExecutionSuccess-bytes32-) when a message is successfully delivered to the recipient. +* [`ERC7786OpenBridge.ExecutionFailed`](#ERC7786OpenBridge-ExecutionFailed-bytes32-) when a message delivery to the recipient reverted (for example because of OOG error). interface requires this function to be payable. Even if we don't expect any value, a gateway may pass @@ -722,21 +745,21 @@ Recovery method in case value is ever received through [`ERC7786OpenBridge.recei
-## `AxelarGatewayAdapter` +## `AxelarGatewayAdapter` - +
```solidity -import "@openzeppelin/community-contracts/crosschain/axelar/AxelarGatewayAdapter.sol"; +import "@openzeppelin/community-contracts/contracts/crosschain/axelar/AxelarGatewayAdapter.sol"; ``` Implementation of an ERC-7786 gateway destination adapter for the Axelar Network in dual mode. -The contract implements AxelarExecutable's [`ERC7579DelayedExecutor._execute`](./account#ERC7579DelayedExecutor-_execute-address-bytes32-bytes32-bytes-) function to execute the message, converting Axelar's native +The contract implements AxelarExecutable's [`AxelarGatewayAdapter._execute`](#AxelarGatewayAdapter-_execute-bytes32-string-string-bytes-) function to execute the message, converting Axelar's native workflow into the standard ERC-7786. @@ -761,17 +784,23 @@ networks (could be base58, base64, ...) but Axelar doesn't support that. - [sendMessage(recipient, payload, attributes)](#AxelarGatewayAdapter-sendMessage-bytes-bytes-bytes---) - [_execute(commandId, axelarSourceChain, axelarSourceAddress, adapterPayload)](#AxelarGatewayAdapter-_execute-bytes32-string-string-bytes-) - [_stringifyAddress(chainType, addr)](#AxelarGatewayAdapter-_stringifyAddress-bytes2-bytes-) -#### AxelarExecutable [!toc] +
+AxelarExecutable + - [execute(commandId, sourceChain, sourceAddress, payload)](#AxelarExecutable-execute-bytes32-string-string-bytes-) - [gateway()](#AxelarExecutable-gateway--) -#### IAxelarExecutable [!toc] -#### Ownable [!toc] + +
+
+Ownable + - [owner()](#Ownable-owner--) - [_checkOwner()](#Ownable-_checkOwner--) - [renounceOwnership()](#Ownable-renounceOwnership--) - [transferOwnership(newOwner)](#Ownable-transferOwnership-address-) - [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-) -#### IERC7786GatewaySource [!toc] + +
@@ -780,12 +809,18 @@ networks (could be base58, base64, ...) but Axelar doesn't support that.
- [RegisteredRemoteGateway(remote)](#AxelarGatewayAdapter-RegisteredRemoteGateway-bytes-) - [RegisteredChainEquivalence(erc7930binary, axelar)](#AxelarGatewayAdapter-RegisteredChainEquivalence-bytes-string-) -#### AxelarExecutable [!toc] -#### IAxelarExecutable [!toc] -#### Ownable [!toc] +
+Ownable + - [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-) -#### IERC7786GatewaySource [!toc] -- [MessageSent(sendId, sender, receiver, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) + +
+
+IERC7786GatewaySource + +- [MessageSent(sendId, sender, recipient, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) + +
@@ -794,22 +829,33 @@ networks (could be base58, base64, ...) but Axelar doesn't support that.
- [UnsupportedNativeTransfer()](#AxelarGatewayAdapter-UnsupportedNativeTransfer--) - [InvalidOriginGateway(axelarSourceChain, axelarSourceAddress)](#AxelarGatewayAdapter-InvalidOriginGateway-string-string-) -- [ReceiverExecutionFailed()](#AxelarGatewayAdapter-ReceiverExecutionFailed--) +- [RecipientExecutionFailed()](#AxelarGatewayAdapter-RecipientExecutionFailed--) - [UnsupportedChainType(chainType)](#AxelarGatewayAdapter-UnsupportedChainType-bytes2-) - [UnsupportedERC7930Chain(erc7930binary)](#AxelarGatewayAdapter-UnsupportedERC7930Chain-bytes-) - [UnsupportedAxelarChain(axelar)](#AxelarGatewayAdapter-UnsupportedAxelarChain-string-) - [InvalidChainIdentifier(erc7930binary)](#AxelarGatewayAdapter-InvalidChainIdentifier-bytes-) - [ChainEquivalenceAlreadyRegistered(erc7930binary, axelar)](#AxelarGatewayAdapter-ChainEquivalenceAlreadyRegistered-bytes-string-) - [RemoteGatewayAlreadyRegistered(chainType, chainReference)](#AxelarGatewayAdapter-RemoteGatewayAlreadyRegistered-bytes2-bytes-) -#### AxelarExecutable [!toc] -#### IAxelarExecutable [!toc] +
+IAxelarExecutable + - [InvalidAddress()](#IAxelarExecutable-InvalidAddress--) - [NotApprovedByGateway()](#IAxelarExecutable-NotApprovedByGateway--) -#### Ownable [!toc] + +
+
+Ownable + - [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-) -#### IERC7786GatewaySource [!toc] + +
+
+IERC7786GatewaySource + - [UnsupportedAttribute(selector)](#IERC7786GatewaySource-UnsupportedAttribute-bytes4-) + +
@@ -962,12 +1008,12 @@ Getter to check whether an attribute is supported or not.
Endpoint for creating a new message. If the message requires further (gateway specific) processing before -it can be sent to the destination chain, then a non-zero `outboxId` must be returned. Otherwise, the +it can be sent to the destination chain, then a non-zero `sendId` must be returned. Otherwise, the message MUST be sent and this function must return 0. -* MUST emit a [`IERC7786GatewaySource.MessageSent`](./interfaces#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) event. +* MUST emit a `MessageSent` event. -If any of the `attributes` is not supported, this function SHOULD revert with an [`IERC7786GatewaySource.UnsupportedAttribute`](./interfaces#IERC7786GatewaySource-UnsupportedAttribute-bytes4-) error. +If any of the `attributes` is not supported, this function SHOULD revert with an `UnsupportedAttribute` error. Other errors SHOULD revert with errors not specified in ERC-7786.
@@ -1080,14 +1126,14 @@ A chain equivalence has been registered. - +
-

ReceiverExecutionFailed()

+

RecipientExecutionFailed()

error

-# +#
@@ -1189,16 +1235,16 @@ A chain equivalence has been registered.
-## `ERC7786Attributes` +## `ERC7786Attributes` - +
```solidity -import "@openzeppelin/community-contracts/crosschain/utils/ERC7786Attributes.sol"; +import "@openzeppelin/community-contracts/contracts/crosschain/utils/ERC7786Attributes.sol"; ``` Library of helper to parse/process ERC-7786 attributes @@ -1227,149 +1273,20 @@ Parse the `requestRelay(uint256,uint256,address)` (0x4cbb573a) attribute into it
- - -
- -## `ERC7786Receiver` - - - - - -
- -```solidity -import "@openzeppelin/community-contracts/crosschain/utils/ERC7786Receiver.sol"; -``` - -Base implementation of an ERC-7786 compliant cross-chain message receiver. - -This abstract contract exposes the `receiveMessage` function that is used for communication with (one or multiple) -destination gateways. This contract leaves two functions unimplemented: - -[`ERC7786Receiver._isKnownGateway`](#ERC7786Receiver-_isKnownGateway-address-), an internal getter used to verify whether an address is recognised by the contract as a valid -ERC-7786 destination gateway. One or multiple gateway can be supported. Note that any malicious address for which -this function returns true would be able to impersonate any account on any other chain sending any message. - -[`ERC7786Receiver._processMessage`](#ERC7786Receiver-_processMessage-address-bytes32-bytes-bytes-), the internal function that will be called with any message that has been validated. - -
-

Functions

-
-- [receiveMessage(receiveId, sender, payload)](#ERC7786Receiver-receiveMessage-bytes32-bytes-bytes-) -- [_isKnownGateway(instance)](#ERC7786Receiver-_isKnownGateway-address-) -- [_processMessage(gateway, receiveId, sender, payload)](#ERC7786Receiver-_processMessage-address-bytes32-bytes-bytes-) -#### IERC7786Receiver [!toc] -
-
- -
-

Errors

-
-- [ERC7786ReceiverInvalidGateway(gateway)](#ERC7786Receiver-ERC7786ReceiverInvalidGateway-address-) -- [ERC7786ReceivePassiveModeValue()](#ERC7786Receiver-ERC7786ReceivePassiveModeValue--) -#### IERC7786Receiver [!toc] -
-
- - - -
-
-

receiveMessage(bytes32 receiveId, bytes sender, bytes payload) โ†’ bytes4

-
-

public

-# -
-
-
- -Endpoint for receiving cross-chain message. - -This function may be called directly by the gateway. - -
-
- - - -
-
-

_isKnownGateway(address instance) โ†’ bool

-
-

internal

-# -
-
-
- -Virtual getter that returns whether an address is a valid ERC-7786 gateway. - -
-
- - - -
-
-

_processMessage(address gateway, bytes32 receiveId, bytes sender, bytes payload)

-
-

internal

-# -
-
-
- -Virtual function that should contain the logic to execute when a cross-chain message is received. - -
-
- - - -
-
-

ERC7786ReceiverInvalidGateway(address gateway)

-
-

error

-# -
-
-
- -
-
- - - -
-
-

ERC7786ReceivePassiveModeValue()

-
-

error

-# -
-
-
- -
-
-
-## `WormholeGatewayAdapter` +## `WormholeGatewayAdapter` - +
```solidity -import "@openzeppelin/community-contracts/crosschain/wormhole/WormholeGatewayAdapter.sol"; +import "@openzeppelin/community-contracts/contracts/crosschain/wormhole/WormholeGatewayAdapter.sol"; ``` An ERC-7786 compliant adapter to send and receive messages via Wormhole. @@ -1404,14 +1321,16 @@ Note: only EVM chains are currently supported - [quoteRelay(recipient, , , value, gasLimit, )](#WormholeGatewayAdapter-quoteRelay-bytes-bytes-bytes---uint256-uint256-address-) - [requestRelay(sendId, gasLimit, refundRecipient)](#WormholeGatewayAdapter-requestRelay-bytes32-uint256-address-) - [receiveWormholeMessages(adapterPayload, additionalMessages, wormholeSourceAddress, wormholeSourceChain, deliveryHash)](#WormholeGatewayAdapter-receiveWormholeMessages-bytes-bytes---bytes32-uint16-bytes32-) -#### Ownable [!toc] +
+Ownable + - [owner()](#Ownable-owner--) - [_checkOwner()](#Ownable-_checkOwner--) - [renounceOwnership()](#Ownable-renounceOwnership--) - [transferOwnership(newOwner)](#Ownable-transferOwnership-address-) - [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-) -#### IWormholeReceiver [!toc] -#### IERC7786GatewaySource [!toc] + +
@@ -1421,11 +1340,18 @@ Note: only EVM chains are currently supported - [MessageRelayed(sendId)](#WormholeGatewayAdapter-MessageRelayed-bytes32-) - [RegisteredRemoteGateway(chainId, remote)](#WormholeGatewayAdapter-RegisteredRemoteGateway-uint256-address-) - [RegisteredChainEquivalence(chainId, wormholeId)](#WormholeGatewayAdapter-RegisteredChainEquivalence-uint256-uint16-) -#### Ownable [!toc] +
+Ownable + - [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-) -#### IWormholeReceiver [!toc] -#### IERC7786GatewaySource [!toc] -- [MessageSent(sendId, sender, receiver, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) + +
+
+IERC7786GatewaySource + +- [MessageSent(sendId, sender, recipient, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) + +
@@ -1436,7 +1362,7 @@ Note: only EVM chains are currently supported - [DuplicatedAttribute()](#WormholeGatewayAdapter-DuplicatedAttribute--) - [UnauthorizedCaller()](#WormholeGatewayAdapter-UnauthorizedCaller-address-) - [InvalidOriginGateway(wormholeSourceChain, wormholeSourceAddress)](#WormholeGatewayAdapter-InvalidOriginGateway-uint16-bytes32-) -- [ReceiverExecutionFailed()](#WormholeGatewayAdapter-ReceiverExecutionFailed--) +- [RecipientExecutionFailed()](#WormholeGatewayAdapter-RecipientExecutionFailed--) - [UnsupportedChainId(chainId)](#WormholeGatewayAdapter-UnsupportedChainId-uint256-) - [UnsupportedWormholeChain(wormholeId)](#WormholeGatewayAdapter-UnsupportedWormholeChain-uint16-) - [ChainEquivalenceAlreadyRegistered(chainId, wormhole)](#WormholeGatewayAdapter-ChainEquivalenceAlreadyRegistered-uint256-uint16-) @@ -1444,12 +1370,19 @@ Note: only EVM chains are currently supported - [InvalidSendId(sendId)](#WormholeGatewayAdapter-InvalidSendId-bytes32-) - [AdditionalMessagesNotSupported()](#WormholeGatewayAdapter-AdditionalMessagesNotSupported--) - [MessageAlreadyExecuted(chainId, outboxId)](#WormholeGatewayAdapter-MessageAlreadyExecuted-uint256-bytes32-) -#### Ownable [!toc] +
+Ownable + - [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-) -#### IWormholeReceiver [!toc] -#### IERC7786GatewaySource [!toc] + +
+
+IERC7786GatewaySource + - [UnsupportedAttribute(selector)](#IERC7786GatewaySource-UnsupportedAttribute-bytes4-) + +
@@ -1720,12 +1653,12 @@ Getter to check whether an attribute is supported or not.
Endpoint for creating a new message. If the message requires further (gateway specific) processing before -it can be sent to the destination chain, then a non-zero `outboxId` must be returned. Otherwise, the +it can be sent to the destination chain, then a non-zero `sendId` must be returned. Otherwise, the message MUST be sent and this function must return 0. -* MUST emit a [`IERC7786GatewaySource.MessageSent`](./interfaces#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) event. +* MUST emit a `MessageSent` event. -If any of the `attributes` is not supported, this function SHOULD revert with an [`IERC7786GatewaySource.UnsupportedAttribute`](./interfaces#IERC7786GatewaySource-UnsupportedAttribute-bytes4-) error. +If any of the `attributes` is not supported, this function SHOULD revert with an `UnsupportedAttribute` error. Other errors SHOULD revert with errors not specified in ERC-7786.
@@ -1892,14 +1825,14 @@ A chain equivalence has been registered. - +
-

ReceiverExecutionFailed()

+

RecipientExecutionFailed()

error

-# +#
@@ -2011,3 +1944,4 @@ A chain equivalence has been registered.
+ diff --git a/content/community-contracts/api/governance.mdx b/content/community-contracts/api/governance.mdx new file mode 100644 index 00000000..8e5bbda8 --- /dev/null +++ b/content/community-contracts/api/governance.mdx @@ -0,0 +1,485 @@ +--- +title: "Governance" +description: "Smart contract governance utilities and implementations" +--- + +This directory includes extensions and utilities for on-chain governance. + +* [`TimelockControllerEnumerable`](#TimelockControllerEnumerable): Extension of OpenZeppelinโ€™s TimelockController with enumerable operations support. + +## Timelock + +[`TimelockControllerEnumerable`](#TimelockControllerEnumerable) + + + +
+ +## `TimelockControllerEnumerable` + + + + + +
+ +```solidity +import "@openzeppelin/community-contracts/contracts/governance/TimelockControllerEnumerable.sol"; +``` + +Extends the TimelockController to allow for enumerable operations + +
+

Functions

+
+- [schedule(target, value, data, predecessor, salt, delay)](#TimelockControllerEnumerable-schedule-address-uint256-bytes-bytes32-bytes32-uint256-) +- [scheduleBatch(targets, values, payloads, predecessor, salt, delay)](#TimelockControllerEnumerable-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-) +- [cancel(id)](#TimelockControllerEnumerable-cancel-bytes32-) +- [operations()](#TimelockControllerEnumerable-operations--) +- [operations(start, end)](#TimelockControllerEnumerable-operations-uint256-uint256-) +- [operationsCount()](#TimelockControllerEnumerable-operationsCount--) +- [operation(index)](#TimelockControllerEnumerable-operation-uint256-) +- [operation(id)](#TimelockControllerEnumerable-operation-bytes32-) +- [operationsBatch()](#TimelockControllerEnumerable-operationsBatch--) +- [operationsBatch(start, end)](#TimelockControllerEnumerable-operationsBatch-uint256-uint256-) +- [operationsBatchCount()](#TimelockControllerEnumerable-operationsBatchCount--) +- [operationBatch(index)](#TimelockControllerEnumerable-operationBatch-uint256-) +- [operationBatch(id)](#TimelockControllerEnumerable-operationBatch-bytes32-) +
+TimelockController + +- [receive()](#TimelockController-receive--) +- [supportsInterface(interfaceId)](#TimelockController-supportsInterface-bytes4-) +- [isOperation(id)](#TimelockController-isOperation-bytes32-) +- [isOperationPending(id)](#TimelockController-isOperationPending-bytes32-) +- [isOperationReady(id)](#TimelockController-isOperationReady-bytes32-) +- [isOperationDone(id)](#TimelockController-isOperationDone-bytes32-) +- [getTimestamp(id)](#TimelockController-getTimestamp-bytes32-) +- [getOperationState(id)](#TimelockController-getOperationState-bytes32-) +- [getMinDelay()](#TimelockController-getMinDelay--) +- [hashOperation(target, value, data, predecessor, salt)](#TimelockController-hashOperation-address-uint256-bytes-bytes32-bytes32-) +- [hashOperationBatch(targets, values, payloads, predecessor, salt)](#TimelockController-hashOperationBatch-address---uint256---bytes---bytes32-bytes32-) +- [execute(target, value, payload, predecessor, salt)](#TimelockController-execute-address-uint256-bytes-bytes32-bytes32-) +- [executeBatch(targets, values, payloads, predecessor, salt)](#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-) +- [_execute(target, value, data)](#TimelockController-_execute-address-uint256-bytes-) +- [updateDelay(newDelay)](#TimelockController-updateDelay-uint256-) +- [_encodeStateBitmap(operationState)](#TimelockController-_encodeStateBitmap-enum-TimelockController-OperationState-) +- [PROPOSER_ROLE()](#TimelockController-PROPOSER_ROLE-bytes32) +- [EXECUTOR_ROLE()](#TimelockController-EXECUTOR_ROLE-bytes32) +- [CANCELLER_ROLE()](#TimelockController-CANCELLER_ROLE-bytes32) + +
+
+ERC1155Holder + +- [onERC1155Received(, , , , )](#ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-) +- [onERC1155BatchReceived(, , , , )](#ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-) + +
+
+ERC721Holder + +- [onERC721Received(, , , )](#ERC721Holder-onERC721Received-address-address-uint256-bytes-) + +
+
+AccessControl + +- [hasRole(role, account)](#AccessControl-hasRole-bytes32-address-) +- [_checkRole(role)](#AccessControl-_checkRole-bytes32-) +- [_checkRole(role, account)](#AccessControl-_checkRole-bytes32-address-) +- [getRoleAdmin(role)](#AccessControl-getRoleAdmin-bytes32-) +- [grantRole(role, account)](#AccessControl-grantRole-bytes32-address-) +- [revokeRole(role, account)](#AccessControl-revokeRole-bytes32-address-) +- [renounceRole(role, callerConfirmation)](#AccessControl-renounceRole-bytes32-address-) +- [_setRoleAdmin(role, adminRole)](#AccessControl-_setRoleAdmin-bytes32-bytes32-) +- [_grantRole(role, account)](#AccessControl-_grantRole-bytes32-address-) +- [_revokeRole(role, account)](#AccessControl-_revokeRole-bytes32-address-) +- [DEFAULT_ADMIN_ROLE()](#AccessControl-DEFAULT_ADMIN_ROLE-bytes32) + +
+
+
+ +
+

Events

+
+
+TimelockController + +- [CallScheduled(id, index, target, value, data, predecessor, delay)](#TimelockController-CallScheduled-bytes32-uint256-address-uint256-bytes-bytes32-uint256-) +- [CallExecuted(id, index, target, value, data)](#TimelockController-CallExecuted-bytes32-uint256-address-uint256-bytes-) +- [CallSalt(id, salt)](#TimelockController-CallSalt-bytes32-bytes32-) +- [Cancelled(id)](#TimelockController-Cancelled-bytes32-) +- [MinDelayChange(oldDuration, newDuration)](#TimelockController-MinDelayChange-uint256-uint256-) + +
+
+IAccessControl + +- [RoleAdminChanged(role, previousAdminRole, newAdminRole)](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) +- [RoleGranted(role, account, sender)](#IAccessControl-RoleGranted-bytes32-address-address-) +- [RoleRevoked(role, account, sender)](#IAccessControl-RoleRevoked-bytes32-address-address-) + +
+
+
+ +
+

Errors

+
+- [OperationIndexNotFound(index)](#TimelockControllerEnumerable-OperationIndexNotFound-uint256-) +- [OperationIdNotFound(id)](#TimelockControllerEnumerable-OperationIdNotFound-bytes32-) +- [OperationBatchIndexNotFound(index)](#TimelockControllerEnumerable-OperationBatchIndexNotFound-uint256-) +- [OperationBatchIdNotFound(id)](#TimelockControllerEnumerable-OperationBatchIdNotFound-bytes32-) +- [InvalidIndexRange(start, end)](#TimelockControllerEnumerable-InvalidIndexRange-uint256-uint256-) +
+TimelockController + +- [TimelockInvalidOperationLength(targets, payloads, values)](#TimelockController-TimelockInvalidOperationLength-uint256-uint256-uint256-) +- [TimelockInsufficientDelay(delay, minDelay)](#TimelockController-TimelockInsufficientDelay-uint256-uint256-) +- [TimelockUnexpectedOperationState(operationId, expectedStates)](#TimelockController-TimelockUnexpectedOperationState-bytes32-bytes32-) +- [TimelockUnexecutedPredecessor(predecessorId)](#TimelockController-TimelockUnexecutedPredecessor-bytes32-) +- [TimelockUnauthorizedCaller(caller)](#TimelockController-TimelockUnauthorizedCaller-address-) + +
+
+IAccessControl + +- [AccessControlUnauthorizedAccount(account, neededRole)](#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-) +- [AccessControlBadConfirmation()](#IAccessControl-AccessControlBadConfirmation--) + +
+
+
+ + + +
+
+

schedule(address target, uint256 value, bytes data, bytes32 predecessor, bytes32 salt, uint256 delay)

+
+

public

+# +
+
+
+ +Schedule an operation containing a single transaction. + +Emits `CallSalt` if salt is nonzero, and `CallScheduled`. + +Requirements: + +- the caller must have the 'proposer' role. + +
+
+ + + +
+
+

scheduleBatch(address[] targets, uint256[] values, bytes[] payloads, bytes32 predecessor, bytes32 salt, uint256 delay)

+
+

public

+# +
+
+
+ +Schedule an operation containing a batch of transactions. + +Emits `CallSalt` if salt is nonzero, and one `CallScheduled` event per transaction in the batch. + +Requirements: + +- the caller must have the 'proposer' role. + +
+
+ + + +
+
+

cancel(bytes32 id)

+
+

public

+# +
+
+
+ +Cancel an operation. + +Requirements: + +- the caller must have the 'canceller' role. + +
+
+ + + +
+
+

operations() โ†’ struct TimelockControllerEnumerable.Operation[] operations_

+
+

public

+# +
+
+
+ +Return all scheduled operations + +This is designed for view accessors queried without gas fees. Using it in state-changing +functions may become uncallable if the list grows too large. + + +
+
+ + + +
+
+

operations(uint256 start, uint256 end) โ†’ struct TimelockControllerEnumerable.Operation[] operations_

+
+

public

+# +
+
+
+ +Return the operations in the given index range + +
+
+ + + +
+
+

operationsCount() โ†’ uint256 operationsCount_

+
+

public

+# +
+
+
+ +Return the number of operations from the set + +
+
+ + + +
+
+

operation(uint256 index) โ†’ struct TimelockControllerEnumerable.Operation operation_

+
+

public

+# +
+
+
+ +Return the operation at the given index + +
+
+ + + +
+
+

operation(bytes32 id) โ†’ struct TimelockControllerEnumerable.Operation operation_

+
+

public

+# +
+
+
+ +Return the operation with the given id + +
+
+ + + +
+
+

operationsBatch() โ†’ struct TimelockControllerEnumerable.OperationBatch[] operationsBatch_

+
+

public

+# +
+
+
+ +Return all scheduled operation batches + +This is designed for view accessors queried without gas fees. Using it in state-changing +functions may become uncallable if the list grows too large. + + +
+
+ + + +
+
+

operationsBatch(uint256 start, uint256 end) โ†’ struct TimelockControllerEnumerable.OperationBatch[] operationsBatch_

+
+

public

+# +
+
+
+ +Return the operationsBatch in the given index range + +
+
+ + + +
+
+

operationsBatchCount() โ†’ uint256 operationsBatchCount_

+
+

public

+# +
+
+
+ +Return the number of operationsBatch from the set + +
+
+ + + +
+
+

operationBatch(uint256 index) โ†’ struct TimelockControllerEnumerable.OperationBatch operationBatch_

+
+

public

+# +
+
+
+ +Return the operationsBatch at the given index + +
+
+ + + +
+
+

operationBatch(bytes32 id) โ†’ struct TimelockControllerEnumerable.OperationBatch operationBatch_

+
+

public

+# +
+
+
+ +Return the operationsBatch with the given id + +
+
+ + + +
+
+

OperationIndexNotFound(uint256 index)

+
+

error

+# +
+
+
+ +The error when the operation index is not found + +
+
+ + + +
+
+

OperationIdNotFound(bytes32 id)

+
+

error

+# +
+
+
+ +The error when the operation id is not found + +
+
+ + + +
+
+

OperationBatchIndexNotFound(uint256 index)

+
+

error

+# +
+
+
+ +The error when the operation batch index is not found + +
+
+ + + +
+
+

OperationBatchIdNotFound(bytes32 id)

+
+

error

+# +
+
+
+ +The error when the operation batch id is not found + +
+
+ + + +
+
+

InvalidIndexRange(uint256 start, uint256 end)

+
+

error

+# +
+
+
+ +The error when the index range is invalid + +
+
+ diff --git a/content/community-contracts/api/index.mdx b/content/community-contracts/api/index.mdx index 14a2be3d..88b57555 100644 --- a/content/community-contracts/api/index.mdx +++ b/content/community-contracts/api/index.mdx @@ -1,17 +1,18 @@ --- title: API Reference +description: API reference for OpenZeppelin Community Contracts --- -## Core APIs +# API Reference -- **[Access](./api/access)** - Access control and permission management -- **[Account](./api/account)** - Account abstraction and smart account functionality -- **[Crosschain](./api/crosschain)** - Cross-chain communication and bridging utilities -- **[Interfaces](./api/interfaces)** - Standard interfaces and contract definitions -- **[Proxy](./api/proxy)** - Proxy patterns and upgradeable contract utilities -- **[Token](./api/token)** - Token standards and implementations +These pages contain the API reference for the OpenZeppelin Community Contracts library. -## Utilities - -- **[Utils](./api/utils)** - General utility functions and helpers - - **[Cryptography](./api/utils/cryptography)** - Cryptographic functions and primitives +- [Access](/community-contracts/api/access) - Access control utilities +- [Account](/community-contracts/api/account) - ERC-4337 account modules and paymasters +- [Crosschain](/community-contracts/api/crosschain) - Cross-chain communication gateways +- [Governance](/community-contracts/api/governance) - Governance extensions +- [Interfaces](/community-contracts/api/interfaces) - Standardized interfaces +- [Proxy](/community-contracts/api/proxy) - Proxy patterns +- [Token](/community-contracts/api/token) - Token extensions and utilities +- [Utils](/community-contracts/api/utils) - Miscellaneous utilities +- [Cryptography](/community-contracts/api/utils/cryptography) - Cryptographic primitives diff --git a/content/community-contracts/api/interfaces.mdx b/content/community-contracts/api/interfaces.mdx index e0833c3d..7e85e3d4 100644 --- a/content/community-contracts/api/interfaces.mdx +++ b/content/community-contracts/api/interfaces.mdx @@ -7,224 +7,259 @@ description: "Smart contract interfaces utilities and implementations" These interfaces are available as `.sol` files. These are useful to interact with third party contracts that implement them. -* [`IERC7786GatewaySource`](#IERC7786GatewaySource), [`IERC7786Receiver`](#IERC7786Receiver) -* [`IERC7802`](#IERC7802) -* [`IERC7821`](#IERC7821) * `IERC7913SignatureVerifier` -* [`IERC7943`](#IERC7943) +* `IERC7943` ## Detailed ABI -[`IERC7786GatewaySource`](#IERC7786GatewaySource) +{`IERC7913SignatureVerifier`} + +{`IERC7943`} -[`IERC7786Receiver`](#IERC7786Receiver) + -[`IERC7802`](#IERC7802) +
-[`IERC7821`](#IERC7821) +## `IERC7786Attributes` -{`IERC7913SignatureVerifier`} + + + + +
+ +```solidity +import "@openzeppelin/community-contracts/contracts/interfaces/IERC7786Attributes.sol"; +``` + +Standard attributes for ERC-7786. These attributes may be standardized in different ERCs. + +
+

Functions

+
+- [requestRelay(value, gasLimit, refundRecipient)](#IERC7786Attributes-requestRelay-uint256-uint256-address-) +
+
+ + + +
+
+

requestRelay(uint256 value, uint256 gasLimit, address refundRecipient)

+
+

external

+# +
+
+
-[`IERC7943`](#IERC7943) +
+
- +
-## `IERC7786GatewaySource` +## `IERC7943Fungible` - +
```solidity -import "@openzeppelin/community-contracts/interfaces/IERC7786.sol"; +import "@openzeppelin/community-contracts/contracts/interfaces/IERC7943.sol"; ``` -Interface for ERC-7786 source gateways. - -See ERC-7786 for more details -

Functions

-- [supportsAttribute(selector)](#IERC7786GatewaySource-supportsAttribute-bytes4-) -- [sendMessage(recipient, payload, attributes)](#IERC7786GatewaySource-sendMessage-bytes-bytes-bytes---) +- [forcedTransfer(from, to, amount)](#IERC7943Fungible-forcedTransfer-address-address-uint256-) +- [setFrozenTokens(account, amount)](#IERC7943Fungible-setFrozenTokens-address-uint256-) +- [canTransact(account)](#IERC7943Fungible-canTransact-address-) +- [getFrozenTokens(account)](#IERC7943Fungible-getFrozenTokens-address-) +- [canTransfer(from, to, amount)](#IERC7943Fungible-canTransfer-address-address-uint256-) +
+IERC165 + +- [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-- [MessageSent(sendId, sender, receiver, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) +- [ForcedTransfer(from, to, amount)](#IERC7943Fungible-ForcedTransfer-address-address-uint256-) +- [Frozen(account, amount)](#IERC7943Fungible-Frozen-address-uint256-)

Errors

-- [UnsupportedAttribute(selector)](#IERC7786GatewaySource-UnsupportedAttribute-bytes4-) +- [ERC7943CannotTransact(account)](#IERC7943Fungible-ERC7943CannotTransact-address-) +- [ERC7943CannotTransfer(from, to, amount)](#IERC7943Fungible-ERC7943CannotTransfer-address-address-uint256-) +- [ERC7943InsufficientUnfrozenBalance(account, amount, unfrozen)](#IERC7943Fungible-ERC7943InsufficientUnfrozenBalance-address-uint256-uint256-)
- +
-

supportsAttribute(bytes4 selector) โ†’ bool

+

forcedTransfer(address from, address to, uint256 amount) โ†’ bool result

external

-# +#
-Getter to check whether an attribute is supported or not. +Requires specific authorization. Used for regulatory compliance or recovery scenarios.
- +
-

sendMessage(bytes recipient, bytes payload, bytes[] attributes) โ†’ bytes32 sendId

+

setFrozenTokens(address account, uint256 amount) โ†’ bool result

external

-# +#
-Endpoint for creating a new message. If the message requires further (gateway specific) processing before -it can be sent to the destination chain, then a non-zero `outboxId` must be returned. Otherwise, the -message MUST be sent and this function must return 0. - -* MUST emit a [`IERC7786GatewaySource.MessageSent`](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) event. - -If any of the `attributes` is not supported, this function SHOULD revert with an [`IERC7786GatewaySource.UnsupportedAttribute`](#IERC7786GatewaySource-UnsupportedAttribute-bytes4-) error. -Other errors SHOULD revert with errors not specified in ERC-7786. +Requires specific authorization. Frozen tokens cannot be transferred by the account.
- +
-

MessageSent(bytes32 indexed sendId, bytes sender, bytes receiver, bytes payload, uint256 value, bytes[] attributes)

+

canTransact(address account) โ†’ bool allowed

-

event

-# +

external

+#
-
-Event emitted when a message is created. If `outboxId` is zero, no further processing is necessary. If -`outboxId` is not zero, then further (gateway specific, and non-standardized) action is required. +This is often used for allowlist/KYC/KYB/AML checks.
- +
-

UnsupportedAttribute(bytes4 selector)

+

getFrozenTokens(address account) โ†’ uint256 amount

-

error

-# +

external

+#
-This error is thrown when a message creation fails because of an unsupported attribute being specified. +It could return an amount higher than the account's balance.
- - -
- -## `IERC7786Receiver` - - - - + +
+
+

canTransfer(address from, address to, uint256 amount) โ†’ bool allowed

+
+

external

+#
+
+
-```solidity -import "@openzeppelin/community-contracts/interfaces/IERC7786.sol"; -``` - -Interface for the ERC-7786 client contract (receiver). - -See ERC-7786 for more details +This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions. -
-

Functions

-
-- [receiveMessage(receiveId, sender, payload)](#IERC7786Receiver-receiveMessage-bytes32-bytes-bytes-)
- +
-

receiveMessage(bytes32 receiveId, bytes sender, bytes payload) โ†’ bytes4

+

ForcedTransfer(address indexed from, address indexed to, uint256 amount)

-

external

-# +

event

+#
-
-Endpoint for receiving cross-chain message. +
-This function may be called directly by the gateway. +
+
+ +
+
+

Frozen(address indexed account, uint256 amount)

+
+

event

+#
- +
-
+
+
-## `IERC7786Attributes` + - - - +
+
+

ERC7943CannotTransact(address account)

+
+

error

+# +
+
+
+
-```solidity -import "@openzeppelin/community-contracts/interfaces/IERC7786Attributes.sol"; -``` + -Standard attributes for ERC-7786. These attributes may be standardized in different ERCs. +
+
+

ERC7943CannotTransfer(address from, address to, uint256 amount)

+
+

error

+# +
+
+
-
-

Functions

-
-- [requestRelay(value, gasLimit, refundRecipient)](#IERC7786Attributes-requestRelay-uint256-uint256-address-)
- +
-

requestRelay(uint256 value, uint256 gasLimit, address refundRecipient)

+

ERC7943InsufficientUnfrozenBalance(address account, uint256 amount, uint256 unfrozen)

-

external

-# +

error

+#
@@ -232,244 +267,275 @@ Standard attributes for ERC-7786. These attributes may be standardized in differ
- +
-## `IERC7802` +## `IERC7943NonFungible` - +
```solidity -import "@openzeppelin/community-contracts/interfaces/IERC7802.sol"; +import "@openzeppelin/community-contracts/contracts/interfaces/IERC7943.sol"; ```

Functions

-- [crosschainMint(_to, _amount)](#IERC7802-crosschainMint-address-uint256-) -- [crosschainBurn(_from, _amount)](#IERC7802-crosschainBurn-address-uint256-) -#### IERC165 [!toc] +- [forcedTransfer(from, to, tokenId)](#IERC7943NonFungible-forcedTransfer-address-address-uint256-) +- [setFrozenTokens(account, tokenId, frozenStatus)](#IERC7943NonFungible-setFrozenTokens-address-uint256-bool-) +- [canTransact(account)](#IERC7943NonFungible-canTransact-address-) +- [getFrozenTokens(account, tokenId)](#IERC7943NonFungible-getFrozenTokens-address-uint256-) +- [canTransfer(from, to, tokenId)](#IERC7943NonFungible-canTransfer-address-address-uint256-) +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-- [CrosschainMint(to, amount, sender)](#IERC7802-CrosschainMint-address-uint256-address-) -- [CrosschainBurn(from, amount, sender)](#IERC7802-CrosschainBurn-address-uint256-address-) -#### IERC165 [!toc] +- [ForcedTransfer(from, to, tokenId)](#IERC7943NonFungible-ForcedTransfer-address-address-uint256-) +- [Frozen(account, tokenId, frozenStatus)](#IERC7943NonFungible-Frozen-address-uint256-bool-) +
+
+ +
+

Errors

+
+- [ERC7943CannotTransact(account)](#IERC7943NonFungible-ERC7943CannotTransact-address-) +- [ERC7943CannotTransfer(from, to, tokenId)](#IERC7943NonFungible-ERC7943CannotTransfer-address-address-uint256-) +- [ERC7943InsufficientUnfrozenBalance(account, tokenId)](#IERC7943NonFungible-ERC7943InsufficientUnfrozenBalance-address-uint256-)
- +
-

crosschainMint(address _to, uint256 _amount)

+

forcedTransfer(address from, address to, uint256 tokenId) โ†’ bool result

external

-# +#
+Requires specific authorization. Used for regulatory compliance or recovery scenarios. +
- +
-

crosschainBurn(address _from, uint256 _amount)

+

setFrozenTokens(address account, uint256 tokenId, bool frozenStatus) โ†’ bool result

external

-# +#
+Requires specific authorization. Frozen tokens cannot be transferred by the account. +
- +
-

CrosschainMint(address indexed to, uint256 amount, address indexed sender)

+

canTransact(address account) โ†’ bool allowed

-

event

-# +

external

+#
-
+This is often used for allowlist/KYC/KYB/AML checks. +
- + +
-

CrosschainBurn(address indexed from, uint256 amount, address indexed sender)

+

getFrozenTokens(address account, uint256 tokenId) โ†’ bool frozenStatus

-

event

-# +

external

+#
-
+It could return true even if account does not hold the token. +
- - -
- -## `IERC7821` - - - - + +
+
+

canTransfer(address from, address to, uint256 tokenId) โ†’ bool allowed

+
+

external

+#
+
+
-```solidity -import "@openzeppelin/community-contracts/interfaces/IERC7821.sol"; -``` - -Interface for minimal batch executor. +This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions. -
-

Functions

-
-- [execute(mode, executionData)](#IERC7821-execute-bytes32-bytes-) -- [supportsExecutionMode(mode)](#IERC7821-supportsExecutionMode-bytes32-)
- +
-

execute(bytes32 mode, bytes executionData)

+

ForcedTransfer(address indexed from, address indexed to, uint256 indexed tokenId)

-

external

-# +

event

+#
-
- -Executes the calls in `executionData`. -Reverts and bubbles up error if any call fails. -`executionData` encoding: +
-* If `opData` is empty, `executionData` is simply `abi.encode(calls)`. -* Else, `executionData` is `abi.encode(calls, opData)`. - See: https://eips.ethereum.org/EIPS/eip-7579 +
+
+ -Supported modes: +
+
+

Frozen(address indexed account, uint256 indexed tokenId, bool indexed frozenStatus)

+
+

event

+# +
+
-* `bytes32(0x01000000000000000000...)`: does not support optional `opData`. -* `bytes32(0x01000000000078210001...)`: supports optional `opData`. +
-Authorization checks: +
+
-* If `opData` is empty, the implementation SHOULD require that - `msg.sender == address(this)`. -* If `opData` is not empty, the implementation SHOULD use the signature - encoded in `opData` to determine if the caller can perform the execution. + -`opData` may be used to store additional data for authentication, -paymaster data, gas limits, etc. +
+
+

ERC7943CannotTransact(address account)

+
+

error

+# +
+
+
- +
-

supportsExecutionMode(bytes32 mode) โ†’ bool

+

ERC7943CannotTransfer(address from, address to, uint256 tokenId)

-

external

-# +

error

+#
-This function is provided for frontends to detect support. -Only returns true for: +
+
+ + -* `bytes32(0x01000000000000000000...)`: does not support optional `opData`. -* `bytes32(0x01000000000078210001...)`: supports optional `opData`. +
+
+

ERC7943InsufficientUnfrozenBalance(address account, uint256 tokenId)

+
+

error

+# +
+
+
- +
-## `IERC7943` +## `IERC7943MultiToken` - +
```solidity -import "@openzeppelin/community-contracts/interfaces/IERC7943.sol"; +import "@openzeppelin/community-contracts/contracts/interfaces/IERC7943.sol"; ```

Functions

-- [forceTransfer(from, to, tokenId, amount)](#IERC7943-forceTransfer-address-address-uint256-uint256-) -- [setFrozen(user, tokenId, amount)](#IERC7943-setFrozen-address-uint256-uint256-) -- [getFrozen(user, tokenId)](#IERC7943-getFrozen-address-uint256-) -- [isTransferAllowed(from, to, tokenId, amount)](#IERC7943-isTransferAllowed-address-address-uint256-uint256-) -- [isUserAllowed(user)](#IERC7943-isUserAllowed-address-) -#### IERC165 [!toc] +- [forcedTransfer(from, to, tokenId, amount)](#IERC7943MultiToken-forcedTransfer-address-address-uint256-uint256-) +- [setFrozenTokens(account, tokenId, amount)](#IERC7943MultiToken-setFrozenTokens-address-uint256-uint256-) +- [canTransact(account)](#IERC7943MultiToken-canTransact-address-) +- [getFrozenTokens(account, tokenId)](#IERC7943MultiToken-getFrozenTokens-address-uint256-) +- [canTransfer(from, to, tokenId, amount)](#IERC7943MultiToken-canTransfer-address-address-uint256-uint256-) +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-- [ForcedTransfer(from, to, tokenId, amount)](#IERC7943-ForcedTransfer-address-address-uint256-uint256-) -- [Frozen(user, tokenId, amount)](#IERC7943-Frozen-address-uint256-uint256-) -#### IERC165 [!toc] +- [ForcedTransfer(from, to, tokenId, amount)](#IERC7943MultiToken-ForcedTransfer-address-address-uint256-uint256-) +- [Frozen(account, tokenId, amount)](#IERC7943MultiToken-Frozen-address-uint256-uint256-)

Errors

-- [ERC7943NotAllowedUser(account)](#IERC7943-ERC7943NotAllowedUser-address-) -- [ERC7943NotAllowedTransfer(from, to, tokenId, amount)](#IERC7943-ERC7943NotAllowedTransfer-address-address-uint256-uint256-) -- [ERC7943InsufficientUnfrozenBalance(user, tokenId, amount, unfrozen)](#IERC7943-ERC7943InsufficientUnfrozenBalance-address-uint256-uint256-uint256-) -#### IERC165 [!toc] +- [ERC7943CannotTransact(account)](#IERC7943MultiToken-ERC7943CannotTransact-address-) +- [ERC7943CannotTransfer(from, to, tokenId, amount)](#IERC7943MultiToken-ERC7943CannotTransfer-address-address-uint256-uint256-) +- [ERC7943InsufficientUnfrozenBalance(account, tokenId, amount, unfrozen)](#IERC7943MultiToken-ERC7943InsufficientUnfrozenBalance-address-uint256-uint256-uint256-)
- +
-

forceTransfer(address from, address to, uint256 tokenId, uint256 amount)

+

forcedTransfer(address from, address to, uint256 tokenId, uint256 amount) โ†’ bool result

external

-# +#
@@ -479,80 +545,82 @@ Requires specific authorization. Used for regulatory compliance or recovery scen
- +
-

setFrozen(address user, uint256 tokenId, uint256 amount)

+

setFrozenTokens(address account, uint256 tokenId, uint256 amount) โ†’ bool result

external

-# +#
-Requires specific authorization. Frozen tokens cannot be transferred by the user. +Requires specific authorization. Frozen tokens cannot be transferred by the account.
- +
-

getFrozen(address user, uint256 tokenId) โ†’ uint256 amount

+

canTransact(address account) โ†’ bool allowed

external

-# +#
+This is often used for allowlist/KYC/KYB/AML checks. +
- +
-

isTransferAllowed(address from, address to, uint256 tokenId, uint256 amount) โ†’ bool allowed

+

getFrozenTokens(address account, uint256 tokenId) โ†’ uint256 amount

external

-# +#
-This may involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions. +It could return an amount higher than the account's balance.
- +
-

isUserAllowed(address user) โ†’ bool allowed

+

canTransfer(address from, address to, uint256 tokenId, uint256 amount) โ†’ bool allowed

external

-# +#
-This is often used for allowlist/KYC/KYB/AML checks. +This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.
- +
-

ForcedTransfer(address indexed from, address indexed to, uint256 tokenId, uint256 amount)

+

ForcedTransfer(address indexed from, address indexed to, uint256 indexed tokenId, uint256 amount)

event

-# +#
@@ -560,14 +628,14 @@ This is often used for allowlist/KYC/KYB/AML checks.
- +
-

Frozen(address indexed user, uint256 indexed tokenId, uint256 amount)

+

Frozen(address indexed account, uint256 indexed tokenId, uint256 amount)

event

-# +#
@@ -576,14 +644,14 @@ This is often used for allowlist/KYC/KYB/AML checks.
- +
-

ERC7943NotAllowedUser(address account)

+

ERC7943CannotTransact(address account)

error

-# +#
@@ -591,14 +659,14 @@ This is often used for allowlist/KYC/KYB/AML checks.
- +
-

ERC7943NotAllowedTransfer(address from, address to, uint256 tokenId, uint256 amount)

+

ERC7943CannotTransfer(address from, address to, uint256 tokenId, uint256 amount)

error

-# +#
@@ -606,14 +674,14 @@ This is often used for allowlist/KYC/KYB/AML checks.
- +
-

ERC7943InsufficientUnfrozenBalance(address user, uint256 tokenId, uint256 amount, uint256 unfrozen)

+

ERC7943InsufficientUnfrozenBalance(address account, uint256 tokenId, uint256 amount, uint256 unfrozen)

error

-# +#
@@ -625,16 +693,16 @@ This is often used for allowlist/KYC/KYB/AML checks.
-## `IDKIMRegistry` +## `IDKIMRegistry` - +
```solidity -import "@openzeppelin/community-contracts/interfaces/IERC7969.sol"; +import "@openzeppelin/community-contracts/contracts/interfaces/IERC7969.sol"; ``` This interface provides a standard way to register and validate DKIM public key hashes onchain @@ -711,3 +779,4 @@ Emitted when a DKIM public key hash is revoked for a domain
+ diff --git a/content/community-contracts/api/proxy.mdx b/content/community-contracts/api/proxy.mdx index 3109f979..1cb68017 100644 --- a/content/community-contracts/api/proxy.mdx +++ b/content/community-contracts/api/proxy.mdx @@ -15,16 +15,16 @@ Variants of proxy patterns, which are contracts that allow to forward a call to
-## `HybridProxy` +## `HybridProxy` - +
```solidity -import "@openzeppelin/community-contracts/proxy/HybridProxy.sol"; +import "@openzeppelin/community-contracts/contracts/proxy/HybridProxy.sol"; ``` A version of an ERC-1967 proxy that uses the address stored in the implementation slot as a beacon. @@ -45,10 +45,14 @@ the returned address will be used as this proxy's implementation.
- [constructor(implementation, data)](#HybridProxy-constructor-address-bytes-) - [_implementation()](#HybridProxy-_implementation--) -#### Proxy [!toc] +
+Proxy + - [_delegate(implementation)](#Proxy-_delegate-address-) - [_fallback()](#Proxy-_fallback--) - [fallback()](#Proxy-fallback--) + +
@@ -92,3 +96,4 @@ define this function, mistakenly identifying it as a beacon.
+ diff --git a/content/community-contracts/api/token.mdx b/content/community-contracts/api/token.mdx index 7ef43718..bb76aa70 100644 --- a/content/community-contracts/api/token.mdx +++ b/content/community-contracts/api/token.mdx @@ -32,19 +32,19 @@ Set of extensions and utilities for tokens (e.g ERC-20, ERC-721, ERC-1155) and d
-## `ERC20Allowlist` +## `ERC20Allowlist` - +
```solidity -import "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Allowlist.sol"; +import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Allowlist.sol"; ``` -Extension of [`PaymasterERC20`](./account#PaymasterERC20) that allows to implement an allowlist +Extension of `ERC20` that allows to implement an allowlist mechanism that can be managed by an authorized account with the [`ERC20Allowlist._disallowUser`](#ERC20Allowlist-_disallowUser-address-) and [`ERC20Allowlist._allowUser`](#ERC20Allowlist-_allowUser-address-) functions. @@ -62,29 +62,30 @@ Deprecated. Use [`ERC20Restricted`](#ERC20Restricted) instead.

Functions

-- [allowed(./account)](#ERC20Allowlist-allowed-address-) +- [allowed(account)](#ERC20Allowlist-allowed-address-) - [_allowUser(user)](#ERC20Allowlist-_allowUser-address-) - [_disallowUser(user)](#ERC20Allowlist-_disallowUser-address-) - [_update(from, to, value)](#ERC20Allowlist-_update-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20Allowlist-_approve-address-address-uint256-bool-) -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) - [totalSupply()](#ERC20-totalSupply--) -- [balanceOf(./account)](#ERC20-balanceOf-address-) +- [balanceOf(account)](#ERC20-balanceOf-address-) - [transfer(to, value)](#ERC20-transfer-address-uint256-) - [allowance(owner, spender)](#ERC20-allowance-address-address-) - [approve(spender, value)](#ERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) - [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) -- [_mint(./account, value)](#ERC20-_mint-address-uint256-) -- [_burn(./account, value)](#ERC20-_burn-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -93,12 +94,13 @@ Deprecated. Use [`ERC20Restricted`](#ERC20Restricted) instead.
- [UserAllowed(user)](#ERC20Allowlist-UserAllowed-address-) - [UserDisallowed(user)](#ERC20Allowlist-UserDisallowed-address-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -106,16 +108,17 @@ Deprecated. Use [`ERC20Restricted`](#ERC20Restricted) instead.

Errors

- [ERC20Disallowed(user)](#ERC20Allowlist-ERC20Disallowed-address-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -260,19 +263,19 @@ The operation failed because the user is not allowed.
-## `ERC20Blocklist` +## `ERC20Blocklist` - +
```solidity -import "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Blocklist.sol"; +import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Blocklist.sol"; ``` -Extension of [`PaymasterERC20`](./account#PaymasterERC20) that allows to implement a blocklist +Extension of `ERC20` that allows to implement a blocklist mechanism that can be managed by an authorized account with the [`ERC20Blocklist._blockUser`](#ERC20Blocklist-_blockUser-address-) and [`ERC20Blocklist._unblockUser`](#ERC20Blocklist-_unblockUser-address-) functions. @@ -290,29 +293,30 @@ Deprecated. Use [`ERC20Restricted`](#ERC20Restricted) instead.

Functions

-- [blocked(./account)](#ERC20Blocklist-blocked-address-) +- [blocked(account)](#ERC20Blocklist-blocked-address-) - [_blockUser(user)](#ERC20Blocklist-_blockUser-address-) - [_unblockUser(user)](#ERC20Blocklist-_unblockUser-address-) - [_update(from, to, value)](#ERC20Blocklist-_update-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20Blocklist-_approve-address-address-uint256-bool-) -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) - [totalSupply()](#ERC20-totalSupply--) -- [balanceOf(./account)](#ERC20-balanceOf-address-) +- [balanceOf(account)](#ERC20-balanceOf-address-) - [transfer(to, value)](#ERC20-transfer-address-uint256-) - [allowance(owner, spender)](#ERC20-allowance-address-address-) - [approve(spender, value)](#ERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) - [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) -- [_mint(./account, value)](#ERC20-_mint-address-uint256-) -- [_burn(./account, value)](#ERC20-_burn-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -321,12 +325,13 @@ Deprecated. Use [`ERC20Restricted`](#ERC20Restricted) instead.
- [UserBlocked(user)](#ERC20Blocklist-UserBlocked-address-) - [UserUnblocked(user)](#ERC20Blocklist-UserUnblocked-address-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -334,16 +339,17 @@ Deprecated. Use [`ERC20Restricted`](#ERC20Restricted) instead.

Errors

- [ERC20Blocked(user)](#ERC20Blocklist-ERC20Blocked-address-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -488,19 +494,19 @@ The operation failed because the user is blocked.
-## `ERC20Collateral` +## `ERC20Collateral` - +
```solidity -import "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Collateral.sol"; +import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Collateral.sol"; ``` -Extension of [`PaymasterERC20`](./account#PaymasterERC20) that limits the supply of tokens based +Extension of `ERC20` that limits the supply of tokens based on a collateral amount and time-based expiration. The [`ERC20Collateral.collateral`](#ERC20Collateral-collateral--) function must be implemented to return the collateral @@ -515,39 +521,39 @@ data. This function can call external oracles or use any local storage. - [CLOCK_MODE()](#ERC20Collateral-CLOCK_MODE--) - [collateral()](#ERC20Collateral-collateral--) - [_update(from, to, value)](#ERC20Collateral-_update-address-address-uint256-) -#### IERC6372 [!toc] -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) - [totalSupply()](#ERC20-totalSupply--) -- [balanceOf(./account)](#ERC20-balanceOf-address-) +- [balanceOf(account)](#ERC20-balanceOf-address-) - [transfer(to, value)](#ERC20-transfer-address-uint256-) - [allowance(owner, spender)](#ERC20-allowance-address-address-) - [approve(spender, value)](#ERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) - [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) -- [_mint(./account, value)](#ERC20-_mint-address-uint256-) -- [_burn(./account, value)](#ERC20-_burn-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### IERC6372 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -556,17 +562,17 @@ data. This function can call external oracles or use any local storage.
- [ERC20ExceededSupply(increasedSupply, cap)](#ERC20Collateral-ERC20ExceededSupply-uint256-uint256-) - [ERC20ExpiredCollateral(timestamp, expiration)](#ERC20Collateral-ERC20ExpiredCollateral-uint48-uint48-) -#### IERC6372 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -711,19 +717,19 @@ Collateral amount has expired.
-## `ERC20Custodian` +## `ERC20Custodian` - +
```solidity -import "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Custodian.sol"; +import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Custodian.sol"; ``` -Extension of [`PaymasterERC20`](./account#PaymasterERC20) that allows to implement a custodian +Extension of `ERC20` that allows to implement a custodian mechanism that can be managed by an authorized account with the [`ERC20Custodian.freeze`](#ERC20Custodian-freeze-address-uint256-) function. @@ -751,28 +757,29 @@ Deprecated. Use [`ERC20Freezable`](#ERC20Freezable) instead.
- [frozen(user)](#ERC20Custodian-frozen-address-) - [freeze(user, amount)](#ERC20Custodian-freeze-address-uint256-) -- [availableBalance(./account)](#ERC20Custodian-availableBalance-address-) +- [availableBalance(account)](#ERC20Custodian-availableBalance-address-) - [_isCustodian(user)](#ERC20Custodian-_isCustodian-address-) - [_update(from, to, value)](#ERC20Custodian-_update-address-address-uint256-) -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) - [totalSupply()](#ERC20-totalSupply--) -- [balanceOf(./account)](#ERC20-balanceOf-address-) +- [balanceOf(account)](#ERC20-balanceOf-address-) - [transfer(to, value)](#ERC20-transfer-address-uint256-) - [allowance(owner, spender)](#ERC20-allowance-address-address-) - [approve(spender, value)](#ERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) - [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) -- [_mint(./account, value)](#ERC20-_mint-address-uint256-) -- [_burn(./account, value)](#ERC20-_burn-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -781,12 +788,13 @@ Deprecated. Use [`ERC20Freezable`](#ERC20Freezable) instead.
- [TokensFrozen(user, amount)](#ERC20Custodian-TokensFrozen-address-uint256-) - [TokensUnfrozen(user, amount)](#ERC20Custodian-TokensUnfrozen-address-uint256-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -796,16 +804,17 @@ Deprecated. Use [`ERC20Freezable`](#ERC20Freezable) instead. - [ERC20InsufficientUnfrozenBalance(user)](#ERC20Custodian-ERC20InsufficientUnfrozenBalance-address-) - [ERC20InsufficientFrozenBalance(user)](#ERC20Custodian-ERC20InsufficientFrozenBalance-address-) - [ERC20NotCustodian()](#ERC20Custodian-ERC20NotCustodian--) -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -911,7 +920,7 @@ Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding this function. -Emits a [`ERC7786OpenBridge.UnsupportedNativeTransfer`](./crosschain#ERC7786OpenBridge-UnsupportedNativeTransfer--) event. +Emits a `Transfer` event. @@ -1006,82 +1015,85 @@ Error thrown when a non-custodian account attempts to perform a custodian-only o
-## `ERC20Freezable` +## `ERC20Freezable` - +
```solidity -import "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Freezable.sol"; +import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Freezable.sol"; ``` -Extension of [`PaymasterERC20`](./account#PaymasterERC20) that allows to implement a freezing +Extension of `ERC20` that allows to implement a freezing mechanism that can be managed by an authorized account with the -`_freezeTokens` and `_unfreezeTokens` functions. +[`ERC20Freezable._setFrozen`](#ERC20Freezable-_setFrozen-address-uint256-) function. The freezing mechanism provides the guarantee to the contract owner (e.g. a DAO or a well-configured multisig) that a specific amount -of tokens held by an account won't be transferable until those -tokens are unfrozen using `_unfreezeTokens`. +of tokens held by an account won't be transferable until the frozen amount +is reduced using [`ERC20Freezable._setFrozen`](#ERC20Freezable-_setFrozen-address-uint256-).

Functions

-- [frozen(./account)](#ERC20Freezable-frozen-address-) -- [available(./account)](#ERC20Freezable-available-address-) -- [_setFrozen(user, amount)](#ERC20Freezable-_setFrozen-address-uint256-) +- [frozen(account)](#ERC20Freezable-frozen-address-) +- [available(account)](#ERC20Freezable-available-address-) +- [_setFrozen(account, amount)](#ERC20Freezable-_setFrozen-address-uint256-) - [_update(from, to, value)](#ERC20Freezable-_update-address-address-uint256-) -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) - [totalSupply()](#ERC20-totalSupply--) -- [balanceOf(./account)](#ERC20-balanceOf-address-) +- [balanceOf(account)](#ERC20-balanceOf-address-) - [transfer(to, value)](#ERC20-transfer-address-uint256-) - [allowance(owner, spender)](#ERC20-allowance-address-address-) - [approve(spender, value)](#ERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) - [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) -- [_mint(./account, value)](#ERC20-_mint-address-uint256-) -- [_burn(./account, value)](#ERC20-_burn-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-- [ERC20InsufficientUnfrozenBalance(user, needed, available)](#ERC20Freezable-ERC20InsufficientUnfrozenBalance-address-uint256-uint256-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] +- [ERC20InsufficientUnfrozenBalance(account, needed, available)](#ERC20Freezable-ERC20InsufficientUnfrozenBalance-address-uint256-uint256-) +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -1123,7 +1135,7 @@ Returns the available (unfrozen) balance of an account. Up to `balanceOf`.
-

_setFrozen(address user, uint256 amount)

+

_setFrozen(address account, uint256 amount)

internal

# @@ -1131,7 +1143,7 @@ Returns the available (unfrozen) balance of an account. Up to `balanceOf`.
-Internal function to set the frozen token amount for a user. +Internal function to set the frozen token amount for a account.
@@ -1161,7 +1173,7 @@ Requirements:
-

ERC20InsufficientUnfrozenBalance(address user, uint256 needed, uint256 available)

+

ERC20InsufficientUnfrozenBalance(address account, uint256 needed, uint256 available)

error

# @@ -1169,7 +1181,7 @@ Requirements:
-The operation failed because the user has insufficient unfrozen balance. +The operation failed because the account has insufficient unfrozen balance.
@@ -1178,85 +1190,88 @@ The operation failed because the user has insufficient unfrozen balance.
-## `ERC20Restricted` +## `ERC20Restricted` - +
```solidity -import "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Restricted.sol"; +import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Restricted.sol"; ``` -Extension of [`PaymasterERC20`](./account#PaymasterERC20) that allows to implement user account transfer restrictions -through the [`IERC7943.isUserAllowed`](./interfaces#IERC7943-isUserAllowed-address-) function. Inspired by [EIP-7943](https://eips.ethereum.org/EIPS/eip-7943). +Extension of `ERC20` that allows to implement user account transfer restrictions +through the [`ERC20Restricted.canTransact`](#ERC20Restricted-canTransact-address-) function. Inspired by [EIP-7943](https://eips.ethereum.org/EIPS/eip-7943). -By default, each account has no explicit restriction. The [`IERC7943.isUserAllowed`](./interfaces#IERC7943-isUserAllowed-address-) function acts as -a blocklist. Developers can override [`IERC7943.isUserAllowed`](./interfaces#IERC7943-isUserAllowed-address-) to check that `restriction == ALLOWED` +By default, each account has no explicit restriction. The [`ERC20Restricted.canTransact`](#ERC20Restricted-canTransact-address-) function acts as +a blocklist. Developers can override [`ERC20Restricted.canTransact`](#ERC20Restricted-canTransact-address-) to check that `restriction == ALLOWED` to implement an allowlist.

Functions

-- [getRestriction(./account)](#ERC20Restricted-getRestriction-address-) -- [isUserAllowed(./account)](#ERC20Restricted-isUserAllowed-address-) +- [getRestriction(account)](#ERC20Restricted-getRestriction-address-) +- [canTransact(account)](#ERC20Restricted-canTransact-address-) - [_update(from, to, value)](#ERC20Restricted-_update-address-address-uint256-) -- [_setRestriction(./account, restriction)](#ERC20Restricted-_setRestriction-address-enum-ERC20Restricted-Restriction-) -- [_blockUser(./account)](#ERC20Restricted-_blockUser-address-) -- [_allowUser(./account)](#ERC20Restricted-_allowUser-address-) -- [_resetUser(./account)](#ERC20Restricted-_resetUser-address-) -- [_checkRestriction(./account)](#ERC20Restricted-_checkRestriction-address-) -#### ERC20 [!toc] +- [_setRestriction(account, restriction)](#ERC20Restricted-_setRestriction-address-enum-ERC20Restricted-Restriction-) +- [_blockUser(account)](#ERC20Restricted-_blockUser-address-) +- [_allowUser(account)](#ERC20Restricted-_allowUser-address-) +- [_resetUser(account)](#ERC20Restricted-_resetUser-address-) +- [_checkRestriction(account)](#ERC20Restricted-_checkRestriction-address-) +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) - [totalSupply()](#ERC20-totalSupply--) -- [balanceOf(./account)](#ERC20-balanceOf-address-) +- [balanceOf(account)](#ERC20-balanceOf-address-) - [transfer(to, value)](#ERC20-transfer-address-uint256-) - [allowance(owner, spender)](#ERC20-allowance-address-address-) - [approve(spender, value)](#ERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) - [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) -- [_mint(./account, value)](#ERC20-_mint-address-uint256-) -- [_burn(./account, value)](#ERC20-_burn-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-- [UserRestrictionsUpdated(./account, restriction)](#ERC20Restricted-UserRestrictionsUpdated-address-enum-ERC20Restricted-Restriction-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +- [UserRestrictionsUpdated(account, restriction)](#ERC20Restricted-UserRestrictionsUpdated-address-enum-ERC20Restricted-Restriction-) +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-- [ERC20UserRestricted(./account)](#ERC20Restricted-ERC20UserRestricted-address-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] +- [ERC20UserRestricted(account)](#ERC20Restricted-ERC20UserRestricted-address-) +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -1277,14 +1292,14 @@ Returns the restriction of a user account.
- +
-

isUserAllowed(address account) โ†’ bool

+

canTransact(address account) โ†’ bool

public

-# +#
@@ -1296,8 +1311,8 @@ Default implementation only disallows explicitly BLOCKED accounts (i.e. a blockl To convert into an allowlist, override as: ```solidity -function isUserAllowed(address account) public view virtual override returns (bool) { - return getRestriction(./account) == Restriction.ALLOWED; +function canTransact(address account) public view virtual override returns (bool) { + return getRestriction(account) == Restriction.ALLOWED; } ``` @@ -1320,8 +1335,8 @@ See `ERC20-_update`. Enforces restriction transfers (excluding minting and burni Requirements: -* `from` must be allowed to transfer tokens (see [`IERC7943.isUserAllowed`](./interfaces#IERC7943-isUserAllowed-address-)). -* `to` must be allowed to receive tokens (see [`IERC7943.isUserAllowed`](./interfaces#IERC7943-isUserAllowed-address-)). +* `from` must be allowed to transfer tokens (see [`ERC20Restricted.canTransact`](#ERC20Restricted-canTransact-address-)). +* `to` must be allowed to receive tokens (see [`ERC20Restricted.canTransact`](#ERC20Restricted-canTransact-address-)).
@@ -1450,125 +1465,150 @@ The operation failed because the user account is restricted.
-## `ERC20uRWA` +## `ERC20uRWA` - +
```solidity -import "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20uRWA.sol"; +import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20uRWA.sol"; ``` -Extension of [`PaymasterERC20`](./account#PaymasterERC20) according to [EIP-7943](https://eips.ethereum.org/EIPS/eip-7943). +Extension of `ERC20` according to [EIP-7943](https://eips.ethereum.org/EIPS/eip-7943). -Combines standard ERC-20 functionality with RWA-specific features like user restrictions, -asset freezing, and forced asset transfers. +Combines standard ERC-20 functionality with RWA-specific features like account restrictions, +asset freezing, and forced asset transfers. This contract doesn't expose minting or burning +capabilities; if implemented in derived contracts as needed, they must include 7943-specific +logic.

Functions

-- [isUserAllowed(user)](#ERC20uRWA-isUserAllowed-address-) +- [canTransact(account)](#ERC20uRWA-canTransact-address-) - [supportsInterface(interfaceId)](#ERC20uRWA-supportsInterface-bytes4-) -- [isTransferAllowed(from, to, , amount)](#ERC20uRWA-isTransferAllowed-address-address-uint256-uint256-) -- [getFrozen(user, )](#ERC20uRWA-getFrozen-address-uint256-) -- [setFrozen(user, , amount)](#ERC20uRWA-setFrozen-address-uint256-uint256-) -- [forceTransfer(from, to, , amount)](#ERC20uRWA-forceTransfer-address-address-uint256-uint256-) +- [canTransfer(from, to, amount)](#ERC20uRWA-canTransfer-address-address-uint256-) +- [getFrozenTokens(account)](#ERC20uRWA-getFrozenTokens-address-) +- [setFrozenTokens(account, amount)](#ERC20uRWA-setFrozenTokens-address-uint256-) +- [forcedTransfer(from, to, amount)](#ERC20uRWA-forcedTransfer-address-address-uint256-) - [_update(from, to, amount)](#ERC20uRWA-_update-address-address-uint256-) - [_checkEnforcer(from, to, amount)](#ERC20uRWA-_checkEnforcer-address-address-uint256-) -- [_checkFreezer(user, amount)](#ERC20uRWA-_checkFreezer-address-uint256-) -#### IERC7943 [!toc] -#### ERC20Restricted [!toc] -- [getRestriction(./account)](#ERC20Restricted-getRestriction-address-) -- [_setRestriction(./account, restriction)](#ERC20Restricted-_setRestriction-address-enum-ERC20Restricted-Restriction-) -- [_blockUser(./account)](#ERC20Restricted-_blockUser-address-) -- [_allowUser(./account)](#ERC20Restricted-_allowUser-address-) -- [_resetUser(./account)](#ERC20Restricted-_resetUser-address-) -- [_checkRestriction(./account)](#ERC20Restricted-_checkRestriction-address-) -#### ERC20Freezable [!toc] -- [frozen(./account)](#ERC20Freezable-frozen-address-) -- [available(./account)](#ERC20Freezable-available-address-) -- [_setFrozen(user, amount)](#ERC20Freezable-_setFrozen-address-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] +- [_checkFreezer(account, amount)](#ERC20uRWA-_checkFreezer-address-uint256-) +
+ERC20Restricted + +- [getRestriction(account)](#ERC20Restricted-getRestriction-address-) +- [_setRestriction(account, restriction)](#ERC20Restricted-_setRestriction-address-enum-ERC20Restricted-Restriction-) +- [_blockUser(account)](#ERC20Restricted-_blockUser-address-) +- [_allowUser(account)](#ERC20Restricted-_allowUser-address-) +- [_resetUser(account)](#ERC20Restricted-_resetUser-address-) +- [_checkRestriction(account)](#ERC20Restricted-_checkRestriction-address-) + +
+
+ERC20Freezable + +- [frozen(account)](#ERC20Freezable-frozen-address-) +- [available(account)](#ERC20Freezable-available-address-) +- [_setFrozen(account, amount)](#ERC20Freezable-_setFrozen-address-uint256-) + +
+
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) - [totalSupply()](#ERC20-totalSupply--) -- [balanceOf(./account)](#ERC20-balanceOf-address-) +- [balanceOf(account)](#ERC20-balanceOf-address-) - [transfer(to, value)](#ERC20-transfer-address-uint256-) - [allowance(owner, spender)](#ERC20-allowance-address-address-) - [approve(spender, value)](#ERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) - [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) -- [_mint(./account, value)](#ERC20-_mint-address-uint256-) -- [_burn(./account, value)](#ERC20-_burn-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### IERC7943 [!toc] -- [ForcedTransfer(from, to, tokenId, amount)](#IERC7943-ForcedTransfer-address-address-uint256-uint256-) -- [Frozen(user, tokenId, amount)](#IERC7943-Frozen-address-uint256-uint256-) -#### ERC20Restricted [!toc] -- [UserRestrictionsUpdated(./account, restriction)](#ERC20Restricted-UserRestrictionsUpdated-address-enum-ERC20Restricted-Restriction-) -#### ERC20Freezable [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC7943Fungible + +- [ForcedTransfer(from, to, amount)](#IERC7943Fungible-ForcedTransfer-address-address-uint256-) +- [Frozen(account, amount)](#IERC7943Fungible-Frozen-address-uint256-) + +
+
+ERC20Restricted + +- [UserRestrictionsUpdated(account, restriction)](#ERC20Restricted-UserRestrictionsUpdated-address-enum-ERC20Restricted-Restriction-) + +
+
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-#### IERC7943 [!toc] -- [ERC7943NotAllowedUser(./account)](#IERC7943-ERC7943NotAllowedUser-address-) -- [ERC7943NotAllowedTransfer(from, to, tokenId, amount)](#IERC7943-ERC7943NotAllowedTransfer-address-address-uint256-uint256-) -- [ERC7943InsufficientUnfrozenBalance(user, tokenId, amount, unfrozen)](#IERC7943-ERC7943InsufficientUnfrozenBalance-address-uint256-uint256-uint256-) -#### ERC20Restricted [!toc] -- [ERC20UserRestricted(./account)](#ERC20Restricted-ERC20UserRestricted-address-) -#### ERC20Freezable [!toc] -- [ERC20InsufficientUnfrozenBalance(user, needed, available)](#ERC20Freezable-ERC20InsufficientUnfrozenBalance-address-uint256-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC7943Fungible + +- [ERC7943CannotTransact(account)](#IERC7943Fungible-ERC7943CannotTransact-address-) +- [ERC7943CannotTransfer(from, to, amount)](#IERC7943Fungible-ERC7943CannotTransfer-address-address-uint256-) +- [ERC7943InsufficientUnfrozenBalance(account, amount, unfrozen)](#IERC7943Fungible-ERC7943InsufficientUnfrozenBalance-address-uint256-uint256-) + +
+
+ERC20Restricted + +- [ERC20UserRestricted(account)](#ERC20Restricted-ERC20UserRestricted-address-) + +
+
+ERC20Freezable + +- [ERC20InsufficientUnfrozenBalance(account, needed, available)](#ERC20Freezable-ERC20InsufficientUnfrozenBalance-address-uint256-uint256-) + +
+
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
- +
-

isUserAllowed(address user) โ†’ bool

+

canTransact(address account) โ†’ bool

public

-# +#
@@ -1580,8 +1620,8 @@ Default implementation only disallows explicitly BLOCKED accounts (i.e. a blockl To convert into an allowlist, override as: ```solidity -function isUserAllowed(address account) public view virtual override returns (bool) { - return getRestriction(./account) == Restriction.ALLOWED; +function canTransact(address account) public view virtual override returns (bool) { + return getRestriction(account) == Restriction.ALLOWED; } ``` @@ -1610,76 +1650,80 @@ This function call must use less than 30 000 gas.
- +
-

isTransferAllowed(address from, address to, uint256, uint256 amount) โ†’ bool

+

canTransfer(address from, address to, uint256 amount) โ†’ bool

external

-# +#
-See [`IERC7943.isTransferAllowed`](./interfaces#IERC7943-isTransferAllowed-address-address-uint256-uint256-). +See [`IERC7943Fungible.canTransfer`](/community-contracts/api/interfaces#IERC7943Fungible-canTransfer-address-address-uint256-). -CAUTION: This function is only meant for external use. Overriding it will not apply the new checks to + +This function is only meant for external use. Overriding it will not apply the new checks to the internal [`ERC20Allowlist._update`](#ERC20Allowlist-_update-address-address-uint256-) function. Consider overriding [`ERC20Allowlist._update`](#ERC20Allowlist-_update-address-address-uint256-) accordingly to keep both functions in sync. +
- +
-

getFrozen(address user, uint256) โ†’ uint256 amount

+

getFrozenTokens(address account) โ†’ uint256 amount

public

-# +#
+It could return an amount higher than the account's balance. +
- +
-

setFrozen(address user, uint256, uint256 amount)

+

setFrozenTokens(address account, uint256 amount) โ†’ bool result

public

-# +#
-See [`IERC7943.setFrozen`](./interfaces#IERC7943-setFrozen-address-uint256-uint256-). +See [`IERC7943Fungible.setFrozenTokens`](/community-contracts/api/interfaces#IERC7943Fungible-setFrozenTokens-address-uint256-). Always returns true if successful. Reverts otherwise. -The `amount` is capped to the balance of the `user` to ensure the [`IERC7943.Frozen`](./interfaces#IERC7943-Frozen-address-uint256-uint256-) event +The `amount` is capped to the balance of the `account` to ensure the [`IERC7943Fungible.Frozen`](/community-contracts/api/interfaces#IERC7943Fungible-Frozen-address-uint256-) event emits values that consistently reflect the actual amount of tokens that are frozen.
- +
-

forceTransfer(address from, address to, uint256, uint256 amount)

+

forcedTransfer(address from, address to, uint256 amount) โ†’ bool result

public

-# +#
-See [`IERC7943.forceTransfer`](./interfaces#IERC7943-forceTransfer-address-address-uint256-uint256-). +See [`IERC7943Fungible.forcedTransfer`](/community-contracts/api/interfaces#IERC7943Fungible-forcedTransfer-address-address-uint256-). Always returns true if successful. Reverts otherwise. Bypasses the [`ERC20Restricted`](#ERC20Restricted) restrictions for the `from` address and adjusts the frozen balance to the new balance after the transfer. @@ -1710,7 +1754,7 @@ Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding this function. -Emits a [`ERC7786OpenBridge.UnsupportedNativeTransfer`](./crosschain#ERC7786OpenBridge-UnsupportedNativeTransfer--) event. +Emits a `Transfer` event.
@@ -1742,7 +1786,7 @@ function _checkEnforcer(address from, address to, uint256 amount) internal view
-

_checkFreezer(address user, uint256 amount)

+

_checkFreezer(address account, uint256 amount)

internal

# @@ -1755,7 +1799,7 @@ Internal function to check if the `freezer` is allowed to freeze the `amount` of Example usage with `AccessControl-onlyRole`: ```solidity -function _checkFreezer(address user, uint256 amount) internal view override onlyRole(FREEZER_ROLE) {} +function _checkFreezer(address account, uint256 amount) internal view override onlyRole(FREEZER_ROLE) {} ```
@@ -1765,16 +1809,16 @@ function _checkFreezer(address user, uint256 amount) internal view override only
-## `ERC4626Fees` +## `ERC4626Fees` - +
```solidity -import "@openzeppelin/community-contracts/token/ERC20/extensions/ERC4626Fees.sol"; +import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC4626Fees.sol"; ``` ERC-4626 vault with entry/exit fees expressed in [basis point (bp)](https://en.wikipedia.org/wiki/Basis_point). @@ -1792,7 +1836,9 @@ ERC-4626 vault with entry/exit fees expressed in [basis point (bp)](https://en.w - [_exitFeeBasisPoints()](#ERC4626Fees-_exitFeeBasisPoints--) - [_entryFeeRecipient()](#ERC4626Fees-_entryFeeRecipient--) - [_exitFeeRecipient()](#ERC4626Fees-_exitFeeRecipient--) -#### ERC4626 [!toc] +
+ERC4626 + - [decimals()](#ERC4626-decimals--) - [asset()](#ERC4626-asset--) - [totalAssets()](#ERC4626-totalAssets--) @@ -1808,65 +1854,77 @@ ERC-4626 vault with entry/exit fees expressed in [basis point (bp)](https://en.w - [redeem(shares, receiver, owner)](#ERC4626-redeem-uint256-address-address-) - [_convertToShares(assets, rounding)](#ERC4626-_convertToShares-uint256-enum-Math-Rounding-) - [_convertToAssets(shares, rounding)](#ERC4626-_convertToAssets-uint256-enum-Math-Rounding-) +- [_transferIn(from, assets)](#ERC4626-_transferIn-address-uint256-) +- [_transferOut(to, assets)](#ERC4626-_transferOut-address-uint256-) - [_decimalsOffset()](#ERC4626-_decimalsOffset--) -#### IERC4626 [!toc] -#### ERC20 [!toc] + +
+
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [totalSupply()](#ERC20-totalSupply--) -- [balanceOf(./account)](#ERC20-balanceOf-address-) +- [balanceOf(account)](#ERC20-balanceOf-address-) - [transfer(to, value)](#ERC20-transfer-address-uint256-) - [allowance(owner, spender)](#ERC20-allowance-address-address-) - [approve(spender, value)](#ERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) - [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) - [_update(from, to, value)](#ERC20-_update-address-address-uint256-) -- [_mint(./account, value)](#ERC20-_mint-address-uint256-) -- [_burn(./account, value)](#ERC20-_burn-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### ERC4626 [!toc] -#### IERC4626 [!toc] +
+IERC4626 + - [Deposit(sender, owner, assets, shares)](#IERC4626-Deposit-address-address-uint256-uint256-) - [Withdraw(sender, receiver, owner, assets, shares)](#IERC4626-Withdraw-address-address-address-uint256-uint256-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
+
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-#### ERC4626 [!toc] +
+ERC4626 + - [ERC4626ExceededMaxDeposit(receiver, assets, max)](#ERC4626-ERC4626ExceededMaxDeposit-address-uint256-uint256-) - [ERC4626ExceededMaxMint(receiver, shares, max)](#ERC4626-ERC4626ExceededMaxMint-address-uint256-uint256-) - [ERC4626ExceededMaxWithdraw(owner, assets, max)](#ERC4626-ERC4626ExceededMaxWithdraw-address-uint256-uint256-) - [ERC4626ExceededMaxRedeem(owner, shares, max)](#ERC4626-ERC4626ExceededMaxRedeem-address-uint256-uint256-) -#### IERC4626 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] + +
+
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -2036,16 +2094,16 @@ Send exit fee to [`ERC4626Fees._exitFeeRecipient`](#ERC4626Fees-_exitFeeRecipien
-## `OnTokenTransferAdapter` +## `OnTokenTransferAdapter` - +
```solidity -import "@openzeppelin/community-contracts/token/OnTokenTransferAdapter.sol"; +import "@openzeppelin/community-contracts/contracts/token/OnTokenTransferAdapter.sol"; ``` This contract exposes the 667 `onTokenTransfer` hook on top of `IERC1363Receiver-onTransferReceived`. @@ -2057,8 +2115,12 @@ Chainlink's Link, that implement the 667 interface for transferAndCall.

Functions

- [onTokenTransfer(from, amount, data)](#OnTokenTransferAdapter-onTokenTransfer-address-uint256-bytes-) -#### IERC1363Receiver [!toc] +
+IERC1363Receiver + - [onTransferReceived(operator, from, value, data)](#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) + +
@@ -2076,3 +2138,4 @@ Chainlink's Link, that implement the 667 interface for transferAndCall. + diff --git a/content/community-contracts/api/utils.mdx b/content/community-contracts/api/utils.mdx index 0047856d..4897ad49 100644 --- a/content/community-contracts/api/utils.mdx +++ b/content/community-contracts/api/utils.mdx @@ -22,16 +22,16 @@ Miscellaneous contracts and libraries containing utility functions you can use t
-## `Masks` +## `Masks` - +
```solidity -import "@openzeppelin/community-contracts/utils/Masks.sol"; +import "@openzeppelin/community-contracts/contracts/utils/Masks.sol"; ``` Library for handling bit masks @@ -208,16 +208,16 @@ Returns the symmetric difference (โˆ†) of two masks, also known as disjunctive u
-## `EnumerableMapExtended` +## `EnumerableMapExtended` - +
```solidity -import "@openzeppelin/community-contracts/utils/structs/EnumerableMapExtended.sol"; +import "@openzeppelin/community-contracts/contracts/utils/structs/EnumerableMapExtended.sol"; ``` Library for managing an enumerable variant of Solidity's @@ -246,17 +246,14 @@ The following map types are supported: - `bytes -> uint256` (`BytesToUintMap`) - `string -> string` (`StringToStringMap`) - -Trying to delete such a structure from storage will likely result in data corruption, rendering the structure +[WARNING] +#### Trying to delete such a structure from storage will likely result in data corruption, rendering the structure unusable. See [ethereum/solidity#11843](https://github.com/ethereum/solidity/pull/11843) for more info. In order to clean an EnumerableMap, you can either remove all elements one by one or create a fresh instance using an array of EnumerableMap. - - -Extensions of openzeppelin/contracts/utils/struct/EnumerableMap.sol. - +#### NOTE: Extensions of openzeppelin/contracts/utils/struct/EnumerableMap.sol.

Functions

@@ -744,16 +741,16 @@ Query for a nonexistent map key.
-## `EnumerableSetExtended` +## `EnumerableSetExtended` - +
```solidity -import "@openzeppelin/community-contracts/utils/structs/EnumerableSetExtended.sol"; +import "@openzeppelin/community-contracts/contracts/utils/structs/EnumerableSetExtended.sol"; ``` Library for managing @@ -780,17 +777,14 @@ contract Example { Sets of type `string` (`StringSet`), `bytes` (`BytesSet`) and `bytes32[2]` (`Bytes32x2Set`) are supported. - -Trying to delete such a structure from storage will likely result in data corruption, rendering the structure +[WARNING] +#### Trying to delete such a structure from storage will likely result in data corruption, rendering the structure unusable. See [ethereum/solidity#11843](https://github.com/ethereum/solidity/pull/11843) for more info. In order to clean an EnumerableSet, you can either remove all elements one by one or create a fresh instance using an array of EnumerableSet. - - -This is an extension of openzeppelin/contracts/utils/struct/EnumerableSet.sol. - +#### NOTE: This is an extension of openzeppelin/contracts/utils/struct/EnumerableSet.sol.

Functions

@@ -973,3 +967,4 @@ uncallable if the set grows to a point where copying to memory consumes too much
+ diff --git a/content/community-contracts/api/utils/cryptography.mdx b/content/community-contracts/api/utils/cryptography.mdx index 1e46a40f..5847fc69 100644 --- a/content/community-contracts/api/utils/cryptography.mdx +++ b/content/community-contracts/api/utils/cryptography.mdx @@ -6,46 +6,38 @@ description: "Smart contract cryptography utilities and implementations" A collection of contracts and libraries that implement various signature validation schemes and cryptographic primitives. These utilities enable secure authentication, multisignature operations, and advanced cryptographic operations in smart contracts. * [`ZKEmailUtils`](#ZKEmailUtils): Library for ZKEmail signature validation utilities, enabling email-based authentication through zero-knowledge proofs. -* [`WebAuthn`](#WebAuthn): Library for verifying WebAuthn Authentication Assertions. * [`DKIMRegistry`](#DKIMRegistry): Implementation of [ERC-7969](https://eips.ethereum.org/EIPS/eip-7969) to enable onchain verification of DomainKeys Identified Mail (DKIM) signatures. * [`SignerZKEmail`](#SignerZKEmail): Implementation of an [AbstractSigner](https://docs.openzeppelin.com/contracts/5.x/api/utils/cryptography#AbstractSigner) that enables email-based authentication through zero-knowledge proofs. -* [`SignerWebAuthn`](#SignerWebAuthn): Implementation of [SignerP256](https://docs.openzeppelin.com/contracts/5.x/api/utils/cryptography#SignerP256) that supports WebAuthn authentication assertions. -* [`ERC7913ZKEmailVerifier`](#ERC7913ZKEmailVerifier), [`ERC7913WebAuthnVerifier`](#ERC7913WebAuthnVerifier): Ready to use ERC-7913 signature verifiers for ZKEmail and WebAuthn. +* [`ERC7913ZKEmailVerifier`](#ERC7913ZKEmailVerifier): Ready to use ERC-7913 signature verifiers for ZKEmail. ## Utils [`ZKEmailUtils`](#ZKEmailUtils) -[`WebAuthn`](#WebAuthn) - [`DKIMRegistry`](#DKIMRegistry) ## Abstract Signers [`SignerZKEmail`](#SignerZKEmail) -[`SignerWebAuthn`](#SignerWebAuthn) - ## Verifiers [`ERC7913ZKEmailVerifier`](#ERC7913ZKEmailVerifier) -[`ERC7913WebAuthnVerifier`](#ERC7913WebAuthnVerifier) -
-## `DKIMRegistry` +## `DKIMRegistry` - +
```solidity -import "@openzeppelin/community-contracts/utils/cryptography/DKIMRegistry.sol"; +import "@openzeppelin/community-contracts/contracts/utils/cryptography/DKIMRegistry.sol"; ``` Implementation of the [ERC-7969](https://eips.ethereum.org/EIPS/eip-7969) interface for registering @@ -85,16 +77,19 @@ contract MyDKIMRegistry is DKIMRegistry, Ownable { - [_setKeyHash(domainHash, keyHash)](#DKIMRegistry-_setKeyHash-bytes32-bytes32-) - [_setKeyHashes(domainHash, keyHashes)](#DKIMRegistry-_setKeyHashes-bytes32-bytes32---) - [_revokeKeyHash(domainHash, keyHash)](#DKIMRegistry-_revokeKeyHash-bytes32-bytes32-) -#### IDKIMRegistry [!toc]

Events

-#### IDKIMRegistry [!toc] +
+IDKIMRegistry + - [KeyHashRegistered(domainHash, keyHash)](#IDKIMRegistry-KeyHashRegistered-bytes32-bytes32-) - [KeyHashRevoked(domainHash)](#IDKIMRegistry-KeyHashRevoked-bytes32-) + +
@@ -129,7 +124,7 @@ Returns whether a DKIM key hash is valid for a given domain. Sets a DKIM key hash as valid for a domain. Internal version without access control. -Emits a [`IDKIMRegistry.KeyHashRegistered`](../interfaces#IDKIMRegistry-KeyHashRegistered-bytes32-bytes32-) event. +Emits a [`IDKIMRegistry.KeyHashRegistered`](/community-contracts/api/interfaces#IDKIMRegistry-KeyHashRegistered-bytes32-bytes32-) event. This function does not validate that keyHash is non-zero. Consider adding @@ -154,7 +149,7 @@ validation in derived contracts if needed. Sets multiple DKIM key hashes as valid for a domain in a single transaction. Internal version without access control. -Emits a [`IDKIMRegistry.KeyHashRegistered`](../interfaces#IDKIMRegistry-KeyHashRegistered-bytes32-bytes32-) event for each key hash. +Emits a [`IDKIMRegistry.KeyHashRegistered`](/community-contracts/api/interfaces#IDKIMRegistry-KeyHashRegistered-bytes32-bytes32-) event for each key hash. This function does not validate that the keyHashes array is non-empty. @@ -179,128 +174,7 @@ Consider adding validation in derived contracts if needed. Revokes a DKIM key hash for a domain, making it invalid. Internal version without access control. -Emits a [`IDKIMRegistry.KeyHashRevoked`](../interfaces#IDKIMRegistry-KeyHashRevoked-bytes32-) event. - - - - - - -
- -## `WebAuthn` - - - - - -
- -```solidity -import "@openzeppelin/community-contracts/utils/cryptography/WebAuthn.sol"; -``` - -Library for verifying WebAuthn Authentication Assertions. - -WebAuthn enables strong authentication for smart contracts using -[P256](https://docs.openzeppelin.com/contracts/5.x/api/utils#P256) -as an alternative to traditional secp256k1 ECDSA signatures. This library verifies -signatures generated during WebAuthn authentication ceremonies as specified in the -[WebAuthn Level 2 standard](https://www.w3.org/TR/webauthn-2/). - -For blockchain use cases, the following WebAuthn validations are intentionally omitted: - -* Origin validation: Origin verification in `clientDataJSON` is omitted as blockchain - contexts rely on authenticator and dapp frontend enforcement. Standard authenticators - implement proper origin validation. -* RP ID hash validation: Verification of `rpIdHash` in authenticatorData against expected - RP ID hash is omitted. This is typically handled by platform-level security measures. - Including an expiry timestamp in signed data is recommended for enhanced security. -* Signature counter: Verification of signature counter increments is omitted. While - useful for detecting credential cloning, on-chain operations typically include nonce - protection, making this check redundant. -* Extension outputs: Extension output value verification is omitted as these are not - essential for core authentication security in blockchain applications. -* Attestation: Attestation object verification is omitted as this implementation - focuses on authentication (`webauthn.get`) rather than registration ceremonies. - -Inspired by: - -* [daimo-eth implementation](https://github.com/daimo-eth/p256-verifier/blob/master/src/WebAuthn.sol) -* [base implementation](https://github.com/base/webauthn-sol/blob/main/src/WebAuthn.sol) - -
-

Functions

-
-- [verify(challenge, auth, qx, qy)](#WebAuthn-verify-bytes-struct-WebAuthn-WebAuthnAuth-bytes32-bytes32-) -- [verify(challenge, auth, qx, qy, requireUV)](#WebAuthn-verify-bytes-struct-WebAuthn-WebAuthnAuth-bytes32-bytes32-bool-) -- [tryDecodeAuth(input)](#WebAuthn-tryDecodeAuth-bytes-) -
-
- - - -
-
-

verify(bytes challenge, struct WebAuthn.WebAuthnAuth auth, bytes32 qx, bytes32 qy) โ†’ bool

-
-

internal

-# -
-
-
- -Performs standard verification of a WebAuthn Authentication Assertion. - -
-
- - - -
-
-

verify(bytes challenge, struct WebAuthn.WebAuthnAuth auth, bytes32 qx, bytes32 qy, bool requireUV) โ†’ bool

-
-

internal

-# -
-
-
- -Performs verification of a WebAuthn Authentication Assertion. This variants allow the caller to select -whether of not to require the UV flag (step 17). - -Verifies: - -1. Type is "webauthn.get" (see [`WebAuthn._validateExpectedTypeHash`](#WebAuthn-_validateExpectedTypeHash-string-uint256-)) -2. Challenge matches the expected value (see [`WebAuthn._validateChallenge`](#WebAuthn-_validateChallenge-string-uint256-bytes-)) -3. Cryptographic signature is valid for the given public key -4. confirming physical user presence during authentication -5. (if `requireUV` is true) confirming stronger user authentication (biometrics/PIN) -6. Backup Eligibility (`BE`) and Backup State (BS) bits relationship is valid - -
-
- - - -
-
-

tryDecodeAuth(bytes input) โ†’ bool success, struct WebAuthn.WebAuthnAuth auth

-
-

internal

-# -
-
-
- -Verifies that calldata bytes (`input`) represents a valid `WebAuthnAuth` object. If encoding is valid, -returns true and the calldata view at the object. Otherwise, returns false and an invalid calldata object. - - -The returned `auth` object should not be accessed if `success` is false. Trying to access the data may -cause revert/panic. - +Emits a [`IDKIMRegistry.KeyHashRevoked`](/community-contracts/api/interfaces#IDKIMRegistry-KeyHashRevoked-bytes32-) event.
@@ -309,16 +183,16 @@ cause revert/panic.
-## `ZKEmailUtils` +## `ZKEmailUtils` - +
```solidity -import "@openzeppelin/community-contracts/utils/cryptography/ZKEmailUtils.sol"; +import "@openzeppelin/community-contracts/contracts/utils/cryptography/ZKEmailUtils.sol"; ``` Library for [ZKEmail](https://docs.zk.email) Groth16 proof validation utilities. @@ -359,7 +233,7 @@ mechanism to ensure the email was actually sent and received without revealing i
-Variant of [`ZKEmailUtils.isValidZKEmail`](#ZKEmailUtils-isValidZKEmail-struct-EmailProof-contract-IDKIMRegistry-contract-IGroth16Verifier-string---bytes---enum-ZKEmailUtils-Case-) that validates the `["signHash", "../access#AccessManagerLight-ADMIN_ROLE-uint8"]` command template. +Variant of [`ZKEmailUtils.isValidZKEmail`](#ZKEmailUtils-isValidZKEmail-struct-EmailProof-contract-IDKIMRegistry-contract-IGroth16Verifier-string---bytes---enum-ZKEmailUtils-Case-) that validates the `["signHash", "`uint`"]` command template.
@@ -404,7 +278,7 @@ Attempts to validate the command for all possible string [`ZKEmailUtils.Case`](# Variant of [`ZKEmailUtils.isValidZKEmail`](#ZKEmailUtils-isValidZKEmail-struct-EmailProof-contract-IDKIMRegistry-contract-IGroth16Verifier-string---bytes---enum-ZKEmailUtils-Case-) that validates a template with a specific string [`ZKEmailUtils.Case`](#ZKEmailUtils-Case). -Useful for templates with Ethereum address matchers (i.e. ``ethAddr``), which are case-sensitive (e.g., `["someCommand", "../access#AccessManagerLight-_groups-mapping-address----Masks-Mask-"]`). +Useful for templates with Ethereum address matchers (i.e. ``ethAddr``), which are case-sensitive (e.g., `["someCommand", "`address`"]`). @@ -452,100 +326,20 @@ into a uint256 array in the order expected by the verifier circuit. - - -
- -## `SignerWebAuthn` - - - - - -
- -```solidity -import "@openzeppelin/community-contracts/utils/cryptography/signers/SignerWebAuthn.sol"; -``` - -Implementation of `SignerP256` that supports WebAuthn authentication assertions. - -This contract enables signature validation using WebAuthn authentication assertions, -leveraging the P256 public key stored in the contract. It allows for both WebAuthn -and raw P256 signature validation, providing compatibility with both signature types. - -The signature is expected to be an abi-encoded [`WebAuthn.WebAuthnAuth`](#WebAuthn-WebAuthnAuth) struct. - -Example usage: - -```solidity -contract MyAccountWebAuthn is Account, SignerWebAuthn, Initializable { - function initialize(bytes32 qx, bytes32 qy) public initializer { - _setSigner(qx, qy); - } -} -``` - - -Failing to call [`ERC7579Signature._setSigner`](../account#ERC7579Signature-_setSigner-address-bytes-) either during construction (if used standalone) -or during initialization (if used as a clone) may leave the signer either front-runnable or unusable. - - -
-

Functions

-
-- [_rawSignatureValidation(hash, signature)](#SignerWebAuthn-_rawSignatureValidation-bytes32-bytes-) -#### SignerP256 [!toc] -- [_setSigner(qx, qy)](#SignerP256-_setSigner-bytes32-bytes32-) -- [signer()](#SignerP256-signer--) -#### AbstractSigner [!toc] -
-
- -
-

Errors

-
-#### SignerP256 [!toc] -- [SignerP256InvalidPublicKey(qx, qy)](#SignerP256-SignerP256InvalidPublicKey-bytes32-bytes32-) -#### AbstractSigner [!toc] -
-
- - - -
-
-

_rawSignatureValidation(bytes32 hash, bytes signature) โ†’ bool

-
-

internal

-# -
-
-
- -Validates a raw signature using the WebAuthn authentication assertion. - -In case the signature can't be validated, it falls back to the -`SignerP256-_rawSignatureValidation` method for raw P256 signature validation by passing -the raw `r` and `s` values from the signature. - -
-
-
-## `SignerZKEmail` +## `SignerZKEmail` - +
```solidity -import "@openzeppelin/community-contracts/utils/cryptography/signers/SignerZKEmail.sol"; +import "@openzeppelin/community-contracts/contracts/utils/cryptography/signers/SignerZKEmail.sol"; ``` Implementation of `AbstractSigner` using [ZKEmail](https://docs.zk.email) signatures. @@ -596,7 +390,6 @@ leave the signer either front-runnable or unusable. - [_setDKIMRegistry(registry_)](#SignerZKEmail-_setDKIMRegistry-contract-IDKIMRegistry-) - [_setVerifier(verifier_)](#SignerZKEmail-_setVerifier-contract-IGroth16Verifier-) - [_rawSignatureValidation(hash, signature)](#SignerZKEmail-_rawSignatureValidation-bytes32-bytes-) -#### AbstractSigner [!toc] @@ -604,7 +397,6 @@ leave the signer either front-runnable or unusable.

Errors

- [InvalidEmailProof(err)](#SignerZKEmail-InvalidEmailProof-enum-ZKEmailUtils-EmailProofError-) -#### AbstractSigner [!toc]
@@ -763,78 +555,20 @@ Proof verification error. - - -
- -## `ERC7913WebAuthnVerifier` - - - - - -
- -```solidity -import "@openzeppelin/community-contracts/utils/cryptography/verifiers/ERC7913WebAuthnVerifier.sol"; -``` - -ERC-7913 signature verifier that supports WebAuthn authentication assertions. - -This verifier enables the validation of WebAuthn signatures using P256 public keys. -The key is expected to be a 64-byte concatenation of the P256 public key coordinates (qx || qy). -The signature is expected to be an abi-encoded [`WebAuthn.WebAuthnAuth`](#WebAuthn-WebAuthnAuth) struct. - -Uses `WebAuthn-verifyMinimal` for signature verification, which performs the essential -WebAuthn checks: type validation, challenge matching, and cryptographic signature verification. - - -Wallets that may require default P256 validation may install a P256 verifier separately. - - -
-

Functions

-
-- [verify(key, hash, signature)](#ERC7913WebAuthnVerifier-verify-bytes-bytes32-bytes-) -#### IERC7913SignatureVerifier [!toc] -
-
- - - -
-
-

verify(bytes key, bytes32 hash, bytes signature) โ†’ bytes4

-
-

public

-# -
-
-
- -Verifies `signature` as a valid signature of `hash` by `key`. - -MUST return the bytes4 magic value IERC7913SignatureVerifier.verify.selector if the signature is valid. -SHOULD return 0xffffffff or revert if the signature is not valid. -SHOULD return 0xffffffff or revert if the key is empty - -
-
-
-## `ERC7913ZKEmailVerifier` +## `ERC7913ZKEmailVerifier` - +
```solidity -import "@openzeppelin/community-contracts/utils/cryptography/verifiers/ERC7913ZKEmailVerifier.sol"; +import "@openzeppelin/community-contracts/contracts/utils/cryptography/verifiers/ERC7913ZKEmailVerifier.sol"; ``` ERC-7913 signature verifier that supports ZKEmail accounts. @@ -867,7 +601,6 @@ Example of overriding _decodeKey to enforce a specific verifier, registry:
- [verify(key, hash, signature)](#ERC7913ZKEmailVerifier-verify-bytes-bytes32-bytes-) - [_decodeKey(key)](#ERC7913ZKEmailVerifier-_decodeKey-bytes-) -#### IERC7913SignatureVerifier [!toc]
@@ -893,7 +626,7 @@ The key format is ABI-encoded (IDKIMRegistry, bytes32, IGroth16Verifier) where: See [`ERC7913ZKEmailVerifier._decodeKey`](#ERC7913ZKEmailVerifier-_decodeKey-bytes-) for the key encoding format. -The signature is an ABI-encoded [`ZKEmailUtils.EmailProofError`](#ZKEmailUtils-EmailProofError) struct containing +The signature is an ABI-encoded `EmailProof` struct containing the proof details. Signature encoding: @@ -934,3 +667,4 @@ bytes memory key = abi.encode(registry, accountSalt, verifier); + diff --git a/content/confidential-contracts/api/finance.mdx b/content/confidential-contracts/api/finance.mdx index 8d0ec00b..8653cfa3 100644 --- a/content/confidential-contracts/api/finance.mdx +++ b/content/confidential-contracts/api/finance.mdx @@ -7,6 +7,7 @@ This directory includes primitives for on-chain confidential financial systems: * [`VestingWalletConfidential`](#VestingWalletConfidential): Handles the vesting of confidential tokens for a given beneficiary. Custody of multiple tokens can be given to this contract, which will release the token to the beneficiary following a given, customizable, vesting schedule. * [`VestingWalletCliffConfidential`](#VestingWalletCliffConfidential): Variant of [`VestingWalletConfidential`](#VestingWalletConfidential) which adds a cliff period to the vesting schedule. +* [`BatcherConfidential`](#BatcherConfidential): A batching primitive that enables routing between two [`ERC7984ERC20Wrapper`](/confidential-contracts/api/token#ERC7984ERC20Wrapper) contracts via a non-confidential route. For convenience, this directory also includes: @@ -16,21 +17,773 @@ For convenience, this directory also includes: [`VestingWalletConfidential`](#VestingWalletConfidential) [`VestingWalletCliffConfidential`](#VestingWalletCliffConfidential) [`VestingWalletConfidentialFactory`](#VestingWalletConfidentialFactory) +[`BatcherConfidential`](#BatcherConfidential) + + + +
+ +## `BatcherConfidential` + + + + + +
+ +```solidity +import "@openzeppelin/confidential-contracts/contracts/finance/BatcherConfidential.sol"; +``` + +`BatcherConfidential` is a batching primitive that enables routing between two [`ERC7984ERC20Wrapper`](/confidential-contracts/api/token#ERC7984ERC20Wrapper) contracts +via a non-confidential route. Users deposit [`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) into the batcher and receive [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) in exchange. Deposits are +made by using `ERC7984` transfer and call functions such as [`ERC7984.confidentialTransferAndCall`](/confidential-contracts/api/token#ERC7984-confidentialTransferAndCall-address-euint64-bytes-). + +Developers must implement the virtual function [`BatcherConfidential._executeRoute`](#BatcherConfidential-_executeRoute-uint256-uint256-) to perform the batch's route. This function is called +once the batch deposits are unwrapped into the underlying tokens. The function should swap the underlying [`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) for +underlying [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--). If an issue is encountered, the function should return `ExecuteOutcome.Cancel` to cancel the batch. + +Developers must also implement the virtual function [`BatcherConfidential.routeDescription`](#BatcherConfidential-routeDescription--) to provide a human readable description of the batch's route. + +Claim outputs are rounded down. This may result in small deposits being rounded down to 0 if the exchange rate is less than 1:1. +[`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) dust from rounding down will accumulate in the batcher over time. + + +The batcher does not support [`ERC7984ERC20Wrapper`](/confidential-contracts/api/token#ERC7984ERC20Wrapper) contracts prior to v0.4.0. + + + +The batcher could be used to maintain confidentiality of deposits--by default there are no confidentiality guarantees. +If desired, developers should consider restricting certain functions to increase confidentiality. + + + +The [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) and [`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) must be carefully inspected to ensure proper capacity is maintained. If [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) or +[`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) are filled--resulting in denial of service--batches could get bricked. The batcher would be unable to wrap +underlying tokens into [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--). Further, if [`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) is also filled, cancellation would also fail on rewrap. + + +
+

Functions

+
+- [constructor(fromToken_, toToken_)](#BatcherConfidential-constructor-contract-IERC7984ERC20Wrapper-contract-IERC7984ERC20Wrapper-) +- [claim(batchId, account)](#BatcherConfidential-claim-uint256-address-) +- [quit(batchId)](#BatcherConfidential-quit-uint256-) +- [dispatchBatch()](#BatcherConfidential-dispatchBatch--) +- [dispatchBatchCallback(batchId, unwrapAmountCleartext, decryptionProof)](#BatcherConfidential-dispatchBatchCallback-uint256-uint64-bytes-) +- [onConfidentialTransferReceived(, from, amount, )](#BatcherConfidential-onConfidentialTransferReceived-address-address-euint64-bytes-) +- [fromToken()](#BatcherConfidential-fromToken--) +- [toToken()](#BatcherConfidential-toToken--) +- [currentBatchId()](#BatcherConfidential-currentBatchId--) +- [unwrapRequestId(batchId)](#BatcherConfidential-unwrapRequestId-uint256-) +- [totalDeposits(batchId)](#BatcherConfidential-totalDeposits-uint256-) +- [deposits(batchId, account)](#BatcherConfidential-deposits-uint256-address-) +- [exchangeRate(batchId)](#BatcherConfidential-exchangeRate-uint256-) +- [exchangeRateDecimals()](#BatcherConfidential-exchangeRateDecimals--) +- [routeDescription()](#BatcherConfidential-routeDescription--) +- [batchState(batchId)](#BatcherConfidential-batchState-uint256-) +- [_claim(batchId, account)](#BatcherConfidential-_claim-uint256-address-) +- [_join(to, amount)](#BatcherConfidential-_join-address-euint64-) +- [_executeRoute(batchId, amount)](#BatcherConfidential-_executeRoute-uint256-uint256-) +- [_validateStateBitmap(batchId, allowedStates)](#BatcherConfidential-_validateStateBitmap-uint256-bytes32-) +- [_getAndIncreaseBatchId()](#BatcherConfidential-_getAndIncreaseBatchId--) +- [_encodeStateBitmap(batchState_)](#BatcherConfidential-_encodeStateBitmap-enum-BatcherConfidential-BatchState-) +
+ReentrancyGuardTransient + +- [_reentrancyGuardEntered()](#ReentrancyGuardTransient-_reentrancyGuardEntered--) +- [_reentrancyGuardStorageSlot()](#ReentrancyGuardTransient-_reentrancyGuardStorageSlot--) + +
+
+
+ +
+

Events

+
+- [BatchDispatched(batchId)](#BatcherConfidential-BatchDispatched-uint256-) +- [BatchCanceled(batchId)](#BatcherConfidential-BatchCanceled-uint256-) +- [BatchFinalized(batchId, exchangeRate)](#BatcherConfidential-BatchFinalized-uint256-uint64-) +- [Joined(batchId, account, amount)](#BatcherConfidential-Joined-uint256-address-euint64-) +- [Claimed(batchId, account, amount)](#BatcherConfidential-Claimed-uint256-address-euint64-) +- [Quit(batchId, account, amount)](#BatcherConfidential-Quit-uint256-address-euint64-) +
+
+ +
+

Errors

+
+- [BatchNonexistent(batchId)](#BatcherConfidential-BatchNonexistent-uint256-) +- [ZeroDeposits(batchId, account)](#BatcherConfidential-ZeroDeposits-uint256-address-) +- [BatchUnexpectedState(batchId, current, expectedStates)](#BatcherConfidential-BatchUnexpectedState-uint256-enum-BatcherConfidential-BatchState-bytes32-) +- [InvalidExchangeRate(batchId, totalDeposits, exchangeRate)](#BatcherConfidential-InvalidExchangeRate-uint256-uint256-uint64-) +- [Unauthorized()](#BatcherConfidential-Unauthorized--) +- [InvalidWrapperToken(token)](#BatcherConfidential-InvalidWrapperToken-address-) +
+ReentrancyGuardTransient + +- [ReentrancyGuardReentrantCall()](#ReentrancyGuardTransient-ReentrancyGuardReentrantCall--) + +
+
+
+ + + +
+
+

constructor(contract IERC7984ERC20Wrapper fromToken_, contract IERC7984ERC20Wrapper toToken_)

+
+

internal

+# +
+
+
+ +
+
+ + + +
+
+

claim(uint256 batchId, address account) โ†’ euint64

+
+

public

+# +
+
+
+ +Claim the `toToken` corresponding to `account`'s deposit in batch with id `batchId`. + + +This function is not gated and can be called by anyone. Claims could be frontrun. + + +
+
+ + + +
+
+

quit(uint256 batchId) โ†’ euint64

+
+

public

+# +
+
+
+ +Quit the batch with id `batchId`. Entire deposit is returned to the user. +This can only be called if the batch has not yet been dispatched or if the batch was canceled. + + +Developers should consider adding additional restrictions to this function +if maintaining confidentiality of deposits is critical to the application. + + + +[`BatcherConfidential.dispatchBatch`](#BatcherConfidential-dispatchBatch--) may fail if an incompatible version of [`ERC7984ERC20Wrapper`](/confidential-contracts/api/token#ERC7984ERC20Wrapper) is used. +This function must be unrestricted in cases where batch dispatching fails. + + +
+
+ + + +
+
+

dispatchBatch()

+
+

public

+# +
+
+
+ +Permissionless function to dispatch the current batch. Increments the [`BatcherConfidential.currentBatchId`](#BatcherConfidential-currentBatchId--). + + +Developers should consider adding additional restrictions to this function +if maintaining confidentiality of deposits is critical to the application. + + +
+
+ + + +
+
+

dispatchBatchCallback(uint256 batchId, uint64 unwrapAmountCleartext, bytes decryptionProof)

+
+

public

+# +
+
+
+ +Dispatch batch callback callable by anyone. This function finalizes the unwrap of [`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) +and calls [`BatcherConfidential._executeRoute`](#BatcherConfidential-_executeRoute-uint256-uint256-) to perform the batch's route. If `_executeRoute` returns `ExecuteOutcome.Partial`, +this function should be called again with the same `batchId`, `unwrapAmountCleartext`, and `decryptionProof`. + +
+
+ + + +
+
+

onConfidentialTransferReceived(address, address from, euint64 amount, bytes) โ†’ ebool

+
+

external

+# +
+
+
+ +See [`IERC7984Receiver.onConfidentialTransferReceived`](/confidential-contracts/api/interfaces#IERC7984Receiver-onConfidentialTransferReceived-address-address-euint64-bytes-). + +Deposit [`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) into the current batch. + + +See [`BatcherConfidential._claim`](#BatcherConfidential-_claim-uint256-address-) to understand how the [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) amount is calculated. Claim amounts are rounded down. Small +deposits may be rounded down to 0 if the exchange rate is less than 1:1. + + +
+
+ + + +
+
+

fromToken() โ†’ contract IERC7984ERC20Wrapper

+
+

public

+# +
+
+
+ +Batcher from token. Users deposit this token in exchange for [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--). + +
+
+ + + +
+
+

toToken() โ†’ contract IERC7984ERC20Wrapper

+
+

public

+# +
+
+
+ +Batcher to token. Users receive this token in exchange for their [`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) deposits. + +
+
+ + + +
+
+

currentBatchId() โ†’ uint256

+
+

public

+# +
+
+
+ +The ongoing batch id. New deposits join this batch. + +
+
+ + + +
+
+

unwrapRequestId(uint256 batchId) โ†’ bytes32

+
+

public

+# +
+
+
+ +The unwrap request id for a batch with id `batchId`. + +
+
+ + + +
+
+

totalDeposits(uint256 batchId) โ†’ euint64

+
+

public

+# +
+
+
+ +The total deposits made in batch with id `batchId`. + +
+
+ + + +
+
+

deposits(uint256 batchId, address account) โ†’ euint64

+
+

public

+# +
+
+
+ +The deposits made by `account` in batch with id `batchId`. + +
+
+ + + +
+
+

exchangeRate(uint256 batchId) โ†’ uint64

+
+

public

+# +
+
+
+ +The exchange rate set for batch with id `batchId`. + +
+
+ + + +
+
+

exchangeRateDecimals() โ†’ uint8

+
+

public

+# +
+
+
+ +The number of decimals of precision for the exchange rate. + +
+
+ + + +
+
+

routeDescription() โ†’ string

+
+

public

+# +
+
+
+ +Human readable description of what the batcher does. + +
+
+ + + +
+
+

batchState(uint256 batchId) โ†’ enum BatcherConfidential.BatchState

+
+

public

+# +
+
+
+ +Returns the current state of a batch. Reverts if the batch does not exist. + +
+
+ + + +
+
+

_claim(uint256 batchId, address account) โ†’ euint64

+
+

internal

+# +
+
+
+ +Claims `toToken` for `account`'s deposit in batch with id `batchId`. Tokens are always +sent to `account`, enabling third-party relayers to claim on behalf of depositors. + +
+
+ + + +
+
+

_join(address to, euint64 amount) โ†’ euint64

+
+

internal

+# +
+
+
+ +Joins a batch with amount `amount` on behalf of `to`. Does not do any transfers in. +Returns the amount joined with. + +
+
+ + + +
+
+

_executeRoute(uint256 batchId, uint256 amount) โ†’ enum BatcherConfidential.ExecuteOutcome

+
+

internal

+# +
+
+
+ +Function which is executed by [`BatcherConfidential.dispatchBatchCallback`](#BatcherConfidential-dispatchBatchCallback-uint256-uint64-bytes-) after validation and unwrap finalization. The parameter +`amount` is the plaintext amount of the `fromToken` which were unwrapped--to attain the underlying tokens received, +evaluate `amount * fromToken().rate()`. This function should swap the underlying [`BatcherConfidential.fromToken`](#BatcherConfidential-fromToken--) for underlying [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--). + +This function returns an [`BatcherConfidential.ExecuteOutcome`](#BatcherConfidential-ExecuteOutcome) enum indicating the new state of the batch. If the route execution is complete, +the balance of the underlying [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) is wrapped and the exchange rate is set. + + +[`BatcherConfidential.dispatchBatchCallback`](#BatcherConfidential-dispatchBatchCallback-uint256-uint64-bytes-) (and in turn [`BatcherConfidential._executeRoute`](#BatcherConfidential-_executeRoute-uint256-uint256-)) can be repeatedly called until the route execution is complete. +If a multi-step route is necessary, intermediate steps should return `ExecuteOutcome.Partial`. Intermediate steps *must* not +result in underlying [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) being transferred into the batcher. + + +[WARNING] +#### This function must eventually return `ExecuteOutcome.Complete` or `ExecuteOutcome.Cancel`. Failure to do so results +in user deposits being locked indefinitely. + +Additionally, the following must hold: + +- `swappedAmount >= ceil(unwrapAmountCleartext / 10 ** exchangeRateDecimals()) * toToken().rate()` (the exchange rate must not be 0) +- `swappedAmount \<= type(uint64).max * toToken().rate()` (the wrapped amount of [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) must fit in `uint64`) + +
+
+ + + +
+
+

_validateStateBitmap(uint256 batchId, bytes32 allowedStates) โ†’ enum BatcherConfidential.BatchState

+
+

internal

+# +
+
+
+ +Check that the current state of a batch matches the requirements described by the `allowedStates` bitmap. +This bitmap should be built using `_encodeStateBitmap`. + +If requirements are not met, reverts with a [`BatcherConfidential.BatchUnexpectedState`](#BatcherConfidential-BatchUnexpectedState-uint256-enum-BatcherConfidential-BatchState-bytes32-) error. + +
+
+ + + +
+
+

_getAndIncreaseBatchId() โ†’ uint256

+
+

internal

+# +
+
+
+ +Gets the current batch id and increments it. + +
+
+ + + +
+
+

_encodeStateBitmap(enum BatcherConfidential.BatchState batchState_) โ†’ bytes32

+
+

internal

+# +
+
+
+ +Encodes a `BatchState` into a `bytes32` representation where each bit enabled corresponds to +the underlying position in the `BatchState` enum. For example: + +0x000...1000 + ^--- Canceled + ^-- Finalized + ^- Dispatched + ^ Pending + +
+
+ + + +
+
+

BatchDispatched(uint256 indexed batchId)

+
+

event

+# +
+
+ +
+ +Emitted when a batch with id `batchId` is dispatched via [`BatcherConfidential.dispatchBatch`](#BatcherConfidential-dispatchBatch--). + +
+
+ + +
+
+

BatchCanceled(uint256 indexed batchId)

+
+

event

+# +
+
+ +
+ +Emitted when a batch with id `batchId` is canceled. + +
+
+ + +
+
+

BatchFinalized(uint256 indexed batchId, uint64 exchangeRate)

+
+

event

+# +
+
+ +
+ +Emitted when a batch with id `batchId` is finalized with an exchange rate of `exchangeRate`. + +
+
+ + +
+
+

Joined(uint256 indexed batchId, address indexed account, euint64 amount)

+
+

event

+# +
+
+ +
+ +Emitted when an `account` joins a batch with id `batchId` with a deposit of `amount`. + +
+
+ + +
+
+

Claimed(uint256 indexed batchId, address indexed account, euint64 amount)

+
+

event

+# +
+
+ +
+ +Emitted when an `account` claims their `amount` from batch with id `batchId`. + +
+
+ + +
+
+

Quit(uint256 indexed batchId, address indexed account, euint64 amount)

+
+

event

+# +
+
+ +
+ +Emitted when an `account` quits a batch with id `batchId`. + +
+
+ + + +
+
+

BatchNonexistent(uint256 batchId)

+
+

error

+# +
+
+
+ +The `batchId` does not exist. Batch IDs start at 1 and must be less than or equal to [`BatcherConfidential.currentBatchId`](#BatcherConfidential-currentBatchId--). + +
+
+ + + +
+
+

ZeroDeposits(uint256 batchId, address account)

+
+

error

+# +
+
+
+ +The `account` has a zero deposits in batch `batchId`. + +
+
+ + + +
+
+

BatchUnexpectedState(uint256 batchId, enum BatcherConfidential.BatchState current, bytes32 expectedStates)

+
+

error

+# +
+
+
+ +The batch `batchId` is in the state `current`, which is invalid for the operation. +The `expectedStates` is a bitmap encoding the expected/allowed states for the operation. + +See [`BatcherConfidential._encodeStateBitmap`](#BatcherConfidential-_encodeStateBitmap-enum-BatcherConfidential-BatchState-). + +
+
+ + + +
+
+

InvalidExchangeRate(uint256 batchId, uint256 totalDeposits, uint64 exchangeRate)

+
+

error

+# +
+
+
+ +Thrown when the given exchange rate is invalid. The exchange rate must be non-zero and the wrapped +amount of [`BatcherConfidential.toToken`](#BatcherConfidential-toToken--) must be less than or equal to `type(uint64).max`. + +
+
+ + + +
+
+

Unauthorized()

+
+

error

+# +
+
+
+ +The caller is not authorized to call this function. + +
+
+ + + +
+
+

InvalidWrapperToken(address token)

+
+

error

+# +
+
+
+ +The given `token` does not support `IERC7984ERC20Wrapper` via `ERC165`. + +
+
-## `ERC7821WithExecutor` +## `ERC7821WithExecutor` - +
```solidity -import "@openzeppelin/confidential-contracts/finance/ERC7821WithExecutor.sol"; +import "@openzeppelin/confidential-contracts/contracts/finance/ERC7821WithExecutor.sol"; ``` Extension of `ERC7821` that adds an [`ERC7821WithExecutor.executor`](#ERC7821WithExecutor-executor--) address that is able to execute arbitrary calls via `ERC7821.execute`. @@ -41,38 +794,54 @@ Extension of `ERC7821` that adds an [`ERC7821WithExecutor.executor`](#ERC7821Wit - [executor()](#ERC7821WithExecutor-executor--) - [__ERC7821WithExecutor_init(executor_)](#ERC7821WithExecutor-__ERC7821WithExecutor_init-address-) - [_erc7821AuthorizedExecutor(caller, mode, executionData)](#ERC7821WithExecutor-_erc7821AuthorizedExecutor-address-bytes32-bytes-) -#### ERC7821 [!toc] +
+ERC7821 + - [execute(mode, executionData)](#ERC7821-execute-bytes32-bytes-) - [supportsExecutionMode(mode)](#ERC7821-supportsExecutionMode-bytes32-) -#### IERC7821 [!toc] -#### Initializable [!toc] + +
+
+Initializable + - [_checkInitializing()](#Initializable-_checkInitializing--) - [_disableInitializers()](#Initializable-_disableInitializers--) - [_getInitializedVersion()](#Initializable-_getInitializedVersion--) - [_isInitializing()](#Initializable-_isInitializing--) - [_initializableStorageSlot()](#Initializable-_initializableStorageSlot--) + +

Events

-#### ERC7821 [!toc] -#### IERC7821 [!toc] -#### Initializable [!toc] +
+Initializable + - [Initialized(version)](#Initializable-Initialized-uint64-) + +

Errors

-#### ERC7821 [!toc] +
+ERC7821 + - [UnsupportedExecutionMode()](#ERC7821-UnsupportedExecutionMode--) -#### IERC7821 [!toc] -#### Initializable [!toc] + +
+
+Initializable + - [InvalidInitialization()](#Initializable-InvalidInitialization--) - [NotInitializing()](#Initializable-NotInitializing--) + +
@@ -143,16 +912,16 @@ function _erc7821AuthorizedExecutor(
-## `VestingWalletCliffConfidential` +## `VestingWalletCliffConfidential` - +
```solidity -import "@openzeppelin/confidential-contracts/finance/VestingWalletCliffConfidential.sol"; +import "@openzeppelin/confidential-contracts/contracts/finance/VestingWalletCliffConfidential.sol"; ``` An extension of [`VestingWalletConfidential`](#VestingWalletConfidential) that adds a cliff to the vesting schedule. The cliff is `cliffSeconds` long and @@ -165,7 +934,9 @@ starts at the vesting start timestamp (see [`VestingWalletConfidential`](#Vestin - [__VestingWalletCliffConfidential_init(beneficiary, startTimestamp, durationSeconds, cliffSeconds)](#VestingWalletCliffConfidential-__VestingWalletCliffConfidential_init-address-uint48-uint48-uint48-) - [__VestingWalletCliffConfidential_init_unchained(cliffSeconds)](#VestingWalletCliffConfidential-__VestingWalletCliffConfidential_init_unchained-uint48-) - [_vestingSchedule(totalAllocation, timestamp)](#VestingWalletCliffConfidential-_vestingSchedule-euint128-uint48-) -#### VestingWalletConfidential [!toc] +
+VestingWalletConfidential + - [start()](#VestingWalletConfidential-start--) - [duration()](#VestingWalletConfidential-duration--) - [end()](#VestingWalletConfidential-end--) @@ -175,9 +946,18 @@ starts at the vesting start timestamp (see [`VestingWalletConfidential`](#Vestin - [vestedAmount(token, timestamp)](#VestingWalletConfidential-vestedAmount-address-uint48-) - [__VestingWalletConfidential_init(beneficiary, startTimestamp, durationSeconds)](#VestingWalletConfidential-__VestingWalletConfidential_init-address-uint48-uint48-) - [__VestingWalletConfidential_init_unchained(startTimestamp, durationSeconds)](#VestingWalletConfidential-__VestingWalletConfidential_init_unchained-uint48-uint48-) -#### ReentrancyGuardTransient [!toc] + +
+
+ReentrancyGuardTransient + - [_reentrancyGuardEntered()](#ReentrancyGuardTransient-_reentrancyGuardEntered--) -#### OwnableUpgradeable [!toc] +- [_reentrancyGuardStorageSlot()](#ReentrancyGuardTransient-_reentrancyGuardStorageSlot--) + +
+
+OwnableUpgradeable + - [__Ownable_init(initialOwner)](#OwnableUpgradeable-__Ownable_init-address-) - [__Ownable_init_unchained(initialOwner)](#OwnableUpgradeable-__Ownable_init_unchained-address-) - [owner()](#OwnableUpgradeable-owner--) @@ -185,32 +965,52 @@ starts at the vesting start timestamp (see [`VestingWalletConfidential`](#Vestin - [renounceOwnership()](#OwnableUpgradeable-renounceOwnership--) - [transferOwnership(newOwner)](#OwnableUpgradeable-transferOwnership-address-) - [_transferOwnership(newOwner)](#OwnableUpgradeable-_transferOwnership-address-) -#### ContextUpgradeable [!toc] + +
+
+ContextUpgradeable + - [__Context_init()](#ContextUpgradeable-__Context_init--) - [__Context_init_unchained()](#ContextUpgradeable-__Context_init_unchained--) - [_msgSender()](#ContextUpgradeable-_msgSender--) - [_msgData()](#ContextUpgradeable-_msgData--) - [_contextSuffixLength()](#ContextUpgradeable-_contextSuffixLength--) -#### Initializable [!toc] + +
+
+Initializable + - [_checkInitializing()](#Initializable-_checkInitializing--) - [_disableInitializers()](#Initializable-_disableInitializers--) - [_getInitializedVersion()](#Initializable-_getInitializedVersion--) - [_isInitializing()](#Initializable-_isInitializing--) - [_initializableStorageSlot()](#Initializable-_initializableStorageSlot--) + +

Events

-#### VestingWalletConfidential [!toc] +
+VestingWalletConfidential + - [VestingWalletConfidentialTokenReleased(token, amount)](#VestingWalletConfidential-VestingWalletConfidentialTokenReleased-address-euint64-) -#### ReentrancyGuardTransient [!toc] -#### OwnableUpgradeable [!toc] + +
+
+OwnableUpgradeable + - [OwnershipTransferred(previousOwner, newOwner)](#OwnableUpgradeable-OwnershipTransferred-address-address-) -#### ContextUpgradeable [!toc] -#### Initializable [!toc] + +
+
+Initializable + - [Initialized(version)](#Initializable-Initialized-uint64-) + +
@@ -218,16 +1018,26 @@ starts at the vesting start timestamp (see [`VestingWalletConfidential`](#Vestin

Errors

- [VestingWalletCliffConfidentialInvalidCliffDuration(cliffSeconds, durationSeconds)](#VestingWalletCliffConfidential-VestingWalletCliffConfidentialInvalidCliffDuration-uint64-uint64-) -#### VestingWalletConfidential [!toc] -#### ReentrancyGuardTransient [!toc] +
+ReentrancyGuardTransient + - [ReentrancyGuardReentrantCall()](#ReentrancyGuardTransient-ReentrancyGuardReentrantCall--) -#### OwnableUpgradeable [!toc] + +
+
+OwnableUpgradeable + - [OwnableUnauthorizedAccount(account)](#OwnableUpgradeable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#OwnableUpgradeable-OwnableInvalidOwner-address-) -#### ContextUpgradeable [!toc] -#### Initializable [!toc] + +
+
+Initializable + - [InvalidInitialization()](#Initializable-InvalidInitialization--) - [NotInitializing()](#Initializable-NotInitializing--) + +
@@ -326,16 +1136,16 @@ The specified cliff duration is larger than the vesting duration.
-## `VestingWalletConfidential` +## `VestingWalletConfidential` - +
```solidity -import "@openzeppelin/confidential-contracts/finance/VestingWalletConfidential.sol"; +import "@openzeppelin/confidential-contracts/contracts/finance/VestingWalletConfidential.sol"; ``` A vesting wallet is an ownable contract that can receive ERC7984 tokens, and release these @@ -354,7 +1164,7 @@ Since the wallet is `Ownable`, and ownership can be transferred, it is possible When using this contract with any token whose balance is adjusted automatically (i.e. a rebase token), make -sure to account the supply/balance adjustment in the vesting schedule to ensure the vested amount is as intended. +sure to account for the supply/balance adjustment in the vesting schedule to ensure the vested amount is as intended. Confidential vesting wallet contracts can be deployed (as clones) using the [`VestingWalletConfidentialFactory`](#VestingWalletConfidentialFactory). @@ -372,9 +1182,16 @@ Confidential vesting wallet contracts can be deployed (as clones) using the [`Ve - [__VestingWalletConfidential_init(beneficiary, startTimestamp, durationSeconds)](#VestingWalletConfidential-__VestingWalletConfidential_init-address-uint48-uint48-) - [__VestingWalletConfidential_init_unchained(startTimestamp, durationSeconds)](#VestingWalletConfidential-__VestingWalletConfidential_init_unchained-uint48-uint48-) - [_vestingSchedule(totalAllocation, timestamp)](#VestingWalletConfidential-_vestingSchedule-euint128-uint48-) -#### ReentrancyGuardTransient [!toc] +
+ReentrancyGuardTransient + - [_reentrancyGuardEntered()](#ReentrancyGuardTransient-_reentrancyGuardEntered--) -#### OwnableUpgradeable [!toc] +- [_reentrancyGuardStorageSlot()](#ReentrancyGuardTransient-_reentrancyGuardStorageSlot--) + +
+
+OwnableUpgradeable + - [__Ownable_init(initialOwner)](#OwnableUpgradeable-__Ownable_init-address-) - [__Ownable_init_unchained(initialOwner)](#OwnableUpgradeable-__Ownable_init_unchained-address-) - [owner()](#OwnableUpgradeable-owner--) @@ -382,18 +1199,28 @@ Confidential vesting wallet contracts can be deployed (as clones) using the [`Ve - [renounceOwnership()](#OwnableUpgradeable-renounceOwnership--) - [transferOwnership(newOwner)](#OwnableUpgradeable-transferOwnership-address-) - [_transferOwnership(newOwner)](#OwnableUpgradeable-_transferOwnership-address-) -#### ContextUpgradeable [!toc] + +
+
+ContextUpgradeable + - [__Context_init()](#ContextUpgradeable-__Context_init--) - [__Context_init_unchained()](#ContextUpgradeable-__Context_init_unchained--) - [_msgSender()](#ContextUpgradeable-_msgSender--) - [_msgData()](#ContextUpgradeable-_msgData--) - [_contextSuffixLength()](#ContextUpgradeable-_contextSuffixLength--) -#### Initializable [!toc] + +
+
+Initializable + - [_checkInitializing()](#Initializable-_checkInitializing--) - [_disableInitializers()](#Initializable-_disableInitializers--) - [_getInitializedVersion()](#Initializable-_getInitializedVersion--) - [_isInitializing()](#Initializable-_isInitializing--) - [_initializableStorageSlot()](#Initializable-_initializableStorageSlot--) + +
@@ -401,27 +1228,44 @@ Confidential vesting wallet contracts can be deployed (as clones) using the [`Ve

Events

- [VestingWalletConfidentialTokenReleased(token, amount)](#VestingWalletConfidential-VestingWalletConfidentialTokenReleased-address-euint64-) -#### ReentrancyGuardTransient [!toc] -#### OwnableUpgradeable [!toc] +
+OwnableUpgradeable + - [OwnershipTransferred(previousOwner, newOwner)](#OwnableUpgradeable-OwnershipTransferred-address-address-) -#### ContextUpgradeable [!toc] -#### Initializable [!toc] + +
+
+Initializable + - [Initialized(version)](#Initializable-Initialized-uint64-) + +

Errors

-#### ReentrancyGuardTransient [!toc] +
+ReentrancyGuardTransient + - [ReentrancyGuardReentrantCall()](#ReentrancyGuardTransient-ReentrancyGuardReentrantCall--) -#### OwnableUpgradeable [!toc] + +
+
+OwnableUpgradeable + - [OwnableUnauthorizedAccount(account)](#OwnableUpgradeable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#OwnableUpgradeable-OwnableInvalidOwner-address-) -#### ContextUpgradeable [!toc] -#### Initializable [!toc] + +
+
+Initializable + - [InvalidInitialization()](#Initializable-InvalidInitialization--) - [NotInitializing()](#Initializable-NotInitializing--) + +
@@ -620,16 +1464,16 @@ Emitted when releasable vested tokens are released.
-## `VestingWalletConfidentialFactory` +## `VestingWalletConfidentialFactory` - +
```solidity -import "@openzeppelin/confidential-contracts/finance/VestingWalletConfidentialFactory.sol"; +import "@openzeppelin/confidential-contracts/contracts/finance/VestingWalletConfidentialFactory.sol"; ``` A factory which enables batch funding of vesting wallets. @@ -836,3 +1680,4 @@ Emitted when a vesting wallet is deployed. + diff --git a/content/confidential-contracts/api/governance.mdx b/content/confidential-contracts/api/governance.mdx index 4089b3d4..1eec5652 100644 --- a/content/confidential-contracts/api/governance.mdx +++ b/content/confidential-contracts/api/governance.mdx @@ -14,20 +14,20 @@ This directory includes primitives for on-chain confidential governance.
-## `VotesConfidential` +## `VotesConfidential` - +
```solidity -import "@openzeppelin/confidential-contracts/governance/utils/VotesConfidential.sol"; +import "@openzeppelin/confidential-contracts/contracts/governance/utils/VotesConfidential.sol"; ``` A confidential votes contract tracking confidential voting power of accounts over time. -It features vote delegation to delegators. +It features vote delegation to delegatees. This contract keeps a history (checkpoints) of each account's confidential vote power. Confidential voting power can be delegated either by calling the [`VotesConfidential.delegate`](#VotesConfidential-delegate-address-) function directly, or by providing @@ -36,7 +36,7 @@ through the public accessors [`VotesConfidential.getVotes`](#VotesConfidential-g allowed to access them. Ensure that [`HandleAccessManager._validateHandleAllowance`](/confidential-contracts/api/utils#HandleAccessManager-_validateHandleAllowance-bytes32-) is implemented properly, allowing all necessary addresses to access voting power handles. -By default, voting units does not account for voting power. This makes transfers of underlying +By default, transfer of voting units does not account for voting power. This makes transfers of voting units cheaper. The downside is that it requires users to delegate to themselves in order to activate checkpoints and have their voting power tracked. @@ -57,21 +57,31 @@ to activate checkpoints and have their voting power tracked. - [_moveDelegateVotes(from, to, amount)](#VotesConfidential-_moveDelegateVotes-address-address-euint64-) - [_validateTimepoint(timepoint)](#VotesConfidential-_validateTimepoint-uint256-) - [_getVotingUnits()](#VotesConfidential-_getVotingUnits-address-) -#### HandleAccessManager [!toc] +
+HandleAccessManager + - [getHandleAllowance(handle, account, persistent)](#HandleAccessManager-getHandleAllowance-bytes32-address-bool-) -- [_validateHandleAllowance(handle)](#HandleAccessManager-_validateHandleAllowance-bytes32-) -#### IERC6372 [!toc] -#### EIP712 [!toc] +- [_validateHandleAllowance()](#HandleAccessManager-_validateHandleAllowance-bytes32-) + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) + +
@@ -80,12 +90,12 @@ to activate checkpoints and have their voting power tracked.
- [DelegateVotesChanged(delegate, previousVotes, newVotes)](#VotesConfidential-DelegateVotesChanged-address-euint64-euint64-) - [DelegateChanged(delegator, fromDelegate, toDelegate)](#VotesConfidential-DelegateChanged-address-address-address-) -#### HandleAccessManager [!toc] -#### IERC6372 [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] +
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### Nonces [!toc] + +
@@ -95,12 +105,18 @@ to activate checkpoints and have their voting power tracked. - [VotesExpiredSignature(expiry)](#VotesConfidential-VotesExpiredSignature-uint256-) - [ERC6372InconsistentClock()](#VotesConfidential-ERC6372InconsistentClock--) - [ERC5805FutureLookup(timepoint, clock)](#VotesConfidential-ERC5805FutureLookup-uint256-uint48-) -#### HandleAccessManager [!toc] -#### IERC6372 [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### Nonces [!toc] +
+HandleAccessManager + +- [HandleAccessManagerNotAllowed(handle, account)](#HandleAccessManager-HandleAccessManagerNotAllowed-bytes32-address-) + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) + +
@@ -452,3 +468,4 @@ Lookup to future votes is not available. + diff --git a/content/confidential-contracts/api/interfaces.mdx b/content/confidential-contracts/api/interfaces.mdx index 9f30b727..7d2437cc 100644 --- a/content/confidential-contracts/api/interfaces.mdx +++ b/content/confidential-contracts/api/interfaces.mdx @@ -7,25 +7,30 @@ These interfaces are available as `.sol` files and are useful to interact with t * [`IERC7984`](#IERC7984) * [`IERC7984Receiver`](#IERC7984Receiver) +* [`IERC7984Rwa`](#IERC7984Rwa) ## Core [`IERC7984`](#IERC7984) [`IERC7984Receiver`](#IERC7984Receiver) +## Extensions +[`IERC7984Rwa`](#IERC7984Rwa) +[`IERC7984ERC20Wrapper`](#IERC7984ERC20Wrapper) +
-## `IERC7984` +## `IERC7984` - +
```solidity -import "@openzeppelin/confidential-contracts/interfaces/IERC7984.sol"; +import "@openzeppelin/confidential-contracts/contracts/interfaces/IERC7984.sol"; ``` Draft interface for a confidential fungible token standard utilizing the Zama FHE library. @@ -49,8 +54,12 @@ Draft interface for a confidential fungible token standard utilizing the Zama FH - [confidentialTransferAndCall(to, amount, data)](#IERC7984-confidentialTransferAndCall-address-euint64-bytes-) - [confidentialTransferFromAndCall(from, to, encryptedAmount, inputProof, data)](#IERC7984-confidentialTransferFromAndCall-address-address-externalEuint64-bytes-bytes-) - [confidentialTransferFromAndCall(from, to, amount, data)](#IERC7984-confidentialTransferFromAndCall-address-address-euint64-bytes-) -#### IERC165 [!toc] +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -60,7 +69,6 @@ Draft interface for a confidential fungible token standard utilizing the Zama FH - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] @@ -235,7 +243,7 @@ Returns the encrypted amount that was actually transferred.
-Similar to #IERC7984-confidentialTransfer-address-externalEuint64-bytes- but without an input proof. The caller +Similar to `confidentialTransfer-address-externalEuint64-bytes` but without an input proof. The caller *must* already be allowed by ACL for the given `amount`.
@@ -273,7 +281,7 @@ Returns the encrypted amount that was actually transferred.
-Similar to #IERC7984-confidentialTransferFrom-address-address-externalEuint64-bytes- but without an input proof. +Similar to `confidentialTransferFrom-address-address-externalEuint64-bytes` but without an input proof. The caller *must* be already allowed by ACL for the given `amount`.
@@ -291,7 +299,7 @@ The caller *must* be already allowed by ACL for the given `amount`.
-Similar to #IERC7984-confidentialTransfer-address-externalEuint64-bytes- but with a callback to `to` after +Similar to `confidentialTransfer-address-externalEuint64-bytes` but with a callback to `to` after the transfer. The callback is made to the [`IERC7984Receiver.onConfidentialTransferReceived`](#IERC7984Receiver-onConfidentialTransferReceived-address-address-euint64-bytes-) function on the @@ -313,7 +321,7 @@ data `data`.
-Similar to #IERC7984-confidentialTransfer-address-euint64- but with a callback to `to` after the transfer. +Similar to `confidentialTransfer-address-euint64` but with a callback to `to` after the transfer.
@@ -330,7 +338,7 @@ Similar to #IERC7984-confidentialTransfer-address-euint64- but with a callback t
-Similar to #IERC7984-confidentialTransferFrom-address-address-externalEuint64-bytes- but with a callback to `to` +Similar to `confidentialTransferFrom-address-address-externalEuint64-bytes` but with a callback to `to` after the transfer.
@@ -348,7 +356,7 @@ after the transfer.
-Similar to #IERC7984-confidentialTransferFrom-address-address-euint64- but with a callback to `to` +Similar to `confidentialTransferFrom-address-address-euint64` but with a callback to `to` after the transfer.
@@ -410,20 +418,240 @@ should be able to disclose the amount. This functionality is implementation spec + + +
+ +## `IERC7984ERC20Wrapper` + + + + + +
+ +```solidity +import "@openzeppelin/confidential-contracts/contracts/interfaces/IERC7984ERC20Wrapper.sol"; +``` + +Interface for ERC7984ERC20Wrapper contract. + +
+

Functions

+
+- [wrap(to, amount)](#IERC7984ERC20Wrapper-wrap-address-uint256-) +- [unwrap(from, to, encryptedAmount, inputProof)](#IERC7984ERC20Wrapper-unwrap-address-address-externalEuint64-bytes-) +- [underlying()](#IERC7984ERC20Wrapper-underlying--) +- [finalizeUnwrap(unwrapRequestId, unwrapAmountCleartext, decryptionProof)](#IERC7984ERC20Wrapper-finalizeUnwrap-bytes32-uint64-bytes-) +- [rate()](#IERC7984ERC20Wrapper-rate--) +- [unwrapAmount(unwrapRequestId)](#IERC7984ERC20Wrapper-unwrapAmount-bytes32-) +
+IERC7984 + +- [name()](#IERC7984-name--) +- [symbol()](#IERC7984-symbol--) +- [decimals()](#IERC7984-decimals--) +- [contractURI()](#IERC7984-contractURI--) +- [confidentialTotalSupply()](#IERC7984-confidentialTotalSupply--) +- [confidentialBalanceOf(account)](#IERC7984-confidentialBalanceOf-address-) +- [isOperator(holder, spender)](#IERC7984-isOperator-address-address-) +- [setOperator(operator, until)](#IERC7984-setOperator-address-uint48-) +- [confidentialTransfer(to, encryptedAmount, inputProof)](#IERC7984-confidentialTransfer-address-externalEuint64-bytes-) +- [confidentialTransfer(to, amount)](#IERC7984-confidentialTransfer-address-euint64-) +- [confidentialTransferFrom(from, to, encryptedAmount, inputProof)](#IERC7984-confidentialTransferFrom-address-address-externalEuint64-bytes-) +- [confidentialTransferFrom(from, to, amount)](#IERC7984-confidentialTransferFrom-address-address-euint64-) +- [confidentialTransferAndCall(to, encryptedAmount, inputProof, data)](#IERC7984-confidentialTransferAndCall-address-externalEuint64-bytes-bytes-) +- [confidentialTransferAndCall(to, amount, data)](#IERC7984-confidentialTransferAndCall-address-euint64-bytes-) +- [confidentialTransferFromAndCall(from, to, encryptedAmount, inputProof, data)](#IERC7984-confidentialTransferFromAndCall-address-address-externalEuint64-bytes-bytes-) +- [confidentialTransferFromAndCall(from, to, amount, data)](#IERC7984-confidentialTransferFromAndCall-address-address-euint64-bytes-) + +
+
+IERC165 + +- [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
+
+
+ +
+

Events

+
+- [UnwrapRequested(receiver, unwrapRequestId, amount)](#IERC7984ERC20Wrapper-UnwrapRequested-address-bytes32-euint64-) +- [UnwrapFinalized(receiver, unwrapRequestId, encryptedAmount, cleartextAmount)](#IERC7984ERC20Wrapper-UnwrapFinalized-address-bytes32-euint64-uint64-) +
+IERC7984 + +- [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) +- [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) +- [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) + +
+
+
+ + + +
+
+

wrap(address to, uint256 amount) โ†’ euint64

+
+

external

+# +
+
+
+ +Wraps `amount` of the underlying token into a confidential token and sends it to `to`. + +Returns amount of wrapped token sent. + +
+
+ + + +
+
+

unwrap(address from, address to, externalEuint64 encryptedAmount, bytes inputProof) โ†’ bytes32

+
+

external

+# +
+
+
+ +Unwraps tokens from `from` and sends the underlying tokens to `to`. The caller must be `from` +or be an approved operator for `from`. + +Returns the unwrap request id. + + +The returned unwrap request id must never be zero. + + +
+
+ + + +
+
+

underlying() โ†’ address

+
+

external

+# +
+
+
+ +Returns the address of the underlying ERC-20 token that is being wrapped. + +
+
+ + + +
+
+

finalizeUnwrap(bytes32 unwrapRequestId, uint64 unwrapAmountCleartext, bytes decryptionProof)

+
+

external

+# +
+
+
+ +Finalizes an unwrap request identified by `unwrapRequestId` with the given `unwrapAmountCleartext` and `decryptionProof`. + +
+
+ + + +
+
+

rate() โ†’ uint256

+
+

external

+# +
+
+
+ +Returns the rate at which the underlying token is converted to the wrapped token. +For example, if the `rate` is 1000, then 1000 units of the underlying token equal 1 unit of the wrapped token. + +
+
+ + + +
+
+

unwrapAmount(bytes32 unwrapRequestId) โ†’ euint64

+
+

external

+# +
+
+
+ +Returns the amount of wrapper tokens that were unwrapped for a given `unwrapRequestId`. + +
+
+ + + +
+
+

UnwrapRequested(address indexed receiver, bytes32 indexed unwrapRequestId, euint64 amount)

+
+

event

+# +
+
+ +
+ +Emitted when an unwrap request is made for a given `receiver`, `unwrapRequestId`, and `amount`. + +
+
+ + +
+
+

UnwrapFinalized(address indexed receiver, bytes32 indexed unwrapRequestId, euint64 encryptedAmount, uint64 cleartextAmount)

+
+

event

+# +
+
+ +
+ +Emitted when an unwrap request is finalized for a given `receiver`, `unwrapRequestId`, `encryptedAmount`, and `cleartextAmount`. + +
+
+
-## `IERC7984Receiver` +## `IERC7984Receiver` - +
```solidity -import "@openzeppelin/confidential-contracts/interfaces/IERC7984Receiver.sol"; +import "@openzeppelin/confidential-contracts/contracts/interfaces/IERC7984Receiver.sol"; ``` Interface for contracts that can receive ERC7984 transfers with a callback. @@ -448,7 +676,15 @@ Interface for contracts that can receive ERC7984 transfers with a callback.
Called upon receiving a confidential token transfer. Returns an encrypted boolean indicating success -of the callback. If false is returned, the transfer must be reversed. +of the callback. If false is returned, the token contract will attempt to refund the transfer. + + +The calling contract (token) must be granted ACL allowance to read the confidential return value. + + + +Do not manually refund the transfer AND return false, as this can lead to double refunds. +
@@ -457,16 +693,16 @@ of the callback. If false is returned, the transfer must be reversed.
-## `IERC7984Rwa` +## `IERC7984Rwa` - +
```solidity -import "@openzeppelin/confidential-contracts/interfaces/IERC7984Rwa.sol"; +import "@openzeppelin/confidential-contracts/contracts/interfaces/IERC7984Rwa.sol"; ``` Interface for confidential RWA contracts. @@ -475,7 +711,7 @@ Interface for confidential RWA contracts.

Functions

- [paused()](#IERC7984Rwa-paused--) -- [isUserAllowed(account)](#IERC7984Rwa-isUserAllowed-address-) +- [canTransact(account)](#IERC7984Rwa-canTransact-address-) - [confidentialFrozen(account)](#IERC7984Rwa-confidentialFrozen-address-) - [confidentialAvailable(account)](#IERC7984Rwa-confidentialAvailable-address-) - [pause()](#IERC7984Rwa-pause--) @@ -490,7 +726,9 @@ Interface for confidential RWA contracts. - [confidentialBurn(account, encryptedAmount)](#IERC7984Rwa-confidentialBurn-address-euint64-) - [forceConfidentialTransferFrom(from, to, encryptedAmount, inputProof)](#IERC7984Rwa-forceConfidentialTransferFrom-address-address-externalEuint64-bytes-) - [forceConfidentialTransferFrom(from, to, encryptedAmount)](#IERC7984Rwa-forceConfidentialTransferFrom-address-address-euint64-) -#### IERC7984 [!toc] +
+IERC7984 + - [name()](#IERC7984-name--) - [symbol()](#IERC7984-symbol--) - [decimals()](#IERC7984-decimals--) @@ -507,19 +745,28 @@ Interface for confidential RWA contracts. - [confidentialTransferAndCall(to, amount, data)](#IERC7984-confidentialTransferAndCall-address-euint64-bytes-) - [confidentialTransferFromAndCall(from, to, encryptedAmount, inputProof, data)](#IERC7984-confidentialTransferFromAndCall-address-address-externalEuint64-bytes-bytes-) - [confidentialTransferFromAndCall(from, to, amount, data)](#IERC7984-confidentialTransferFromAndCall-address-address-euint64-bytes-) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-#### IERC7984 [!toc] +
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] + +
@@ -540,14 +787,14 @@ Returns true if the contract is paused, false otherwise. - +
-

isUserAllowed(address account) โ†’ bool

+

canTransact(address account) โ†’ bool

external

-# +#
diff --git a/content/confidential-contracts/api/token.mdx b/content/confidential-contracts/api/token.mdx index c1cb0ba9..e5215b12 100644 --- a/content/confidential-contracts/api/token.mdx +++ b/content/confidential-contracts/api/token.mdx @@ -12,6 +12,7 @@ This set of interfaces, contracts, and utilities are all related to `ERC7984`, a * [`ERC7984Restricted`](#ERC7984Restricted): An extension of [`ERC7984`](#ERC7984) that implements user account transfer restrictions. * [`ERC7984Omnibus`](#ERC7984Omnibus): An extension of [`ERC7984`](#ERC7984) that emits additional events for omnibus transfers, which contain encrypted addresses for the sub-account sender and recipient. * [`ERC7984Rwa`](#ERC7984Rwa): Extension of [`ERC7984`](#ERC7984) that supports confidential Real World Assets (RWAs) by providing compliance checks, transfer controls and enforcement actions. +* [`ERC7984Votes`](#ERC7984Votes): An extension of [`ERC7984`](#ERC7984) that supports confidential vote tracking and delegation via [`VotesConfidential`](/confidential-contracts/api/governance#VotesConfidential). * [`ERC7984Utils`](#ERC7984Utils): A library that provides the on-transfer callback check used by [`ERC7984`](#ERC7984). ## Core @@ -24,6 +25,7 @@ This set of interfaces, contracts, and utilities are all related to `ERC7984`, a [`ERC7984Restricted`](#ERC7984Restricted) [`ERC7984Omnibus`](#ERC7984Omnibus) [`ERC7984Rwa`](#ERC7984Rwa) +[`ERC7984Votes`](#ERC7984Votes) ## Utilities [`ERC7984Utils`](#ERC7984Utils) @@ -32,16 +34,16 @@ This set of interfaces, contracts, and utilities are all related to `ERC7984`, a
-## `ERC7984` +## `ERC7984` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/ERC7984.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/ERC7984.sol"; ``` Reference implementation for [`IERC7984`](/confidential-contracts/api/interfaces#IERC7984). @@ -87,9 +89,6 @@ Key features: - [_transfer(from, to, amount)](#ERC7984-_transfer-address-address-euint64-) - [_transferAndCall(from, to, amount, data)](#ERC7984-_transferAndCall-address-address-euint64-bytes-) - [_update(from, to, amount)](#ERC7984-_update-address-address-euint64-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc]
@@ -97,12 +96,14 @@ Key features:

Events

- [AmountDiscloseRequested(encryptedAmount, requester)](#ERC7984-AmountDiscloseRequested-euint64-address-) -#### ERC165 [!toc] -#### IERC7984 [!toc] +
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] + +
@@ -115,10 +116,6 @@ Key features: - [ERC7984ZeroBalance(holder)](#ERC7984-ERC7984ZeroBalance-address-) - [ERC7984UnauthorizedUseOfEncryptedAmount(amount, user)](#ERC7984-ERC7984UnauthorizedUseOfEncryptedAmount-euint64-address-) - [ERC7984UnauthorizedCaller(caller)](#ERC7984-ERC7984UnauthorizedCaller-address-) -- [ERC7984InvalidGatewayRequest(requestId)](#ERC7984-ERC7984InvalidGatewayRequest-uint256-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] @@ -330,7 +327,7 @@ Returns the encrypted amount that was actually transferred.
-Similar to interfaces#IERC7984-confidentialTransfer-address-externalEuint64-bytes- but without an input proof. The caller +Similar to `confidentialTransfer-address-externalEuint64-bytes` but without an input proof. The caller *must* already be allowed by ACL for the given `amount`.
@@ -368,7 +365,7 @@ Returns the encrypted amount that was actually transferred.
-Similar to interfaces#IERC7984-confidentialTransferFrom-address-address-externalEuint64-bytes- but without an input proof. +Similar to `confidentialTransferFrom-address-address-externalEuint64-bytes` but without an input proof. The caller *must* be already allowed by ACL for the given `amount`.
@@ -386,7 +383,7 @@ The caller *must* be already allowed by ACL for the given `amount`.
-Similar to interfaces#IERC7984-confidentialTransfer-address-externalEuint64-bytes- but with a callback to `to` after +Similar to `confidentialTransfer-address-externalEuint64-bytes` but with a callback to `to` after the transfer. The callback is made to the [`IERC7984Receiver.onConfidentialTransferReceived`](/confidential-contracts/api/interfaces#IERC7984Receiver-onConfidentialTransferReceived-address-address-euint64-bytes-) function on the @@ -408,7 +405,7 @@ data `data`.
-Similar to interfaces#IERC7984-confidentialTransfer-address-euint64- but with a callback to `to` after the transfer. +Similar to `confidentialTransfer-address-euint64` but with a callback to `to` after the transfer.
@@ -425,7 +422,7 @@ Similar to interfaces#IERC7984-confidentialTransfer-address-euint64- but with a
-Similar to interfaces#IERC7984-confidentialTransferFrom-address-address-externalEuint64-bytes- but with a callback to `to` +Similar to `confidentialTransferFrom-address-address-externalEuint64-bytes` but with a callback to `to` after the transfer.
@@ -443,7 +440,7 @@ after the transfer.
-Similar to interfaces#IERC7984-confidentialTransferFrom-address-address-euint64- but with a callback to `to` +Similar to `confidentialTransferFrom-address-address-euint64` but with a callback to `to` after the transfer.
@@ -707,37 +704,20 @@ The given caller `caller` is not authorized for the current operation. - - -
-
-

ERC7984InvalidGatewayRequest(uint256 requestId)

-
-

error

-# -
-
-
- -The given gateway request ID `requestId` is invalid. - -
-
-
-## `ERC7984ERC20Wrapper` +## `ERC7984ERC20Wrapper` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984ERC20Wrapper.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/extensions/ERC7984ERC20Wrapper.sol"; ``` A wrapper contract built on top of [`ERC7984`](#ERC7984) that allows wrapping an `ERC20` token @@ -753,20 +733,27 @@ tokens such as fee-on-transfer or other deflationary-type tokens are not support

Functions

- [constructor(underlying_)](#ERC7984ERC20Wrapper-constructor-contract-IERC20-) -- [decimals()](#ERC7984ERC20Wrapper-decimals--) -- [rate()](#ERC7984ERC20Wrapper-rate--) -- [underlying()](#ERC7984ERC20Wrapper-underlying--) - [onTransferReceived(, from, amount, data)](#ERC7984ERC20Wrapper-onTransferReceived-address-address-uint256-bytes-) - [wrap(to, amount)](#ERC7984ERC20Wrapper-wrap-address-uint256-) - [unwrap(from, to, amount)](#ERC7984ERC20Wrapper-unwrap-address-address-euint64-) - [unwrap(from, to, encryptedAmount, inputProof)](#ERC7984ERC20Wrapper-unwrap-address-address-externalEuint64-bytes-) -- [finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)](#ERC7984ERC20Wrapper-finalizeUnwrap-euint64-uint64-bytes-) +- [finalizeUnwrap(unwrapRequestId, unwrapAmountCleartext, decryptionProof)](#ERC7984ERC20Wrapper-finalizeUnwrap-bytes32-uint64-bytes-) +- [decimals()](#ERC7984ERC20Wrapper-decimals--) +- [rate()](#ERC7984ERC20Wrapper-rate--) +- [underlying()](#ERC7984ERC20Wrapper-underlying--) +- [unwrapAmount(unwrapRequestId)](#ERC7984ERC20Wrapper-unwrapAmount-bytes32-) +- [supportsInterface(interfaceId)](#ERC7984ERC20Wrapper-supportsInterface-bytes4-) +- [inferredTotalSupply()](#ERC7984ERC20Wrapper-inferredTotalSupply--) +- [maxTotalSupply()](#ERC7984ERC20Wrapper-maxTotalSupply--) +- [unwrapRequester(unwrapRequestId)](#ERC7984ERC20Wrapper-unwrapRequester-bytes32-) +- [_checkConfidentialTotalSupply()](#ERC7984ERC20Wrapper-_checkConfidentialTotalSupply--) +- [_update(from, to, amount)](#ERC7984ERC20Wrapper-_update-address-address-euint64-) - [_unwrap(from, to, amount)](#ERC7984ERC20Wrapper-_unwrap-address-address-euint64-) - [_fallbackUnderlyingDecimals()](#ERC7984ERC20Wrapper-_fallbackUnderlyingDecimals--) - [_maxDecimals()](#ERC7984ERC20Wrapper-_maxDecimals--) -#### IERC1363Receiver [!toc] -#### ERC7984 [!toc] -- [supportsInterface(interfaceId)](#ERC7984-supportsInterface-bytes4-) +
+ERC7984 + - [name()](#ERC7984-name--) - [symbol()](#ERC7984-symbol--) - [contractURI()](#ERC7984-contractURI--) @@ -789,46 +776,54 @@ tokens such as fee-on-transfer or other deflationary-type tokens are not support - [_burn(from, amount)](#ERC7984-_burn-address-euint64-) - [_transfer(from, to, amount)](#ERC7984-_transfer-address-address-euint64-) - [_transferAndCall(from, to, amount, data)](#ERC7984-_transferAndCall-address-address-euint64-bytes-) -- [_update(from, to, amount)](#ERC7984-_update-address-address-euint64-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +

Events

-- [UnwrapRequested(receiver, amount)](#ERC7984ERC20Wrapper-UnwrapRequested-address-euint64-) -- [UnwrapFinalized(receiver, encryptedAmount, cleartextAmount)](#ERC7984ERC20Wrapper-UnwrapFinalized-address-euint64-uint64-) -#### IERC1363Receiver [!toc] -#### ERC7984 [!toc] +
+IERC7984ERC20Wrapper + +- [UnwrapRequested(receiver, unwrapRequestId, amount)](#IERC7984ERC20Wrapper-UnwrapRequested-address-bytes32-euint64-) +- [UnwrapFinalized(receiver, unwrapRequestId, encryptedAmount, cleartextAmount)](#IERC7984ERC20Wrapper-UnwrapFinalized-address-bytes32-euint64-uint64-) + +
+
+ERC7984 + - [AmountDiscloseRequested(encryptedAmount, requester)](#ERC7984-AmountDiscloseRequested-euint64-address-) -#### ERC165 [!toc] -#### IERC7984 [!toc] + +
+
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] + +

Errors

-- [InvalidUnwrapRequest(amount)](#ERC7984ERC20Wrapper-InvalidUnwrapRequest-euint64-) -#### IERC1363Receiver [!toc] -#### ERC7984 [!toc] +- [InvalidUnwrapRequest(unwrapRequestId)](#ERC7984ERC20Wrapper-InvalidUnwrapRequest-bytes32-) +- [ERC7984TotalSupplyOverflow()](#ERC7984ERC20Wrapper-ERC7984TotalSupplyOverflow--) +
+ERC7984 + - [ERC7984InvalidReceiver(receiver)](#ERC7984-ERC7984InvalidReceiver-address-) - [ERC7984InvalidSender(sender)](#ERC7984-ERC7984InvalidSender-address-) - [ERC7984UnauthorizedSpender(holder, spender)](#ERC7984-ERC7984UnauthorizedSpender-address-address-) - [ERC7984ZeroBalance(holder)](#ERC7984-ERC7984ZeroBalance-address-) - [ERC7984UnauthorizedUseOfEncryptedAmount(amount, user)](#ERC7984-ERC7984UnauthorizedUseOfEncryptedAmount-euint64-address-) - [ERC7984UnauthorizedCaller(caller)](#ERC7984-ERC7984UnauthorizedCaller-address-) -- [ERC7984InvalidGatewayRequest(requestId)](#ERC7984-ERC7984InvalidGatewayRequest-uint256-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -847,6 +842,101 @@ tokens such as fee-on-transfer or other deflationary-type tokens are not support + + +
+
+

onTransferReceived(address, address from, uint256 amount, bytes data) โ†’ bytes4

+
+

public

+# +
+
+
+ +`ERC1363` callback function which wraps tokens to the address specified in `data` or +the address `from` (if no address is specified in `data`). This function refunds any excess tokens +sent beyond the nearest multiple of [`ERC7984ERC20Wrapper.rate`](#ERC7984ERC20Wrapper-rate--) to `from`. See [`ERC7984ERC20Wrapper.wrap`](#ERC7984ERC20Wrapper-wrap-address-uint256-) for more details on wrapping tokens. + +
+
+ + + +
+
+

wrap(address to, uint256 amount) โ†’ euint64

+
+

public

+# +
+
+
+ +See [`IERC7984ERC20Wrapper.wrap`](/confidential-contracts/api/interfaces#IERC7984ERC20Wrapper-wrap-address-uint256-). Tokens are exchanged at a fixed rate specified by [`ERC7984ERC20Wrapper.rate`](#ERC7984ERC20Wrapper-rate--) such that +`amount / rate()` confidential tokens are sent. The amount transferred in is rounded down to the nearest +multiple of [`ERC7984ERC20Wrapper.rate`](#ERC7984ERC20Wrapper-rate--). + +Returns the amount of wrapped token sent. + +
+
+ + + +
+
+

unwrap(address from, address to, euint64 amount) โ†’ bytes32

+
+

public

+# +
+
+
+ +Unwrap without passing an input proof. See `unwrap-address-address-bytes32-bytes` for more details. + +
+
+ + + +
+
+

unwrap(address from, address to, externalEuint64 encryptedAmount, bytes inputProof) โ†’ bytes32

+
+

public

+# +
+
+
+ +See [`IERC7984ERC20Wrapper.unwrap`](/confidential-contracts/api/interfaces#IERC7984ERC20Wrapper-unwrap-address-address-externalEuint64-bytes-). `amount * rate()` underlying tokens are sent to `to`. + + +The unwrap request created by this function must be finalized by calling [`ERC7984ERC20Wrapper.finalizeUnwrap`](#ERC7984ERC20Wrapper-finalizeUnwrap-bytes32-uint64-bytes-). + + +
+
+ + + +
+
+

finalizeUnwrap(bytes32 unwrapRequestId, uint64 unwrapAmountCleartext, bytes decryptionProof)

+
+

public

+# +
+
+
+ +Finalizes an unwrap request identified by `unwrapRequestId` with the given `unwrapAmountCleartext` and `decryptionProof`. + +
+
+
@@ -886,7 +976,7 @@ For example, if the `rate` is 1000, then 1000 units of the underlying token equa
-

underlying() โ†’ contract IERC20

+

underlying() โ†’ address

public

# @@ -899,100 +989,138 @@ Returns the address of the underlying ERC-20 token that is being wrapped.
- +
-

onTransferReceived(address, address from, uint256 amount, bytes data) โ†’ bytes4

+

unwrapAmount(bytes32 unwrapRequestId) โ†’ euint64

public

-# +#
-`ERC1363` callback function which wraps tokens to the address specified in `data` or -the address `from` (if no address is specified in `data`). This function refunds any excess tokens -sent beyond the nearest multiple of [`ERC7984ERC20Wrapper.rate`](#ERC7984ERC20Wrapper-rate--). See [`ERC7984ERC20Wrapper.wrap`](#ERC7984ERC20Wrapper-wrap-address-uint256-) from more details on wrapping tokens. +Returns the amount of wrapper tokens that were unwrapped for a given `unwrapRequestId`.
- +
-

wrap(address to, uint256 amount)

+

supportsInterface(bytes4 interfaceId) โ†’ bool

public

-# +#
-Wraps amount `amount` of the underlying token into a confidential token and sends it to -`to`. Tokens are exchanged at a fixed rate specified by [`ERC7984ERC20Wrapper.rate`](#ERC7984ERC20Wrapper-rate--) such that `amount / rate()` confidential -tokens are sent. Amount transferred in is rounded down to the nearest multiple of [`ERC7984ERC20Wrapper.rate`](#ERC7984ERC20Wrapper-rate--). +Returns true if this contract implements the interface defined by +`interfaceId`. See the corresponding +[ERC section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified) +to learn more about how these ids are created. + +This function call must use less than 30 000 gas.
- +
-

unwrap(address from, address to, euint64 amount)

+

inferredTotalSupply() โ†’ uint256

public

-# +#
-Unwraps tokens from `from` and sends the underlying tokens to `to`. The caller must be `from` -or be an approved operator for `from`. `amount * rate()` underlying tokens are sent to `to`. +Returns the underlying balance divided by the [`ERC7984ERC20Wrapper.rate`](#ERC7984ERC20Wrapper-rate--), a value greater or equal to the actual +[`ERC7984.confidentialTotalSupply`](#ERC7984-confidentialTotalSupply--). -The unwrap request created by this function must be finalized by calling [`ERC7984ERC20Wrapper.finalizeUnwrap`](#ERC7984ERC20Wrapper-finalizeUnwrap-euint64-uint64-bytes-). - - -The caller *must* already be approved by ACL for the given `amount`. +The return value of this function can be inflated by directly sending underlying tokens to the wrapper contract. +Reductions will lag compared to [`ERC7984.confidentialTotalSupply`](#ERC7984-confidentialTotalSupply--) since it is updated on [`ERC7984ERC20Wrapper.unwrap`](#ERC7984ERC20Wrapper-unwrap-address-address-externalEuint64-bytes-) while this function updates +on [`ERC7984ERC20Wrapper.finalizeUnwrap`](#ERC7984ERC20Wrapper-finalizeUnwrap-bytes32-uint64-bytes-).
- +
-

unwrap(address from, address to, externalEuint64 encryptedAmount, bytes inputProof)

+

maxTotalSupply() โ†’ uint256

public

-# +#
-Variant of [`ERC7984ERC20Wrapper.unwrap`](#ERC7984ERC20Wrapper-unwrap-address-address-externalEuint64-bytes-) that passes an `inputProof` which approves the caller for the `encryptedAmount` -in the ACL. +Returns the maximum total supply of wrapped tokens supported by the encrypted datatype.
- +
-

finalizeUnwrap(euint64 burntAmount, uint64 burntAmountCleartext, bytes decryptionProof)

+

unwrapRequester(bytes32 unwrapRequestId) โ†’ address

public

-# +# +
+
+
+ +Gets the address that will receive the ERC-20 tokens associated with a pending unwrap request identified by +`unwrapRequestId`. Returns `address(0)` if there is no pending unwrap request with id `unwrapRequestId`. + +
+
+ + + +
+
+

_checkConfidentialTotalSupply()

+
+

internal

+#
-Fills an unwrap request for a given cipher-text `burntAmount` with the `cleartextAmount` and `decryptionProof`. +This function must revert if the new [`ERC7984.confidentialTotalSupply`](#ERC7984-confidentialTotalSupply--) is invalid (overflow occurred). + + +Overflow can be detected here since the wrapper holdings are non-confidential. In other cases, it may be impossible +to infer total supply overflow synchronously. This function may revert even if the [`ERC7984.confidentialTotalSupply`](#ERC7984-confidentialTotalSupply--) did +not overflow. + + +
+
+ + + +
+
+

_update(address from, address to, euint64 amount) โ†’ euint64

+
+

internal

+# +
+
+
@@ -1001,7 +1129,7 @@ Fills an unwrap request for a given cipher-text `burntAmount` with the `cleartex
-

_unwrap(address from, address to, euint64 amount)

+

_unwrap(address from, address to, euint64 amount) โ†’ bytes32

internal

# @@ -1009,6 +1137,8 @@ Fills an unwrap request for a given cipher-text `burntAmount` with the `cleartex
+Internal logic for handling the creation of unwrap requests. Returns the unwrap request id. +
@@ -1043,50 +1173,34 @@ ERC-20 token.
-Returns the maximum number that will be used for [`IERC7984.decimals`](/confidential-contracts/api/interfaces#IERC7984-decimals--) by the wrapper. +Returns the maximum number that will be used for [`ERC7984.decimals`](#ERC7984-decimals--) by the wrapper.
- +
-

UnwrapRequested(address indexed receiver, euint64 amount)

+

InvalidUnwrapRequest(bytes32 unwrapRequestId)

-

event

-# -
-
- -
- -
-
- - -
-
-

UnwrapFinalized(address indexed receiver, euint64 encryptedAmount, uint64 cleartextAmount)

-
-

event

-# +

error

+#
-
- +
-

InvalidUnwrapRequest(euint64 amount)

+

ERC7984TotalSupplyOverflow()

error

-# +#
@@ -1098,24 +1212,23 @@ Returns the maximum number that will be used for [`IERC7984.decimals`](/confiden
-## `ERC7984Freezable` +## `ERC7984Freezable` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984Freezable.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/extensions/ERC7984Freezable.sol"; ``` Extension of [`ERC7984`](#ERC7984) that implements a confidential -freezing mechanism that can be managed by an authorized account with -[`IERC7984Rwa.setConfidentialFrozen`](/confidential-contracts/api/interfaces#IERC7984Rwa-setConfidentialFrozen-address-euint64-) functions. +freezing mechanism that can be managed by calling the internal function +[`ERC7984Freezable._setConfidentialFrozen`](#ERC7984Freezable-_setConfidentialFrozen-address-euint64-) by an inheriting contract. -The freezing mechanism provides the guarantee to the contract owner -(e.g. a DAO or a well-configured multisig) that a specific confidential +The freezing mechanism provides the guarantee that a specific confidential amount of tokens held by an account won't be transferable until those tokens are unfrozen. @@ -1129,7 +1242,9 @@ Inspired by https://github.com/OpenZeppelin/openzeppelin-community-contracts/blo - [_confidentialAvailable(account)](#ERC7984Freezable-_confidentialAvailable-address-) - [_setConfidentialFrozen(account, encryptedAmount)](#ERC7984Freezable-_setConfidentialFrozen-address-euint64-) - [_update(from, to, encryptedAmount)](#ERC7984Freezable-_update-address-address-euint64-) -#### ERC7984 [!toc] +
+ERC7984 + - [supportsInterface(interfaceId)](#ERC7984-supportsInterface-bytes4-) - [name()](#ERC7984-name--) - [symbol()](#ERC7984-symbol--) @@ -1154,9 +1269,8 @@ Inspired by https://github.com/OpenZeppelin/openzeppelin-community-contracts/blo - [_burn(from, amount)](#ERC7984-_burn-address-euint64-) - [_transfer(from, to, amount)](#ERC7984-_transfer-address-address-euint64-) - [_transferAndCall(from, to, amount, data)](#ERC7984-_transferAndCall-address-address-euint64-bytes-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -1164,31 +1278,37 @@ Inspired by https://github.com/OpenZeppelin/openzeppelin-community-contracts/blo

Events

- [TokensFrozen(account, encryptedAmount)](#ERC7984Freezable-TokensFrozen-address-euint64-) -#### ERC7984 [!toc] +
+ERC7984 + - [AmountDiscloseRequested(encryptedAmount, requester)](#ERC7984-AmountDiscloseRequested-euint64-address-) -#### ERC165 [!toc] -#### IERC7984 [!toc] + +
+
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] + +

Errors

-#### ERC7984 [!toc] +
+ERC7984 + - [ERC7984InvalidReceiver(receiver)](#ERC7984-ERC7984InvalidReceiver-address-) - [ERC7984InvalidSender(sender)](#ERC7984-ERC7984InvalidSender-address-) - [ERC7984UnauthorizedSpender(holder, spender)](#ERC7984-ERC7984UnauthorizedSpender-address-address-) - [ERC7984ZeroBalance(holder)](#ERC7984-ERC7984ZeroBalance-address-) - [ERC7984UnauthorizedUseOfEncryptedAmount(amount, user)](#ERC7984-ERC7984UnauthorizedUseOfEncryptedAmount-euint64-address-) - [ERC7984UnauthorizedCaller(caller)](#ERC7984-ERC7984UnauthorizedCaller-address-) -- [ERC7984InvalidGatewayRequest(requestId)](#ERC7984-ERC7984InvalidGatewayRequest-uint256-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -1305,20 +1425,20 @@ Emitted when a confidential amount of token is frozen for an account
-## `ERC7984ObserverAccess` +## `ERC7984ObserverAccess` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984ObserverAccess.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/extensions/ERC7984ObserverAccess.sol"; ``` -Extension of [`ERC7984`](#ERC7984) that allows each account to add a observer who is given -permanent ACL access to its transfer and balance amounts. A observer can be added or removed at any point in time. +Extension of [`ERC7984`](#ERC7984) that allows each account to add an observer who is given +permanent ACL access to its transfer and balance amounts. An observer can be added or removed at any point in time.

Functions

@@ -1326,7 +1446,9 @@ permanent ACL access to its transfer and balance amounts. A observer can be adde - [setObserver(account, newObserver)](#ERC7984ObserverAccess-setObserver-address-address-) - [observer(account)](#ERC7984ObserverAccess-observer-address-) - [_update(from, to, amount)](#ERC7984ObserverAccess-_update-address-address-euint64-) -#### ERC7984 [!toc] +
+ERC7984 + - [supportsInterface(interfaceId)](#ERC7984-supportsInterface-bytes4-) - [name()](#ERC7984-name--) - [symbol()](#ERC7984-symbol--) @@ -1351,9 +1473,8 @@ permanent ACL access to its transfer and balance amounts. A observer can be adde - [_burn(from, amount)](#ERC7984-_burn-address-euint64-) - [_transfer(from, to, amount)](#ERC7984-_transfer-address-address-euint64-) - [_transferAndCall(from, to, amount, data)](#ERC7984-_transferAndCall-address-address-euint64-bytes-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -1361,14 +1482,20 @@ permanent ACL access to its transfer and balance amounts. A observer can be adde

Events

- [ERC7984ObserverAccessObserverSet(account, oldObserver, newObserver)](#ERC7984ObserverAccess-ERC7984ObserverAccessObserverSet-address-address-address-) -#### ERC7984 [!toc] +
+ERC7984 + - [AmountDiscloseRequested(encryptedAmount, requester)](#ERC7984-AmountDiscloseRequested-euint64-address-) -#### ERC165 [!toc] -#### IERC7984 [!toc] + +
+
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] + +
@@ -1376,17 +1503,17 @@ permanent ACL access to its transfer and balance amounts. A observer can be adde

Errors

- [Unauthorized()](#ERC7984ObserverAccess-Unauthorized--) -#### ERC7984 [!toc] +
+ERC7984 + - [ERC7984InvalidReceiver(receiver)](#ERC7984-ERC7984InvalidReceiver-address-) - [ERC7984InvalidSender(sender)](#ERC7984-ERC7984InvalidSender-address-) - [ERC7984UnauthorizedSpender(holder, spender)](#ERC7984-ERC7984UnauthorizedSpender-address-address-) - [ERC7984ZeroBalance(holder)](#ERC7984-ERC7984ZeroBalance-address-) - [ERC7984UnauthorizedUseOfEncryptedAmount(amount, user)](#ERC7984-ERC7984UnauthorizedUseOfEncryptedAmount-euint64-address-) - [ERC7984UnauthorizedCaller(caller)](#ERC7984-ERC7984UnauthorizedCaller-address-) -- [ERC7984InvalidGatewayRequest(requestId)](#ERC7984-ERC7984InvalidGatewayRequest-uint256-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -1479,16 +1606,16 @@ Thrown when an account tries to set a `newObserver` for a given `account` withou
-## `ERC7984Omnibus` +## `ERC7984Omnibus` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984Omnibus.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/extensions/ERC7984Omnibus.sol"; ``` Extension of [`ERC7984`](#ERC7984) that emits additional events for omnibus transfers. @@ -1512,7 +1639,9 @@ balances externally. - [confidentialTransferFromAndCallOmnibus(omnibusFrom, omnibusTo, sender, recipient, amount, data)](#ERC7984Omnibus-confidentialTransferFromAndCallOmnibus-address-address-eaddress-eaddress-euint64-bytes-) - [_confidentialTransferFromOmnibus(omnibusFrom, omnibusTo, sender, recipient, amount)](#ERC7984Omnibus-_confidentialTransferFromOmnibus-address-address-eaddress-eaddress-euint64-) - [_confidentialTransferFromAndCallOmnibus(omnibusFrom, omnibusTo, sender, recipient, amount, data)](#ERC7984Omnibus-_confidentialTransferFromAndCallOmnibus-address-address-eaddress-eaddress-euint64-bytes-) -#### ERC7984 [!toc] +
+ERC7984 + - [supportsInterface(interfaceId)](#ERC7984-supportsInterface-bytes4-) - [name()](#ERC7984-name--) - [symbol()](#ERC7984-symbol--) @@ -1538,9 +1667,8 @@ balances externally. - [_transfer(from, to, amount)](#ERC7984-_transfer-address-address-euint64-) - [_transferAndCall(from, to, amount, data)](#ERC7984-_transferAndCall-address-address-euint64-bytes-) - [_update(from, to, amount)](#ERC7984-_update-address-address-euint64-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -1548,14 +1676,20 @@ balances externally.

Events

- [OmnibusConfidentialTransfer(omnibusFrom, omnibusTo, sender, recipient, amount)](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) -#### ERC7984 [!toc] +
+ERC7984 + - [AmountDiscloseRequested(encryptedAmount, requester)](#ERC7984-AmountDiscloseRequested-euint64-address-) -#### ERC165 [!toc] -#### IERC7984 [!toc] + +
+
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] + +
@@ -1563,17 +1697,17 @@ balances externally.

Errors

- [ERC7984UnauthorizedUseOfEncryptedAddress(addr, user)](#ERC7984Omnibus-ERC7984UnauthorizedUseOfEncryptedAddress-eaddress-address-) -#### ERC7984 [!toc] +
+ERC7984 + - [ERC7984InvalidReceiver(receiver)](#ERC7984-ERC7984InvalidReceiver-address-) - [ERC7984InvalidSender(sender)](#ERC7984-ERC7984InvalidSender-address-) - [ERC7984UnauthorizedSpender(holder, spender)](#ERC7984-ERC7984UnauthorizedSpender-address-address-) - [ERC7984ZeroBalance(holder)](#ERC7984-ERC7984ZeroBalance-address-) - [ERC7984UnauthorizedUseOfEncryptedAmount(amount, user)](#ERC7984-ERC7984UnauthorizedUseOfEncryptedAmount-euint64-address-) - [ERC7984UnauthorizedCaller(caller)](#ERC7984-ERC7984UnauthorizedCaller-address-) -- [ERC7984InvalidGatewayRequest(requestId)](#ERC7984-ERC7984InvalidGatewayRequest-uint256-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -1589,7 +1723,7 @@ balances externally.
-Wraps the interfaces#IERC7984-confidentialTransfer-address-externalEuint64-bytes- function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event. +Wraps the `confidentialTransfer-address-externalEuint64-bytes` function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event.
@@ -1606,7 +1740,7 @@ Wraps the interfaces#IERC7984-confidentialTransfer-address-externalEuint64-bytes
-Wraps the interfaces#IERC7984-confidentialTransfer-address-euint64- function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event. +Wraps the `confidentialTransfer-address-euint64` function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event.
@@ -1623,7 +1757,7 @@ Wraps the interfaces#IERC7984-confidentialTransfer-address-euint64- function and
-Wraps the interfaces#IERC7984-confidentialTransferFrom-address-address-externalEuint64-bytes- function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event. +Wraps the `confidentialTransferFrom-address-address-externalEuint64-bytes` function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event.
@@ -1640,7 +1774,7 @@ Wraps the interfaces#IERC7984-confidentialTransferFrom-address-address-externalE
-Wraps the interfaces#IERC7984-confidentialTransferFrom-address-address-euint64- function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event. +Wraps the `confidentialTransferFrom-address-address-euint64` function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event.
@@ -1657,7 +1791,7 @@ Wraps the interfaces#IERC7984-confidentialTransferFrom-address-address-euint64-
-Wraps the interfaces#IERC7984-confidentialTransferAndCall-address-externalEuint64-bytes-bytes- function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event. +Wraps the `confidentialTransferAndCall-address-externalEuint64-bytes-bytes` function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event.
@@ -1674,7 +1808,7 @@ Wraps the interfaces#IERC7984-confidentialTransferAndCall-address-externalEuint6
-Wraps the interfaces#IERC7984-confidentialTransferAndCall-address-euint64-bytes- function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event. +Wraps the `confidentialTransferAndCall-address-euint64-bytes` function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event.
@@ -1691,7 +1825,7 @@ Wraps the interfaces#IERC7984-confidentialTransferAndCall-address-euint64-bytes-
-Wraps the interfaces#IERC7984-confidentialTransferFromAndCall-address-address-externalEuint64-bytes-bytes- function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event. +Wraps the `confidentialTransferFromAndCall-address-address-externalEuint64-bytes-bytes` function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event.
@@ -1708,7 +1842,7 @@ Wraps the interfaces#IERC7984-confidentialTransferFromAndCall-address-address-ex
-Wraps the interfaces#IERC7984-confidentialTransferFromAndCall-address-address-euint64-bytes- function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event. +Wraps the `confidentialTransferFromAndCall-address-address-euint64-bytes` function and emits the [`ERC7984Omnibus.OmnibusConfidentialTransfer`](#ERC7984Omnibus-OmnibusConfidentialTransfer-address-address-eaddress-eaddress-euint64-) event.
@@ -1796,31 +1930,31 @@ Try using the equivalent transfer function with an input proof.
-## `ERC7984Restricted` +## `ERC7984Restricted` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984Restricted.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/extensions/ERC7984Restricted.sol"; ``` Extension of [`ERC7984`](#ERC7984) that implements user account transfer restrictions through the -[`IERC7984Rwa.isUserAllowed`](/confidential-contracts/api/interfaces#IERC7984Rwa-isUserAllowed-address-) function. Inspired by +[`ERC7984Restricted.canTransact`](#ERC7984Restricted-canTransact-address-) function. Inspired by https://github.com/OpenZeppelin/openzeppelin-community-contracts/blob/master/contracts/token/ERC20/extensions/ERC20Restricted.sol. -By default, each account has no explicit restriction. The [`IERC7984Rwa.isUserAllowed`](/confidential-contracts/api/interfaces#IERC7984Rwa-isUserAllowed-address-) function acts as -a blocklist. Developers can override [`IERC7984Rwa.isUserAllowed`](/confidential-contracts/api/interfaces#IERC7984Rwa-isUserAllowed-address-) to check that `restriction == ALLOWED` +By default, each account has no explicit restriction. The [`ERC7984Restricted.canTransact`](#ERC7984Restricted-canTransact-address-) function acts as +a blocklist. Developers can override [`ERC7984Restricted.canTransact`](#ERC7984Restricted-canTransact-address-) to check that `restriction == ALLOWED` to implement an allowlist.

Functions

- [getRestriction(account)](#ERC7984Restricted-getRestriction-address-) -- [isUserAllowed(account)](#ERC7984Restricted-isUserAllowed-address-) +- [canTransact(account)](#ERC7984Restricted-canTransact-address-) - [_update(from, to, value)](#ERC7984Restricted-_update-address-address-euint64-) - [_setRestriction(account, restriction)](#ERC7984Restricted-_setRestriction-address-enum-ERC7984Restricted-Restriction-) - [_blockUser(account)](#ERC7984Restricted-_blockUser-address-) @@ -1829,7 +1963,9 @@ to implement an allowlist. - [_checkRestriction(account)](#ERC7984Restricted-_checkRestriction-address-) - [_checkSenderRestriction(account)](#ERC7984Restricted-_checkSenderRestriction-address-) - [_checkRecipientRestriction(account)](#ERC7984Restricted-_checkRecipientRestriction-address-) -#### ERC7984 [!toc] +
+ERC7984 + - [supportsInterface(interfaceId)](#ERC7984-supportsInterface-bytes4-) - [name()](#ERC7984-name--) - [symbol()](#ERC7984-symbol--) @@ -1854,9 +1990,8 @@ to implement an allowlist. - [_burn(from, amount)](#ERC7984-_burn-address-euint64-) - [_transfer(from, to, amount)](#ERC7984-_transfer-address-address-euint64-) - [_transferAndCall(from, to, amount, data)](#ERC7984-_transferAndCall-address-address-euint64-bytes-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -1864,14 +1999,20 @@ to implement an allowlist.

Events

- [UserRestrictionUpdated(account, restriction)](#ERC7984Restricted-UserRestrictionUpdated-address-enum-ERC7984Restricted-Restriction-) -#### ERC7984 [!toc] +
+ERC7984 + - [AmountDiscloseRequested(encryptedAmount, requester)](#ERC7984-AmountDiscloseRequested-euint64-address-) -#### ERC165 [!toc] -#### IERC7984 [!toc] + +
+
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] + +
@@ -1879,17 +2020,17 @@ to implement an allowlist.

Errors

- [UserRestricted(account)](#ERC7984Restricted-UserRestricted-address-) -#### ERC7984 [!toc] +
+ERC7984 + - [ERC7984InvalidReceiver(receiver)](#ERC7984-ERC7984InvalidReceiver-address-) - [ERC7984InvalidSender(sender)](#ERC7984-ERC7984InvalidSender-address-) - [ERC7984UnauthorizedSpender(holder, spender)](#ERC7984-ERC7984UnauthorizedSpender-address-address-) - [ERC7984ZeroBalance(holder)](#ERC7984-ERC7984ZeroBalance-address-) - [ERC7984UnauthorizedUseOfEncryptedAmount(amount, user)](#ERC7984-ERC7984UnauthorizedUseOfEncryptedAmount-euint64-address-) - [ERC7984UnauthorizedCaller(caller)](#ERC7984-ERC7984UnauthorizedCaller-address-) -- [ERC7984InvalidGatewayRequest(requestId)](#ERC7984-ERC7984InvalidGatewayRequest-uint256-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -1910,14 +2051,14 @@ Returns the restriction of a user account. - +
-

isUserAllowed(address account) โ†’ bool

+

canTransact(address account) โ†’ bool

public

-# +#
@@ -1945,8 +2086,8 @@ See [`ERC7984._update`](#ERC7984-_update-address-address-euint64-). Enforces tra Requirements: -* `from` must be allowed to transfer tokens (see [`IERC7984Rwa.isUserAllowed`](/confidential-contracts/api/interfaces#IERC7984Rwa-isUserAllowed-address-)). -* `to` must be allowed to receive tokens (see [`IERC7984Rwa.isUserAllowed`](/confidential-contracts/api/interfaces#IERC7984Rwa-isUserAllowed-address-)). +* `from` must be allowed to transfer tokens (see [`ERC7984Restricted.canTransact`](#ERC7984Restricted-canTransact-address-)). +* `to` must be allowed to receive tokens (see [`ERC7984Restricted.canTransact`](#ERC7984Restricted-canTransact-address-)). The default restriction behavior can be changed (for a pass-through for instance) by overriding [`ERC7984Restricted._checkSenderRestriction`](#ERC7984Restricted-_checkSenderRestriction-address-) and/or [`ERC7984Restricted._checkRecipientRestriction`](#ERC7984Restricted-_checkRecipientRestriction-address-). @@ -2114,16 +2255,16 @@ The operation failed because the user account is restricted.
-## `ERC7984Rwa` +## `ERC7984Rwa` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984Rwa.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/extensions/ERC7984Rwa.sol"; ``` Extension of [`ERC7984`](#ERC7984) that supports confidential Real World Assets (RWAs). @@ -2161,12 +2302,14 @@ This interface provides compliance checks, transfer controls and enforcement act - [confidentialAvailable(account)](#ERC7984Rwa-confidentialAvailable-address-) - [confidentialFrozen(account)](#ERC7984Rwa-confidentialFrozen-address-) - [paused()](#ERC7984Rwa-paused--) -- [isUserAllowed(account)](#ERC7984Rwa-isUserAllowed-address-) +- [canTransact(account)](#ERC7984Rwa-canTransact-address-) - [_update(from, to, encryptedAmount)](#ERC7984Rwa-_update-address-address-euint64-) - [_forceUpdate(from, to, encryptedAmount)](#ERC7984Rwa-_forceUpdate-address-address-euint64-) - [_checkSenderRestriction(account)](#ERC7984Rwa-_checkSenderRestriction-address-) - [AGENT_ROLE()](#ERC7984Rwa-AGENT_ROLE-bytes32) -#### AccessControl [!toc] +
+AccessControl + - [hasRole(role, account)](#AccessControl-hasRole-bytes32-address-) - [_checkRole(role)](#AccessControl-_checkRole-bytes32-) - [_checkRole(role, account)](#AccessControl-_checkRole-bytes32-address-) @@ -2178,14 +2321,26 @@ This interface provides compliance checks, transfer controls and enforcement act - [_grantRole(role, account)](#AccessControl-_grantRole-bytes32-address-) - [_revokeRole(role, account)](#AccessControl-_revokeRole-bytes32-address-) - [DEFAULT_ADMIN_ROLE()](#AccessControl-DEFAULT_ADMIN_ROLE-bytes32) -#### Multicall [!toc] + +
+
+Multicall + - [multicall(data)](#Multicall-multicall-bytes---) -#### Pausable [!toc] + +
+
+Pausable + - [_requireNotPaused()](#Pausable-_requireNotPaused--) - [_requirePaused()](#Pausable-_requirePaused--) - [_pause()](#Pausable-_pause--) - [_unpause()](#Pausable-_unpause--) -#### ERC7984Restricted [!toc] + +
+
+ERC7984Restricted + - [getRestriction(account)](#ERC7984Restricted-getRestriction-address-) - [_setRestriction(account, restriction)](#ERC7984Restricted-_setRestriction-address-enum-ERC7984Restricted-Restriction-) - [_blockUser(account)](#ERC7984Restricted-_blockUser-address-) @@ -2193,10 +2348,18 @@ This interface provides compliance checks, transfer controls and enforcement act - [_resetUser(account)](#ERC7984Restricted-_resetUser-address-) - [_checkRestriction(account)](#ERC7984Restricted-_checkRestriction-address-) - [_checkRecipientRestriction(account)](#ERC7984Restricted-_checkRecipientRestriction-address-) -#### ERC7984Freezable [!toc] + +
+
+ERC7984Freezable + - [_confidentialAvailable(account)](#ERC7984Freezable-_confidentialAvailable-address-) - [_setConfidentialFrozen(account, encryptedAmount)](#ERC7984Freezable-_setConfidentialFrozen-address-euint64-) -#### ERC7984 [!toc] + +
+
+ERC7984 + - [name()](#ERC7984-name--) - [symbol()](#ERC7984-symbol--) - [decimals()](#ERC7984-decimals--) @@ -2220,68 +2383,92 @@ This interface provides compliance checks, transfer controls and enforcement act - [_burn(from, amount)](#ERC7984-_burn-address-euint64-) - [_transfer(from, to, amount)](#ERC7984-_transfer-address-address-euint64-) - [_transferAndCall(from, to, amount, data)](#ERC7984-_transferAndCall-address-address-euint64-bytes-) -#### ERC165 [!toc] -#### IERC7984Rwa [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] -#### IAccessControl [!toc] + +

Events

-#### AccessControl [!toc] -#### Multicall [!toc] -#### Pausable [!toc] +
+Pausable + - [Paused(account)](#Pausable-Paused-address-) - [Unpaused(account)](#Pausable-Unpaused-address-) -#### ERC7984Restricted [!toc] + +
+
+ERC7984Restricted + - [UserRestrictionUpdated(account, restriction)](#ERC7984Restricted-UserRestrictionUpdated-address-enum-ERC7984Restricted-Restriction-) -#### ERC7984Freezable [!toc] + +
+
+ERC7984Freezable + - [TokensFrozen(account, encryptedAmount)](#ERC7984Freezable-TokensFrozen-address-euint64-) -#### ERC7984 [!toc] + +
+
+ERC7984 + - [AmountDiscloseRequested(encryptedAmount, requester)](#ERC7984-AmountDiscloseRequested-euint64-address-) -#### ERC165 [!toc] -#### IERC7984Rwa [!toc] -#### IERC7984 [!toc] + +
+
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] -#### IAccessControl [!toc] + +
+
+IAccessControl + - [RoleAdminChanged(role, previousAdminRole, newAdminRole)](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) - [RoleGranted(role, account, sender)](#IAccessControl-RoleGranted-bytes32-address-address-) - [RoleRevoked(role, account, sender)](#IAccessControl-RoleRevoked-bytes32-address-address-) + +

Errors

-#### AccessControl [!toc] -#### Multicall [!toc] -#### Pausable [!toc] +
+Pausable + - [EnforcedPause()](#Pausable-EnforcedPause--) - [ExpectedPause()](#Pausable-ExpectedPause--) -#### ERC7984Restricted [!toc] + +
+
+ERC7984Restricted + - [UserRestricted(account)](#ERC7984Restricted-UserRestricted-address-) -#### ERC7984Freezable [!toc] -#### ERC7984 [!toc] + +
+
+ERC7984 + - [ERC7984InvalidReceiver(receiver)](#ERC7984-ERC7984InvalidReceiver-address-) - [ERC7984InvalidSender(sender)](#ERC7984-ERC7984InvalidSender-address-) - [ERC7984UnauthorizedSpender(holder, spender)](#ERC7984-ERC7984UnauthorizedSpender-address-address-) - [ERC7984ZeroBalance(holder)](#ERC7984-ERC7984ZeroBalance-address-) - [ERC7984UnauthorizedUseOfEncryptedAmount(amount, user)](#ERC7984-ERC7984UnauthorizedUseOfEncryptedAmount-euint64-address-) - [ERC7984UnauthorizedCaller(caller)](#ERC7984-ERC7984UnauthorizedCaller-address-) -- [ERC7984InvalidGatewayRequest(requestId)](#ERC7984-ERC7984InvalidGatewayRequest-uint256-) -#### ERC165 [!toc] -#### IERC7984Rwa [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] -#### IAccessControl [!toc] + +
+
+IAccessControl + - [AccessControlUnauthorizedAccount(account, neededRole)](#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-) - [AccessControlBadConfirmation()](#IAccessControl-AccessControlBadConfirmation--) + +
@@ -2601,7 +2788,7 @@ Burns confidential amount of tokens from account.
-Variant of interfaces#IERC7984Rwa-forceConfidentialTransferFrom-address-address-euint64- with an input proof. +Variant of `forceConfidentialTransferFrom-address-address-euint64` with an input proof.
@@ -2676,14 +2863,14 @@ Returns true if the contract is paused, and false otherwise. - +
-

isUserAllowed(address account) โ†’ bool

+

canTransact(address account) โ†’ bool

public

-# +#
@@ -2741,7 +2928,7 @@ Internal function which forces transfer of confidential amount of tokens from ac
-Bypasses the `from` restriction check when performing a [`IERC7984Rwa.forceConfidentialTransferFrom`](/confidential-contracts/api/interfaces#IERC7984Rwa-forceConfidentialTransferFrom-address-address-euint64-). +Bypasses the `from` restriction check when performing a [`ERC7984Rwa.forceConfidentialTransferFrom`](#ERC7984Rwa-forceConfidentialTransferFrom-address-address-euint64-).
@@ -2760,12 +2947,12 @@ Bypasses the `from` restriction check when performing a [`IERC7984Rwa.forceConfi Accounts granted the agent role have the following permissioned abilities: -- Mint/Burn to/from a given address (does not require permission) -- Force transfer from a given address (does not require permission) - - Bypasses pause and restriction checks (not frozen) -- Pause/Unpause the contract -- Block/Unblock a given account -- Set frozen amount of tokens for a given account. +* Mint/Burn to/from a given address (does not require permission) +* Force transfer from a given address (does not require permission) +** Bypasses pause and restriction checks (not frozen) +* Pause/Unpause the contract +* Block/Unblock a given account +* Set frozen amount of tokens for a given account. @@ -2774,22 +2961,22 @@ Accounts granted the agent role have the following permissioned abilities:
-## `ERC7984Votes` +## `ERC7984Votes` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984Votes.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/extensions/ERC7984Votes.sol"; ``` Extension of [`ERC7984`](#ERC7984) supporting confidential votes tracking and delegation. The amount of confidential voting units an account has is equal to the balance of -that account. Voing power is taken into account when an account delegates votes to itself or to another +that account. Voting power is taken into account when an account delegates votes to itself or to another account.
@@ -2798,7 +2985,9 @@ account. - [confidentialTotalSupply()](#ERC7984Votes-confidentialTotalSupply--) - [_update(from, to, amount)](#ERC7984Votes-_update-address-address-euint64-) - [_getVotingUnits(account)](#ERC7984Votes-_getVotingUnits-address-) -#### VotesConfidential [!toc] +
+VotesConfidential + - [clock()](#VotesConfidential-clock--) - [CLOCK_MODE()](#VotesConfidential-CLOCK_MODE--) - [getVotes(account)](#VotesConfidential-getVotes-address-) @@ -2811,22 +3000,36 @@ account. - [_transferVotingUnits(from, to, amount)](#VotesConfidential-_transferVotingUnits-address-address-euint64-) - [_moveDelegateVotes(from, to, amount)](#VotesConfidential-_moveDelegateVotes-address-address-euint64-) - [_validateTimepoint(timepoint)](#VotesConfidential-_validateTimepoint-uint256-) -#### HandleAccessManager [!toc] + +
+
+HandleAccessManager + - [getHandleAllowance(handle, account, persistent)](#HandleAccessManager-getHandleAllowance-bytes32-address-bool-) -- [_validateHandleAllowance(handle)](#HandleAccessManager-_validateHandleAllowance-bytes32-) -#### IERC6372 [!toc] -#### EIP712 [!toc] +- [_validateHandleAllowance()](#HandleAccessManager-_validateHandleAllowance-bytes32-) + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### ERC7984 [!toc] + +
+
+ERC7984 + - [supportsInterface(interfaceId)](#ERC7984-supportsInterface-bytes4-) - [name()](#ERC7984-name--) - [symbol()](#ERC7984-symbol--) @@ -2850,59 +3053,78 @@ account. - [_burn(from, amount)](#ERC7984-_burn-address-euint64-) - [_transfer(from, to, amount)](#ERC7984-_transfer-address-address-euint64-) - [_transferAndCall(from, to, amount, data)](#ERC7984-_transferAndCall-address-address-euint64-bytes-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +

Events

-#### VotesConfidential [!toc] +
+VotesConfidential + - [DelegateVotesChanged(delegate, previousVotes, newVotes)](#VotesConfidential-DelegateVotesChanged-address-euint64-euint64-) - [DelegateChanged(delegator, fromDelegate, toDelegate)](#VotesConfidential-DelegateChanged-address-address-address-) -#### HandleAccessManager [!toc] -#### IERC6372 [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### Nonces [!toc] -#### ERC7984 [!toc] + +
+
+ERC7984 + - [AmountDiscloseRequested(encryptedAmount, requester)](#ERC7984-AmountDiscloseRequested-euint64-address-) -#### ERC165 [!toc] -#### IERC7984 [!toc] + +
+
+IERC7984 + - [OperatorSet(holder, operator, until)](#IERC7984-OperatorSet-address-address-uint48-) - [ConfidentialTransfer(from, to, amount)](#IERC7984-ConfidentialTransfer-address-address-euint64-) - [AmountDisclosed(encryptedAmount, amount)](#IERC7984-AmountDisclosed-euint64-uint64-) -#### IERC165 [!toc] + +

Errors

-#### VotesConfidential [!toc] +
+VotesConfidential + - [VotesExpiredSignature(expiry)](#VotesConfidential-VotesExpiredSignature-uint256-) - [ERC6372InconsistentClock()](#VotesConfidential-ERC6372InconsistentClock--) - [ERC5805FutureLookup(timepoint, clock)](#VotesConfidential-ERC5805FutureLookup-uint256-uint48-) -#### HandleAccessManager [!toc] -#### IERC6372 [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### Nonces [!toc] + +
+
+HandleAccessManager + +- [HandleAccessManagerNotAllowed(handle, account)](#HandleAccessManager-HandleAccessManagerNotAllowed-bytes32-address-) + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### ERC7984 [!toc] + +
+
+ERC7984 + - [ERC7984InvalidReceiver(receiver)](#ERC7984-ERC7984InvalidReceiver-address-) - [ERC7984InvalidSender(sender)](#ERC7984-ERC7984InvalidSender-address-) - [ERC7984UnauthorizedSpender(holder, spender)](#ERC7984-ERC7984UnauthorizedSpender-address-address-) - [ERC7984ZeroBalance(holder)](#ERC7984-ERC7984ZeroBalance-address-) - [ERC7984UnauthorizedUseOfEncryptedAmount(amount, user)](#ERC7984-ERC7984UnauthorizedUseOfEncryptedAmount-euint64-address-) - [ERC7984UnauthorizedCaller(caller)](#ERC7984-ERC7984UnauthorizedCaller-address-) -- [ERC7984InvalidGatewayRequest(requestId)](#ERC7984-ERC7984InvalidGatewayRequest-uint256-) -#### ERC165 [!toc] -#### IERC7984 [!toc] -#### IERC165 [!toc] + +
@@ -2957,16 +3179,16 @@ Returns the confidential total supply of the token.
-## `ERC7984Utils` +## `ERC7984Utils` - +
```solidity -import "@openzeppelin/confidential-contracts/token/ERC7984/utils/ERC7984Utils.sol"; +import "@openzeppelin/confidential-contracts/contracts/token/ERC7984/utils/ERC7984Utils.sol"; ``` Library that provides common [`ERC7984`](#ERC7984) utility functions. @@ -3001,3 +3223,4 @@ should try to refund the `from` address. + diff --git a/content/confidential-contracts/api/utils.mdx b/content/confidential-contracts/api/utils.mdx index 2a378b76..0e491fcc 100644 --- a/content/confidential-contracts/api/utils.mdx +++ b/content/confidential-contracts/api/utils.mdx @@ -24,16 +24,16 @@ Miscellaneous contracts and libraries containing utility functions you can use t
-## `FHESafeMath` +## `FHESafeMath` - +
```solidity -import "@openzeppelin/confidential-contracts/utils/FHESafeMath.sol"; +import "@openzeppelin/confidential-contracts/contracts/utils/FHESafeMath.sol"; ``` Library providing safe arithmetic operations for encrypted values @@ -41,7 +41,7 @@ to handle potential overflows in FHE operations. An uninitialized `euint64` value (equivalent to euint64.wrap(bytes32(0))) is evaluated as 0. -This library will may return an uninitialized value if all inputs are uninitialized. +This library may return an uninitialized value if all inputs are uninitialized.
@@ -132,23 +132,30 @@ will be `a - b`. Otherwise, `success` will be false, and `res` will be 0.
-## `HandleAccessManager` +## `HandleAccessManager` - +
```solidity -import "@openzeppelin/confidential-contracts/utils/HandleAccessManager.sol"; +import "@openzeppelin/confidential-contracts/contracts/utils/HandleAccessManager.sol"; ```

Functions

- [getHandleAllowance(handle, account, persistent)](#HandleAccessManager-getHandleAllowance-bytes32-address-bool-) -- [_validateHandleAllowance(handle)](#HandleAccessManager-_validateHandleAllowance-bytes32-) +- [_validateHandleAllowance()](#HandleAccessManager-_validateHandleAllowance-bytes32-) +
+
+ +
+

Errors

+
+- [HandleAccessManagerNotAllowed(handle, account)](#HandleAccessManager-HandleAccessManagerNotAllowed-bytes32-address-)
@@ -168,8 +175,7 @@ Get handle access for the given handle `handle`. Access will be given to the account `account` with the given persistence flag. -This function call is gated by `msg.sender` and validated by the -[`HandleAccessManager._validateHandleAllowance`](#HandleAccessManager-_validateHandleAllowance-bytes32-) function. +This function call is validated by [`HandleAccessManager._validateHandleAllowance`](#HandleAccessManager-_validateHandleAllowance-bytes32-).
@@ -179,7 +185,7 @@ This function call is gated by `msg.sender` and validated by the
-

_validateHandleAllowance(bytes32 handle)

+

_validateHandleAllowance(bytes32) โ†’ bool

internal

# @@ -187,26 +193,41 @@ This function call is gated by `msg.sender` and validated by the
-Unimplemented function that must revert if the message sender is not allowed to call +Validation function that must return true if the message sender is allowed to call [`HandleAccessManager.getHandleAllowance`](#HandleAccessManager-getHandleAllowance-bytes32-address-bool-) for the given handle.
+ + +
+
+

HandleAccessManagerNotAllowed(bytes32 handle, address account)

+
+

error

+# +
+
+
+ +
+
+
-## `CheckpointsConfidential` +## `CheckpointsConfidential` - +
```solidity -import "@openzeppelin/confidential-contracts/utils/structs/CheckpointsConfidential.sol"; +import "@openzeppelin/confidential-contracts/contracts/utils/structs/CheckpointsConfidential.sol"; ``` This library defines the `Trace*` struct, for checkpointing values as they change at different points in @@ -541,694 +562,3 @@ Returns checkpoint at given position.
- - -
- -## `Checkpoints` - - - - - -
- -```solidity -import "@openzeppelin/confidential-contracts/utils/structs/temporary-Checkpoints.sol"; -``` - -This library defines the `Trace*` struct, for checkpointing values as they change at different points in -time, and later looking up past values by block number. See [`VotesConfidential`](/confidential-contracts/api/governance#VotesConfidential) as an example. - -To create a history of checkpoints define a variable type `Checkpoints.Trace*` in your contract, and store a new -checkpoint for the current transaction block using the [`CheckpointsConfidential.push`](#CheckpointsConfidential-push-struct-CheckpointsConfidential-TraceEuint64-uint256-euint64-) function. - -
-

Functions

-
-- [push(self, key, value)](#Checkpoints-push-struct-Checkpoints-Trace256-uint256-uint256-) -- [lowerLookup(self, key)](#Checkpoints-lowerLookup-struct-Checkpoints-Trace256-uint256-) -- [upperLookup(self, key)](#Checkpoints-upperLookup-struct-Checkpoints-Trace256-uint256-) -- [upperLookupRecent(self, key)](#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace256-uint256-) -- [latest(self)](#Checkpoints-latest-struct-Checkpoints-Trace256-) -- [latestCheckpoint(self)](#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace256-) -- [length(self)](#Checkpoints-length-struct-Checkpoints-Trace256-) -- [at(self, pos)](#Checkpoints-at-struct-Checkpoints-Trace256-uint32-) -- [push(self, key, value)](#Checkpoints-push-struct-Checkpoints-Trace224-uint32-uint224-) -- [lowerLookup(self, key)](#Checkpoints-lowerLookup-struct-Checkpoints-Trace224-uint32-) -- [upperLookup(self, key)](#Checkpoints-upperLookup-struct-Checkpoints-Trace224-uint32-) -- [upperLookupRecent(self, key)](#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace224-uint32-) -- [latest(self)](#Checkpoints-latest-struct-Checkpoints-Trace224-) -- [latestCheckpoint(self)](#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace224-) -- [length(self)](#Checkpoints-length-struct-Checkpoints-Trace224-) -- [at(self, pos)](#Checkpoints-at-struct-Checkpoints-Trace224-uint32-) -- [push(self, key, value)](#Checkpoints-push-struct-Checkpoints-Trace208-uint48-uint208-) -- [lowerLookup(self, key)](#Checkpoints-lowerLookup-struct-Checkpoints-Trace208-uint48-) -- [upperLookup(self, key)](#Checkpoints-upperLookup-struct-Checkpoints-Trace208-uint48-) -- [upperLookupRecent(self, key)](#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace208-uint48-) -- [latest(self)](#Checkpoints-latest-struct-Checkpoints-Trace208-) -- [latestCheckpoint(self)](#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace208-) -- [length(self)](#Checkpoints-length-struct-Checkpoints-Trace208-) -- [at(self, pos)](#Checkpoints-at-struct-Checkpoints-Trace208-uint32-) -- [push(self, key, value)](#Checkpoints-push-struct-Checkpoints-Trace160-uint96-uint160-) -- [lowerLookup(self, key)](#Checkpoints-lowerLookup-struct-Checkpoints-Trace160-uint96-) -- [upperLookup(self, key)](#Checkpoints-upperLookup-struct-Checkpoints-Trace160-uint96-) -- [upperLookupRecent(self, key)](#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace160-uint96-) -- [latest(self)](#Checkpoints-latest-struct-Checkpoints-Trace160-) -- [latestCheckpoint(self)](#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace160-) -- [length(self)](#Checkpoints-length-struct-Checkpoints-Trace160-) -- [at(self, pos)](#Checkpoints-at-struct-Checkpoints-Trace160-uint32-) -
-
- -
-

Errors

-
-- [CheckpointUnorderedInsertion()](#Checkpoints-CheckpointUnorderedInsertion--) -
-
- - - -
-
-

push(struct Checkpoints.Trace256 self, uint256 key, uint256 value) โ†’ uint256 oldValue, uint256 newValue

-
-

internal

-# -
-
-
- -Pushes a (`key`, `value`) pair into a Trace256 so that it is stored as the checkpoint. - -Returns previous value and new value. - - -Never accept `key` as a user input, since an arbitrary `type(uint256).max` key set will disable the -library. - - -
-
- - - -
-
-

lowerLookup(struct Checkpoints.Trace256 self, uint256 key) โ†’ uint256

-
-

internal

-# -
-
-
- -Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if -there is none. - -
-
- - - -
-
-

upperLookup(struct Checkpoints.Trace256 self, uint256 key) โ†’ uint256

-
-

internal

-# -
-
-
- -Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero -if there is none. - -
-
- - - -
-
-

upperLookupRecent(struct Checkpoints.Trace256 self, uint256 key) โ†’ uint256

-
-

internal

-# -
-
-
- -Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero -if there is none. - - -This is a variant of [`CheckpointsConfidential.upperLookup`](#CheckpointsConfidential-upperLookup-struct-CheckpointsConfidential-TraceEuint64-uint256-) that is optimized to find "recent" checkpoint (checkpoints with high -keys). - - -
-
- - - -
-
-

latest(struct Checkpoints.Trace256 self) โ†’ uint256

-
-

internal

-# -
-
-
- -Returns the value in the most recent checkpoint, or zero if there are no checkpoints. - -
-
- - - -
-
-

latestCheckpoint(struct Checkpoints.Trace256 self) โ†’ bool exists, uint256 _key, uint256 _value

-
-

internal

-# -
-
-
- -Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value -in the most recent checkpoint. - -
-
- - - -
-
-

length(struct Checkpoints.Trace256 self) โ†’ uint256

-
-

internal

-# -
-
-
- -Returns the number of checkpoints. - -
-
- - - -
-
-

at(struct Checkpoints.Trace256 self, uint32 pos) โ†’ struct Checkpoints.Checkpoint256

-
-

internal

-# -
-
-
- -Returns checkpoint at given position. - -
-
- - - -
-
-

push(struct Checkpoints.Trace224 self, uint32 key, uint224 value) โ†’ uint224 oldValue, uint224 newValue

-
-

internal

-# -
-
-
- -Pushes a (`key`, `value`) pair into a Trace224 so that it is stored as the checkpoint. - -Returns previous value and new value. - - -Never accept `key` as a user input, since an arbitrary `type(uint32).max` key set will disable the -library. - - -
-
- - - -
-
-

lowerLookup(struct Checkpoints.Trace224 self, uint32 key) โ†’ uint224

-
-

internal

-# -
-
-
- -Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if -there is none. - -
-
- - - -
-
-

upperLookup(struct Checkpoints.Trace224 self, uint32 key) โ†’ uint224

-
-

internal

-# -
-
-
- -Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero -if there is none. - -
-
- - - -
-
-

upperLookupRecent(struct Checkpoints.Trace224 self, uint32 key) โ†’ uint224

-
-

internal

-# -
-
-
- -Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero -if there is none. - - -This is a variant of [`CheckpointsConfidential.upperLookup`](#CheckpointsConfidential-upperLookup-struct-CheckpointsConfidential-TraceEuint64-uint256-) that is optimized to find "recent" checkpoint (checkpoints with high -keys). - - -
-
- - - -
-
-

latest(struct Checkpoints.Trace224 self) โ†’ uint224

-
-

internal

-# -
-
-
- -Returns the value in the most recent checkpoint, or zero if there are no checkpoints. - -
-
- - - -
-
-

latestCheckpoint(struct Checkpoints.Trace224 self) โ†’ bool exists, uint32 _key, uint224 _value

-
-

internal

-# -
-
-
- -Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value -in the most recent checkpoint. - -
-
- - - -
-
-

length(struct Checkpoints.Trace224 self) โ†’ uint256

-
-

internal

-# -
-
-
- -Returns the number of checkpoints. - -
-
- - - -
-
-

at(struct Checkpoints.Trace224 self, uint32 pos) โ†’ struct Checkpoints.Checkpoint224

-
-

internal

-# -
-
-
- -Returns checkpoint at given position. - -
-
- - - -
-
-

push(struct Checkpoints.Trace208 self, uint48 key, uint208 value) โ†’ uint208 oldValue, uint208 newValue

-
-

internal

-# -
-
-
- -Pushes a (`key`, `value`) pair into a Trace208 so that it is stored as the checkpoint. - -Returns previous value and new value. - - -Never accept `key` as a user input, since an arbitrary `type(uint48).max` key set will disable the -library. - - -
-
- - - -
-
-

lowerLookup(struct Checkpoints.Trace208 self, uint48 key) โ†’ uint208

-
-

internal

-# -
-
-
- -Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if -there is none. - -
-
- - - -
-
-

upperLookup(struct Checkpoints.Trace208 self, uint48 key) โ†’ uint208

-
-

internal

-# -
-
-
- -Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero -if there is none. - -
-
- - - -
-
-

upperLookupRecent(struct Checkpoints.Trace208 self, uint48 key) โ†’ uint208

-
-

internal

-# -
-
-
- -Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero -if there is none. - - -This is a variant of [`CheckpointsConfidential.upperLookup`](#CheckpointsConfidential-upperLookup-struct-CheckpointsConfidential-TraceEuint64-uint256-) that is optimized to find "recent" checkpoint (checkpoints with high -keys). - - -
-
- - - -
-
-

latest(struct Checkpoints.Trace208 self) โ†’ uint208

-
-

internal

-# -
-
-
- -Returns the value in the most recent checkpoint, or zero if there are no checkpoints. - -
-
- - - -
-
-

latestCheckpoint(struct Checkpoints.Trace208 self) โ†’ bool exists, uint48 _key, uint208 _value

-
-

internal

-# -
-
-
- -Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value -in the most recent checkpoint. - -
-
- - - -
-
-

length(struct Checkpoints.Trace208 self) โ†’ uint256

-
-

internal

-# -
-
-
- -Returns the number of checkpoints. - -
-
- - - -
-
-

at(struct Checkpoints.Trace208 self, uint32 pos) โ†’ struct Checkpoints.Checkpoint208

-
-

internal

-# -
-
-
- -Returns checkpoint at given position. - -
-
- - - -
-
-

push(struct Checkpoints.Trace160 self, uint96 key, uint160 value) โ†’ uint160 oldValue, uint160 newValue

-
-

internal

-# -
-
-
- -Pushes a (`key`, `value`) pair into a Trace160 so that it is stored as the checkpoint. - -Returns previous value and new value. - - -Never accept `key` as a user input, since an arbitrary `type(uint96).max` key set will disable the -library. - - -
-
- - - -
-
-

lowerLookup(struct Checkpoints.Trace160 self, uint96 key) โ†’ uint160

-
-

internal

-# -
-
-
- -Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if -there is none. - -
-
- - - -
-
-

upperLookup(struct Checkpoints.Trace160 self, uint96 key) โ†’ uint160

-
-

internal

-# -
-
-
- -Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero -if there is none. - -
-
- - - -
-
-

upperLookupRecent(struct Checkpoints.Trace160 self, uint96 key) โ†’ uint160

-
-

internal

-# -
-
-
- -Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero -if there is none. - - -This is a variant of [`CheckpointsConfidential.upperLookup`](#CheckpointsConfidential-upperLookup-struct-CheckpointsConfidential-TraceEuint64-uint256-) that is optimized to find "recent" checkpoint (checkpoints with high -keys). - - -
-
- - - -
-
-

latest(struct Checkpoints.Trace160 self) โ†’ uint160

-
-

internal

-# -
-
-
- -Returns the value in the most recent checkpoint, or zero if there are no checkpoints. - -
-
- - - -
-
-

latestCheckpoint(struct Checkpoints.Trace160 self) โ†’ bool exists, uint96 _key, uint160 _value

-
-

internal

-# -
-
-
- -Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value -in the most recent checkpoint. - -
-
- - - -
-
-

length(struct Checkpoints.Trace160 self) โ†’ uint256

-
-

internal

-# -
-
-
- -Returns the number of checkpoints. - -
-
- - - -
-
-

at(struct Checkpoints.Trace160 self, uint32 pos) โ†’ struct Checkpoints.Checkpoint160

-
-

internal

-# -
-
-
- -Returns checkpoint at given position. - -
-
- - - -
-
-

CheckpointUnorderedInsertion()

-
-

error

-# -
-
-
- -A value was attempted to be inserted on a past checkpoint. - -
-
diff --git a/content/contracts/5.x/api/access.mdx b/content/contracts/5.x/api/access.mdx index b2d6fc6a..1a8f9e6a 100644 --- a/content/contracts/5.x/api/access.mdx +++ b/content/contracts/5.x/api/access.mdx @@ -50,7 +50,7 @@ This directory provides ways to restrict who can access the functions of a contr ## `AccessControl` - + @@ -122,32 +122,33 @@ to enforce additional security measures for this role. - [_grantRole(role, account)](#AccessControl-_grantRole-bytes32-address-) - [_revokeRole(role, account)](#AccessControl-_revokeRole-bytes32-address-) - [DEFAULT_ADMIN_ROLE()](#AccessControl-DEFAULT_ADMIN_ROLE-bytes32) -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControl [!toc]

Events

-#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControl [!toc] +
+IAccessControl + - [RoleAdminChanged(role, previousAdminRole, newAdminRole)](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) - [RoleGranted(role, account, sender)](#IAccessControl-RoleGranted-bytes32-address-address-) - [RoleRevoked(role, account, sender)](#IAccessControl-RoleRevoked-bytes32-address-address-) + +

Errors

-#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControl [!toc] +
+IAccessControl + - [AccessControlUnauthorizedAccount(account, neededRole)](#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-) - [AccessControlBadConfirmation()](#IAccessControl-AccessControlBadConfirmation--) + +
@@ -182,6 +183,13 @@ with an [`IAccessControl.AccessControlUnauthorizedAccount`](#IAccessControl-Acce
+Returns true if this contract implements the interface defined by +`interfaceId`. See the corresponding +[ERC section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified) +to learn more about how these ids are created. + +This function call must use less than 30 000 gas. +
@@ -421,7 +429,7 @@ May emit a [`IAccessControl.RoleRevoked`](#IAccessControl-RoleRevoked-bytes32-ad ## `IAccessControl` - + @@ -679,7 +687,7 @@ Don't confuse with [`IAccessControl.AccessControlUnauthorizedAccount`](#IAccessC ## `Ownable` - + @@ -918,7 +926,7 @@ The owner is not a valid owner account. (eg. `address(0)`) ## `Ownable2Step` - + @@ -951,10 +959,14 @@ from parent (Ownable). - [transferOwnership(newOwner)](#Ownable2Step-transferOwnership-address-) - [_transferOwnership(newOwner)](#Ownable2Step-_transferOwnership-address-) - [acceptOwnership()](#Ownable2Step-acceptOwnership--) -#### Ownable [!toc] +
+Ownable + - [owner()](#Ownable-owner--) - [_checkOwner()](#Ownable-_checkOwner--) - [renounceOwnership()](#Ownable-renounceOwnership--) + +
@@ -962,17 +974,25 @@ from parent (Ownable).

Events

- [OwnershipTransferStarted(previousOwner, newOwner)](#Ownable2Step-OwnershipTransferStarted-address-address-) -#### Ownable [!toc] +
+Ownable + - [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-) + +

Errors

-#### Ownable [!toc] +
+Ownable + - [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-) + +
@@ -1070,7 +1090,7 @@ The new owner accepts the ownership transfer. ## `AccessControlDefaultAdminRules` - + @@ -1135,53 +1155,60 @@ contract MyToken is AccessControlDefaultAdminRules { - [rollbackDefaultAdminDelay()](#AccessControlDefaultAdminRules-rollbackDefaultAdminDelay--) - [_rollbackDefaultAdminDelay()](#AccessControlDefaultAdminRules-_rollbackDefaultAdminDelay--) - [_delayChangeWait(newDelay)](#AccessControlDefaultAdminRules-_delayChangeWait-uint48-) -#### AccessControl [!toc] +
+AccessControl + - [hasRole(role, account)](#AccessControl-hasRole-bytes32-address-) - [_checkRole(role)](#AccessControl-_checkRole-bytes32-) - [_checkRole(role, account)](#AccessControl-_checkRole-bytes32-address-) - [getRoleAdmin(role)](#AccessControl-getRoleAdmin-bytes32-) - [DEFAULT_ADMIN_ROLE()](#AccessControl-DEFAULT_ADMIN_ROLE-bytes32) -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IERC5313 [!toc] -#### IAccessControlDefaultAdminRules [!toc] -#### IAccessControl [!toc] + +

Events

-#### AccessControl [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IERC5313 [!toc] -#### IAccessControlDefaultAdminRules [!toc] +
+IAccessControlDefaultAdminRules + - [DefaultAdminTransferScheduled(newAdmin, acceptSchedule)](#IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-) - [DefaultAdminTransferCanceled()](#IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--) - [DefaultAdminDelayChangeScheduled(newDelay, effectSchedule)](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-) - [DefaultAdminDelayChangeCanceled()](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--) -#### IAccessControl [!toc] + +
+
+IAccessControl + - [RoleAdminChanged(role, previousAdminRole, newAdminRole)](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) - [RoleGranted(role, account, sender)](#IAccessControl-RoleGranted-bytes32-address-address-) - [RoleRevoked(role, account, sender)](#IAccessControl-RoleRevoked-bytes32-address-address-) + +

Errors

-#### AccessControl [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IERC5313 [!toc] -#### IAccessControlDefaultAdminRules [!toc] +
+IAccessControlDefaultAdminRules + - [AccessControlInvalidDefaultAdmin(defaultAdmin)](#IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address-) - [AccessControlEnforcedDefaultAdminRules()](#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules--) - [AccessControlEnforcedDefaultAdminDelay(schedule)](#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48-) -#### IAccessControl [!toc] + +
+
+IAccessControl + - [AccessControlUnauthorizedAccount(account, neededRole)](#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-) - [AccessControlBadConfirmation()](#IAccessControl-AccessControlBadConfirmation--) + +
@@ -1503,7 +1530,7 @@ Requirements: - Only can be called by the current [`AccessControlDefaultAdminRules.defaultAdmin`](#AccessControlDefaultAdminRules-defaultAdmin--). -Emits a DefaultAdminRoleChangeStarted event. +Emits a [`IAccessControlDefaultAdminRules.DefaultAdminTransferScheduled`](#IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-) event. @@ -1547,7 +1574,7 @@ Requirements: - Only can be called by the current [`AccessControlDefaultAdminRules.defaultAdmin`](#AccessControlDefaultAdminRules-defaultAdmin--). -May emit a DefaultAdminTransferCanceled event. +May emit a [`IAccessControlDefaultAdminRules.DefaultAdminTransferCanceled`](#IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--) event. @@ -1653,7 +1680,7 @@ Requirements: - Only can be called by the current [`AccessControlDefaultAdminRules.defaultAdmin`](#AccessControlDefaultAdminRules-defaultAdmin--). -Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event. +Emits a [`IAccessControlDefaultAdminRules.DefaultAdminDelayChangeScheduled`](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-) event and may emit a [`IAccessControlDefaultAdminRules.DefaultAdminDelayChangeCanceled`](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--) event. @@ -1695,7 +1722,7 @@ Requirements: - Only can be called by the current [`AccessControlDefaultAdminRules.defaultAdmin`](#AccessControlDefaultAdminRules-defaultAdmin--). -May emit a DefaultAdminDelayChangeCanceled event. +May emit a [`IAccessControlDefaultAdminRules.DefaultAdminDelayChangeCanceled`](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--) event. @@ -1748,7 +1775,7 @@ See [`AccessControlDefaultAdminRules.defaultAdminDelayIncreaseWait`](#AccessCont ## `AccessControlEnumerable` - + @@ -1769,7 +1796,9 @@ Extension of [`AccessControl`](#AccessControl) that allows enumerating the membe - [getRoleMembers(role)](#AccessControlEnumerable-getRoleMembers-bytes32-) - [_grantRole(role, account)](#AccessControlEnumerable-_grantRole-bytes32-address-) - [_revokeRole(role, account)](#AccessControlEnumerable-_revokeRole-bytes32-address-) -#### AccessControl [!toc] +
+AccessControl + - [hasRole(role, account)](#AccessControl-hasRole-bytes32-address-) - [_checkRole(role)](#AccessControl-_checkRole-bytes32-) - [_checkRole(role, account)](#AccessControl-_checkRole-bytes32-address-) @@ -1779,37 +1808,35 @@ Extension of [`AccessControl`](#AccessControl) that allows enumerating the membe - [renounceRole(role, callerConfirmation)](#AccessControl-renounceRole-bytes32-address-) - [_setRoleAdmin(role, adminRole)](#AccessControl-_setRoleAdmin-bytes32-bytes32-) - [DEFAULT_ADMIN_ROLE()](#AccessControl-DEFAULT_ADMIN_ROLE-bytes32) -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControlEnumerable [!toc] -#### IAccessControl [!toc] + +

Events

-#### AccessControl [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControlEnumerable [!toc] -#### IAccessControl [!toc] +
+IAccessControl + - [RoleAdminChanged(role, previousAdminRole, newAdminRole)](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) - [RoleGranted(role, account, sender)](#IAccessControl-RoleGranted-bytes32-address-address-) - [RoleRevoked(role, account, sender)](#IAccessControl-RoleRevoked-bytes32-address-address-) + +

Errors

-#### AccessControl [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControlEnumerable [!toc] -#### IAccessControl [!toc] +
+IAccessControl + - [AccessControlUnauthorizedAccount(account, neededRole)](#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-) - [AccessControlBadConfirmation()](#IAccessControl-AccessControlBadConfirmation--) + +
@@ -1938,7 +1965,7 @@ Overload [`AccessControl._revokeRole`](#AccessControl-_revokeRole-bytes32-addres ## `IAccessControlDefaultAdminRules` - + @@ -1963,12 +1990,16 @@ External interface of AccessControlDefaultAdminRules declared to support ERC-165 - [changeDefaultAdminDelay(newDelay)](#IAccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-) - [rollbackDefaultAdminDelay()](#IAccessControlDefaultAdminRules-rollbackDefaultAdminDelay--) - [defaultAdminDelayIncreaseWait()](#IAccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--) -#### IAccessControl [!toc] +
+IAccessControl + - [hasRole(role, account)](#IAccessControl-hasRole-bytes32-address-) - [getRoleAdmin(role)](#IAccessControl-getRoleAdmin-bytes32-) - [grantRole(role, account)](#IAccessControl-grantRole-bytes32-address-) - [revokeRole(role, account)](#IAccessControl-revokeRole-bytes32-address-) - [renounceRole(role, callerConfirmation)](#IAccessControl-renounceRole-bytes32-address-) + +
@@ -1979,10 +2010,14 @@ External interface of AccessControlDefaultAdminRules declared to support ERC-165 - [DefaultAdminTransferCanceled()](#IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--) - [DefaultAdminDelayChangeScheduled(newDelay, effectSchedule)](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-) - [DefaultAdminDelayChangeCanceled()](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--) -#### IAccessControl [!toc] +
+IAccessControl + - [RoleAdminChanged(role, previousAdminRole, newAdminRole)](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) - [RoleGranted(role, account, sender)](#IAccessControl-RoleGranted-bytes32-address-address-) - [RoleRevoked(role, account, sender)](#IAccessControl-RoleRevoked-bytes32-address-address-) + +
@@ -1992,9 +2027,13 @@ External interface of AccessControlDefaultAdminRules declared to support ERC-165 - [AccessControlInvalidDefaultAdmin(defaultAdmin)](#IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address-) - [AccessControlEnforcedDefaultAdminRules()](#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules--) - [AccessControlEnforcedDefaultAdminDelay(schedule)](#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48-) -#### IAccessControl [!toc] +
+IAccessControl + - [AccessControlUnauthorizedAccount(account, neededRole)](#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-) - [AccessControlBadConfirmation()](#IAccessControl-AccessControlBadConfirmation--) + +
@@ -2112,7 +2151,7 @@ Requirements: - Only can be called by the current [`AccessControlDefaultAdminRules.defaultAdmin`](#AccessControlDefaultAdminRules-defaultAdmin--). -Emits a DefaultAdminRoleChangeStarted event. +Emits a [`IAccessControlDefaultAdminRules.DefaultAdminTransferScheduled`](#IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-) event. @@ -2137,7 +2176,7 @@ Requirements: - Only can be called by the current [`AccessControlDefaultAdminRules.defaultAdmin`](#AccessControlDefaultAdminRules-defaultAdmin--). -May emit a DefaultAdminTransferCanceled event. +May emit a [`IAccessControlDefaultAdminRules.DefaultAdminTransferCanceled`](#IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--) event. @@ -2205,7 +2244,7 @@ Requirements: - Only can be called by the current [`AccessControlDefaultAdminRules.defaultAdmin`](#AccessControlDefaultAdminRules-defaultAdmin--). -Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event. +Emits a [`IAccessControlDefaultAdminRules.DefaultAdminDelayChangeScheduled`](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-) event and may emit a [`IAccessControlDefaultAdminRules.DefaultAdminDelayChangeCanceled`](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--) event. @@ -2228,7 +2267,7 @@ Requirements: - Only can be called by the current [`AccessControlDefaultAdminRules.defaultAdmin`](#AccessControlDefaultAdminRules-defaultAdmin--). -May emit a DefaultAdminDelayChangeCanceled event. +May emit a [`IAccessControlDefaultAdminRules.DefaultAdminDelayChangeCanceled`](#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--) event. @@ -2400,7 +2439,7 @@ the operation must wait until `schedule`. ## `IAccessControlEnumerable` - + @@ -2417,31 +2456,43 @@ External interface of AccessControlEnumerable declared to support ERC-165 detect
- [getRoleMember(role, index)](#IAccessControlEnumerable-getRoleMember-bytes32-uint256-) - [getRoleMemberCount(role)](#IAccessControlEnumerable-getRoleMemberCount-bytes32-) -#### IAccessControl [!toc] +
+IAccessControl + - [hasRole(role, account)](#IAccessControl-hasRole-bytes32-address-) - [getRoleAdmin(role)](#IAccessControl-getRoleAdmin-bytes32-) - [grantRole(role, account)](#IAccessControl-grantRole-bytes32-address-) - [revokeRole(role, account)](#IAccessControl-revokeRole-bytes32-address-) - [renounceRole(role, callerConfirmation)](#IAccessControl-renounceRole-bytes32-address-) + +

Events

-#### IAccessControl [!toc] +
+IAccessControl + - [RoleAdminChanged(role, previousAdminRole, newAdminRole)](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) - [RoleGranted(role, account, sender)](#IAccessControl-RoleGranted-bytes32-address-address-) - [RoleRevoked(role, account, sender)](#IAccessControl-RoleRevoked-bytes32-address-address-) + +

Errors

-#### IAccessControl [!toc] +
+IAccessControl + - [AccessControlUnauthorizedAccount(account, neededRole)](#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-) - [AccessControlBadConfirmation()](#IAccessControl-AccessControlBadConfirmation--) + +
@@ -2497,7 +2548,7 @@ together with [`AccessControlEnumerable.getRoleMember`](#AccessControlEnumerable ## `AccessManaged` - + @@ -2532,25 +2583,32 @@ functions, and ideally only used in `external` functions. See [`AccessManaged.re - [isConsumingScheduledOp()](#AccessManaged-isConsumingScheduledOp--) - [_setAuthority(newAuthority)](#AccessManaged-_setAuthority-address-) - [_checkCanCall(caller, data)](#AccessManaged-_checkCanCall-address-bytes-) -#### IAccessManaged [!toc]

Events

-#### IAccessManaged [!toc] +
+IAccessManaged + - [AuthorityUpdated(authority)](#IAccessManaged-AuthorityUpdated-address-) + +

Errors

-#### IAccessManaged [!toc] +
+IAccessManaged + - [AccessManagedUnauthorized(caller)](#IAccessManaged-AccessManagedUnauthorized-address-) - [AccessManagedRequiredDelay(caller, delay)](#IAccessManaged-AccessManagedRequiredDelay-address-uint32-) - [AccessManagedInvalidAuthority(authority)](#IAccessManaged-AccessManagedInvalidAuthority-address-) + +
@@ -2570,22 +2628,20 @@ functions, and ideally only used in `external` functions. See [`AccessManaged.re Restricts access to a function as defined by the connected Authority for this contract and the caller and selector of the function that entered the contract. - -In general, this modifier should only be used on `external` functions. It is okay to use it on `public` +[IMPORTANT] +#### In general, this modifier should only be used on `external` functions. It is okay to use it on `public` functions that are used as external entry points and are not called internally. Unless you know what you're doing, it should never be used on `internal` functions. Failure to follow these rules can have critical security implications! This is because the permissions are determined by the function that entered the contract, i.e. the function at the bottom of the call stack, and not the function where the modifier is visible in the source code. - - -Avoid adding this modifier to the [`receive()`](https://docs.soliditylang.org/en/v0.8.20/contracts.html#receive-ether-function) +#### [WARNING] +#### Avoid adding this modifier to the [`receive()`](https://docs.soliditylang.org/en/v0.8.20/contracts.html#receive-ether-function) function or the [`fallback()`](https://docs.soliditylang.org/en/v0.8.20/contracts.html#fallback-function). These functions are the only execution paths where a function selector cannot be unambiguously determined from the calldata since the selector defaults to `0x00000000` in the `receive()` function and similarly in the `fallback()` function if no calldata is provided. (See [`AccessManaged._checkCanCall`](#AccessManaged-_checkCanCall-address-bytes-)). The `receive()` function will always panic whereas the `fallback()` may panic depending on the calldata length. - @@ -2702,7 +2758,7 @@ is less than 4 bytes long. ## `AccessManager` - + @@ -2815,16 +2871,21 @@ mindful of the danger associated with functions such as [`Ownable.renounceOwners - [updateAuthority(target, newAuthority)](#AccessManager-updateAuthority-address-address-) - [ADMIN_ROLE()](#AccessManager-ADMIN_ROLE-uint64) - [PUBLIC_ROLE()](#AccessManager-PUBLIC_ROLE-uint64) -#### IAccessManager [!toc] -#### Multicall [!toc] +
+Multicall + - [multicall(data)](#Multicall-multicall-bytes---) + +

Events

-#### IAccessManager [!toc] +
+IAccessManager + - [OperationScheduled(operationId, nonce, schedule, caller, target, data)](#IAccessManager-OperationScheduled-bytes32-uint32-uint48-address-address-bytes-) - [OperationExecuted(operationId, nonce)](#IAccessManager-OperationExecuted-bytes32-uint32-) - [OperationCanceled(operationId, nonce)](#IAccessManager-OperationCanceled-bytes32-uint32-) @@ -2837,26 +2898,31 @@ mindful of the danger associated with functions such as [`Ownable.renounceOwners - [TargetClosed(target, closed)](#IAccessManager-TargetClosed-address-bool-) - [TargetFunctionRoleUpdated(target, selector, roleId)](#IAccessManager-TargetFunctionRoleUpdated-address-bytes4-uint64-) - [TargetAdminDelayUpdated(target, delay, since)](#IAccessManager-TargetAdminDelayUpdated-address-uint32-uint48-) -#### Multicall [!toc] + +

Errors

-#### IAccessManager [!toc] +
+IAccessManager + - [AccessManagerAlreadyScheduled(operationId)](#IAccessManager-AccessManagerAlreadyScheduled-bytes32-) - [AccessManagerNotScheduled(operationId)](#IAccessManager-AccessManagerNotScheduled-bytes32-) - [AccessManagerNotReady(operationId)](#IAccessManager-AccessManagerNotReady-bytes32-) - [AccessManagerExpired(operationId)](#IAccessManager-AccessManagerExpired-bytes32-) - [AccessManagerLockedRole(roleId)](#IAccessManager-AccessManagerLockedRole-uint64-) +- [AccessManagerLockedFunction(selector)](#IAccessManager-AccessManagerLockedFunction-bytes4-) - [AccessManagerBadConfirmation()](#IAccessManager-AccessManagerBadConfirmation--) - [AccessManagerUnauthorizedAccount(msgsender, roleId)](#IAccessManager-AccessManagerUnauthorizedAccount-address-uint64-) - [AccessManagerUnauthorizedCall(caller, target, selector)](#IAccessManager-AccessManagerUnauthorizedCall-address-address-bytes4-) - [AccessManagerUnauthorizedConsume(target)](#IAccessManager-AccessManagerUnauthorizedConsume-address-) - [AccessManagerUnauthorizedCancel(msgsender, caller, target, selector)](#IAccessManager-AccessManagerUnauthorizedCancel-address-address-address-bytes4-) - [AccessManagerInvalidInitialAdmin(initialAdmin)](#IAccessManager-AccessManagerInvalidInitialAdmin-address-) -#### Multicall [!toc] + +
@@ -3147,6 +3213,7 @@ Give a label to a role, for improved role discoverability by UIs. Requirements: - the caller must be a global admin +- `roleId` must not be the `ADMIN_ROLE` or `PUBLIC_ROLE` Emits a [`IAccessManager.RoleLabel`](#IAccessManager-RoleLabel-uint64-string-) event. @@ -3253,6 +3320,7 @@ Change admin role for a given role. Requirements: - the caller must be a global admin +- `roleId` must not be the `ADMIN_ROLE` or `PUBLIC_ROLE` Emits a [`IAccessControl.RoleAdminChanged`](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) event @@ -3276,6 +3344,7 @@ Change guardian role for a given role. Requirements: - the caller must be a global admin +- `roleId` must not be the `ADMIN_ROLE` or `PUBLIC_ROLE` Emits a [`IAccessManager.RoleGuardianChanged`](#IAccessManager-RoleGuardianChanged-uint64-uint64-) event @@ -3299,6 +3368,7 @@ Update the delay for granting a `roleId`. Requirements: - the caller must be a global admin +- `roleId` must not be the `PUBLIC_ROLE` Emits a [`IAccessManager.RoleGrantDelayChanged`](#IAccessManager-RoleGrantDelayChanged-uint64-uint32-uint48-) event. @@ -3774,7 +3844,7 @@ The identifier of the public role. Automatically granted to all addresses with n ## `AuthorityUtils` - + @@ -3816,7 +3886,7 @@ This helper function takes care of invoking `canCall` in a backwards compatible ## `IAccessManaged` - + @@ -3973,7 +4043,7 @@ Authority that manages this contract was updated. ## `IAccessManager` - + @@ -4044,6 +4114,7 @@ import "@openzeppelin/contracts/access/manager/IAccessManager.sol"; - [AccessManagerNotReady(operationId)](#IAccessManager-AccessManagerNotReady-bytes32-) - [AccessManagerExpired(operationId)](#IAccessManager-AccessManagerExpired-bytes32-) - [AccessManagerLockedRole(roleId)](#IAccessManager-AccessManagerLockedRole-uint64-) +- [AccessManagerLockedFunction(selector)](#IAccessManager-AccessManagerLockedFunction-bytes4-) - [AccessManagerBadConfirmation()](#IAccessManager-AccessManagerBadConfirmation--) - [AccessManagerUnauthorizedAccount(msgsender, roleId)](#IAccessManager-AccessManagerUnauthorizedAccount-address-uint64-) - [AccessManagerUnauthorizedCall(caller, target, selector)](#IAccessManager-AccessManagerUnauthorizedCall-address-address-bytes4-) @@ -4306,6 +4377,7 @@ Give a label to a role, for improved role discoverability by UIs. Requirements: - the caller must be a global admin +- `roleId` must not be the `ADMIN_ROLE` or `PUBLIC_ROLE` Emits a [`IAccessManager.RoleLabel`](#IAccessManager-RoleLabel-uint64-string-) event. @@ -4412,6 +4484,7 @@ Change admin role for a given role. Requirements: - the caller must be a global admin +- `roleId` must not be the `ADMIN_ROLE` or `PUBLIC_ROLE` Emits a [`IAccessControl.RoleAdminChanged`](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) event @@ -4435,6 +4508,7 @@ Change guardian role for a given role. Requirements: - the caller must be a global admin +- `roleId` must not be the `ADMIN_ROLE` or `PUBLIC_ROLE` Emits a [`IAccessManager.RoleGuardianChanged`](#IAccessManager-RoleGuardianChanged-uint64-uint64-) event @@ -4458,6 +4532,7 @@ Update the delay for granting a `roleId`. Requirements: - the caller must be a global admin +- `roleId` must not be the `PUBLIC_ROLE` Emits a [`IAccessManager.RoleGrantDelayChanged`](#IAccessManager-RoleGrantDelayChanged-uint64-uint32-uint48-) event. @@ -4796,7 +4871,7 @@ Emitted when `account` is granted `roleId`. The meaning of the `since` argument depends on the `newMember` argument. If the role is granted to a new member, the `since` argument indicates when the account becomes a member of the role, -otherwise it indicates the execution delay for this account and roleId is updated. +otherwise it indicates the timestamp when the execution delay update takes effect for this account and roleId. @@ -4996,6 +5071,21 @@ Admin delay for a given `target` will be updated to `delay` when `since` is reac + + +
+
+

AccessManagerLockedFunction(bytes4 selector)

+
+

error

+# +
+
+
+ +
+
+
@@ -5092,7 +5182,7 @@ Admin delay for a given `target` will be updated to `delay` when `since` is reac ## `IAuthority` - + diff --git a/content/contracts/5.x/api/account.mdx b/content/contracts/5.x/api/account.mdx index 8d16aab0..8b021760 100644 --- a/content/contracts/5.x/api/account.mdx +++ b/content/contracts/5.x/api/account.mdx @@ -34,9 +34,9 @@ This directory includes contracts to build accounts for ERC-4337. These include:
-## `Account` +## `Account` - + @@ -86,9 +86,12 @@ digital signature validation implementations. - [_checkEntryPoint()](#Account-_checkEntryPoint--) - [_checkEntryPointOrSelf()](#Account-_checkEntryPointOrSelf--) - [receive()](#Account-receive--) -#### IAccount [!toc] -#### AbstractSigner [!toc] +
+AbstractSigner + - [_rawSignatureValidation(hash, signature)](#AbstractSigner-_rawSignatureValidation-bytes32-bytes-) + +
@@ -96,8 +99,6 @@ digital signature validation implementations.

Errors

- [AccountUnauthorized(sender)](#Account-AccountUnauthorized-address-) -#### IAccount [!toc] -#### AbstractSigner [!toc]
@@ -353,9 +354,9 @@ Unauthorized call to the account.
-## `AccountERC7579` +## `AccountERC7579` - + @@ -382,8 +383,8 @@ contract MyAccountERC7579 is AccountERC7579, Initializable { } ``` - -* Hook support is not included. See [`AccountERC7579Hooked`](#AccountERC7579Hooked) for a version that hooks to execution. +[NOTE] +#### * Hook support is not included. See [`AccountERC7579Hooked`](#AccountERC7579Hooked) for a version that hooks to execution. * Validator selection, when verifying either ERC-1271 signature or ERC-4337 UserOperation is implemented in internal virtual functions [`AccountERC7579._extractUserOpValidator`](#AccountERC7579-_extractUserOpValidator-struct-PackedUserOperation-) and [`AccountERC7579._extractSignatureValidator`](#AccountERC7579-_extractSignatureValidator-bytes-). Both are implemented following common practices. However, this part is not standardized in ERC-7579 (or in any follow-up ERC). Some @@ -391,10 +392,7 @@ contract MyAccountERC7579 is AccountERC7579, Initializable { * When combined with [`ERC7739`](/contracts/5.x/api/utils/cryptography#ERC7739), resolution ordering of [`AccountERC7579.isValidSignature`](#AccountERC7579-isValidSignature-bytes32-bytes-) may have an impact ([`ERC7739`](/contracts/5.x/api/utils/cryptography#ERC7739) does not call super). Manual resolution might be necessary. * Static calls (using callType `0xfe`) are currently NOT supported. - - -Removing all validator modules will render the account inoperable, as no user operations can be validated thereafter. - +#### WARNING: Removing all validator modules will render the account inoperable, as no user operations can be validated thereafter.

Modifiers

@@ -427,11 +425,9 @@ Removing all validator modules will render the account inoperable, as no user op - [_extractSignatureValidator(signature)](#AccountERC7579-_extractSignatureValidator-bytes-) - [_decodeFallbackData(data)](#AccountERC7579-_decodeFallbackData-bytes-) - [_rawSignatureValidation(, )](#AccountERC7579-_rawSignatureValidation-bytes32-bytes-) -#### IERC7579ModuleConfig [!toc] -#### IERC7579AccountConfig [!toc] -#### IERC7579Execution [!toc] -#### IERC1271 [!toc] -#### Account [!toc] +
+Account + - [entryPoint()](#Account-entryPoint--) - [getNonce()](#Account-getNonce--) - [getNonce(key)](#Account-getNonce-uint192-) @@ -441,23 +437,21 @@ Removing all validator modules will render the account inoperable, as no user op - [_checkEntryPoint()](#Account-_checkEntryPoint--) - [_checkEntryPointOrSelf()](#Account-_checkEntryPointOrSelf--) - [receive()](#Account-receive--) -#### IAccount [!toc] -#### AbstractSigner [!toc] + +

Events

-#### IERC7579ModuleConfig [!toc] +
+IERC7579ModuleConfig + - [ModuleInstalled(moduleTypeId, module)](#IERC7579ModuleConfig-ModuleInstalled-uint256-address-) - [ModuleUninstalled(moduleTypeId, module)](#IERC7579ModuleConfig-ModuleUninstalled-uint256-address-) -#### IERC7579AccountConfig [!toc] -#### IERC7579Execution [!toc] -#### IERC1271 [!toc] -#### Account [!toc] -#### IAccount [!toc] -#### AbstractSigner [!toc] + +
@@ -466,14 +460,12 @@ Removing all validator modules will render the account inoperable, as no user op
- [ERC7579MissingFallbackHandler(selector)](#AccountERC7579-ERC7579MissingFallbackHandler-bytes4-) - [ERC7579CannotDecodeFallbackData()](#AccountERC7579-ERC7579CannotDecodeFallbackData--) -#### IERC7579ModuleConfig [!toc] -#### IERC7579AccountConfig [!toc] -#### IERC7579Execution [!toc] -#### IERC1271 [!toc] -#### Account [!toc] +
+Account + - [AccountUnauthorized(sender)](#Account-AccountUnauthorized-address-) -#### IAccount [!toc] -#### AbstractSigner [!toc] + +
@@ -923,7 +915,7 @@ If we had calldata here, we could use calldata slice which are cheaper to manipu actual copy. However, this would require `_installModule` to get a calldata bytes object instead of a memory bytes object. This would prevent calling `_installModule` from a contract constructor and would force the use of external initializers. That may change in the future, as most accounts will probably be deployed as -clones/proxy/ERC-7702 delegates and therefore rely on initializers anyway. +clones/proxy/EIP-7702 delegates and therefore rely on initializers anyway. @@ -984,9 +976,9 @@ The provided initData/deInitData for a fallback module is too short to extract a
-## `AccountERC7579Hooked` +## `AccountERC7579Hooked` - + @@ -999,7 +991,7 @@ import "@openzeppelin/contracts/account/extensions/draft-AccountERC7579Hooked.so Extension of [`AccountERC7579`](#AccountERC7579) with support for a single hook module (type 4). If installed, this extension will call the hook module's [`IERC7579Hook.preCheck`](/contracts/5.x/api/interfaces#IERC7579Hook-preCheck-address-uint256-bytes-) before executing any operation -with [`AccountERC7579._execute`](#AccountERC7579-_execute-Mode-bytes-) (including [`AccessManager.execute`](/contracts/5.x/api/access#AccessManager-execute-address-bytes-) and [`AccountERC7579.executeFromExecutor`](#AccountERC7579-executeFromExecutor-bytes32-bytes-) by default) and [`IERC7579Hook.postCheck`](/contracts/5.x/api/interfaces#IERC7579Hook-postCheck-bytes-) thereafter. +with [`AccountERC7579._execute`](#AccountERC7579-_execute-Mode-bytes-) (including [`AccountERC7579.execute`](#AccountERC7579-execute-bytes32-bytes-) and [`AccountERC7579.executeFromExecutor`](#AccountERC7579-executeFromExecutor-bytes32-bytes-) by default) and [`IERC7579Hook.postCheck`](/contracts/5.x/api/interfaces#IERC7579Hook-postCheck-bytes-) thereafter. Hook modules break the check-effect-interaction pattern. In particular, the [`IERC7579Hook.preCheck`](/contracts/5.x/api/interfaces#IERC7579Hook-preCheck-address-uint256-bytes-) hook can @@ -1027,7 +1019,9 @@ modules or further overriding functions that involve hooks. - [_uninstallModule(moduleTypeId, module, deInitData)](#AccountERC7579Hooked-_uninstallModule-uint256-address-bytes-) - [_execute(mode, executionCalldata)](#AccountERC7579Hooked-_execute-Mode-bytes-) - [_fallback()](#AccountERC7579Hooked-_fallback--) -#### AccountERC7579 [!toc] +
+AccountERC7579 + - [fallback()](#AccountERC7579-fallback-bytes-) - [supportsExecutionMode(encodedMode)](#AccountERC7579-supportsExecutionMode-bytes32-) - [installModule(moduleTypeId, module, initData)](#AccountERC7579-installModule-uint256-address-bytes-) @@ -1042,11 +1036,11 @@ modules or further overriding functions that involve hooks. - [_extractSignatureValidator(signature)](#AccountERC7579-_extractSignatureValidator-bytes-) - [_decodeFallbackData(data)](#AccountERC7579-_decodeFallbackData-bytes-) - [_rawSignatureValidation(, )](#AccountERC7579-_rawSignatureValidation-bytes32-bytes-) -#### IERC7579ModuleConfig [!toc] -#### IERC7579AccountConfig [!toc] -#### IERC7579Execution [!toc] -#### IERC1271 [!toc] -#### Account [!toc] + +
+
+Account + - [entryPoint()](#Account-entryPoint--) - [getNonce()](#Account-getNonce--) - [getNonce(key)](#Account-getNonce-uint192-) @@ -1056,24 +1050,21 @@ modules or further overriding functions that involve hooks. - [_checkEntryPoint()](#Account-_checkEntryPoint--) - [_checkEntryPointOrSelf()](#Account-_checkEntryPointOrSelf--) - [receive()](#Account-receive--) -#### IAccount [!toc] -#### AbstractSigner [!toc] + +

Events

-#### AccountERC7579 [!toc] -#### IERC7579ModuleConfig [!toc] +
+IERC7579ModuleConfig + - [ModuleInstalled(moduleTypeId, module)](#IERC7579ModuleConfig-ModuleInstalled-uint256-address-) - [ModuleUninstalled(moduleTypeId, module)](#IERC7579ModuleConfig-ModuleUninstalled-uint256-address-) -#### IERC7579AccountConfig [!toc] -#### IERC7579Execution [!toc] -#### IERC1271 [!toc] -#### Account [!toc] -#### IAccount [!toc] -#### AbstractSigner [!toc] + +
@@ -1081,17 +1072,19 @@ modules or further overriding functions that involve hooks.

Errors

- [ERC7579HookModuleAlreadyPresent(hook)](#AccountERC7579Hooked-ERC7579HookModuleAlreadyPresent-address-) -#### AccountERC7579 [!toc] +
+AccountERC7579 + - [ERC7579MissingFallbackHandler(selector)](#AccountERC7579-ERC7579MissingFallbackHandler-bytes4-) - [ERC7579CannotDecodeFallbackData()](#AccountERC7579-ERC7579CannotDecodeFallbackData--) -#### IERC7579ModuleConfig [!toc] -#### IERC7579AccountConfig [!toc] -#### IERC7579Execution [!toc] -#### IERC1271 [!toc] -#### Account [!toc] + +
+
+Account + - [AccountUnauthorized(sender)](#Account-AccountUnauthorized-address-) -#### IAccount [!toc] -#### AbstractSigner [!toc] + +
@@ -1271,9 +1264,9 @@ A hook module is already present. This contract only supports one hook module.
-## `ERC7821` +## `ERC7821` - + @@ -1295,7 +1288,6 @@ Only supports single batch mode (`0x01000000000000000000`). Does not support opt - [execute(mode, executionData)](#ERC7821-execute-bytes32-bytes-) - [supportsExecutionMode(mode)](#ERC7821-supportsExecutionMode-bytes32-) - [_erc7821AuthorizedExecutor(caller, , )](#ERC7821-_erc7821AuthorizedExecutor-address-bytes32-bytes-) -#### IERC7821 [!toc]
@@ -1303,7 +1295,6 @@ Only supports single batch mode (`0x01000000000000000000`). Does not support opt

Errors

- [UnsupportedExecutionMode()](#ERC7821-UnsupportedExecutionMode--) -#### IERC7821 [!toc]
@@ -1363,7 +1354,7 @@ Only returns true for:
-Access control mechanism for the [`AccessManager.execute`](/contracts/5.x/api/access#AccessManager-execute-address-bytes-) function. +Access control mechanism for the [`AccountERC7579.execute`](#AccountERC7579-execute-bytes32-bytes-) function. By default, only the contract itself is allowed to execute. Override this function to implement custom access control, for example to allow the @@ -1401,9 +1392,9 @@ function _erc7821AuthorizedExecutor(
-## `EIP7702Utils` +## `EIP7702Utils` - + @@ -1415,7 +1406,7 @@ import "@openzeppelin/contracts/account/utils/EIP7702Utils.sol"; Library with common EIP-7702 utility functions. -See [ERC-7702](https://eips.ethereum.org/EIPS/eip-7702). +See [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702).

Functions

@@ -1445,9 +1436,9 @@ Returns the address of the delegate if `account` has an EIP-7702 delegation setu
-## `IEntryPointExtra` +## `IEntryPointExtra` - + @@ -1485,9 +1476,9 @@ This is available on all entrypoint since v0.4.0, but is not formally part of th
-## `ERC4337Utils` +## `ERC4337Utils` - + @@ -1506,7 +1497,9 @@ See [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337).
- [parseValidationData(validationData)](#ERC4337Utils-parseValidationData-uint256-) - [packValidationData(aggregator, validAfter, validUntil)](#ERC4337Utils-packValidationData-address-uint48-uint48-) +- [packValidationData(aggregator, validAfter, validUntil, range)](#ERC4337Utils-packValidationData-address-uint48-uint48-enum-ERC4337Utils-ValidationRange-) - [packValidationData(sigSuccess, validAfter, validUntil)](#ERC4337Utils-packValidationData-bool-uint48-uint48-) +- [packValidationData(sigSuccess, validAfter, validUntil, range)](#ERC4337Utils-packValidationData-bool-uint48-uint48-enum-ERC4337Utils-ValidationRange-) - [combineValidationData(validationData1, validationData2)](#ERC4337Utils-combineValidationData-uint256-uint256-) - [getValidationData(validationData)](#ERC4337Utils-getValidationData-uint256-) - [hash(self, entrypoint)](#ERC4337Utils-hash-struct-PackedUserOperation-address-) @@ -1521,6 +1514,7 @@ See [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337). - [paymasterVerificationGasLimit(self)](#ERC4337Utils-paymasterVerificationGasLimit-struct-PackedUserOperation-) - [paymasterPostOpGasLimit(self)](#ERC4337Utils-paymasterPostOpGasLimit-struct-PackedUserOperation-) - [paymasterData(self)](#ERC4337Utils-paymasterData-struct-PackedUserOperation-) +- [paymasterSignature(self)](#ERC4337Utils-paymasterSignature-struct-PackedUserOperation-)
@@ -1528,7 +1522,7 @@ See [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337).
-

parseValidationData(uint256 validationData) โ†’ address aggregator, uint48 validAfter, uint48 validUntil

+

parseValidationData(uint256 validationData) โ†’ address aggregator, uint48 validAfter, uint48 validUntil, enum ERC4337Utils.ValidationRange range

internal

# @@ -1536,7 +1530,8 @@ See [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337).
-Parses the validation data into its components. See [`ERC4337Utils.packValidationData`](#ERC4337Utils-packValidationData-bool-uint48-uint48-). +Parses the validation data into its components and the validity range. See [`ERC4337Utils.packValidationData`](#ERC4337Utils-packValidationData-bool-uint48-uint48-enum-ERC4337Utils-ValidationRange-). +Strips away the highest bit flag from the `validAfter` and `validUntil` fields.
@@ -1558,6 +1553,24 @@ Packs the validation data into a single uint256. See [`ERC4337Utils.parseValidat
+ + +
+
+

packValidationData(address aggregator, uint48 validAfter, uint48 validUntil, enum ERC4337Utils.ValidationRange range) โ†’ uint256

+
+

internal

+# +
+
+
+ +Variant of [`ERC4337Utils.packValidationData`](#ERC4337Utils-packValidationData-bool-uint48-uint48-enum-ERC4337Utils-ValidationRange-) that forces which validity range to use. This overwrites the presence of +flags in `validAfter` and `validUntil`). + +
+
+
@@ -1570,7 +1583,25 @@ Packs the validation data into a single uint256. See [`ERC4337Utils.parseValidat
-Same as [`ERC4337Utils.packValidationData`](#ERC4337Utils-packValidationData-bool-uint48-uint48-), but with a boolean signature success flag. +Variant of [`ERC4337Utils.packValidationData`](#ERC4337Utils-packValidationData-bool-uint48-uint48-enum-ERC4337Utils-ValidationRange-) that uses a boolean success flag instead of an aggregator address. + +
+
+ + + +
+
+

packValidationData(bool sigSuccess, uint48 validAfter, uint48 validUntil, enum ERC4337Utils.ValidationRange range) โ†’ uint256

+
+

internal

+# +
+
+
+ +Variant of [`ERC4337Utils.packValidationData`](#ERC4337Utils-packValidationData-bool-uint48-uint48-enum-ERC4337Utils-ValidationRange-) that uses a boolean success flag instead of an aggregator address and that +forces which validity range to use. This overwrites the presence of flags in `validAfter` and `validUntil`).
@@ -1592,6 +1623,10 @@ Combines two validation data into a single one. The `aggregator` is set to [`ERC4337Utils.SIG_VALIDATION_SUCCESS`](#ERC4337Utils-SIG_VALIDATION_SUCCESS-uint256) if both are successful, while the `validAfter` is the maximum and the `validUntil` is the minimum of both. + +Returns `SIG_VALIDATION_FAILED` if the validation ranges differ. + +
@@ -1812,6 +1847,25 @@ Returns the third section of `paymasterAndData` from the [`PackedUserOperation`]
Returns the fourth section of `paymasterAndData` from the [`PackedUserOperation`](/contracts/5.x/api/interfaces#PackedUserOperation). +If a paymaster signature is present, it is excluded from the returned data. + +
+ + + + +
+
+

paymasterSignature(struct PackedUserOperation self) โ†’ bytes

+
+

internal

+# +
+
+
+ +Returns the paymaster signature from `paymasterAndData` (EntryPoint v0.9+). +Returns empty bytes if no paymaster signature is present.
@@ -1820,9 +1874,9 @@ Returns the fourth section of `paymasterAndData` from the [`PackedUserOperation`
-## `Mode` +## `Mode` - + @@ -1836,9 +1890,9 @@ import "@openzeppelin/contracts/account/utils/draft-ERC7579Utils.sol";
-## `CallType` +## `CallType` - + @@ -1852,9 +1906,9 @@ import "@openzeppelin/contracts/account/utils/draft-ERC7579Utils.sol";
-## `ExecType` +## `ExecType` - + @@ -1868,9 +1922,9 @@ import "@openzeppelin/contracts/account/utils/draft-ERC7579Utils.sol";
-## `ModeSelector` +## `ModeSelector` - + @@ -1884,9 +1938,9 @@ import "@openzeppelin/contracts/account/utils/draft-ERC7579Utils.sol";
-## `ModePayload` +## `ModePayload` - + @@ -1900,9 +1954,9 @@ import "@openzeppelin/contracts/account/utils/draft-ERC7579Utils.sol";
-## `ERC7579Utils` +## `ERC7579Utils` - + @@ -2285,9 +2339,9 @@ Input calldata not properly formatted and possibly malicious.
-## `eqCallType` +## `eqCallType` - + @@ -2320,9 +2374,9 @@ Compares two `CallType` values for equality.
-## `eqExecType` +## `eqExecType` - + @@ -2355,9 +2409,9 @@ Compares two `ExecType` values for equality.
-## `eqModeSelector` +## `eqModeSelector` - + @@ -2390,9 +2444,9 @@ Compares two `ModeSelector` values for equality.
-## `eqModePayload` +## `eqModePayload` - + @@ -2420,3 +2474,4 @@ Compares two `ModePayload` values for equality.
+ diff --git a/content/contracts/5.x/api/crosschain.mdx b/content/contracts/5.x/api/crosschain.mdx index 864666f4..0e1d7b30 100644 --- a/content/contracts/5.x/api/crosschain.mdx +++ b/content/contracts/5.x/api/crosschain.mdx @@ -5,88 +5,395 @@ description: "Smart contract crosschain utilities and implementations" This directory contains contracts for sending and receiving cross chain messages that follows the ERC-7786 standard. -* [`ERC7786Recipient`](#ERC7786Recipient): generic ERC-7786 crosschain contract that receives messages from a trusted gateway +* [`CrosschainLinked`](#CrosschainLinked): helper to facilitate communication between a contract on one chain and counterparts on remote chains through ERC-7786 gateways. +* [`CrosschainRemoteExecutor`](#CrosschainRemoteExecutor): executor contract that relays transaction from a controller on a remote chain. +* [`ERC7786Recipient`](#ERC7786Recipient): generic ERC-7786 crosschain contract that receives messages from a trusted gateway. + +Additionally there are multiple bridge constructions: + +* [`BridgeFungible`](#BridgeFungible): Core bridging logic for crosschain ERC-20 transfer. Used by [`BridgeERC20`](#BridgeERC20), [`BridgeERC7802`](#BridgeERC7802) and [`ERC20Crosschain`](/contracts/5.x/api/token/ERC20#ERC20Crosschain), +* [`BridgeNonFungible`](#BridgeNonFungible): Core bridging logic for crosschain ERC-721 transfer. Used by [`BridgeERC721`](#BridgeERC721) and [`ERC721Crosschain`](/contracts/5.x/api/token/ERC721#ERC721Crosschain), +* [`BridgeMultiToken`](#BridgeMultiToken): Core bridging logic for crosschain ERC-1155 transfer. Used by [`BridgeERC1155`](#BridgeERC1155) and [`ERC1155Crosschain`](/contracts/5.x/api/token/ERC1155#ERC1155Crosschain), +* [`BridgeERC20`](#BridgeERC20): Standalone bridge contract to connect an ERC-20 token contract with counterparts on remote chains, +* [`BridgeERC721`](#BridgeERC721): Standalone bridge contract to connect an ERC-721 token contract with counterparts on remote chains, +* [`BridgeERC1155`](#BridgeERC1155): Standalone bridge contract to connect an ERC-1155 token contract with counterparts on remote chains, +* [`BridgeERC7802`](#BridgeERC7802): Standalone bridge contract to connect an ERC-7802 token contract with counterparts on remote chains. ## Helpers +[`CrosschainLinked`](#CrosschainLinked) + +[`CrosschainRemoteExecutor`](#CrosschainRemoteExecutor) + [`ERC7786Recipient`](#ERC7786Recipient) - +## Bridges + +[`BridgeFungible`](#BridgeFungible) + +[`BridgeNonFungible`](#BridgeNonFungible) + +[`BridgeMultiToken`](#BridgeMultiToken) + +[`BridgeERC20`](#BridgeERC20) + +[`BridgeERC721`](#BridgeERC721) + +[`BridgeERC1155`](#BridgeERC1155) + +[`BridgeERC7802`](#BridgeERC7802) + +
-## `ERC7786Recipient` +## `CrosschainLinked` - +
```solidity -import "@openzeppelin/contracts/crosschain/ERC7786Recipient.sol"; +import "@openzeppelin/contracts/crosschain/CrosschainLinked.sol"; ``` -Base implementation of an ERC-7786 compliant cross-chain message receiver. +Core bridging mechanism. -This abstract contract exposes the `receiveMessage` function that is used for communication with (one or multiple) -destination gateways. This contract leaves two functions unimplemented: +This contract contains the logic to register and send messages to counterparts on remote chains using ERC-7786 +gateways. It ensure received messages originate from a counterpart. This is the base of token bridges such as +[`BridgeFungible`](#BridgeFungible). -* [`ERC7786Recipient._isAuthorizedGateway`](#ERC7786Recipient-_isAuthorizedGateway-address-bytes-), an internal getter used to verify whether an address is recognised by the contract as a -valid ERC-7786 destination gateway. One or multiple gateway can be supported. Note that any malicious address for -which this function returns true would be able to impersonate any account on any other chain sending any message. +Contracts that inherit from this contract can use the internal [`CrosschainLinked._sendMessageToCounterpart`](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) to send messages to their +counterpart on a foreign chain. They must override the [`CrosschainRemoteExecutor._processMessage`](#CrosschainRemoteExecutor-_processMessage-address-bytes32-bytes-bytes-) function to handle messages that have +been verified. + +
+

Functions

+
+- [constructor(links)](#CrosschainLinked-constructor-struct-CrosschainLinked-Link---) +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) +
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) +- [_processMessage(gateway, receiveId, sender, payload)](#ERC7786Recipient-_processMessage-address-bytes32-bytes-bytes-) + +
+
+
+ +
+

Events

+
+- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) +
+
+ +
+

Errors

+
+- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) +
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+
+ + + +
+
+

constructor(struct CrosschainLinked.Link[] links)

+
+

internal

+# +
+
+
+ +
+
+ + + +
+
+

getLink(bytes chain) โ†’ address gateway, bytes counterpart

+
+

public

+# +
+
+
+ +Returns the ERC-7786 gateway used for sending and receiving cross-chain messages to a given chain. + +Note: The `chain` parameter is a "chain-only" InteroperableAddress (empty address) and the `counterpart` returns +the full InteroperableAddress (chain ref + address) that is on `chain`. + +
+
+ + + +
+
+

_setLink(address gateway, bytes counterpart, bool allowOverride)

+
+

internal

+# +
+
+
+ +Internal setter to change the ERC-7786 gateway and counterpart for a given chain. Called at construction. + +Note: The `counterpart` parameter is the full InteroperableAddress (chain ref + address). + +
+
+ + + +
+
+

_sendMessageToCounterpart(bytes chain, bytes payload, bytes[] attributes) โ†’ bytes32

+
+

internal

+# +
+
+
+ +Internal messaging function + +Note: The `chain` parameter is a "chain-only" InteroperableAddress (empty address). + +
+
+ + + +
+
+

_isAuthorizedGateway(address instance, bytes sender) โ†’ bool

+
+

internal

+# +
+
+
+ +Virtual getter that returns whether an address is a valid ERC-7786 gateway for a given sender. + +The `sender` parameter is an interoperable address that include the source chain. The chain part can be +extracted using the [`InteroperableAddress`](/contracts/5.x/api/utils#InteroperableAddress) library to selectively authorize gateways based on the origin chain +of a message. + +
+
+ + + +
+
+

LinkRegistered(address gateway, bytes counterpart)

+
+

event

+# +
+
+ +
+ +Emitted when a new link is registered. + +Note: the `counterpart` argument is a full InteroperableAddress (chain ref + address). + +
+
-* [`ERC7786Recipient._processMessage`](#ERC7786Recipient-_processMessage-address-bytes32-bytes-bytes-), the internal function that will be called with any message that has been validated. + -This contract implements replay protection, meaning that if two messages are received from the same gateway with the -same `receiveId`, then the second one will NOT be executed, regardless of the result of [`ERC7786Recipient._isAuthorizedGateway`](#ERC7786Recipient-_isAuthorizedGateway-address-bytes-). +
+
+

LinkAlreadyRegistered(bytes chain)

+
+

error

+# +
+
+
+ +Reverted when trying to register a link for a chain that is already registered. + +Note: the `chain` argument is a "chain-only" InteroperableAddress (empty address). + +
+
+ + + +
+ +## `CrosschainRemoteExecutor` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/CrosschainRemoteExecutor.sol"; +``` + +Helper contract used to relay transactions received from a controller through an ERC-7786 gateway. This is +used by the [`GovernorCrosschain`](/contracts/5.x/api/governance#GovernorCrosschain) governance module for the execution of cross-chain actions. + +A [`CrosschainRemoteExecutor`](#CrosschainRemoteExecutor) address can be seen as the local identity of a remote executor on another chain. It +holds assets and permissions for the sake of its controller.

Functions

+- [constructor(initialGateway, initialController)](#CrosschainRemoteExecutor-constructor-address-bytes-) +- [gateway()](#CrosschainRemoteExecutor-gateway--) +- [controller()](#CrosschainRemoteExecutor-controller--) +- [reconfigure(newGateway, newController)](#CrosschainRemoteExecutor-reconfigure-address-bytes-) +- [_setup(gateway_, controller_)](#CrosschainRemoteExecutor-_setup-address-bytes-) +- [_isAuthorizedGateway(instance, sender)](#CrosschainRemoteExecutor-_isAuthorizedGateway-address-bytes-) +- [_processMessage(, , , payload)](#CrosschainRemoteExecutor-_processMessage-address-bytes32-bytes-bytes-) +
+ERC7786Recipient + - [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) -- [_isAuthorizedGateway(gateway, sender)](#ERC7786Recipient-_isAuthorizedGateway-address-bytes-) -- [_processMessage(gateway, receiveId, sender, payload)](#ERC7786Recipient-_processMessage-address-bytes32-bytes-bytes-) -#### IERC7786Recipient [!toc] + +
+
+
+ +
+

Events

+
+- [CrosschainControllerSet(gateway, controller)](#CrosschainRemoteExecutor-CrosschainControllerSet-address-bytes-)

Errors

+- [AccessRestricted()](#CrosschainRemoteExecutor-AccessRestricted--) +
+ERC7786Recipient + - [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) -- [ERC7786RecipientMessageAlreadyProcessed(gateway, receiveId)](#ERC7786Recipient-ERC7786RecipientMessageAlreadyProcessed-address-bytes32-) -#### IERC7786Recipient [!toc] + +
- +
-

receiveMessage(bytes32 receiveId, bytes sender, bytes payload) โ†’ bytes4

+

constructor(address initialGateway, bytes initialController)

-

external

-# +

public

+#
-Endpoint for receiving cross-chain message. +
+
-This function may be called directly by the gateway. + + +
+
+

gateway() โ†’ address

+
+

public

+# +
+
+
+ +Accessor that returns the address of the gateway used by this remote executor.
- +
-

_isAuthorizedGateway(address gateway, bytes sender) โ†’ bool

+

controller() โ†’ bytes

+
+

public

+# +
+
+
+ +Accessor that returns the interoperable address of the controller allowed to relay instructions to this +remote executor. + +
+
+ + + +
+
+

reconfigure(address newGateway, bytes newController)

+
+

public

+# +
+
+
+ +Endpoint allowing the controller to reconfigure the executor. This must be called by the executor itself +following an instruction from the controller. + +
+
+ + + +
+
+

_setup(address gateway_, bytes controller_)

internal

-# +# +
+
+
+ +Internal setter to reconfigure the gateway and controller. + +
+
+ + + +
+
+

_isAuthorizedGateway(address instance, bytes sender) โ†’ bool

+
+

internal

+#
@@ -100,49 +407,1500 @@ of a message.
- +
-

_processMessage(address gateway, bytes32 receiveId, bytes sender, bytes payload)

+

_processMessage(address, bytes32, bytes, bytes payload)

internal

-# +#
Virtual function that should contain the logic to execute when a cross-chain message is received. + +This function should revert on failure. Any silent failure from this function will result in the message +being marked as received and not being retryable. + +
- +
-

ERC7786RecipientUnauthorizedGateway(address gateway, bytes sender)

+

CrosschainControllerSet(address gateway, bytes controller)

-

error

-# +

event

+#
+
+Emitted when the gateway or controller of this remote executor is updated. +
- +
-

ERC7786RecipientMessageAlreadyProcessed(address gateway, bytes32 receiveId)

+

AccessRestricted()

error

-# +#
+Reverted when a non-controller tries to relay instructions to this executor. +
+ + + +
+ +## `ERC7786Recipient` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/ERC7786Recipient.sol"; +``` + +Base implementation of an ERC-7786 compliant cross-chain message receiver. + +This abstract contract exposes the `receiveMessage` function that is used for communication with (one or multiple) +destination gateways. This contract leaves two functions unimplemented: + +* [`CrosschainLinked._isAuthorizedGateway`](#CrosschainLinked-_isAuthorizedGateway-address-bytes-), an internal getter used to verify whether an address is recognised by the contract as a +valid ERC-7786 destination gateway. One or multiple gateway can be supported. Note that any malicious address for +which this function returns true would be able to impersonate any account on any other chain sending any message. + +* [`CrosschainRemoteExecutor._processMessage`](#CrosschainRemoteExecutor-_processMessage-address-bytes32-bytes-bytes-), the internal function that will be called with any message that has been validated. + +ERC-7786 requires the gateway to ensure messages are not delivered more than once. Therefore, we don't need to keep +track of the processed receiveId. + +@custom:stateless + +
+

Functions

+
+- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) +- [_isAuthorizedGateway(gateway, sender)](#ERC7786Recipient-_isAuthorizedGateway-address-bytes-) +- [_processMessage(gateway, receiveId, sender, payload)](#ERC7786Recipient-_processMessage-address-bytes32-bytes-bytes-) +
+
+ +
+

Errors

+
+- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) +
+
+ + + +
+
+

receiveMessage(bytes32 receiveId, bytes sender, bytes payload) โ†’ bytes4

+
+

external

+# +
+
+
+ +Endpoint for receiving cross-chain message. + +This function may be called directly by the gateway. + +
+
+ + + +
+
+

_isAuthorizedGateway(address gateway, bytes sender) โ†’ bool

+
+

internal

+# +
+
+
+ +Virtual getter that returns whether an address is a valid ERC-7786 gateway for a given sender. + +The `sender` parameter is an interoperable address that include the source chain. The chain part can be +extracted using the [`InteroperableAddress`](/contracts/5.x/api/utils#InteroperableAddress) library to selectively authorize gateways based on the origin chain +of a message. + +
+
+ + + +
+
+

_processMessage(address gateway, bytes32 receiveId, bytes sender, bytes payload)

+
+

internal

+# +
+
+
+ +Virtual function that should contain the logic to execute when a cross-chain message is received. + + +This function should revert on failure. Any silent failure from this function will result in the message +being marked as received and not being retryable. + + +
+
+ + + +
+
+

ERC7786RecipientUnauthorizedGateway(address gateway, bytes sender)

+
+

error

+# +
+
+
+ +Error thrown if the gateway is not authorized to send messages to this contract on behalf of the sender. + +
+
+ + + +
+ +## `BridgeERC1155` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/bridges/BridgeERC1155.sol"; +``` + +This is a variant of [`BridgeMultiToken`](#BridgeMultiToken) that implements the bridge logic for ERC-1155 tokens that do not expose +a crosschain mint and burn mechanism. Instead, it takes custody of bridged assets. + +
+

Functions

+
+- [constructor(token_)](#BridgeERC1155-constructor-contract-IERC1155-) +- [token()](#BridgeERC1155-token--) +- [crosschainTransferFrom(from, to, id, value)](#BridgeERC1155-crosschainTransferFrom-address-bytes-uint256-uint256-) +- [crosschainTransferFrom(from, to, ids, values)](#BridgeERC1155-crosschainTransferFrom-address-bytes-uint256---uint256---) +- [_onSend(from, ids, values)](#BridgeERC1155-_onSend-address-uint256---uint256---) +- [_onReceive(to, ids, values)](#BridgeERC1155-_onReceive-address-uint256---uint256---) +- [onERC1155Received(operator, , , , )](#BridgeERC1155-onERC1155Received-address-address-uint256-uint256-bytes-) +- [onERC1155BatchReceived(operator, , , , )](#BridgeERC1155-onERC1155BatchReceived-address-address-uint256---uint256---bytes-) +
+ERC1155Holder + +- [supportsInterface(interfaceId)](#ERC1155Holder-supportsInterface-bytes4-) + +
+
+BridgeMultiToken + +- [_crosschainTransfer(from, to, ids, values)](#BridgeMultiToken-_crosschainTransfer-address-bytes-uint256---uint256---) +- [_processMessage(, receiveId, , payload)](#BridgeMultiToken-_processMessage-address-bytes32-bytes-bytes-) + +
+
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+
+ +
+

Events

+
+
+BridgeMultiToken + +- [CrosschainMultiTokenTransferSent(sendId, from, to, ids, values)](#BridgeMultiToken-CrosschainMultiTokenTransferSent-bytes32-address-bytes-uint256---uint256---) +- [CrosschainMultiTokenTransferReceived(receiveId, from, to, ids, values)](#BridgeMultiToken-CrosschainMultiTokenTransferReceived-bytes32-bytes-address-uint256---uint256---) + +
+
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+
+ + + +
+
+

constructor(contract IERC1155 token_)

+
+

internal

+# +
+
+
+ +
+
+ + + +
+
+

token() โ†’ contract IERC1155

+
+

public

+# +
+
+
+ +
+
+ + + +
+
+

crosschainTransferFrom(address from, bytes to, uint256 id, uint256 value) โ†’ bytes32

+
+

public

+# +
+
+
+ +Transfer `amount` tokens to a crosschain receiver. + +Note: The `to` parameter is the full InteroperableAddress (chain ref + address). + +
+
+ + + +
+
+

crosschainTransferFrom(address from, bytes to, uint256[] ids, uint256[] values) โ†’ bytes32

+
+

public

+# +
+
+
+ +Transfer `amount` tokens to a crosschain receiver. + +Note: The `to` parameter is the full InteroperableAddress (chain ref + address). + +
+
+ + + +
+
+

_onSend(address from, uint256[] ids, uint256[] values)

+
+

internal

+# +
+
+
+ +"Locking" tokens is done by taking custody + +
+
+ + + +
+
+

_onReceive(address to, uint256[] ids, uint256[] values)

+
+

internal

+# +
+
+
+ +"Unlocking" tokens is done by releasing custody + +
+
+ + + +
+
+

onERC1155Received(address operator, address, uint256, uint256, bytes) โ†’ bytes4

+
+

public

+# +
+
+
+ +Support receiving tokens only if the transfer was initiated by the bridge itself. + +
+
+ + + +
+
+

onERC1155BatchReceived(address operator, address, uint256[], uint256[], bytes) โ†’ bytes4

+
+

public

+# +
+
+
+ +Support receiving tokens only if the transfer was initiated by the bridge itself. + +
+
+ + + +
+ +## `BridgeERC20` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/bridges/BridgeERC20.sol"; +``` + +This is a variant of [`BridgeFungible`](#BridgeFungible) that implements the bridge logic for ERC-20 tokens that do not expose a +crosschain mint and burn mechanism. Instead, it takes custody of bridged assets. + +
+

Functions

+
+- [constructor(token_)](#BridgeERC20-constructor-contract-IERC20-) +- [token()](#BridgeERC20-token--) +- [_onSend(from, amount)](#BridgeERC20-_onSend-address-uint256-) +- [_onReceive(to, amount)](#BridgeERC20-_onReceive-address-uint256-) +
+BridgeFungible + +- [crosschainTransfer(to, amount)](#BridgeFungible-crosschainTransfer-bytes-uint256-) +- [_crosschainTransfer(from, to, amount)](#BridgeFungible-_crosschainTransfer-address-bytes-uint256-) +- [_processMessage(, receiveId, , payload)](#BridgeFungible-_processMessage-address-bytes32-bytes-bytes-) + +
+
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+
+ +
+

Events

+
+
+BridgeFungible + +- [CrosschainFungibleTransferSent(sendId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferSent-bytes32-address-bytes-uint256-) +- [CrosschainFungibleTransferReceived(receiveId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferReceived-bytes32-bytes-address-uint256-) + +
+
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+
+ + + +
+
+

constructor(contract IERC20 token_)

+
+

internal

+# +
+
+
+ +
+
+ + + +
+
+

token() โ†’ contract IERC20

+
+

public

+# +
+
+
+ +
+
+ + + +
+
+

_onSend(address from, uint256 amount)

+
+

internal

+# +
+
+
+ +"Locking" tokens is done by taking custody + +
+
+ + + +
+
+

_onReceive(address to, uint256 amount)

+
+

internal

+# +
+
+
+ +"Unlocking" tokens is done by releasing custody + +
+
+ + + +
+ +## `BridgeERC721` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/bridges/BridgeERC721.sol"; +``` + +This is a variant of [`BridgeNonFungible`](#BridgeNonFungible) that implements the bridge logic for ERC-721 tokens that do not expose +a crosschain mint and burn mechanism. Instead, it takes custody of bridged assets. + +
+

Functions

+
+- [constructor(token_)](#BridgeERC721-constructor-contract-IERC721-) +- [token()](#BridgeERC721-token--) +- [crosschainTransferFrom(from, to, tokenId)](#BridgeERC721-crosschainTransferFrom-address-bytes-uint256-) +- [_onSend(from, tokenId)](#BridgeERC721-_onSend-address-uint256-) +- [_onReceive(to, tokenId)](#BridgeERC721-_onReceive-address-uint256-) +
+BridgeNonFungible + +- [_crosschainTransfer(from, to, tokenId)](#BridgeNonFungible-_crosschainTransfer-address-bytes-uint256-) +- [_processMessage(, receiveId, , payload)](#BridgeNonFungible-_processMessage-address-bytes32-bytes-bytes-) + +
+
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+
+ +
+

Events

+
+
+BridgeNonFungible + +- [CrosschainNonFungibleTransferSent(sendId, from, to, tokenId)](#BridgeNonFungible-CrosschainNonFungibleTransferSent-bytes32-address-bytes-uint256-) +- [CrosschainNonFungibleTransferReceived(receiveId, from, to, tokenId)](#BridgeNonFungible-CrosschainNonFungibleTransferReceived-bytes32-bytes-address-uint256-) + +
+
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+
+ + + +
+
+

constructor(contract IERC721 token_)

+
+

internal

+# +
+
+
+ +
+
+ + + +
+
+

token() โ†’ contract IERC721

+
+

public

+# +
+
+
+ +
+
+ + + +
+
+

crosschainTransferFrom(address from, bytes to, uint256 tokenId) โ†’ bytes32

+
+

public

+# +
+
+
+ +Transfer `tokenId` from `from` (on this chain) to `to` (on a different chain). + +The `to` parameter is the full InteroperableAddress that references both the destination chain and the account +on that chain. Similarly to the underlying token's [`ERC721.transferFrom`](/contracts/5.x/api/token/ERC721#ERC721-transferFrom-address-address-uint256-) function, this function can be called +either by the token holder or by anyone that is approved by the token holder. It reuses the token's allowance +system, meaning that an account that is "approved for all" or "approved for tokenId" can perform the crosschain +transfer directly without having to take temporary custody of the token. + +
+
+ + + +
+
+

_onSend(address from, uint256 tokenId)

+
+

internal

+# +
+
+
+ +"Locking" tokens is done by taking custody + +
+
+ + + +
+
+

_onReceive(address to, uint256 tokenId)

+
+

internal

+# +
+
+
+ +"Unlocking" tokens is done by releasing custody + +
+
+ + + +
+ +## `BridgeERC7802` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/bridges/BridgeERC7802.sol"; +``` + +This is a variant of [`BridgeFungible`](#BridgeFungible) that implements the bridge logic for ERC-7802 compliant tokens. + +
+

Functions

+
+- [constructor(token_)](#BridgeERC7802-constructor-contract-IERC7802-) +- [token()](#BridgeERC7802-token--) +- [_onSend(from, amount)](#BridgeERC7802-_onSend-address-uint256-) +- [_onReceive(to, amount)](#BridgeERC7802-_onReceive-address-uint256-) +
+BridgeFungible + +- [crosschainTransfer(to, amount)](#BridgeFungible-crosschainTransfer-bytes-uint256-) +- [_crosschainTransfer(from, to, amount)](#BridgeFungible-_crosschainTransfer-address-bytes-uint256-) +- [_processMessage(, receiveId, , payload)](#BridgeFungible-_processMessage-address-bytes32-bytes-bytes-) + +
+
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+
+ +
+

Events

+
+
+BridgeFungible + +- [CrosschainFungibleTransferSent(sendId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferSent-bytes32-address-bytes-uint256-) +- [CrosschainFungibleTransferReceived(receiveId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferReceived-bytes32-bytes-address-uint256-) + +
+
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+
+ + + +
+
+

constructor(contract IERC7802 token_)

+
+

internal

+# +
+
+
+ +
+
+ + + +
+
+

token() โ†’ contract IERC7802

+
+

public

+# +
+
+
+ +
+
+ + + +
+
+

_onSend(address from, uint256 amount)

+
+

internal

+# +
+
+
+ +"Locking" tokens using an ERC-7802 crosschain burn + +
+
+ + + +
+
+

_onReceive(address to, uint256 amount)

+
+

internal

+# +
+
+
+ +"Unlocking" tokens using an ERC-7802 crosschain mint + +
+
+ + + +
+ +## `BridgeFungible` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/bridges/abstract/BridgeFungible.sol"; +``` + +Base contract for bridging ERC-20 between chains using an ERC-7786 gateway. + +In order to use this contract, two functions must be implemented to link it to the token: +* [`BridgeERC1155._onSend`](#BridgeERC1155-_onSend-address-uint256---uint256---): called when a crosschain transfer is going out. Must take the sender tokens or revert. +* [`BridgeERC1155._onReceive`](#BridgeERC1155-_onReceive-address-uint256---uint256---): called when a crosschain transfer is coming in. Must give tokens to the receiver. + +This base contract is used by the [`BridgeERC20`](#BridgeERC20), which interfaces with legacy ERC-20 tokens, and [`BridgeERC7802`](#BridgeERC7802), +which interface with ERC-7802 to provide an approve-free user experience. It is also used by the [`ERC20Crosschain`](/contracts/5.x/api/token/ERC20#ERC20Crosschain) +extension, which embeds the bridge logic directly in the token contract. + +
+

Functions

+
+- [crosschainTransfer(to, amount)](#BridgeFungible-crosschainTransfer-bytes-uint256-) +- [_crosschainTransfer(from, to, amount)](#BridgeFungible-_crosschainTransfer-address-bytes-uint256-) +- [_processMessage(, receiveId, , payload)](#BridgeFungible-_processMessage-address-bytes32-bytes-bytes-) +- [_onSend(from, amount)](#BridgeFungible-_onSend-address-uint256-) +- [_onReceive(to, amount)](#BridgeFungible-_onReceive-address-uint256-) +
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+
+ +
+

Events

+
+- [CrosschainFungibleTransferSent(sendId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferSent-bytes32-address-bytes-uint256-) +- [CrosschainFungibleTransferReceived(receiveId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferReceived-bytes32-bytes-address-uint256-) +
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+
+ + + +
+
+

crosschainTransfer(bytes to, uint256 amount) โ†’ bytes32

+
+

public

+# +
+
+
+ +Transfer `amount` tokens to a crosschain receiver. + +Note: The `to` parameter is the full InteroperableAddress (chain ref + address). + +
+
+ + + +
+
+

_crosschainTransfer(address from, bytes to, uint256 amount) โ†’ bytes32

+
+

internal

+# +
+
+
+ +Internal crosschain transfer function. + +Note: The `to` parameter is the full InteroperableAddress (chain ref + address). + +
+
+ + + +
+
+

_processMessage(address, bytes32 receiveId, bytes, bytes payload)

+
+

internal

+# +
+
+
+ +Virtual function that should contain the logic to execute when a cross-chain message is received. + + +This function should revert on failure. Any silent failure from this function will result in the message +being marked as received and not being retryable. + + +
+
+ + + +
+
+

_onSend(address from, uint256 amount)

+
+

internal

+# +
+
+
+ +Virtual function: implementation is required to handle token being burnt or locked on the source chain. + +
+
+ + + +
+
+

_onReceive(address to, uint256 amount)

+
+

internal

+# +
+
+
+ +Virtual function: implementation is required to handle token being minted or unlocked on the destination chain. + +
+
+ + + +
+
+

CrosschainFungibleTransferSent(bytes32 indexed sendId, address indexed from, bytes to, uint256 amount)

+
+

event

+# +
+
+ +
+ +Emitted when a crosschain ERC-20 transfer is sent. + +
+
+ + +
+
+

CrosschainFungibleTransferReceived(bytes32 indexed receiveId, bytes from, address indexed to, uint256 amount)

+
+

event

+# +
+
+ +
+ +Emitted when a crosschain ERC-20 transfer is received. + +
+
+ + + +
+ +## `BridgeMultiToken` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/bridges/abstract/BridgeMultiToken.sol"; +``` + +Base contract for bridging ERC-1155 between chains using an ERC-7786 gateway. + +In order to use this contract, two functions must be implemented to link it to the token: +* [`BridgeERC1155._onSend`](#BridgeERC1155-_onSend-address-uint256---uint256---): called when a crosschain transfer is going out. Must take the sender tokens or revert. +* [`BridgeERC1155._onReceive`](#BridgeERC1155-_onReceive-address-uint256---uint256---): called when a crosschain transfer is coming in. Must give tokens to the receiver. + +This base contract is used by the [`BridgeERC1155`](#BridgeERC1155), which interfaces with legacy ERC-1155 tokens. It is also used by +the [`ERC1155Crosschain`](/contracts/5.x/api/token/ERC1155#ERC1155Crosschain) extension, which embeds the bridge logic directly in the token contract. + +This base contract implements the crosschain transfer operation though internal functions. It is for the the "child +contracts" that inherit from this to implement the external interfaces and make this functions accessible. + +
+

Functions

+
+- [_crosschainTransfer(from, to, ids, values)](#BridgeMultiToken-_crosschainTransfer-address-bytes-uint256---uint256---) +- [_processMessage(, receiveId, , payload)](#BridgeMultiToken-_processMessage-address-bytes32-bytes-bytes-) +- [_onSend(from, ids, values)](#BridgeMultiToken-_onSend-address-uint256---uint256---) +- [_onReceive(to, ids, values)](#BridgeMultiToken-_onReceive-address-uint256---uint256---) +
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+
+ +
+

Events

+
+- [CrosschainMultiTokenTransferSent(sendId, from, to, ids, values)](#BridgeMultiToken-CrosschainMultiTokenTransferSent-bytes32-address-bytes-uint256---uint256---) +- [CrosschainMultiTokenTransferReceived(receiveId, from, to, ids, values)](#BridgeMultiToken-CrosschainMultiTokenTransferReceived-bytes32-bytes-address-uint256---uint256---) +
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+
+ + + +
+
+

_crosschainTransfer(address from, bytes to, uint256[] ids, uint256[] values) โ†’ bytes32

+
+

internal

+# +
+
+
+ +Internal crosschain transfer function. + +Note: The `to` parameter is the full InteroperableAddress (chain ref + address). + +
+
+ + + +
+
+

_processMessage(address, bytes32 receiveId, bytes, bytes payload)

+
+

internal

+# +
+
+
+ +Virtual function that should contain the logic to execute when a cross-chain message is received. + + +This function should revert on failure. Any silent failure from this function will result in the message +being marked as received and not being retryable. + + +
+
+ + + +
+
+

_onSend(address from, uint256[] ids, uint256[] values)

+
+

internal

+# +
+
+
+ +Virtual function: implementation is required to handle token being burnt or locked on the source chain. + +
+
+ + + +
+
+

_onReceive(address to, uint256[] ids, uint256[] values)

+
+

internal

+# +
+
+
+ +Virtual function: implementation is required to handle token being minted or unlocked on the destination chain. + +
+
+ + + +
+
+

CrosschainMultiTokenTransferSent(bytes32 indexed sendId, address indexed from, bytes to, uint256[] ids, uint256[] values)

+
+

event

+# +
+
+ +
+ +
+
+ + +
+
+

CrosschainMultiTokenTransferReceived(bytes32 indexed receiveId, bytes from, address indexed to, uint256[] ids, uint256[] values)

+
+

event

+# +
+
+ +
+ +
+
+ + + +
+ +## `BridgeNonFungible` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/crosschain/bridges/abstract/BridgeNonFungible.sol"; +``` + +Base contract for bridging ERC-721 between chains using an ERC-7786 gateway. + +In order to use this contract, two functions must be implemented to link it to the token: +* [`BridgeERC1155._onSend`](#BridgeERC1155-_onSend-address-uint256---uint256---): called when a crosschain transfer is going out. Must take the sender tokens or revert. +* [`BridgeERC1155._onReceive`](#BridgeERC1155-_onReceive-address-uint256---uint256---): called when a crosschain transfer is coming in. Must give tokens to the receiver. + +This base contract is used by the [`BridgeERC721`](#BridgeERC721), which interfaces with legacy ERC-721 tokens. It is also used by +the [`ERC721Crosschain`](/contracts/5.x/api/token/ERC721#ERC721Crosschain) extension, which embeds the bridge logic directly in the token contract. + +
+

Functions

+
+- [_crosschainTransfer(from, to, tokenId)](#BridgeNonFungible-_crosschainTransfer-address-bytes-uint256-) +- [_processMessage(, receiveId, , payload)](#BridgeNonFungible-_processMessage-address-bytes32-bytes-bytes-) +- [_onSend(from, tokenId)](#BridgeNonFungible-_onSend-address-uint256-) +- [_onReceive(to, tokenId)](#BridgeNonFungible-_onReceive-address-uint256-) +
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+
+ +
+

Events

+
+- [CrosschainNonFungibleTransferSent(sendId, from, to, tokenId)](#BridgeNonFungible-CrosschainNonFungibleTransferSent-bytes32-address-bytes-uint256-) +- [CrosschainNonFungibleTransferReceived(receiveId, from, to, tokenId)](#BridgeNonFungible-CrosschainNonFungibleTransferReceived-bytes32-bytes-address-uint256-) +
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+
+ + + +
+
+

_crosschainTransfer(address from, bytes to, uint256 tokenId) โ†’ bytes32

+
+

internal

+# +
+
+
+ +Internal crosschain transfer function. + + +The `to` parameter is the full InteroperableAddress (chain ref + address). + + +
+
+ + + +
+
+

_processMessage(address, bytes32 receiveId, bytes, bytes payload)

+
+

internal

+# +
+
+
+ +Virtual function that should contain the logic to execute when a cross-chain message is received. + + +This function should revert on failure. Any silent failure from this function will result in the message +being marked as received and not being retryable. + + +
+
+ + + +
+
+

_onSend(address from, uint256 tokenId)

+
+

internal

+# +
+
+
+ +Virtual function: implementation is required to handle token being burnt or locked on the source chain. + +
+
+ + + +
+
+

_onReceive(address to, uint256 tokenId)

+
+

internal

+# +
+
+
+ +Virtual function: implementation is required to handle token being minted or unlocked on the destination chain. + +
+
+ + + +
+
+

CrosschainNonFungibleTransferSent(bytes32 indexed sendId, address indexed from, bytes to, uint256 tokenId)

+
+

event

+# +
+
+ +
+ +Emitted when a crosschain ERC-721 transfer is sent. + +
+
+ + +
+
+

CrosschainNonFungibleTransferReceived(bytes32 indexed receiveId, bytes from, address indexed to, uint256 tokenId)

+
+

event

+# +
+
+ +
+ +Emitted when a crosschain ERC-721 transfer is received. + +
+
+ diff --git a/content/contracts/5.x/api/finance.mdx b/content/contracts/5.x/api/finance.mdx index 3dea4798..3b652257 100644 --- a/content/contracts/5.x/api/finance.mdx +++ b/content/contracts/5.x/api/finance.mdx @@ -17,9 +17,9 @@ This directory includes primitives for financial systems:
-## `VestingWallet` +## `VestingWallet` - + @@ -75,12 +75,16 @@ Consider disabling one of the withdrawal methods. - [vestedAmount(timestamp)](#VestingWallet-vestedAmount-uint64-) - [vestedAmount(token, timestamp)](#VestingWallet-vestedAmount-address-uint64-) - [_vestingSchedule(totalAllocation, timestamp)](#VestingWallet-_vestingSchedule-uint256-uint64-) -#### Ownable [!toc] +
+Ownable + - [owner()](#Ownable-owner--) - [_checkOwner()](#Ownable-_checkOwner--) - [renounceOwnership()](#Ownable-renounceOwnership--) - [transferOwnership(newOwner)](#Ownable-transferOwnership-address-) - [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-) + +
@@ -89,17 +93,25 @@ Consider disabling one of the withdrawal methods.
- [EtherReleased(amount)](#VestingWallet-EtherReleased-uint256-) - [ERC20Released(token, amount)](#VestingWallet-ERC20Released-address-uint256-) -#### Ownable [!toc] +
+Ownable + - [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-) + +

Errors

-#### Ownable [!toc] +
+Ownable + - [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-) + +
@@ -383,9 +395,9 @@ an asset given its total historical allocation.
-## `VestingWalletCliff` +## `VestingWalletCliff` - + @@ -405,7 +417,9 @@ _Available since v5.1._ - [constructor(cliffSeconds)](#VestingWalletCliff-constructor-uint64-) - [cliff()](#VestingWalletCliff-cliff--) - [_vestingSchedule(totalAllocation, timestamp)](#VestingWalletCliff-_vestingSchedule-uint256-uint64-) -#### VestingWallet [!toc] +
+VestingWallet + - [receive()](#VestingWallet-receive--) - [start()](#VestingWallet-start--) - [duration()](#VestingWallet-duration--) @@ -418,23 +432,37 @@ _Available since v5.1._ - [release(token)](#VestingWallet-release-address-) - [vestedAmount(timestamp)](#VestingWallet-vestedAmount-uint64-) - [vestedAmount(token, timestamp)](#VestingWallet-vestedAmount-address-uint64-) -#### Ownable [!toc] + +
+
+Ownable + - [owner()](#Ownable-owner--) - [_checkOwner()](#Ownable-_checkOwner--) - [renounceOwnership()](#Ownable-renounceOwnership--) - [transferOwnership(newOwner)](#Ownable-transferOwnership-address-) - [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-) + +

Events

-#### VestingWallet [!toc] +
+VestingWallet + - [EtherReleased(amount)](#VestingWallet-EtherReleased-uint256-) - [ERC20Released(token, amount)](#VestingWallet-ERC20Released-address-uint256-) -#### Ownable [!toc] + +
+
+Ownable + - [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-) + +
@@ -442,10 +470,13 @@ _Available since v5.1._

Errors

- [InvalidCliffDuration(cliffSeconds, durationSeconds)](#VestingWalletCliff-InvalidCliffDuration-uint64-uint64-) -#### VestingWallet [!toc] -#### Ownable [!toc] +
+Ownable + - [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-) + +
@@ -524,3 +555,4 @@ The specified cliff duration is larger than the vesting duration.
+ diff --git a/content/contracts/5.x/api/governance.mdx b/content/contracts/5.x/api/governance.mdx index d177b40a..8941a9ea 100644 --- a/content/contracts/5.x/api/governance.mdx +++ b/content/contracts/5.x/api/governance.mdx @@ -37,12 +37,13 @@ Timelock extensions add a delay for governance decisions to be executed. The wor Other extensions can customize the behavior or interface in multiple ways. -* [`GovernorStorage`](#GovernorStorage): Stores the proposal details onchain and provides enumerability of the proposals. This can be useful for some L2 chains where storage is cheap compared to calldata. -* [`GovernorSettings`](#GovernorSettings): Manages some of the settings (voting delay, voting period duration, and proposal threshold) in a way that can be updated through a governance proposal, without requiring an upgrade. +* [`GovernorCrosschain`](#GovernorCrosschain): Helps with the execution of crosschain operation using `CrosschainRemoteExector` and ERC-7786 gateways. +* [`GovernorNoncesKeyed`](#GovernorNoncesKeyed): An extension of [`Governor`](#Governor) with support for keyed nonces in addition to traditional nonces when voting by signature. * [`GovernorPreventLateQuorum`](#GovernorPreventLateQuorum): Ensures there is a minimum voting period after quorum is reached as a security protection against large voters. * [`GovernorProposalGuardian`](#GovernorProposalGuardian): Adds a proposal guardian that can cancel proposals at any stage in their lifecycle--this permission is passed on to the proposers if the guardian is not set. +* [`GovernorSettings`](#GovernorSettings): Manages some of the settings (voting delay, voting period duration, and proposal threshold) in a way that can be updated through a governance proposal, without requiring an upgrade. +* [`GovernorStorage`](#GovernorStorage): Stores the proposal details onchain and provides enumerability of the proposals. This can be useful for some L2 chains where storage is cheap compared to calldata. * [`GovernorSuperQuorum`](#GovernorSuperQuorum): Extension of [`Governor`](#Governor) with a super quorum. Proposals that meet the super quorum (and have a majority of for votes) advance to the `Succeeded` state before the proposal deadline. -* [`GovernorNoncesKeyed`](#GovernorNoncesKeyed): An extension of [`Governor`](#Governor) with support for keyed nonces in addition to traditional nonces when voting by signature. In addition to modules and extensions, the core contract requires a few virtual functions to be implemented to your particular specifications: @@ -82,17 +83,19 @@ Functions of the `Governor` contract do not include access control. If you want [`GovernorTimelockCompound`](#GovernorTimelockCompound) -[`GovernorSettings`](#GovernorSettings) +[`GovernorCrosschain`](#GovernorCrosschain) -[`GovernorPreventLateQuorum`](#GovernorPreventLateQuorum) +[`GovernorNoncesKeyed`](#GovernorNoncesKeyed) -[`GovernorStorage`](#GovernorStorage) +[`GovernorPreventLateQuorum`](#GovernorPreventLateQuorum) [`GovernorProposalGuardian`](#GovernorProposalGuardian) -[`GovernorSuperQuorum`](#GovernorSuperQuorum) +[`GovernorSettings`](#GovernorSettings) -[`GovernorNoncesKeyed`](#GovernorNoncesKeyed) +[`GovernorStorage`](#GovernorStorage) + +[`GovernorSuperQuorum`](#GovernorSuperQuorum) ## Utils @@ -123,7 +126,7 @@ In a governance system, the [`TimelockController`](#TimelockController) contract #### Operation structure -Operation executed by the [`TimelockController`](contracts/5.x/api/governance#TimelockController) can contain one or multiple subsequent calls. Depending on whether you need to multiple calls to be executed atomically, you can either use simple or batched operations. +Operation executed by the [`TimelockController`](/contracts/5.x/api/governance#TimelockController) can contain one or multiple subsequent calls. Depending on whether you need multiple calls to be executed atomically, you can either use simple or batched operations. Both operations contain: @@ -146,16 +149,16 @@ Timelocked operations are identified by a unique id (their hash) and follow a sp `Unset` -> `Pending` -> `Pending` + `Ready` -> `Done` -* By calling [`schedule`](contracts/5.x/api/governance#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-) (or [`scheduleBatch`](contracts/5.x/api/governance#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-)), a proposer moves the operation from the `Unset` to the `Pending` state. This starts a timer that must be longer than the minimum delay. The timer expires at a timestamp accessible through the [`getTimestamp`](contracts/5.x/api/governance#TimelockController-getTimestamp-bytes32-) method. +* By calling [`schedule`](/contracts/5.x/api/governance#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-) (or [`scheduleBatch`](/contracts/5.x/api/governance#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-)), a proposer moves the operation from the `Unset` to the `Pending` state. This starts a timer that must be longer than the minimum delay. The timer expires at a timestamp accessible through the [`getTimestamp`](/contracts/5.x/api/governance#TimelockController-getTimestamp-bytes32-) method. * Once the timer expires, the operation automatically gets the `Ready` state. At this point, it can be executed. -* By calling [`execute`](contracts/5.x/api/governance#TimelockController-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-) (or [`executeBatch`](contracts/5.x/api/governance#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-)), an executor triggers the operationโ€™s underlying transactions and moves it to the `Done` state. If the operation has a predecessor, it has to be in the `Done` state for this transition to succeed. -* [`cancel`](contracts/5.x/api/governance#TimelockController-TimelockController-cancel-bytes32-) allows proposers to cancel any `Pending` operation. This resets the operation to the `Unset` state. It is thus possible for a proposer to re-schedule an operation that has been cancelled. In this case, the timer restarts when the operation is rescheduled. +* By calling [`execute`](/contracts/5.x/api/governance#TimelockController-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-) (or [`executeBatch`](/contracts/5.x/api/governance#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-)), an executor triggers the operationโ€™s underlying transactions and moves it to the `Done` state. If the operation has a predecessor, it has to be in the `Done` state for this transition to succeed. +* [`cancel`](/contracts/5.x/api/governance#TimelockController-TimelockController-cancel-bytes32-) allows proposers to cancel any `Pending` operation. This resets the operation to the `Unset` state. It is thus possible for a proposer to re-schedule an operation that has been cancelled. In this case, the timer restarts when the operation is rescheduled. Operations status can be queried using the functions: -* [`isOperationPending(bytes32)`](contracts/5.x/api/governance#TimelockController-isOperationPending-bytes32-) -* [`isOperationReady(bytes32)`](contracts/5.x/api/governance#TimelockController-isOperationReady-bytes32-) -* [`isOperationDone(bytes32)`](contracts/5.x/api/governance#TimelockController-isOperationDone-bytes32-) +* [`isOperationPending(bytes32)`](/contracts/5.x/api/governance#TimelockController-isOperationPending-bytes32-) +* [`isOperationReady(bytes32)`](/contracts/5.x/api/governance#TimelockController-isOperationReady-bytes32-) +* [`isOperationDone(bytes32)`](/contracts/5.x/api/governance#TimelockController-isOperationDone-bytes32-) #### Roles @@ -168,7 +171,7 @@ The admins are in charge of managing proposers and executors. For the timelock t The proposers are in charge of scheduling (and cancelling) operations. This is a critical role, that should be given to governing entities. This could be an EOA, a multisig, or a DAO. -**Proposer fight:** Having multiple proposers, while providing redundancy in case one becomes unavailable, can be dangerous. As proposer have their say on all operations, they could cancel operations they disagree with, including operations to remove them for the proposers. +**Proposer fight:** Having multiple proposers, while providing redundancy in case one becomes unavailable, can be dangerous. Proposers have a say on all operations--they could cancel operations they disagree with, including operations to remove them from the list of proposers. This role is identified by the **PROPOSER_ROLE** value: `0xb09aa5aeb3702cfd50b6b62bc4532604938f21248a27a1d5ca736082b6819cc1` @@ -187,9 +190,9 @@ A live contract without at least one proposer and one executor is locked. Make s
-## `Governor` +## `Governor` - + @@ -273,56 +276,63 @@ This contract is abstract and requires several functions to be implemented in va - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -335,17 +345,17 @@ This contract is abstract and requires several functions to be implemented in va - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -367,7 +377,7 @@ parameter setters in [`GovernorSettings`](#GovernorSettings) are protected using The governance executing address may be different from the Governor's own address, for example it could be a timelock. This can be customized by modules by overriding [`Governor._executor`](#Governor-_executor--). The executor is only able to invoke these -functions during the execution of the governor's [`AccessManager.execute`](/contracts/5.x/api/access#AccessManager-execute-address-bytes-) function, and not under any other circumstances. Thus, +functions during the execution of the governor's [`Governor.execute`](#Governor-execute-address---uint256---bytes---bytes32-) function, and not under any other circumstances. Thus, for example, additional timelock proposers are not able to change governance parameters without going through the governance protocol (since v4.6). @@ -645,7 +655,7 @@ Whether a proposal needs to be queued before execution.
Reverts if the `msg.sender` is not the executor. In case the executor is not this contract -itself, the function reverts if `msg.data` is not whitelisted as a result of an [`AccessManager.execute`](/contracts/5.x/api/access#AccessManager-execute-address-bytes-) +itself, the function reverts if `msg.data` is not whitelisted as a result of an [`Governor.execute`](#Governor-execute-address---uint256---bytes---bytes32-) operation. See [`Governor.onlyGovernance`](#Governor-onlyGovernance--).
@@ -888,7 +898,7 @@ performed (for example adding a vault/timelock). Calling this function directly will NOT check the current state of the proposal, set the executed flag to -true or emit the `ProposalExecuted` event. Executing a proposal should be done using [`AccessManager.execute`](/contracts/5.x/api/access#AccessManager-execute-address-bytes-). +true or emit the `ProposalExecuted` event. Executing a proposal should be done using [`Governor.execute`](#Governor-execute-address---uint256---bytes---bytes32-).
@@ -1291,6 +1301,23 @@ If requirements are not met, reverts with a [`IGovernor.GovernorUnexpectedPropos
+Check if the proposer is authorized to submit a proposal with the given description. + +If the proposal description ends with `#proposer=0x???`, where `0x???` is an address written as a hex string +(case insensitive), then the submission of this proposal will only be authorized to said address. + +This is used for frontrunning protection. By adding this pattern at the end of their proposal, one can ensure +that no other address can submit the same proposal. An attacker would have to either remove or change that part, +which would result in a different proposal id. + +If the description does not match this pattern, it is unrestricted and anyone can submit it. This includes: + +- If the `0x???` part is not a valid hex string. +- If the `0x???` part is a valid hex string, but does not contain exactly 40 hex digits. +- If it ends with the expected suffix followed by newlines or other whitespace. +- If it ends with some other similar suffix, e.g. `#other=abc`. +- If it does not end with any such suffix. +
@@ -1458,9 +1485,9 @@ quorum depending on values such as the totalSupply of a token at this timepoint
-## `IGovernor` +## `IGovernor` - + @@ -1507,11 +1534,19 @@ Making event parameters `indexed` affects how events are decoded, potentially br - [castVoteWithReasonAndParams(proposalId, support, reason, params)](#IGovernor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-) - [castVoteBySig(proposalId, support, voter, signature)](#IGovernor-castVoteBySig-uint256-uint8-address-bytes-) - [castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)](#IGovernor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-) -#### IERC6372 [!toc] +
+IERC6372 + - [clock()](#IERC6372-clock--) - [CLOCK_MODE()](#IERC6372-CLOCK_MODE--) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -1524,8 +1559,6 @@ Making event parameters `indexed` affects how events are decoded, potentially br - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### IERC165 [!toc] @@ -1544,12 +1577,9 @@ Making event parameters `indexed` affects how events are decoded, potentially br - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### IERC165 [!toc] @@ -2428,23 +2458,6 @@ Queue operation is not implemented for this governor. Execute should be called d - - -
-
-

GovernorNotQueuedProposal(uint256 proposalId)

-
-

error

-# -
-
-
- -The proposal hasn't been queued yet. - -
-
-
@@ -2501,9 +2514,9 @@ The given `account` is unable to cancel the proposal with given `proposalId`.
-## `TimelockController` +## `TimelockController` - + @@ -2558,14 +2571,22 @@ a multisig or a DAO as the sole proposer. - [PROPOSER_ROLE()](#TimelockController-PROPOSER_ROLE-bytes32) - [EXECUTOR_ROLE()](#TimelockController-EXECUTOR_ROLE-bytes32) - [CANCELLER_ROLE()](#TimelockController-CANCELLER_ROLE-bytes32) -#### ERC1155Holder [!toc] +
+ERC1155Holder + - [onERC1155Received(, , , , )](#ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-) - [onERC1155BatchReceived(, , , , )](#ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-) -#### IERC1155Receiver [!toc] -#### ERC721Holder [!toc] + +
+
+ERC721Holder + - [onERC721Received(, , , )](#ERC721Holder-onERC721Received-address-address-uint256-bytes-) -#### IERC721Receiver [!toc] -#### AccessControl [!toc] + +
+
+AccessControl + - [hasRole(role, account)](#AccessControl-hasRole-bytes32-address-) - [_checkRole(role)](#AccessControl-_checkRole-bytes32-) - [_checkRole(role, account)](#AccessControl-_checkRole-bytes32-address-) @@ -2577,9 +2598,8 @@ a multisig or a DAO as the sole proposer. - [_grantRole(role, account)](#AccessControl-_grantRole-bytes32-address-) - [_revokeRole(role, account)](#AccessControl-_revokeRole-bytes32-address-) - [DEFAULT_ADMIN_ROLE()](#AccessControl-DEFAULT_ADMIN_ROLE-bytes32) -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControl [!toc] + +
@@ -2591,17 +2611,14 @@ a multisig or a DAO as the sole proposer. - [CallSalt(id, salt)](#TimelockController-CallSalt-bytes32-bytes32-) - [Cancelled(id)](#TimelockController-Cancelled-bytes32-) - [MinDelayChange(oldDuration, newDuration)](#TimelockController-MinDelayChange-uint256-uint256-) -#### ERC1155Holder [!toc] -#### IERC1155Receiver [!toc] -#### ERC721Holder [!toc] -#### IERC721Receiver [!toc] -#### AccessControl [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControl [!toc] +
+IAccessControl + - [RoleAdminChanged(role, previousAdminRole, newAdminRole)](#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-) - [RoleGranted(role, account, sender)](#IAccessControl-RoleGranted-bytes32-address-address-) - [RoleRevoked(role, account, sender)](#IAccessControl-RoleRevoked-bytes32-address-address-) + +
@@ -2613,16 +2630,13 @@ a multisig or a DAO as the sole proposer. - [TimelockUnexpectedOperationState(operationId, expectedStates)](#TimelockController-TimelockUnexpectedOperationState-bytes32-bytes32-) - [TimelockUnexecutedPredecessor(predecessorId)](#TimelockController-TimelockUnexecutedPredecessor-bytes32-) - [TimelockUnauthorizedCaller(caller)](#TimelockController-TimelockUnauthorizedCaller-address-) -#### ERC1155Holder [!toc] -#### IERC1155Receiver [!toc] -#### ERC721Holder [!toc] -#### IERC721Receiver [!toc] -#### AccessControl [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IAccessControl [!toc] +
+IAccessControl + - [AccessControlUnauthorizedAccount(account, neededRole)](#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-) - [AccessControlBadConfirmation()](#IAccessControl-AccessControlBadConfirmation--) + +
@@ -2705,6 +2719,13 @@ Contract might receive/hold ETH as part of the maintenance process.
+Returns true if this contract implements the interface defined by +`interfaceId`. See the corresponding +[ERC section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified) +to learn more about how these ids are created. + +This function call must use less than 30 000 gas. +
@@ -3270,9 +3291,9 @@ The caller account is not authorized.
-## `GovernorCountingFractional` +## `GovernorCountingFractional` - + @@ -3315,7 +3336,9 @@ _Available since v5.1._ - [_quorumReached(proposalId)](#GovernorCountingFractional-_quorumReached-uint256-) - [_voteSucceeded(proposalId)](#GovernorCountingFractional-_voteSucceeded-uint256-) - [_countVote(proposalId, account, support, totalWeight, params)](#GovernorCountingFractional-_countVote-uint256-address-uint8-uint256-bytes-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -3368,46 +3391,49 @@ _Available since v5.1._ - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -3415,10 +3441,9 @@ _Available since v5.1._

Errors

- [GovernorExceedRemainingWeight(voter, usedVotes, remainingWeight)](#GovernorCountingFractional-GovernorExceedRemainingWeight-address-uint256-uint256-) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -3431,17 +3456,17 @@ _Available since v5.1._ - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -3634,9 +3659,9 @@ A fractional vote params uses more votes than are available for that user.
-## `GovernorCountingOverridable` +## `GovernorCountingOverridable` - + @@ -3664,12 +3689,18 @@ token that inherits [`VotesExtended`](#VotesExtended). - [castOverrideVote(proposalId, support, reason)](#GovernorCountingOverridable-castOverrideVote-uint256-uint8-string-) - [castOverrideVoteBySig(proposalId, support, voter, reason, signature)](#GovernorCountingOverridable-castOverrideVoteBySig-uint256-uint8-address-string-bytes-) - [OVERRIDE_BALLOT_TYPEHASH()](#GovernorCountingOverridable-OVERRIDE_BALLOT_TYPEHASH-bytes32) -#### GovernorVotes [!toc] +
+GovernorVotes + - [token()](#GovernorVotes-token--) - [clock()](#GovernorVotes-clock--) - [CLOCK_MODE()](#GovernorVotes-CLOCK_MODE--) - [_getVotes(account, timepoint, )](#GovernorVotes-_getVotes-address-uint256-bytes-) -#### Governor [!toc] + +
+
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -3719,23 +3750,26 @@ token that inherits [`VotesExtended`](#VotesExtended). - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -3744,24 +3778,23 @@ token that inherits [`VotesExtended`](#VotesExtended).
- [VoteReduced(delegate, proposalId, support, weight)](#GovernorCountingOverridable-VoteReduced-address-uint256-uint8-uint256-) - [OverrideVoteCast(voter, proposalId, support, weight, reason)](#GovernorCountingOverridable-OverrideVoteCast-address-uint256-uint8-uint256-string-) -#### GovernorVotes [!toc] -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -3769,11 +3802,9 @@ token that inherits [`VotesExtended`](#VotesExtended).

Errors

- [GovernorAlreadyOverriddenVote(account)](#GovernorCountingOverridable-GovernorAlreadyOverriddenVote-address-) -#### GovernorVotes [!toc] -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -3786,17 +3817,17 @@ token that inherits [`VotesExtended`](#VotesExtended). - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -4092,9 +4123,9 @@ A delegated vote on `proposalId` was overridden by `weight`
-## `GovernorCountingSimple` +## `GovernorCountingSimple` - + @@ -4115,7 +4146,9 @@ Extension of [`Governor`](#Governor) for simple, 3 options, vote counting. - [_quorumReached(proposalId)](#GovernorCountingSimple-_quorumReached-uint256-) - [_voteSucceeded(proposalId)](#GovernorCountingSimple-_voteSucceeded-uint256-) - [_countVote(proposalId, account, support, totalWeight, )](#GovernorCountingSimple-_countVote-uint256-address-uint8-uint256-bytes-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -4168,56 +4201,58 @@ Extension of [`Governor`](#Governor) for simple, 3 options, vote counting. - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -4230,17 +4265,17 @@ Extension of [`Governor`](#Governor) for simple, 3 options, vote counting. - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -4361,7 +4396,207 @@ See [`Governor._voteSucceeded`](#Governor-_voteSucceeded-uint256-). In this modu
-See [`Governor._countVote`](#Governor-_countVote-uint256-address-uint8-uint256-bytes-). In this module, the support follows the `VoteType` enum (from Governor Bravo). +See [`Governor._countVote`](#Governor-_countVote-uint256-address-uint8-uint256-bytes-). In this module, the support follows the `VoteType` enum (from Governor Bravo). + +
+ + + + +
+ +## `GovernorCrosschain` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorCrosschain.sol"; +``` + +Extension of [`Governor`](#Governor) for cross-chain governance through ERC-7786 gateways and [`CrosschainRemoteExecutor`](/contracts/5.x/api/crosschain#CrosschainRemoteExecutor). + +
+

Functions

+
+- [relayCrosschain(gateway, executor, mode, executionCalldata)](#GovernorCrosschain-relayCrosschain-address-bytes-Mode-bytes-) +- [_crosschainExecute(gateway, executor, mode, executionCalldata)](#GovernorCrosschain-_crosschainExecute-address-bytes-Mode-bytes-) +
+Governor + +- [receive()](#Governor-receive--) +- [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) +- [name()](#Governor-name--) +- [version()](#Governor-version--) +- [hashProposal(targets, values, calldatas, descriptionHash)](#Governor-hashProposal-address---uint256---bytes---bytes32-) +- [getProposalId(targets, values, calldatas, descriptionHash)](#Governor-getProposalId-address---uint256---bytes---bytes32-) +- [state(proposalId)](#Governor-state-uint256-) +- [proposalThreshold()](#Governor-proposalThreshold--) +- [proposalSnapshot(proposalId)](#Governor-proposalSnapshot-uint256-) +- [proposalDeadline(proposalId)](#Governor-proposalDeadline-uint256-) +- [proposalProposer(proposalId)](#Governor-proposalProposer-uint256-) +- [proposalEta(proposalId)](#Governor-proposalEta-uint256-) +- [proposalNeedsQueuing()](#Governor-proposalNeedsQueuing-uint256-) +- [_checkGovernance()](#Governor-_checkGovernance--) +- [_quorumReached(proposalId)](#Governor-_quorumReached-uint256-) +- [_voteSucceeded(proposalId)](#Governor-_voteSucceeded-uint256-) +- [_getVotes(account, timepoint, params)](#Governor-_getVotes-address-uint256-bytes-) +- [_countVote(proposalId, account, support, totalWeight, params)](#Governor-_countVote-uint256-address-uint8-uint256-bytes-) +- [_tallyUpdated(proposalId)](#Governor-_tallyUpdated-uint256-) +- [_defaultParams()](#Governor-_defaultParams--) +- [propose(targets, values, calldatas, description)](#Governor-propose-address---uint256---bytes---string-) +- [_propose(targets, values, calldatas, description, proposer)](#Governor-_propose-address---uint256---bytes---string-address-) +- [queue(targets, values, calldatas, descriptionHash)](#Governor-queue-address---uint256---bytes---bytes32-) +- [_queueOperations(, , , , )](#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-) +- [execute(targets, values, calldatas, descriptionHash)](#Governor-execute-address---uint256---bytes---bytes32-) +- [_executeOperations(, targets, values, calldatas, )](#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-) +- [cancel(targets, values, calldatas, descriptionHash)](#Governor-cancel-address---uint256---bytes---bytes32-) +- [_cancel(targets, values, calldatas, descriptionHash)](#Governor-_cancel-address---uint256---bytes---bytes32-) +- [getVotes(account, timepoint)](#Governor-getVotes-address-uint256-) +- [getVotesWithParams(account, timepoint, params)](#Governor-getVotesWithParams-address-uint256-bytes-) +- [castVote(proposalId, support)](#Governor-castVote-uint256-uint8-) +- [castVoteWithReason(proposalId, support, reason)](#Governor-castVoteWithReason-uint256-uint8-string-) +- [castVoteWithReasonAndParams(proposalId, support, reason, params)](#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-) +- [castVoteBySig(proposalId, support, voter, signature)](#Governor-castVoteBySig-uint256-uint8-address-bytes-) +- [castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)](#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-) +- [_validateVoteSig(proposalId, support, voter, signature)](#Governor-_validateVoteSig-uint256-uint8-address-bytes-) +- [_validateExtendedVoteSig(proposalId, support, voter, reason, params, signature)](#Governor-_validateExtendedVoteSig-uint256-uint8-address-string-bytes-bytes-) +- [_castVote(proposalId, account, support, reason)](#Governor-_castVote-uint256-address-uint8-string-) +- [_castVote(proposalId, account, support, reason, params)](#Governor-_castVote-uint256-address-uint8-string-bytes-) +- [relay(target, value, data)](#Governor-relay-address-uint256-bytes-) +- [_executor()](#Governor-_executor--) +- [onERC721Received(, , , )](#Governor-onERC721Received-address-address-uint256-bytes-) +- [onERC1155Received(, , , , )](#Governor-onERC1155Received-address-address-uint256-uint256-bytes-) +- [onERC1155BatchReceived(, , , , )](#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-) +- [_encodeStateBitmap(proposalState)](#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-) +- [_validateStateBitmap(proposalId, allowedStates)](#Governor-_validateStateBitmap-uint256-bytes32-) +- [_isValidDescriptionForProposer(proposer, description)](#Governor-_isValidDescriptionForProposer-address-string-) +- [_validateCancel(proposalId, caller)](#Governor-_validateCancel-uint256-address-) +- [clock()](#Governor-clock--) +- [CLOCK_MODE()](#Governor-CLOCK_MODE--) +- [votingDelay()](#Governor-votingDelay--) +- [votingPeriod()](#Governor-votingPeriod--) +- [quorum(timepoint)](#Governor-quorum-uint256-) +- [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) +- [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) + +
+
+IGovernor + +- [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) +- [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) + +
+
+Nonces + +- [nonces(owner)](#Nonces-nonces-address-) +- [_useNonce(owner)](#Nonces-_useNonce-address-) +- [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) + +
+
+EIP712 + +- [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) +- [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) +- [eip712Domain()](#EIP712-eip712Domain--) +- [_EIP712Name()](#EIP712-_EIP712Name--) +- [_EIP712Version()](#EIP712-_EIP712Version--) + +
+
+
+ +
+

Events

+
+
+IGovernor + +- [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) +- [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) +- [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) +- [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) +- [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) +- [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) + +
+
+IERC5267 + +- [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) + +
+
+
+ +
+

Errors

+
+
+IGovernor + +- [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) +- [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) +- [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) +- [GovernorOnlyExecutor(account)](#IGovernor-GovernorOnlyExecutor-address-) +- [GovernorNonexistentProposal(proposalId)](#IGovernor-GovernorNonexistentProposal-uint256-) +- [GovernorUnexpectedProposalState(proposalId, current, expectedStates)](#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-) +- [GovernorInvalidVotingPeriod(votingPeriod)](#IGovernor-GovernorInvalidVotingPeriod-uint256-) +- [GovernorInsufficientProposerVotes(proposer, votes, threshold)](#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-) +- [GovernorRestrictedProposer(proposer)](#IGovernor-GovernorRestrictedProposer-address-) +- [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) +- [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) +- [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) +- [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) +- [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) +- [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) + +
+
+Nonces + +- [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) + +
+
+
+ + + +
+
+

relayCrosschain(address gateway, bytes executor, Mode mode, bytes executionCalldata)

+
+

public

+# +
+
+
+ +Send crosschain instruction to an arbitrary remote executor via an arbitrary ERC-7786 gateway. + +
+
+ + + +
+
+

_crosschainExecute(address gateway, bytes executor, Mode mode, bytes executionCalldata)

+
+

internal

+# +
+
+
+ +Send crosschain instruction to an arbitrary remote executor via an arbitrary ERC-7786 gateway.
@@ -4370,9 +4605,9 @@ See [`Governor._countVote`](#Governor-_countVote-uint256-address-uint8-uint256-b
-## `GovernorNoncesKeyed` +## `GovernorNoncesKeyed` - + @@ -4395,11 +4630,17 @@ Traditional (un-keyed) nonces are still supported and can continue to be used as - [_useCheckedNonce(owner, nonce)](#GovernorNoncesKeyed-_useCheckedNonce-address-uint256-) - [_validateVoteSig(proposalId, support, voter, signature)](#GovernorNoncesKeyed-_validateVoteSig-uint256-uint8-address-bytes-) - [_validateExtendedVoteSig(proposalId, support, voter, reason, params, signature)](#GovernorNoncesKeyed-_validateExtendedVoteSig-uint256-uint8-address-string-bytes-bytes-) -#### NoncesKeyed [!toc] +
+NoncesKeyed + - [nonces(owner, key)](#NoncesKeyed-nonces-address-uint192-) - [_useNonce(owner, key)](#NoncesKeyed-_useNonce-address-uint192-) - [_useCheckedNonce(owner, key, nonce)](#NoncesKeyed-_useCheckedNonce-address-uint192-uint64-) -#### Governor [!toc] + +
+
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -4453,59 +4694,64 @@ Traditional (un-keyed) nonces are still supported and can continue to be used as - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### NoncesKeyed [!toc] -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### NoncesKeyed [!toc] -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -4518,17 +4764,17 @@ Traditional (un-keyed) nonces are still supported and can continue to be used as - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -4595,9 +4841,9 @@ Side effects may be skipped depending on the linearization of the function.
-## `GovernorPreventLateQuorum` +## `GovernorPreventLateQuorum` - + @@ -4624,7 +4870,9 @@ proposal. - [lateQuorumVoteExtension()](#GovernorPreventLateQuorum-lateQuorumVoteExtension--) - [setLateQuorumVoteExtension(newVoteExtension)](#GovernorPreventLateQuorum-setLateQuorumVoteExtension-uint48-) - [_setLateQuorumVoteExtension(newVoteExtension)](#GovernorPreventLateQuorum-_setLateQuorumVoteExtension-uint48-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -4678,25 +4926,33 @@ proposal. - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -4705,33 +4961,32 @@ proposal.
- [ProposalExtended(proposalId, extendedDeadline)](#GovernorPreventLateQuorum-ProposalExtended-uint256-uint64-) - [LateQuorumVoteExtensionSet(oldVoteExtension, newVoteExtension)](#GovernorPreventLateQuorum-LateQuorumVoteExtensionSet-uint64-uint64-) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -4744,17 +4999,17 @@ proposal. - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -4911,9 +5166,9 @@ Emitted when the [`GovernorPreventLateQuorum.lateQuorumVoteExtension`](#Governor
-## `GovernorProposalGuardian` +## `GovernorProposalGuardian` - + @@ -4936,7 +5191,9 @@ if the proposal guardian is not configured, then proposers take this role for th - [setProposalGuardian(newProposalGuardian)](#GovernorProposalGuardian-setProposalGuardian-address-) - [_setProposalGuardian(newProposalGuardian)](#GovernorProposalGuardian-_setProposalGuardian-address-) - [_validateCancel(proposalId, caller)](#GovernorProposalGuardian-_validateCancel-uint256-address-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -4991,25 +5248,33 @@ if the proposal guardian is not configured, then proposers take this role for th - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -5017,33 +5282,32 @@ if the proposal guardian is not configured, then proposers take this role for th

Events

- [ProposalGuardianSet(oldProposalGuardian, newProposalGuardian)](#GovernorProposalGuardian-ProposalGuardianSet-address-address-) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -5056,17 +5320,17 @@ if the proposal guardian is not configured, then proposers take this role for th - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -5166,9 +5430,9 @@ Override [`Governor._validateCancel`](#Governor-_validateCancel-uint256-address-
-## `GovernorSequentialProposalId` +## `GovernorSequentialProposalId` - + @@ -5188,7 +5452,9 @@ sequential ids. - [latestProposalId()](#GovernorSequentialProposalId-latestProposalId--) - [_propose(targets, values, calldatas, description, proposer)](#GovernorSequentialProposalId-_propose-address---uint256---bytes---string-address-) - [_initializeLatestProposalId(newLatestProposalId)](#GovernorSequentialProposalId-_initializeLatestProposalId-uint256-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -5242,48 +5508,56 @@ sequential ids. - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -5291,10 +5565,9 @@ sequential ids.

Errors

- [GovernorAlreadyInitializedLatestProposalId()](#GovernorSequentialProposalId-GovernorAlreadyInitializedLatestProposalId--) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -5307,17 +5580,17 @@ sequential ids. - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -5413,9 +5686,9 @@ The [`GovernorSequentialProposalId.latestProposalId`](#GovernorSequentialProposa
-## `GovernorSettings` +## `GovernorSettings` - + @@ -5440,7 +5713,9 @@ Extension of [`Governor`](#Governor) for settings updatable through governance. - [_setVotingDelay(newVotingDelay)](#GovernorSettings-_setVotingDelay-uint48-) - [_setVotingPeriod(newVotingPeriod)](#GovernorSettings-_setVotingPeriod-uint32-) - [_setProposalThreshold(newProposalThreshold)](#GovernorSettings-_setProposalThreshold-uint256-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -5493,25 +5768,33 @@ Extension of [`Governor`](#Governor) for settings updatable through governance. - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -5521,33 +5804,32 @@ Extension of [`Governor`](#Governor) for settings updatable through governance. - [VotingDelaySet(oldVotingDelay, newVotingDelay)](#GovernorSettings-VotingDelaySet-uint256-uint256-) - [VotingPeriodSet(oldVotingPeriod, newVotingPeriod)](#GovernorSettings-VotingPeriodSet-uint256-uint256-) - [ProposalThresholdSet(oldProposalThreshold, newProposalThreshold)](#GovernorSettings-ProposalThresholdSet-uint256-uint256-) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -5560,17 +5842,17 @@ Extension of [`Governor`](#Governor) for settings updatable through governance. - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -5802,9 +6084,9 @@ Emits a [`GovernorSettings.ProposalThresholdSet`](#GovernorSettings-ProposalThre
-## `GovernorStorage` +## `GovernorStorage` - + @@ -5832,7 +6114,9 @@ Use cases for this module include: - [proposalCount()](#GovernorStorage-proposalCount--) - [proposalDetails(proposalId)](#GovernorStorage-proposalDetails-uint256-) - [proposalDetailsAt(index)](#GovernorStorage-proposalDetailsAt-uint256-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -5887,58 +6171,65 @@ Use cases for this module include: - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -5951,17 +6242,17 @@ Use cases for this module include: - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -6088,9 +6379,9 @@ Returns the details (including the proposalId) of a proposal given its sequentia
-## `GovernorSuperQuorum` +## `GovernorSuperQuorum` - + @@ -6110,7 +6401,9 @@ extension must implement [`GovernorCountingFractional.proposalVotes`](#GovernorC - [superQuorum(timepoint)](#GovernorSuperQuorum-superQuorum-uint256-) - [proposalVotes(proposalId)](#GovernorSuperQuorum-proposalVotes-uint256-) - [state(proposalId)](#GovernorSuperQuorum-state-uint256-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -6165,58 +6458,65 @@ extension must implement [`GovernorCountingFractional.proposalVotes`](#GovernorC - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -6229,17 +6529,17 @@ extension must implement [`GovernorCountingFractional.proposalVotes`](#GovernorC - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -6321,9 +6621,9 @@ types of scenarios.
-## `GovernorTimelockAccess` +## `GovernorTimelockAccess` - + @@ -6343,7 +6643,7 @@ and [`GovernorTimelockCompound`](#GovernorTimelockCompound), where the timelock permissions. Operations that are delay-restricted by the manager, however, will be executed through the [`AccessManager.execute`](/contracts/5.x/api/access#AccessManager-execute-address-bytes-) function. -==== Security Considerations +#### Security Considerations Some operations may be cancelable in the `AccessManager` by the admin or a set of guardians, depending on the restricted function being invoked. Since proposals are atomic, the cancellation by a guardian of a single operation @@ -6379,7 +6679,9 @@ the same time. See [`AccessManager.schedule`](/contracts/5.x/api/access#AccessMa - [_queueOperations(proposalId, targets, , calldatas, )](#GovernorTimelockAccess-_queueOperations-uint256-address---uint256---bytes---bytes32-) - [_executeOperations(proposalId, targets, values, calldatas, )](#GovernorTimelockAccess-_executeOperations-uint256-address---uint256---bytes---bytes32-) - [_cancel(targets, values, calldatas, descriptionHash)](#GovernorTimelockAccess-_cancel-address---uint256---bytes---bytes32-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -6430,25 +6732,33 @@ the same time. See [`AccessManager.schedule`](/contracts/5.x/api/access#AccessMa - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -6457,23 +6767,23 @@ the same time. See [`AccessManager.schedule`](/contracts/5.x/api/access#AccessMa
- [BaseDelaySet(oldBaseDelaySeconds, newBaseDelaySeconds)](#GovernorTimelockAccess-BaseDelaySet-uint32-uint32-) - [AccessManagerIgnoredSet(target, selector, ignored)](#GovernorTimelockAccess-AccessManagerIgnoredSet-address-bytes4-bool-) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -6483,10 +6793,9 @@ the same time. See [`AccessManager.schedule`](/contracts/5.x/api/access#AccessMa - [GovernorUnmetDelay(proposalId, neededTimestamp)](#GovernorTimelockAccess-GovernorUnmetDelay-uint256-uint256-) - [GovernorMismatchedNonce(proposalId, expectedNonce, actualNonce)](#GovernorTimelockAccess-GovernorMismatchedNonce-uint256-uint256-uint256-) - [GovernorLockedIgnore()](#GovernorTimelockAccess-GovernorLockedIgnore--) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -6499,17 +6808,17 @@ the same time. See [`AccessManager.schedule`](/contracts/5.x/api/access#AccessMa - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -6848,9 +7157,9 @@ Emits a [`IGovernor.ProposalCanceled`](#IGovernor-ProposalCanceled-uint256-) eve
-## `GovernorTimelockCompound` +## `GovernorTimelockCompound` - + @@ -6882,7 +7191,9 @@ inaccessible from a proposal, unless executed via [`Governor.relay`](#Governor-r - [_executor()](#GovernorTimelockCompound-_executor--) - [__acceptAdmin()](#GovernorTimelockCompound-__acceptAdmin--) - [updateTimelock(newTimelock)](#GovernorTimelockCompound-updateTimelock-contract-ICompoundTimelock-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -6932,25 +7243,33 @@ inaccessible from a proposal, unless executed via [`Governor.relay`](#Governor-r - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -6958,33 +7277,32 @@ inaccessible from a proposal, unless executed via [`Governor.relay`](#Governor-r

Events

- [TimelockChange(oldTimelock, newTimelock)](#GovernorTimelockCompound-TimelockChange-address-address-) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -6997,17 +7315,17 @@ inaccessible from a proposal, unless executed via [`Governor.relay`](#Governor-r - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -7186,7 +7504,9 @@ Note that if the timelock admin has been handed over in a previous operation, we timelock if admin of the timelock has already been accepted and the operation is executed outside the scope of governance. -CAUTION: It is not recommended to change the timelock while there are other queued governance proposals. + +It is not recommended to change the timelock while there are other queued governance proposals. + @@ -7213,9 +7533,9 @@ Emitted when the timelock controller used for proposal execution is modified.
-## `GovernorTimelockControl` +## `GovernorTimelockControl` - + @@ -7252,7 +7572,9 @@ proposals that have been approved by the voters, effectively executing a Denial - [_cancel(targets, values, calldatas, descriptionHash)](#GovernorTimelockControl-_cancel-address---uint256---bytes---bytes32-) - [_executor()](#GovernorTimelockControl-_executor--) - [updateTimelock(newTimelock)](#GovernorTimelockControl-updateTimelock-contract-TimelockController-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -7302,25 +7624,33 @@ proposals that have been approved by the voters, effectively executing a Denial - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -7328,33 +7658,32 @@ proposals that have been approved by the voters, effectively executing a Denial

Events

- [TimelockChange(oldTimelock, newTimelock)](#GovernorTimelockControl-TimelockChange-address-address-) -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -7367,17 +7696,17 @@ proposals that have been approved by the voters, effectively executing a Denial - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -7532,7 +7861,9 @@ Address through which the governor executes action. In this case, the timelock. Public endpoint to update the underlying timelock instance. Restricted to the timelock itself, so updates must be proposed, scheduled, and executed through governance proposals. -CAUTION: It is not recommended to change the timelock while there are other queued governance proposals. + +It is not recommended to change the timelock while there are other queued governance proposals. + @@ -7559,9 +7890,9 @@ Emitted when the timelock controller used for proposal execution is modified.
-## `GovernorVotes` +## `GovernorVotes` - + @@ -7582,7 +7913,9 @@ token. - [clock()](#GovernorVotes-clock--) - [CLOCK_MODE()](#GovernorVotes-CLOCK_MODE--) - [_getVotes(account, timepoint, )](#GovernorVotes-_getVotes-address-uint256-bytes-) -#### Governor [!toc] +
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -7635,58 +7968,65 @@ token. - [quorum(timepoint)](#Governor-quorum-uint256-) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -7699,17 +8039,17 @@ token. - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -7799,9 +8139,9 @@ Machine-readable description of the clock as specified in ERC-6372.
-## `GovernorVotesQuorumFraction` +## `GovernorVotesQuorumFraction` - + @@ -7825,12 +8165,18 @@ fraction of the total supply. - [updateQuorumNumerator(newQuorumNumerator)](#GovernorVotesQuorumFraction-updateQuorumNumerator-uint256-) - [_updateQuorumNumerator(newQuorumNumerator)](#GovernorVotesQuorumFraction-_updateQuorumNumerator-uint256-) - [_optimisticUpperLookupRecent(ckpts, timepoint)](#GovernorVotesQuorumFraction-_optimisticUpperLookupRecent-struct-Checkpoints-Trace208-uint256-) -#### GovernorVotes [!toc] +
+GovernorVotes + - [token()](#GovernorVotes-token--) - [clock()](#GovernorVotes-clock--) - [CLOCK_MODE()](#GovernorVotes-CLOCK_MODE--) - [_getVotes(account, timepoint, )](#GovernorVotes-_getVotes-address-uint256-bytes-) -#### Governor [!toc] + +
+
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -7882,25 +8228,33 @@ fraction of the total supply. - [votingPeriod()](#Governor-votingPeriod--) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -7908,24 +8262,23 @@ fraction of the total supply.

Events

- [QuorumNumeratorUpdated(oldQuorumNumerator, newQuorumNumerator)](#GovernorVotesQuorumFraction-QuorumNumeratorUpdated-uint256-uint256-) -#### GovernorVotes [!toc] -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -7933,11 +8286,9 @@ fraction of the total supply.

Errors

- [GovernorInvalidQuorumFraction(quorumNumerator, quorumDenominator)](#GovernorVotesQuorumFraction-GovernorInvalidQuorumFraction-uint256-uint256-) -#### GovernorVotes [!toc] -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] +
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -7950,17 +8301,17 @@ fraction of the total supply. - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -8154,9 +8505,9 @@ The quorum set is not a valid fraction.
-## `GovernorVotesSuperQuorumFraction` +## `GovernorVotesSuperQuorumFraction` - + @@ -8181,21 +8532,35 @@ the `Succeeded` state before the proposal deadline. - [_updateSuperQuorumNumerator(newSuperQuorumNumerator)](#GovernorVotesSuperQuorumFraction-_updateSuperQuorumNumerator-uint256-) - [_updateQuorumNumerator(newQuorumNumerator)](#GovernorVotesSuperQuorumFraction-_updateQuorumNumerator-uint256-) - [state(proposalId)](#GovernorVotesSuperQuorumFraction-state-uint256-) -#### GovernorSuperQuorum [!toc] +
+GovernorSuperQuorum + - [proposalVotes(proposalId)](#GovernorSuperQuorum-proposalVotes-uint256-) -#### GovernorVotesQuorumFraction [!toc] + +
+
+GovernorVotesQuorumFraction + - [quorumNumerator()](#GovernorVotesQuorumFraction-quorumNumerator--) - [quorumNumerator(timepoint)](#GovernorVotesQuorumFraction-quorumNumerator-uint256-) - [quorumDenominator()](#GovernorVotesQuorumFraction-quorumDenominator--) - [quorum(timepoint)](#GovernorVotesQuorumFraction-quorum-uint256-) - [updateQuorumNumerator(newQuorumNumerator)](#GovernorVotesQuorumFraction-updateQuorumNumerator-uint256-) - [_optimisticUpperLookupRecent(ckpts, timepoint)](#GovernorVotesQuorumFraction-_optimisticUpperLookupRecent-struct-Checkpoints-Trace208-uint256-) -#### GovernorVotes [!toc] + +
+
+GovernorVotes + - [token()](#GovernorVotes-token--) - [clock()](#GovernorVotes-clock--) - [CLOCK_MODE()](#GovernorVotes-CLOCK_MODE--) - [_getVotes(account, timepoint, )](#GovernorVotes-_getVotes-address-uint256-bytes-) -#### Governor [!toc] + +
+
+Governor + - [receive()](#Governor-receive--) - [supportsInterface(interfaceId)](#Governor-supportsInterface-bytes4-) - [name()](#Governor-name--) @@ -8246,25 +8611,33 @@ the `Succeeded` state before the proposal deadline. - [votingPeriod()](#Governor-votingPeriod--) - [BALLOT_TYPEHASH()](#Governor-BALLOT_TYPEHASH-bytes32) - [EXTENDED_BALLOT_TYPEHASH()](#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32) -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [COUNTING_MODE()](#IGovernor-COUNTING_MODE--) - [hasVoted(proposalId, account)](#IGovernor-hasVoted-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -8272,27 +8645,29 @@ the `Succeeded` state before the proposal deadline.

Events

- [SuperQuorumNumeratorUpdated(oldSuperQuorumNumerator, newSuperQuorumNumerator)](#GovernorVotesSuperQuorumFraction-SuperQuorumNumeratorUpdated-uint256-uint256-) -#### GovernorSuperQuorum [!toc] -#### GovernorVotesQuorumFraction [!toc] +
+GovernorVotesQuorumFraction + - [QuorumNumeratorUpdated(oldQuorumNumerator, newQuorumNumerator)](#GovernorVotesQuorumFraction-QuorumNumeratorUpdated-uint256-uint256-) -#### GovernorVotes [!toc] -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)](#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-) - [ProposalQueued(proposalId, etaSeconds)](#IGovernor-ProposalQueued-uint256-uint256-) - [ProposalExecuted(proposalId)](#IGovernor-ProposalExecuted-uint256-) - [ProposalCanceled(proposalId)](#IGovernor-ProposalCanceled-uint256-) - [VoteCast(voter, proposalId, support, weight, reason)](#IGovernor-VoteCast-address-uint256-uint8-uint256-string-) - [VoteCastWithParams(voter, proposalId, support, weight, reason, params)](#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -8302,14 +8677,15 @@ the `Succeeded` state before the proposal deadline. - [GovernorInvalidSuperQuorumFraction(superQuorumNumerator, denominator)](#GovernorVotesSuperQuorumFraction-GovernorInvalidSuperQuorumFraction-uint256-uint256-) - [GovernorInvalidSuperQuorumTooSmall(superQuorumNumerator, quorumNumerator)](#GovernorVotesSuperQuorumFraction-GovernorInvalidSuperQuorumTooSmall-uint256-uint256-) - [GovernorInvalidQuorumTooLarge(quorumNumerator, superQuorumNumerator)](#GovernorVotesSuperQuorumFraction-GovernorInvalidQuorumTooLarge-uint256-uint256-) -#### GovernorSuperQuorum [!toc] -#### GovernorVotesQuorumFraction [!toc] +
+GovernorVotesQuorumFraction + - [GovernorInvalidQuorumFraction(quorumNumerator, quorumDenominator)](#GovernorVotesQuorumFraction-GovernorInvalidQuorumFraction-uint256-uint256-) -#### GovernorVotes [!toc] -#### Governor [!toc] -#### IERC1155Receiver [!toc] -#### IERC721Receiver [!toc] -#### IGovernor [!toc] + +
+
+IGovernor + - [GovernorInvalidProposalLength(targets, calldatas, values)](#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-) - [GovernorAlreadyCastVote(voter)](#IGovernor-GovernorAlreadyCastVote-address-) - [GovernorDisabledDeposit()](#IGovernor-GovernorDisabledDeposit--) @@ -8322,17 +8698,17 @@ the `Succeeded` state before the proposal deadline. - [GovernorInvalidVoteType()](#IGovernor-GovernorInvalidVoteType--) - [GovernorInvalidVoteParams()](#IGovernor-GovernorInvalidVoteParams--) - [GovernorQueueNotImplemented()](#IGovernor-GovernorQueueNotImplemented--) -- [GovernorNotQueuedProposal(proposalId)](#IGovernor-GovernorNotQueuedProposal-uint256-) - [GovernorAlreadyQueuedProposal(proposalId)](#IGovernor-GovernorAlreadyQueuedProposal-uint256-) - [GovernorInvalidSignature(voter)](#IGovernor-GovernorInvalidSignature-address-) - [GovernorUnableToCancel(proposalId, account)](#IGovernor-GovernorUnableToCancel-uint256-address-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -8573,9 +8949,9 @@ The quorum set is not valid as it exceeds the super quorum.
-## `IVotes` +## `IVotes` - + @@ -8780,9 +9156,9 @@ The signature used has expired.
-## `Votes` +## `Votes` - + @@ -8828,35 +9204,43 @@ previous example, it would be included in [`ERC721._update`](/contracts/5.x/api/ - [_numCheckpoints(account)](#Votes-_numCheckpoints-address-) - [_checkpoints(account, pos)](#Votes-_checkpoints-address-uint32-) - [_getVotingUnits()](#Votes-_getVotingUnits-address-) -#### IERC5805 [!toc] -#### IVotes [!toc] -#### IERC6372 [!toc] -#### Nonces [!toc] +
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] + +

Events

-#### IERC5805 [!toc] -#### IVotes [!toc] +
+IVotes + - [DelegateChanged(delegator, fromDelegate, toDelegate)](#IVotes-DelegateChanged-address-address-address-) - [DelegateVotesChanged(delegate, previousVotes, newVotes)](#IVotes-DelegateVotesChanged-address-uint256-uint256-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) + +
@@ -8865,14 +9249,18 @@ previous example, it would be included in [`ERC721._update`](/contracts/5.x/api/
- [ERC6372InconsistentClock()](#Votes-ERC6372InconsistentClock--) - [ERC5805FutureLookup(timepoint, clock)](#Votes-ERC5805FutureLookup-uint256-uint48-) -#### IERC5805 [!toc] -#### IVotes [!toc] +
+IVotes + - [VotesExpiredSignature(expiry)](#IVotes-VotesExpiredSignature-uint256-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
@@ -9206,9 +9594,9 @@ Lookup to future votes is not available.
-## `VotesExtended` +## `VotesExtended` - + @@ -9251,7 +9639,9 @@ contract VotingToken is Token, VotesExtended { - [getPastBalanceOf(account, timepoint)](#VotesExtended-getPastBalanceOf-address-uint256-) - [_delegate(account, delegatee)](#VotesExtended-_delegate-address-address-) - [_transferVotingUnits(from, to, amount)](#VotesExtended-_transferVotingUnits-address-address-uint256-) -#### Votes [!toc] +
+Votes + - [clock()](#Votes-clock--) - [CLOCK_MODE()](#Votes-CLOCK_MODE--) - [_validateTimepoint(timepoint)](#Votes-_validateTimepoint-uint256-) @@ -9266,53 +9656,70 @@ contract VotingToken is Token, VotesExtended { - [_numCheckpoints(account)](#Votes-_numCheckpoints-address-) - [_checkpoints(account, pos)](#Votes-_checkpoints-address-uint32-) - [_getVotingUnits()](#Votes-_getVotingUnits-address-) -#### IERC5805 [!toc] -#### IVotes [!toc] -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] + +

Events

-#### Votes [!toc] -#### IERC5805 [!toc] -#### IVotes [!toc] +
+IVotes + - [DelegateChanged(delegator, fromDelegate, toDelegate)](#IVotes-DelegateChanged-address-address-address-) - [DelegateVotesChanged(delegate, previousVotes, newVotes)](#IVotes-DelegateVotesChanged-address-uint256-uint256-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) + +

Errors

-#### Votes [!toc] +
+Votes + - [ERC6372InconsistentClock()](#Votes-ERC6372InconsistentClock--) - [ERC5805FutureLookup(timepoint, clock)](#Votes-ERC5805FutureLookup-uint256-uint48-) -#### IERC5805 [!toc] -#### IVotes [!toc] + +
+
+IVotes + - [VotesExpiredSignature(expiry)](#IVotes-VotesExpiredSignature-uint256-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
@@ -9396,3 +9803,4 @@ should be zero. Total supply of voting units will be adjusted with mints and bur + diff --git a/content/contracts/5.x/api/interfaces.mdx b/content/contracts/5.x/api/interfaces.mdx index 92d69448..6fde47a5 100644 --- a/content/contracts/5.x/api/interfaces.mdx +++ b/content/contracts/5.x/api/interfaces.mdx @@ -30,6 +30,8 @@ are useful to interact with third party contracts that implement them. * [`IERC1820Implementer`](#IERC1820Implementer) * [`IERC1820Registry`](#IERC1820Registry) * [`IERC1822Proxiable`](#IERC1822Proxiable) +* [`IERC1967`](#IERC1967) +* [`IERC2309`](#IERC2309) * [`IERC2612`](#IERC2612) * [`IERC2981`](#IERC2981) * [`IERC3156FlashLender`](#IERC3156FlashLender) @@ -44,11 +46,18 @@ are useful to interact with third party contracts that implement them. * [`IERC6909ContentURI`](#IERC6909ContentURI) * [`IERC6909Metadata`](#IERC6909Metadata) * [`IERC6909TokenSupply`](#IERC6909TokenSupply) +* [`IERC7579Module`](#IERC7579Module) +* [`IERC7579Validator`](#IERC7579Validator) +* [`IERC7579Hook`](#IERC7579Hook) +* [`IERC7579Execution`](#IERC7579Execution) +* [`IERC7579AccountConfig`](#IERC7579AccountConfig) +* [`IERC7579ModuleConfig`](#IERC7579ModuleConfig) * [`IERC7674`](#IERC7674) -ย [`IERC7751`](#IERC7751) * [`IERC7786GatewaySource`](#IERC7786GatewaySource) * [`IERC7786Recipient`](#IERC7786Recipient) * [`IERC7802`](#IERC7802) +* [`IERC7913SignatureVerifier`](#IERC7913SignatureVerifier) ## Detailed ABI @@ -72,6 +81,10 @@ are useful to interact with third party contracts that implement them. [`IERC1822Proxiable`](#IERC1822Proxiable) +[`IERC1967`](#IERC1967) + +[`IERC2309`](#IERC2309) + [`IERC2612`](#IERC2612) [`IERC2981`](#IERC2981) @@ -100,6 +113,18 @@ are useful to interact with third party contracts that implement them. [`IERC6909TokenSupply`](#IERC6909TokenSupply) +[`IERC7579Module`](#IERC7579Module) + +[`IERC7579Validator`](#IERC7579Validator) + +[`IERC7579Hook`](#IERC7579Hook) + +[`IERC7579Execution`](#IERC7579Execution) + +[`IERC7579AccountConfig`](#IERC7579AccountConfig) + +[`IERC7579ModuleConfig`](#IERC7579ModuleConfig) + [`IERC7674`](#IERC7674) [`IERC7751`](#IERC7751) @@ -110,13 +135,15 @@ are useful to interact with third party contracts that implement them. [`IERC7802`](#IERC7802) +[`IERC7913SignatureVerifier`](#IERC7913SignatureVerifier) +
-## `IERC1271` +## `IERC1271` - + @@ -157,9 +184,9 @@ Should return whether the signature provided is valid for the provided data
-## `IERC1363` +## `IERC1363` - + @@ -183,25 +210,36 @@ after `transfer` or `transferFrom`, or code on a spender contract after `approve - [transferFromAndCall(from, to, value, data)](#IERC1363-transferFromAndCall-address-address-uint256-bytes-) - [approveAndCall(spender, value)](#IERC1363-approveAndCall-address-uint256-) - [approveAndCall(spender, value, data)](#IERC1363-approveAndCall-address-uint256-bytes-) -#### IERC165 [!toc] +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) -#### IERC20 [!toc] + +
+
+IERC20 + - [totalSupply()](#IERC20-totalSupply--) - [balanceOf(account)](#IERC20-balanceOf-address-) - [transfer(to, value)](#IERC20-transfer-address-uint256-) - [allowance(owner, spender)](#IERC20-allowance-address-address-) - [approve(spender, value)](#IERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#IERC20-transferFrom-address-address-uint256-) + +

Events

-#### IERC165 [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -317,9 +355,9 @@ caller's tokens and then calls [`IERC1363Spender.onApprovalReceived`](#IERC1363S
-## `IERC1363Receiver` +## `IERC1363Receiver` - + @@ -367,9 +405,9 @@ To accept the transfer, this must return
-## `IERC1363Spender` +## `IERC1363Spender` - + @@ -417,9 +455,9 @@ To accept the approval, this must return
-## `IERC1820Implementer` +## `IERC1820Implementer` - + @@ -465,9 +503,9 @@ See [`IERC1820Registry.setInterfaceImplementer`](#IERC1820Registry-setInterfaceI
-## `IERC1820Registry` +## `IERC1820Registry` - + @@ -714,9 +752,9 @@ corresponding
-## `IERC1967` +## `IERC1967` - + @@ -793,9 +831,9 @@ Emitted when the beacon is changed.
-## `IERC2309` +## `IERC2309` - + @@ -836,9 +874,9 @@ Emitted when the tokens from `fromTokenId` to `toTokenId` are transferred from `
-## `IERC2612` +## `IERC2612` - + @@ -851,10 +889,14 @@ import "@openzeppelin/contracts/interfaces/IERC2612.sol";

Functions

-#### IERC20Permit [!toc] +
+IERC20Permit + - [permit(owner, spender, value, deadline, v, r, s)](#IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) - [nonces(owner)](#IERC20Permit-nonces-address-) - [DOMAIN_SEPARATOR()](#IERC20Permit-DOMAIN_SEPARATOR--) + +
@@ -862,9 +904,9 @@ import "@openzeppelin/contracts/interfaces/IERC2612.sol";
-## `IERC2981` +## `IERC2981` - + @@ -883,8 +925,12 @@ support for royalty payments across all NFT marketplaces and ecosystem participa

Functions

- [royaltyInfo(tokenId, salePrice)](#IERC2981-royaltyInfo-uint256-uint256-) -#### IERC165 [!toc] +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -915,9 +961,9 @@ royalty receiver and 0 tokens to the seller. Contracts dealing with royalty shou
-## `IERC3156FlashBorrower` +## `IERC3156FlashBorrower` - + @@ -958,9 +1004,9 @@ Receive a flash loan.
-## `IERC3156FlashLender` +## `IERC3156FlashLender` - + @@ -1037,9 +1083,9 @@ Initiate a flash loan.
-## `IERC4626` +## `IERC4626` - + @@ -1071,17 +1117,25 @@ Interface of the ERC-4626 "Tokenized Vault Standard", as defined in - [maxRedeem(owner)](#IERC4626-maxRedeem-address-) - [previewRedeem(shares)](#IERC4626-previewRedeem-uint256-) - [redeem(shares, receiver, owner)](#IERC4626-redeem-uint256-address-address-) -#### IERC20Metadata [!toc] +
+IERC20Metadata + - [name()](#IERC20Metadata-name--) - [symbol()](#IERC20Metadata-symbol--) - [decimals()](#IERC20Metadata-decimals--) -#### IERC20 [!toc] + +
+
+IERC20 + - [totalSupply()](#IERC20-totalSupply--) - [balanceOf(account)](#IERC20-balanceOf-address-) - [transfer(to, value)](#IERC20-transfer-address-uint256-) - [allowance(owner, spender)](#IERC20-allowance-address-address-) - [approve(spender, value)](#IERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#IERC20-transferFrom-address-address-uint256-) + +
@@ -1090,10 +1144,13 @@ Interface of the ERC-4626 "Tokenized Vault Standard", as defined in
- [Deposit(sender, owner, assets, shares)](#IERC4626-Deposit-address-address-uint256-uint256-) - [Withdraw(sender, receiver, owner, assets, shares)](#IERC4626-Withdraw-address-address-address-uint256-uint256-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -1549,9 +1606,9 @@ Those methods should be performed separately.
-## `IERC4906` +## `IERC4906` - + @@ -1564,7 +1621,9 @@ import "@openzeppelin/contracts/interfaces/IERC4906.sol";

Functions

-#### IERC721 [!toc] +
+IERC721 + - [balanceOf(owner)](#IERC721-balanceOf-address-) - [ownerOf(tokenId)](#IERC721-ownerOf-uint256-) - [safeTransferFrom(from, to, tokenId, data)](#IERC721-safeTransferFrom-address-address-uint256-bytes-) @@ -1574,8 +1633,14 @@ import "@openzeppelin/contracts/interfaces/IERC4906.sol"; - [setApprovalForAll(operator, approved)](#IERC721-setApprovalForAll-address-bool-) - [getApproved(tokenId)](#IERC721-getApproved-uint256-) - [isApprovedForAll(owner, operator)](#IERC721-isApprovedForAll-address-address-) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -1584,11 +1649,14 @@ import "@openzeppelin/contracts/interfaces/IERC4906.sol";
- [MetadataUpdate(_tokenId)](#IERC4906-MetadataUpdate-uint256-) - [BatchMetadataUpdate(_fromTokenId, _toTokenId)](#IERC4906-BatchMetadataUpdate-uint256-uint256-) -#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### IERC165 [!toc] + +
@@ -1635,9 +1703,9 @@ timely update the images and related attributes of the NFTs.
-## `IERC5267` +## `IERC5267` - + @@ -1701,9 +1769,9 @@ MAY be emitted to signal that the domain could have changed.
-## `IERC5313` +## `IERC5313` - + @@ -1745,9 +1813,9 @@ Gets the address of the owner.
-## `IERC5805` +## `IERC5805` - + @@ -1760,35 +1828,49 @@ import "@openzeppelin/contracts/interfaces/IERC5805.sol";

Functions

-#### IVotes [!toc] +
+IVotes + - [getVotes(account)](#IVotes-getVotes-address-) - [getPastVotes(account, timepoint)](#IVotes-getPastVotes-address-uint256-) - [getPastTotalSupply(timepoint)](#IVotes-getPastTotalSupply-uint256-) - [delegates(account)](#IVotes-delegates-address-) - [delegate(delegatee)](#IVotes-delegate-address-) - [delegateBySig(delegatee, nonce, expiry, v, r, s)](#IVotes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-) -#### IERC6372 [!toc] + +
+
+IERC6372 + - [clock()](#IERC6372-clock--) - [CLOCK_MODE()](#IERC6372-CLOCK_MODE--) + +

Events

-#### IVotes [!toc] +
+IVotes + - [DelegateChanged(delegator, fromDelegate, toDelegate)](#IVotes-DelegateChanged-address-address-address-) - [DelegateVotesChanged(delegate, previousVotes, newVotes)](#IVotes-DelegateVotesChanged-address-uint256-uint256-) -#### IERC6372 [!toc] + +

Errors

-#### IVotes [!toc] +
+IVotes + - [VotesExpiredSignature(expiry)](#IVotes-VotesExpiredSignature-uint256-) -#### IERC6372 [!toc] + +
@@ -1796,9 +1878,9 @@ import "@openzeppelin/contracts/interfaces/IERC5805.sol";
-## `IERC6372` +## `IERC6372` - + @@ -1854,9 +1936,9 @@ Description of the clock
-## `IERC6909` +## `IERC6909` - + @@ -1879,8 +1961,12 @@ Required interface of an ERC-6909 compliant contract, as defined in the - [setOperator(spender, approved)](#IERC6909-setOperator-address-bool-) - [transfer(receiver, id, amount)](#IERC6909-transfer-address-uint256-uint256-) - [transferFrom(sender, receiver, id, amount)](#IERC6909-transferFrom-address-address-uint256-uint256-) -#### IERC165 [!toc] +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -1890,7 +1976,6 @@ Required interface of an ERC-6909 compliant contract, as defined in the - [Approval(owner, spender, id, amount)](#IERC6909-Approval-address-address-uint256-uint256-) - [OperatorSet(owner, spender, approved)](#IERC6909-OperatorSet-address-address-bool-) - [Transfer(caller, sender, receiver, id, amount)](#IERC6909-Transfer-address-address-address-uint256-uint256-) -#### IERC165 [!toc]
@@ -2083,9 +2168,9 @@ Emitted when `amount` tokens of type `id` are moved from `sender` to `receiver`
-## `IERC6909Metadata` +## `IERC6909Metadata` - + @@ -2103,7 +2188,9 @@ Optional extension of [`IERC6909`](#IERC6909) that adds metadata functions. - [name(id)](#IERC6909Metadata-name-uint256-) - [symbol(id)](#IERC6909Metadata-symbol-uint256-) - [decimals(id)](#IERC6909Metadata-decimals-uint256-) -#### IERC6909 [!toc] +
+IERC6909 + - [balanceOf(owner, id)](#IERC6909-balanceOf-address-uint256-) - [allowance(owner, spender, id)](#IERC6909-allowance-address-address-uint256-) - [isOperator(owner, spender)](#IERC6909-isOperator-address-address-) @@ -2111,19 +2198,28 @@ Optional extension of [`IERC6909`](#IERC6909) that adds metadata functions. - [setOperator(spender, approved)](#IERC6909-setOperator-address-bool-) - [transfer(receiver, id, amount)](#IERC6909-transfer-address-uint256-uint256-) - [transferFrom(sender, receiver, id, amount)](#IERC6909-transferFrom-address-address-uint256-uint256-) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-#### IERC6909 [!toc] +
+IERC6909 + - [Approval(owner, spender, id, amount)](#IERC6909-Approval-address-address-uint256-uint256-) - [OperatorSet(owner, spender, approved)](#IERC6909-OperatorSet-address-address-bool-) - [Transfer(caller, sender, receiver, id, amount)](#IERC6909-Transfer-address-address-address-uint256-uint256-) -#### IERC165 [!toc] + +
@@ -2182,9 +2278,9 @@ Returns the number of decimals for the token of type `id`.
-## `IERC6909ContentURI` +## `IERC6909ContentURI` - + @@ -2201,7 +2297,9 @@ Optional extension of [`IERC6909`](#IERC6909) that adds content URI functions.
- [contractURI()](#IERC6909ContentURI-contractURI--) - [tokenURI(id)](#IERC6909ContentURI-tokenURI-uint256-) -#### IERC6909 [!toc] +
+IERC6909 + - [balanceOf(owner, id)](#IERC6909-balanceOf-address-uint256-) - [allowance(owner, spender, id)](#IERC6909-allowance-address-address-uint256-) - [isOperator(owner, spender)](#IERC6909-isOperator-address-address-) @@ -2209,19 +2307,28 @@ Optional extension of [`IERC6909`](#IERC6909) that adds content URI functions. - [setOperator(spender, approved)](#IERC6909-setOperator-address-bool-) - [transfer(receiver, id, amount)](#IERC6909-transfer-address-uint256-uint256-) - [transferFrom(sender, receiver, id, amount)](#IERC6909-transferFrom-address-address-uint256-uint256-) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-#### IERC6909 [!toc] +
+IERC6909 + - [Approval(owner, spender, id, amount)](#IERC6909-Approval-address-address-uint256-uint256-) - [OperatorSet(owner, spender, approved)](#IERC6909-OperatorSet-address-address-bool-) - [Transfer(caller, sender, receiver, id, amount)](#IERC6909-Transfer-address-address-address-uint256-uint256-) -#### IERC165 [!toc] + +
@@ -2263,9 +2370,9 @@ Returns the URI for the token of type `id`.
-## `IERC6909TokenSupply` +## `IERC6909TokenSupply` - + @@ -2281,7 +2388,9 @@ Optional extension of [`IERC6909`](#IERC6909) that adds a token supply function.

Functions

- [totalSupply(id)](#IERC6909TokenSupply-totalSupply-uint256-) -#### IERC6909 [!toc] +
+IERC6909 + - [balanceOf(owner, id)](#IERC6909-balanceOf-address-uint256-) - [allowance(owner, spender, id)](#IERC6909-allowance-address-address-uint256-) - [isOperator(owner, spender)](#IERC6909-isOperator-address-address-) @@ -2289,19 +2398,28 @@ Optional extension of [`IERC6909`](#IERC6909) that adds a token supply function. - [setOperator(spender, approved)](#IERC6909-setOperator-address-bool-) - [transfer(receiver, id, amount)](#IERC6909-transfer-address-uint256-uint256-) - [transferFrom(sender, receiver, id, amount)](#IERC6909-transferFrom-address-address-uint256-uint256-) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-#### IERC6909 [!toc] +
+IERC6909 + - [Approval(owner, spender, id, amount)](#IERC6909-Approval-address-address-uint256-uint256-) - [OperatorSet(owner, spender, approved)](#IERC6909-OperatorSet-address-address-bool-) - [Transfer(caller, sender, receiver, id, amount)](#IERC6909-Transfer-address-address-address-uint256-uint256-) -#### IERC165 [!toc] + +
@@ -2326,9 +2444,9 @@ Returns the total supply of the token of type `id`.
-## `IERC7751` +## `IERC7751` - + @@ -2367,9 +2485,9 @@ Interface of the [ERC-7751](https://eips.ethereum.org/EIPS/eip-7751) wrapping of
-## `IERC777` +## `IERC777` - + @@ -2811,9 +2929,9 @@ Emitted when `operator` is revoked its operator status for `tokenHolder`.
-## `IERC777Recipient` +## `IERC777Recipient` - + @@ -2867,9 +2985,9 @@ This function may revert to prevent the operation from being executed.
-## `IERC777Sender` +## `IERC777Sender` - + @@ -2923,9 +3041,9 @@ This function may revert to prevent the operation from being executed.
-## `IERC7913SignatureVerifier` +## `IERC7913SignatureVerifier` - + @@ -2969,9 +3087,9 @@ SHOULD return 0xffffffff or revert if the key is empty
-## `IERC1822Proxiable` +## `IERC1822Proxiable` - + @@ -3019,9 +3137,9 @@ function revert if invoked through a proxy.
-## `PackedUserOperation` +## `PackedUserOperation` - + @@ -3057,15 +3175,17 @@ When passed to on-chain contracts, the following packed version is used. - `preVerificationGas` (`uint256`) - `gasFees` (`bytes32`): concatenation of maxPriorityFeePerGas (16 bytes) and maxFeePerGas (16 bytes) - `paymasterAndData` (`bytes`): concatenation of paymaster fields (or empty) + For EntryPoint v0.9+, may optionally include `paymasterSignature` at the end: + `paymaster || paymasterVerificationGasLimit || paymasterPostOpGasLimit || paymasterData || paymasterSignature || paymasterSignatureSize || PAYMASTER_SIG_MAGIC` - `signature` (`bytes`)
-## `IAggregator` +## `IAggregator` - + @@ -3153,9 +3273,9 @@ Requirements:
-## `IEntryPointNonces` +## `IEntryPointNonces` - + @@ -3203,9 +3323,9 @@ Nonces for a certain `key` are always increasing.
-## `IEntryPointStake` +## `IEntryPointStake` - + @@ -3339,9 +3459,9 @@ Withdraws the stake of the account to `withdrawAddress`.
-## `IEntryPoint` +## `IEntryPoint` - + @@ -3360,15 +3480,23 @@ User operations are validated and executed by this contract.
- [handleOps(ops, beneficiary)](#IEntryPoint-handleOps-struct-PackedUserOperation---address-payable-) - [handleAggregatedOps(opsPerAggregator, beneficiary)](#IEntryPoint-handleAggregatedOps-struct-IEntryPoint-UserOpsPerAggregator---address-payable-) -#### IEntryPointStake [!toc] +
+IEntryPointStake + - [balanceOf(account)](#IEntryPointStake-balanceOf-address-) - [depositTo(account)](#IEntryPointStake-depositTo-address-) - [withdrawTo(withdrawAddress, withdrawAmount)](#IEntryPointStake-withdrawTo-address-payable-uint256-) - [addStake(unstakeDelaySec)](#IEntryPointStake-addStake-uint32-) - [unlockStake()](#IEntryPointStake-unlockStake--) - [withdrawStake(withdrawAddress)](#IEntryPointStake-withdrawStake-address-payable-) -#### IEntryPointNonces [!toc] + +
+
+IEntryPointNonces + - [getNonce(sender, key)](#IEntryPointNonces-getNonce-address-uint192-) + +
@@ -3377,8 +3505,6 @@ User operations are validated and executed by this contract.
- [FailedOp(opIndex, reason)](#IEntryPoint-FailedOp-uint256-string-) - [FailedOpWithRevert(opIndex, reason, inner)](#IEntryPoint-FailedOpWithRevert-uint256-string-bytes-) -#### IEntryPointStake [!toc] -#### IEntryPointNonces [!toc]
@@ -3454,9 +3580,9 @@ A user operation at `opIndex` failed with `reason` and `inner` returned data.
-## `IAccount` +## `IAccount` - + @@ -3508,9 +3634,9 @@ Returns an encoded packed validation data that is composed of the following elem
-## `IAccountExecute` +## `IAccountExecute` - + @@ -3551,9 +3677,9 @@ Executes a user operation.
-## `IPaymaster` +## `IPaymaster` - + @@ -3620,9 +3746,9 @@ Verifies the sender is the entrypoint.
-## `IERC20Errors` +## `IERC20Errors` - + @@ -3753,9 +3879,9 @@ Indicates a failure with the `spender` to be approved. Used in approvals.
-## `IERC721Errors` +## `IERC721Errors` - + @@ -3923,9 +4049,9 @@ Indicates a failure with the `operator` to be approved. Used in approvals.
-## `IERC1155Errors` +## `IERC1155Errors` - + @@ -4075,9 +4201,9 @@ Used in batch transfers.
-## `VALIDATION_SUCCESS` +## `VALIDATION_SUCCESS` - + @@ -4091,9 +4217,9 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-## `VALIDATION_FAILED` +## `VALIDATION_FAILED` - + @@ -4107,9 +4233,9 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-## `MODULE_TYPE_VALIDATOR` +## `MODULE_TYPE_VALIDATOR` - + @@ -4123,9 +4249,9 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-## `MODULE_TYPE_EXECUTOR` +## `MODULE_TYPE_EXECUTOR` - + @@ -4139,9 +4265,9 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-## `MODULE_TYPE_FALLBACK` +## `MODULE_TYPE_FALLBACK` - + @@ -4155,9 +4281,9 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-## `MODULE_TYPE_HOOK` +## `MODULE_TYPE_HOOK` - + @@ -4171,9 +4297,9 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-## `IERC7579Module` +## `IERC7579Module` - + @@ -4249,9 +4375,9 @@ Returns boolean value if module is a certain type
-## `IERC7579Validator` +## `IERC7579Validator` - + @@ -4270,10 +4396,14 @@ A module that implements logic to validate user operations and signatures.
- [validateUserOp(userOp, userOpHash)](#IERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-) - [isValidSignatureWithSender(sender, hash, signature)](#IERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-) -#### IERC7579Module [!toc] +
+IERC7579Module + - [onInstall(data)](#IERC7579Module-onInstall-bytes-) - [onUninstall(data)](#IERC7579Module-onUninstall-bytes-) - [isModuleType(moduleTypeId)](#IERC7579Module-isModuleType-uint256-) + +
@@ -4315,9 +4445,9 @@ Validates a signature using ERC-1271
-## `IERC7579Hook` +## `IERC7579Hook` - + @@ -4337,10 +4467,14 @@ either individually or batched.
- [preCheck(msgSender, value, msgData)](#IERC7579Hook-preCheck-address-uint256-bytes-) - [postCheck(hookData)](#IERC7579Hook-postCheck-bytes-) -#### IERC7579Module [!toc] +
+IERC7579Module + - [onInstall(data)](#IERC7579Module-onInstall-bytes-) - [onUninstall(data)](#IERC7579Module-onUninstall-bytes-) - [isModuleType(moduleTypeId)](#IERC7579Module-isModuleType-uint256-) + +
@@ -4382,9 +4516,9 @@ Called by the smart account after execution
-## `Execution` +## `Execution` - + @@ -4398,9 +4532,9 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-## `IERC7579Execution` +## `IERC7579Execution` - + @@ -4461,9 +4595,9 @@ Executes a transaction on behalf of the account.
-## `IERC7579AccountConfig` +## `IERC7579AccountConfig` - + @@ -4541,9 +4675,9 @@ Function to check if the account supports a certain module typeId
-## `IERC7579ModuleConfig` +## `IERC7579ModuleConfig` - + @@ -4660,9 +4794,9 @@ Returns whether a module is installed on the smart account
-## `IERC7674` +## `IERC7674` - + @@ -4678,22 +4812,30 @@ Temporary Approval Extension for ERC-20 ([ERC-7674](https://github.com/ethereum/

Functions

- [temporaryApprove(spender, value)](#IERC7674-temporaryApprove-address-uint256-) -#### IERC20 [!toc] +
+IERC20 + - [totalSupply()](#IERC20-totalSupply--) - [balanceOf(account)](#IERC20-balanceOf-address-) - [transfer(to, value)](#IERC20-transfer-address-uint256-) - [allowance(owner, spender)](#IERC20-allowance-address-address-) - [approve(spender, value)](#IERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#IERC20-transferFrom-address-address-uint256-) + +

Events

-#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -4719,9 +4861,9 @@ held by the caller.
-## `IERC7786GatewaySource` +## `IERC7786GatewaySource` - + @@ -4838,9 +4980,9 @@ This error is thrown when a message creation fails because of an unsupported att
-## `IERC7786Recipient` +## `IERC7786Recipient` - + @@ -4884,9 +5026,9 @@ This function may be called directly by the gateway.
-## `IERC7802` +## `IERC7802` - + @@ -4901,8 +5043,12 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7802.sol";
- [crosschainMint(_to, _amount)](#IERC7802-crosschainMint-address-uint256-) - [crosschainBurn(_from, _amount)](#IERC7802-crosschainBurn-address-uint256-) -#### IERC165 [!toc] +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -4911,7 +5057,6 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7802.sol";
- [CrosschainMint(to, amount, sender)](#IERC7802-CrosschainMint-address-uint256-address-) - [CrosschainBurn(from, amount, sender)](#IERC7802-CrosschainBurn-address-uint256-address-) -#### IERC165 [!toc]
@@ -4980,9 +5125,9 @@ import "@openzeppelin/contracts/interfaces/draft-IERC7802.sol";
-## `IERC7821` +## `IERC7821` - + @@ -5060,3 +5205,4 @@ Only returns true for:
+ diff --git a/content/contracts/5.x/api/metatx.mdx b/content/contracts/5.x/api/metatx.mdx index 4fcbd986..72afa69a 100644 --- a/content/contracts/5.x/api/metatx.mdx +++ b/content/contracts/5.x/api/metatx.mdx @@ -20,9 +20,9 @@ This directory includes contracts for adding meta-transaction capabilities (i.e.
-## `ERC2771Context` +## `ERC2771Context` - + @@ -32,7 +32,7 @@ This directory includes contracts for adding meta-transaction capabilities (i.e. import "@openzeppelin/contracts/metatx/ERC2771Context.sol"; ``` -Context variant with ERC-2771 support. +Context variant with ERC-2771 support. See [`ERC2771Context._msgSender`](#ERC2771Context-_msgSender--) for the calldata format. Avoid using this pattern in contracts that rely on a specific calldata length as they'll @@ -168,9 +168,9 @@ ERC-2771 specifies the context as being a single address (20 bytes).
-## `ERC2771Forwarder` +## `ERC2771Forwarder` - + @@ -188,7 +188,7 @@ This forwarder operates on forward requests that include: * `to`: The address that should be called. * `value`: The amount of native token to attach with the requested call. * `gas`: The amount of gas limit that will be forwarded with the requested call. -* `nonce`: A unique transaction ordering identifier to avoid replayability and request invalidation. +* `nonce` (implicit): Taken from [`Nonces`](/contracts/5.x/api/utils#Nonces) for `from` and included in the signed typed data. * `deadline`: A timestamp after which the request is not executable anymore. * `data`: Encoded `msg.data` to send with the requested call. @@ -205,7 +205,7 @@ handle `msg.data.length == 0`. `ERC2771Context` in OpenZeppelin Contracts versio do not handle this properly. -==== Security Considerations +#### Security Considerations If a relayer submits a forward request, it should be willing to pay up to 100% of the gas amount specified in the request. This contract does not implement any kind of retribution for this gas, @@ -230,17 +230,24 @@ used to execute arbitrary code. - [_recoverForwardRequestSigner(request)](#ERC2771Forwarder-_recoverForwardRequestSigner-struct-ERC2771Forwarder-ForwardRequestData-) - [_execute(request, requireValidRequest)](#ERC2771Forwarder-_execute-struct-ERC2771Forwarder-ForwardRequestData-bool-) - [_isTrustedByTarget(target)](#ERC2771Forwarder-_isTrustedByTarget-address-) -#### Nonces [!toc] +
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] + +
@@ -248,24 +255,29 @@ used to execute arbitrary code.

Events

- [ExecutedForwardRequest(signer, nonce, success)](#ERC2771Forwarder-ExecutedForwardRequest-address-uint256-bool-) -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] +
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) + +

Errors

+- [ERC2771ForwarderFailureInAtomicBatch()](#ERC2771Forwarder-ERC2771ForwarderFailureInAtomicBatch--) - [ERC2771ForwarderInvalidSigner(signer, from)](#ERC2771Forwarder-ERC2771ForwarderInvalidSigner-address-address-) - [ERC2771ForwarderMismatchedValue(requestedValue, msgValue)](#ERC2771Forwarder-ERC2771ForwarderMismatchedValue-uint256-uint256-) - [ERC2771ForwarderExpiredRequest(deadline)](#ERC2771Forwarder-ERC2771ForwarderExpiredRequest-uint48-) - [ERC2771UntrustfulTarget(target, forwarder)](#ERC2771Forwarder-ERC2771UntrustfulTarget-address-address-) -#### Nonces [!toc] +
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
@@ -304,7 +316,7 @@ A transaction is considered valid when the target trusts this forwarder, the req (deadline is not met), and the signer matches the `from` parameter of the signed request. -A request may return false here but it won't cause [`TimelockController.executeBatch`](/contracts/5.x/api/governance#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-) to revert if a refund +A request may return false here but it won't cause [`ERC2771Forwarder.executeBatch`](#ERC2771Forwarder-executeBatch-struct-ERC2771Forwarder-ForwardRequestData---address-payable-) to revert if a refund receiver is provided. @@ -330,7 +342,7 @@ out of gas. Will revert if the request is invalid or the call reverts, in this c Requirements: - The request value should be equal to the provided `msg.value`. -- The request should be valid according to [`IERC7913SignatureVerifier.verify`](/contracts/5.x/api/interfaces#IERC7913SignatureVerifier-verify-bytes-bytes32-bytes-). +- The request should be valid according to [`ERC2771Forwarder.verify`](#ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData-).
@@ -347,9 +359,9 @@ Requirements:
-Batch version of [`AccessManager.execute`](/contracts/5.x/api/access#AccessManager-execute-address-bytes-) with optional refunding and atomic execution. +Batch version of [`ERC2771Forwarder.execute`](#ERC2771Forwarder-execute-struct-ERC2771Forwarder-ForwardRequestData-) with optional refunding and atomic execution. -In case a batch contains at least one invalid request (see [`IERC7913SignatureVerifier.verify`](/contracts/5.x/api/interfaces#IERC7913SignatureVerifier-verify-bytes-bytes32-bytes-)), the +In case a batch contains at least one invalid request (see [`ERC2771Forwarder.verify`](#ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData-)), the request will be skipped and the `refundReceiver` parameter will receive back the unused requested value at the end of the execution. This is done to prevent reverting the entire batch when a request is invalid or has already been submitted. @@ -363,7 +375,7 @@ including reverted transactions. Requirements: - The sum of the requests' values should be equal to the provided `msg.value`. -- All of the requests should be valid (see [`IERC7913SignatureVerifier.verify`](/contracts/5.x/api/interfaces#IERC7913SignatureVerifier-verify-bytes-bytes32-bytes-)) when `refundReceiver` is the zero address. +- All of the requests should be valid (see [`ERC2771Forwarder.verify`](#ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData-)) when `refundReceiver` is the zero address. Setting a zero `refundReceiver` guarantees an all-or-nothing requests execution only for @@ -387,7 +399,7 @@ subcall, the second-level call may revert without the top-level call reverting.
Validates if the provided request can be executed at current block timestamp with -the given `request.signature` on behalf of `request.signer`. +the given `request.signature` on behalf of `request.from`.
@@ -408,7 +420,7 @@ Returns a tuple with the recovered the signer of an EIP712 forward request messa and a boolean indicating if the signature is valid. -The signature is considered valid if [`ECDSA.tryRecover`](/contracts/5.x/api/utils/cryptography#ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32-) indicates no recover error for it. +The signature is considered valid if [`ECDSA.tryRecoverCalldata`](/contracts/5.x/api/utils/cryptography#ECDSA-tryRecoverCalldata-bytes32-bytes-) indicates no recover error for it.
@@ -433,7 +445,7 @@ Internal function without msg.value validation. Requirements: - The caller must have provided enough gas to forward with the call. -- The request must be valid (see [`IERC7913SignatureVerifier.verify`](/contracts/5.x/api/interfaces#IERC7913SignatureVerifier-verify-bytes-bytes32-bytes-)) if the `requireValidRequest` is true. +- The request must be valid (see [`ERC2771Forwarder.verify`](#ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData-)) if the `requireValidRequest` is true. Emits an [`ERC2771Forwarder.ExecutedForwardRequest`](#ERC2771Forwarder-ExecutedForwardRequest-address-uint256-bool-) event. @@ -494,6 +506,23 @@ the requested call to run out of gas.
+ + +
+
+

ERC2771ForwarderFailureInAtomicBatch()

+
+

error

+# +
+
+
+ +One of the calls in an atomic batch failed. + +
+
+
@@ -561,3 +590,4 @@ The request target doesn't trust the `forwarder`.
+ diff --git a/content/contracts/5.x/api/proxy.mdx b/content/contracts/5.x/api/proxy.mdx index 0b1cd166..8f7d0d77 100644 --- a/content/contracts/5.x/api/proxy.mdx +++ b/content/contracts/5.x/api/proxy.mdx @@ -22,10 +22,10 @@ There are two alternative ways to add upgradeability to an ERC-1967 proxy. Their **๐Ÿ”ฅ CAUTION**\ Using upgradeable proxies correctly and securely is a difficult task that requires deep knowledge of the proxy pattern, Solidity, and the EVM. Unless you want a lot of low level control, we recommend using the [OpenZeppelin Upgrades Plugins](/upgrades-plugins) for Hardhat and Foundry. -A different family of proxies are beacon proxies. This pattern, popularized by Dharma, allows multiple proxies to be upgraded to a different implementation in a single transaction. +A different family of proxies is beacon proxies. This pattern, popularized by Dharma, allows multiple proxies to be upgraded to a different implementation in a single transaction. * [`BeaconProxy`](#BeaconProxy): A proxy that retrieves its implementation from a beacon contract. -* [`UpgradeableBeacon`](#UpgradeableBeacon): A beacon contract with a built in admin that can upgrade the [`BeaconProxy`](#BeaconProxy) pointing to it. +* [`UpgradeableBeacon`](#UpgradeableBeacon): A beacon contract with a built-in admin that can upgrade the [`BeaconProxy`](#BeaconProxy) pointing to it. In this pattern, the proxy contract doesnโ€™t hold the implementation address in storage like an ERC-1967 proxy. Instead, the address is stored in a separate beacon contract. The `upgrade` operations are sent to the beacon instead of to the proxy contract, and all proxies that follow that beacon are automatically upgraded. @@ -90,9 +90,9 @@ The current implementation of this security mechanism uses [ERC-1822](https://ei
-## `Clones` +## `Clones` - + @@ -474,9 +474,9 @@ Get the immutable args attached to a clone.
-## `ERC1967Proxy` +## `ERC1967Proxy` - + @@ -496,10 +496,22 @@ implementation behind the proxy.
- [constructor(implementation, _data)](#ERC1967Proxy-constructor-address-bytes-) - [_implementation()](#ERC1967Proxy-_implementation--) -#### Proxy [!toc] +- [_unsafeAllowUninitialized()](#ERC1967Proxy-_unsafeAllowUninitialized--) +
+Proxy + - [_delegate(implementation)](#Proxy-_delegate-address-) - [_fallback()](#Proxy-_fallback--) - [fallback()](#Proxy-fallback--) + +
+
+
+ +
+

Errors

+
+- [ERC1967ProxyUninitialized()](#ERC1967Proxy-ERC1967ProxyUninitialized--)
@@ -517,8 +529,11 @@ implementation behind the proxy. Initializes the upgradeable proxy with an initial implementation specified by `implementation`. -If `_data` is nonempty, it's used as data in a delegate call to `implementation`. This will typically be an -encoded function call, and allows initializing the storage of the proxy like a Solidity constructor. +Provided `_data` is passed in a delegate call to `implementation`. This will typically be an encoded function +call, and allows initializing the storage of the proxy like a Solidity constructor. By default construction +will fail if `_data` is empty. This behavior can be overridden using a custom [`ERC1967Proxy._unsafeAllowUninitialized`](#ERC1967Proxy-_unsafeAllowUninitialized--) that +returns true. In that case, empty `_data` is ignored and no delegate call to the implementation is performed +during construction. Requirements: @@ -550,13 +565,53 @@ the [`eth_getStorageAt`](https://eth.wiki/json-rpc/API#eth_getstorageat) RPC cal
+ + +
+
+

_unsafeAllowUninitialized() โ†’ bool

+
+

internal

+# +
+
+
+ +Returns whether the proxy can be left uninitialized. + + +Override this function to allow the proxy to be left uninitialized. +Consider uninitialized proxies might be susceptible to man-in-the-middle threats +where the proxy is replaced with a malicious one. + + +
+
+ + + +
+
+

ERC1967ProxyUninitialized()

+
+

error

+# +
+
+
+ +The proxy is left uninitialized. + +
+
+
-## `ERC1967Utils` +## `ERC1967Utils` - + @@ -645,7 +700,7 @@ Returns the current admin. To get this value clients can read directly from the storage slot shown below (specified by ERC-1967) using -the [`eth_getStorageAt`](https://eth.wiki/json-rpc/API#eth_getstorageat) RPC call. +the [`eth_getStorageAt`](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getstorageat) RPC call. `0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103` @@ -706,9 +761,11 @@ to avoid stuck value in the contract. Emits an [`IERC1967.BeaconUpgraded`](/contracts/5.x/api/interfaces#IERC1967-BeaconUpgraded-address-) event. -CAUTION: Invoking this function has no effect on an instance of [`BeaconProxy`](#BeaconProxy) since v5, since + +Invoking this function has no effect on an instance of [`BeaconProxy`](#BeaconProxy) since v5, since it uses an immutable beacon without looking at the value of the ERC-1967 beacon slot for efficiency. +
@@ -785,9 +842,9 @@ An upgrade function sees `msg.value > 0` that may be lost.
-## `Proxy` +## `Proxy` - + @@ -801,8 +858,8 @@ This abstract contract provides a fallback function that delegates all calls to instruction `delegatecall`. We refer to the second contract as the _implementation_ behind the proxy, and it has to be specified by overriding the virtual [`ERC1967Proxy._implementation`](#ERC1967Proxy-_implementation--) function. -Additionally, delegation to the implementation can be triggered manually through the [`AccountERC7579._fallback`](/contracts/5.x/api/account#AccountERC7579-_fallback--) function, or to a -different contract through the [`Votes._delegate`](/contracts/5.x/api/governance#Votes-_delegate-address-address-) function. +Additionally, delegation to the implementation can be triggered manually through the [`Proxy._fallback`](#Proxy-_fallback--) function, or to a +different contract through the [`Proxy._delegate`](#Proxy-_delegate-address-) function. The success and return data of the delegated call will be returned back to the caller of the proxy. @@ -848,7 +905,7 @@ This function does not return to its internal call site, it will return directly
This is a virtual function that should be overridden so it returns the address to which the fallback -function and [`AccountERC7579._fallback`](/contracts/5.x/api/account#AccountERC7579-_fallback--) should delegate. +function and [`Proxy._fallback`](#Proxy-_fallback--) should delegate.
@@ -894,9 +951,9 @@ function in the contract matches the call data.
-## `BeaconProxy` +## `BeaconProxy` - + @@ -912,8 +969,10 @@ The beacon address can only be set once during construction, and cannot be chang immutable variable to avoid unnecessary storage reads, and also in the beacon storage slot specified by [ERC-1967](https://eips.ethereum.org/EIPS/eip-1967) so that it can be accessed externally. -CAUTION: Since the beacon address can never be changed, you must ensure that you either control the beacon, or trust + +Since the beacon address can never be changed, you must ensure that you either control the beacon, or trust the beacon to not upgrade the implementation maliciously. + Do not use the implementation logic to modify the beacon storage slot. Doing so would leave the proxy in @@ -926,10 +985,14 @@ an inconsistent state where the beacon storage slot does not match the beacon ad - [constructor(beacon, data)](#BeaconProxy-constructor-address-bytes-) - [_implementation()](#BeaconProxy-_implementation--) - [_getBeacon()](#BeaconProxy-_getBeacon--) -#### Proxy [!toc] +
+Proxy + - [_delegate(implementation)](#Proxy-_delegate-address-) - [_fallback()](#Proxy-_fallback--) - [fallback()](#Proxy-fallback--) + +
@@ -997,9 +1060,9 @@ Returns the beacon.
-## `IBeacon` +## `IBeacon` - + @@ -1041,9 +1104,9 @@ Must return an address that can be used as a delegate call target.
-## `UpgradeableBeacon` +## `UpgradeableBeacon` - + @@ -1064,13 +1127,16 @@ An owner is able to change the implementation the beacon points to, thus upgradi - [constructor(implementation_, initialOwner)](#UpgradeableBeacon-constructor-address-address-) - [implementation()](#UpgradeableBeacon-implementation--) - [upgradeTo(newImplementation)](#UpgradeableBeacon-upgradeTo-address-) -#### Ownable [!toc] +
+Ownable + - [owner()](#Ownable-owner--) - [_checkOwner()](#Ownable-_checkOwner--) - [renounceOwnership()](#Ownable-renounceOwnership--) - [transferOwnership(newOwner)](#Ownable-transferOwnership-address-) - [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-) -#### IBeacon [!toc] + +
@@ -1078,9 +1144,12 @@ An owner is able to change the implementation the beacon points to, thus upgradi

Events

- [Upgraded(implementation)](#UpgradeableBeacon-Upgraded-address-) -#### Ownable [!toc] +
+Ownable + - [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-) -#### IBeacon [!toc] + +
@@ -1088,10 +1157,13 @@ An owner is able to change the implementation the beacon points to, thus upgradi

Errors

- [BeaconInvalidImplementation(implementation)](#UpgradeableBeacon-BeaconInvalidImplementation-address-) -#### Ownable [!toc] +
+Ownable + - [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-) -#### IBeacon [!toc] + +
@@ -1143,7 +1215,7 @@ Returns the current implementation address. Upgrades the beacon to a new implementation. -Emits an [`IERC1967.Upgraded`](/contracts/5.x/api/interfaces#IERC1967-Upgraded-address-) event. +Emits an [`UpgradeableBeacon.Upgraded`](#UpgradeableBeacon-Upgraded-address-) event. Requirements: @@ -1192,9 +1264,9 @@ The `implementation` of the beacon is invalid.
-## `ProxyAdmin` +## `ProxyAdmin` - + @@ -1213,29 +1285,41 @@ explanation of why you would want to use this see the documentation for [`Transp - [constructor(initialOwner)](#ProxyAdmin-constructor-address-) - [upgradeAndCall(proxy, implementation, data)](#ProxyAdmin-upgradeAndCall-contract-ITransparentUpgradeableProxy-address-bytes-) - [UPGRADE_INTERFACE_VERSION()](#ProxyAdmin-UPGRADE_INTERFACE_VERSION-string) -#### Ownable [!toc] +
+Ownable + - [owner()](#Ownable-owner--) - [_checkOwner()](#Ownable-_checkOwner--) - [renounceOwnership()](#Ownable-renounceOwnership--) - [transferOwnership(newOwner)](#Ownable-transferOwnership-address-) - [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-) + +

Events

-#### Ownable [!toc] +
+Ownable + - [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-) + +

Errors

-#### Ownable [!toc] +
+Ownable + - [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-) - [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-) + +
@@ -1305,9 +1389,9 @@ during an upgrade.
-## `ITransparentUpgradeableProxy` +## `ITransparentUpgradeableProxy` - + @@ -1326,17 +1410,20 @@ include them in the ABI so this interface must be used to interact with it.

Functions

- [upgradeToAndCall(newImplementation, data)](#ITransparentUpgradeableProxy-upgradeToAndCall-address-bytes-) -#### IERC1967 [!toc]

Events

-#### IERC1967 [!toc] +
+IERC1967 + - [Upgraded(implementation)](#IERC1967-Upgraded-address-) - [AdminChanged(previousAdmin, newAdmin)](#IERC1967-AdminChanged-address-address-) - [BeaconUpgraded(beacon)](#IERC1967-BeaconUpgraded-address-) + +
@@ -1361,9 +1448,9 @@ See [`UUPSUpgradeable.upgradeToAndCall`](#UUPSUpgradeable-upgradeToAndCall-addre
-## `TransparentUpgradeableProxy` +## `TransparentUpgradeableProxy` - + @@ -1426,11 +1513,20 @@ could render the `upgradeToAndCall` function inaccessible, preventing upgradeabi - [constructor(_logic, initialOwner, _data)](#TransparentUpgradeableProxy-constructor-address-address-bytes-) - [_proxyAdmin()](#TransparentUpgradeableProxy-_proxyAdmin--) - [_fallback()](#TransparentUpgradeableProxy-_fallback--) -#### ERC1967Proxy [!toc] +
+ERC1967Proxy + - [_implementation()](#ERC1967Proxy-_implementation--) -#### Proxy [!toc] +- [_unsafeAllowUninitialized()](#ERC1967Proxy-_unsafeAllowUninitialized--) + +
+
+Proxy + - [_delegate(implementation)](#Proxy-_delegate-address-) - [fallback()](#Proxy-fallback--) + +
@@ -1438,8 +1534,12 @@ could render the `upgradeToAndCall` function inaccessible, preventing upgradeabi

Errors

- [ProxyDeniedAdminAccess()](#TransparentUpgradeableProxy-ProxyDeniedAdminAccess--) -#### ERC1967Proxy [!toc] -#### Proxy [!toc] +
+ERC1967Proxy + +- [ERC1967ProxyUninitialized()](#ERC1967Proxy-ERC1967ProxyUninitialized--) + +
@@ -1517,9 +1617,9 @@ The proxy caller is the current admin, and can't fallback to the proxy target.
-## `Initializable` +## `Initializable` - + @@ -1560,11 +1660,13 @@ To avoid leaving the proxy in an uninitialized state, the initializer function s possible by providing the encoded function call as the `_data` argument to [`ERC1967Proxy.constructor`](#ERC1967Proxy-constructor-address-bytes-). -CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure + +When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure that all initializers are idempotent. This is not verified automatically as constructors are by Solidity. + - -Avoid leaving a contract uninitialized. +[CAUTION] +#### Avoid leaving a contract uninitialized. An uninitialized contract can be taken over by an attacker. This applies to both a proxy and its implementation contract, which may impact the proxy. To prevent the implementation contract from being used, you should invoke @@ -1577,7 +1679,6 @@ constructor() { _disableInitializers(); } ``` -

Modifiers

@@ -1843,9 +1944,9 @@ The contract is not initializing.
-## `UUPSUpgradeable` +## `UUPSUpgradeable` - + @@ -1883,7 +1984,6 @@ The [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-add - [_checkNotDelegated()](#UUPSUpgradeable-_checkNotDelegated--) - [_authorizeUpgrade(newImplementation)](#UUPSUpgradeable-_authorizeUpgrade-address-) - [UPGRADE_INTERFACE_VERSION()](#UUPSUpgradeable-UPGRADE_INTERFACE_VERSION-string) -#### IERC1822Proxiable [!toc]
@@ -1892,7 +1992,6 @@ The [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-add
- [UUPSUnauthorizedCallContext()](#UUPSUpgradeable-UUPSUnauthorizedCallContext--) - [UUPSUnsupportedProxiableUUID(slot)](#UUPSUpgradeable-UUPSUnsupportedProxiableUUID-bytes32-) -#### IERC1822Proxiable [!toc]
@@ -1949,7 +2048,7 @@ callable on the implementing contract but not through proxies.
-Implementation of the ERC-1822 [`IERC1822Proxiable.proxiableUUID`](/contracts/5.x/api/interfaces#IERC1822Proxiable-proxiableUUID--) function. This returns the storage slot used by the +Implementation of the ERC-1822 [`UUPSUpgradeable.proxiableUUID`](#UUPSUpgradeable-proxiableUUID--) function. This returns the storage slot used by the implementation. It is used to validate the implementation's compatibility when performing an upgrade. @@ -1978,7 +2077,7 @@ encoded in `data`. Calls [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-). -Emits an [`IERC1967.Upgraded`](/contracts/5.x/api/interfaces#IERC1967-Upgraded-address-) event. +Emits an [`UpgradeableBeacon.Upgraded`](#UpgradeableBeacon-Upgraded-address-) event.
@@ -2098,3 +2197,4 @@ The storage `slot` is unsupported as a UUID.
+ diff --git a/content/contracts/5.x/api/token/ERC1155.mdx b/content/contracts/5.x/api/token/ERC1155.mdx index 69846298..d9dfdbbe 100644 --- a/content/contracts/5.x/api/token/ERC1155.mdx +++ b/content/contracts/5.x/api/token/ERC1155.mdx @@ -13,6 +13,7 @@ Additionally there are multiple custom extensions, including: * designation of addresses that can pause token transfers for all users ([`ERC1155Pausable`](#ERC1155Pausable)). * destruction of own tokens ([`ERC1155Burnable`](#ERC1155Burnable)). +* crosschain bridging of tokens through ERC-7786 gateways ([`ERC1155Crosschain`](#ERC1155Crosschain)). This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC-1155 (such as [`_mint`](#ERC1155-_mint-address-uint256-uint256-bytes-)) and expose them as external functions in the way they prefer. @@ -30,10 +31,12 @@ This core set of contracts is designed to be unopinionated, allowing developers ## Extensions -[`ERC1155Pausable`](#ERC1155Pausable) - [`ERC1155Burnable`](#ERC1155Burnable) +[`ERC1155Crosschain`](#ERC1155Crosschain) + +[`ERC1155Pausable`](#ERC1155Pausable) + [`ERC1155Supply`](#ERC1155Supply) [`ERC1155URIStorage`](#ERC1155URIStorage) @@ -48,9 +51,9 @@ This core set of contracts is designed to be unopinionated, allowing developers
-## `ERC1155` +## `ERC1155` - + @@ -76,8 +79,10 @@ Originally based on code by Enjin: https://github.com/enjin/erc-1155 - [isApprovedForAll(account, operator)](#ERC1155-isApprovedForAll-address-address-) - [safeTransferFrom(from, to, id, value, data)](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) - [safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-) +- [_checkAuthorized(operator, owner)](#ERC1155-_checkAuthorized-address-address-) - [_update(from, to, ids, values)](#ERC1155-_update-address-address-uint256---uint256---) - [_updateWithAcceptanceCheck(from, to, ids, values, data)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-) +- [_updateWithAcceptanceCheck(from, to, ids, values, data, batch)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-bool-) - [_safeTransferFrom(from, to, id, value, data)](#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-) - [_safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-) - [_setURI(newuri)](#ERC1155-_setURI-string-) @@ -86,33 +91,30 @@ Originally based on code by Enjin: https://github.com/enjin/erc-1155 - [_burn(from, id, value)](#ERC1155-_burn-address-uint256-uint256-) - [_burnBatch(from, ids, values)](#ERC1155-_burnBatch-address-uint256---uint256---) - [_setApprovalForAll(owner, operator, approved)](#ERC1155-_setApprovalForAll-address-address-bool-) -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc]

Events

-#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] +
+IERC1155 + - [TransferSingle(operator, from, to, id, value)](#IERC1155-TransferSingle-address-address-address-uint256-uint256-) - [TransferBatch(operator, from, to, ids, values)](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) - [ApprovalForAll(account, operator, approved)](#IERC1155-ApprovalForAll-address-address-bool-) - [URI(value, id)](#IERC1155-URI-string-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### IERC1155Errors [!toc] +
+IERC1155Errors + - [ERC1155InsufficientBalance(sender, balance, needed, tokenId)](#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-) - [ERC1155InvalidSender(sender)](#IERC1155Errors-ERC1155InvalidSender-address-) - [ERC1155InvalidReceiver(receiver)](#IERC1155Errors-ERC1155InvalidReceiver-address-) @@ -120,10 +122,8 @@ Originally based on code by Enjin: https://github.com/enjin/erc-1155 - [ERC1155InvalidApprover(approver)](#IERC1155Errors-ERC1155InvalidApprover-address-) - [ERC1155InvalidOperator(operator)](#IERC1155Errors-ERC1155InvalidOperator-address-) - [ERC1155InvalidArrayLength(idsLength, valuesLength)](#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-) -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -316,7 +316,7 @@ acceptance magic value.
-[Batched](/contracts/5.x/erc1155) version of [`ERC1155.safeTransferFrom`](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-). +[Batched](/contracts/5.x/erc1155#batch-operations) version of [`ERC1155.safeTransferFrom`](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-). This function can potentially allow a reentrancy attack when transferring tokens @@ -336,6 +336,23 @@ acceptance magic value.
+ + +
+
+

_checkAuthorized(address operator, address owner)

+
+

internal

+# +
+
+
+ +Checks if `operator` is authorized to transfer tokens owned by `owner`. Reverts with [`IERC1155Errors.ERC1155MissingApprovalForAll`](/contracts/5.x/api/interfaces#IERC1155Errors-ERC1155MissingApprovalForAll-address-address-) if not. + +
+
+
@@ -360,7 +377,7 @@ Requirements: - `ids` and `values` must have the same length. -The ERC-1155 acceptance check is not performed in this function. See [`ERC1155._updateWithAcceptanceCheck`](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-) instead. +The ERC-1155 acceptance check is not performed in this function. See [`ERC1155._updateWithAcceptanceCheck`](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-bool-) instead.
@@ -388,6 +405,36 @@ update to the contract state after this function would break the check-effect-in overriding [`ERC1155._update`](#ERC1155-_update-address-address-uint256---uint256---) instead. + +This version is kept for backward compatibility. We recommend calling the alternative version with a boolean +flag in order to achieve better control over which hook to call. + + +
+
+ + + +
+
+

_updateWithAcceptanceCheck(address from, address to, uint256[] ids, uint256[] values, bytes data, bool batch)

+
+

internal

+# +
+
+
+ +Version of [`ERC1155._update`](#ERC1155-_update-address-address-uint256---uint256---) that performs the token acceptance check by calling +[`IERC1155Receiver.onERC1155Received`](#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-) or [`IERC1155Receiver.onERC1155BatchReceived`](#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-) on the receiver address if it +contains code (eg. is a smart contract at the moment of execution). + + +Overriding this function is discouraged because it poses a reentrancy risk from the receiver. So any +update to the contract state after this function would break the check-effect-interaction pattern. Consider +overriding [`ERC1155._update`](#ERC1155-_update-address-address-uint256---uint256---) instead. + +
@@ -429,7 +476,7 @@ acceptance magic value.
-[Batched](/contracts/5.x/erc1155) version of [`ERC1155._safeTransferFrom`](#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-). +[Batched](/contracts/5.x/erc1155#batch-operations) version of [`ERC1155._safeTransferFrom`](#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-). Emits a [`IERC1155.TransferBatch`](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) event. @@ -512,7 +559,7 @@ acceptance magic value.
-[Batched](/contracts/5.x/erc1155) version of [`ERC1155._mint`](#ERC1155-_mint-address-uint256-uint256-bytes-). +[Batched](/contracts/5.x/erc1155#batch-operations) version of [`ERC1155._mint`](#ERC1155-_mint-address-uint256-uint256-bytes-). Emits a [`IERC1155.TransferBatch`](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) event. @@ -562,7 +609,7 @@ Requirements:
-[Batched](/contracts/5.x/erc1155) version of [`ERC1155._burn`](#ERC1155-_burn-address-uint256-uint256-). +[Batched](/contracts/5.x/erc1155#batch-operations) version of [`ERC1155._burn`](#ERC1155-_burn-address-uint256-uint256-). Emits a [`IERC1155.TransferBatch`](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) event. @@ -593,6 +640,7 @@ Emits an [`IERC1155.ApprovalForAll`](#IERC1155-ApprovalForAll-address-address-bo Requirements: +- `owner` cannot be the zero address. - `operator` cannot be the zero address.
@@ -602,9 +650,9 @@ Requirements:
-## `IERC1155` +## `IERC1155` - + @@ -626,8 +674,12 @@ Required interface of an ERC-1155 compliant contract, as defined in the - [isApprovedForAll(account, operator)](#IERC1155-isApprovedForAll-address-address-) - [safeTransferFrom(from, to, id, value, data)](#IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) - [safeBatchTransferFrom(from, to, ids, values, data)](#IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-) -#### IERC165 [!toc] +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -638,7 +690,6 @@ Required interface of an ERC-1155 compliant contract, as defined in the - [TransferBatch(operator, from, to, ids, values)](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) - [ApprovalForAll(account, operator, approved)](#IERC1155-ApprovalForAll-address-address-bool-) - [URI(value, id)](#IERC1155-URI-string-uint256-) -#### IERC165 [!toc]
@@ -671,7 +722,7 @@ Returns the value of tokens of token type `id` owned by `account`.
-[Batched](/contracts/5.x/erc1155) version of [`IERC6909.balanceOf`](../interfaces#IERC6909-balanceOf-address-uint256-). +[Batched](/contracts/5.x/erc1155#batch-operations) version of [`ERC1155.balanceOf`](#ERC1155-balanceOf-address-uint256-). Requirements: @@ -768,7 +819,7 @@ acceptance magic value.
-[Batched](/contracts/5.x/erc1155) version of [`ERC1155.safeTransferFrom`](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-). +[Batched](/contracts/5.x/erc1155#batch-operations) version of [`ERC1155.safeTransferFrom`](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-). This function can potentially allow a reentrancy attack when transferring tokens @@ -867,9 +918,9 @@ returned by [`IERC1155MetadataURI.uri`](#IERC1155MetadataURI-uri-uint256-).
-## `IERC1155Receiver` +## `IERC1155Receiver` - + @@ -887,8 +938,12 @@ ERC-1155 token transfers.
- [onERC1155Received(operator, from, id, value, data)](#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-) - [onERC1155BatchReceived(operator, from, ids, values, data)](#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-) -#### IERC165 [!toc] +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -945,9 +1000,9 @@ To accept the transfer(s), this must return
-## `ERC1155Burnable` +## `ERC1155Burnable` - + @@ -965,7 +1020,9 @@ own tokens and those that they have been approved to use.
- [burn(account, id, value)](#ERC1155Burnable-burn-address-uint256-uint256-) - [burnBatch(account, ids, values)](#ERC1155Burnable-burnBatch-address-uint256---uint256---) -#### ERC1155 [!toc] +
+ERC1155 + - [supportsInterface(interfaceId)](#ERC1155-supportsInterface-bytes4-) - [uri()](#ERC1155-uri-uint256-) - [balanceOf(account, id)](#ERC1155-balanceOf-address-uint256-) @@ -974,8 +1031,10 @@ own tokens and those that they have been approved to use. - [isApprovedForAll(account, operator)](#ERC1155-isApprovedForAll-address-address-) - [safeTransferFrom(from, to, id, value, data)](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) - [safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-) +- [_checkAuthorized(operator, owner)](#ERC1155-_checkAuthorized-address-address-) - [_update(from, to, ids, values)](#ERC1155-_update-address-address-uint256---uint256---) - [_updateWithAcceptanceCheck(from, to, ids, values, data)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-) +- [_updateWithAcceptanceCheck(from, to, ids, values, data, batch)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-bool-) - [_safeTransferFrom(from, to, id, value, data)](#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-) - [_safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-) - [_setURI(newuri)](#ERC1155-_setURI-string-) @@ -984,35 +1043,32 @@ own tokens and those that they have been approved to use. - [_burn(from, id, value)](#ERC1155-_burn-address-uint256-uint256-) - [_burnBatch(from, ids, values)](#ERC1155-_burnBatch-address-uint256---uint256---) - [_setApprovalForAll(owner, operator, approved)](#ERC1155-_setApprovalForAll-address-address-bool-) -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### ERC1155 [!toc] -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] +
+IERC1155 + - [TransferSingle(operator, from, to, id, value)](#IERC1155-TransferSingle-address-address-address-uint256-uint256-) - [TransferBatch(operator, from, to, ids, values)](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) - [ApprovalForAll(account, operator, approved)](#IERC1155-ApprovalForAll-address-address-bool-) - [URI(value, id)](#IERC1155-URI-string-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### ERC1155 [!toc] -#### IERC1155Errors [!toc] +
+IERC1155Errors + - [ERC1155InsufficientBalance(sender, balance, needed, tokenId)](#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-) - [ERC1155InvalidSender(sender)](#IERC1155Errors-ERC1155InvalidSender-address-) - [ERC1155InvalidReceiver(receiver)](#IERC1155Errors-ERC1155InvalidReceiver-address-) @@ -1020,10 +1076,8 @@ own tokens and those that they have been approved to use. - [ERC1155InvalidApprover(approver)](#IERC1155Errors-ERC1155InvalidApprover-address-) - [ERC1155InvalidOperator(operator)](#IERC1155Errors-ERC1155InvalidOperator-address-) - [ERC1155InvalidArrayLength(idsLength, valuesLength)](#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-) -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -1057,13 +1111,218 @@ own tokens and those that they have been approved to use.
+ + +
+ +## `ERC1155Crosschain` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155Crosschain.sol"; +``` + +Extension of [`ERC1155`](#ERC1155) that makes it natively cross-chain using the ERC-7786 based [`BridgeMultiToken`](/contracts/5.x/api/crosschain#BridgeMultiToken). + +This extension makes the token compatible with: +* [`ERC1155Crosschain`](#ERC1155Crosschain) instances on other chains, +* [`ERC1155`](#ERC1155) instances on other chains that are bridged using [`BridgeERC1155`](/contracts/5.x/api/crosschain#BridgeERC1155), + +
+

Functions

+
+- [crosschainTransferFrom(from, to, id, value)](#ERC1155Crosschain-crosschainTransferFrom-address-bytes-uint256-uint256-) +- [crosschainTransferFrom(from, to, ids, values)](#ERC1155Crosschain-crosschainTransferFrom-address-bytes-uint256---uint256---) +- [_onSend(from, ids, values)](#ERC1155Crosschain-_onSend-address-uint256---uint256---) +- [_onReceive(to, ids, values)](#ERC1155Crosschain-_onReceive-address-uint256---uint256---) +
+BridgeMultiToken + +- [_crosschainTransfer(from, to, ids, values)](#BridgeMultiToken-_crosschainTransfer-address-bytes-uint256---uint256---) +- [_processMessage(, receiveId, , payload)](#BridgeMultiToken-_processMessage-address-bytes32-bytes-bytes-) + +
+
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+ERC1155 + +- [supportsInterface(interfaceId)](#ERC1155-supportsInterface-bytes4-) +- [uri()](#ERC1155-uri-uint256-) +- [balanceOf(account, id)](#ERC1155-balanceOf-address-uint256-) +- [balanceOfBatch(accounts, ids)](#ERC1155-balanceOfBatch-address---uint256---) +- [setApprovalForAll(operator, approved)](#ERC1155-setApprovalForAll-address-bool-) +- [isApprovedForAll(account, operator)](#ERC1155-isApprovedForAll-address-address-) +- [safeTransferFrom(from, to, id, value, data)](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) +- [safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-) +- [_checkAuthorized(operator, owner)](#ERC1155-_checkAuthorized-address-address-) +- [_update(from, to, ids, values)](#ERC1155-_update-address-address-uint256---uint256---) +- [_updateWithAcceptanceCheck(from, to, ids, values, data)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-) +- [_updateWithAcceptanceCheck(from, to, ids, values, data, batch)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-bool-) +- [_safeTransferFrom(from, to, id, value, data)](#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-) +- [_safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-) +- [_setURI(newuri)](#ERC1155-_setURI-string-) +- [_mint(to, id, value, data)](#ERC1155-_mint-address-uint256-uint256-bytes-) +- [_mintBatch(to, ids, values, data)](#ERC1155-_mintBatch-address-uint256---uint256---bytes-) +- [_burn(from, id, value)](#ERC1155-_burn-address-uint256-uint256-) +- [_burnBatch(from, ids, values)](#ERC1155-_burnBatch-address-uint256---uint256---) +- [_setApprovalForAll(owner, operator, approved)](#ERC1155-_setApprovalForAll-address-address-bool-) + +
+
+
+ +
+

Events

+
+
+BridgeMultiToken + +- [CrosschainMultiTokenTransferSent(sendId, from, to, ids, values)](#BridgeMultiToken-CrosschainMultiTokenTransferSent-bytes32-address-bytes-uint256---uint256---) +- [CrosschainMultiTokenTransferReceived(receiveId, from, to, ids, values)](#BridgeMultiToken-CrosschainMultiTokenTransferReceived-bytes32-bytes-address-uint256---uint256---) + +
+
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+IERC1155 + +- [TransferSingle(operator, from, to, id, value)](#IERC1155-TransferSingle-address-address-address-uint256-uint256-) +- [TransferBatch(operator, from, to, ids, values)](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) +- [ApprovalForAll(account, operator, approved)](#IERC1155-ApprovalForAll-address-address-bool-) +- [URI(value, id)](#IERC1155-URI-string-uint256-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+IERC1155Errors + +- [ERC1155InsufficientBalance(sender, balance, needed, tokenId)](#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-) +- [ERC1155InvalidSender(sender)](#IERC1155Errors-ERC1155InvalidSender-address-) +- [ERC1155InvalidReceiver(receiver)](#IERC1155Errors-ERC1155InvalidReceiver-address-) +- [ERC1155MissingApprovalForAll(operator, owner)](#IERC1155Errors-ERC1155MissingApprovalForAll-address-address-) +- [ERC1155InvalidApprover(approver)](#IERC1155Errors-ERC1155InvalidApprover-address-) +- [ERC1155InvalidOperator(operator)](#IERC1155Errors-ERC1155InvalidOperator-address-) +- [ERC1155InvalidArrayLength(idsLength, valuesLength)](#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-) + +
+
+
+ + + +
+
+

crosschainTransferFrom(address from, bytes to, uint256 id, uint256 value) โ†’ bytes32

+
+

public

+# +
+
+
+ +TransferFrom variant of [`ERC1155Crosschain.crosschainTransferFrom`](#ERC1155Crosschain-crosschainTransferFrom-address-bytes-uint256---uint256---), using ERC1155 allowance from the sender to the caller. + +
+
+ + + +
+
+

crosschainTransferFrom(address from, bytes to, uint256[] ids, uint256[] values) โ†’ bytes32

+
+

public

+# +
+
+
+ +TransferFrom variant of [`ERC1155Crosschain.crosschainTransferFrom`](#ERC1155Crosschain-crosschainTransferFrom-address-bytes-uint256---uint256---), using ERC1155 allowance from the sender to the caller. + +
+
+ + + +
+
+

_onSend(address from, uint256[] ids, uint256[] values)

+
+

internal

+# +
+
+
+ +"Locking" tokens is achieved through burning + +
+
+ + + +
+
+

_onReceive(address to, uint256[] ids, uint256[] values)

+
+

internal

+# +
+
+
+ +"Unlocking" tokens is achieved through minting + +
+
+
-## `ERC1155Pausable` +## `ERC1155Pausable` - + @@ -1082,8 +1341,8 @@ event of a large bug. This contract does not include public pause and unpause functions. In addition to inheriting this contract, you must define both functions, invoking the -[`Pausable._pause`](../utils#Pausable-_pause--) and [`Pausable._unpause`](../utils#Pausable-_unpause--) internal functions, with appropriate -access control, e.g. using [`AccessControl`](../access#AccessControl) or [`Ownable`](../access#Ownable). Not doing so will +[`Pausable._pause`](/contracts/5.x/api/utils#Pausable-_pause--) and [`Pausable._unpause`](/contracts/5.x/api/utils#Pausable-_unpause--) internal functions, with appropriate +access control, e.g. using [`AccessControl`](/contracts/5.x/api/access#AccessControl) or [`Ownable`](/contracts/5.x/api/access#Ownable). Not doing so will make the contract pause mechanism of the contract unreachable, and thus unusable. @@ -1091,13 +1350,19 @@ make the contract pause mechanism of the contract unreachable, and thus unusable

Functions

- [_update(from, to, ids, values)](#ERC1155Pausable-_update-address-address-uint256---uint256---) -#### Pausable [!toc] +
+Pausable + - [paused()](#Pausable-paused--) - [_requireNotPaused()](#Pausable-_requireNotPaused--) - [_requirePaused()](#Pausable-_requirePaused--) - [_pause()](#Pausable-_pause--) - [_unpause()](#Pausable-_unpause--) -#### ERC1155 [!toc] + +
+
+ERC1155 + - [supportsInterface(interfaceId)](#ERC1155-supportsInterface-bytes4-) - [uri()](#ERC1155-uri-uint256-) - [balanceOf(account, id)](#ERC1155-balanceOf-address-uint256-) @@ -1106,7 +1371,9 @@ make the contract pause mechanism of the contract unreachable, and thus unusable - [isApprovedForAll(account, operator)](#ERC1155-isApprovedForAll-address-address-) - [safeTransferFrom(from, to, id, value, data)](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) - [safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-) +- [_checkAuthorized(operator, owner)](#ERC1155-_checkAuthorized-address-address-) - [_updateWithAcceptanceCheck(from, to, ids, values, data)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-) +- [_updateWithAcceptanceCheck(from, to, ids, values, data, batch)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-bool-) - [_safeTransferFrom(from, to, id, value, data)](#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-) - [_safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-) - [_setURI(newuri)](#ERC1155-_setURI-string-) @@ -1115,41 +1382,46 @@ make the contract pause mechanism of the contract unreachable, and thus unusable - [_burn(from, id, value)](#ERC1155-_burn-address-uint256-uint256-) - [_burnBatch(from, ids, values)](#ERC1155-_burnBatch-address-uint256---uint256---) - [_setApprovalForAll(owner, operator, approved)](#ERC1155-_setApprovalForAll-address-address-bool-) -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Pausable [!toc] +
+Pausable + - [Paused(account)](#Pausable-Paused-address-) - [Unpaused(account)](#Pausable-Unpaused-address-) -#### ERC1155 [!toc] -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] + +
+
+IERC1155 + - [TransferSingle(operator, from, to, id, value)](#IERC1155-TransferSingle-address-address-address-uint256-uint256-) - [TransferBatch(operator, from, to, ids, values)](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) - [ApprovalForAll(account, operator, approved)](#IERC1155-ApprovalForAll-address-address-bool-) - [URI(value, id)](#IERC1155-URI-string-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Pausable [!toc] +
+Pausable + - [EnforcedPause()](#Pausable-EnforcedPause--) - [ExpectedPause()](#Pausable-ExpectedPause--) -#### ERC1155 [!toc] -#### IERC1155Errors [!toc] + +
+
+IERC1155Errors + - [ERC1155InsufficientBalance(sender, balance, needed, tokenId)](#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-) - [ERC1155InvalidSender(sender)](#IERC1155Errors-ERC1155InvalidSender-address-) - [ERC1155InvalidReceiver(receiver)](#IERC1155Errors-ERC1155InvalidReceiver-address-) @@ -1157,10 +1429,8 @@ make the contract pause mechanism of the contract unreachable, and thus unusable - [ERC1155InvalidApprover(approver)](#IERC1155Errors-ERC1155InvalidApprover-address-) - [ERC1155InvalidOperator(operator)](#IERC1155Errors-ERC1155InvalidOperator-address-) - [ERC1155InvalidArrayLength(idsLength, valuesLength)](#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-) -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -1189,9 +1459,9 @@ Requirements:
-## `ERC1155Supply` +## `ERC1155Supply` - + @@ -1204,16 +1474,18 @@ import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155Supply.sol"; Extension of ERC-1155 that adds tracking of total supply per id. Useful for scenarios where Fungible and Non-fungible tokens have to be -clearly identified. Note: While a totalSupply of 1 might mean the -corresponding is an NFT, there is no guarantees that no other token with the -same id are not going to be minted. +clearly identified. Note: While a `totalSupply` of 1 may mean the +corresponding token is an NFT, there are no inherent guarantees that +no more tokens with the same id will be minted in future. This contract implies a global limit of 2**256 - 1 to the number of tokens that can be minted. -CAUTION: This extension should not be added in an upgrade to an already deployed contract. + +This extension should not be added in an upgrade to an already deployed contract. +

Functions

@@ -1222,7 +1494,9 @@ CAUTION: This extension should not be added in an upgrade to an already deployed - [totalSupply()](#ERC1155Supply-totalSupply--) - [exists(id)](#ERC1155Supply-exists-uint256-) - [_update(from, to, ids, values)](#ERC1155Supply-_update-address-address-uint256---uint256---) -#### ERC1155 [!toc] +
+ERC1155 + - [supportsInterface(interfaceId)](#ERC1155-supportsInterface-bytes4-) - [uri()](#ERC1155-uri-uint256-) - [balanceOf(account, id)](#ERC1155-balanceOf-address-uint256-) @@ -1231,7 +1505,9 @@ CAUTION: This extension should not be added in an upgrade to an already deployed - [isApprovedForAll(account, operator)](#ERC1155-isApprovedForAll-address-address-) - [safeTransferFrom(from, to, id, value, data)](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) - [safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-) +- [_checkAuthorized(operator, owner)](#ERC1155-_checkAuthorized-address-address-) - [_updateWithAcceptanceCheck(from, to, ids, values, data)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-) +- [_updateWithAcceptanceCheck(from, to, ids, values, data, batch)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-bool-) - [_safeTransferFrom(from, to, id, value, data)](#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-) - [_safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-) - [_setURI(newuri)](#ERC1155-_setURI-string-) @@ -1240,35 +1516,32 @@ CAUTION: This extension should not be added in an upgrade to an already deployed - [_burn(from, id, value)](#ERC1155-_burn-address-uint256-uint256-) - [_burnBatch(from, ids, values)](#ERC1155-_burnBatch-address-uint256---uint256---) - [_setApprovalForAll(owner, operator, approved)](#ERC1155-_setApprovalForAll-address-address-bool-) -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### ERC1155 [!toc] -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] +
+IERC1155 + - [TransferSingle(operator, from, to, id, value)](#IERC1155-TransferSingle-address-address-address-uint256-uint256-) - [TransferBatch(operator, from, to, ids, values)](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) - [ApprovalForAll(account, operator, approved)](#IERC1155-ApprovalForAll-address-address-bool-) - [URI(value, id)](#IERC1155-URI-string-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### ERC1155 [!toc] -#### IERC1155Errors [!toc] +
+IERC1155Errors + - [ERC1155InsufficientBalance(sender, balance, needed, tokenId)](#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-) - [ERC1155InvalidSender(sender)](#IERC1155Errors-ERC1155InvalidSender-address-) - [ERC1155InvalidReceiver(receiver)](#IERC1155Errors-ERC1155InvalidReceiver-address-) @@ -1276,10 +1549,8 @@ CAUTION: This extension should not be added in an upgrade to an already deployed - [ERC1155InvalidApprover(approver)](#IERC1155Errors-ERC1155InvalidApprover-address-) - [ERC1155InvalidOperator(operator)](#IERC1155Errors-ERC1155InvalidOperator-address-) - [ERC1155InvalidArrayLength(idsLength, valuesLength)](#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-) -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -1295,7 +1566,7 @@ CAUTION: This extension should not be added in an upgrade to an already deployed
-Total value of tokens in with a given id. +Total value of tokens with a given id.
@@ -1329,7 +1600,7 @@ Total value of tokens.
-Indicates whether any token exist with a given id, or not. +Indicates whether any tokens exist with a given id, or not.
@@ -1358,7 +1629,7 @@ Requirements: - `ids` and `values` must have the same length. -The ERC-1155 acceptance check is not performed in this function. See [`ERC1155._updateWithAcceptanceCheck`](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-) instead. +The ERC-1155 acceptance check is not performed in this function. See [`ERC1155._updateWithAcceptanceCheck`](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-bool-) instead. @@ -1368,9 +1639,9 @@ The ERC-1155 acceptance check is not performed in this function. See [`ERC1155._
-## `ERC1155URIStorage` +## `ERC1155URIStorage` - + @@ -1389,7 +1660,9 @@ Inspired by the [`ERC721URIStorage`](/contracts/5.x/api/token/ERC721#ERC721URISt - [uri(tokenId)](#ERC1155URIStorage-uri-uint256-) - [_setURI(tokenId, tokenURI)](#ERC1155URIStorage-_setURI-uint256-string-) - [_setBaseURI(baseURI)](#ERC1155URIStorage-_setBaseURI-string-) -#### ERC1155 [!toc] +
+ERC1155 + - [supportsInterface(interfaceId)](#ERC1155-supportsInterface-bytes4-) - [balanceOf(account, id)](#ERC1155-balanceOf-address-uint256-) - [balanceOfBatch(accounts, ids)](#ERC1155-balanceOfBatch-address---uint256---) @@ -1397,8 +1670,10 @@ Inspired by the [`ERC721URIStorage`](/contracts/5.x/api/token/ERC721#ERC721URISt - [isApprovedForAll(account, operator)](#ERC1155-isApprovedForAll-address-address-) - [safeTransferFrom(from, to, id, value, data)](#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) - [safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-) +- [_checkAuthorized(operator, owner)](#ERC1155-_checkAuthorized-address-address-) - [_update(from, to, ids, values)](#ERC1155-_update-address-address-uint256---uint256---) - [_updateWithAcceptanceCheck(from, to, ids, values, data)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-) +- [_updateWithAcceptanceCheck(from, to, ids, values, data, batch)](#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-bool-) - [_safeTransferFrom(from, to, id, value, data)](#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-) - [_safeBatchTransferFrom(from, to, ids, values, data)](#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-) - [_setURI(newuri)](#ERC1155-_setURI-string-) @@ -1407,35 +1682,32 @@ Inspired by the [`ERC721URIStorage`](/contracts/5.x/api/token/ERC721#ERC721URISt - [_burn(from, id, value)](#ERC1155-_burn-address-uint256-uint256-) - [_burnBatch(from, ids, values)](#ERC1155-_burnBatch-address-uint256---uint256---) - [_setApprovalForAll(owner, operator, approved)](#ERC1155-_setApprovalForAll-address-address-bool-) -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### ERC1155 [!toc] -#### IERC1155Errors [!toc] -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] +
+IERC1155 + - [TransferSingle(operator, from, to, id, value)](#IERC1155-TransferSingle-address-address-address-uint256-uint256-) - [TransferBatch(operator, from, to, ids, values)](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) - [ApprovalForAll(account, operator, approved)](#IERC1155-ApprovalForAll-address-address-bool-) - [URI(value, id)](#IERC1155-URI-string-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### ERC1155 [!toc] -#### IERC1155Errors [!toc] +
+IERC1155Errors + - [ERC1155InsufficientBalance(sender, balance, needed, tokenId)](#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-) - [ERC1155InvalidSender(sender)](#IERC1155Errors-ERC1155InvalidSender-address-) - [ERC1155InvalidReceiver(receiver)](#IERC1155Errors-ERC1155InvalidReceiver-address-) @@ -1443,10 +1715,8 @@ Inspired by the [`ERC721URIStorage`](/contracts/5.x/api/token/ERC721#ERC721URISt - [ERC1155InvalidApprover(approver)](#IERC1155Errors-ERC1155InvalidApprover-address-) - [ERC1155InvalidOperator(operator)](#IERC1155Errors-ERC1155InvalidOperator-address-) - [ERC1155InvalidArrayLength(idsLength, valuesLength)](#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-) -#### IERC1155MetadataURI [!toc] -#### IERC1155 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -1520,9 +1790,9 @@ Sets `baseURI` as the `_baseURI` for all tokens
-## `IERC1155MetadataURI` +## `IERC1155MetadataURI` - + @@ -1539,27 +1809,38 @@ in the [ERC](https://eips.ethereum.org/EIPS/eip-1155#metadata-extensions).

Functions

- [uri(id)](#IERC1155MetadataURI-uri-uint256-) -#### IERC1155 [!toc] +
+IERC1155 + - [balanceOf(account, id)](#IERC1155-balanceOf-address-uint256-) - [balanceOfBatch(accounts, ids)](#IERC1155-balanceOfBatch-address---uint256---) - [setApprovalForAll(operator, approved)](#IERC1155-setApprovalForAll-address-bool-) - [isApprovedForAll(account, operator)](#IERC1155-isApprovedForAll-address-address-) - [safeTransferFrom(from, to, id, value, data)](#IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) - [safeBatchTransferFrom(from, to, ids, values, data)](#IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-#### IERC1155 [!toc] +
+IERC1155 + - [TransferSingle(operator, from, to, id, value)](#IERC1155-TransferSingle-address-address-address-uint256-uint256-) - [TransferBatch(operator, from, to, ids, values)](#IERC1155-TransferBatch-address-address-address-uint256---uint256---) - [ApprovalForAll(account, operator, approved)](#IERC1155-ApprovalForAll-address-address-bool-) - [URI(value, id)](#IERC1155-URI-string-uint256-) -#### IERC165 [!toc] + +
@@ -1587,9 +1868,9 @@ clients with the actual token type ID.
-## `ERC1155Holder` +## `ERC1155Holder` - + @@ -1614,9 +1895,6 @@ stuck. - [supportsInterface(interfaceId)](#ERC1155Holder-supportsInterface-bytes4-) - [onERC1155Received(, , , , )](#ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-) - [onERC1155BatchReceived(, , , , )](#ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-) -#### IERC1155Receiver [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc]
@@ -1676,9 +1954,9 @@ This function call must use less than 30 000 gas.
-## `ERC1155Utils` +## `ERC1155Utils` - + @@ -1745,3 +2023,4 @@ the transfer.
+ diff --git a/content/contracts/5.x/api/token/ERC20.mdx b/content/contracts/5.x/api/token/ERC20.mdx index f0473dda..4c9d8b45 100644 --- a/content/contracts/5.x/api/token/ERC20.mdx +++ b/content/contracts/5.x/api/token/ERC20.mdx @@ -21,6 +21,7 @@ Additionally there are multiple custom extensions, including: * [`ERC20Bridgeable`](#ERC20Bridgeable): compatibility with crosschain bridges through ERC-7802. * [`ERC20Burnable`](#ERC20Burnable): destruction of own tokens. * [`ERC20Capped`](#ERC20Capped): enforcement of a cap to the total supply when minting tokens. +* [`ERC20Crosschain`](#ERC20Crosschain): embedded [`BridgeFungible`](/contracts/5.x/api/crosschain#BridgeFungible) bridge, making the token crosschain through the use of ERC-7786 gateways. * [`ERC20Pausable`](#ERC20Pausable): ability to pause token transfers. * [`ERC20FlashMint`](#ERC20FlashMint): token level support for flash loans through the minting and burning of ephemeral tokens (standardized as ERC-3156). * [`ERC20Votes`](#ERC20Votes): support for voting and vote delegation. [See the governance guide for a minimal example (with the required overrides when combining ERC20 + ERC20Permit + ERC20Votes)](/contracts/5.x/api/governance#token). @@ -35,7 +36,7 @@ Finally, there are some utilities to interact with ERC-20 contracts in various w Other utilities that support ERC-20 assets can be found in the codebase: -* ERC-20 tokens can be timelocked (held for a beneficiary until a specified time) or vested (released following a given schedule) using a [`VestingWallet`](../finance#VestingWallet). +* ERC-20 tokens can be timelocked (held for a beneficiary until a specified time) or vested (released following a given schedule) using a [`VestingWallet`](/contracts/5.x/api/finance#VestingWallet). This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC-20 (such as [`_mint`](#ERC20-_mint-address-uint256-)) and expose them as external functions in the way they prefer. @@ -61,6 +62,8 @@ This core set of contracts is designed to be unopinionated, allowing developers [`ERC20Capped`](#ERC20Capped) +[`ERC20Crosschain`](#ERC20Crosschain) + [`ERC20Pausable`](#ERC20Pausable) [`ERC20Votes`](#ERC20Votes) @@ -85,9 +88,9 @@ This core set of contracts is designed to be unopinionated, allowing developers
-## `ERC20` +## `ERC20` - + @@ -100,7 +103,7 @@ import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; Implementation of the [`IERC20`](#IERC20) interface. This implementation is agnostic to the way tokens are created. This means -that a supply mechanism has to be added in a derived contract using [`ERC1155._mint`](/contracts/5.x/api/token/ERC1155#ERC1155-_mint-address-uint256-uint256-bytes-). +that a supply mechanism has to be added in a derived contract using [`ERC20._mint`](#ERC20-_mint-address-uint256-). For a detailed writeup see our guide @@ -108,7 +111,7 @@ For a detailed writeup see our guide to implement supply mechanisms](https://forum.openzeppelin.com/t/how-to-implement-erc20-supply-mechanisms/226). -The default value of [`IERC6909Metadata.decimals`](../interfaces#IERC6909Metadata-decimals-uint256-) is 18. To change this, you should override +The default value of [`ERC20.decimals`](#ERC20-decimals--) is 18. To change this, you should override this function so it returns a different value. We have followed general OpenZeppelin Contracts guidelines: functions revert @@ -136,35 +139,36 @@ applications. - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc]

Events

-#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -180,7 +184,7 @@ applications.
-Sets the values for [`Governor.name`](../governance#Governor-name--) and [`IERC6909Metadata.symbol`](../interfaces#IERC6909Metadata-symbol-uint256-). +Sets the values for [`ERC20.name`](#ERC20-name--) and [`ERC20.symbol`](#ERC20-symbol--). Both values are immutable: they can only be set once during construction. @@ -320,10 +324,10 @@ Requirements:
Returns the remaining number of tokens that `spender` will be -allowed to spend on behalf of `owner` through [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-). This is +allowed to spend on behalf of `owner` through [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-). This is zero by default. -This value changes when [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) or [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-) are called. +This value changes when [`ERC20.approve`](#ERC20-approve-address-uint256-) or [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-) are called.
@@ -368,7 +372,7 @@ Requirements: See [`IERC20.transferFrom`](#IERC20-transferFrom-address-address-uint256-). -Skips emitting an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event indicating an allowance update. This is not +Skips emitting an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event indicating an allowance update. This is not required by the ERC. See [_approve](#ERC20-_approve-address-address-uint256-bool-). @@ -400,13 +404,13 @@ Requirements: Moves a `value` amount of tokens from `from` to `to`. -This internal function is equivalent to [`IERC6909.transfer`](../interfaces#IERC6909-transfer-address-uint256-uint256-), and can be used to +This internal function is equivalent to [`ERC20.transfer`](#ERC20-transfer-address-uint256-), and can be used to e.g. implement automatic token fees, slashing mechanisms, etc. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event. -This function is not virtual, [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) should be overridden instead. +This function is not virtual, [`ERC20._update`](#ERC20-_update-address-address-uint256-) should be overridden instead. @@ -428,7 +432,7 @@ Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding this function. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event. @@ -448,10 +452,10 @@ Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-ad Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0). Relies on the `_update` mechanism -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event with `from` set to the zero address. +Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event with `from` set to the zero address. -This function is not virtual, [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) should be overridden instead. +This function is not virtual, [`ERC20._update`](#ERC20-_update-address-address-uint256-) should be overridden instead. @@ -472,10 +476,10 @@ This function is not virtual, [`ERC1155._update`](/contracts/5.x/api/token/ERC11 Destroys a `value` amount of tokens from `account`, lowering the total supply. Relies on the `_update` mechanism. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event with `to` set to the zero address. +Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event with `to` set to the zero address. -This function is not virtual, [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) should be overridden instead +This function is not virtual, [`ERC20._update`](#ERC20-_update-address-address-uint256-) should be overridden instead @@ -498,7 +502,7 @@ Sets `value` as the allowance of `spender` over the `owner`'s tokens. This internal function is equivalent to `approve`, and can be used to e.g. set automatic allowances for certain subsystems, etc. -Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event. Requirements: @@ -522,7 +526,7 @@ Overrides to this logic should be done to the variant with an additional `bool e
-Variant of [`ERC20._approve`](#ERC20-_approve-address-address-uint256-bool-) with an optional flag to enable or disable the [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Variant of [`ERC20._approve`](#ERC20-_approve-address-address-uint256-bool-) with an optional flag to enable or disable the [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event. By default (when calling [`ERC20._approve`](#ERC20-_approve-address-address-uint256-bool-)) the flag is set to true. On the other hand, approval changes made by `_spendAllowance` during the `transferFrom` operation sets the flag to false. This saves gas by not emitting any @@ -559,7 +563,7 @@ Updates `owner`'s allowance for `spender` based on spent `value`. Does not update the allowance value in case of infinite allowance. Revert if not enough allowance is available. -Does not emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Does not emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
@@ -568,9 +572,9 @@ Does not emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-a
-## `IERC20` +## `IERC20` - + @@ -652,7 +656,7 @@ Moves a `value` amount of tokens from the caller's account to `to`. Returns a boolean value indicating whether the operation succeeded. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event.
@@ -670,10 +674,10 @@ Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-ad
Returns the remaining number of tokens that `spender` will be -allowed to spend on behalf of `owner` through [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-). This is +allowed to spend on behalf of `owner` through [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-). This is zero by default. -This value changes when [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) or [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-) are called. +This value changes when [`ERC20.approve`](#ERC20-approve-address-uint256-) or [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-) are called.
@@ -704,7 +708,7 @@ desired value afterwards: https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729 -Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event. @@ -727,7 +731,7 @@ allowance. Returns a boolean value indicating whether the operation succeeded. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event. @@ -766,7 +770,7 @@ Note that `value` may be zero.
Emitted when the allowance of a `spender` for an `owner` is set by -a call to [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-). `value` is the new allowance. +a call to [`ERC20.approve`](#ERC20-approve-address-uint256-). `value` is the new allowance.
@@ -775,9 +779,9 @@ a call to [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-ui
-## `ERC1363` +## `ERC1363` - + @@ -803,10 +807,9 @@ _Available since v5.1._ - [transferFromAndCall(from, to, value, data)](#ERC1363-transferFromAndCall-address-address-uint256-bytes-) - [approveAndCall(spender, value)](#ERC1363-approveAndCall-address-uint256-) - [approveAndCall(spender, value, data)](#ERC1363-approveAndCall-address-uint256-bytes-) -#### IERC1363 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -823,24 +826,21 @@ _Available since v5.1._ - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### IERC1363 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -850,19 +850,17 @@ _Available since v5.1._ - [ERC1363TransferFailed(receiver, value)](#ERC1363-ERC1363TransferFailed-address-uint256-) - [ERC1363TransferFromFailed(sender, receiver, value)](#ERC1363-ERC1363TransferFromFailed-address-address-uint256-) - [ERC1363ApproveFailed(spender, value)](#ERC1363-ERC1363ApproveFailed-address-uint256-) -#### IERC1363 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -901,15 +899,15 @@ This function call must use less than 30 000 gas.
Moves a `value` amount of tokens from the caller's account to `to` -and then calls [`IERC1363Receiver.onTransferReceived`](../interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on `to`. Returns a flag that indicates +and then calls [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on `to`. Returns a flag that indicates if the call succeeded. Requirements: - The target has code (i.e. is a contract). -- The target `to` must implement the [`IERC1363Receiver`](../interfaces#IERC1363Receiver) interface. -- The target must return the [`IERC1363Receiver.onTransferReceived`](../interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) selector to accept the transfer. -- The internal [`IERC6909.transfer`](../interfaces#IERC6909-transfer-address-uint256-uint256-) must succeed (returned `true`). +- The target `to` must implement the [`IERC1363Receiver`](/contracts/5.x/api/interfaces#IERC1363Receiver) interface. +- The target must return the [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) selector to accept the transfer. +- The internal [`ERC20.transfer`](#ERC20-transfer-address-uint256-) must succeed (returned `true`).
@@ -926,7 +924,7 @@ Requirements:
-Variant of [`IERC1363.transferAndCall`](../interfaces#IERC1363-transferAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with +Variant of [`ERC1363.transferAndCall`](#ERC1363-transferAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with no specified format.
@@ -945,15 +943,15 @@ no specified format.
Moves a `value` amount of tokens from `from` to `to` using the allowance mechanism -and then calls [`IERC1363Receiver.onTransferReceived`](../interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on `to`. Returns a flag that indicates +and then calls [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on `to`. Returns a flag that indicates if the call succeeded. Requirements: - The target has code (i.e. is a contract). -- The target `to` must implement the [`IERC1363Receiver`](../interfaces#IERC1363Receiver) interface. -- The target must return the [`IERC1363Receiver.onTransferReceived`](../interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) selector to accept the transfer. -- The internal [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-) must succeed (returned `true`). +- The target `to` must implement the [`IERC1363Receiver`](/contracts/5.x/api/interfaces#IERC1363Receiver) interface. +- The target must return the [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) selector to accept the transfer. +- The internal [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-) must succeed (returned `true`).
@@ -970,7 +968,7 @@ Requirements:
-Variant of [`IERC1363.transferFromAndCall`](../interfaces#IERC1363-transferFromAndCall-address-address-uint256-bytes-) that accepts an additional `data` parameter with +Variant of [`ERC1363.transferFromAndCall`](#ERC1363-transferFromAndCall-address-address-uint256-bytes-) that accepts an additional `data` parameter with no specified format.
@@ -989,15 +987,15 @@ no specified format.
Sets a `value` amount of tokens as the allowance of `spender` over the -caller's tokens and then calls [`IERC1363Spender.onApprovalReceived`](../interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) on `spender`. +caller's tokens and then calls [`IERC1363Spender.onApprovalReceived`](/contracts/5.x/api/interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) on `spender`. Returns a flag that indicates if the call succeeded. Requirements: - The target has code (i.e. is a contract). -- The target `spender` must implement the [`IERC1363Spender`](../interfaces#IERC1363Spender) interface. -- The target must return the [`IERC1363Spender.onApprovalReceived`](../interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) selector to accept the approval. -- The internal [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) must succeed (returned `true`). +- The target `spender` must implement the [`IERC1363Spender`](/contracts/5.x/api/interfaces#IERC1363Spender) interface. +- The target must return the [`IERC1363Spender.onApprovalReceived`](/contracts/5.x/api/interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) selector to accept the approval. +- The internal [`ERC20.approve`](#ERC20-approve-address-uint256-) must succeed (returned `true`).
@@ -1014,7 +1012,7 @@ Requirements:
-Variant of [`IERC1363.approveAndCall`](../interfaces#IERC1363-approveAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with +Variant of [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with no specified format.
@@ -1032,7 +1030,7 @@ no specified format.
-Indicates a failure within the [`IERC6909.transfer`](../interfaces#IERC6909-transfer-address-uint256-uint256-) part of a transferAndCall operation. +Indicates a failure within the [`ERC20.transfer`](#ERC20-transfer-address-uint256-) part of a transferAndCall operation.
@@ -1049,7 +1047,7 @@ Indicates a failure within the [`IERC6909.transfer`](../interfaces#IERC6909-tran
-Indicates a failure within the [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-) part of a transferFromAndCall operation. +Indicates a failure within the [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-) part of a transferFromAndCall operation.
@@ -1066,7 +1064,7 @@ Indicates a failure within the [`IERC6909.transferFrom`](../interfaces#IERC6909-
-Indicates a failure within the [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) part of a approveAndCall operation. +Indicates a failure within the [`ERC20.approve`](#ERC20-approve-address-uint256-) part of a approveAndCall operation.
@@ -1075,9 +1073,9 @@ Indicates a failure within the [`IERC6909.approve`](../interfaces#IERC6909-appro
-## `ERC20Burnable` +## `ERC20Burnable` - + @@ -1096,7 +1094,9 @@ recognized off-chain (via event analysis).
- [burn(value)](#ERC20Burnable-burn-uint256-) - [burnFrom(account, value)](#ERC20Burnable-burnFrom-address-uint256-) -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -1113,37 +1113,38 @@ recognized off-chain (via event analysis). - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -1195,9 +1196,9 @@ Requirements:
-## `ERC20Capped` +## `ERC20Capped` - + @@ -1215,7 +1216,9 @@ Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens. - [constructor(cap_)](#ERC20Capped-constructor-uint256-) - [cap()](#ERC20Capped-cap--) - [_update(from, to, value)](#ERC20Capped-_update-address-address-uint256-) -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -1231,21 +1234,21 @@ Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens. - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -1254,16 +1257,17 @@ Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens.
- [ERC20ExceededCap(increasedSupply, cap)](#ERC20Capped-ERC20ExceededCap-uint256-uint256-) - [ERC20InvalidCap(cap)](#ERC20Capped-ERC20InvalidCap-uint256-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -1318,7 +1322,7 @@ Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding this function. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event. @@ -1357,13 +1361,200 @@ The supplied cap is not a valid cap. + + +
+ +## `ERC20Crosschain` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Crosschain.sol"; +``` + +Extension of [`ERC20`](#ERC20) that makes it natively cross-chain using the ERC-7786 based [`BridgeFungible`](/contracts/5.x/api/crosschain#BridgeFungible). + +This extension makes the token compatible with counterparts on other chains, which can be: +* [`ERC20Crosschain`](#ERC20Crosschain) instances, +* [`ERC20`](#ERC20) instances that are bridged using [`BridgeERC20`](/contracts/5.x/api/crosschain#BridgeERC20), +* [`ERC20Bridgeable`](#ERC20Bridgeable) instances that are bridged using [`BridgeERC7802`](/contracts/5.x/api/crosschain#BridgeERC7802). + +It is mostly equivalent to inheriting from both [`ERC20Bridgeable`](#ERC20Bridgeable) and [`BridgeERC7802`](/contracts/5.x/api/crosschain#BridgeERC7802), and configuring them such +that: +* `token` (on the [`BridgeERC7802`](/contracts/5.x/api/crosschain#BridgeERC7802) side) is `address(this)`, +* `_checkTokenBridge` (on the [`ERC20Bridgeable`](#ERC20Bridgeable) side) is implemented such that it only accepts self-calls. + +
+

Functions

+
+- [crosschainTransferFrom(from, to, amount)](#ERC20Crosschain-crosschainTransferFrom-address-bytes-uint256-) +- [_onSend(from, amount)](#ERC20Crosschain-_onSend-address-uint256-) +- [_onReceive(to, amount)](#ERC20Crosschain-_onReceive-address-uint256-) +
+BridgeFungible + +- [crosschainTransfer(to, amount)](#BridgeFungible-crosschainTransfer-bytes-uint256-) +- [_crosschainTransfer(from, to, amount)](#BridgeFungible-_crosschainTransfer-address-bytes-uint256-) +- [_processMessage(, receiveId, , payload)](#BridgeFungible-_processMessage-address-bytes32-bytes-bytes-) + +
+
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+ERC20 + +- [name()](#ERC20-name--) +- [symbol()](#ERC20-symbol--) +- [decimals()](#ERC20-decimals--) +- [totalSupply()](#ERC20-totalSupply--) +- [balanceOf(account)](#ERC20-balanceOf-address-) +- [transfer(to, value)](#ERC20-transfer-address-uint256-) +- [allowance(owner, spender)](#ERC20-allowance-address-address-) +- [approve(spender, value)](#ERC20-approve-address-uint256-) +- [transferFrom(from, to, value)](#ERC20-transferFrom-address-address-uint256-) +- [_transfer(from, to, value)](#ERC20-_transfer-address-address-uint256-) +- [_update(from, to, value)](#ERC20-_update-address-address-uint256-) +- [_mint(account, value)](#ERC20-_mint-address-uint256-) +- [_burn(account, value)](#ERC20-_burn-address-uint256-) +- [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) +- [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) +- [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) + +
+
+
+ +
+

Events

+
+
+BridgeFungible + +- [CrosschainFungibleTransferSent(sendId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferSent-bytes32-address-bytes-uint256-) +- [CrosschainFungibleTransferReceived(receiveId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferReceived-bytes32-bytes-address-uint256-) + +
+
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+IERC20 + +- [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) +- [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+IERC20Errors + +- [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) +- [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) +- [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) +- [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) +- [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) +- [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) + +
+
+
+ + + +
+
+

crosschainTransferFrom(address from, bytes to, uint256 amount) โ†’ bytes32

+
+

public

+# +
+
+
+ +Variant of [`BridgeFungible.crosschainTransfer`](/contracts/5.x/api/crosschain#BridgeFungible-crosschainTransfer-bytes-uint256-) that allows an authorized account (using ERC20 allowance) to operate on `from`'s assets. + +
+
+ + + +
+
+

_onSend(address from, uint256 amount)

+
+

internal

+# +
+
+
+ +"Locking" tokens is achieved through burning + +
+
+ + + +
+
+

_onReceive(address to, uint256 amount)

+
+

internal

+# +
+
+
+ +"Unlocking" tokens is achieved through minting + +
+
+
-## `ERC20FlashMint` +## `ERC20FlashMint` - + @@ -1376,13 +1567,13 @@ import "@openzeppelin/contracts/token/ERC20/extensions/ERC20FlashMint.sol"; Implementation of the ERC-3156 Flash loans extension, as defined in [ERC-3156](https://eips.ethereum.org/EIPS/eip-3156). -Adds the [`IERC3156FlashLender.flashLoan`](../interfaces#IERC3156FlashLender-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-) method, which provides flash loan support at the token -level. By default there is no fee, but this can be changed by overriding [`IERC3156FlashLender.flashFee`](../interfaces#IERC3156FlashLender-flashFee-address-uint256-). +Adds the [`ERC20FlashMint.flashLoan`](#ERC20FlashMint-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-) method, which provides flash loan support at the token +level. By default there is no fee, but this can be changed by overriding [`ERC20FlashMint.flashFee`](#ERC20FlashMint-flashFee-address-uint256-). When this extension is used along with the [`ERC20Capped`](#ERC20Capped) or [`ERC20Votes`](#ERC20Votes) extensions, -[`IERC3156FlashLender.maxFlashLoan`](../interfaces#IERC3156FlashLender-maxFlashLoan-address-) will not correctly reflect the maximum that can be flash minted. We recommend -overriding [`IERC3156FlashLender.maxFlashLoan`](../interfaces#IERC3156FlashLender-maxFlashLoan-address-) so that it correctly reflects the supply cap. +[`ERC20FlashMint.maxFlashLoan`](#ERC20FlashMint-maxFlashLoan-address-) will not correctly reflect the maximum that can be flash minted. We recommend +overriding [`ERC20FlashMint.maxFlashLoan`](#ERC20FlashMint-maxFlashLoan-address-) so that it correctly reflects the supply cap.
@@ -1390,11 +1581,12 @@ overriding [`IERC3156FlashLender.maxFlashLoan`](../interfaces#IERC3156FlashLende
- [maxFlashLoan(token)](#ERC20FlashMint-maxFlashLoan-address-) - [flashFee(token, value)](#ERC20FlashMint-flashFee-address-uint256-) -- [_flashFee(token, value)](#ERC20FlashMint-_flashFee-address-uint256-) +- [_flashFee(, )](#ERC20FlashMint-_flashFee-address-uint256-) - [_flashFeeReceiver()](#ERC20FlashMint-_flashFeeReceiver--) - [flashLoan(receiver, token, value, data)](#ERC20FlashMint-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-) -#### IERC3156FlashLender [!toc] -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -1411,22 +1603,21 @@ overriding [`IERC3156FlashLender.maxFlashLoan`](../interfaces#IERC3156FlashLende - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### IERC3156FlashLender [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -1436,17 +1627,17 @@ overriding [`IERC3156FlashLender.maxFlashLoan`](../interfaces#IERC3156FlashLende - [ERC3156UnsupportedToken(token)](#ERC20FlashMint-ERC3156UnsupportedToken-address-) - [ERC3156ExceededMaxLoan(maxLoan)](#ERC20FlashMint-ERC3156ExceededMaxLoan-uint256-) - [ERC3156InvalidReceiver(receiver)](#ERC20FlashMint-ERC3156InvalidReceiver-address-) -#### IERC3156FlashLender [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -1464,6 +1655,12 @@ overriding [`IERC3156FlashLender.maxFlashLoan`](../interfaces#IERC3156FlashLende Returns the maximum amount of tokens available for loan. + +This function will not automatically detect any supply cap +added by other extensions, such as [`ERC20Capped`](#ERC20Capped). If necessary, +override this function to take a supply cap into account. + + @@ -1490,7 +1687,7 @@ loans.
-

_flashFee(address token, uint256 value) โ†’ uint256

+

_flashFee(address, uint256) โ†’ uint256

internal

# @@ -1537,7 +1734,7 @@ This function can be overloaded to change the fee receiver.
Performs a flash loan. New tokens are minted and sent to the -`receiver`, who is required to implement the [`IERC3156FlashBorrower`](../interfaces#IERC3156FlashBorrower) +`receiver`, who is required to implement the [`IERC3156FlashBorrower`](/contracts/5.x/api/interfaces#IERC3156FlashBorrower) interface. By the end of the flash loan, the receiver is expected to own value + fee tokens and have them approved back to the token contract itself so they can be burned. @@ -1591,7 +1788,7 @@ The requested loan exceeds the max loan value for `token`.
-The receiver of a flashloan is not a valid [`IERC3156FlashBorrower.onFlashLoan`](../interfaces#IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-) implementer. +The receiver of a flashloan is not a valid [`IERC3156FlashBorrower.onFlashLoan`](/contracts/5.x/api/interfaces#IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-) implementer.
@@ -1600,9 +1797,9 @@ The receiver of a flashloan is not a valid [`IERC3156FlashBorrower.onFlashLoan`]
-## `ERC20Pausable` +## `ERC20Pausable` - + @@ -1621,8 +1818,8 @@ event of a large bug. This contract does not include public pause and unpause functions. In addition to inheriting this contract, you must define both functions, invoking the -[`Pausable._pause`](../utils#Pausable-_pause--) and [`Pausable._unpause`](../utils#Pausable-_unpause--) internal functions, with appropriate -access control, e.g. using [`AccessControl`](../access#AccessControl) or [`Ownable`](../access#Ownable). Not doing so will +[`Pausable._pause`](/contracts/5.x/api/utils#Pausable-_pause--) and [`Pausable._unpause`](/contracts/5.x/api/utils#Pausable-_unpause--) internal functions, with appropriate +access control, e.g. using [`AccessControl`](/contracts/5.x/api/access#AccessControl) or [`Ownable`](/contracts/5.x/api/access#Ownable). Not doing so will make the contract pause mechanism of the contract unreachable, and thus unusable. @@ -1630,13 +1827,19 @@ make the contract pause mechanism of the contract unreachable, and thus unusable

Functions

- [_update(from, to, value)](#ERC20Pausable-_update-address-address-uint256-) -#### Pausable [!toc] +
+Pausable + - [paused()](#Pausable-paused--) - [_requireNotPaused()](#Pausable-_requireNotPaused--) - [_requirePaused()](#Pausable-_requirePaused--) - [_pause()](#Pausable-_pause--) - [_unpause()](#Pausable-_unpause--) -#### ERC20 [!toc] + +
+
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -1652,43 +1855,52 @@ make the contract pause mechanism of the contract unreachable, and thus unusable - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### Pausable [!toc] +
+Pausable + - [Paused(account)](#Pausable-Paused-address-) - [Unpaused(account)](#Pausable-Unpaused-address-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
+
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-#### Pausable [!toc] +
+Pausable + - [EnforcedPause()](#Pausable-EnforcedPause--) - [ExpectedPause()](#Pausable-ExpectedPause--) -#### ERC20 [!toc] -#### IERC20Errors [!toc] + +
+
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -1717,9 +1929,9 @@ Requirements:
-## `ERC20Permit` +## `ERC20Permit` - + @@ -1743,18 +1955,26 @@ need to send a transaction, and thus is not required to hold Ether at all. - [permit(owner, spender, value, deadline, v, r, s)](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) - [nonces(owner)](#ERC20Permit-nonces-address-) - [DOMAIN_SEPARATOR()](#ERC20Permit-DOMAIN_SEPARATOR--) -#### Nonces [!toc] +
+Nonces + - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### IERC20Permit [!toc] -#### ERC20 [!toc] + +
+
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -1771,26 +1991,27 @@ need to send a transaction, and thus is not required to hold Ether at all. - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] +
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### IERC20Permit [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
+
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -1799,21 +2020,23 @@ need to send a transaction, and thus is not required to hold Ether at all.
- [ERC2612ExpiredSignature(deadline)](#ERC20Permit-ERC2612ExpiredSignature-uint256-) - [ERC2612InvalidSigner(signer, owner)](#ERC20Permit-ERC2612InvalidSigner-address-address-) -#### Nonces [!toc] +
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### IERC20Permit [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] + +
+
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -1829,7 +2052,7 @@ need to send a transaction, and thus is not required to hold Ether at all.
-Initializes the [`EIP712`](../utils/cryptography#EIP712) domain separator using the `name` parameter, and setting `version` to `"1"`. +Initializes the [`EIP712`](/contracts/5.x/api/utils/cryptography#EIP712) domain separator using the `name` parameter, and setting `version` to `"1"`. It's a good idea to use the same `name` that is defined as the ERC-20 token name. @@ -1856,7 +2079,7 @@ The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related ordering also applies here. -Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event. Requirements: @@ -1870,7 +2093,9 @@ For more information on the signature format, see the [relevant EIP section](https://eips.ethereum.org/EIPS/eip-2612#specification). -CAUTION: See Security Considerations above. + +See Security Considerations above. +
@@ -1908,7 +2133,7 @@ prevents a signature from being used multiple times.
-Returns the domain separator used in the encoding of the signature for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-), as defined by [`EIP712`](../utils/cryptography#EIP712). +Returns the domain separator used in the encoding of the signature for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-), as defined by [`EIP712`](/contracts/5.x/api/utils/cryptography#EIP712).
@@ -1951,9 +2176,9 @@ Mismatched signature.
-## `ERC20Votes` +## `ERC20Votes` - + @@ -1971,8 +2196,8 @@ This contract does not provide interface compatibility with Compound's COMP toke This extension keeps a history (checkpoints) of each account's vote power. Vote power can be delegated either -by calling the [`Votes.delegate`](../governance#Votes-delegate-address-) function directly, or by providing a signature to be used with [`Votes.delegateBySig`](../governance#Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-). Voting -power can be queried through the public accessors [`Votes.getVotes`](../governance#Votes-getVotes-address-) and [`Votes.getPastVotes`](../governance#Votes-getPastVotes-address-uint256-). +by calling the [`Votes.delegate`](/contracts/5.x/api/governance#Votes-delegate-address-) function directly, or by providing a signature to be used with [`Votes.delegateBySig`](/contracts/5.x/api/governance#Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-). Voting +power can be queried through the public accessors [`Votes.getVotes`](/contracts/5.x/api/governance#Votes-getVotes-address-) and [`Votes.getPastVotes`](/contracts/5.x/api/governance#Votes-getPastVotes-address-uint256-). By default, token balance does not account for voting power. This makes transfers cheaper. The downside is that it requires users to delegate to themselves in order to activate checkpoints and have their voting power tracked. @@ -1985,7 +2210,9 @@ requires users to delegate to themselves in order to activate checkpoints and ha - [_getVotingUnits(account)](#ERC20Votes-_getVotingUnits-address-) - [numCheckpoints(account)](#ERC20Votes-numCheckpoints-address-) - [checkpoints(account, pos)](#ERC20Votes-checkpoints-address-uint32-) -#### Votes [!toc] +
+Votes + - [clock()](#Votes-clock--) - [CLOCK_MODE()](#Votes-CLOCK_MODE--) - [_validateTimepoint(timepoint)](#Votes-_validateTimepoint-uint256-) @@ -2001,21 +2228,29 @@ requires users to delegate to themselves in order to activate checkpoints and ha - [_moveDelegateVotes(from, to, amount)](#Votes-_moveDelegateVotes-address-address-uint256-) - [_numCheckpoints(account)](#Votes-_numCheckpoints-address-) - [_checkpoints(account, pos)](#Votes-_checkpoints-address-uint32-) -#### IERC5805 [!toc] -#### IVotes [!toc] -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC20 [!toc] + +
+
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -2031,31 +2266,34 @@ requires users to delegate to themselves in order to activate checkpoints and ha - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### Votes [!toc] -#### IERC5805 [!toc] -#### IVotes [!toc] +
+IVotes + - [DelegateChanged(delegator, fromDelegate, toDelegate)](#IVotes-DelegateChanged-address-address-address-) - [DelegateVotesChanged(delegate, previousVotes, newVotes)](#IVotes-DelegateVotesChanged-address-uint256-uint256-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
+
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -2063,27 +2301,36 @@ requires users to delegate to themselves in order to activate checkpoints and ha

Errors

- [ERC20ExceededSafeSupply(increasedSupply, cap)](#ERC20Votes-ERC20ExceededSafeSupply-uint256-uint256-) -#### Votes [!toc] +
+Votes + - [ERC6372InconsistentClock()](#Votes-ERC6372InconsistentClock--) - [ERC5805FutureLookup(timepoint, clock)](#Votes-ERC5805FutureLookup-uint256-uint48-) -#### IERC5805 [!toc] -#### IVotes [!toc] + +
+
+IVotes + - [VotesExpiredSignature(expiry)](#IVotes-VotesExpiredSignature-uint256-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] + +
+
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -2101,10 +2348,10 @@ requires users to delegate to themselves in order to activate checkpoints and ha Maximum token supply. Defaults to `type(uint208).max` (2^208^ - 1). -This maximum is enforced in [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---). It limits the total supply of the token, which is otherwise a uint256, -so that checkpoints can be stored in the Trace208 structure used by [`Votes`](../governance#Votes). Increasing this value will not -remove the underlying limitation, and will cause [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) to fail because of a math overflow in -[`Votes._transferVotingUnits`](../governance#Votes-_transferVotingUnits-address-address-uint256-). An override could be used to further restrict the total supply (to a lower value) if +This maximum is enforced in [`ERC20._update`](#ERC20-_update-address-address-uint256-). It limits the total supply of the token, which is otherwise a uint256, +so that checkpoints can be stored in the Trace208 structure used by [`Votes`](/contracts/5.x/api/governance#Votes). Increasing this value will not +remove the underlying limitation, and will cause [`ERC20._update`](#ERC20-_update-address-address-uint256-) to fail because of a math overflow in +[`Votes._transferVotingUnits`](/contracts/5.x/api/governance#Votes-_transferVotingUnits-address-address-uint256-). An override could be used to further restrict the total supply (to a lower value) if additional logic requires it. When resolving override conflicts on this function, the minimum should be returned. @@ -2125,7 +2372,7 @@ returned. Move voting power when tokens are transferred. -Emits a [`IVotes.DelegateVotesChanged`](../governance#IVotes-DelegateVotesChanged-address-uint256-uint256-) event. +Emits a [`IVotes.DelegateVotesChanged`](/contracts/5.x/api/governance#IVotes-DelegateVotesChanged-address-uint256-uint256-) event. @@ -2207,9 +2454,9 @@ Total supply cap has been exceeded, introducing a risk of votes overflowing.
-## `ERC20Wrapper` +## `ERC20Wrapper` - + @@ -2226,7 +2473,7 @@ in conjunction with other modules. For example, combining this wrapping mechanis wrapping of an existing "basic" ERC-20 into a governance token. -Any mechanism in which the underlying token changes the [`IERC6909.balanceOf`](../interfaces#IERC6909-balanceOf-address-uint256-) of an account without an explicit transfer +Any mechanism in which the underlying token changes the [`ERC20.balanceOf`](#ERC20-balanceOf-address-) of an account without an explicit transfer may desynchronize this contract's supply and its underlying balance. Please exercise caution when wrapping tokens that may undercollateralize the wrapper (i.e. wrapper's total supply is higher than its underlying balance). See [`ERC20Wrapper._recover`](#ERC20Wrapper-_recover-address-) for recovering value accrued to the wrapper. @@ -2241,7 +2488,9 @@ for recovering value accrued to the wrapper. - [depositFor(account, value)](#ERC20Wrapper-depositFor-address-uint256-) - [withdrawTo(account, value)](#ERC20Wrapper-withdrawTo-address-uint256-) - [_recover(account)](#ERC20Wrapper-_recover-address-) -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [totalSupply()](#ERC20-totalSupply--) @@ -2257,21 +2506,21 @@ for recovering value accrued to the wrapper. - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -2279,16 +2528,17 @@ for recovering value accrued to the wrapper.

Errors

- [ERC20InvalidUnderlying(token)](#ERC20Wrapper-ERC20InvalidUnderlying-address-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -2412,9 +2662,9 @@ The underlying token couldn't be wrapped.
-## `ERC4626` +## `ERC4626` - + @@ -2428,12 +2678,12 @@ Implementation of the ERC-4626 "Tokenized Vault Standard" as defined in [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626). This extension allows the minting and burning of "shares" (represented using the ERC-20 inheritance) in exchange for -underlying "assets" through standardized [`IERC4626.deposit`](../interfaces#IERC4626-deposit-uint256-address-), [`IERC4626.mint`](../interfaces#IERC4626-mint-uint256-address-), [`IERC4626.redeem`](../interfaces#IERC4626-redeem-uint256-address-address-) and [`IERC777.burn`](../interfaces#IERC777-burn-uint256-bytes-) workflows. This contract extends +underlying "assets" through standardized [`ERC4626.deposit`](#ERC4626-deposit-uint256-address-), [`ERC4626.mint`](#ERC4626-mint-uint256-address-), [`ERC4626.redeem`](#ERC4626-redeem-uint256-address-address-) and [`ERC20Burnable.burn`](#ERC20Burnable-burn-uint256-) workflows. This contract extends the ERC-20 standard. Any additional extensions included along it would affect the "shares" token represented by this contract and not the "assets" token which is an independent contract. - -In empty (or nearly empty) ERC-4626 vaults, deposits are at high risk of being stolen through frontrunning +[CAUTION] +#### In empty (or nearly empty) ERC-4626 vaults, deposits are at high risk of being stolen through frontrunning with a "donation" to the vault that inflates the price of a share. This is variously known as a donation or inflation attack and is essentially a problem of slippage. Vault deployers can protect against this attack by making an initial deposit of a non-trivial amount of the asset, such that price manipulation becomes infeasible. Withdrawals may @@ -2457,25 +2707,23 @@ bigger losses. Developers willing to revert back to the pre-v4.9 behavior just n `_convertToShares` and `_convertToAssets` functions. To learn more, check out our [ERC-4626 guide](/contracts/5.x/erc4626). - - -When overriding this contract, some elements must be considered: +#### [NOTE] +#### When overriding this contract, some elements must be considered: * When overriding the behavior of the deposit or withdraw mechanisms, it is recommended to override the internal -functions. Overriding [`ERC4626._deposit`](#ERC4626-_deposit-address-address-uint256-uint256-) automatically affects both [`IERC4626.deposit`](../interfaces#IERC4626-deposit-uint256-address-) and [`IERC4626.mint`](../interfaces#IERC4626-mint-uint256-address-). Similarly, overriding [`ERC4626._withdraw`](#ERC4626-_withdraw-address-address-address-uint256-uint256-) -automatically affects both [`IERC4626.withdraw`](../interfaces#IERC4626-withdraw-uint256-address-address-) and [`IERC4626.redeem`](../interfaces#IERC4626-redeem-uint256-address-address-). Overall it is not recommended to override the public facing -functions since that could lead to inconsistent behaviors between the [`IERC4626.deposit`](../interfaces#IERC4626-deposit-uint256-address-) and [`IERC4626.mint`](../interfaces#IERC4626-mint-uint256-address-) or between [`IERC4626.withdraw`](../interfaces#IERC4626-withdraw-uint256-address-address-) and -[`IERC4626.redeem`](../interfaces#IERC4626-redeem-uint256-address-address-), which is documented to have lead to loss of funds. +functions. Overriding [`ERC4626._deposit`](#ERC4626-_deposit-address-address-uint256-uint256-) automatically affects both [`ERC4626.deposit`](#ERC4626-deposit-uint256-address-) and [`ERC4626.mint`](#ERC4626-mint-uint256-address-). Similarly, overriding [`ERC4626._withdraw`](#ERC4626-_withdraw-address-address-address-uint256-uint256-) +automatically affects both [`ERC4626.withdraw`](#ERC4626-withdraw-uint256-address-address-) and [`ERC4626.redeem`](#ERC4626-redeem-uint256-address-address-). Overall it is not recommended to override the public facing +functions since that could lead to inconsistent behaviors between the [`ERC4626.deposit`](#ERC4626-deposit-uint256-address-) and [`ERC4626.mint`](#ERC4626-mint-uint256-address-) or between [`ERC4626.withdraw`](#ERC4626-withdraw-uint256-address-address-) and +[`ERC4626.redeem`](#ERC4626-redeem-uint256-address-address-), which is documented to have led to loss of funds. * Overrides to the deposit or withdraw mechanism must be reflected in the preview functions as well. -* [`IERC4626.maxWithdraw`](../interfaces#IERC4626-maxWithdraw-address-) depends on [`IERC4626.maxRedeem`](../interfaces#IERC4626-maxRedeem-address-). Therefore, overriding [`IERC4626.maxRedeem`](../interfaces#IERC4626-maxRedeem-address-) only is enough. On the other hand, -overriding [`IERC4626.maxWithdraw`](../interfaces#IERC4626-maxWithdraw-address-) only would have no effect on [`IERC4626.maxRedeem`](../interfaces#IERC4626-maxRedeem-address-), and could create an inconsistency between the two +* [`ERC4626.maxWithdraw`](#ERC4626-maxWithdraw-address-) depends on [`ERC4626.maxRedeem`](#ERC4626-maxRedeem-address-). Therefore, overriding [`ERC4626.maxRedeem`](#ERC4626-maxRedeem-address-) only is enough. On the other hand, +overriding [`ERC4626.maxWithdraw`](#ERC4626-maxWithdraw-address-) only would have no effect on [`ERC4626.maxRedeem`](#ERC4626-maxRedeem-address-), and could create an inconsistency between the two functions. -* If [`IERC4626.previewRedeem`](../interfaces#IERC4626-previewRedeem-uint256-) is overridden to revert, [`IERC4626.maxWithdraw`](../interfaces#IERC4626-maxWithdraw-address-) must be overridden as necessary to ensure it +* If [`ERC4626.previewRedeem`](#ERC4626-previewRedeem-uint256-) is overridden to revert, [`ERC4626.maxWithdraw`](#ERC4626-maxWithdraw-address-) must be overridden as necessary to ensure it always return successfully. -

Functions

@@ -2502,9 +2750,12 @@ always return successfully. - [_convertToAssets(shares, rounding)](#ERC4626-_convertToAssets-uint256-enum-Math-Rounding-) - [_deposit(caller, receiver, assets, shares)](#ERC4626-_deposit-address-address-uint256-uint256-) - [_withdraw(caller, receiver, owner, assets, shares)](#ERC4626-_withdraw-address-address-address-uint256-uint256-) +- [_transferIn(from, assets)](#ERC4626-_transferIn-address-uint256-) +- [_transferOut(to, assets)](#ERC4626-_transferOut-address-uint256-) - [_decimalsOffset()](#ERC4626-_decimalsOffset--) -#### IERC4626 [!toc] -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [totalSupply()](#ERC20-totalSupply--) @@ -2520,24 +2771,28 @@ always return successfully. - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### IERC4626 [!toc] +
+IERC4626 + - [Deposit(sender, owner, assets, shares)](#IERC4626-Deposit-address-address-uint256-uint256-) - [Withdraw(sender, receiver, owner, assets, shares)](#IERC4626-Withdraw-address-address-address-uint256-uint256-) -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
+
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -2548,17 +2803,17 @@ always return successfully. - [ERC4626ExceededMaxMint(receiver, shares, max)](#ERC4626-ERC4626ExceededMaxMint-address-uint256-uint256-) - [ERC4626ExceededMaxWithdraw(owner, assets, max)](#ERC4626-ERC4626ExceededMaxWithdraw-address-uint256-uint256-) - [ERC4626ExceededMaxRedeem(owner, shares, max)](#ERC4626-ERC4626ExceededMaxRedeem-address-uint256-uint256-) -#### IERC4626 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -3085,6 +3340,40 @@ Withdraw/redeem common workflow. + + +
+
+

_transferIn(address from, uint256 assets)

+
+

internal

+# +
+
+
+ +Performs a transfer in of underlying assets. The default implementation uses `SafeERC20`. Used by [`ERC4626._deposit`](#ERC4626-_deposit-address-address-uint256-uint256-). + +
+
+ + + +
+
+

_transferOut(address to, uint256 assets)

+
+

internal

+# +
+
+
+ +Performs a transfer out of underlying assets. The default implementation uses `SafeERC20`. Used by [`ERC4626._withdraw`](#ERC4626-_withdraw-address-address-address-uint256-uint256-). + +
+
+
@@ -3146,7 +3435,7 @@ Attempted to mint more shares than the max amount for `receiver`.
-Attempted to withdraw more assets than the max amount for `receiver`. +Attempted to withdraw more assets than the max amount for `owner`.
@@ -3163,7 +3452,7 @@ Attempted to withdraw more assets than the max amount for `receiver`.
-Attempted to redeem more shares than the max amount for `receiver`. +Attempted to redeem more shares than the max amount for `owner`.
@@ -3172,9 +3461,9 @@ Attempted to redeem more shares than the max amount for `receiver`.
-## `IERC20Metadata` +## `IERC20Metadata` - + @@ -3192,22 +3481,30 @@ Interface for the optional metadata functions from the ERC-20 standard. - [name()](#IERC20Metadata-name--) - [symbol()](#IERC20Metadata-symbol--) - [decimals()](#IERC20Metadata-decimals--) -#### IERC20 [!toc] +
+IERC20 + - [totalSupply()](#IERC20-totalSupply--) - [balanceOf(account)](#IERC20-balanceOf-address-) - [transfer(to, value)](#IERC20-transfer-address-uint256-) - [allowance(owner, spender)](#IERC20-allowance-address-address-) - [approve(spender, value)](#IERC20-approve-address-uint256-) - [transferFrom(from, to, value)](#IERC20-transferFrom-address-address-uint256-) + +

Events

-#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +
@@ -3266,9 +3563,9 @@ Returns the decimals places of the token.
-## `IERC20Permit` +## `IERC20Permit` - + @@ -3285,7 +3582,7 @@ Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint presenting a message signed by the account. By not relying on [`IERC20.approve`](#IERC20-approve-address-uint256-), the token holder account doesn't need to send a transaction, and thus is not required to hold Ether at all. -==== Security Considerations +#### Security Considerations There are two important considerations concerning the use of `permit`. The first is that a valid permit signature expresses an allowance, and it should not be assumed to convey additional meaning. In particular, it should not be @@ -3342,7 +3639,7 @@ The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related ordering also applies here. -Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event. Requirements: @@ -3356,7 +3653,9 @@ For more information on the signature format, see the [relevant EIP section](https://eips.ethereum.org/EIPS/eip-2612#specification). -CAUTION: See Security Considerations above. + +See Security Considerations above. +
@@ -3394,7 +3693,7 @@ prevents a signature from being used multiple times.
-Returns the domain separator used in the encoding of the signature for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-), as defined by [`EIP712`](../utils/cryptography#EIP712). +Returns the domain separator used in the encoding of the signature for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-), as defined by [`EIP712`](/contracts/5.x/api/utils/cryptography#EIP712).
@@ -3403,9 +3702,9 @@ Returns the domain separator used in the encoding of the signature for [`ERC20Pe
-## `ERC20Bridgeable` +## `ERC20Bridgeable` - + @@ -3432,10 +3731,9 @@ ERC20 extension that implements the standard token interface according to - [crosschainMint(to, value)](#ERC20Bridgeable-crosschainMint-address-uint256-) - [crosschainBurn(from, value)](#ERC20Bridgeable-crosschainBurn-address-uint256-) - [_checkTokenBridge(caller)](#ERC20Bridgeable-_checkTokenBridge-address-) -#### IERC7802 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -3452,45 +3750,45 @@ ERC20 extension that implements the standard token interface according to - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) - [_spendAllowance(owner, spender, value)](#ERC20-_spendAllowance-address-address-uint256-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### IERC7802 [!toc] +
+IERC7802 + - [CrosschainMint(to, amount, sender)](#IERC7802-CrosschainMint-address-uint256-address-) - [CrosschainBurn(from, amount, sender)](#IERC7802-CrosschainBurn-address-uint256-address-) -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
+
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-#### IERC7802 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -3546,7 +3844,7 @@ This function call must use less than 30 000 gas.
-See [`IERC7802.crosschainMint`](../interfaces#IERC7802-crosschainMint-address-uint256-). Emits a [`IERC7802.CrosschainMint`](../interfaces#IERC7802-CrosschainMint-address-uint256-address-) event. +See [`IERC7802.crosschainMint`](/contracts/5.x/api/interfaces#IERC7802-crosschainMint-address-uint256-). Emits a [`IERC7802.CrosschainMint`](/contracts/5.x/api/interfaces#IERC7802-CrosschainMint-address-uint256-address-) event.
@@ -3563,7 +3861,7 @@ See [`IERC7802.crosschainMint`](../interfaces#IERC7802-crosschainMint-address-ui
-See [`IERC7802.crosschainBurn`](../interfaces#IERC7802-crosschainBurn-address-uint256-). Emits a [`IERC7802.CrosschainBurn`](../interfaces#IERC7802-CrosschainBurn-address-uint256-address-) event. +See [`IERC7802.crosschainBurn`](/contracts/5.x/api/interfaces#IERC7802-crosschainBurn-address-uint256-). Emits a [`IERC7802.CrosschainBurn`](/contracts/5.x/api/interfaces#IERC7802-CrosschainBurn-address-uint256-address-) event.
@@ -3583,7 +3881,7 @@ See [`IERC7802.crosschainBurn`](../interfaces#IERC7802-crosschainBurn-address-ui Checks if the caller is a trusted token bridge. MUST revert otherwise. Developers should implement this function using an access control mechanism that allows -customizing the list of allowed senders. Consider using [`AccessControl`](../access#AccessControl) or [`AccessManaged`](../access#AccessManaged). +customizing the list of allowed senders. Consider using [`AccessControl`](/contracts/5.x/api/access#AccessControl) or [`AccessManaged`](/contracts/5.x/api/access#AccessManaged). @@ -3592,9 +3890,9 @@ customizing the list of allowed senders. Consider using [`AccessControl`](../acc
-## `ERC20TemporaryApproval` +## `ERC20TemporaryApproval` - + @@ -3620,8 +3918,9 @@ _Available since v5.1._ - [temporaryApprove(spender, value)](#ERC20TemporaryApproval-temporaryApprove-address-uint256-) - [_temporaryApprove(owner, spender, value)](#ERC20TemporaryApproval-_temporaryApprove-address-address-uint256-) - [_spendAllowance(owner, spender, value)](#ERC20TemporaryApproval-_spendAllowance-address-address-uint256-) -#### IERC7674 [!toc] -#### ERC20 [!toc] +
+ERC20 + - [name()](#ERC20-name--) - [symbol()](#ERC20-symbol--) - [decimals()](#ERC20-decimals--) @@ -3636,39 +3935,38 @@ _Available since v5.1._ - [_burn(account, value)](#ERC20-_burn-address-uint256-) - [_approve(owner, spender, value)](#ERC20-_approve-address-address-uint256-) - [_approve(owner, spender, value, emitEvent)](#ERC20-_approve-address-address-uint256-bool-) -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +

Events

-#### IERC7674 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] -#### IERC20Metadata [!toc] -#### IERC20 [!toc] +
+IERC20 + - [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-) - [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-) + +

Errors

-#### IERC7674 [!toc] -#### ERC20 [!toc] -#### IERC20Errors [!toc] +
+IERC20Errors + - [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-) - [ERC20InvalidSender(sender)](#IERC20Errors-ERC20InvalidSender-address-) - [ERC20InvalidReceiver(receiver)](#IERC20Errors-ERC20InvalidReceiver-address-) - [ERC20InsufficientAllowance(spender, allowance, needed)](#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-) - [ERC20InvalidApprover(approver)](#IERC20Errors-ERC20InvalidApprover-address-) - [ERC20InvalidSpender(spender)](#IERC20Errors-ERC20InvalidSpender-address-) -#### IERC20Metadata [!toc] -#### IERC20 [!toc] + +
@@ -3684,7 +3982,7 @@ _Available since v5.1._
-[`IERC6909.allowance`](../interfaces#IERC6909-allowance-address-address-uint256-) override that includes the temporary allowance when looking up the current allowance. If +[`ERC20.allowance`](#ERC20-allowance-address-address-) override that includes the temporary allowance when looking up the current allowance. If adding up the persistent and the temporary allowances result in an overflow, type(uint256).max is returned.
@@ -3719,7 +4017,7 @@ Internal getter for the current temporary allowance that `spender` has over `own
-Alternative to [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) that sets a `value` amount of tokens as the temporary allowance of `spender` over +Alternative to [`ERC20.approve`](#ERC20-approve-address-uint256-) that sets a `value` amount of tokens as the temporary allowance of `spender` over the caller's tokens. Returns a boolean value indicating whether the operation succeeded. @@ -3727,7 +4025,7 @@ Returns a boolean value indicating whether the operation succeeded. Requirements: - `spender` cannot be the zero address. -Does NOT emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Does NOT emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
@@ -3753,7 +4051,7 @@ Requirements: - `owner` cannot be the zero address. - `spender` cannot be the zero address. -Does NOT emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Does NOT emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event. @@ -3784,9 +4082,9 @@ is enough to cover the spending.
-## `ERC1363Utils` +## `ERC1363Utils` - + @@ -3828,13 +4126,13 @@ See [ERC-1363](https://eips.ethereum.org/EIPS/eip-1363).
-Performs a call to [`IERC1363Receiver.onTransferReceived`](../interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on a target address. +Performs a call to [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on a target address. Requirements: - The target has code (i.e. is a contract). -- The target `to` must implement the [`IERC1363Receiver`](../interfaces#IERC1363Receiver) interface. -- The target must return the [`IERC1363Receiver.onTransferReceived`](../interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) selector to accept the transfer. +- The target `to` must implement the [`IERC1363Receiver`](/contracts/5.x/api/interfaces#IERC1363Receiver) interface. +- The target must return the [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) selector to accept the transfer.
@@ -3851,13 +4149,13 @@ Requirements:
-Performs a call to [`IERC1363Spender.onApprovalReceived`](../interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) on a target address. +Performs a call to [`IERC1363Spender.onApprovalReceived`](/contracts/5.x/api/interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) on a target address. Requirements: - The target has code (i.e. is a contract). -- The target `spender` must implement the [`IERC1363Spender`](../interfaces#IERC1363Spender) interface. -- The target must return the [`IERC1363Spender.onApprovalReceived`](../interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) selector to accept the approval. +- The target `spender` must implement the [`IERC1363Spender`](/contracts/5.x/api/interfaces#IERC1363Spender) interface. +- The target must return the [`IERC1363Spender.onApprovalReceived`](/contracts/5.x/api/interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) selector to accept the approval.
@@ -3900,9 +4198,9 @@ Indicates a failure with the token `spender`. Used in approvals.
-## `SafeERC20` +## `SafeERC20` - + @@ -4008,7 +4306,7 @@ Variant of [`SafeERC20.safeTransfer`](#SafeERC20-safeTransfer-contract-IERC20-ad
-Variant of [`ERC1155.safeTransferFrom`](/contracts/5.x/api/token/ERC1155#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) that returns a bool instead of reverting if the operation is not successful. +Variant of [`SafeERC20.safeTransferFrom`](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-) that returns a bool instead of reverting if the operation is not successful.
@@ -4190,3 +4488,4 @@ Indicates a failed `decreaseAllowance` request. + diff --git a/content/contracts/5.x/api/token/ERC6909.mdx b/content/contracts/5.x/api/token/ERC6909.mdx index 5430787f..cb2ebfa5 100644 --- a/content/contracts/5.x/api/token/ERC6909.mdx +++ b/content/contracts/5.x/api/token/ERC6909.mdx @@ -7,10 +7,10 @@ This set of interfaces and contracts are all related to the [ERC-6909 Minimal Mu The ERC consists of four interfaces which fulfill different roles--the interfaces are as follows: -1. [`IERC6909`](../interfaces#IERC6909): Base interface for a vanilla ERC6909 token. -2. [`IERC6909ContentURI`](../interfaces#IERC6909ContentURI): Extends the base interface and adds content URI (contract and token level) functionality. -3. [`IERC6909Metadata`](../interfaces#IERC6909Metadata): Extends the base interface and adds metadata functionality, which exposes a name, symbol, and decimals for each token id. -4. [`IERC6909TokenSupply`](../interfaces#IERC6909TokenSupply): Extends the base interface and adds total supply functionality for each token id. +1. [`IERC6909`](/contracts/5.x/api/interfaces#IERC6909): Base interface for a vanilla ERC6909 token. +2. [`IERC6909ContentURI`](/contracts/5.x/api/interfaces#IERC6909ContentURI): Extends the base interface and adds content URI (contract and token level) functionality. +3. [`IERC6909Metadata`](/contracts/5.x/api/interfaces#IERC6909Metadata): Extends the base interface and adds metadata functionality, which exposes a name, symbol, and decimals for each token id. +4. [`IERC6909TokenSupply`](/contracts/5.x/api/interfaces#IERC6909TokenSupply): Extends the base interface and adds total supply functionality for each token id. Implementations are provided for each of the 4 interfaces defined in the ERC. @@ -30,9 +30,9 @@ Implementations are provided for each of the 4 interfaces defined in the ERC.
-## `ERC6909` +## `ERC6909` - + @@ -63,21 +63,20 @@ See https://eips.ethereum.org/EIPS/eip-6909 - [_approve(owner, spender, id, amount)](#ERC6909-_approve-address-address-uint256-uint256-) - [_setOperator(owner, spender, approved)](#ERC6909-_setOperator-address-address-bool-) - [_spendAllowance(owner, spender, id, amount)](#ERC6909-_spendAllowance-address-address-uint256-uint256-) -#### IERC6909 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc]

Events

-#### IERC6909 [!toc] +
+IERC6909 + - [Approval(owner, spender, id, amount)](#IERC6909-Approval-address-address-uint256-uint256-) - [OperatorSet(owner, spender, approved)](#IERC6909-OperatorSet-address-address-bool-) - [Transfer(caller, sender, receiver, id, amount)](#IERC6909-Transfer-address-address-address-uint256-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -90,9 +89,6 @@ See https://eips.ethereum.org/EIPS/eip-6909 - [ERC6909InvalidReceiver(receiver)](#ERC6909-ERC6909InvalidReceiver-address-) - [ERC6909InvalidSender(sender)](#ERC6909-ERC6909InvalidSender-address-) - [ERC6909InvalidSpender(spender)](#ERC6909-ERC6909InvalidSpender-address-) -#### IERC6909 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] @@ -265,10 +261,10 @@ Must return true. Creates `amount` of token `id` and assigns them to `account`, by transferring it from address(0). Relies on the `_update` mechanism. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event with `from` set to the zero address. +Emits a [`IERC6909.Transfer`](/contracts/5.x/api/interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event with `from` set to the zero address. -This function is not virtual, [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) should be overridden instead. +This function is not virtual, [`ERC6909._update`](#ERC6909-_update-address-address-uint256-uint256-) should be overridden instead. @@ -290,10 +286,10 @@ Moves `amount` of token `id` from `from` to `to` without checking for approvals. that neither the sender nor the receiver are address(0), which means it cannot mint or burn tokens. Relies on the `_update` mechanism. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC6909.Transfer`](/contracts/5.x/api/interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. -This function is not virtual, [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) should be overridden instead. +This function is not virtual, [`ERC6909._update`](#ERC6909-_update-address-address-uint256-uint256-) should be overridden instead. @@ -314,10 +310,10 @@ This function is not virtual, [`ERC1155._update`](/contracts/5.x/api/token/ERC11 Destroys a `amount` of token `id` from `account`. Relies on the `_update` mechanism. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event with `to` set to the zero address. +Emits a [`IERC6909.Transfer`](/contracts/5.x/api/interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event with `to` set to the zero address. -This function is not virtual, [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) should be overridden instead +This function is not virtual, [`ERC6909._update`](#ERC6909-_update-address-address-uint256-uint256-) should be overridden instead @@ -339,7 +335,7 @@ Transfers `amount` of token `id` from `from` to `to`, or alternatively mints (or (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding this function. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC6909.Transfer`](/contracts/5.x/api/interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. @@ -361,7 +357,7 @@ Sets `amount` as the allowance of `spender` over the `owner`'s `id` tokens. This internal function is equivalent to `approve`, and can be used to e.g. set automatic allowances for certain subsystems, etc. -Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Emits an [`IERC6909.Approval`](/contracts/5.x/api/interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. Requirements: @@ -388,7 +384,7 @@ Approve `spender` to operate on all of `owner`'s tokens This internal function is equivalent to `setOperator`, and can be used to e.g. set automatic allowances for certain subsystems, etc. -Emits an [`IERC6909.OperatorSet`](../interfaces#IERC6909-OperatorSet-address-address-bool-) event. +Emits an [`IERC6909.OperatorSet`](/contracts/5.x/api/interfaces#IERC6909-OperatorSet-address-address-bool-) event. Requirements: @@ -415,7 +411,7 @@ Updates `owner`'s allowance for `spender` based on spent `amount`. Does not update the allowance value in case of infinite allowance. Revert if not enough allowance is available. -Does not emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Does not emit an [`IERC6909.Approval`](/contracts/5.x/api/interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. @@ -514,9 +510,9 @@ Does not emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-a
-## `ERC6909ContentURI` +## `ERC6909ContentURI` - + @@ -531,13 +527,14 @@ Implementation of the Content URI extension defined in ERC6909.

Functions

+- [supportsInterface(interfaceId)](#ERC6909ContentURI-supportsInterface-bytes4-) - [contractURI()](#ERC6909ContentURI-contractURI--) - [tokenURI(id)](#ERC6909ContentURI-tokenURI-uint256-) - [_setContractURI(newContractURI)](#ERC6909ContentURI-_setContractURI-string-) - [_setTokenURI(id, newTokenURI)](#ERC6909ContentURI-_setTokenURI-uint256-string-) -#### IERC6909ContentURI [!toc] -#### ERC6909 [!toc] -- [supportsInterface(interfaceId)](#ERC6909-supportsInterface-bytes4-) +
+ERC6909 + - [balanceOf(owner, id)](#ERC6909-balanceOf-address-uint256-) - [allowance(owner, spender, id)](#ERC6909-allowance-address-address-uint256-) - [isOperator(owner, spender)](#ERC6909-isOperator-address-address-) @@ -552,9 +549,8 @@ Implementation of the Content URI extension defined in ERC6909. - [_approve(owner, spender, id, amount)](#ERC6909-_approve-address-address-uint256-uint256-) - [_setOperator(owner, spender, approved)](#ERC6909-_setOperator-address-address-bool-) - [_spendAllowance(owner, spender, id, amount)](#ERC6909-_spendAllowance-address-address-uint256-uint256-) -#### IERC6909 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -563,31 +559,53 @@ Implementation of the Content URI extension defined in ERC6909.
- [ContractURIUpdated()](#ERC6909ContentURI-ContractURIUpdated--) - [URI(value, id)](#ERC6909ContentURI-URI-string-uint256-) -#### IERC6909ContentURI [!toc] -#### ERC6909 [!toc] -#### IERC6909 [!toc] +
+IERC6909 + - [Approval(owner, spender, id, amount)](#IERC6909-Approval-address-address-uint256-uint256-) - [OperatorSet(owner, spender, approved)](#IERC6909-OperatorSet-address-address-bool-) - [Transfer(caller, sender, receiver, id, amount)](#IERC6909-Transfer-address-address-address-uint256-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### IERC6909ContentURI [!toc] -#### ERC6909 [!toc] +
+ERC6909 + - [ERC6909InsufficientBalance(sender, balance, needed, id)](#ERC6909-ERC6909InsufficientBalance-address-uint256-uint256-uint256-) - [ERC6909InsufficientAllowance(spender, allowance, needed, id)](#ERC6909-ERC6909InsufficientAllowance-address-uint256-uint256-uint256-) - [ERC6909InvalidApprover(approver)](#ERC6909-ERC6909InvalidApprover-address-) - [ERC6909InvalidReceiver(receiver)](#ERC6909-ERC6909InvalidReceiver-address-) - [ERC6909InvalidSender(sender)](#ERC6909-ERC6909InvalidSender-address-) - [ERC6909InvalidSpender(spender)](#ERC6909-ERC6909InvalidSpender-address-) -#### IERC6909 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
+
+
+ + + +
+
+

supportsInterface(bytes4 interfaceId) โ†’ bool

+
+

public

+# +
+
+
+ +Returns true if this contract implements the interface defined by +`interfaceId`. See the corresponding +[ERC section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified) +to learn more about how these ids are created. + +This function call must use less than 30 000 gas. +
@@ -637,7 +655,7 @@ Returns the URI for the token of type `id`.
-Sets the [`IERC6909ContentURI.contractURI`](../interfaces#IERC6909ContentURI-contractURI--) for the contract. +Sets the [`ERC6909ContentURI.contractURI`](#ERC6909ContentURI-contractURI--) for the contract. Emits a [`ERC6909ContentURI.ContractURIUpdated`](#ERC6909ContentURI-ContractURIUpdated--) event. @@ -656,9 +674,9 @@ Emits a [`ERC6909ContentURI.ContractURIUpdated`](#ERC6909ContentURI-ContractURIU
-Sets the [`IERC6909ContentURI.tokenURI`](../interfaces#IERC6909ContentURI-tokenURI-uint256-) for a given token of type `id`. +Sets the [`ERC6909ContentURI.tokenURI`](#ERC6909ContentURI-tokenURI-uint256-) for a given token of type `id`. -Emits a [`IERC1155.URI`](/contracts/5.x/api/token/ERC1155#IERC1155-URI-string-uint256-) event. +Emits a [`ERC6909ContentURI.URI`](#ERC6909ContentURI-URI-string-uint256-) event.
@@ -702,9 +720,9 @@ See [`IERC1155.URI`](/contracts/5.x/api/token/ERC1155#IERC1155-URI-string-uint25
-## `ERC6909Metadata` +## `ERC6909Metadata` - + @@ -722,12 +740,13 @@ Implementation of the Metadata extension defined in ERC6909. Exposes the name, s - [name(id)](#ERC6909Metadata-name-uint256-) - [symbol(id)](#ERC6909Metadata-symbol-uint256-) - [decimals(id)](#ERC6909Metadata-decimals-uint256-) +- [supportsInterface(interfaceId)](#ERC6909Metadata-supportsInterface-bytes4-) - [_setName(id, newName)](#ERC6909Metadata-_setName-uint256-string-) - [_setSymbol(id, newSymbol)](#ERC6909Metadata-_setSymbol-uint256-string-) - [_setDecimals(id, newDecimals)](#ERC6909Metadata-_setDecimals-uint256-uint8-) -#### IERC6909Metadata [!toc] -#### ERC6909 [!toc] -- [supportsInterface(interfaceId)](#ERC6909-supportsInterface-bytes4-) +
+ERC6909 + - [balanceOf(owner, id)](#ERC6909-balanceOf-address-uint256-) - [allowance(owner, spender, id)](#ERC6909-allowance-address-address-uint256-) - [isOperator(owner, spender)](#ERC6909-isOperator-address-address-) @@ -742,9 +761,8 @@ Implementation of the Metadata extension defined in ERC6909. Exposes the name, s - [_approve(owner, spender, id, amount)](#ERC6909-_approve-address-address-uint256-uint256-) - [_setOperator(owner, spender, approved)](#ERC6909-_setOperator-address-address-bool-) - [_spendAllowance(owner, spender, id, amount)](#ERC6909-_spendAllowance-address-address-uint256-uint256-) -#### IERC6909 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -754,31 +772,31 @@ Implementation of the Metadata extension defined in ERC6909. Exposes the name, s - [ERC6909NameUpdated(id, newName)](#ERC6909Metadata-ERC6909NameUpdated-uint256-string-) - [ERC6909SymbolUpdated(id, newSymbol)](#ERC6909Metadata-ERC6909SymbolUpdated-uint256-string-) - [ERC6909DecimalsUpdated(id, newDecimals)](#ERC6909Metadata-ERC6909DecimalsUpdated-uint256-uint8-) -#### IERC6909Metadata [!toc] -#### ERC6909 [!toc] -#### IERC6909 [!toc] +
+IERC6909 + - [Approval(owner, spender, id, amount)](#IERC6909-Approval-address-address-uint256-uint256-) - [OperatorSet(owner, spender, approved)](#IERC6909-OperatorSet-address-address-bool-) - [Transfer(caller, sender, receiver, id, amount)](#IERC6909-Transfer-address-address-address-uint256-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### IERC6909Metadata [!toc] -#### ERC6909 [!toc] +
+ERC6909 + - [ERC6909InsufficientBalance(sender, balance, needed, id)](#ERC6909-ERC6909InsufficientBalance-address-uint256-uint256-uint256-) - [ERC6909InsufficientAllowance(spender, allowance, needed, id)](#ERC6909-ERC6909InsufficientAllowance-address-uint256-uint256-uint256-) - [ERC6909InvalidApprover(approver)](#ERC6909-ERC6909InvalidApprover-address-) - [ERC6909InvalidReceiver(receiver)](#ERC6909-ERC6909InvalidReceiver-address-) - [ERC6909InvalidSender(sender)](#ERC6909-ERC6909InvalidSender-address-) - [ERC6909InvalidSpender(spender)](#ERC6909-ERC6909InvalidSpender-address-) -#### IERC6909 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -833,6 +851,28 @@ Returns the number of decimals for the token of type `id`. + + +
+
+

supportsInterface(bytes4 interfaceId) โ†’ bool

+
+

public

+# +
+
+
+ +Returns true if this contract implements the interface defined by +`interfaceId`. See the corresponding +[ERC section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified) +to learn more about how these ids are created. + +This function call must use less than 30 000 gas. + +
+
+
@@ -946,9 +986,9 @@ The decimals value for token of type `id` was updated to `newDecimals`.
-## `ERC6909TokenSupply` +## `ERC6909TokenSupply` - + @@ -965,10 +1005,11 @@ Tracks the total supply of each token id individually.

Functions

- [totalSupply(id)](#ERC6909TokenSupply-totalSupply-uint256-) +- [supportsInterface(interfaceId)](#ERC6909TokenSupply-supportsInterface-bytes4-) - [_update(from, to, id, amount)](#ERC6909TokenSupply-_update-address-address-uint256-uint256-) -#### IERC6909TokenSupply [!toc] -#### ERC6909 [!toc] -- [supportsInterface(interfaceId)](#ERC6909-supportsInterface-bytes4-) +
+ERC6909 + - [balanceOf(owner, id)](#ERC6909-balanceOf-address-uint256-) - [allowance(owner, spender, id)](#ERC6909-allowance-address-address-uint256-) - [isOperator(owner, spender)](#ERC6909-isOperator-address-address-) @@ -982,40 +1023,39 @@ Tracks the total supply of each token id individually. - [_approve(owner, spender, id, amount)](#ERC6909-_approve-address-address-uint256-uint256-) - [_setOperator(owner, spender, approved)](#ERC6909-_setOperator-address-address-bool-) - [_spendAllowance(owner, spender, id, amount)](#ERC6909-_spendAllowance-address-address-uint256-uint256-) -#### IERC6909 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### IERC6909TokenSupply [!toc] -#### ERC6909 [!toc] -#### IERC6909 [!toc] +
+IERC6909 + - [Approval(owner, spender, id, amount)](#IERC6909-Approval-address-address-uint256-uint256-) - [OperatorSet(owner, spender, approved)](#IERC6909-OperatorSet-address-address-bool-) - [Transfer(caller, sender, receiver, id, amount)](#IERC6909-Transfer-address-address-address-uint256-uint256-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### IERC6909TokenSupply [!toc] -#### ERC6909 [!toc] +
+ERC6909 + - [ERC6909InsufficientBalance(sender, balance, needed, id)](#ERC6909-ERC6909InsufficientBalance-address-uint256-uint256-uint256-) - [ERC6909InsufficientAllowance(spender, allowance, needed, id)](#ERC6909-ERC6909InsufficientAllowance-address-uint256-uint256-uint256-) - [ERC6909InvalidApprover(approver)](#ERC6909-ERC6909InvalidApprover-address-) - [ERC6909InvalidReceiver(receiver)](#ERC6909-ERC6909InvalidReceiver-address-) - [ERC6909InvalidSender(sender)](#ERC6909-ERC6909InvalidSender-address-) - [ERC6909InvalidSpender(spender)](#ERC6909-ERC6909InvalidSpender-address-) -#### IERC6909 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -1036,6 +1076,28 @@ Returns the total supply of the token of type `id`.
+ + +
+
+

supportsInterface(bytes4 interfaceId) โ†’ bool

+
+

public

+# +
+
+
+ +Returns true if this contract implements the interface defined by +`interfaceId`. See the corresponding +[ERC section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified) +to learn more about how these ids are created. + +This function call must use less than 30 000 gas. + +
+
+
@@ -1052,3 +1114,4 @@ Override the `_update` function to update the total supply of each token id as n
+ diff --git a/content/contracts/5.x/api/token/ERC721.mdx b/content/contracts/5.x/api/token/ERC721.mdx index 72f8829e..9d62fa92 100644 --- a/content/contracts/5.x/api/token/ERC721.mdx +++ b/content/contracts/5.x/api/token/ERC721.mdx @@ -24,12 +24,13 @@ OpenZeppelin Contracts provides implementations of all four interfaces: Additionally there are a few of other extensions: +* [`ERC721Burnable`](#ERC721Burnable): A way for token holders to burn their own tokens. * [`ERC721Consecutive`](#ERC721Consecutive): An implementation of [ERC-2309](https://eips.ethereum.org/EIPS/eip-2309) for minting batches of tokens during construction, in accordance with ERC-721. +* [`ERC721Crosschain`](#ERC721Crosschain): Embedded [`BridgeNonFungible`](/contracts/5.x/api/crosschain#BridgeNonFungible) bridge, making the token crosschain through the use of ERC-7786 gateways. +* [`ERC721Pausable`](#ERC721Pausable): A primitive to pause contract operation. +* [`ERC721Royalty`](#ERC721Royalty): A way to signal royalty information following ERC-2981. * [`ERC721URIStorage`](#ERC721URIStorage): A more flexible but more expensive way of storing metadata. * [`ERC721Votes`](#ERC721Votes): Support for voting and vote delegation. -* [`ERC721Royalty`](#ERC721Royalty): A way to signal royalty information following ERC-2981. -* [`ERC721Pausable`](#ERC721Pausable): A primitive to pause contract operation. -* [`ERC721Burnable`](#ERC721Burnable): A way for token holders to burn their own tokens. * [`ERC721Wrapper`](#ERC721Wrapper): Wrapper to create an ERC-721 backed by another ERC-721, with deposit and withdraw methods. Useful in conjunction with [`ERC721Votes`](#ERC721Votes). @@ -52,18 +53,20 @@ This core set of contracts is designed to be unopinionated, allowing developers ## Extensions -[`ERC721Pausable`](#ERC721Pausable) - [`ERC721Burnable`](#ERC721Burnable) [`ERC721Consecutive`](#ERC721Consecutive) -[`ERC721URIStorage`](#ERC721URIStorage) +[`ERC721Crosschain`](#ERC721Crosschain) -[`ERC721Votes`](#ERC721Votes) +[`ERC721Pausable`](#ERC721Pausable) [`ERC721Royalty`](#ERC721Royalty) +[`ERC721URIStorage`](#ERC721URIStorage) + +[`ERC721Votes`](#ERC721Votes) + [`ERC721Wrapper`](#ERC721Wrapper) ## Utilities @@ -76,9 +79,9 @@ This core set of contracts is designed to be unopinionated, allowing developers
-## `ERC721` +## `ERC721` - + @@ -127,32 +130,29 @@ the Metadata extension, but not including the Enumerable extension, which is ava - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc]

Events

-#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### IERC721Errors [!toc] +
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -161,10 +161,8 @@ the Metadata extension, but not including the Enumerable extension, which is ava - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -308,7 +306,7 @@ Returns the Uniform Resource Identifier (URI) for `tokenId` token.
-Base URI for computing [`IERC6909ContentURI.tokenURI`](../interfaces#IERC6909ContentURI-tokenURI-uint256-). If set, the resulting URI for each +Base URI for computing [`ERC721.tokenURI`](#ERC721-tokenURI-uint256-). If set, the resulting URI for each token will be the concatenation of the `baseURI` and the `tokenId`. Empty by default, can be overridden in child contracts. @@ -337,7 +335,7 @@ Requirements: - The caller must own the token or be an approved operator. - `tokenId` must exist. -Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Emits an [`IERC721.Approval`](#IERC721-Approval-address-address-uint256-) event.
@@ -376,13 +374,13 @@ Requirements:
Approve or remove `operator` as an operator for the caller. -Operators can call [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-) or [`ERC1155.safeTransferFrom`](/contracts/5.x/api/token/ERC1155#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) for any token owned by the caller. +Operators can call [`ERC721.transferFrom`](#ERC721-transferFrom-address-address-uint256-) or [`ERC721.safeTransferFrom`](#ERC721-safeTransferFrom-address-address-uint256-bytes-) for any token owned by the caller. Requirements: - The `operator` cannot be the address zero. -Emits an [`IERC1155.ApprovalForAll`](/contracts/5.x/api/token/ERC1155#IERC1155-ApprovalForAll-address-address-bool-) event. +Emits an [`IERC721.ApprovalForAll`](#IERC721-ApprovalForAll-address-address-bool-) event.
@@ -401,7 +399,7 @@ Emits an [`IERC1155.ApprovalForAll`](/contracts/5.x/api/token/ERC1155#IERC1155-A Returns if the `operator` is allowed to manage all of the assets of `owner`. -See [`ERC1155.setApprovalForAll`](/contracts/5.x/api/token/ERC1155#ERC1155-setApprovalForAll-address-bool-) +See [`ERC721.setApprovalForAll`](#ERC721-setApprovalForAll-address-bool-) @@ -422,7 +420,7 @@ Transfers `tokenId` token from `from` to `to`. Note that the caller is responsible to confirm that the recipient is capable of receiving ERC-721 -or else they may be permanently lost. Usage of [`ERC1155.safeTransferFrom`](/contracts/5.x/api/token/ERC1155#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) prevents loss, though the caller must +or else they may be permanently lost. Usage of [`ERC721.safeTransferFrom`](#ERC721-safeTransferFrom-address-address-uint256-bytes-) prevents loss, though the caller must understand this adds an external call which potentially creates a reentrancy vulnerability. @@ -431,9 +429,9 @@ Requirements: - `from` cannot be the zero address. - `to` cannot be the zero address. - `tokenId` token must be owned by `from`. -- If the caller is not `from`, it must be approved to move this token by either [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) or [`ERC1155.setApprovalForAll`](/contracts/5.x/api/token/ERC1155#ERC1155-setApprovalForAll-address-bool-). +- If the caller is not `from`, it must be approved to move this token by either [`ERC721.approve`](#ERC721-approve-address-uint256-) or [`ERC721.setApprovalForAll`](#ERC721-setApprovalForAll-address-bool-). -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -458,12 +456,12 @@ Requirements: - `from` cannot be the zero address. - `to` cannot be the zero address. - `tokenId` token must exist and be owned by `from`. -- If the caller is not `from`, it must have been allowed to move this token by either [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) or - [`ERC1155.setApprovalForAll`](/contracts/5.x/api/token/ERC1155#ERC1155-setApprovalForAll-address-bool-). +- If the caller is not `from`, it must have been allowed to move this token by either [`ERC721.approve`](#ERC721-approve-address-uint256-) or + [`ERC721.setApprovalForAll`](#ERC721-setApprovalForAll-address-bool-). - If `to` refers to a smart contract, it must implement [`IERC721Receiver.onERC721Received`](#IERC721Receiver-onERC721Received-address-address-uint256-bytes-), which is called upon a safe transfer. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -487,11 +485,11 @@ Requirements: - `from` cannot be the zero address. - `to` cannot be the zero address. - `tokenId` token must exist and be owned by `from`. -- If the caller is not `from`, it must be approved to move this token by either [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) or [`ERC1155.setApprovalForAll`](/contracts/5.x/api/token/ERC1155#ERC1155-setApprovalForAll-address-bool-). +- If the caller is not `from`, it must be approved to move this token by either [`ERC721.approve`](#ERC721-approve-address-uint256-) or [`ERC721.setApprovalForAll`](#ERC721-setApprovalForAll-address-bool-). - If `to` refers to a smart contract, it must implement [`IERC721Receiver.onERC721Received`](#IERC721Receiver-onERC721Received-address-address-uint256-bytes-), which is called upon a safe transfer. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -631,7 +629,7 @@ Transfers `tokenId` from its current owner to `to`, or alternatively mints (or b The `auth` argument is optional. If the value passed is non 0, then this function will check that `auth` is either the owner of the token, or approved to operate on the token (by the owner). -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. If overriding this function in a way that tracks balances, see also [`ERC721._increaseBalance`](#ERC721-_increaseBalance-address-uint128-). @@ -663,7 +661,7 @@ Requirements: - `tokenId` must not exist. - `to` cannot be the zero address. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -687,7 +685,7 @@ Requirements: - `tokenId` must not exist. - If `to` refers to a smart contract, it must implement [`IERC721Receiver.onERC721Received`](#IERC721Receiver-onERC721Received-address-address-uint256-bytes-), which is called upon a safe transfer. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -730,7 +728,7 @@ Requirements: - `tokenId` must exist. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -748,14 +746,14 @@ Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-ad
Transfers `tokenId` from `from` to `to`. - As opposed to [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-), this imposes no restrictions on msg.sender. + As opposed to [`ERC721.transferFrom`](#ERC721-transferFrom-address-address-uint256-), this imposes no restrictions on msg.sender. Requirements: - `to` cannot be the zero address. - `tokenId` token must be owned by `from`. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event.
@@ -777,7 +775,7 @@ are aware of the ERC-721 standard to prevent tokens from being forever locked. `data` is additional data, it has no specified format and it is sent in call to `to`. -This internal function is like [`ERC1155.safeTransferFrom`](/contracts/5.x/api/token/ERC1155#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) in the sense that it invokes +This internal function is like [`ERC721.safeTransferFrom`](#ERC721-safeTransferFrom-address-address-uint256-bytes-) in the sense that it invokes [`IERC721Receiver.onERC721Received`](#IERC721Receiver-onERC721Received-address-address-uint256-bytes-) on the receiver, and can be used to e.g. implement alternative mechanisms to perform token transfer, such as signature-based. @@ -788,7 +786,7 @@ Requirements: - `from` cannot be the zero address. - If `to` refers to a smart contract, it must implement [`IERC721Receiver.onERC721Received`](#IERC721Receiver-onERC721Received-address-address-uint256-bytes-), which is called upon a safe transfer. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -828,7 +826,7 @@ Approve `to` to operate on `tokenId` The `auth` argument is optional. If the value passed is non 0, then this function will check that `auth` is either the owner of the token, or approved to operate on all tokens held by this owner. -Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Emits an [`IERC721.Approval`](#IERC721-Approval-address-address-uint256-) event. Overrides to this logic should be done to the variant with an additional `bool emitEvent` argument. @@ -847,7 +845,7 @@ Overrides to this logic should be done to the variant with an additional `bool e
-Variant of `_approve` with an optional flag to enable or disable the [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. The event is not +Variant of `_approve` with an optional flag to enable or disable the [`IERC721.Approval`](#IERC721-Approval-address-address-uint256-) event. The event is not emitted in the context of transfers.
@@ -870,7 +868,7 @@ Approve `operator` to operate on all of `owner` tokens Requirements: - operator can't be the address zero. -Emits an [`IERC1155.ApprovalForAll`](/contracts/5.x/api/token/ERC1155#IERC1155-ApprovalForAll-address-address-bool-) event. +Emits an [`IERC721.ApprovalForAll`](#IERC721-ApprovalForAll-address-address-bool-) event. @@ -899,9 +897,9 @@ Overrides to ownership logic should be done to [`ERC721._ownerOf`](#ERC721-_owne
-## `IERC721` +## `IERC721` - + @@ -925,8 +923,12 @@ Required interface of an ERC-721 compliant contract. - [setApprovalForAll(operator, approved)](#IERC721-setApprovalForAll-address-bool-) - [getApproved(tokenId)](#IERC721-getApproved-uint256-) - [isApprovedForAll(owner, operator)](#IERC721-isApprovedForAll-address-address-) -#### IERC165 [!toc] +
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +
@@ -936,7 +938,6 @@ Required interface of an ERC-721 compliant contract. - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### IERC165 [!toc] @@ -997,11 +998,11 @@ Requirements: - `from` cannot be the zero address. - `to` cannot be the zero address. - `tokenId` token must exist and be owned by `from`. -- If the caller is not `from`, it must be approved to move this token by either [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) or [`ERC1155.setApprovalForAll`](/contracts/5.x/api/token/ERC1155#ERC1155-setApprovalForAll-address-bool-). +- If the caller is not `from`, it must be approved to move this token by either [`ERC721.approve`](#ERC721-approve-address-uint256-) or [`ERC721.setApprovalForAll`](#ERC721-setApprovalForAll-address-bool-). - If `to` refers to a smart contract, it must implement [`IERC721Receiver.onERC721Received`](#IERC721Receiver-onERC721Received-address-address-uint256-bytes-), which is called upon a safe transfer. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -1026,12 +1027,12 @@ Requirements: - `from` cannot be the zero address. - `to` cannot be the zero address. - `tokenId` token must exist and be owned by `from`. -- If the caller is not `from`, it must have been allowed to move this token by either [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) or - [`ERC1155.setApprovalForAll`](/contracts/5.x/api/token/ERC1155#ERC1155-setApprovalForAll-address-bool-). +- If the caller is not `from`, it must have been allowed to move this token by either [`ERC721.approve`](#ERC721-approve-address-uint256-) or + [`ERC721.setApprovalForAll`](#ERC721-setApprovalForAll-address-bool-). - If `to` refers to a smart contract, it must implement [`IERC721Receiver.onERC721Received`](#IERC721Receiver-onERC721Received-address-address-uint256-bytes-), which is called upon a safe transfer. -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -1052,7 +1053,7 @@ Transfers `tokenId` token from `from` to `to`. Note that the caller is responsible to confirm that the recipient is capable of receiving ERC-721 -or else they may be permanently lost. Usage of [`ERC1155.safeTransferFrom`](/contracts/5.x/api/token/ERC1155#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) prevents loss, though the caller must +or else they may be permanently lost. Usage of [`ERC721.safeTransferFrom`](#ERC721-safeTransferFrom-address-address-uint256-bytes-) prevents loss, though the caller must understand this adds an external call which potentially creates a reentrancy vulnerability. @@ -1061,9 +1062,9 @@ Requirements: - `from` cannot be the zero address. - `to` cannot be the zero address. - `tokenId` token must be owned by `from`. -- If the caller is not `from`, it must be approved to move this token by either [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) or [`ERC1155.setApprovalForAll`](/contracts/5.x/api/token/ERC1155#ERC1155-setApprovalForAll-address-bool-). +- If the caller is not `from`, it must be approved to move this token by either [`ERC721.approve`](#ERC721-approve-address-uint256-) or [`ERC721.setApprovalForAll`](#ERC721-setApprovalForAll-address-bool-). -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. @@ -1090,7 +1091,7 @@ Requirements: - The caller must own the token or be an approved operator. - `tokenId` must exist. -Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event. +Emits an [`IERC721.Approval`](#IERC721-Approval-address-address-uint256-) event. @@ -1108,13 +1109,13 @@ Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-u
Approve or remove `operator` as an operator for the caller. -Operators can call [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-) or [`ERC1155.safeTransferFrom`](/contracts/5.x/api/token/ERC1155#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-) for any token owned by the caller. +Operators can call [`ERC721.transferFrom`](#ERC721-transferFrom-address-address-uint256-) or [`ERC721.safeTransferFrom`](#ERC721-safeTransferFrom-address-address-uint256-bytes-) for any token owned by the caller. Requirements: - The `operator` cannot be the address zero. -Emits an [`IERC1155.ApprovalForAll`](/contracts/5.x/api/token/ERC1155#IERC1155-ApprovalForAll-address-address-bool-) event. +Emits an [`IERC721.ApprovalForAll`](#IERC721-ApprovalForAll-address-address-bool-) event.
@@ -1154,7 +1155,7 @@ Requirements: Returns if the `operator` is allowed to manage all of the assets of `owner`. -See [`ERC1155.setApprovalForAll`](/contracts/5.x/api/token/ERC1155#ERC1155-setApprovalForAll-address-bool-) +See [`ERC721.setApprovalForAll`](#ERC721-setApprovalForAll-address-bool-) @@ -1215,9 +1216,9 @@ Emitted when `owner` enables or disables (`approved`) `operator` to manage all o
-## `IERC721Receiver` +## `IERC721Receiver` - + @@ -1265,9 +1266,9 @@ The selector can be obtained in Solidity with `IERC721Receiver.onERC721Received.
-## `ERC721Burnable` +## `ERC721Burnable` - + @@ -1283,7 +1284,9 @@ ERC-721 Token that can be burned (destroyed).

Functions

- [burn(tokenId)](#ERC721Burnable-burn-uint256-) -#### ERC721 [!toc] +
+ERC721 + - [supportsInterface(interfaceId)](#ERC721-supportsInterface-bytes4-) - [balanceOf(owner)](#ERC721-balanceOf-address-) - [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) @@ -1315,34 +1318,31 @@ ERC-721 Token that can be burned (destroyed). - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### ERC721 [!toc] -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### ERC721 [!toc] -#### IERC721Errors [!toc] +
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -1351,10 +1351,8 @@ ERC-721 Token that can be burned (destroyed). - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -1383,9 +1381,9 @@ Requirements:
-## `ERC721Consecutive` +## `ERC721Consecutive` - + @@ -1406,7 +1404,7 @@ Using this extension removes the ability to mint single tokens during contract c regained after construction. During construction, only batch minting is allowed. -This extension does not call the [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) function for tokens minted in batch. Any logic added to this +This extension does not call the [`ERC721._update`](#ERC721-_update-address-uint256-address-) function for tokens minted in batch. Any logic added to this function through overrides will not be triggered when tokens are minted in batch. You may want to also override [`ERC721._increaseBalance`](#ERC721-_increaseBalance-address-uint128-) or [`ERC721Consecutive._mintConsecutive`](#ERC721Consecutive-_mintConsecutive-address-uint96-) to account for these mints. @@ -1425,7 +1423,9 @@ super call before your custom logic. - [_mintConsecutive(to, batchSize)](#ERC721Consecutive-_mintConsecutive-address-uint96-) - [_update(to, tokenId, auth)](#ERC721Consecutive-_update-address-uint256-address-) - [_firstConsecutiveId()](#ERC721Consecutive-_firstConsecutiveId--) -#### ERC721 [!toc] +
+ERC721 + - [supportsInterface(interfaceId)](#ERC721-supportsInterface-bytes4-) - [balanceOf(owner)](#ERC721-balanceOf-address-) - [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) @@ -1455,29 +1455,28 @@ super call before your custom logic. - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IERC2309 [!toc] + +

Events

-#### ERC721 [!toc] -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IERC2309 [!toc] + +
+
+IERC2309 + - [ConsecutiveTransfer(fromTokenId, toTokenId, fromAddress, toAddress)](#IERC2309-ConsecutiveTransfer-uint256-uint256-address-address-) + +
@@ -1488,8 +1487,9 @@ super call before your custom logic. - [ERC721ExceededMaxBatchMint(batchSize, maxBatch)](#ERC721Consecutive-ERC721ExceededMaxBatchMint-uint256-uint256-) - [ERC721ForbiddenMint()](#ERC721Consecutive-ERC721ForbiddenMint--) - [ERC721ForbiddenBatchBurn()](#ERC721Consecutive-ERC721ForbiddenBatchBurn--) -#### ERC721 [!toc] -#### IERC721Errors [!toc] +
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -1498,11 +1498,8 @@ super call before your custom logic. - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] -#### IERC2309 [!toc] + +
@@ -1568,12 +1565,16 @@ Requirements: - `batchSize` must not be greater than [`ERC721Consecutive._maxBatchSize`](#ERC721Consecutive-_maxBatchSize--). - The function is called in the constructor of the contract (directly or indirectly). -CAUTION: Does not emit a `Transfer` event. This is ERC-721 compliant as long as it is done inside of the + +Does not emit a `Transfer` event. This is ERC-721 compliant as long as it is done inside of the constructor, which is enforced by this function. + -CAUTION: Does not invoke `onERC721Received` on the receiver. + +Does not invoke `onERC721Received` on the receiver. + -Emits a [`IERC2309.ConsecutiveTransfer`](../interfaces#IERC2309-ConsecutiveTransfer-uint256-uint256-address-address-) event. +Emits a [`IERC2309.ConsecutiveTransfer`](/contracts/5.x/api/interfaces#IERC2309-ConsecutiveTransfer-uint256-uint256-address-address-) event. @@ -1594,7 +1595,7 @@ See [`ERC721._update`](#ERC721-_update-address-uint256-address-). Override versi Using [`ERC721Consecutive`](#ERC721Consecutive) prevents minting during construction in favor of [`ERC721Consecutive._mintConsecutive`](#ERC721Consecutive-_mintConsecutive-address-uint96-). -After construction, [`ERC721Consecutive._mintConsecutive`](#ERC721Consecutive-_mintConsecutive-address-uint96-) is no longer available and minting through [`ERC1155._update`](/contracts/5.x/api/token/ERC1155#ERC1155-_update-address-address-uint256---uint256---) becomes available. +After construction, [`ERC721Consecutive._mintConsecutive`](#ERC721Consecutive-_mintConsecutive-address-uint96-) is no longer available and minting through [`ERC721._update`](#ERC721-_update-address-uint256-address-) becomes available. @@ -1687,13 +1688,211 @@ Batch burn is not supported. + + +
+ +## `ERC721Crosschain` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Crosschain.sol"; +``` + +Extension of [`ERC721`](#ERC721) that makes it natively cross-chain using the ERC-7786 based [`BridgeNonFungible`](/contracts/5.x/api/crosschain#BridgeNonFungible). + +This extension makes the token compatible with: +* [`ERC721Crosschain`](#ERC721Crosschain) instances on other chains, +* [`ERC721`](#ERC721) instances on other chains that are bridged using [`BridgeERC721`](/contracts/5.x/api/crosschain#BridgeERC721), + +
+

Functions

+
+- [crosschainTransferFrom(from, to, tokenId)](#ERC721Crosschain-crosschainTransferFrom-address-bytes-uint256-) +- [_onSend(from, tokenId)](#ERC721Crosschain-_onSend-address-uint256-) +- [_onReceive(to, tokenId)](#ERC721Crosschain-_onReceive-address-uint256-) +
+BridgeNonFungible + +- [_crosschainTransfer(from, to, tokenId)](#BridgeNonFungible-_crosschainTransfer-address-bytes-uint256-) +- [_processMessage(, receiveId, , payload)](#BridgeNonFungible-_processMessage-address-bytes32-bytes-bytes-) + +
+
+CrosschainLinked + +- [getLink(chain)](#CrosschainLinked-getLink-bytes-) +- [_setLink(gateway, counterpart, allowOverride)](#CrosschainLinked-_setLink-address-bytes-bool-) +- [_sendMessageToCounterpart(chain, payload, attributes)](#CrosschainLinked-_sendMessageToCounterpart-bytes-bytes-bytes---) +- [_isAuthorizedGateway(instance, sender)](#CrosschainLinked-_isAuthorizedGateway-address-bytes-) + +
+
+ERC7786Recipient + +- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-) + +
+
+ERC721 + +- [supportsInterface(interfaceId)](#ERC721-supportsInterface-bytes4-) +- [balanceOf(owner)](#ERC721-balanceOf-address-) +- [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) +- [name()](#ERC721-name--) +- [symbol()](#ERC721-symbol--) +- [tokenURI(tokenId)](#ERC721-tokenURI-uint256-) +- [_baseURI()](#ERC721-_baseURI--) +- [approve(to, tokenId)](#ERC721-approve-address-uint256-) +- [getApproved(tokenId)](#ERC721-getApproved-uint256-) +- [setApprovalForAll(operator, approved)](#ERC721-setApprovalForAll-address-bool-) +- [isApprovedForAll(owner, operator)](#ERC721-isApprovedForAll-address-address-) +- [transferFrom(from, to, tokenId)](#ERC721-transferFrom-address-address-uint256-) +- [safeTransferFrom(from, to, tokenId)](#ERC721-safeTransferFrom-address-address-uint256-) +- [safeTransferFrom(from, to, tokenId, data)](#ERC721-safeTransferFrom-address-address-uint256-bytes-) +- [_ownerOf(tokenId)](#ERC721-_ownerOf-uint256-) +- [_getApproved(tokenId)](#ERC721-_getApproved-uint256-) +- [_isAuthorized(owner, spender, tokenId)](#ERC721-_isAuthorized-address-address-uint256-) +- [_checkAuthorized(owner, spender, tokenId)](#ERC721-_checkAuthorized-address-address-uint256-) +- [_increaseBalance(account, value)](#ERC721-_increaseBalance-address-uint128-) +- [_update(to, tokenId, auth)](#ERC721-_update-address-uint256-address-) +- [_mint(to, tokenId)](#ERC721-_mint-address-uint256-) +- [_safeMint(to, tokenId)](#ERC721-_safeMint-address-uint256-) +- [_safeMint(to, tokenId, data)](#ERC721-_safeMint-address-uint256-bytes-) +- [_burn(tokenId)](#ERC721-_burn-uint256-) +- [_transfer(from, to, tokenId)](#ERC721-_transfer-address-address-uint256-) +- [_safeTransfer(from, to, tokenId)](#ERC721-_safeTransfer-address-address-uint256-) +- [_safeTransfer(from, to, tokenId, data)](#ERC721-_safeTransfer-address-address-uint256-bytes-) +- [_approve(to, tokenId, auth)](#ERC721-_approve-address-uint256-address-) +- [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) +- [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) +- [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) + +
+
+
+ +
+

Events

+
+
+BridgeNonFungible + +- [CrosschainNonFungibleTransferSent(sendId, from, to, tokenId)](#BridgeNonFungible-CrosschainNonFungibleTransferSent-bytes32-address-bytes-uint256-) +- [CrosschainNonFungibleTransferReceived(receiveId, from, to, tokenId)](#BridgeNonFungible-CrosschainNonFungibleTransferReceived-bytes32-bytes-address-uint256-) + +
+
+CrosschainLinked + +- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-) + +
+
+IERC721 + +- [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) +- [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) +- [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) + +
+
+
+ +
+

Errors

+
+
+CrosschainLinked + +- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-) + +
+
+ERC7786Recipient + +- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-) + +
+
+IERC721Errors + +- [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) +- [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) +- [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) +- [ERC721InvalidSender(sender)](#IERC721Errors-ERC721InvalidSender-address-) +- [ERC721InvalidReceiver(receiver)](#IERC721Errors-ERC721InvalidReceiver-address-) +- [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) +- [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) +- [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) + +
+
+
+ + + +
+
+

crosschainTransferFrom(address from, bytes to, uint256 tokenId) โ†’ bytes32

+
+

public

+# +
+
+
+ +Crosschain variant of [`ERC721.transferFrom`](#ERC721-transferFrom-address-address-uint256-), using the allowance system from the underlying ERC-721 token. + +
+
+ + + +
+
+

_onSend(address from, uint256 tokenId)

+
+

internal

+# +
+
+
+ +"Locking" tokens is achieved through burning + +
+
+ + + +
+
+

_onReceive(address to, uint256 tokenId)

+
+

internal

+# +
+
+
+ +"Unlocking" tokens is achieved through minting + +
+
+
-## `ERC721Enumerable` +## `ERC721Enumerable` - + @@ -1706,8 +1905,10 @@ import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol"; This implements an optional extension of [`ERC721`](#ERC721) defined in the ERC that adds enumerability of all the token ids in the contract as well as all token ids owned by each account. -CAUTION: [`ERC721`](#ERC721) extensions that implement custom `balanceOf` logic, such as [`ERC721Consecutive`](#ERC721Consecutive), + +[`ERC721`](#ERC721) extensions that implement custom `balanceOf` logic, such as [`ERC721Consecutive`](#ERC721Consecutive), interfere with enumerability and should not be used together with [`ERC721Enumerable`](#ERC721Enumerable). +

Functions

@@ -1718,8 +1919,9 @@ interfere with enumerability and should not be used together with [`ERC721Enumer - [tokenByIndex(index)](#ERC721Enumerable-tokenByIndex-uint256-) - [_update(to, tokenId, auth)](#ERC721Enumerable-_update-address-uint256-address-) - [_increaseBalance(account, amount)](#ERC721Enumerable-_increaseBalance-address-uint128-) -#### IERC721Enumerable [!toc] -#### ERC721 [!toc] +
+ERC721 + - [balanceOf(owner)](#ERC721-balanceOf-address-) - [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) - [name()](#ERC721-name--) @@ -1748,27 +1950,22 @@ interfere with enumerability and should not be used together with [`ERC721Enumer - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### IERC721Enumerable [!toc] -#### ERC721 [!toc] -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -1777,9 +1974,9 @@ interfere with enumerability and should not be used together with [`ERC721Enumer
- [ERC721OutOfBoundsIndex(owner, index)](#ERC721Enumerable-ERC721OutOfBoundsIndex-address-uint256-) - [ERC721EnumerableForbiddenBatchMint()](#ERC721Enumerable-ERC721EnumerableForbiddenBatchMint--) -#### IERC721Enumerable [!toc] -#### ERC721 [!toc] -#### IERC721Errors [!toc] +
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -1788,10 +1985,8 @@ interfere with enumerability and should not be used together with [`ERC721Enumer - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -1830,7 +2025,7 @@ This function call must use less than 30 000 gas.
Returns a token ID owned by `owner` at a given `index` of its token list. -Use along with [`IERC6909.balanceOf`](../interfaces#IERC6909-balanceOf-address-uint256-) to enumerate all of ``owner``'s tokens. +Use along with [`ERC721.balanceOf`](#ERC721-balanceOf-address-) to enumerate all of ``owner``'s tokens.
@@ -1865,7 +2060,7 @@ Returns the total amount of tokens stored by the contract.
Returns a token ID at a given `index` of all the tokens stored by the contract. -Use along with [`IERC6909TokenSupply.totalSupply`](../interfaces#IERC6909TokenSupply-totalSupply-uint256-) to enumerate all tokens. +Use along with [`ERC721Enumerable.totalSupply`](#ERC721Enumerable-totalSupply--) to enumerate all tokens.
@@ -1888,7 +2083,7 @@ Transfers `tokenId` from its current owner to `to`, or alternatively mints (or b The `auth` argument is optional. If the value passed is non 0, then this function will check that `auth` is either the owner of the token, or approved to operate on the token (by the owner). -Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event. +Emits a [`IERC721.Transfer`](#IERC721-Transfer-address-address-uint256-) event. If overriding this function in a way that tracks balances, see also [`ERC721._increaseBalance`](#ERC721-_increaseBalance-address-uint128-). @@ -1954,9 +2149,9 @@ Batch mint is not allowed.
-## `ERC721Pausable` +## `ERC721Pausable` - + @@ -1975,8 +2170,8 @@ event of a large bug. This contract does not include public pause and unpause functions. In addition to inheriting this contract, you must define both functions, invoking the -[`Pausable._pause`](../utils#Pausable-_pause--) and [`Pausable._unpause`](../utils#Pausable-_unpause--) internal functions, with appropriate -access control, e.g. using [`AccessControl`](../access#AccessControl) or [`Ownable`](../access#Ownable). Not doing so will +[`Pausable._pause`](/contracts/5.x/api/utils#Pausable-_pause--) and [`Pausable._unpause`](/contracts/5.x/api/utils#Pausable-_unpause--) internal functions, with appropriate +access control, e.g. using [`AccessControl`](/contracts/5.x/api/access#AccessControl) or [`Ownable`](/contracts/5.x/api/access#Ownable). Not doing so will make the contract pause mechanism of the contract unreachable, and thus unusable. @@ -1984,13 +2179,19 @@ make the contract pause mechanism of the contract unreachable, and thus unusable

Functions

- [_update(to, tokenId, auth)](#ERC721Pausable-_update-address-uint256-address-) -#### Pausable [!toc] +
+Pausable + - [paused()](#Pausable-paused--) - [_requireNotPaused()](#Pausable-_requireNotPaused--) - [_requirePaused()](#Pausable-_requirePaused--) - [_pause()](#Pausable-_pause--) - [_unpause()](#Pausable-_unpause--) -#### ERC721 [!toc] + +
+
+ERC721 + - [supportsInterface(interfaceId)](#ERC721-supportsInterface-bytes4-) - [balanceOf(owner)](#ERC721-balanceOf-address-) - [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) @@ -2021,40 +2222,45 @@ make the contract pause mechanism of the contract unreachable, and thus unusable - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Pausable [!toc] +
+Pausable + - [Paused(account)](#Pausable-Paused-address-) - [Unpaused(account)](#Pausable-Unpaused-address-) -#### ERC721 [!toc] -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] + +
+
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Pausable [!toc] +
+Pausable + - [EnforcedPause()](#Pausable-EnforcedPause--) - [ExpectedPause()](#Pausable-ExpectedPause--) -#### ERC721 [!toc] -#### IERC721Errors [!toc] + +
+
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -2063,10 +2269,8 @@ make the contract pause mechanism of the contract unreachable, and thus unusable - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -2095,9 +2299,9 @@ Requirements:
-## `ERC721Royalty` +## `ERC721Royalty` - + @@ -2123,7 +2327,9 @@ voluntarily pay royalties together with sales, but note that this standard is no

Functions

- [supportsInterface(interfaceId)](#ERC721Royalty-supportsInterface-bytes4-) -#### ERC721 [!toc] +
+ERC721 + - [balanceOf(owner)](#ERC721-balanceOf-address-) - [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) - [name()](#ERC721-name--) @@ -2154,44 +2360,42 @@ voluntarily pay royalties together with sales, but note that this standard is no - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC2981 [!toc] + +
+
+ERC2981 + - [royaltyInfo(tokenId, salePrice)](#ERC2981-royaltyInfo-uint256-uint256-) - [_feeDenominator()](#ERC2981-_feeDenominator--) - [_setDefaultRoyalty(receiver, feeNumerator)](#ERC2981-_setDefaultRoyalty-address-uint96-) - [_deleteDefaultRoyalty()](#ERC2981-_deleteDefaultRoyalty--) - [_setTokenRoyalty(tokenId, receiver, feeNumerator)](#ERC2981-_setTokenRoyalty-uint256-address-uint96-) - [_resetTokenRoyalty(tokenId)](#ERC2981-_resetTokenRoyalty-uint256-) -#### ERC165 [!toc] -#### IERC2981 [!toc] -#### IERC165 [!toc] + +

Events

-#### ERC721 [!toc] -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC2981 [!toc] -#### ERC165 [!toc] -#### IERC2981 [!toc] -#### IERC165 [!toc] + +

Errors

-#### ERC721 [!toc] -#### IERC721Errors [!toc] +
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -2200,16 +2404,17 @@ voluntarily pay royalties together with sales, but note that this standard is no - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC2981 [!toc] + +
+
+ERC2981 + - [ERC2981InvalidDefaultRoyalty(numerator, denominator)](#ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-) - [ERC2981InvalidDefaultRoyaltyReceiver(receiver)](#ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-) - [ERC2981InvalidTokenRoyalty(tokenId, numerator, denominator)](#ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-) - [ERC2981InvalidTokenRoyaltyReceiver(tokenId, receiver)](#ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-) -#### ERC165 [!toc] -#### IERC2981 [!toc] -#### IERC165 [!toc] + +
@@ -2232,9 +2437,9 @@ voluntarily pay royalties together with sales, but note that this standard is no
-## `ERC721URIStorage` +## `ERC721URIStorage` - + @@ -2252,7 +2457,10 @@ ERC-721 token with storage based token URI management. - [supportsInterface(interfaceId)](#ERC721URIStorage-supportsInterface-bytes4-) - [tokenURI(tokenId)](#ERC721URIStorage-tokenURI-uint256-) - [_setTokenURI(tokenId, _tokenURI)](#ERC721URIStorage-_setTokenURI-uint256-string-) -#### ERC721 [!toc] +- [_suffixURI(tokenId)](#ERC721URIStorage-_suffixURI-uint256-) +
+ERC721 + - [balanceOf(owner)](#ERC721-balanceOf-address-) - [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) - [name()](#ERC721-name--) @@ -2282,38 +2490,38 @@ ERC-721 token with storage based token URI management. - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC4906 [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### ERC721 [!toc] -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC4906 [!toc] +
+IERC4906 + - [MetadataUpdate(_tokenId)](#IERC4906-MetadataUpdate-uint256-) - [BatchMetadataUpdate(_fromTokenId, _toTokenId)](#IERC4906-BatchMetadataUpdate-uint256-uint256-) -#### IERC721 [!toc] + +
+
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### ERC721 [!toc] -#### IERC721Errors [!toc] +
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -2322,11 +2530,8 @@ ERC-721 token with storage based token URI management. - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC4906 [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -2381,7 +2586,24 @@ This function call must use less than 30 000 gas. Sets `_tokenURI` as the tokenURI of `tokenId`. -Emits [`IERC4906.MetadataUpdate`](../interfaces#IERC4906-MetadataUpdate-uint256-). +Emits [`IERC4906.MetadataUpdate`](/contracts/5.x/api/interfaces#IERC4906-MetadataUpdate-uint256-). + + + + + + +
+
+

_suffixURI(uint256 tokenId) โ†’ string

+
+

internal

+# +
+
+
+ +Returns the suffix part of the tokenURI for `tokenId`.
@@ -2390,9 +2612,9 @@ Emits [`IERC4906.MetadataUpdate`](../interfaces#IERC4906-MetadataUpdate-uint256-
-## `ERC721Votes` +## `ERC721Votes` - + @@ -2402,7 +2624,7 @@ Emits [`IERC4906.MetadataUpdate`](../interfaces#IERC4906-MetadataUpdate-uint256- import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Votes.sol"; ``` -Extension of ERC-721 to support voting and delegation as implemented by [`Votes`](../governance#Votes), where each individual NFT counts +Extension of ERC-721 to support voting and delegation as implemented by [`Votes`](/contracts/5.x/api/governance#Votes), where each individual NFT counts as 1 vote unit. Tokens do not count as votes until they are delegated, because votes must be tracked which incurs an additional cost @@ -2415,7 +2637,9 @@ the votes in governance decisions, or they can delegate to themselves to be thei - [_update(to, tokenId, auth)](#ERC721Votes-_update-address-uint256-address-) - [_getVotingUnits(account)](#ERC721Votes-_getVotingUnits-address-) - [_increaseBalance(account, amount)](#ERC721Votes-_increaseBalance-address-uint128-) -#### Votes [!toc] +
+Votes + - [clock()](#Votes-clock--) - [CLOCK_MODE()](#Votes-CLOCK_MODE--) - [_validateTimepoint(timepoint)](#Votes-_validateTimepoint-uint256-) @@ -2431,21 +2655,29 @@ the votes in governance decisions, or they can delegate to themselves to be thei - [_moveDelegateVotes(from, to, amount)](#Votes-_moveDelegateVotes-address-address-uint256-) - [_numCheckpoints(account)](#Votes-_numCheckpoints-address-) - [_checkpoints(account, pos)](#Votes-_checkpoints-address-uint32-) -#### IERC5805 [!toc] -#### IVotes [!toc] -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) - [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-) -#### EIP712 [!toc] + +
+
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### ERC721 [!toc] + +
+
+ERC721 + - [supportsInterface(interfaceId)](#ERC721-supportsInterface-bytes4-) - [balanceOf(owner)](#ERC721-balanceOf-address-) - [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) @@ -2475,55 +2707,63 @@ the votes in governance decisions, or they can delegate to themselves to be thei - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### Votes [!toc] -#### IERC5805 [!toc] -#### IVotes [!toc] +
+IVotes + - [DelegateChanged(delegator, fromDelegate, toDelegate)](#IVotes-DelegateChanged-address-address-address-) - [DelegateVotesChanged(delegate, previousVotes, newVotes)](#IVotes-DelegateVotesChanged-address-uint256-uint256-) -#### IERC6372 [!toc] -#### Nonces [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] + +
+
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### ERC721 [!toc] -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] + +
+
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Errors

-#### Votes [!toc] +
+Votes + - [ERC6372InconsistentClock()](#Votes-ERC6372InconsistentClock--) - [ERC5805FutureLookup(timepoint, clock)](#Votes-ERC5805FutureLookup-uint256-uint48-) -#### IERC5805 [!toc] -#### IVotes [!toc] + +
+
+IVotes + - [VotesExpiredSignature(expiry)](#IVotes-VotesExpiredSignature-uint256-) -#### IERC6372 [!toc] -#### Nonces [!toc] + +
+
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) -#### EIP712 [!toc] -#### IERC5267 [!toc] -#### ERC721 [!toc] -#### IERC721Errors [!toc] + +
+
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -2532,10 +2772,8 @@ the votes in governance decisions, or they can delegate to themselves to be thei - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -2553,7 +2791,7 @@ the votes in governance decisions, or they can delegate to themselves to be thei See [`ERC721._update`](#ERC721-_update-address-uint256-address-). Adjusts votes when tokens are transferred. -Emits a [`IVotes.DelegateVotesChanged`](../governance#IVotes-DelegateVotesChanged-address-uint256-uint256-) event. +Emits a [`IVotes.DelegateVotesChanged`](/contracts/5.x/api/governance#IVotes-DelegateVotesChanged-address-uint256-uint256-) event. @@ -2600,9 +2838,9 @@ See [`ERC721._increaseBalance`](#ERC721-_increaseBalance-address-uint128-). We n
-## `ERC721Wrapper` +## `ERC721Wrapper` - + @@ -2627,8 +2865,9 @@ the wrapping of an existing "basic" ERC-721 into a governance token. - [onERC721Received(, from, tokenId, )](#ERC721Wrapper-onERC721Received-address-address-uint256-bytes-) - [_recover(account, tokenId)](#ERC721Wrapper-_recover-address-uint256-) - [underlying()](#ERC721Wrapper-underlying--) -#### IERC721Receiver [!toc] -#### ERC721 [!toc] +
+ERC721 + - [supportsInterface(interfaceId)](#ERC721-supportsInterface-bytes4-) - [balanceOf(owner)](#ERC721-balanceOf-address-) - [ownerOf(tokenId)](#ERC721-ownerOf-uint256-) @@ -2660,27 +2899,22 @@ the wrapping of an existing "basic" ERC-721 into a governance token. - [_approve(to, tokenId, auth, emitEvent)](#ERC721-_approve-address-uint256-address-bool-) - [_setApprovalForAll(owner, operator, approved)](#ERC721-_setApprovalForAll-address-address-bool-) - [_requireOwned(tokenId)](#ERC721-_requireOwned-uint256-) -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +

Events

-#### IERC721Receiver [!toc] -#### ERC721 [!toc] -#### IERC721Errors [!toc] -#### IERC721Metadata [!toc] -#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -2688,9 +2922,9 @@ the wrapping of an existing "basic" ERC-721 into a governance token.

Errors

- [ERC721UnsupportedToken(token)](#ERC721Wrapper-ERC721UnsupportedToken-address-) -#### IERC721Receiver [!toc] -#### ERC721 [!toc] -#### IERC721Errors [!toc] +
+IERC721Errors + - [ERC721InvalidOwner(owner)](#IERC721Errors-ERC721InvalidOwner-address-) - [ERC721NonexistentToken(tokenId)](#IERC721Errors-ERC721NonexistentToken-uint256-) - [ERC721IncorrectOwner(sender, tokenId, owner)](#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-) @@ -2699,10 +2933,8 @@ the wrapping of an existing "basic" ERC-721 into a governance token. - [ERC721InsufficientApproval(operator, tokenId)](#IERC721Errors-ERC721InsufficientApproval-address-uint256-) - [ERC721InvalidApprover(approver)](#IERC721Errors-ERC721InvalidApprover-address-) - [ERC721InvalidOperator(operator)](#IERC721Errors-ERC721InvalidOperator-address-) -#### IERC721Metadata [!toc] -#### IERC721 [!toc] -#### ERC165 [!toc] -#### IERC165 [!toc] + +
@@ -2771,7 +3003,7 @@ Overrides [`IERC721Receiver.onERC721Received`](#IERC721Receiver-onERC721Received this contract. In case there's data attached, it validates that the operator is this contract, so only trusted data -is accepted from [`ERC20Wrapper.depositFor`](/contracts/5.x/api/token/ERC20#ERC20Wrapper-depositFor-address-uint256-). +is accepted from [`ERC721Wrapper.depositFor`](#ERC721Wrapper-depositFor-address-uint256---). Doesn't work with unsafe transfers (eg. [`IERC721.transferFrom`](#IERC721-transferFrom-address-address-uint256-)). Use [`ERC721Wrapper._recover`](#ERC721Wrapper-_recover-address-uint256-) @@ -2837,9 +3069,9 @@ The received ERC-721 token couldn't be wrapped.
-## `IERC721Enumerable` +## `IERC721Enumerable` - + @@ -2857,7 +3089,9 @@ See https://eips.ethereum.org/EIPS/eip-721 - [totalSupply()](#IERC721Enumerable-totalSupply--) - [tokenOfOwnerByIndex(owner, index)](#IERC721Enumerable-tokenOfOwnerByIndex-address-uint256-) - [tokenByIndex(index)](#IERC721Enumerable-tokenByIndex-uint256-) -#### IERC721 [!toc] +
+IERC721 + - [balanceOf(owner)](#IERC721-balanceOf-address-) - [ownerOf(tokenId)](#IERC721-ownerOf-uint256-) - [safeTransferFrom(from, to, tokenId, data)](#IERC721-safeTransferFrom-address-address-uint256-bytes-) @@ -2867,19 +3101,28 @@ See https://eips.ethereum.org/EIPS/eip-721 - [setApprovalForAll(operator, approved)](#IERC721-setApprovalForAll-address-bool-) - [getApproved(tokenId)](#IERC721-getApproved-uint256-) - [isApprovedForAll(owner, operator)](#IERC721-isApprovedForAll-address-address-) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### IERC165 [!toc] + +
@@ -2913,7 +3156,7 @@ Returns the total amount of tokens stored by the contract.
Returns a token ID owned by `owner` at a given `index` of its token list. -Use along with [`IERC6909.balanceOf`](../interfaces#IERC6909-balanceOf-address-uint256-) to enumerate all of ``owner``'s tokens. +Use along with [`ERC721.balanceOf`](#ERC721-balanceOf-address-) to enumerate all of ``owner``'s tokens.
@@ -2931,7 +3174,7 @@ Use along with [`IERC6909.balanceOf`](../interfaces#IERC6909-balanceOf-address-u
Returns a token ID at a given `index` of all the tokens stored by the contract. -Use along with [`IERC6909TokenSupply.totalSupply`](../interfaces#IERC6909TokenSupply-totalSupply-uint256-) to enumerate all tokens. +Use along with [`ERC721Enumerable.totalSupply`](#ERC721Enumerable-totalSupply--) to enumerate all tokens.
@@ -2940,9 +3183,9 @@ Use along with [`IERC6909TokenSupply.totalSupply`](../interfaces#IERC6909TokenSu
-## `IERC721Metadata` +## `IERC721Metadata` - + @@ -2960,7 +3203,9 @@ See https://eips.ethereum.org/EIPS/eip-721 - [name()](#IERC721Metadata-name--) - [symbol()](#IERC721Metadata-symbol--) - [tokenURI(tokenId)](#IERC721Metadata-tokenURI-uint256-) -#### IERC721 [!toc] +
+IERC721 + - [balanceOf(owner)](#IERC721-balanceOf-address-) - [ownerOf(tokenId)](#IERC721-ownerOf-uint256-) - [safeTransferFrom(from, to, tokenId, data)](#IERC721-safeTransferFrom-address-address-uint256-bytes-) @@ -2970,19 +3215,28 @@ See https://eips.ethereum.org/EIPS/eip-721 - [setApprovalForAll(operator, approved)](#IERC721-setApprovalForAll-address-bool-) - [getApproved(tokenId)](#IERC721-getApproved-uint256-) - [isApprovedForAll(owner, operator)](#IERC721-isApprovedForAll-address-address-) -#### IERC165 [!toc] + +
+
+IERC165 + - [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-) + +

Events

-#### IERC721 [!toc] +
+IERC721 + - [Transfer(from, to, tokenId)](#IERC721-Transfer-address-address-uint256-) - [Approval(owner, approved, tokenId)](#IERC721-Approval-address-address-uint256-) - [ApprovalForAll(owner, operator, approved)](#IERC721-ApprovalForAll-address-address-bool-) -#### IERC165 [!toc] + +
@@ -3041,9 +3295,9 @@ Returns the Uniform Resource Identifier (URI) for `tokenId` token.
-## `ERC721Holder` +## `ERC721Holder` - + @@ -3065,7 +3319,6 @@ Make sure the contract is able to use its token with [`IERC721.safeTransferFrom`

Functions

- [onERC721Received(, , , )](#ERC721Holder-onERC721Received-address-address-uint256-bytes-) -#### IERC721Receiver [!toc]
@@ -3092,9 +3345,9 @@ Always returns `IERC721Receiver.onERC721Received.selector`.
-## `ERC721Utils` +## `ERC721Utils` - + @@ -3138,3 +3391,4 @@ the transfer.
+ diff --git a/content/contracts/5.x/api/token/common.mdx b/content/contracts/5.x/api/token/common.mdx index a1f70f22..1f1b5644 100644 --- a/content/contracts/5.x/api/token/common.mdx +++ b/content/contracts/5.x/api/token/common.mdx @@ -16,9 +16,9 @@ Functionality that is common to multiple token standards.
-## `ERC2981` +## `ERC2981` - + @@ -52,9 +52,6 @@ voluntarily pay royalties together with sales, but note that this standard is no - [_deleteDefaultRoyalty()](#ERC2981-_deleteDefaultRoyalty--) - [_setTokenRoyalty(tokenId, receiver, feeNumerator)](#ERC2981-_setTokenRoyalty-uint256-address-uint96-) - [_resetTokenRoyalty(tokenId)](#ERC2981-_resetTokenRoyalty-uint256-) -#### ERC165 [!toc] -#### IERC2981 [!toc] -#### IERC165 [!toc]
@@ -65,9 +62,6 @@ voluntarily pay royalties together with sales, but note that this standard is no - [ERC2981InvalidDefaultRoyaltyReceiver(receiver)](#ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-) - [ERC2981InvalidTokenRoyalty(tokenId, numerator, denominator)](#ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-) - [ERC2981InvalidTokenRoyaltyReceiver(tokenId, receiver)](#ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-) -#### ERC165 [!toc] -#### IERC2981 [!toc] -#### IERC165 [!toc] @@ -280,3 +274,4 @@ The royalty receiver for `tokenId` is invalid. + diff --git a/content/contracts/5.x/api/utils.mdx b/content/contracts/5.x/api/utils.mdx index 38b05b49..de595447 100644 --- a/content/contracts/5.x/api/utils.mdx +++ b/content/contracts/5.x/api/utils.mdx @@ -42,6 +42,7 @@ Miscellaneous contracts and libraries containing utility functions you can use t * [`RelayedCall`](#RelayedCall): A library for performing calls that use minimal and predictable relayers to hide the sender. * [`RLP`](#RLP): Library for encoding and decoding data in Ethereumโ€™s Recursive Length Prefix format. * [`ShortStrings`](#ShortStrings): Library to encode (and decode) short strings into (or from) a single bytes32 slot for optimizing costs. Short strings are limited to 31 characters. +* [`SimulateCall`](#SimulateCall): Library for simulating contract calls, enabling safe inspection of call results without affecting on-chain state. * [`SlotDerivation`](#SlotDerivation): Methods for deriving storage slot from ERC-7201 namespaces as well as from constructions such as mapping and arrays. * [`StorageSlot`](#StorageSlot): Methods for accessing specific storage slots formatted as common primitive types. * [`Strings`](#Strings): Common operations for strings formatting. @@ -76,7 +77,7 @@ Because Solidity does not support generic types, [`EnumerableMap`](#EnumerableMa This set of interfaces and contracts deal with [type introspection](https://en.wikipedia.org/wiki/Type_introspection) of contracts, that is, examining which functions can be called on them. This is usually referred to as a contractโ€™s _interface_. -Ethereum contracts have no native concept of an interface, so applications must usually simply trust they are not making an incorrect call. For trusted setups this is a non-issue, but often unknown and untrusted third-party addresses need to be interacted with. There may even not be any direct calls to them! (e.g. ERC-20 tokens may be sent to a contract that lacks a way to transfer them out of it, locking them forever). In these cases, a contract _declaring_ its interface can be very helpful in preventing errors. +Ethereum contracts have no native concept of an interface, so applications must usually simply trust that they are not making an incorrect call. For trusted setups this is a non-issue, but often unknown and untrusted third-party addresses need to be interacted with. There may not even be any direct calls to them! (e.g. ERC-20 tokens may be sent to a contract that lacks a way to transfer them out of it, locking them forever). In these cases, a contract _declaring_ its interface can be very helpful in preventing errors. [`IERC165`](#IERC165) @@ -148,6 +149,8 @@ Ethereum contracts have no native concept of an interface, so applications must [`ShortStrings`](#ShortStrings) +[`SimulateCall`](#SimulateCall) + [`SlotDerivation`](#SlotDerivation) [`StorageSlot`](#StorageSlot) @@ -162,9 +165,9 @@ Ethereum contracts have no native concept of an interface, so applications must
-## `Address` +## `Address` - + @@ -247,7 +250,7 @@ function instead. If `target` reverts with a revert reason or custom error, it is bubbled up by this function (like regular Solidity function calls). However, if the call reverted with no returned reason, this function reverts with a -[`Errors.FailedCall`](#Errors-FailedCall--) error. +`Errors.FailedCall` error. Returns the raw returned data. To convert to the expected return value, use [`abi.decode`](https://solidity.readthedocs.io/en/latest/units-and-global-variables.html?highlight=abi.decode#abi-encoding-and-decoding-functions). @@ -332,7 +335,7 @@ but performing a delegate call.
Tool to verify that a low level call to smart-contract was successful, and reverts if the target -was not a contract or bubbling up the revert reason (falling back to [`Errors.FailedCall`](#Errors-FailedCall--)) in case +was not a contract or bubbling up the revert reason (falling back to `Errors.FailedCall`) in case of an unsuccessful call. @@ -355,7 +358,7 @@ This function is DEPRECATED and may be removed in the next major release.
Tool to verify that a low level call was successful, and reverts if it wasn't, either by bubbling the -revert reason or with a default [`Errors.FailedCall`](#Errors-FailedCall--) error. +revert reason or with a default `Errors.FailedCall` error.
@@ -381,9 +384,9 @@ There's no code at `target` (it is not a contract).
-## `Arrays` +## `Arrays` - + @@ -417,10 +420,16 @@ Collection of functions related to array types. - [slice(array, start, end)](#Arrays-slice-uint256---uint256-uint256-) - [splice(array, start)](#Arrays-splice-address---uint256-) - [splice(array, start, end)](#Arrays-splice-address---uint256-uint256-) +- [replace(array, pos, replacement)](#Arrays-replace-address---uint256-address---) +- [replace(array, pos, replacement, offset, length)](#Arrays-replace-address---uint256-address---uint256-uint256-) - [splice(array, start)](#Arrays-splice-bytes32---uint256-) - [splice(array, start, end)](#Arrays-splice-bytes32---uint256-uint256-) +- [replace(array, pos, replacement)](#Arrays-replace-bytes32---uint256-bytes32---) +- [replace(array, pos, replacement, offset, length)](#Arrays-replace-bytes32---uint256-bytes32---uint256-uint256-) - [splice(array, start)](#Arrays-splice-uint256---uint256-) - [splice(array, start, end)](#Arrays-splice-uint256---uint256-uint256-) +- [replace(array, pos, replacement)](#Arrays-replace-uint256---uint256-uint256---) +- [replace(array, pos, replacement, offset, length)](#Arrays-replace-uint256---uint256-uint256---uint256-uint256-) - [unsafeAccess(arr, pos)](#Arrays-unsafeAccess-address---uint256-) - [unsafeAccess(arr, pos)](#Arrays-unsafeAccess-bytes32---uint256-) - [unsafeAccess(arr, pos)](#Arrays-unsafeAccess-uint256---uint256-) @@ -836,14 +845,12 @@ replicates the behavior of [Javascript's `Array.slice`](https://developer.mozill
-Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array. +Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array, +and shrinks the array length accordingly, effectively overwriting the array with array[start:]. This function modifies the provided array in place. If you need to preserve the original array, use [`Arrays.slice`](#Arrays-slice-uint256---uint256-uint256-) instead. - -replicates the behavior of [Javascript's `Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) -
@@ -860,14 +867,63 @@ replicates the behavior of [Javascript's `Array.splice`](https://developer.mozil
-Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array. The +Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array, +and shrinks the array length accordingly, effectively overwriting the array with array[start:end]. The `end` argument is truncated to the length of the `array`. This function modifies the provided array in place. If you need to preserve the original array, use [`Arrays.slice`](#Arrays-slice-uint256---uint256-uint256-) instead. + +
+ + + + +
+
+

replace(address[] array, uint256 pos, address[] replacement) โ†’ address[]

+
+

internal

+# +
+
+
+ +Replaces elements in `array` starting at `pos` with all elements from `replacement`. + +Parameters are clamped to valid ranges (e.g. `pos` is clamped to `[0, array.length]`). +If `pos >= array.length`, no replacement occurs and the array is returned unchanged. + + +This function modifies the provided array in place. + + +
+
+ + + +
+
+

replace(address[] array, uint256 pos, address[] replacement, uint256 offset, uint256 length) โ†’ address[]

+
+

internal

+# +
+
+
+ +Replaces elements in `array` starting at `pos` with elements from `replacement` starting at `offset`. +Copies at most `length` elements from `replacement` to `array`. + +Parameters are clamped to valid ranges (i.e. `pos` is clamped to `[0, array.length]`, `offset` is +clamped to `[0, replacement.length]`, and `length` is clamped to `min(length, replacement.length - offset, +array.length - pos)`). If `pos >= array.length` or `offset >= replacement.length`, no replacement occurs +and the array is returned unchanged. + -replicates the behavior of [Javascript's `Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) +This function modifies the provided array in place.
@@ -885,14 +941,12 @@ replicates the behavior of [Javascript's `Array.splice`](https://developer.mozil
-Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array. +Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array, +and shrinks the array length accordingly, effectively overwriting the array with array[start:]. This function modifies the provided array in place. If you need to preserve the original array, use [`Arrays.slice`](#Arrays-slice-uint256---uint256-uint256-) instead. - -replicates the behavior of [Javascript's `Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) -
@@ -909,14 +963,63 @@ replicates the behavior of [Javascript's `Array.splice`](https://developer.mozil
-Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array. The +Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array, +and shrinks the array length accordingly, effectively overwriting the array with array[start:end]. The `end` argument is truncated to the length of the `array`. This function modifies the provided array in place. If you need to preserve the original array, use [`Arrays.slice`](#Arrays-slice-uint256---uint256-uint256-) instead. + +
+ + + + +
+
+

replace(bytes32[] array, uint256 pos, bytes32[] replacement) โ†’ bytes32[]

+
+

internal

+# +
+
+
+ +Replaces elements in `array` starting at `pos` with all elements from `replacement`. + +Parameters are clamped to valid ranges (e.g. `pos` is clamped to `[0, array.length]`). +If `pos >= array.length`, no replacement occurs and the array is returned unchanged. + + +This function modifies the provided array in place. + + +
+
+ + + +
+
+

replace(bytes32[] array, uint256 pos, bytes32[] replacement, uint256 offset, uint256 length) โ†’ bytes32[]

+
+

internal

+# +
+
+
+ +Replaces elements in `array` starting at `pos` with elements from `replacement` starting at `offset`. +Copies at most `length` elements from `replacement` to `array`. + +Parameters are clamped to valid ranges (i.e. `pos` is clamped to `[0, array.length]`, `offset` is +clamped to `[0, replacement.length]`, and `length` is clamped to `min(length, replacement.length - offset, +array.length - pos)`). If `pos >= array.length` or `offset >= replacement.length`, no replacement occurs +and the array is returned unchanged. + -replicates the behavior of [Javascript's `Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) +This function modifies the provided array in place.
@@ -934,14 +1037,12 @@ replicates the behavior of [Javascript's `Array.splice`](https://developer.mozil
-Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array. +Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array, +and shrinks the array length accordingly, effectively overwriting the array with array[start:]. This function modifies the provided array in place. If you need to preserve the original array, use [`Arrays.slice`](#Arrays-slice-uint256---uint256-uint256-) instead. - -replicates the behavior of [Javascript's `Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) -
@@ -958,14 +1059,63 @@ replicates the behavior of [Javascript's `Array.splice`](https://developer.mozil
-Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array. The +Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array, +and shrinks the array length accordingly, effectively overwriting the array with array[start:end]. The `end` argument is truncated to the length of the `array`. This function modifies the provided array in place. If you need to preserve the original array, use [`Arrays.slice`](#Arrays-slice-uint256---uint256-uint256-) instead. + +
+ + + + +
+
+

replace(uint256[] array, uint256 pos, uint256[] replacement) โ†’ uint256[]

+
+

internal

+# +
+
+
+ +Replaces elements in `array` starting at `pos` with all elements from `replacement`. + +Parameters are clamped to valid ranges (e.g. `pos` is clamped to `[0, array.length]`). +If `pos >= array.length`, no replacement occurs and the array is returned unchanged. + + +This function modifies the provided array in place. + + +
+
+ + + +
+
+

replace(uint256[] array, uint256 pos, uint256[] replacement, uint256 offset, uint256 length) โ†’ uint256[]

+
+

internal

+# +
+
+
+ +Replaces elements in `array` starting at `pos` with elements from `replacement` starting at `offset`. +Copies at most `length` elements from `replacement` to `array`. + +Parameters are clamped to valid ranges (i.e. `pos` is clamped to `[0, array.length]`, `offset` is +clamped to `[0, replacement.length]`, and `length` is clamped to `min(length, replacement.length - offset, +array.length - pos)`). If `pos >= array.length` or `offset >= replacement.length`, no replacement occurs +and the array is returned unchanged. + -replicates the behavior of [Javascript's `Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) +This function modifies the provided array in place.
@@ -1196,7 +1346,7 @@ Only use if you are certain `pos` is lower than the array length. Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden. -this does not clear elements if length is reduced, of initialize elements if length is increased. +this does not clear elements if length is reduced, or initialize elements if length is increased.
@@ -1217,7 +1367,7 @@ this does not clear elements if length is reduced, of initialize elements if len Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden. -this does not clear elements if length is reduced, of initialize elements if length is increased. +this does not clear elements if length is reduced, or initialize elements if length is increased. @@ -1238,7 +1388,7 @@ this does not clear elements if length is reduced, of initialize elements if len Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden. -this does not clear elements if length is reduced, of initialize elements if length is increased. +this does not clear elements if length is reduced, or initialize elements if length is increased. @@ -1259,7 +1409,7 @@ this does not clear elements if length is reduced, of initialize elements if len Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden. -this does not clear elements if length is reduced, of initialize elements if length is increased. +this does not clear elements if length is reduced, or initialize elements if length is increased. @@ -1280,7 +1430,7 @@ this does not clear elements if length is reduced, of initialize elements if len Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden. -this does not clear elements if length is reduced, of initialize elements if length is increased. +this does not clear elements if length is reduced, or initialize elements if length is increased. @@ -1290,9 +1440,9 @@ this does not clear elements if length is reduced, of initialize elements if len
-## `Base58` +## `Base58` - + @@ -1386,9 +1536,9 @@ Unrecognized Base58 character on decoding.
-## `Base64` +## `Base64` - + @@ -1467,7 +1617,7 @@ Converts a Base64 `string` to the `bytes` it represents. * Supports padded and unpadded inputs. * Supports both encoding ([`Base58.encode`](#Base58-encode-bytes-) and [`Base64.encodeURL`](#Base64-encodeURL-bytes-)) seamlessly. -* Does NOT revert if the input is not a valid Base64 string. +* Reverts with [`Base64.InvalidBase64Char`](#Base64-InvalidBase64Char-bytes1-) if the input contains an invalid character.
@@ -1491,9 +1641,9 @@ Converts a Base64 `string` to the `bytes` it represents.
-## `Blockhash` +## `Blockhash` - + @@ -1549,9 +1699,9 @@ by returning zero, consistent with the EVM's native `BLOCKHASH` behavior.
-## `Bytes` +## `Bytes` - + @@ -1574,7 +1724,10 @@ Bytes operations. - [slice(buffer, start, end)](#Bytes-slice-bytes-uint256-uint256-) - [splice(buffer, start)](#Bytes-splice-bytes-uint256-) - [splice(buffer, start, end)](#Bytes-splice-bytes-uint256-uint256-) +- [replace(buffer, pos, replacement)](#Bytes-replace-bytes-uint256-bytes-) +- [replace(buffer, pos, replacement, offset, length)](#Bytes-replace-bytes-uint256-bytes-uint256-uint256-) - [concat(buffers)](#Bytes-concat-bytes---) +- [toNibbles(input)](#Bytes-toNibbles-bytes-) - [equal(a, b)](#Bytes-equal-bytes-bytes-) - [reverseBytes32(value)](#Bytes-reverseBytes32-bytes32-) - [reverseBytes16(value)](#Bytes-reverseBytes16-bytes16-) @@ -1733,14 +1886,12 @@ replicates the behavior of [Javascript's `Array.slice`](https://developer.mozill
-Moves the content of `buffer`, from `start` (included) to the end of `buffer` to the start of that buffer. +Moves the content of `buffer`, from `start` (included) to the end of `buffer` to the start of that buffer, +and shrinks the buffer length accordingly, effectively overriding the content of buffer with buffer[start:]. This function modifies the provided buffer in place. If you need to preserve the original buffer, use [`Arrays.slice`](#Arrays-slice-uint256---uint256-uint256-) instead - -replicates the behavior of [Javascript's `Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) -
@@ -1757,14 +1908,63 @@ replicates the behavior of [Javascript's `Array.splice`](https://developer.mozil
-Moves the content of `buffer`, from `start` (included) to end (excluded) to the start of that buffer. The -`end` argument is truncated to the length of the `buffer`. +Moves the content of `buffer`, from `start` (included) to `end` (excluded) to the start of that buffer, +and shrinks the buffer length accordingly, effectively overriding the content of buffer with buffer[start:end]. +The `end` argument is truncated to the length of the `buffer`. This function modifies the provided buffer in place. If you need to preserve the original buffer, use [`Arrays.slice`](#Arrays-slice-uint256---uint256-uint256-) instead + +
+ + + + +
+
+

replace(bytes buffer, uint256 pos, bytes replacement) โ†’ bytes

+
+

internal

+# +
+
+
+ +Replaces bytes in `buffer` starting at `pos` with all bytes from `replacement`. + +Parameters are clamped to valid ranges (i.e. `pos` is clamped to `[0, buffer.length]`). +If `pos >= buffer.length`, no replacement occurs and the buffer is returned unchanged. + + +This function modifies the provided buffer in place. + + +
+
+ + + +
+
+

replace(bytes buffer, uint256 pos, bytes replacement, uint256 offset, uint256 length) โ†’ bytes

+
+

internal

+# +
+
+
+ +Replaces bytes in `buffer` starting at `pos` with bytes from `replacement` starting at `offset`. +Copies at most `length` bytes from `replacement` to `buffer`. + +Parameters are clamped to valid ranges (i.e. `pos` is clamped to `[0, buffer.length]`, `offset` is +clamped to `[0, replacement.length]`, and `length` is clamped to `min(length, replacement.length - offset, +buffer.length - pos))`. If `pos >= buffer.length` or `offset >= replacement.length`, no replacement occurs +and the buffer is returned unchanged. + -replicates the behavior of [Javascript's `Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) +This function modifies the provided buffer in place.
@@ -1795,6 +1995,25 @@ significantly less readable. It might be worth benchmarking the savings of the f
+ + +
+
+

toNibbles(bytes input) โ†’ bytes output

+
+

internal

+# +
+
+
+ +Split each byte in `input` into two nibbles (4 bits each) + +Example: hex"01234567" โ†’ hex"0001020304050607" + +
+
+
@@ -1920,9 +2139,9 @@ if the buffer is all zeros.
-## `CAIP10` +## `CAIP10` - + @@ -2020,9 +2239,9 @@ parsed using the [`CAIP2`](#CAIP2) library.
-## `CAIP2` +## `CAIP2` - + @@ -2118,9 +2337,9 @@ This function does not verify that the CAIP-2 input is properly formatted.
-## `Calldata` +## `Calldata` - + @@ -2174,9 +2393,9 @@ Helper library for manipulating objects in calldata.
-## `Comparators` +## `Comparators` - + @@ -2232,9 +2451,9 @@ _Available since v5.1._
-## `Context` +## `Context` - + @@ -2311,9 +2530,9 @@ This contract is only required for intermediate, library-like contracts.
-## `Create2` +## `Create2` - + @@ -2432,9 +2651,9 @@ There's no code to deploy.
-## `Errors` +## `Errors` - + @@ -2535,9 +2754,9 @@ A necessary precompile is missing.
-## `LowLevelCall` +## `LowLevelCall` - + @@ -2601,7 +2820,7 @@ Performs a Solidity function call using a low level `call` and ignoring the retu
-Same as [`LowLevelCall.callNoReturn`](#LowLevelCall-callNoReturn-address-uint256-bytes-), but allows to specify the value to be sent in the call. +Same as `callNoReturn-address-bytes`, but allows specifying the value to be sent in the call.
@@ -2619,7 +2838,7 @@ Same as [`LowLevelCall.callNoReturn`](#LowLevelCall-callNoReturn-address-uint256
Performs a Solidity function call using a low level `call` and returns the first 64 bytes of the result -in the scratch space of memory. Useful for functions that return a tuple of single-word values. +in the scratch space of memory. Useful for functions that return a tuple with two single-word values. Do not assume that the results are zero if `success` is false. Memory can be already allocated @@ -2641,7 +2860,7 @@ and this function doesn't zero it out.
-Same as `callReturnBytes32Pair`, but allows to specify the value to be sent in the call. +Same as `callReturn64Bytes-address-bytes`, but allows specifying the value to be sent in the call.
@@ -2676,7 +2895,7 @@ Performs a Solidity function call using a low level `staticcall` and ignoring th
Performs a Solidity function call using a low level `staticcall` and returns the first 64 bytes of the result -in the scratch space of memory. Useful for functions that return a tuple of single-word values. +in the scratch space of memory. Useful for functions that return a tuple with two single-word values. Do not assume that the results are zero if `success` is false. Memory can be already allocated @@ -2716,7 +2935,7 @@ Performs a Solidity function call using a low level `delegatecall` and ignoring
Performs a Solidity function call using a low level `delegatecall` and returns the first 64 bytes of the result -in the scratch space of memory. Useful for functions that return a tuple of single-word values. +in the scratch space of memory. Useful for functions that return a tuple with two single-word values. Do not assume that the results are zero if `success` is false. Memory can be already allocated @@ -2796,9 +3015,9 @@ Revert with the return data from the last call.
-## `Memory` +## `Memory` - + @@ -2824,9 +3043,7 @@ guidelines for [Memory Safety](https://docs.soliditylang.org/en/v0.8.20/assembly

Functions

- [getFreeMemoryPointer()](#Memory-getFreeMemoryPointer--) -- [setFreeMemoryPointer(ptr)](#Memory-setFreeMemoryPointer-Memory-Pointer-) -- [asBytes32(ptr)](#Memory-asBytes32-Memory-Pointer-) -- [asPointer(value)](#Memory-asPointer-bytes32-) +- [unsafeSetFreeMemoryPointer(ptr)](#Memory-unsafeSetFreeMemoryPointer-Memory-Pointer-) - [forward(ptr, offset)](#Memory-forward-Memory-Pointer-uint256-) - [equal(ptr1, ptr2)](#Memory-equal-Memory-Pointer-Memory-Pointer-) - [asSlice(self)](#Memory-asSlice-bytes-) @@ -2835,6 +3052,8 @@ guidelines for [Memory Safety](https://docs.soliditylang.org/en/v0.8.20/assembly - [slice(self, offset, len)](#Memory-slice-Memory-Slice-uint256-uint256-) - [load(self, offset)](#Memory-load-Memory-Slice-uint256-) - [toBytes(self)](#Memory-toBytes-Memory-Slice-) +- [equal(a, b)](#Memory-equal-Memory-Slice-Memory-Slice-) +- [isReserved(self)](#Memory-isReserved-Memory-Slice-)
@@ -2855,20 +3074,24 @@ Returns a `Pointer` to the current free `Pointer`.
- +
-

setFreeMemoryPointer(Memory.Pointer ptr)

+

unsafeSetFreeMemoryPointer(Memory.Pointer ptr)

internal

-# +#
Sets the free `Pointer` to a specific value. +The solidity memory layout requires that the FMP is never set to a value lower than 0x80. Setting the +FMP to a value lower than 0x80 may cause unexpected behavior. Deallocating all memory can be achieved by +setting the FMP to 0x80. + Everything after the pointer may be overwritten. @@ -2876,40 +3099,6 @@ Everything after the pointer may be overwritten.
- - -
-
-

asBytes32(Memory.Pointer ptr) โ†’ bytes32

-
-

internal

-# -
-
-
- -`Pointer` to `bytes32`. Expects a pointer to a properly ABI-encoded `bytes` object. - -
-
- - - -
-
-

asPointer(bytes32 value) โ†’ Memory.Pointer

-
-

internal

-# -
-
-
- -`bytes32` to `Pointer`. Expects a pointer to a properly ABI-encoded `bytes` object. - -
-
-
@@ -2990,7 +3179,7 @@ Returns the length of a given slice (equiv to self.length for calldata slices)
-Offset a memory slice (equivalent to self[start:] for calldata slices) +Offset a memory slice (equivalent to self[offset:] for calldata slices)
@@ -3007,7 +3196,7 @@ Offset a memory slice (equivalent to self[start:] for calldata slices)
-Offset and cut a Slice (equivalent to self[start:start+length] for calldata slices) +Offset and cut a Slice (equivalent to self[offset:offset+len] for calldata slices)
@@ -3050,13 +3239,47 @@ Extract the data corresponding to a Slice (allocate new memory)
+ + +
+
+

equal(Memory.Slice a, Memory.Slice b) โ†’ bool result

+
+

internal

+# +
+
+
+ +Returns true if the two slices contain the same data. + +
+
+ + + +
+
+

isReserved(Memory.Slice self) โ†’ bool result

+
+

internal

+# +
+
+
+ +Returns true if the memory occupied by the slice is reserved (i.e. before the free memory pointer) + +
+
+
-## `Multicall` +## `Multicall` - + @@ -3107,9 +3330,9 @@ Receives and executes a batch of function calls on this contract.
-## `Nonces` +## `Nonces` - + @@ -3211,9 +3434,9 @@ The nonce used for an `account` is not the expected current nonce.
-## `NoncesKeyed` +## `NoncesKeyed` - + @@ -3240,17 +3463,25 @@ Doing so will NOT reset the current state of nonces, avoiding replay attacks whe - [_useNonce(owner, key)](#NoncesKeyed-_useNonce-address-uint192-) - [_useCheckedNonce(owner, keyNonce)](#NoncesKeyed-_useCheckedNonce-address-uint256-) - [_useCheckedNonce(owner, key, nonce)](#NoncesKeyed-_useCheckedNonce-address-uint192-uint64-) -#### Nonces [!toc] +
+Nonces + - [nonces(owner)](#Nonces-nonces-address-) - [_useNonce(owner)](#Nonces-_useNonce-address-) + +

Errors

-#### Nonces [!toc] +
+Nonces + - [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-) + +
@@ -3335,9 +3566,9 @@ This version takes the key and the nonce as two different parameters.
-## `Packing` +## `Packing` - + @@ -6798,9 +7029,9 @@ _Available since v5.1._
-## `Panic` +## `Panic` - + @@ -6857,9 +7088,9 @@ the internal constants with predefined codes.
-## `Pausable` +## `Pausable` - + @@ -7122,9 +7353,9 @@ The operation failed because the contract is not paused.
-## `RLP` +## `RLP` - + @@ -7143,6 +7374,33 @@ Inspired by * https://github.com/succinctlabs/optimism-bedrock-contracts/blob/main/rlp/RLPWriter.sol * https://github.com/succinctlabs/optimism-bedrock-contracts/blob/main/rlp/RLPReader.sol +## Canonical vs Non-Canonical Encodings + +According to the Ethereum Yellow Paper, a "canonical" RLP encoding is the unique, minimal +representation of a value. For scalar values (integers), this means: + +* No leading zero bytes (e.g., `0x0123` should be encoded as 2 bytes, not `0x000123` as 3 bytes) +* Single bytes less than 0x80 must be encoded directly without a prefix wrapper +* Zero is represented as an empty byte array (prefix `0x80`) + +A "non-canonical" encoding represents the same value but doesn't follow these minimality rules. +For example, encoding the integer 1234 (0x04d2) with a leading zero as `0x830004d2` instead +of the canonical `0x8204d2`. + +[IMPORTANT] +#### This implementation takes a permissive approach to decoding, accepting some non-canonical +encodings (e.g., scalar values with leading zero bytes) that would be rejected by +strict implementations like go-ethereum. This design choice prioritizes compatibility +with diverse RLP encoders in the ecosystem over strict adherence to the Yellow Paper +specification's canonicalization requirements. + +Users should be aware that: + +* Multiple different RLP encodings may decode to the same value (non-injective) +* Encoding followed by decoding is guaranteed to work correctly +* External RLP data from untrusted sources may have non-canonical encodings +* Improperly wrapped single bytes (< 0x80) are still rejected as invalid +

Functions

@@ -7372,7 +7630,10 @@ This follows the de facto ecosystem standard where booleans are treated as 0/1 i
-Encode an address as RLP. +Encode an address as an RLP item of fixed size (20 bytes). + +The address is encoded with its leading zeros (if it has any). If someone wants to encode the address as a scalar, +they can cast it to an uint256 and then call the corresponding [`Base58.encode`](#Base58-encode-bytes-) function.
@@ -7389,7 +7650,9 @@ Encode an address as RLP.
-Encode a uint256 as RLP. +Encode an uint256 as an RLP scalar. + +Unlike `encode-bytes32-`, this function uses scalar encoding that removes the prefix zeros.
@@ -7398,7 +7661,7 @@ Encode a uint256 as RLP.
-

encode(bytes32 input) โ†’ bytes

+

encode(bytes32 input) โ†’ bytes result

internal

# @@ -7406,7 +7669,9 @@ Encode a uint256 as RLP.
-Encode a bytes32 as RLP. Type alias for #RLP-encode-uint256-. +Encode a bytes32 as an RLP item of fixed size (32 bytes). + +Unlike `encode-uint256-`, this function uses array encoding that preserves the prefix zeros.
@@ -7440,7 +7705,7 @@ Encode a bytes buffer as RLP.
-Encode a string as RLP. Type alias for #Base58-encode-bytes-. +Encode a string as RLP. Type alias for `encode-bytes-`.
@@ -7458,6 +7723,8 @@ Encode a string as RLP. Type alias for #Base58-encode-bytes-.
Encode an array of bytes as RLP. +This function expects an array of already encoded bytes, not raw bytes. +Users should call [`Base58.encode`](#Base58-encode-bytes-) on each element of the array before calling it.
@@ -7466,7 +7733,7 @@ Encode an array of bytes as RLP.
-

encode(struct RLP.Encoder self) โ†’ bytes result

+

encode(struct RLP.Encoder self) โ†’ bytes

internal

# @@ -7491,7 +7758,13 @@ Encode an encoder (list of bytes) as RLP
-Decode an RLP encoded bool. See #RLP-encode-bool- +Decode an RLP encoded bool. See `encode-bool` + + +This function treats any non-zero value as `true`, which is more permissive +than some implementations (e.g., go-ethereum only accepts `0x00` for false and `0x01` +for true). For example, `0x02`, `0x03`, etc. will all decode as `true`. +
@@ -7508,7 +7781,16 @@ Decode an RLP encoded bool. See #RLP-encode-bool-
-Decode an RLP encoded address. See #RLP-encode-address- +Decode an RLP encoded address. See `encode-address` + +[NOTE] +#### This function accepts both single-byte encodings (for values 0-127, including +precompile addresses like 0x01) and the standard 21-byte encoding with the `0x94` prefix. +For example, `0x01` decodes to `0x0000000000000000000000000000000000000001`. + +Additionally, like [`RLP.readUint256`](#RLP-readUint256-Memory-Slice-), this function accepts non-canonical encodings with +leading zeros. For instance, both `0x01` and `0x940000000000000000000000000000000000000001` +decode to the same address.
@@ -7525,7 +7807,20 @@ Decode an RLP encoded address. See #RLP-encode-address-
-Decode an RLP encoded uint256. See #RLP-encode-uint256- +Decode an RLP encoded uint256. See `encode-uint256` + +[NOTE] +#### This function accepts non-canonical encodings with leading zero bytes for multi-byte values, +which differs from the Ethereum Yellow Paper specification and some reference +implementations like go-ethereum. For example, both `0x88ab54a98ceb1f0ad2` and +`0x8900ab54a98ceb1f0ad2` will decode to the same uint256 value (12345678901234567890). + +However, single bytes less than 0x80 must NOT be wrapped with a prefix. For example, +`0x8100` is invalid (should be `0x00`), but `0x820000` is valid (two zero bytes). + +This permissive behavior is intentional for compatibility with various RLP encoders +in the ecosystem, but users should be aware that multiple RLP encodings may map +to the same decoded value (non-injective decoding).
@@ -7542,7 +7837,14 @@ Decode an RLP encoded uint256. See #RLP-encode-uint256-
-Decode an RLP encoded bytes32. See #RLP-encode-bytes32- +Decode an RLP encoded bytes32. See `encode-bytes32` + + +Since this function delegates to [`RLP.readUint256`](#RLP-readUint256-Memory-Slice-), it inherits the non-canonical +encoding acceptance behavior for multi-byte values. Multiple RLP encodings with different +leading zero bytes may decode to the same bytes32 value, but single bytes < 0x80 must +not be wrapped with a prefix (e.g., `0x820000` is valid, but `0x8100` is not). +
@@ -7559,7 +7861,7 @@ Decode an RLP encoded bytes32. See #RLP-encode-bytes32-
-Decodes an RLP encoded bytes. See #Base58-encode-bytes- +Decodes an RLP encoded bytes. See `encode-bytes`
@@ -7576,7 +7878,7 @@ Decodes an RLP encoded bytes. See #Base58-encode-bytes-
-Decodes an RLP encoded string. See #RLP-encode-string- +Decodes an RLP encoded string. See `encode-string`
@@ -7593,7 +7895,12 @@ Decodes an RLP encoded string. See #RLP-encode-string-
-Decodes an RLP encoded list into an array of RLP Items. +Decodes an RLP encoded list in a memory slice into an array of RLP Items. + + +The returned array contains slice references into the original payload, not copied bytes. Any further +modification of the input buffer may cause the output result to become invalid. +
@@ -7714,6 +8021,11 @@ Decode an RLP encoded string from bytes. See [`RLP.readString`](#RLP-readString- Decode an RLP encoded list from bytes. See [`RLP.readList`](#RLP-readList-Memory-Slice-) + +The returned array contains slice references into the original payload, not copied bytes. Any further +modification of the input buffer may cause the output result to become invalid. + + @@ -7729,7 +8041,7 @@ Decode an RLP encoded list from bytes. See [`RLP.readList`](#RLP-readList-Memory
-The item is not properly formatted and cannot de decoded. +The item is not properly formatted and cannot be decoded.
@@ -7738,9 +8050,9 @@ The item is not properly formatted and cannot de decoded.
-## `ReentrancyGuard` +## `ReentrancyGuard` - + @@ -7841,9 +8153,11 @@ by making the `nonReentrant` function external, and making it call a A `view` only version of [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--). Use to block view functions from being called, preventing reading from inconsistent contract state. -CAUTION: This is a "view" modifier and does not change the reentrancy + +This is a "view" modifier and does not change the reentrancy status. Use it only on view functions. For payable or non-payable functions, use the standard [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--) modifier instead. +
@@ -7917,9 +8231,9 @@ Unauthorized reentrant call.
-## `ReentrancyGuardTransient` +## `ReentrancyGuardTransient` - + @@ -8000,9 +8314,11 @@ by making the `nonReentrant` function external, and making it call a A `view` only version of [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--). Use to block view functions from being called, preventing reading from inconsistent contract state. -CAUTION: This is a "view" modifier and does not change the reentrancy + +This is a "view" modifier and does not change the reentrancy status. Use it only on view functions. For payable or non-payable functions, use the standard [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--) modifier instead. +
@@ -8061,9 +8377,9 @@ Unauthorized reentrant call.
-## `RelayedCall` +## `RelayedCall` - + @@ -8085,6 +8401,12 @@ the target only sees the unprivileged relay address as `msg.sender`. For example, instead of `target.call(data)` where the target sees this contract as `msg.sender`, use [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-bytes32-) where the target sees a relay address as `msg.sender`. + +This library uses the PUSH0 opcode that was introduced in the Shanghai hardfork. While this instruction is +now widely supported, developers using the library on exotic chains should verify that their target chain has +supports for EIP-3855. + +

Functions

@@ -8101,7 +8423,7 @@ For example, instead of `target.call(data)` where the target sees this contract
-

relayCall(address target, bytes data) โ†’ bool, bytes

+

relayCall(address target, bytes data) โ†’ bool success, bytes retData

internal

# @@ -8118,7 +8440,7 @@ Relays a call to the target contract through a dynamically deployed relay contra
-

relayCall(address target, uint256 value, bytes data) โ†’ bool, bytes

+

relayCall(address target, uint256 value, bytes data) โ†’ bool success, bytes retData

internal

# @@ -8126,7 +8448,7 @@ Relays a call to the target contract through a dynamically deployed relay contra
-Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-bytes32-) but with a value. +Same as `relayCall-address-bytes` but with a value.
@@ -8135,7 +8457,7 @@ Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-b
-

relayCall(address target, bytes data, bytes32 salt) โ†’ bool, bytes

+

relayCall(address target, bytes data, bytes32 salt) โ†’ bool success, bytes retData

internal

# @@ -8143,7 +8465,7 @@ Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-b
-Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-bytes32-) but with a salt. +Same as `relayCall-address-bytes` but with a salt.
@@ -8152,7 +8474,7 @@ Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-b
-

relayCall(address target, uint256 value, bytes data, bytes32 salt) โ†’ bool, bytes

+

relayCall(address target, uint256 value, bytes data, bytes32 salt) โ†’ bool success, bytes retData

internal

# @@ -8160,7 +8482,7 @@ Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-b
-Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-bytes32-) but with a salt and a value. +Same as `relayCall-address-bytes` but with a salt and a value.
@@ -8203,9 +8525,9 @@ Returns the relayer address for a given salt.
-## `ShortString` +## `ShortString` - + @@ -8219,9 +8541,9 @@ import "@openzeppelin/contracts/utils/ShortStrings.sol";
-## `ShortStrings` +## `ShortStrings` - + @@ -8418,36 +8740,125 @@ actual characters as the UTF-8 encoding of a single character can span over mult
- +
-## `SlotDerivation` +## `SimulateCall` - +
```solidity -import "@openzeppelin/contracts/utils/SlotDerivation.sol"; +import "@openzeppelin/contracts/utils/SimulateCall.sol"; ``` -Library for computing storage (and transient storage) locations from namespaces and deriving slots -corresponding to standard patterns. The derivation method for array and mapping matches the storage layout used by -the solidity language / compiler. - -See [Solidity docs for mappings and dynamic arrays.](https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_storage.html#mappings-and-dynamic-arrays). +Library for simulating external calls and inspecting the result of the call while reverting any state changes +of events the call may have produced. -Example usage: -```solidity -contract Example { - // Add the library methods - using StorageSlot for bytes32; - using SlotDerivation for *; +This pattern is useful when you need to simulate the result of a call without actually executing it on-chain. Since +the address of the sender is preserved, this supports simulating calls that perform token swap that use the caller's +balance, or any operation that is restricted to the caller. - // Declare a namespace +
+

Functions

+
+- [simulateCall(target, data)](#SimulateCall-simulateCall-address-bytes-) +- [simulateCall(target, value, data)](#SimulateCall-simulateCall-address-uint256-bytes-) +- [getSimulator()](#SimulateCall-getSimulator--) +
+
+ + + +
+
+

simulateCall(address target, bytes data) โ†’ bool success, bytes retData

+
+

internal

+# +
+
+
+ +Simulates a call to the target contract through a dynamically deployed simulator. + +
+
+ + + +
+
+

simulateCall(address target, uint256 value, bytes data) โ†’ bool success, bytes retData

+
+

internal

+# +
+
+
+ +Same as `simulateCall-address-bytes` but with a value. + +
+
+ + + +
+
+

getSimulator() โ†’ address instance

+
+

internal

+# +
+
+
+ +Returns the simulator address. + +The simulator REVERTs on success and RETURNs on failure, preserving the return data in both cases. + +* A failed target call returns the return data and succeeds in our context (no state changes). +* A successful target call causes a revert in our context (undoing all state changes) while still +capturing the return data. + +
+
+ + + +
+ +## `SlotDerivation` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/utils/SlotDerivation.sol"; +``` + +Library for computing storage (and transient storage) locations from namespaces and deriving slots +corresponding to standard patterns. The derivation method for array and mapping matches the storage layout used by +the solidity language / compiler. + +See [Solidity docs for mappings and dynamic arrays.](https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_storage.html#mappings-and-dynamic-arrays). + +Example usage: +```solidity +contract Example { + // Add the library methods + using StorageSlot for bytes32; + using SlotDerivation for *; + + // Declare a namespace string private constant _NAMESPACE = ""; // eg. OpenZeppelin.Slot function setValueInNamespace(uint256 key, address newValue) internal { @@ -8661,9 +9072,9 @@ Derive the location of a mapping element from the key.
-## `StorageSlot` +## `StorageSlot` - + @@ -8873,9 +9284,9 @@ Returns an `BytesSlot` representation of the bytes storage pointer `store`.
-## `Strings` +## `Strings` - + @@ -9098,7 +9509,7 @@ Requirements:
-Variant of #Strings-parseUint-string- that parses a substring of `input` located between position `begin` (included) and +Variant of `parseUint-string` that parses a substring of `input` located between position `begin` (included) and `end` (excluded). Requirements: @@ -9120,7 +9531,7 @@ Requirements:
-Variant of #Strings-parseUint-string- that returns false if the parsing fails because of an invalid character. +Variant of `parseUint-string` that returns false if the parsing fails because of an invalid character. This function will revert if the result does not fit in a `uint256`. @@ -9141,7 +9552,7 @@ This function will revert if the result does not fit in a `uint256`.
-Variant of #Strings-parseUint-string-uint256-uint256- that returns false if the parsing fails because of an invalid +Variant of `parseUint-string-uint256-uint256` that returns false if the parsing fails because of an invalid character. @@ -9184,7 +9595,7 @@ Requirements:
-Variant of #Strings-parseInt-string- that parses a substring of `input` located between position `begin` (included) and +Variant of `parseInt-string` that parses a substring of `input` located between position `begin` (included) and `end` (excluded). Requirements: @@ -9206,7 +9617,7 @@ Requirements:
-Variant of #Strings-parseInt-string- that returns false if the parsing fails because of an invalid character or if +Variant of `parseInt-string` that returns false if the parsing fails because of an invalid character or if the result does not fit in a `int256`. @@ -9228,7 +9639,7 @@ This function will revert if the absolute value of the result does not fit in a
-Variant of #Strings-parseInt-string-uint256-uint256- that returns false if the parsing fails because of an invalid +Variant of `parseInt-string-uint256-uint256` that returns false if the parsing fails because of an invalid character or if the result does not fit in a `int256`. @@ -9271,7 +9682,7 @@ Requirements:
-Variant of #Strings-parseHexUint-string- that parses a substring of `input` located between position `begin` (included) and +Variant of `parseHexUint-string` that parses a substring of `input` located between position `begin` (included) and `end` (excluded). Requirements: @@ -9293,7 +9704,7 @@ Requirements:
-Variant of #Strings-parseHexUint-string- that returns false if the parsing fails because of an invalid character. +Variant of `parseHexUint-string` that returns false if the parsing fails because of an invalid character. This function will revert if the result does not fit in a `uint256`. @@ -9314,7 +9725,7 @@ This function will revert if the result does not fit in a `uint256`.
-Variant of #Strings-parseHexUint-string-uint256-uint256- that returns false if the parsing fails because of an +Variant of `parseHexUint-string-uint256-uint256` that returns false if the parsing fails because of an invalid character. @@ -9339,7 +9750,7 @@ This function will revert if the result does not fit in a `uint256`. Parse a hexadecimal string (with or without "0x" prefix), and returns the value as an `address`. Requirements: -- The string must be formatted as `(0x)?[0-9a-fA-F][`SafeCast.toUint240`](#SafeCast-toUint240-uint256-)` +- The string must be formatted as `(0x)?[0-9a-fA-F]`40``
@@ -9356,11 +9767,11 @@ Requirements:
-Variant of #Strings-parseAddress-string- that parses a substring of `input` located between position `begin` (included) and +Variant of `parseAddress-string` that parses a substring of `input` located between position `begin` (included) and `end` (excluded). Requirements: -- The substring must be formatted as `(0x)?[0-9a-fA-F][`SafeCast.toUint240`](#SafeCast-toUint240-uint256-)` +- The substring must be formatted as `(0x)?[0-9a-fA-F]`40``
@@ -9377,8 +9788,8 @@ Requirements:
-Variant of #Strings-parseAddress-string- that returns false if the parsing fails because the input is not a properly -formatted address. See #Strings-parseAddress-string- requirements. +Variant of `parseAddress-string` that returns false if the parsing fails because the input is not a properly +formatted address. See `parseAddress-string` requirements.
@@ -9395,8 +9806,8 @@ formatted address. See #Strings-parseAddress-string- requirements.
-Variant of #Strings-parseAddress-string-uint256-uint256- that returns false if the parsing fails because input is not a properly -formatted address. See #Strings-parseAddress-string-uint256-uint256- requirements. +Variant of `parseAddress-string-uint256-uint256` that returns false if the parsing fails because input is not a properly +formatted address. See `parseAddress-string-uint256-uint256` requirements.
@@ -9420,9 +9831,10 @@ This function should only be used in double quoted JSON strings. Single quotes a -This function escapes all unicode characters, and not just the ones in ranges defined in section 2.5 of -RFC-4627 (U+0000 to U+001F, U+0022 and U+005C). ECMAScript's `JSON.parse` does recover escaped unicode -characters that are not in this range, but other tooling may provide different results. +This function escapes backslashes (including those in \uXXXX sequences) and the characters in ranges +defined in section 2.5 of RFC-4627 (U+0000 to U+001F, U+0022 and U+005C). All control characters in U+0000 +to U+001F are escaped (\b, \t, \n, \f, \r use short form; others use \u00XX). ECMAScript's `JSON.parse` does +recover escaped unicode characters that are not in this range, but other tooling may provide different results.
@@ -9483,9 +9895,9 @@ The string being parsed is not a properly formatted address.
-## `TransientSlot` +## `TransientSlot` - + @@ -9802,9 +10214,9 @@ Store `value` at location `slot` in transient storage.
-## `InteroperableAddress` +## `InteroperableAddress` - + @@ -9874,7 +10286,7 @@ ERC-7930, including interoperable addresses with empty chain reference or empty
-Variant of #InteroperableAddress-formatV1-bytes2-bytes-bytes- specific to EVM chains. Returns the ERC-7930 interoperable +Variant of `formatV1-bytes2-bytes-bytes-` specific to EVM chains. Returns the ERC-7930 interoperable address (version 1) for a given chainid and ethereum address.
@@ -9892,7 +10304,7 @@ address (version 1) for a given chainid and ethereum address.
-Variant of #InteroperableAddress-formatV1-bytes2-bytes-bytes- that specifies an EVM chain without an address. +Variant of `formatV1-bytes2-bytes-bytes-` that specifies an EVM chain without an address.
@@ -9909,7 +10321,7 @@ Variant of #InteroperableAddress-formatV1-bytes2-bytes-bytes- that specifies an
-Variant of #InteroperableAddress-formatV1-bytes2-bytes-bytes- that specifies an EVM address without a chain reference. +Variant of `formatV1-bytes2-bytes-bytes-` that specifies an EVM address without a chain reference.
@@ -9927,7 +10339,12 @@ Variant of #InteroperableAddress-formatV1-bytes2-bytes-bytes- that specifies an
Parse a ERC-7930 interoperable address (version 1) into its different components. Reverts if the input is -not following a version 1 of ERC-7930 +not following a version 1 of ERC-7930. + + +Trailing bytes after a valid v1 encoding are ignored. The same decoded address may therefore correspond +to multiple distinct input byte strings. +
@@ -9999,6 +10416,11 @@ Variant of [`InteroperableAddress.tryParseV1`](#InteroperableAddress-tryParseV1- Parse a ERC-7930 interoperable address (version 1) corresponding to an EIP-155 chain. The `chainId` and `addr` return values will be zero if the input doesn't include a chainReference or an address, respectively. + +Trailing bytes after a valid v1 encoding are ignored. The same decoded (chainId, addr) may therefore +correspond to multiple distinct input byte strings. + + Requirements: * The input must be a valid ERC-7930 interoperable address (version 1) @@ -10093,9 +10515,9 @@ Variant of [`InteroperableAddress.tryParseEvmV1`](#InteroperableAddress-tryParse
-## `ERC165` +## `ERC165` - + @@ -10107,7 +10529,7 @@ import "@openzeppelin/contracts/utils/introspection/ERC165.sol"; Implementation of the [`IERC165`](#IERC165) interface. -Contracts that want to implement ERC-165 should inherit from this contract and override [`AccessControl.supportsInterface`](/contracts/5.x/api/access#AccessControl-supportsInterface-bytes4-) to check +Contracts that want to implement ERC-165 should inherit from this contract and override [`ERC165.supportsInterface`](#ERC165-supportsInterface-bytes4-) to check for the additional interface id that will be supported. For example: ```solidity @@ -10120,7 +10542,6 @@ function supportsInterface(bytes4 interfaceId) public view virtual override retu

Functions

- [supportsInterface(interfaceId)](#ERC165-supportsInterface-bytes4-) -#### IERC165 [!toc]
@@ -10150,9 +10571,9 @@ This function call must use less than 30 000 gas.
-## `ERC165Checker` +## `ERC165Checker` - + @@ -10289,9 +10710,9 @@ Interface identification is specified in ERC-165.
-## `IERC165` +## `IERC165` - + @@ -10342,9 +10763,9 @@ This function call must use less than 30 000 gas.
-## `Math` +## `Math` - + @@ -11065,9 +11486,9 @@ Counts the number of leading zero bits in a uint256.
-## `SafeCast` +## `SafeCast` - + @@ -12759,7 +13180,7 @@ Cast a boolean (false or true) to a uint256 (0 or 1) with no jump.
-Value doesn't fit in an uint of `bits` size. +Value doesn't fit in a uint of `bits` size.
@@ -12776,7 +13197,7 @@ Value doesn't fit in an uint of `bits` size.
-An int value doesn't fit in an uint of `bits` size. +An int value doesn't fit in a uint of `bits` size.
@@ -12810,7 +13231,7 @@ Value doesn't fit in an int of `bits` size.
-An uint value doesn't fit in an int of `bits` size. +A uint value doesn't fit in an int of `bits` size.
@@ -12819,9 +13240,9 @@ An uint value doesn't fit in an int of `bits` size.
-## `SignedMath` +## `SignedMath` - + @@ -12940,9 +13361,9 @@ Returns the absolute unsigned value of a signed value.
-## `Accumulators` +## `Accumulators` - + @@ -12960,14 +13381,14 @@ to existing data and performs a single memory allocation during flattening (O(n) Uses 0x00 as sentinel value for empty state (i.e. null pointers) -==== How it works +#### How it works 1. Create an empty accumulator with null head/tail pointers 2. Add data using [`RLP.push`](#RLP-push-struct-RLP-Encoder-struct-RLP-Encoder-) (append) or [`Accumulators.shift`](#Accumulators-shift-struct-Accumulators-Accumulator-Memory-Slice-) (prepend). It creates linked list nodes 3. Each node stores a reference to existing data (no copying) 4. Call [`Accumulators.flatten`](#Accumulators-flatten-struct-Accumulators-Accumulator-) to materialize the final concatenated result in a single operation -==== Performance +#### Performance * Addition: O(1) per operation (just pointer manipulation) * Flattening: O(n) single pass with one memory allocation @@ -13091,9 +13512,9 @@ Flatten all the bytes entries in an Accumulator into a single buffer
-## `BitMaps` +## `BitMaps` - + @@ -13197,9 +13618,9 @@ Unsets the bit at `index`.
-## `Checkpoints` +## `Checkpoints` - + @@ -13889,9 +14310,9 @@ A value was attempted to be inserted on a past checkpoint.
-## `CircularBuffer` +## `CircularBuffer` - + @@ -13910,6 +14331,7 @@ structure. Elements can't be removed but the data structure can be cleared. See [`CircularBuffer.clear`](#CircularBuffer-clear-struct-CircularBuffer-Bytes32CircularBuffer-). Complexity: + - insertion ([`RLP.push`](#RLP-push-struct-RLP-Encoder-struct-RLP-Encoder-)): O(1) - lookup ([`CircularBuffer.last`](#CircularBuffer-last-struct-CircularBuffer-Bytes32CircularBuffer-uint256-)): O(1) - inclusion ([`CircularBuffer.includes`](#CircularBuffer-includes-struct-CircularBuffer-Bytes32CircularBuffer-bytes32-)): O(N) (worst case) @@ -13927,9 +14349,21 @@ contract Example { // Declare a buffer storage variable CircularBuffer.Bytes32CircularBuffer private myBuffer; + + constructor() { + myBuffer.setup(16); // Initialize the buffer with a non-zero fixed size (e.g., 16) + } + + function pushValue(bytes32 value) external { + myBuffer.push(value); // Safe to push because the buffer was initialized in the constructor + } } ``` + +Make sure to call [`CircularBuffer.setup`](#CircularBuffer-setup-struct-CircularBuffer-Bytes32CircularBuffer-uint256-) on your buffer during construction/initialization + + _Available since v5.1._
@@ -14104,9 +14538,9 @@ Error emitted when trying to setup a buffer with a size of 0.
-## `DoubleEndedQueue` +## `DoubleEndedQueue` - + @@ -14131,12 +14565,19 @@ DoubleEndedQueue.Bytes32Deque queue;

Functions

- [pushBack(deque, value)](#DoubleEndedQueue-pushBack-struct-DoubleEndedQueue-Bytes32Deque-bytes32-) +- [tryPushBack(deque, value)](#DoubleEndedQueue-tryPushBack-struct-DoubleEndedQueue-Bytes32Deque-bytes32-) - [popBack(deque)](#DoubleEndedQueue-popBack-struct-DoubleEndedQueue-Bytes32Deque-) +- [tryPopBack(deque)](#DoubleEndedQueue-tryPopBack-struct-DoubleEndedQueue-Bytes32Deque-) - [pushFront(deque, value)](#DoubleEndedQueue-pushFront-struct-DoubleEndedQueue-Bytes32Deque-bytes32-) +- [tryPushFront(deque, value)](#DoubleEndedQueue-tryPushFront-struct-DoubleEndedQueue-Bytes32Deque-bytes32-) - [popFront(deque)](#DoubleEndedQueue-popFront-struct-DoubleEndedQueue-Bytes32Deque-) +- [tryPopFront(deque)](#DoubleEndedQueue-tryPopFront-struct-DoubleEndedQueue-Bytes32Deque-) - [front(deque)](#DoubleEndedQueue-front-struct-DoubleEndedQueue-Bytes32Deque-) +- [tryFront(deque)](#DoubleEndedQueue-tryFront-struct-DoubleEndedQueue-Bytes32Deque-) - [back(deque)](#DoubleEndedQueue-back-struct-DoubleEndedQueue-Bytes32Deque-) +- [tryBack(deque)](#DoubleEndedQueue-tryBack-struct-DoubleEndedQueue-Bytes32Deque-) - [at(deque, index)](#DoubleEndedQueue-at-struct-DoubleEndedQueue-Bytes32Deque-uint256-) +- [tryAt(deque, index)](#DoubleEndedQueue-tryAt-struct-DoubleEndedQueue-Bytes32Deque-uint256-) - [clear(deque)](#DoubleEndedQueue-clear-struct-DoubleEndedQueue-Bytes32Deque-) - [length(deque)](#DoubleEndedQueue-length-struct-DoubleEndedQueue-Bytes32Deque-) - [empty(deque)](#DoubleEndedQueue-empty-struct-DoubleEndedQueue-Bytes32Deque-) @@ -14162,11 +14603,30 @@ Reverts with [`Panic.RESOURCE_ERROR`](#Panic-RESOURCE_ERROR-uint256) if the queu
+ + +
+
+

tryPushBack(struct DoubleEndedQueue.Bytes32Deque deque, bytes32 value) โ†’ bool success

+
+

internal

+# +
+
+
+ +Attempts to insert an item at the end of the queue. + +Returns `false` if the queue is full. Never reverts. + +
+
+
-

popBack(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bytes32 value

+

popBack(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bytes32

internal

# @@ -14181,6 +14641,25 @@ Reverts with [`Panic.EMPTY_ARRAY_POP`](#Panic-EMPTY_ARRAY_POP-uint256) if the qu
+ + +
+
+

tryPopBack(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bool success, bytes32 value

+
+

internal

+# +
+
+
+ +Attempts to remove the item at the end of the queue and return it. + +Returns `(false, 0x00)` if the queue is empty. Never reverts. + +
+
+
@@ -14200,11 +14679,30 @@ Reverts with [`Panic.RESOURCE_ERROR`](#Panic-RESOURCE_ERROR-uint256) if the queu
+ + +
+
+

tryPushFront(struct DoubleEndedQueue.Bytes32Deque deque, bytes32 value) โ†’ bool success

+
+

internal

+# +
+
+
+ +Attempts to insert an item at the beginning of the queue. + +Returns `false` if the queue is full. Never reverts. + +
+
+
-

popFront(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bytes32 value

+

popFront(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bytes32

internal

# @@ -14219,11 +14717,31 @@ Reverts with [`Panic.EMPTY_ARRAY_POP`](#Panic-EMPTY_ARRAY_POP-uint256) if the qu
+ + +
+
+

tryPopFront(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bool success, bytes32 value

+
+

internal

+# +
+
+
+ +Attempts to remove the item at the beginning of the queue and +return it. + +Returns `(false, 0x00)` if the queue is empty. Never reverts. + +
+
+
-

front(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bytes32 value

+

front(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bytes32

internal

# @@ -14238,11 +14756,30 @@ Reverts with [`Panic.ARRAY_OUT_OF_BOUNDS`](#Panic-ARRAY_OUT_OF_BOUNDS-uint256) i
+ + +
+
+

tryFront(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bool success, bytes32 value

+
+

internal

+# +
+
+
+ +Attempts to return the item at the beginning of the queue. + +Returns `(false, 0x00)` if the queue is empty. Never reverts. + +
+
+
-

back(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bytes32 value

+

back(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bytes32

internal

# @@ -14257,11 +14794,30 @@ Reverts with [`Panic.ARRAY_OUT_OF_BOUNDS`](#Panic-ARRAY_OUT_OF_BOUNDS-uint256) i
+ + +
+
+

tryBack(struct DoubleEndedQueue.Bytes32Deque deque) โ†’ bool success, bytes32 value

+
+

internal

+# +
+
+
+ +Attempts to return the item at the end of the queue. + +Returns `(false, 0x00)` if the queue is empty. Never reverts. + +
+
+
-

at(struct DoubleEndedQueue.Bytes32Deque deque, uint256 index) โ†’ bytes32 value

+

at(struct DoubleEndedQueue.Bytes32Deque deque, uint256 index) โ†’ bytes32

internal

# @@ -14277,6 +14833,26 @@ Reverts with [`Panic.ARRAY_OUT_OF_BOUNDS`](#Panic-ARRAY_OUT_OF_BOUNDS-uint256) i
+ + +
+
+

tryAt(struct DoubleEndedQueue.Bytes32Deque deque, uint256 index) โ†’ bool success, bytes32 value

+
+

internal

+# +
+
+
+ +Attempts to return the item at a position in the queue given by `index`, with the first item at +0 and the last item at `length(deque) - 1`. + +Returns `(false, 0x00)` if the index is out of bounds. Never reverts. + +
+
+
@@ -14337,9 +14913,9 @@ Returns true if the queue is empty.
-## `EnumerableMap` +## `EnumerableMap` - + @@ -14382,15 +14958,15 @@ The following map types are supported: - `address -> bytes32` (`AddressToBytes32Map`) since v5.1.0 - `bytes32 -> address` (`Bytes32ToAddressMap`) since v5.1.0 - `bytes -> bytes` (`BytesToBytesMap`) since v5.4.0 +- `bytes4 -> address` (`Bytes4ToAddressMap`) since v5.6.0 - -Trying to delete such a structure from storage will likely result in data corruption, rendering the structure +[WARNING] +#### Trying to delete such a structure from storage will likely result in data corruption, rendering the structure unusable. See [ethereum/solidity#11843](https://github.com/ethereum/solidity/pull/11843) for more info. In order to clean an EnumerableMap, you can either remove all elements one by one or create a fresh instance using an array of EnumerableMap. -

Functions

@@ -14485,6 +15061,16 @@ array of EnumerableMap. - [get(map, key)](#EnumerableMap-get-struct-EnumerableMap-Bytes32ToAddressMap-bytes32-) - [keys(map)](#EnumerableMap-keys-struct-EnumerableMap-Bytes32ToAddressMap-) - [keys(map, start, end)](#EnumerableMap-keys-struct-EnumerableMap-Bytes32ToAddressMap-uint256-uint256-) +- [set(map, key, value)](#EnumerableMap-set-struct-EnumerableMap-Bytes4ToAddressMap-bytes4-address-) +- [remove(map, key)](#EnumerableMap-remove-struct-EnumerableMap-Bytes4ToAddressMap-bytes4-) +- [clear(map)](#EnumerableMap-clear-struct-EnumerableMap-Bytes4ToAddressMap-) +- [contains(map, key)](#EnumerableMap-contains-struct-EnumerableMap-Bytes4ToAddressMap-bytes4-) +- [length(map)](#EnumerableMap-length-struct-EnumerableMap-Bytes4ToAddressMap-) +- [at(map, index)](#EnumerableMap-at-struct-EnumerableMap-Bytes4ToAddressMap-uint256-) +- [tryGet(map, key)](#EnumerableMap-tryGet-struct-EnumerableMap-Bytes4ToAddressMap-bytes4-) +- [get(map, key)](#EnumerableMap-get-struct-EnumerableMap-Bytes4ToAddressMap-bytes4-) +- [keys(map)](#EnumerableMap-keys-struct-EnumerableMap-Bytes4ToAddressMap-) +- [keys(map, start, end)](#EnumerableMap-keys-struct-EnumerableMap-Bytes4ToAddressMap-uint256-uint256-) - [set(map, key, value)](#EnumerableMap-set-struct-EnumerableMap-BytesToBytesMap-bytes-bytes-) - [remove(map, key)](#EnumerableMap-remove-struct-EnumerableMap-BytesToBytesMap-bytes-) - [clear(map)](#EnumerableMap-clear-struct-EnumerableMap-BytesToBytesMap-) @@ -16369,14 +16955,14 @@ uncallable if the map grows to a point where copying to memory consumes too much
- +
-

set(struct EnumerableMap.BytesToBytesMap map, bytes key, bytes value) โ†’ bool

+

set(struct EnumerableMap.Bytes4ToAddressMap map, bytes4 key, address value) โ†’ bool

internal

-# +#
@@ -16390,33 +16976,33 @@ already present.
- +
-

remove(struct EnumerableMap.BytesToBytesMap map, bytes key) โ†’ bool

+

remove(struct EnumerableMap.Bytes4ToAddressMap map, bytes4 key) โ†’ bool

internal

-# +#
-Removes a key-value pair from a map. O(1). +Removes a value from a map. O(1). Returns true if the key was removed from the map, that is if it was present.
- +
-

clear(struct EnumerableMap.BytesToBytesMap map)

+

clear(struct EnumerableMap.Bytes4ToAddressMap map)

internal

-# +#
@@ -16424,21 +17010,22 @@ Returns true if the key was removed from the map, that is if it was present. Removes all the entries from a map. O(n). -Developers should keep in mind that this function has an unbounded cost and using it may render the -function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block. +This function has an unbounded cost that scales with map size. Developers should keep in mind that +using it may render the function uncallable if the map grows to the point where clearing it consumes too much +gas to fit in a block.
- +
-

contains(struct EnumerableMap.BytesToBytesMap map, bytes key) โ†’ bool

+

contains(struct EnumerableMap.Bytes4ToAddressMap map, bytes4 key) โ†’ bool

internal

-# +#
@@ -16448,39 +17035,38 @@ Returns true if the key is in the map. O(1).
- +
-

length(struct EnumerableMap.BytesToBytesMap map) โ†’ uint256

+

length(struct EnumerableMap.Bytes4ToAddressMap map) โ†’ uint256

internal

-# +#
-Returns the number of key-value pairs in the map. O(1). +Returns the number of elements in the map. O(1).
- +
-

at(struct EnumerableMap.BytesToBytesMap map, uint256 index) โ†’ bytes key, bytes value

+

at(struct EnumerableMap.Bytes4ToAddressMap map, uint256 index) โ†’ bytes4 key, address value

internal

-# +#
-Returns the key-value pair stored at position `index` in the map. O(1). - -Note that there are no guarantees on the ordering of entries inside the -array, and it may change when more entries are added or removed. +Returns the element stored at position `index` in the map. O(1). +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. Requirements: @@ -16489,14 +17075,14 @@ Requirements:
- +
-

tryGet(struct EnumerableMap.BytesToBytesMap map, bytes key) โ†’ bool exists, bytes value

+

tryGet(struct EnumerableMap.Bytes4ToAddressMap map, bytes4 key) โ†’ bool exists, address value

internal

-# +#
@@ -16507,14 +17093,14 @@ Does not revert if `key` is not in the map.
- +
-

get(struct EnumerableMap.BytesToBytesMap map, bytes key) โ†’ bytes value

+

get(struct EnumerableMap.Bytes4ToAddressMap map, bytes4 key) โ†’ address

internal

-# +#
@@ -16528,14 +17114,14 @@ Requirements:
- +
-

keys(struct EnumerableMap.BytesToBytesMap map) โ†’ bytes[]

+

keys(struct EnumerableMap.Bytes4ToAddressMap map) โ†’ bytes4[]

internal

-# +#
@@ -16552,14 +17138,14 @@ uncallable if the map grows to a point where copying to memory consumes too much
- +
-

keys(struct EnumerableMap.BytesToBytesMap map, uint256 start, uint256 end) โ†’ bytes[]

+

keys(struct EnumerableMap.Bytes4ToAddressMap map, uint256 start, uint256 end) โ†’ bytes4[]

internal

-# +#
@@ -16576,32 +17162,239 @@ uncallable if the map grows to a point where copying to memory consumes too much
- +
-

EnumerableMapNonexistentKey(bytes32 key)

+

set(struct EnumerableMap.BytesToBytesMap map, bytes key, bytes value) โ†’ bool

-

error

-# +

internal

+#
-Query for a nonexistent map key. +Adds a key-value pair to a map, or updates the value for an existing +key. O(1). + +Returns true if the key was added to the map, that is if it was not +already present.
- +
-

EnumerableMapNonexistentBytesKey(bytes key)

+

remove(struct EnumerableMap.BytesToBytesMap map, bytes key) โ†’ bool

-

error

-# -
+

internal

+# +
+
+
+ +Removes a key-value pair from a map. O(1). + +Returns true if the key was removed from the map, that is if it was present. + +
+
+ + + +
+
+

clear(struct EnumerableMap.BytesToBytesMap map)

+
+

internal

+# +
+
+
+ +Removes all the entries from a map. O(n). + + +Developers should keep in mind that this function has an unbounded cost and using it may render the +function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block. + + +
+
+ + + +
+
+

contains(struct EnumerableMap.BytesToBytesMap map, bytes key) โ†’ bool

+
+

internal

+# +
+
+
+ +Returns true if the key is in the map. O(1). + +
+
+ + + +
+
+

length(struct EnumerableMap.BytesToBytesMap map) โ†’ uint256

+
+

internal

+# +
+
+
+ +Returns the number of key-value pairs in the map. O(1). + +
+
+ + + +
+
+

at(struct EnumerableMap.BytesToBytesMap map, uint256 index) โ†’ bytes key, bytes value

+
+

internal

+# +
+
+
+ +Returns the key-value pair stored at position `index` in the map. O(1). + +Note that there are no guarantees on the ordering of entries inside the +array, and it may change when more entries are added or removed. + +Requirements: + +- `index` must be strictly less than [`Memory.length`](#Memory-length-Memory-Slice-). + +
+
+ + + +
+
+

tryGet(struct EnumerableMap.BytesToBytesMap map, bytes key) โ†’ bool exists, bytes value

+
+

internal

+# +
+
+
+ +Tries to return the value associated with `key`. O(1). +Does not revert if `key` is not in the map. + +
+
+ + + +
+
+

get(struct EnumerableMap.BytesToBytesMap map, bytes key) โ†’ bytes value

+
+

internal

+# +
+
+
+ +Returns the value associated with `key`. O(1). + +Requirements: + +- `key` must be in the map. + +
+
+ + + +
+
+

keys(struct EnumerableMap.BytesToBytesMap map) โ†’ bytes[]

+
+

internal

+# +
+
+
+ +Returns an array containing all the keys + + +This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + + +
+
+ + + +
+
+

keys(struct EnumerableMap.BytesToBytesMap map, uint256 start, uint256 end) โ†’ bytes[]

+
+

internal

+# +
+
+
+ +Returns an array containing a slice of the keys + + +This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + + +
+
+ + + +
+
+

EnumerableMapNonexistentKey(bytes32 key)

+
+

error

+# +
+
+
+ +Query for a nonexistent map key. + +
+
+ + + +
+
+

EnumerableMapNonexistentBytesKey(bytes key)

+
+

error

+# +
@@ -16614,9 +17407,9 @@ Query for a nonexistent map key.
-## `EnumerableSet` +## `EnumerableSet` - + @@ -16654,15 +17447,15 @@ The following types are supported: - `uint256` (`UintSet`) since v3.3.0 - `string` (`StringSet`) since v5.4.0 - `bytes` (`BytesSet`) since v5.4.0 +- `bytes4` (`Bytes4Set`) since v5.6.0 - -Trying to delete such a structure from storage will likely result in data corruption, rendering the structure +[WARNING] +#### Trying to delete such a structure from storage will likely result in data corruption, rendering the structure unusable. See [ethereum/solidity#11843](https://github.com/ethereum/solidity/pull/11843) for more info. In order to clean an EnumerableSet, you can either remove all elements one by one or create a fresh instance using an array of EnumerableSet. -

Functions

@@ -16675,6 +17468,14 @@ array of EnumerableSet. - [at(set, index)](#EnumerableSet-at-struct-EnumerableSet-Bytes32Set-uint256-) - [values(set)](#EnumerableSet-values-struct-EnumerableSet-Bytes32Set-) - [values(set, start, end)](#EnumerableSet-values-struct-EnumerableSet-Bytes32Set-uint256-uint256-) +- [add(set, value)](#EnumerableSet-add-struct-EnumerableSet-Bytes4Set-bytes4-) +- [remove(set, value)](#EnumerableSet-remove-struct-EnumerableSet-Bytes4Set-bytes4-) +- [clear(set)](#EnumerableSet-clear-struct-EnumerableSet-Bytes4Set-) +- [contains(set, value)](#EnumerableSet-contains-struct-EnumerableSet-Bytes4Set-bytes4-) +- [length(set)](#EnumerableSet-length-struct-EnumerableSet-Bytes4Set-) +- [at(set, index)](#EnumerableSet-at-struct-EnumerableSet-Bytes4Set-uint256-) +- [values(set)](#EnumerableSet-values-struct-EnumerableSet-Bytes4Set-) +- [values(set, start, end)](#EnumerableSet-values-struct-EnumerableSet-Bytes4Set-uint256-uint256-) - [add(set, value)](#EnumerableSet-add-struct-EnumerableSet-AddressSet-address-) - [remove(set, value)](#EnumerableSet-remove-struct-EnumerableSet-AddressSet-address-) - [clear(set)](#EnumerableSet-clear-struct-EnumerableSet-AddressSet-) @@ -16878,6 +17679,174 @@ uncallable if the set grows to a point where copying to memory consumes too much
+ + +
+
+

add(struct EnumerableSet.Bytes4Set set, bytes4 value) โ†’ bool

+
+

internal

+# +
+
+
+ +Add a value to a set. O(1). + +Returns true if the value was added to the set, that is if it was not +already present. + +
+
+ + + +
+
+

remove(struct EnumerableSet.Bytes4Set set, bytes4 value) โ†’ bool

+
+

internal

+# +
+
+
+ +Removes a value from a set. O(1). + +Returns true if the value was removed from the set, that is if it was +present. + +
+
+ + + +
+
+

clear(struct EnumerableSet.Bytes4Set set)

+
+

internal

+# +
+
+
+ +Removes all the values from a set. O(n). + + +Developers should keep in mind that this function has an unbounded cost and using it may render the +function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block. + + +
+
+ + + +
+
+

contains(struct EnumerableSet.Bytes4Set set, bytes4 value) โ†’ bool

+
+

internal

+# +
+
+
+ +Returns true if the value is in the set. O(1). + +
+
+ + + +
+
+

length(struct EnumerableSet.Bytes4Set set) โ†’ uint256

+
+

internal

+# +
+
+
+ +Returns the number of values in the set. O(1). + +
+
+ + + +
+
+

at(struct EnumerableSet.Bytes4Set set, uint256 index) โ†’ bytes4

+
+

internal

+# +
+
+
+ +Returns the value stored at position `index` in the set. O(1). + +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. + +Requirements: + +- `index` must be strictly less than [`Memory.length`](#Memory-length-Memory-Slice-). + +
+
+ + + +
+
+

values(struct EnumerableSet.Bytes4Set set) โ†’ bytes4[]

+
+

internal

+# +
+
+
+ +Return the entire set in an array + + +This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + + +
+
+ + + +
+
+

values(struct EnumerableSet.Bytes4Set set, uint256 start, uint256 end) โ†’ bytes4[]

+
+

internal

+# +
+
+
+ +Return a slice of the set in an array + + +This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + + +
+
+
@@ -17554,9 +18523,9 @@ uncallable if the set grows to a point where copying to memory consumes too much
-## `Heap` +## `Heap` - + @@ -17573,9 +18542,10 @@ Heaps are represented as a tree of values where the first element (index 0) is t index i is the child of the node at index (i-1)/2 and the parent of nodes at index 2*i+1 and 2*i+2. Each node stores an element of the heap. -The structure is ordered so that each node is bigger than its parent. An immediate consequence is that the -highest priority value is the one at the root. This value can be looked up in constant time (O(1)) at -`heap.tree[0]` +The structure is ordered so that, per the comparator, each node has lower priority than its parent; as a +consequence, the highest-priority value is at the root. This value can be looked up in constant time (O(1)) at +`heap.tree[0]`. By default, the comparator is `Comparators.lt`, which treats smaller values as higher priority +(min-heap). Using `Comparators.gt` yields a max-heap. The structure is designed to perform the following operations with the corresponding complexities: @@ -17798,9 +18768,9 @@ Removes all elements in the heap.
-## `MerkleTree` +## `MerkleTree` - + @@ -18066,9 +19036,9 @@ Error emitted when the proof used during an update is invalid (could not reprodu
-## `Time` +## `Time` - + @@ -18240,3 +19210,4 @@ pack the components into a Delay object.
+ diff --git a/content/contracts/5.x/api/utils/cryptography.mdx b/content/contracts/5.x/api/utils/cryptography.mdx index 13e43174..0f496a59 100644 --- a/content/contracts/5.x/api/utils/cryptography.mdx +++ b/content/contracts/5.x/api/utils/cryptography.mdx @@ -11,6 +11,7 @@ A collection of contracts and libraries that implement various signature validat * [`SignatureChecker`](#SignatureChecker): A library helper to support regular ECDSA from EOAs as well as ERC-1271 signatures for smart contracts. * [`Hashes`](#Hashes): Commonly used hash functions. * [`MerkleProof`](#MerkleProof): Functions for verifying [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree) proofs. +* [`TrieProof`](#TrieProof): Library for verifying Ethereum Merkle-Patricia trie inclusion proofs. * [`EIP712`](#EIP712): Contract with functions to allow processing signed typed structure data according to [EIP-712](https://eips.ethereum.org/EIPS/eip-712). * [`ERC7739Utils`](#ERC7739Utils): Utilities library that implements a defensive rehashing mechanism to prevent replayability of smart contract signatures based on ERC-7739. * [`WebAuthn`](#WebAuthn): Library for verifying WebAuthn Authentication Assertions. @@ -38,6 +39,8 @@ A collection of contracts and libraries that implement various signature validat [`MerkleProof`](#MerkleProof) +[`TrieProof`](#TrieProof) + [`EIP712`](#EIP712) [`ERC7739Utils`](#ERC7739Utils) @@ -76,9 +79,9 @@ A collection of contracts and libraries that implement various signature validat
-## `ECDSA` +## `ECDSA` - + @@ -263,7 +266,7 @@ See [ERC-2098 short signatures](https://eips.ethereum.org/EIPS/eip-2098)
-Overload of [`ECDSA.recover`](#ECDSA-recover-bytes32-uint8-bytes32-bytes32-) that receives the `r and `vs` short-signature fields separately. +Overload of [`ECDSA.recover`](#ECDSA-recover-bytes32-uint8-bytes32-bytes32-) that receives the `r` and `vs` short-signature fields separately.
@@ -339,7 +342,7 @@ Consider validating the result before use, or use [`ECDSA.tryRecover`](#ECDSA-tr
-Variant of [`CAIP10.parse`](#CAIP10-parse-string-) that takes a signature in calldata +Variant of [`ECDSA.parse`](#ECDSA-parse-bytes-) that takes a signature in calldata
@@ -356,7 +359,7 @@ Variant of [`CAIP10.parse`](#CAIP10-parse-string-) that takes a signature in cal
-The signature derives the `address(0)`. +The signature is invalid.
@@ -399,9 +402,9 @@ The signature has an S value that is in the upper half order.
-## `EIP712` +## `EIP712` - + @@ -445,15 +448,18 @@ separator from the immutable values, which is cheaper than accessing a cached ve - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc]

Events

-#### IERC5267 [!toc] +
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) + +
@@ -478,7 +484,8 @@ The meaning of `name` and `version` is specified in - `version`: the current major version of the signing domain. -These parameters cannot be changed except through a [smart contract upgrade](/contracts/5.x/learn/upgrading-smart-contracts). +These parameters cannot be changed except through a [smart +contract upgrade](/contracts/5.x/learn/upgrading-smart-contracts).
@@ -596,9 +603,9 @@ It only reads from storage if necessary (in case the value is too large to fit i
-## `Hashes` +## `Hashes` - + @@ -662,9 +669,9 @@ Implementation of keccak256(abi.encode(a, b)) that doesn't allocate or expand me
-## `MerkleProof` +## `MerkleProof` - + @@ -923,7 +930,9 @@ Returns true if the `leaves` can be simultaneously proven to be a part of a Merk This version handles multiproofs in memory with the default hashing function. -CAUTION: Not all Merkle trees admit multiproofs. See [`MerkleProof.processMultiProof`](#MerkleProof-processMultiProof-bytes32---bool---bytes32---function--bytes32-bytes32--view-returns--bytes32--) for details. + +Not all Merkle trees admit multiproofs. See [`MerkleProof.processMultiProof`](#MerkleProof-processMultiProof-bytes32---bool---bytes32---function--bytes32-bytes32--view-returns--bytes32--) for details. + Consider the case where `root == proof[0] && leaves.length == 0` as it will return `true`. @@ -952,9 +961,11 @@ respectively. This version handles multiproofs in memory with the default hashing function. -CAUTION: Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree + +Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree is complete (but not necessarily perfect), 2) the leaves to be proven are in the opposite order they are in the tree (i.e., as seen from right to left starting at the deepest layer and continuing at the next layer). + The _empty set_ (i.e. the case where `proof.length == 1 && leaves.length == 0`) is considered a no-op, @@ -982,7 +993,9 @@ Returns true if the `leaves` can be simultaneously proven to be a part of a Merk This version handles multiproofs in memory with a custom hashing function. -CAUTION: Not all Merkle trees admit multiproofs. See [`MerkleProof.processMultiProof`](#MerkleProof-processMultiProof-bytes32---bool---bytes32---function--bytes32-bytes32--view-returns--bytes32--) for details. + +Not all Merkle trees admit multiproofs. See [`MerkleProof.processMultiProof`](#MerkleProof-processMultiProof-bytes32---bool---bytes32---function--bytes32-bytes32--view-returns--bytes32--) for details. + Consider the case where `root == proof[0] && leaves.length == 0` as it will return `true`. @@ -1011,9 +1024,11 @@ respectively. This version handles multiproofs in memory with a custom hashing function. -CAUTION: Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree + +Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree is complete (but not necessarily perfect), 2) the leaves to be proven are in the opposite order they are in the tree (i.e., as seen from right to left starting at the deepest layer and continuing at the next layer). + The _empty set_ (i.e. the case where `proof.length == 1 && leaves.length == 0`) is considered a no-op, @@ -1041,7 +1056,9 @@ Returns true if the `leaves` can be simultaneously proven to be a part of a Merk This version handles multiproofs in calldata with the default hashing function. -CAUTION: Not all Merkle trees admit multiproofs. See [`MerkleProof.processMultiProof`](#MerkleProof-processMultiProof-bytes32---bool---bytes32---function--bytes32-bytes32--view-returns--bytes32--) for details. + +Not all Merkle trees admit multiproofs. See [`MerkleProof.processMultiProof`](#MerkleProof-processMultiProof-bytes32---bool---bytes32---function--bytes32-bytes32--view-returns--bytes32--) for details. + Consider the case where `root == proof[0] && leaves.length == 0` as it will return `true`. @@ -1070,9 +1087,11 @@ respectively. This version handles multiproofs in calldata with the default hashing function. -CAUTION: Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree + +Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree is complete (but not necessarily perfect), 2) the leaves to be proven are in the opposite order they are in the tree (i.e., as seen from right to left starting at the deepest layer and continuing at the next layer). + The _empty set_ (i.e. the case where `proof.length == 1 && leaves.length == 0`) is considered a no-op, @@ -1100,7 +1119,9 @@ Returns true if the `leaves` can be simultaneously proven to be a part of a Merk This version handles multiproofs in calldata with a custom hashing function. -CAUTION: Not all Merkle trees admit multiproofs. See [`MerkleProof.processMultiProof`](#MerkleProof-processMultiProof-bytes32---bool---bytes32---function--bytes32-bytes32--view-returns--bytes32--) for details. + +Not all Merkle trees admit multiproofs. See [`MerkleProof.processMultiProof`](#MerkleProof-processMultiProof-bytes32---bool---bytes32---function--bytes32-bytes32--view-returns--bytes32--) for details. + Consider the case where `root == proof[0] && leaves.length == 0` as it will return `true`. @@ -1129,9 +1150,11 @@ respectively. This version handles multiproofs in calldata with a custom hashing function. -CAUTION: Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree + +Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree is complete (but not necessarily perfect), 2) the leaves to be proven are in the opposite order they are in the tree (i.e., as seen from right to left starting at the deepest layer and continuing at the next layer). + The _empty set_ (i.e. the case where `proof.length == 1 && leaves.length == 0`) is considered a no-op, @@ -1163,9 +1186,9 @@ The multiproof provided is not valid.
-## `MessageHashUtils` +## `MessageHashUtils` - + @@ -1189,6 +1212,16 @@ specifications. - [toDataWithIntendedValidatorHash(validator, data)](#MessageHashUtils-toDataWithIntendedValidatorHash-address-bytes-) - [toDataWithIntendedValidatorHash(validator, messageHash)](#MessageHashUtils-toDataWithIntendedValidatorHash-address-bytes32-) - [toTypedDataHash(domainSeparator, structHash)](#MessageHashUtils-toTypedDataHash-bytes32-bytes32-) +- [toDomainSeparator(fields, name, version, chainId, verifyingContract, salt)](#MessageHashUtils-toDomainSeparator-bytes1-string-string-uint256-address-bytes32-) +- [toDomainSeparator(fields, nameHash, versionHash, chainId, verifyingContract, salt)](#MessageHashUtils-toDomainSeparator-bytes1-bytes32-bytes32-uint256-address-bytes32-) +- [toDomainTypeHash(fields)](#MessageHashUtils-toDomainTypeHash-bytes1-) +
+
+ +
+

Errors

+
+- [ERC5267ExtensionsNotSupported()](#MessageHashUtils-ERC5267ExtensionsNotSupported--)
@@ -1281,7 +1314,7 @@ See [`ECDSA.recover`](#ECDSA-recover-bytes32-uint8-bytes32-bytes32-).
-Variant of #MessageHashUtils-toDataWithIntendedValidatorHash-address-bytes- optimized for cases where `data` is a bytes32. +Variant of `toDataWithIntendedValidatorHash-address-bytes` optimized for cases where `data` is a bytes32.
@@ -1309,13 +1342,91 @@ See [`ECDSA.recover`](#ECDSA-recover-bytes32-uint8-bytes32-bytes32-).
+ + +
+
+

toDomainSeparator(bytes1 fields, string name, string version, uint256 chainId, address verifyingContract, bytes32 salt) โ†’ bytes32 hash

+
+

internal

+# +
+
+
+ +Returns the EIP-712 domain separator constructed from an `eip712Domain`. See [`IERC5267.eip712Domain`](/contracts/5.x/api/interfaces#IERC5267-eip712Domain--) + +This function dynamically constructs the domain separator based on which fields are present in the +`fields` parameter. It contains flags that indicate which domain fields are present: + +* Bit 0 (0x01): name +* Bit 1 (0x02): version +* Bit 2 (0x04): chainId +* Bit 3 (0x08): verifyingContract +* Bit 4 (0x10): salt + +Arguments that correspond to fields which are not present in `fields` are ignored. For example, if `fields` is +`0x0f` (`0b01111`), then the `salt` parameter is ignored. + +
+
+ + + +
+
+

toDomainSeparator(bytes1 fields, bytes32 nameHash, bytes32 versionHash, uint256 chainId, address verifyingContract, bytes32 salt) โ†’ bytes32 hash

+
+

internal

+# +
+
+
+ +Variant of `toDomainSeparator-bytes1-string-string-uint256-address-bytes32` that uses hashed name and version. + +
+
+ + + +
+
+

toDomainTypeHash(bytes1 fields) โ†’ bytes32 hash

+
+

internal

+# +
+
+
+ +Builds an EIP-712 domain type hash depending on the `fields` provided, following [ERC-5267](https://eips.ethereum.org/EIPS/eip-5267) + +
+
+ + + +
+
+

ERC5267ExtensionsNotSupported()

+
+

error

+# +
+
+
+ +
+
+
-## `P256` +## `P256` - + @@ -1379,7 +1490,7 @@ bytecode.
-Same as [`IERC7913SignatureVerifier.verify`](../interfaces#IERC7913SignatureVerifier-verify-bytes-bytes32-bytes-), but it will revert if the required precompile is not available. +Same as [`MerkleProof.verify`](#MerkleProof-verify-bytes32---bytes32-bytes32-function--bytes32-bytes32--view-returns--bytes32--), but it will revert if the required precompile is not available. Make sure any logic (code or precompile) deployed at that address is the expected one, otherwise the returned value may be misinterpreted as a positive boolean. @@ -1399,7 +1510,7 @@ otherwise the returned value may be misinterpreted as a positive boolean.
-Same as [`IERC7913SignatureVerifier.verify`](../interfaces#IERC7913SignatureVerifier-verify-bytes-bytes32-bytes-), but only the Solidity implementation is used. +Same as [`MerkleProof.verify`](#MerkleProof-verify-bytes32---bytes32-bytes32-function--bytes32-bytes32--view-returns--bytes32--), but only the Solidity implementation is used.
@@ -1434,7 +1545,7 @@ Public key recovery
Checks if (x, y) are valid coordinates of a point on the curve. -In particular this function checks that x < P and y < P. +In particular this function checks that x < P and y < P.
@@ -1443,9 +1554,9 @@ In particular this function checks that x < P and y < P.
-## `RSA` +## `RSA` - + @@ -1530,9 +1641,9 @@ using a low exponent out of security concerns.
-## `SignatureChecker` +## `SignatureChecker` - + @@ -1556,6 +1667,7 @@ See [ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) and [ERC-7913](https://e - [isValidSignatureNow(signer, hash, signature)](#SignatureChecker-isValidSignatureNow-address-bytes32-bytes-) - [isValidSignatureNowCalldata(signer, hash, signature)](#SignatureChecker-isValidSignatureNowCalldata-address-bytes32-bytes-) - [isValidERC1271SignatureNow(signer, hash, signature)](#SignatureChecker-isValidERC1271SignatureNow-address-bytes32-bytes-) +- [isValidERC1271SignatureNowCalldata(signer, hash, signature)](#SignatureChecker-isValidERC1271SignatureNowCalldata-address-bytes32-bytes-) - [isValidSignatureNow(signer, hash, signature)](#SignatureChecker-isValidSignatureNow-bytes-bytes32-bytes-) - [areValidSignaturesNow(hash, signers, signatures)](#SignatureChecker-areValidSignaturesNow-bytes32-bytes---bytes---)
@@ -1582,7 +1694,7 @@ change through time. It could return true at block N and false at block N+1 (or -For an extended version of this function that supports ERC-7913 signatures, see #SignatureChecker-isValidSignatureNow-bytes-bytes32-bytes-. +For an extended version of this function that supports ERC-7913 signatures, see `isValidSignatureNow-bytes-bytes32-bytes-`.
@@ -1628,6 +1740,21 @@ change through time. It could return true at block N and false at block N+1 (or
+ + +
+
+

isValidERC1271SignatureNowCalldata(address signer, bytes32 hash, bytes signature) โ†’ bool result

+
+

internal

+# +
+
+
+ +
+
+
@@ -1647,9 +1774,9 @@ The signer is a `bytes` object that is the concatenation of an address and optio Verification is done as follows: -* If `signer.length < 20`: verification fails +* If `signer.length < 20`: verification fails * If `signer.length == 20`: verification is done using [`SignatureChecker.isValidSignatureNow`](#SignatureChecker-isValidSignatureNow-bytes-bytes32-bytes-) -* Otherwise: verification is done using [`IERC7913SignatureVerifier`](../interfaces#IERC7913SignatureVerifier) +* Otherwise: verification is done using [`IERC7913SignatureVerifier`](/contracts/5.x/api/interfaces#IERC7913SignatureVerifier) Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus @@ -1685,13 +1812,134 @@ change through time. It could return true at block N and false at block N+1 (or
+ + +
+ +## `TrieProof` + + + + + +
+ +```solidity +import "@openzeppelin/contracts/utils/cryptography/TrieProof.sol"; +``` + +Library for verifying Ethereum Merkle-Patricia trie inclusion proofs. + +The [`TrieProof.traverse`](#TrieProof-traverse-bytes32-bytes-bytes---) and [`MerkleProof.verify`](#MerkleProof-verify-bytes32---bytes32-bytes32-function--bytes32-bytes32--view-returns--bytes32--) functions can be used to prove the following value: + +* Transaction against the transactionsRoot of a block. +* Event against receiptsRoot of a block. +* Account details (RLP encoding of [nonce, balance, storageRoot, codeHash]) against the stateRoot of a block. +* Storage slot (RLP encoding of the value) against the storageRoot of a account. + +Proving a storage slot is usually done in 3 steps: + +* From the stateRoot of a block, process the account proof (see `eth_getProof`) to get the account details. +* RLP decode the account details to extract the storageRoot. +* Use storageRoot of that account to process the storageProof (again, see `eth_getProof`). + +See [Merkle-Patricia trie](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie) + +Based on [this implementation from optimism](https://github.com/ethereum-optimism/optimism/blob/ef970556e668b271a152124023a8d6bb5159bacf/packages/contracts-bedrock/src/libraries/trie/MerkleTrie.sol). + +
+

Functions

+
+- [verify(value, root, key, proof)](#TrieProof-verify-bytes-bytes32-bytes-bytes---) +- [traverse(root, key, proof)](#TrieProof-traverse-bytes32-bytes-bytes---) +- [tryTraverse(root, key, proof)](#TrieProof-tryTraverse-bytes32-bytes-bytes---) +
+
+ +
+

Errors

+
+- [TrieProofTraversalError(err)](#TrieProof-TrieProofTraversalError-enum-TrieProof-ProofError-) +
+
+ + + +
+
+

verify(bytes value, bytes32 root, bytes key, bytes[] proof) โ†’ bool

+
+

internal

+# +
+
+
+ +Verifies a `proof` against a given `key`, `value`, `and root` hash. + +
+
+ + + +
+
+

traverse(bytes32 root, bytes key, bytes[] proof) โ†’ bytes

+
+

internal

+# +
+
+
+ +Traverses a proof with a given key and returns the value. + +Reverts with [`TrieProof.TrieProofTraversalError`](#TrieProof-TrieProofTraversalError-enum-TrieProof-ProofError-) if proof is invalid. + +
+
+ + + +
+
+

tryTraverse(bytes32 root, bytes key, bytes[] proof) โ†’ bytes value, enum TrieProof.ProofError err

+
+

internal

+# +
+
+
+ +Traverses a proof with a given key and returns the value and an error flag +instead of reverting if the proof is invalid. This function may still revert if +malformed input leads to RLP decoding errors. + +
+
+ + + +
+
+

TrieProofTraversalError(enum TrieProof.ProofError err)

+
+

error

+# +
+
+
+ +
+
+
-## `WebAuthn` +## `WebAuthn` - + @@ -1711,15 +1959,18 @@ signatures generated during WebAuthn authentication ceremonies as specified in t For blockchain use cases, the following WebAuthn validations are intentionally omitted: -* Origin validation: Origin verification in `clientDataJSON` is omitted as blockchain - contexts rely on authenticator and dapp frontend enforcement. Standard authenticators - implement proper origin validation. +* Origin validation: Origin verification in `clientDataJSON` is omitted. This check is the + responsibility of the authenticator and does not have a meaningful on-chain use case; standard + authenticators implement proper origin validation before signing. * RP ID hash validation: Verification of `rpIdHash` in authenticatorData against expected - RP ID hash is omitted. This is typically handled by platform-level security measures. - Including an expiry timestamp in signed data is recommended for enhanced security. -* Signature counter: Verification of signature counter increments is omitted. While - useful for detecting credential cloning, on-chain operations typically include nonce - protection, making this check redundant. + RP ID hash is omitted. This check is the responsibility of the authenticator and does not have + a meaningful on-chain use case; it is typically enforced at the platform level. +* Signature counter: Verification of signature counter increments is omitted. The + signature counter is maintained by authenticators per the WebAuthn spec to detect + credential cloning, but validating it requires storing per-credential mutable state + (the last seen counter value) which is impractical for most smart contract applications. + Additionally, counter enforcement is primarily an authenticator responsibility, not a + contract-level concern. * Extension outputs: Extension output value verification is omitted as these are not essential for core authentication security in blockchain applications. * Attestation: Attestation object verification is omitted as this implementation @@ -1810,9 +2061,9 @@ cause revert/panic.
-## `ERC7739Utils` +## `ERC7739Utils` - + @@ -1825,7 +2076,8 @@ import "@openzeppelin/contracts/utils/cryptography/draft-ERC7739Utils.sol"; Utilities to process [ERC-7739](https://ercs.ethereum.org/ERCS/erc-7739) typed data signatures that are specific to an EIP-712 domain. -This library provides methods to wrap, unwrap and operate over typed data signatures with a defensive rehashing mechanism that includes the app's [EIP-712](/contracts/5.x/api/utils/cryptography#EIP712-_domainSeparatorV4) +This library provides methods to wrap, unwrap and operate over typed data signatures with a defensive +rehashing mechanism that includes the app's xref:api:utils/cryptography#EIP712-_domainSeparatorV4[EIP-712] and preserves readability of the signed content using an EIP-712 nested approach. A smart contract domain can validate a signature for a typed data structure in two ways: @@ -1837,7 +2089,8 @@ A smart contract domain can validate a signature for a typed data structure in t A provider for a smart contract wallet would need to return this signature as the result of a call to `personal_sign` or `eth_signTypedData`, and this may be unsupported by API clients that expect a return value of 129 bytes, or specifically the `r,s,v` parameters -of an [ECDSA](/contracts/5.x/api/utils/cryptography#ECDSA) signature, as is for example specified for [EIP-712](/contracts/5.x/api/utils/cryptography#EIP712). +of an xref:api:utils/cryptography#ECDSA[ECDSA] signature, as is for example specified for +xref:api:utils/cryptography#EIP712[EIP-712].
@@ -1899,7 +2152,6 @@ Constructed as follows: This function returns empty if the input format is invalid instead of reverting. -data instead.
@@ -1921,7 +2173,7 @@ Nests an `ERC-191` digest into a `PersonalSign` EIP-712 struct, and returns the This struct hash must be combined with a domain separator, using [`MessageHashUtils.toTypedDataHash`](#MessageHashUtils-toTypedDataHash-bytes32-bytes32-) before being verified/recovered. -This is used to simulates the `personal_sign` RPC method in the context of smart contracts. +This is used to simulate the `personal_sign` RPC method in the context of smart contracts.
@@ -1957,7 +2209,7 @@ before being verified/recovered.
-Variant of #ERC7739Utils-typedDataSignStructHash-string-string-bytes32-bytes- that takes a content descriptor +Variant of `typedDataSignStructHash-string-string-bytes32-bytes` that takes a content descriptor and decodes the `contentsName` and `contentsType` out of it.
@@ -2008,9 +2260,9 @@ length.
-## `AbstractSigner` +## `AbstractSigner` - + @@ -2022,7 +2274,7 @@ import "@openzeppelin/contracts/utils/cryptography/signers/AbstractSigner.sol"; Abstract contract for signature validation. -Developers must implement [`AccountERC7579._rawSignatureValidation`](../account#AccountERC7579-_rawSignatureValidation-bytes32-bytes-) and use it as the lowest-level signature validation mechanism. +Developers must implement [`AbstractSigner._rawSignatureValidation`](#AbstractSigner-_rawSignatureValidation-bytes32-bytes-) and use it as the lowest-level signature validation mechanism. @custom:stateless @@ -2049,8 +2301,9 @@ Signature validation algorithm. Implementing a signature validation algorithm is a security-sensitive operation as it involves -cryptographic verification. It is important to review and test thoroughly before deployment. Consider using one of the signature verification libraries ([ECDSA](/contracts/5.x/api/utils/cryptography#ECDSA), -[P256](/contracts/5.x/api/utils/cryptography#P256) or [RSA](/contracts/5.x/api/utils/cryptography#RSA)). +cryptographic verification. It is important to review and test thoroughly before deployment. Consider +using one of the signature verification libraries (xref:api:utils/cryptography#ECDSA[ECDSA], +xref:api:utils/cryptography#P256[P256] or xref:api:utils/cryptography#RSA[RSA]).
@@ -2060,9 +2313,9 @@ cryptographic verification. It is important to review and test thoroughly before
-## `MultiSignerERC7913` +## `MultiSignerERC7913` - + @@ -2123,7 +2376,6 @@ either front-runnable or unusable. - [_rawSignatureValidation(hash, signature)](#MultiSignerERC7913-_rawSignatureValidation-bytes32-bytes-) - [_validateSignatures(hash, signers, signatures)](#MultiSignerERC7913-_validateSignatures-bytes32-bytes---bytes---) - [_validateThreshold(validatingSigners)](#MultiSignerERC7913-_validateThreshold-bytes---) -#### AbstractSigner [!toc]
@@ -2133,7 +2385,6 @@ either front-runnable or unusable. - [ERC7913SignerAdded(signers)](#MultiSignerERC7913-ERC7913SignerAdded-bytes-) - [ERC7913SignerRemoved(signers)](#MultiSignerERC7913-ERC7913SignerRemoved-bytes-) - [ERC7913ThresholdSet(threshold)](#MultiSignerERC7913-ERC7913ThresholdSet-uint64-) -#### AbstractSigner [!toc] @@ -2145,7 +2396,6 @@ either front-runnable or unusable. - [MultiSignerERC7913InvalidSigner(signer)](#MultiSignerERC7913-MultiSignerERC7913InvalidSigner-bytes-) - [MultiSignerERC7913ZeroThreshold()](#MultiSignerERC7913-MultiSignerERC7913ZeroThreshold--) - [MultiSignerERC7913UnreachableThreshold(signers, threshold)](#MultiSignerERC7913-MultiSignerERC7913UnreachableThreshold-uint64-uint64-) -#### AbstractSigner [!toc] @@ -2260,6 +2510,15 @@ Requirements: * Each of `newSigners` must be at least 20 bytes long. Reverts with [`MultiSignerERC7913.MultiSignerERC7913InvalidSigner`](#MultiSignerERC7913-MultiSignerERC7913InvalidSigner-bytes-) if not. * Each of `newSigners` must not be authorized. See [`MultiSignerERC7913.isSigner`](#MultiSignerERC7913-isSigner-bytes-). Reverts with [`MultiSignerERC7913.MultiSignerERC7913AlreadyExists`](#MultiSignerERC7913-MultiSignerERC7913AlreadyExists-bytes-) if so. + +This function does not validate that signers are controlled or represent appropriate entities. Integrators +must ensure signers are properly validated before adding them. Problematic signers can compromise +the multisig's security or functionality. Examples include uncontrolled addresses (e.g., `address(0)`), +the account's own address (which may cause recursive validation loops), or contracts that may unintentionally +allow arbitrary validation (e.g. using the identity precompile at `address(0x04)`, which would return the +ERC-1271 magic value for any `isValidSignature` call). + + @@ -2562,9 +2821,9 @@ The `threshold` is unreachable given the number of `signers`.
-## `MultiSignerERC7913Weighted` +## `MultiSignerERC7913Weighted` - + @@ -2625,7 +2884,9 @@ least two signers (e.g., one with weight 1 and one with weight 3). See [`MultiSi - [_removeSigners(signers)](#MultiSignerERC7913Weighted-_removeSigners-bytes---) - [_validateReachableThreshold()](#MultiSignerERC7913Weighted-_validateReachableThreshold--) - [_validateThreshold(signers)](#MultiSignerERC7913Weighted-_validateThreshold-bytes---) -#### MultiSignerERC7913 [!toc] +
+MultiSignerERC7913 + - [getSigners(start, end)](#MultiSignerERC7913-getSigners-uint64-uint64-) - [getSignerCount()](#MultiSignerERC7913-getSignerCount--) - [isSigner(signer)](#MultiSignerERC7913-isSigner-bytes-) @@ -2633,7 +2894,8 @@ least two signers (e.g., one with weight 1 and one with weight 3). See [`MultiSi - [_setThreshold(newThreshold)](#MultiSignerERC7913-_setThreshold-uint64-) - [_rawSignatureValidation(hash, signature)](#MultiSignerERC7913-_rawSignatureValidation-bytes32-bytes-) - [_validateSignatures(hash, signers, signatures)](#MultiSignerERC7913-_validateSignatures-bytes32-bytes---bytes---) -#### AbstractSigner [!toc] + +
@@ -2641,11 +2903,14 @@ least two signers (e.g., one with weight 1 and one with weight 3). See [`MultiSi

Events

- [ERC7913SignerWeightChanged(signer, weight)](#MultiSignerERC7913Weighted-ERC7913SignerWeightChanged-bytes-uint64-) -#### MultiSignerERC7913 [!toc] +
+MultiSignerERC7913 + - [ERC7913SignerAdded(signers)](#MultiSignerERC7913-ERC7913SignerAdded-bytes-) - [ERC7913SignerRemoved(signers)](#MultiSignerERC7913-ERC7913SignerRemoved-bytes-) - [ERC7913ThresholdSet(threshold)](#MultiSignerERC7913-ERC7913ThresholdSet-uint64-) -#### AbstractSigner [!toc] + +
@@ -2654,13 +2919,16 @@ least two signers (e.g., one with weight 1 and one with weight 3). See [`MultiSi
- [MultiSignerERC7913WeightedInvalidWeight(signer, weight)](#MultiSignerERC7913Weighted-MultiSignerERC7913WeightedInvalidWeight-bytes-uint64-) - [MultiSignerERC7913WeightedMismatchedLength()](#MultiSignerERC7913Weighted-MultiSignerERC7913WeightedMismatchedLength--) -#### MultiSignerERC7913 [!toc] +
+MultiSignerERC7913 + - [MultiSignerERC7913AlreadyExists(signer)](#MultiSignerERC7913-MultiSignerERC7913AlreadyExists-bytes-) - [MultiSignerERC7913NonexistentSigner(signer)](#MultiSignerERC7913-MultiSignerERC7913NonexistentSigner-bytes-) - [MultiSignerERC7913InvalidSigner(signer)](#MultiSignerERC7913-MultiSignerERC7913InvalidSigner-bytes-) - [MultiSignerERC7913ZeroThreshold()](#MultiSignerERC7913-MultiSignerERC7913ZeroThreshold--) - [MultiSignerERC7913UnreachableThreshold(signers, threshold)](#MultiSignerERC7913-MultiSignerERC7913UnreachableThreshold-uint64-uint64-) -#### AbstractSigner [!toc] + +
@@ -2893,9 +3161,9 @@ Thrown when the arrays lengths don't match. See [`MultiSignerERC7913Weighted._se
-## `SignerECDSA` +## `SignerECDSA` - + @@ -2905,9 +3173,9 @@ Thrown when the arrays lengths don't match. See [`MultiSignerERC7913Weighted._se import "@openzeppelin/contracts/utils/cryptography/signers/SignerECDSA.sol"; ``` -Implementation of [`AbstractSigner`](#AbstractSigner) using [ECDSA](/contracts/5.x/api/utils/cryptography#ECDSA) signatures. +Implementation of [`AbstractSigner`](#AbstractSigner) using xref:api:utils/cryptography#ECDSA[ECDSA] signatures. -For [`Account`](../account#Account) usage, a [`SignerECDSA._setSigner`](#SignerECDSA-_setSigner-address-) function is provided to set the [`SignerECDSA.signer`](#SignerECDSA-signer--) address. +For [`Account`](/contracts/5.x/api/account#Account) usage, a [`SignerECDSA._setSigner`](#SignerECDSA-_setSigner-address-) function is provided to set the [`SignerECDSA.signer`](#SignerECDSA-signer--) address. Doing so is easier for a factory, who is likely to use initializable clones of this contract. Example of usage: @@ -2932,7 +3200,6 @@ or during initialization (if used as a clone) may leave the signer either front- - [_setSigner(signerAddr)](#SignerECDSA-_setSigner-address-) - [signer()](#SignerECDSA-signer--) - [_rawSignatureValidation(hash, signature)](#SignerECDSA-_rawSignatureValidation-bytes32-bytes-) -#### AbstractSigner [!toc]
@@ -3002,7 +3269,9 @@ Signature validation algorithm. Implementing a signature validation algorithm is a security-sensitive operation as it involves -cryptographic verification. It is important to review and test thoroughly before deployment. Consider using one of the signature verification libraries ([ECDSA](/contracts/5.x/api/utils/cryptography#ECDSA), [P256](/contracts/5.x/api/utils/cryptography#P256) or [RSA](/contracts/5.x/api/utils/cryptography#RSA)). +cryptographic verification. It is important to review and test thoroughly before deployment. Consider +using one of the signature verification libraries (xref:api:utils/cryptography#ECDSA[ECDSA], +xref:api:utils/cryptography#P256[P256] or xref:api:utils/cryptography#RSA[RSA]). @@ -3012,9 +3281,9 @@ cryptographic verification. It is important to review and test thoroughly before
-## `SignerEIP7702` +## `SignerEIP7702` - + @@ -3024,7 +3293,7 @@ cryptographic verification. It is important to review and test thoroughly before import "@openzeppelin/contracts/utils/cryptography/signers/SignerEIP7702.sol"; ``` -Implementation of [`AbstractSigner`](#AbstractSigner) for implementation for an EOA. Useful for ERC-7702 accounts. +Implementation of [`AbstractSigner`](#AbstractSigner) for implementation for an EOA. Useful for EIP-7702 accounts. @custom:stateless @@ -3032,7 +3301,6 @@ Implementation of [`AbstractSigner`](#AbstractSigner) for implementation for an

Functions

- [_rawSignatureValidation(hash, signature)](#SignerEIP7702-_rawSignatureValidation-bytes32-bytes-) -#### AbstractSigner [!toc]
@@ -3057,9 +3325,9 @@ Validates the signature using the EOA's address (i.e. `address(this)`).
-## `SignerERC7913` +## `SignerERC7913` - + @@ -3072,7 +3340,7 @@ import "@openzeppelin/contracts/utils/cryptography/signers/SignerERC7913.sol"; Implementation of [`AbstractSigner`](#AbstractSigner) using [ERC-7913](https://eips.ethereum.org/EIPS/eip-7913) signature verification. -For [`Account`](../account#Account) usage, a [`SignerECDSA._setSigner`](#SignerECDSA-_setSigner-address-) function is provided to set the ERC-7913 formatted [`SignerECDSA.signer`](#SignerECDSA-signer--). +For [`Account`](/contracts/5.x/api/account#Account) usage, a [`SignerECDSA._setSigner`](#SignerECDSA-_setSigner-address-) function is provided to set the ERC-7913 formatted [`SignerECDSA.signer`](#SignerECDSA-signer--). Doing so is easier for a factory, who is likely to use initializable clones of this contract. The signer is a `bytes` object that concatenates a verifier address and a key: `verifier || key`. @@ -3103,7 +3371,6 @@ or during initialization (if used as a clone) may leave the signer either front- - [signer()](#SignerERC7913-signer--) - [_setSigner(signer_)](#SignerERC7913-_setSigner-bytes-) - [_rawSignatureValidation(hash, signature)](#SignerERC7913-_rawSignatureValidation-bytes32-bytes-) -#### AbstractSigner [!toc]
@@ -3168,7 +3435,7 @@ Sets the signer (i.e. `verifier || key`) with an ERC-7913 formatted signer.
-Verifies a signature using #SignatureChecker-isValidSignatureNow-bytes-bytes32-bytes- +Verifies a signature using `SignatureChecker-isValidSignatureNow-bytes-bytes32-bytes-` with [`SignerECDSA.signer`](#SignerECDSA-signer--), `hash` and `signature`.
@@ -3178,9 +3445,9 @@ with [`SignerECDSA.signer`](#SignerECDSA-signer--), `hash` and `signature`.
-## `SignerP256` +## `SignerP256` - + @@ -3190,9 +3457,9 @@ with [`SignerECDSA.signer`](#SignerECDSA-signer--), `hash` and `signature`. import "@openzeppelin/contracts/utils/cryptography/signers/SignerP256.sol"; ``` -Implementation of [`AbstractSigner`](#AbstractSigner) using [P256](/contracts/5.x/api/utils/cryptography#P256) signatures. +Implementation of [`AbstractSigner`](#AbstractSigner) using xref:api:utils/cryptography#P256[P256] signatures. -For [`Account`](../account#Account) usage, a [`SignerECDSA._setSigner`](#SignerECDSA-_setSigner-address-) function is provided to set the [`SignerECDSA.signer`](#SignerECDSA-signer--) public key. +For [`Account`](/contracts/5.x/api/account#Account) usage, a [`SignerECDSA._setSigner`](#SignerECDSA-_setSigner-address-) function is provided to set the [`SignerECDSA.signer`](#SignerECDSA-signer--) public key. Doing so is easier for a factory, who is likely to use initializable clones of this contract. Example of usage: @@ -3217,7 +3484,6 @@ or during initialization (if used as a clone) may leave the signer either front- - [_setSigner(qx, qy)](#SignerP256-_setSigner-bytes32-bytes32-) - [signer()](#SignerP256-signer--) - [_rawSignatureValidation(hash, signature)](#SignerP256-_rawSignatureValidation-bytes32-bytes-) -#### AbstractSigner [!toc]
@@ -3225,7 +3491,6 @@ or during initialization (if used as a clone) may leave the signer either front-

Errors

- [SignerP256InvalidPublicKey(qx, qy)](#SignerP256-SignerP256InvalidPublicKey-bytes32-bytes32-) -#### AbstractSigner [!toc]
@@ -3295,7 +3560,9 @@ Signature validation algorithm. Implementing a signature validation algorithm is a security-sensitive operation as it involves -cryptographic verification. It is important to review and test thoroughly before deployment. Consider using one of the signature verification libraries ([ECDSA](/contracts/5.x/api/utils/cryptography#ECDSA), [P256](/contracts/5.x/api/utils/cryptography#P256) or [RSA](/contracts/5.x/api/utils/cryptography#RSA)). +cryptographic verification. It is important to review and test thoroughly before deployment. Consider +using one of the signature verification libraries (xref:api:utils/cryptography#ECDSA[ECDSA], +xref:api:utils/cryptography#P256[P256] or xref:api:utils/cryptography#RSA[RSA]). @@ -3320,9 +3587,9 @@ cryptographic verification. It is important to review and test thoroughly before
-## `SignerRSA` +## `SignerRSA` - + @@ -3332,9 +3599,9 @@ cryptographic verification. It is important to review and test thoroughly before import "@openzeppelin/contracts/utils/cryptography/signers/SignerRSA.sol"; ``` -Implementation of [`AbstractSigner`](#AbstractSigner) using [RSA](/contracts/5.x/api/utils/cryptography#RSA) signatures. +Implementation of [`AbstractSigner`](#AbstractSigner) using xref:api:utils/cryptography#RSA[RSA] signatures. -For [`Account`](../account#Account) usage, a [`SignerECDSA._setSigner`](#SignerECDSA-_setSigner-address-) function is provided to set the [`SignerECDSA.signer`](#SignerECDSA-signer--) public key. +For [`Account`](/contracts/5.x/api/account#Account) usage, a [`SignerECDSA._setSigner`](#SignerECDSA-_setSigner-address-) function is provided to set the [`SignerECDSA.signer`](#SignerECDSA-signer--) public key. Doing so is easier for a factory, who is likely to use initializable clones of this contract. Example of usage: @@ -3359,7 +3626,6 @@ or during initialization (if used as a clone) may leave the signer either front- - [_setSigner(e, n)](#SignerRSA-_setSigner-bytes-bytes-) - [signer()](#SignerRSA-signer--) - [_rawSignatureValidation(hash, signature)](#SignerRSA-_rawSignatureValidation-bytes32-bytes-) -#### AbstractSigner [!toc]
@@ -3441,9 +3707,9 @@ encoding as per section 9.2 (step 1) of the RFC.
-## `SignerWebAuthn` +## `SignerWebAuthn` - + @@ -3480,19 +3746,25 @@ or during initialization (if used as a clone) may leave the signer either front-

Functions

- [_rawSignatureValidation(hash, signature)](#SignerWebAuthn-_rawSignatureValidation-bytes32-bytes-) -#### SignerP256 [!toc] +
+SignerP256 + - [_setSigner(qx, qy)](#SignerP256-_setSigner-bytes32-bytes32-) - [signer()](#SignerP256-signer--) -#### AbstractSigner [!toc] + +

Errors

-#### SignerP256 [!toc] +
+SignerP256 + - [SignerP256InvalidPublicKey(qx, qy)](#SignerP256-SignerP256InvalidPublicKey-bytes32-bytes32-) -#### AbstractSigner [!toc] + +
@@ -3510,9 +3782,7 @@ or during initialization (if used as a clone) may leave the signer either front- Validates a raw signature using the WebAuthn authentication assertion. -In case the signature can't be validated, it falls back to the -[`SignerP256._rawSignatureValidation`](#SignerP256-_rawSignatureValidation-bytes32-bytes-) method for raw P256 signature validation by passing -the raw `r` and `s` values from the signature. +Returns `false` if the signature is not a valid WebAuthn authentication assertion. @@ -3521,9 +3791,9 @@ the raw `r` and `s` values from the signature.
-## `ERC7739` +## `ERC7739` - + @@ -3538,11 +3808,13 @@ Validates signatures wrapping the message hash in a nested EIP712 type. See [`ER Linking the signature to the EIP-712 domain separator is a security measure to prevent signature replay across different EIP-712 domains (e.g. a single offchain owner of multiple contracts). -This contract requires implementing the [`AccountERC7579._rawSignatureValidation`](../account#AccountERC7579-_rawSignatureValidation-bytes32-bytes-) function, which passes the wrapped message hash, +This contract requires implementing the [`AbstractSigner._rawSignatureValidation`](#AbstractSigner-_rawSignatureValidation-bytes32-bytes-) function, which passes the wrapped message hash, which may be either an typed data or a personal sign nested type. -[EIP-712](/contracts/5.x/api/utils/cryptography#EIP712) uses [ShortStrings](/contracts/5.x/api/utils/cryptography#ShortStrings) to optimize gas costs for short strings (up to 31 characters). Consider that strings longer than that will use storage, which may limit the ability of the signer to be used within the ERC-4337 validation phase (due to +xref:api:utils/cryptography#EIP712[EIP-712] uses xref:api:utils/cryptography#ShortStrings[ShortStrings] to +optimize gas costs for short strings (up to 31 characters). Consider that strings longer than that will use storage, +which may limit the ability of the signer to be used within the ERC-4337 validation phase (due to [ERC-7562 storage access rules](https://eips.ethereum.org/EIPS/eip-7562#storage-rules)). @@ -3550,27 +3822,34 @@ which may be either an typed data or a personal sign nested type.

Functions

- [isValidSignature(hash, signature)](#ERC7739-isValidSignature-bytes32-bytes-) -#### IERC1271 [!toc] -#### EIP712 [!toc] +
+EIP712 + - [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--) - [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-) - [eip712Domain()](#EIP712-eip712Domain--) - [_EIP712Name()](#EIP712-_EIP712Name--) - [_EIP712Version()](#EIP712-_EIP712Version--) -#### IERC5267 [!toc] -#### AbstractSigner [!toc] + +
+
+AbstractSigner + - [_rawSignatureValidation(hash, signature)](#AbstractSigner-_rawSignatureValidation-bytes32-bytes-) + +

Events

-#### IERC1271 [!toc] -#### EIP712 [!toc] -#### IERC5267 [!toc] +
+IERC5267 + - [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--) -#### AbstractSigner [!toc] + +
@@ -3600,9 +3879,9 @@ A nested EIP-712 type might be presented in 2 different ways:
-## `ERC7913P256Verifier` +## `ERC7913P256Verifier` - + @@ -3620,7 +3899,6 @@ ERC-7913 signature verifier that support P256 (secp256r1) keys.

Functions

- [verify(key, hash, signature)](#ERC7913P256Verifier-verify-bytes-bytes32-bytes-) -#### IERC7913SignatureVerifier [!toc]
@@ -3649,9 +3927,9 @@ SHOULD return 0xffffffff or revert if the key is empty
-## `ERC7913RSAVerifier` +## `ERC7913RSAVerifier` - + @@ -3669,7 +3947,6 @@ ERC-7913 signature verifier that support RSA keys.

Functions

- [verify(key, hash, signature)](#ERC7913RSAVerifier-verify-bytes-bytes32-bytes-) -#### IERC7913SignatureVerifier [!toc]
@@ -3698,9 +3975,9 @@ SHOULD return 0xffffffff or revert if the key is empty
-## `ERC7913WebAuthnVerifier` +## `ERC7913WebAuthnVerifier` - + @@ -3716,7 +3993,7 @@ This verifier enables the validation of WebAuthn signatures using P256 public ke The key is expected to be a 64-byte concatenation of the P256 public key coordinates (qx || qy). The signature is expected to be an abi-encoded [`WebAuthn.WebAuthnAuth`](#WebAuthn-WebAuthnAuth) struct. -Uses `WebAuthn-verifyMinimal` for signature verification, which performs the essential +Uses [`WebAuthn.verify`](#WebAuthn-verify-bytes-struct-WebAuthn-WebAuthnAuth-bytes32-bytes32-bool-) for signature verification, which performs the essential WebAuthn checks: type validation, challenge matching, and cryptographic signature verification. @@ -3729,7 +4006,6 @@ Wallets that may require default P256 validation may install a P256 verifier sep

Functions

- [verify(key, hash, signature)](#ERC7913WebAuthnVerifier-verify-bytes-bytes32-bytes-) -#### IERC7913SignatureVerifier [!toc]
@@ -3753,3 +4029,4 @@ SHOULD return 0xffffffff or revert if the key is empty + diff --git a/docgen/templates-md/contract.hbs b/docgen/templates-md/contract.hbs index 7ba72057..1e5112b8 100644 --- a/docgen/templates-md/contract.hbs +++ b/docgen/templates-md/contract.hbs @@ -33,12 +33,22 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

Functions

{{#each inherited-functions}} -{{#unless @first}} -#### {{contract.name}} [!toc] -{{/unless}} +{{#if @first}} {{#each functions}} - [{{{name}}}({{names params}})](#{{anchor}}) {{/each}} +{{else}} +{{#if functions}} +
+{{contract.name}} + +{{#each functions}} +- [{{{name}}}({{names params}})](#{{anchor}}) +{{/each}} + +
+{{/if}} +{{/if}} {{/each}}
@@ -49,12 +59,22 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

Events

{{#each inheritance}} -{{#unless @first}} -#### {{name}} [!toc] -{{/unless}} +{{#if @first}} {{#each events}} - [{{{name}}}({{names params}})](#{{anchor}}) {{/each}} +{{else}} +{{#if events}} +
+{{name}} + +{{#each events}} +- [{{{name}}}({{names params}})](#{{anchor}}) +{{/each}} + +
+{{/if}} +{{/if}} {{/each}}
@@ -65,12 +85,22 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

Errors

{{#each inheritance}} -{{#unless @first}} -#### {{name}} [!toc] -{{/unless}} +{{#if @first}} +{{#each errors}} +- [{{{name}}}({{names params}})](#{{anchor}}) +{{/each}} +{{else}} +{{#if errors}} +
+{{name}} + {{#each errors}} - [{{{name}}}({{names params}})](#{{anchor}}) {{/each}} + +
+{{/if}} +{{/if}} {{/each}}
diff --git a/docgen/templates-md/helpers.js b/docgen/templates-md/helpers.js index 21468281..30f94abc 100644 --- a/docgen/templates-md/helpers.js +++ b/docgen/templates-md/helpers.js @@ -56,7 +56,7 @@ module.exports['process-natspec'] = function (natspec, opts) { const currentPage = opts.data.root.__item_context?.page || opts.data.root.id; const links = getAllLinks(opts.data.site.items, currentPage); - const processed = processReferences(natspec, links); + const processed = processReferences(natspec, links, currentPage); return processCallouts(processed); // Add callout processing at the end }; @@ -89,6 +89,8 @@ function getAllLinks(items, currentPage) { } const res = {}; + // Track which page each link key belongs to for same-page preference + const linkPages = {}; const currentPagePath = currentPage ? currentPage.replace(/\.mdx$/, '') : ''; for (const item of items) { @@ -97,6 +99,7 @@ function getAllLinks(items, currentPage) { // Generate xref keys for legacy compatibility res[`xref-${item.anchor}`] = linkPath; + linkPages[`xref-${item.anchor}`] = pagePath; // Generate original case xref keys if (item.__item_context && item.__item_context.contract) { @@ -106,11 +109,18 @@ function getAllLinks(items, currentPage) { originalAnchor += slug('(' + signature + ')'); } res[`xref-${originalAnchor}`] = linkPath; + linkPages[`xref-${originalAnchor}`] = pagePath; } - res[slug(item.fullName)] = `[\`${item.fullName}\`](${linkPath})`; + const key = slug(item.fullName); + res[key] = `[\`${item.fullName}\`](${linkPath})`; + linkPages[key] = pagePath; } + // Attach page info for same-page preference in findBestMatch + res.__linkPages = linkPages; + res.__currentPagePath = currentPagePath; + if (currentPage) { let cache = linksCache.get(items); if (!cache) { @@ -124,6 +134,7 @@ function getAllLinks(items, currentPage) { } function generateLinkPath(pagePath, currentPagePath, anchor) { + // Same page: use fragment-only link if ( currentPagePath && (pagePath === currentPagePath || pagePath.split('/').pop() === currentPagePath.split('/').pop()) @@ -131,30 +142,8 @@ function generateLinkPath(pagePath, currentPagePath, anchor) { return `#${anchor}`; } - if (currentPagePath) { - const currentParts = currentPagePath.split('/'); - const targetParts = pagePath.split('/'); - - // Find common base - let i = 0; - while (i < currentParts.length && i < targetParts.length && currentParts[i] === targetParts[i]) { - i++; - } - - const upLevels = Math.max(0, currentParts.length - 1 - i); - const downPath = targetParts.slice(i); - - if (upLevels === 0 && downPath.length === 1) { - return `${downPath[0]}#${anchor}`; - } else if (upLevels === 0) { - return `${downPath.join('/')}#${anchor}`; - } else { - const relativePath = '../'.repeat(upLevels) + downPath.join('/'); - return `${relativePath}#${anchor}`; - } - } - - return `${pagePath}#${anchor}`; + // Cross-page: use absolute path with API_DOCS_PATH prefix + return `/${API_DOCS_PATH}/${pagePath}#${anchor}`; } // Process {REF} and other references @@ -219,7 +208,13 @@ function processReferences(content, links) { return replacement || `\`${key}\``; }); - return cleanupContent(result); + result = cleanupContent(result); + + // Escape bare < that aren't HTML/JSX tags (e.g., "< 0x80", "< 128") + // Must run after cleanupContent (which decodes < to <) and before processCallouts + result = result.replace(/(<)(\s+\w)/g, '<$2'); + + return result; } function resolveReference(refId, links) { @@ -249,39 +244,43 @@ function resolveReference(refId, links) { } function findBestMatch(key, links) { - let replacement = links[key]; + // Exact match first + if (links[key]) { + return links[key]; + } - if (!replacement) { - // Strategy 1: Look for keys that end with this key - let matchingKeys = Object.keys(links).filter(linkKey => { - const parts = linkKey.split('-'); - return parts.length >= 2 && parts[parts.length - 1] === key; - }); + const linkPages = links.__linkPages || {}; + const currentPagePath = links.__currentPagePath || ''; - // Strategy 2: Try with different separators - if (matchingKeys.length === 0) { - const keyWithDashes = key.replace(/\./g, '-'); - matchingKeys = Object.keys(links).filter(linkKey => linkKey.includes(keyWithDashes)); - } + // Match by contract function name (e.g., {transfer} matches ERC20-transfer) + // Only match if the key is the final segment after the last hyphen + const matchingKeys = Object.keys(links).filter(linkKey => { + if (linkKey.startsWith('__')) return false; // skip metadata keys + const parts = linkKey.split('-'); + return parts.length >= 2 && parts[parts.length - 1] === key; + }); - // Strategy 3: Try partial matches - if (matchingKeys.length === 0) { - matchingKeys = Object.keys(links).filter(linkKey => { - return linkKey === key || linkKey.endsWith('-' + key) || linkKey.includes(key); - }); + if (matchingKeys.length > 0) { + const nonXrefMatches = matchingKeys.filter(k => !k.startsWith('xref-')); + const candidates = nonXrefMatches.length > 0 ? nonXrefMatches : matchingKeys; + + // Prefer matches from the same page (e.g., ERC20.name over Governor.name on the ERC20 page) + if (currentPagePath && candidates.length > 1) { + const samePageMatch = candidates.find(k => linkPages[k] === currentPagePath); + if (samePageMatch) { + return links[samePageMatch]; + } } - if (matchingKeys.length > 0) { - const nonXrefMatches = matchingKeys.filter(k => !k.startsWith('xref-')); - const bestMatch = nonXrefMatches.length > 0 ? nonXrefMatches[0] : matchingKeys[0]; - replacement = links[bestMatch]; - } + return links[candidates[0]]; } - return replacement; + return undefined; } function cleanupContent(content) { + const apiDocsBase = '/' + API_DOCS_PATH; + const docsBase = apiDocsBase.replace(/\/api$/, ''); return content .replace(/</g, '<') .replace(/>/g, '>') @@ -295,7 +294,26 @@ function cleanupContent(content) { .replace(/https?:\/\/[^\s[]+\[[^\]]+\]/g, match => { const urlMatch = match.match(/^(https?:\/\/[^[]+)\[([^\]]+)\]$/); return urlMatch ? `[${urlMatch[2]}](${urlMatch[1]})` : match; - }); + }) + // Convert remaining Antora xref patterns in natspec + // xref:ROOT:filename.adoc#anchor[text] -> [text](docsBase/filename#anchor) + .replace(/xref:ROOT:([^[]+)\.adoc(?:#([^[]*))?\[([^\]]*)\]/g, (_, file, anchor, text) => + `[${text}](${docsBase}/${file}${anchor ? '#' + anchor : ''})`) + // xref:api:filename.adoc#anchor[text] -> [text](apiDocsBase/filename#anchor) + .replace(/xref:api:([^[]+)\.adoc(?:#([^[]*))?\[([^\]]*)\]/g, (_, file, anchor, text) => + `[${text}](${apiDocsBase}/${file}${anchor ? '#' + anchor : ''})`) + // xref:module::filename.adoc[text] -> [text](docsBase/module/filename) + // Modules like "learn" are relative to the product docs base, not site root + .replace(/xref:([a-z-]+)::([^[]+)\.adoc(?:#([^[]*))?\[([^\]]*)\]/g, (_, mod, file, anchor, text) => { + // upgrades-plugins is a separate product at site root + const base = mod === 'upgrades-plugins' ? '' : docsBase; + return `[${text}](${base}/${mod}/${file}${anchor ? '#' + anchor : ''})`; + }) + // xref:filename.adoc#anchor[text] -> [text](apiDocsBase/filename#anchor) (bare, within API context) + .replace(/xref:([^:[\s]+)\.adoc(?:#([^[]*))?\[([^\]]*)\]/g, (_, file, anchor, text) => + `[${text}](${apiDocsBase}/${file}${anchor ? '#' + anchor : ''})`) + // Strip /index from links + .replace(/\/index([#)])/g, '$1'); } function processAdocContent(content) { @@ -325,8 +343,22 @@ function processAdocContent(content) { let mdContent = fs.readFileSync(tempMdFile, 'utf8'); // Clean up and transform markdown, then process callouts once at the end + // Convert Antora xref patterns that downdoc turns into markdown links + const apiDocsBase = '/' + API_DOCS_PATH; + const docsBase = apiDocsBase.replace(/\/api$/, ''); mdContent = cleanupContent(mdContent) - .replace(/\(api:([^)]+)\.adoc([^)]*)\)/g, `(${API_DOCS_PATH}/$1.mdx$2)`) + // api:filename.adoc#anchor -> /contracts/5.x/api/filename#anchor + .replace(/\(api:([^)]+)\.adoc([^)]*)\)/g, `(${apiDocsBase}/$1$2)`) + // ROOT:filename.adoc -> docs base (non-API pages like guides) + .replace(/\(ROOT:([^)]+)\.adoc([^)]*)\)/g, `(${docsBase}/$1$2)`) + // upgrades-plugins::filename.adoc -> /upgrades-plugins/filename + .replace(/\(upgrades-plugins::([^)]+)\.adoc([^)]*)\)/g, '(/upgrades-plugins/$1$2)') + // Strip /index from links (Fumadocs routes index.mdx as the directory root) + .replace(/\/index([#)])/g, '$1') + // governance.adoc#anchor -> /contracts/5.x/api/governance#anchor (within API context) + .replace(/\(([a-z0-9-]+)\.adoc(#[^)]*)\)/g, `(${apiDocsBase}/$1$2)`) + // Clean up any remaining bare .adoc references + .replace(/([a-z0-9-]+)\.adoc/g, '$1') .replace(/!\[([^\]]*)\]\(([^/)][^)]*\.(png|jpg|jpeg|gif|svg|webp))\)/g, '![$1](/$2)') .replace(/^#+\s+.+$/m, '') .replace(/^\n+/, ''); @@ -351,8 +383,14 @@ function processAdocContent(content) { } function processCallouts(content) { - // First, normalize whitespace around block delimiters to make patterns more consistent - let result = content.replace(/\s*\n====\s*\n/g, '\n====\n').replace(/\n====\s*\n/g, '\n====\n'); + // Convert AsciiDoc headings in natspec (==== heading -> #### heading) + // Must come BEFORE block delimiter normalization + let result = content.replace(/^={4}\s+(.+)$/gm, '#### $1'); + result = result.replace(/^={3}\s+(.+)$/gm, '### $1'); + result = result.replace(/^={2}\s+(.+)$/gm, '## $1'); + + // Normalize whitespace around block delimiters to make patterns more consistent + result = result.replace(/\s*\n====\s*\n/g, '\n====\n').replace(/\n====\s*\n/g, '\n====\n'); // Handle AsciiDoc block admonitions (with ====) result = result.replace(/^\[(NOTE|TIP)\]\s*\n====\s*\n([\s\S]*?)\n====$/gm, '\n$2\n'); @@ -361,9 +399,9 @@ function processCallouts(content) { '\n$2\n', ); - // Handle simple single-line admonitions - result = result.replace(/^(NOTE|TIP):\s*(.+)$/gm, '\n$2\n'); - result = result.replace(/^(IMPORTANT|WARNING):\s*(.+)$/gm, '\n$2\n'); + // Handle single/multi-line admonitions (NOTE: content until blank line) + result = result.replace(/^(NOTE|TIP):\s*([\s\S]*?)(?=\n\n|$)/gm, '\n$2\n'); + result = result.replace(/^(IMPORTANT|WARNING|CAUTION):\s*([\s\S]*?)(?=\n\n|$)/gm, '\n$2\n'); // Handle markdown-style bold admonitions (the ones you're seeing) result = result.replace( @@ -407,6 +445,9 @@ function processCallouts(content) { // Remove callouts that only contain whitespace/newlines result = result.replace(/]*>\s*\n\s*<\/Callout>/g, ''); + // Remove any remaining standalone ==== block delimiters (orphaned from callout processing) + result = result.replace(/^====\s*$/gm, ''); + return result; } diff --git a/examples/AccessManagerEnumerable.sol b/examples/AccessManagerEnumerable.sol new file mode 100644 index 00000000..78640b4c --- /dev/null +++ b/examples/AccessManagerEnumerable.sol @@ -0,0 +1,161 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.24; + +import {AccessManager} from "@openzeppelin/contracts/access/manager/AccessManager.sol"; +import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol"; + +/** + * @dev Extension of {AccessManager} that allows enumerating the members of each role + * and the target functions each role is allowed to call. + * + * NOTE: Given {ADMIN_ROLE} is the default role for every restricted function, the + * {getRoleTargetFunctions} and {getRoleTargetFunctionCount} functions will return an empty array + * and 0 respectively. + */ +abstract contract AccessManagerEnumerable is AccessManager { + using EnumerableSet for EnumerableSet.AddressSet; + using EnumerableSet for EnumerableSet.Bytes4Set; + + mapping(uint64 roleId => EnumerableSet.AddressSet) private _roleMembers; + mapping(uint64 roleId => mapping(address target => EnumerableSet.Bytes4Set)) private _roleTargetFunctions; + + /** + * @dev Returns the number of accounts that have `roleId`. Can be used + * together with {getRoleMember} to enumerate all bearers of a role. + */ + function getRoleMemberCount(uint64 roleId) public view virtual returns (uint256) { + return _roleMembers[roleId].length(); + } + + /** + * @dev Returns one of the accounts that have `roleId`. `index` must be a + * value between 0 and {getRoleMemberCount}, non-inclusive. + * + * Role bearers are not sorted in any particular way, and their ordering may change at any point. + * + * WARNING: When using {getRoleMember} and {getRoleMemberCount}, make sure + * you perform all queries on the same block. See the following + * https://forum.openzeppelin.com/t/iterating-over-elements-on-enumerableset-in-openzeppelin-contracts/2296[forum post] + * for more information. + */ + function getRoleMember(uint64 roleId, uint256 index) public view virtual returns (address) { + return _roleMembers[roleId].at(index); + } + + /** + * @dev Returns a range of accounts that have `roleId`. `start` and `end` define the range bounds. + * `start` is inclusive and `end` is exclusive. + * + * Role bearers are not sorted in any particular way, and their ordering may change at any point. + * + * It is not necessary to call {getRoleMemberCount} before calling this function. Using `start = 0` and + * `end = type(uint256).max` will return every member of `roleId`. + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function getRoleMembers(uint64 roleId, uint256 start, uint256 end) public view virtual returns (address[] memory) { + return _roleMembers[roleId].values(start, end); + } + + /** + * @dev Returns the number of target function selectors that require `roleId` for the given `target`. + * Can be used together with {getRoleTargetFunction} to enumerate all target functions for a role on a specific target. + * + * NOTE: Given {ADMIN_ROLE} is the default role for every restricted function, passing {ADMIN_ROLE} as `roleId` will + * return 0. See {_updateRoleTargetFunction} for more details. + */ + function getRoleTargetFunctionCount(uint64 roleId, address target) public view virtual returns (uint256) { + return _roleTargetFunctions[roleId][target].length(); + } + + /** + * @dev Returns one of the target function selectors that require `roleId` for the given `target`. + * `index` must be a value between 0 and {getRoleTargetFunctionCount}, non-inclusive. + * + * Target function selectors are not sorted in any particular way, and their ordering may change at any point. + * + * WARNING: When using {getRoleTargetFunction} and {getRoleTargetFunctionCount}, make sure + * you perform all queries on the same block. See the following + * https://forum.openzeppelin.com/t/iterating-over-elements-on-enumerableset-in-openzeppelin-contracts/2296[forum post] + * for more information. + */ + function getRoleTargetFunction(uint64 roleId, address target, uint256 index) public view virtual returns (bytes4) { + return _roleTargetFunctions[roleId][target].at(index); + } + + /** + * @dev Returns a range of target function selectors that require `roleId` for the given `target`. + * `start` and `end` define the range bounds. `start` is inclusive and `end` is exclusive. + * + * Target function selectors are not sorted in any particular way, and their ordering may change at any point. + * + * It is not necessary to call {getRoleTargetFunctionCount} before calling this function. Using `start = 0` and + * `end = type(uint256).max` will return every function selector that `roleId` is allowed to call on `target`. + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + * + * NOTE: Given {ADMIN_ROLE} is the default role for every restricted function, passing {ADMIN_ROLE} as `roleId` will + * return an empty array. See {_updateRoleTargetFunction} for more details. + */ + function getRoleTargetFunctions( + uint64 roleId, + address target, + uint256 start, + uint256 end + ) public view virtual returns (bytes4[] memory) { + return _roleTargetFunctions[roleId][target].values(start, end); + } + + /// @dev See {AccessManager-_grantRole}. Adds the account to the role members set. + function _grantRole( + uint64 roleId, + address account, + uint32 grantDelay, + uint32 executionDelay + ) internal virtual override returns (bool) { + bool granted = super._grantRole(roleId, account, grantDelay, executionDelay); + if (granted) { + _roleMembers[roleId].add(account); + } + return granted; + } + + /// @dev See {AccessManager-_revokeRole}. Removes the account from the role members set. + function _revokeRole(uint64 roleId, address account) internal virtual override returns (bool) { + bool revoked = super._revokeRole(roleId, account); + if (revoked) { + _roleMembers[roleId].remove(account); + } + return revoked; + } + + /** + * @dev See {AccessManager-_setTargetFunctionRole}. Adds the selector to the role target functions set. + * + * NOTE: This function does not track function selectors for the {ADMIN_ROLE}, since exhaustively tracking + * all restricted/admin functions is impractical (by default, all restricted functions are assigned to {ADMIN_ROLE}). + * Therefore, roles assigned as {ADMIN_ROLE} will not have their selectors included in this extension's tracking. + */ + function _setTargetFunctionRole(address target, bytes4 selector, uint64 roleId) internal virtual override { + // cache old role ID + uint64 oldRoleId = getTargetFunctionRole(target, selector); + + // call super + super._setTargetFunctionRole(target, selector, roleId); + + // update enumerable sets + if (oldRoleId != ADMIN_ROLE) { + _roleTargetFunctions[oldRoleId][target].remove(selector); + } + if (roleId != ADMIN_ROLE) { + _roleTargetFunctions[roleId][target].add(selector); + } + } +} diff --git a/examples/ERC4626Fees.sol b/examples/ERC4626Fees.sol index 1c2f79ec..3be58174 100644 --- a/examples/ERC4626Fees.sol +++ b/examples/ERC4626Fees.sol @@ -45,7 +45,7 @@ abstract contract ERC4626Fees is ERC4626 { return assets - _feeOnTotal(assets, _exitFeeBasisPoints()); } - /// @dev Send entry fee to {_entryFeeRecipient}. See {IERC4626-_deposit}. + /// @dev Send entry fee to {_entryFeeRecipient}. See {ERC4626-_deposit}. function _deposit(address caller, address receiver, uint256 assets, uint256 shares) internal virtual override { uint256 fee = _feeOnTotal(assets, _entryFeeBasisPoints()); address recipient = _entryFeeRecipient(); @@ -57,7 +57,7 @@ abstract contract ERC4626Fees is ERC4626 { } } - /// @dev Send exit fee to {_exitFeeRecipient}. See {IERC4626-_deposit}. + /// @dev Send exit fee to {_exitFeeRecipient}. See {ERC4626-_withdraw}. function _withdraw( address caller, address receiver, diff --git a/examples/account/MyAccountEIP7702.sol b/examples/account/MyAccountEIP7702.sol new file mode 100644 index 00000000..9e7893ef --- /dev/null +++ b/examples/account/MyAccountEIP7702.sol @@ -0,0 +1,20 @@ +// contracts/MyAccountEIP7702.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Account} from "@openzeppelin/contracts/account/Account.sol"; +import {ERC7821} from "@openzeppelin/contracts/account/extensions/draft-ERC7821.sol"; +import {SignerEIP7702} from "@openzeppelin/contracts/utils/cryptography/signers/SignerEIP7702.sol"; +import {ERC721Holder} from "@openzeppelin/contracts/token/ERC721/utils/ERC721Holder.sol"; +import {ERC1155Holder} from "@openzeppelin/contracts/token/ERC1155/utils/ERC1155Holder.sol"; + +contract MyAccountEIP7702 is Account, SignerEIP7702, ERC7821, ERC721Holder, ERC1155Holder { + /// @dev Allows the entry point as an authorized executor. + function _erc7821AuthorizedExecutor( + address caller, + bytes32 mode, + bytes calldata executionData + ) internal view virtual override returns (bool) { + return caller == address(entryPoint()) || super._erc7821AuthorizedExecutor(caller, mode, executionData); + } +} diff --git a/examples/account/MyFactoryAccount.sol b/examples/account/MyFactoryAccount.sol index d095260c..4f1fd736 100644 --- a/examples/account/MyFactoryAccount.sol +++ b/examples/account/MyFactoryAccount.sol @@ -16,22 +16,32 @@ contract MyFactoryAccount { address private immutable _impl; constructor(address impl_) { - require(impl_.code.length > 0); _impl = impl_; } /// @dev Predict the address of the account - function predictAddress(bytes calldata callData) public view returns (address) { - return _impl.predictDeterministicAddress(keccak256(callData), address(this)); + function predictAddress(bytes32 salt, bytes calldata callData) public view returns (address, bytes32) { + bytes32 calldataSalt = _saltedCallData(salt, callData); + return (_impl.predictDeterministicAddress(calldataSalt, address(this)), calldataSalt); } /// @dev Create clone accounts on demand - function cloneAndInitialize(bytes calldata callData) public returns (address) { - address predicted = predictAddress(callData); + function cloneAndInitialize(bytes32 salt, bytes calldata callData) public returns (address) { + return _cloneAndInitialize(salt, callData); + } + + /// @dev Create clone accounts on demand and return the address. Uses `callData` to initialize the clone. + function _cloneAndInitialize(bytes32 salt, bytes calldata callData) internal returns (address) { + (address predicted, bytes32 _calldataSalt) = predictAddress(salt, callData); if (predicted.code.length == 0) { - _impl.cloneDeterministic(keccak256(callData)); + _impl.cloneDeterministic(_calldataSalt); predicted.functionCall(callData); } return predicted; } + + function _saltedCallData(bytes32 salt, bytes calldata callData) internal pure returns (bytes32) { + // Scope salt to the callData to avoid front-running the salt with a different callData + return keccak256(abi.encodePacked(salt, callData)); + } } diff --git a/examples/crosschain/MyERC7786GatewaySource.sol b/examples/crosschain/MyERC7786GatewaySource.sol index 95f3127f..b643b4da 100644 --- a/examples/crosschain/MyERC7786GatewaySource.sol +++ b/examples/crosschain/MyERC7786GatewaySource.sol @@ -2,7 +2,7 @@ // SPDX-License-Identifier: MIT pragma solidity ^0.8.24; -import {IERC7786GatewaySource} from "@openzeppelin/community-contracts/interfaces/IERC7786.sol"; +import {IERC7786GatewaySource} from "@openzeppelin/contracts/interfaces/draft-IERC7786.sol"; import {InteroperableAddress} from "@openzeppelin/contracts/utils/draft-InteroperableAddress.sol"; abstract contract MyERC7786GatewaySource is IERC7786GatewaySource { diff --git a/scripts/generate-api-docs.js b/scripts/generate-api-docs.js index d7c41c62..ad0b375c 100755 --- a/scripts/generate-api-docs.js +++ b/scripts/generate-api-docs.js @@ -2,18 +2,25 @@ import { promises as fs } from "node:fs"; import path from "node:path"; -import { execSync } from "node:child_process"; +import { execSync, execFileSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); +const DOCGEN_DIR = path.join(__dirname, "..", "docgen"); // Parse command line arguments function parseArgs() { const args = process.argv.slice(2); const options = { contractsRepo: - "https://github.com/stevedylandev/openzeppelin-contracts.git", + "https://github.com/OpenZeppelin/openzeppelin-contracts.git", contractsBranch: "master", tempDir: "temp-contracts", apiOutputDir: "content/contracts/5.x/api", examplesOutputDir: "examples", + skipTemplateInject: false, + preGenerated: null, }; for (let i = 0; i < args.length; i++) { @@ -44,6 +51,13 @@ function parseArgs() { case "-e": options.examplesOutputDir = args[++i]; break; + case "--skip-template-inject": + options.skipTemplateInject = true; + break; + case "--pre-generated": + case "-p": + options.preGenerated = args[++i]; + break; default: console.error(`Unknown option: ${arg}`); showHelp(); @@ -61,20 +75,142 @@ Generate OpenZeppelin Contracts API documentation Usage: node generate-api-docs.js [options] Options: - -r, --repo Contracts repository URL (default: https://github.com/OpenZeppelin/openzeppelin-contracts.git) + -r, --repo Contracts repository URL or local path -b, --branch Contracts repository branch (default: master) -t, --temp-dir Temporary directory for cloning (default: temp-contracts) - -a, --api-output API documentation output directory (default: content/contracts/v5.x/api) + -a, --api-output API documentation output directory (default: content/contracts/5.x/api) -e, --examples-output Examples output directory (default: examples) + -p, --pre-generated Path within repo containing pre-generated MDX files (skips docgen) + --skip-template-inject Skip injecting canonical templates (use source repo's own) -h, --help Show this help message +Modes: + Default (Solidity repos): Injects canonical templates, runs hardhat docgen, copies output + --pre-generated (other): Skips docgen entirely, copies pre-generated MDX from source repo + Examples: - node generate-api-docs.js - node generate-api-docs.js --repo https://github.com/myorg/contracts.git --branch v4.0 - node generate-api-docs.js --api-output content/contracts/v4.x/api --examples-output examples-v4 + # Solidity repo (injects templates, runs docgen): + node generate-api-docs.js --repo https://github.com/OpenZeppelin/openzeppelin-contracts.git --api-output content/contracts/5.x/api + + # Non-Solidity repo (copies pre-generated MDX): + node generate-api-docs.js --repo https://github.com/OpenZeppelin/cairo-contracts.git --api-output content/contracts-cairo/3.x/api --pre-generated docs/api `); } +// Extract GitHub org/repo from a repo URL or path +function extractRepoInfo(repoPath) { + // Handle GitHub URLs + const githubMatch = repoPath.match( + /github\.com\/([^/]+)\/([^/.]+)/, + ); + if (githubMatch) { + return { org: githubMatch[1], repo: githubMatch[2] }; + } + // Handle local paths - extract from directory name + const dirName = path.basename(repoPath.replace(/\/+$/, "")); + return { org: "OpenZeppelin", repo: dirName }; +} + +// Derive the npm package name from the repo name +function derivePackageName(repoName) { + // openzeppelin-contracts -> @openzeppelin/contracts + // openzeppelin-community-contracts -> @openzeppelin/community-contracts + // openzeppelin-confidential-contracts -> @openzeppelin/confidential-contracts + const withoutPrefix = repoName.replace(/^openzeppelin-/, ""); + return withoutPrefix; +} + +async function injectTemplates(tempDir, options) { + const { contractsRepo, apiOutputDir } = options; + const repoInfo = extractRepoInfo(contractsRepo); + const packageName = derivePackageName(repoInfo.repo); + + console.log("๐Ÿ“‹ Injecting canonical MDX templates..."); + + const templatesTarget = path.join(tempDir, "docs", "templates-md"); + const configTarget = path.join(tempDir, "docs", "config-md.js"); + + // Copy canonical templates + await fs.mkdir(templatesTarget, { recursive: true }); + await copyDirRecursive( + path.join(DOCGEN_DIR, "templates-md"), + templatesTarget, + ); + + // Copy canonical config (as config-md.js and also overwrite config.js + // so prepare-docs.sh scripts that read config.js directly still work) + await fs.copyFile(path.join(DOCGEN_DIR, "config-md.js"), configTarget); + const configJsTarget = path.join(tempDir, "docs", "config.js"); + await fs.copyFile(path.join(DOCGEN_DIR, "config-md.js"), configJsTarget); + + // Customize API_DOCS_PATH in helpers.js + // API_DOCS_PATH is the URL path (strip content/ prefix from the file path) + const apiDocsPath = apiOutputDir.replace(/^content\//, ""); + const helpersPath = path.join(templatesTarget, "helpers.js"); + let helpers = await fs.readFile(helpersPath, "utf8"); + helpers = helpers.replace( + /const API_DOCS_PATH = '[^']+'/, + `const API_DOCS_PATH = '${apiDocsPath}'`, + ); + await fs.writeFile(helpersPath, helpers, "utf8"); + console.log(` โœ“ API_DOCS_PATH set to '${apiDocsPath}'`); + + // Customize GitHub link and import path in contract.hbs + const contractPath = path.join(templatesTarget, "contract.hbs"); + let contract = await fs.readFile(contractPath, "utf8"); + + // Update GitHub link: just replace the org/repo part, keep v{{oz-version}} for versioned repos + contract = contract.replace( + /OpenZeppelin\/openzeppelin-contracts/g, + `${repoInfo.org}/${repoInfo.repo}`, + ); + + // Update import path: the canonical template has @openzeppelin/{{absolutePath}} + // where absolutePath starts with "contracts/...". For the main contracts repo + // this produces @openzeppelin/contracts/token/... which is correct. + // For community-contracts, we need @openzeppelin/community-contracts/contracts/token/... + // So only patch if the package name isn't just "contracts" + if (packageName !== "contracts") { + contract = contract.replace( + /import "@openzeppelin\/\{\{/, + `import "@openzeppelin/${packageName}/{{`, + ); + } + await fs.writeFile(contractPath, contract, "utf8"); + console.log( + ` โœ“ GitHub link set to ${repoInfo.org}/${repoInfo.repo}`, + ); + console.log( + ` โœ“ Import path set to @openzeppelin/${packageName}/`, + ); + + // Patch hardhat config to use config-md + const hardhatConfigPaths = [ + path.join(tempDir, "hardhat.config.js"), + path.join(tempDir, "hardhat.config.ts"), + ]; + + for (const configPath of hardhatConfigPaths) { + try { + let config = await fs.readFile(configPath, "utf8"); + if (config.includes("require('./docs/config')")) { + config = config.replace( + "require('./docs/config')", + "require('./docs/config-md')", + ); + await fs.writeFile(configPath, config, "utf8"); + console.log(` โœ“ Patched ${path.basename(configPath)} to use config-md`); + } else if (config.includes("require('./docs/config-md')")) { + console.log( + ` โœ“ ${path.basename(configPath)} already uses config-md`, + ); + } + } catch { + // Config file doesn't exist, skip + } + } +} + async function generateApiDocs(options) { const { contractsRepo, @@ -82,13 +218,19 @@ async function generateApiDocs(options) { tempDir, apiOutputDir, examplesOutputDir, + skipTemplateInject, + preGenerated, } = options; - console.log("๐Ÿ”„ Generating OpenZeppelin Contracts API documentation..."); + console.log("๐Ÿ”„ Generating OpenZeppelin API documentation..."); console.log(`๐Ÿ“ฆ Repository: ${contractsRepo}`); console.log(`๐ŸŒฟ Branch: ${contractsBranch}`); console.log(`๐Ÿ“‚ API Output: ${apiOutputDir}`); - console.log(`๐Ÿ“‚ Examples Output: ${examplesOutputDir}`); + if (preGenerated) { + console.log(`๐Ÿ“‹ Mode: pre-generated (source path: ${preGenerated})`); + } else { + console.log(`๐Ÿ“‚ Examples Output: ${examplesOutputDir}`); + } try { // Back up index.mdx if it exists @@ -109,15 +251,48 @@ async function generateApiDocs(options) { // Create output directory await fs.mkdir(apiOutputDir, { recursive: true }); - // Clone the contracts repository - console.log("๐Ÿ“ฆ Cloning contracts repository..."); - execSync( - `git clone --depth 1 --revision "${contractsBranch}" --recurse-submodules "${contractsRepo}" "${tempDir}"`, - { - stdio: "inherit", - }, + // Clone the repository (works for both URLs and local paths) + console.log("๐Ÿ“ฆ Cloning repository..."); + execFileSync( + "git", + ["clone", "--depth", "1", "--branch", contractsBranch, "--recurse-submodules", contractsRepo, tempDir], + { stdio: "inherit" }, ); + // Pre-generated mode: just copy MDX files from source repo, skip docgen + if (preGenerated) { + const sourcePath = path.join(tempDir, preGenerated); + try { + await fs.access(sourcePath); + await copyDirRecursive(sourcePath, apiOutputDir); + console.log(`โœ… Pre-generated docs copied from ${preGenerated}`); + } catch (error) { + console.log( + `โŒ Error: Pre-generated docs not found at ${preGenerated}`, + ); + process.exit(1); + } + + // Restore index.mdx if backed up + if (indexBackup) { + console.log("โ™ป๏ธ Restoring index.mdx..."); + await fs.writeFile(indexPath, indexBackup, "utf8"); + } + + // Clean up + console.log("๐Ÿงน Cleaning up..."); + await fs.rm(tempDir, { recursive: true, force: true }); + + console.log("๐ŸŽ‰ API documentation generation complete!"); + console.log(`๐Ÿ“‚ Documentation available in: ${apiOutputDir}`); + return; + } + + // Solidity docgen mode: inject templates and run generation + if (!skipTemplateInject) { + await injectTemplates(tempDir, options); + } + // Navigate to contracts directory and install dependencies console.log("๐Ÿ“š Installing dependencies..."); const originalDir = process.cwd(); @@ -126,11 +301,11 @@ async function generateApiDocs(options) { try { execSync("npm install --silent", { stdio: "inherit" }); - // Generate markdown documentation - console.log("๐Ÿ—๏ธ Generating clean markdown documentation..."); + // Generate MDX documentation + console.log("๐Ÿ—๏ธ Generating MDX documentation..."); execSync("npm run prepare-docs", { stdio: "inherit" }); - // Copy generated markdown files + // Copy generated files console.log("๐Ÿ“‹ Copying generated documentation..."); const docsPath = path.join("docs", "modules", "api", "pages"); @@ -143,7 +318,7 @@ async function generateApiDocs(options) { console.log(`โœ… API documentation copied to ${apiOutputDir}`); } catch (error) { console.log( - "โŒ Error: Markdown documentation not found at expected location", + "โŒ Error: Documentation not found at expected location", ); process.exit(1); } @@ -164,32 +339,6 @@ async function generateApiDocs(options) { ); console.log(`โœ… Examples copied to ${examplesOutputDir}`); } - - // Get version for index file - let version = "latest"; - try { - const packageJson = JSON.parse( - await fs.readFile("package.json", "utf8"), - ); - version = packageJson.version || version; - } catch (error) { - console.log("โš ๏ธ Could not read package.json for version info"); - } - - // Generate index file - // console.log("๐Ÿ“ Generating API index..."); - // const indexContent = `--- - // title: API Reference - // --- - - // # API Reference - // `; - - // await fs.writeFile( - // path.join(originalDir, apiOutputDir, "index.mdx"), - // indexContent, - // "utf8", - // ); } finally { // Go back to original directory process.chdir(originalDir); @@ -207,10 +356,6 @@ async function generateApiDocs(options) { console.log("๐ŸŽ‰ API documentation generation complete!"); console.log(`๐Ÿ“‚ Documentation available in: ${apiOutputDir}`); - console.log(""); - console.log("Next steps:"); - console.log(` - Review generated markdown files in ${apiOutputDir}`); - console.log(" - Update the api/index.mdx file with your TOC"); } catch (error) { console.error("โŒ Error generating API documentation:", error.message); process.exit(1); @@ -218,14 +363,29 @@ async function generateApiDocs(options) { } async function copyDirRecursive(src, dest) { + await fs.mkdir(dest, { recursive: true }); const entries = await fs.readdir(src, { withFileTypes: true }); for (const entry of entries) { const srcPath = path.join(src, entry.name); const destPath = path.join(dest, entry.name); - if (entry.isDirectory()) { - await fs.mkdir(destPath, { recursive: true }); + if (entry.isSymbolicLink()) { + // Resolve symlink and copy the target; skip broken symlinks + try { + const realPath = await fs.realpath(srcPath); + const stat = await fs.stat(realPath); + if (stat.isDirectory()) { + await copyDirRecursive(realPath, destPath); + } else { + await fs.copyFile(realPath, destPath); + } + } catch { + // Broken symlink, skip + } + } else if (entry.isDirectory()) { + // Skip node_modules and .git when copying local repos + if (entry.name === "node_modules" || entry.name === ".git") continue; await copyDirRecursive(srcPath, destPath); } else { await fs.copyFile(srcPath, destPath);