From 124946fe1edc139a61d699f67bd73360a6820d23 Mon Sep 17 00:00:00 2001
From: stevep0z <255929980+stevep0z@users.noreply.github.com>
Date: Thu, 2 Apr 2026 10:22:05 -0500
Subject: [PATCH 01/11] fix: update docgen templates with strict reference
matching and output fixes
- Remove fuzzy reference matching that caused cross-standard contamination
(e.g., ERC20 constructor referencing Governor.name, IERC6909Metadata.symbol)
- Add same-page preference so {name} on an ERC20 page resolves to ERC20.name
- Use absolute paths for cross-page links via API_DOCS_PATH
- Fix multi-line callout handling (NOTE: blocks spanning multiple lines)
- Escape bare < in natspec (e.g., < 0x80) to prevent MDX parse errors
- Convert Antora xref patterns to markdown links
- Convert AsciiDoc headings (====) to markdown (####)
- Clean up orphaned block delimiters
- Strip /index from links for Fumadocs compatibility
---
docgen/templates-md/helpers.js | 155 +++++++++++++++++++++------------
1 file changed, 98 insertions(+), 57 deletions(-)
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, '')
.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;
}
From 34b09b738903cabfcfaf6695e3fa84f90692ba8a Mon Sep 17 00:00:00 2001
From: stevep0z <255929980+stevep0z@users.noreply.github.com>
Date: Thu, 2 Apr 2026 10:22:17 -0500
Subject: [PATCH 02/11] docs: regenerate API reference for contracts 5.x and
community-contracts
Regenerated from openzeppelin-contracts (master) and
openzeppelin-community-contracts (master) using updated docgen templates.
- All cross-page links use absolute paths
- No cross-standard contamination in reference resolution
- No legacy AsciiDoc patterns in output
- 0 link validation errors
---
content/community-contracts/api/access.mdx | 5 +-
content/community-contracts/api/account.mdx | 127 +-
.../community-contracts/api/crosschain.mdx | 203 +-
.../community-contracts/api/governance.mdx | 472 ++
content/community-contracts/api/index.mdx | 23 +-
.../community-contracts/api/interfaces.mdx | 493 ++-
content/community-contracts/api/proxy.mdx | 9 +-
content/community-contracts/api/token.mdx | 279 +-
content/community-contracts/api/utils.mdx | 47 +-
.../api/utils/cryptography.mdx | 304 +-
content/contracts/5.x/api/access.mdx | 390 +-
content/contracts/5.x/api/account.mdx | 155 +-
content/contracts/5.x/api/crosschain.mdx | 1880 +++++++-
content/contracts/5.x/api/finance.mdx | 9 +-
content/contracts/5.x/api/governance.mdx | 389 +-
content/contracts/5.x/api/interfaces.mdx | 3876 +++++++++--------
content/contracts/5.x/api/metatx.mdx | 49 +-
content/contracts/5.x/api/proxy.mdx | 1054 ++---
content/contracts/5.x/api/token/ERC1155.mdx | 325 +-
content/contracts/5.x/api/token/ERC20.mdx | 3443 ++++++++-------
content/contracts/5.x/api/token/ERC6909.mdx | 123 +-
content/contracts/5.x/api/token/ERC721.mdx | 386 +-
content/contracts/5.x/api/token/common.mdx | 5 +-
content/contracts/5.x/api/utils.mdx | 2742 ++++++++----
.../contracts/5.x/api/utils/cryptography.mdx | 460 +-
25 files changed, 10774 insertions(+), 6474 deletions(-)
create mode 100644 content/community-contracts/api/governance.mdx
diff --git a/content/community-contracts/api/access.mdx b/content/community-contracts/api/access.mdx
index 6f9659b3..6023bc9c 100644
--- a/content/community-contracts/api/access.mdx
+++ b/content/community-contracts/api/access.mdx
@@ -5,7 +5,7 @@ description: "Smart contract access utilities and implementations"
This directory contains utility contracts to restrict access control in smart contracts. These include:
-* [`AccessManagerLight`](#AccessManagerLight): A simpler version of an AccessManager that uses `bytes8` roles to allow function calls identified by their 4-bytes selector.
+- [`AccessManagerLight`](#AccessManagerLight): A simpler version of an AccessManager that uses `bytes8` roles to allow function calls identified by their 4-bytes selector.
## AccessManager
@@ -24,7 +24,7 @@ This directory contains utility contracts to restrict access control in smart co
```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
@@ -461,3 +461,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..ae6ac946 100644
--- a/content/community-contracts/api/account.mdx
+++ b/content/community-contracts/api/account.mdx
@@ -5,20 +5,20 @@ description: "Smart contract account utilities and implementations"
This directory includes contracts to build accounts for ERC-4337. These include:
-* [`ERC7579Executor`](#ERC7579Executor): An executor module that enables executing calls from accounts where the it’s installed.
-* [`ERC7579DelayedExecutor`](#ERC7579DelayedExecutor): An executor module that adds a delay before executing an account operation.
-* [`ERC7579SelectorExecutor`](#ERC7579SelectorExecutor): An executor module that restricts execution to specific function selectors.
-* [`ERC7579Validator`](#ERC7579Validator): Abstract validator module for ERC-7579 accounts that provides base implementation for signature validation.
-* [`ERC7579Signature`](#ERC7579Signature): Implementation of [`ERC7579Validator`](#ERC7579Validator) using ERC-7913 signature verification for address-less cryptographic keys and account signatures.
-* [`ERC7579Multisig`](#ERC7579Multisig): An extension of [`ERC7579Validator`](#ERC7579Validator) that enables validation using ERC-7913 signer keys.
-* [`ERC7579MultisigWeighted`](#ERC7579MultisigWeighted): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows different weights to be assigned to signers.
-* [`ERC7579MultisigConfirmation`](#ERC7579MultisigConfirmation): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that requires each signer to provide a confirmation signature.
-* [`ERC7579MultisigStorage`](#ERC7579MultisigStorage): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows storing presigned approvals in storage.
-* [`PaymasterCore`](#PaymasterCore): An ERC-4337 paymaster implementation that includes the core logic to validate and pay for user operations.
-* [`PaymasterERC20`](#PaymasterERC20): A paymaster that allows users to pay for user operations using ERC-20 tokens.
-* [`PaymasterERC20Guarantor`](#PaymasterERC20Guarantor): A paymaster that enables third parties to guarantee user operations by pre-funding gas costs, with the option for users to repay or for guarantors to absorb the cost.
-* [`PaymasterERC721Owner`](#PaymasterERC721Owner): A paymaster that allows users to pay for user operations based on ERC-721 ownership.
-* [`PaymasterSigner`](#PaymasterSigner): A paymaster that allows users to pay for user operations using an authorized signature.
+- [`ERC7579Executor`](#ERC7579Executor): An executor module that enables executing calls from accounts where the it's installed.
+- [`ERC7579DelayedExecutor`](#ERC7579DelayedExecutor): An executor module that adds a delay before executing an account operation.
+- [`ERC7579SelectorExecutor`](#ERC7579SelectorExecutor): An executor module that restricts execution to specific function selectors.
+- [`ERC7579Validator`](#ERC7579Validator): Abstract validator module for ERC-7579 accounts that provides base implementation for signature validation.
+- [`ERC7579Signature`](#ERC7579Signature): Implementation of [`ERC7579Validator`](#ERC7579Validator) using ERC-7913 signature verification for address-less cryptographic keys and account signatures.
+- [`ERC7579Multisig`](#ERC7579Multisig): An extension of [`ERC7579Validator`](#ERC7579Validator) that enables validation using ERC-7913 signer keys.
+- [`ERC7579MultisigWeighted`](#ERC7579MultisigWeighted): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows different weights to be assigned to signers.
+- [`ERC7579MultisigConfirmation`](#ERC7579MultisigConfirmation): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that requires each signer to provide a confirmation signature.
+- [`ERC7579MultisigStorage`](#ERC7579MultisigStorage): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows storing presigned approvals in storage.
+- [`PaymasterCore`](#PaymasterCore): An ERC-4337 paymaster implementation that includes the core logic to validate and pay for user operations.
+- [`PaymasterERC20`](#PaymasterERC20): A paymaster that allows users to pay for user operations using ERC-20 tokens.
+- [`PaymasterERC20Guarantor`](#PaymasterERC20Guarantor): A paymaster that enables third parties to guarantee user operations by pre-funding gas costs, with the option for users to repay or for guarantors to absorb the cost.
+- [`PaymasterERC721Owner`](#PaymasterERC721Owner): A paymaster that allows users to pay for user operations based on ERC-721 ownership.
+- [`PaymasterSigner`](#PaymasterSigner): A paymaster that allows users to pay for user operations using an authorized signature.
## Modules
@@ -69,13 +69,13 @@ This directory includes contracts to build accounts for ERC-4337. These include:
```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
@@ -106,8 +106,8 @@ authorization logic, such as requiring specific signers or roles.
Use [`ERC7579DelayedExecutor._scheduleAt`](#ERC7579DelayedExecutor-_scheduleAt-address-bytes32-bytes32-bytes-uint48-uint32-) to schedule operations at a specific points in time. This is
-useful to pre-schedule operations for non-deployed accounts (e.g. subscriptions).
+useful to pre-schedule operations for non-deployed accounts (e.g. subscriptions).
Functions
@@ -442,16 +442,16 @@ and respecting the previous delay and expiration values.
This function does not clean up scheduled operations. This means operations
+
could potentially be re-executed if the module is reinstalled later. This is a deliberate
design choice for efficiency, but module implementations may want to override this behavior
to clear scheduled operations during uninstallation for their specific use cases.
-
Calling this function directly will remove the expiration ([`ERC7579DelayedExecutor.getExpiration`](#ERC7579DelayedExecutor-getExpiration-address-)) value and
+
will schedule a reset of the delay ([`ERC7579DelayedExecutor.getDelay`](#ERC7579DelayedExecutor-getDelay-address-)) to `0` for the account. Reinstalling the
module will not immediately reset the delay if the delay reset hasn't taken effect yet.
-
@@ -472,9 +472,9 @@ Returns `data` as the execution calldata. See [`ERC7579Executor._execute`](#ERC7
This function relies on the operation state validation in [`ERC7579DelayedExecutor._execute`](#ERC7579DelayedExecutor-_execute-address-bytes32-bytes32-bytes-) for
+
authorization. Extensions of this module should override this function to implement
additional validation logic if needed.
-
@@ -804,7 +804,7 @@ The module is not installed on the account.
```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
@@ -817,9 +817,9 @@ derived contracts.
This is a simplified executor that directly executes operations without delay or expiration
+
mechanisms. For a more advanced implementation with time-delayed execution patterns and
security features, see [`ERC7579DelayedExecutor`](#ERC7579DelayedExecutor).
-
Functions
@@ -908,9 +908,9 @@ Example extension:
Pack extra data in the `data` arguments (e.g. a signature) to be used in the
+
validation process. Calldata can be sliced to extract it and return only the
execution calldata.
-
@@ -967,7 +967,7 @@ Emitted when an operation is executed.
```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
@@ -1060,8 +1060,8 @@ disabled until they are added later.
An account can only call onInstall once. If called directly by the account,
-the signer will be set to the provided data. Future installations will behave as a no-op.
+the signer will be set to the provided data. Future installations will behave as a no-op.
@@ -1085,8 +1085,8 @@ See [`ERC7579DelayedExecutor.onUninstall`](#ERC7579DelayedExecutor-onUninstall-b
This function has unbounded gas costs and may become uncallable if the set grows too large.
-See `EnumerableSet-clear`.
+See `EnumerableSet-clear`.
@@ -1109,9 +1109,9 @@ Using `start = 0` and `end = type(uint64).max` will return the entire set of sig
Depending on the `start` and `end`, this operation can copy a large amount of data to memory, which
+
can be expensive. This is designed for view accessors queried without gas fees. Using it in state-changing
functions may become uncallable if the slice grows too large.
-
@@ -1338,7 +1338,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:
@@ -1541,7 +1541,7 @@ The `threshold` is unreachable given the number of `signers`.
```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
@@ -1553,8 +1553,8 @@ consent to be added. Each signer must sign an EIP-712 message to confirm their a
Use this module to ensure that all guardians in a social recovery or multisig setup have
-explicitly agreed to their roles.
+explicitly agreed to their roles.
Functions
@@ -1720,7 +1720,7 @@ Error thrown when a confirmation signature has expired
```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.
@@ -1830,8 +1830,8 @@ signed, otherwise acts as a no-op.
Does not check if the signer is authorized for the account. Valid signatures from
-invalid signers won't be executable. See [`ERC7579Multisig._validateSignatures`](#ERC7579Multisig-_validateSignatures-address-bytes32-bytes---bytes---) for more details.
+invalid signers won't be executable. See [`ERC7579Multisig._validateSignatures`](#ERC7579Multisig-_validateSignatures-address-bytes32-bytes---bytes---) for more details.
@@ -1851,7 +1851,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.
@@ -1887,7 +1887,7 @@ Emitted when a signer signs a hash
```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.
@@ -1905,9 +1905,9 @@ after the time delay has passed.
When setting a threshold value, ensure it matches the scale used for signer weights.
+
For example, if signers have weights like 1, 2, or 3, then a threshold of 4 would require
signatures with a total weight of at least 4 (e.g., one with weight 1 and one with weight 3).
-
Functions
@@ -1996,8 +1996,8 @@ If weights are not provided but signers are, all signers default to weight 1.
An account can only call onInstall once. If called directly by the account,
-the signer will be set to the provided data. Future installations will behave as a no-op.
+the signer will be set to the provided data. Future installations will behave as a no-op.
@@ -2158,10 +2158,10 @@ Override to validate threshold against total weight instead of signer count.
This function intentionally does not call `super._validateReachableThreshold` because the base implementation
+
assumes each signer has a weight of 1, which is a subset of this weighted implementation. Consider that multiple
implementations of this function may exist in the contract, so important side effects may be missed
depending on the linearization order.
-
@@ -2183,8 +2183,8 @@ Overrides the base implementation to use weights instead of count.
This function intentionally does not call `super._validateThreshold` because the base implementation
-assumes each signer has a weight of 1, which is incompatible with this weighted implementation.
+assumes each signer has a weight of 1, which is incompatible with this weighted implementation.
@@ -2206,8 +2206,8 @@ Emitted when a signer's weight is changed.
Not emitted in [`ERC7579Multisig._addSigners`](#ERC7579Multisig-_addSigners-address-bytes---) or [`ERC7579Multisig._removeSigners`](#ERC7579Multisig-_removeSigners-address-bytes---). Indexers must rely on [`ERC7579Multisig.ERC7913SignerAdded`](#ERC7579Multisig-ERC7913SignerAdded-address-bytes-)
-and [`ERC7579Multisig.ERC7913SignerRemoved`](#ERC7579Multisig-ERC7913SignerRemoved-address-bytes-) to index a default weight of 1. See [`ERC7579MultisigWeighted.signerWeight`](#ERC7579MultisigWeighted-signerWeight-address-bytes-).
+and [`ERC7579Multisig.ERC7913SignerRemoved`](#ERC7579Multisig-ERC7913SignerRemoved-address-bytes-) to index a default weight of 1. See [`ERC7579MultisigWeighted.signerWeight`](#ERC7579MultisigWeighted-signerWeight-address-bytes-).
@@ -2259,7 +2259,7 @@ Thrown when the arrays lengths don't match.
```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
@@ -2340,8 +2340,8 @@ Returns the set of authorized selectors for the specified account.
This operation copies the entire selectors set to memory, which
-can be expensive or may result in unbounded computation.
+can be expensive or may result in unbounded computation.
@@ -2381,8 +2381,8 @@ 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-).
@@ -2538,7 +2538,7 @@ Error thrown when attempting to execute a non-authorized selector
```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.
@@ -2623,8 +2623,8 @@ See `IERC7579Module-onInstall`.
An account can only call onInstall once. If called directly by the account,
-the signer will be set to the provided data. Future installations will behave as a no-op.
+the signer will be set to the provided data. Future installations will behave as a no-op.
@@ -2645,9 +2645,9 @@ See `IERC7579Module-onUninstall`.
The signer's key will be removed if the account calls this function, potentially
+
making the account unusable. As an account operator, make sure to uninstall to a predefined path
in your account that properly handles side effects of uninstallation. See `AccountERC7579-uninstallModule`.
-
@@ -2757,7 +2757,7 @@ Thrown when the signer length is less than 20 bytes.
```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.
@@ -2889,8 +2889,8 @@ Validation algorithm.
Validation is a critical security function. Implementations must carefully
-handle cryptographic verification to prevent unauthorized access.
+handle cryptographic verification to prevent unauthorized access.
@@ -2908,7 +2908,7 @@ handle cryptographic verification to prevent unauthorized access.
```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
@@ -2925,8 +2925,8 @@ through the internal functions [`PaymasterCore.deposit`](#PaymasterCore-deposit-
See [Paymaster's unstaked reputation rules](https://eips.ethereum.org/EIPS/eip-7562#unstaked-paymasters-reputation-rules)
- for more details on the paymaster's storage access limitations.
+ for more details on the paymaster's storage access limitations.
Modifiers
@@ -3094,8 +3094,8 @@ is returned by [`PaymasterCore.validatePaymasterUserOp`](#PaymasterCore-validate
The `actualUserOpFeePerGas` is not `tx.gasprice`. A user operation can be bundled with other transactions
-making the gas price of the user operation to differ.
+making the gas price of the user operation to differ.
@@ -3256,7 +3256,7 @@ Unauthorized call to the paymaster.
```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.
@@ -3366,9 +3366,9 @@ Returns a `prefundContext` that's passed to the [`PaymasterCore._postOp`](#Payma
Consider not reverting if the prefund fails when overriding this function. This is to avoid reverting
+
during the validation phase of the user operation, which may penalize the paymaster's reputation according
to ERC-7562 validation rules.
-
@@ -3391,9 +3391,9 @@ Reverts with [`PaymasterERC20.PaymasterERC20FailedRefund`](#PaymasterERC20-Payma
This function may revert after the user operation has been executed without
+
reverting the user operation itself. Consider implementing a mechanism to handle
this case gracefully.
-
@@ -3438,7 +3438,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
@@ -3572,7 +3572,7 @@ and the `actualAmount` of `token`.
```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.
@@ -3685,8 +3685,8 @@ Otherwise, fallback to [`PaymasterERC20._refund`](#PaymasterERC20-_refund-contra
For guaranteed user operations where the user paid the `actualGasCost` back, this function
-doesn't call `super._refund`. Consider whether there are side effects in the parent contract that need to be executed.
+doesn't call `super._refund`. Consider whether there are side effects in the parent contract that need to be executed.
@@ -3707,8 +3707,8 @@ Fetches the guarantor address and validation data from the user operation.
Return `address(0)` to disable the guarantor feature. If supported, ensure
-explicit consent (e.g., signature verification) to prevent unauthorized use.
+explicit consent (e.g., signature verification) to prevent unauthorized use.
@@ -3761,7 +3761,7 @@ Emitted when a user operation identified by `userOpHash` is guaranteed by a `gua
```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.
@@ -3876,8 +3876,8 @@ Returns the context to be passed to postOp and the validation data.
The default `context` is `bytes(0)`. Developers that add a context when overriding this function MUST
-also override [`PaymasterCore._postOp`](#PaymasterCore-_postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) to process the context passed along.
+also override [`PaymasterCore._postOp`](#PaymasterCore-_postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) to process the context passed along.
@@ -3913,7 +3913,7 @@ Emitted when the paymaster token is set.
```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`.
@@ -4017,8 +4017,8 @@ Returns the context to be passed to postOp and the validation data.
The `context` returned is `bytes(0)`. Developers overriding this function MUST
-override [`PaymasterCore._postOp`](#PaymasterCore-_postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) to process the context passed along.
+override [`PaymasterCore._postOp`](#PaymasterCore-_postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) to process the context passed along.
@@ -4039,3 +4039,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..1995d1fd 100644
--- a/content/community-contracts/api/crosschain.mdx
+++ b/content/community-contracts/api/crosschain.mdx
@@ -5,21 +5,16 @@ 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.
+- [`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:
-* [`AxelarGatewayAdapter`](#AxelarGatewayAdapter): ERC-7786 gateway adapter for Axelar.
+- [`AxelarGatewayAdapter`](#AxelarGatewayAdapter): ERC-7786 gateway adapter for Axelar.
## Gateways
[`ERC7786OpenBridge`](#ERC7786OpenBridge)
-## Clients
-
-[`ERC7786Receiver`](#ERC7786Receiver)
-
## Adapters
### Axelar
@@ -39,10 +34,10 @@ Developers can access interoperability protocols through gateway adapters. The l
```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.
@@ -79,7 +74,7 @@ equivalent bridge on the destination chain if N of the M gateways agree.
- [renounceOwnership()](#Ownable-renounceOwnership--)
- [transferOwnership(newOwner)](#Ownable-transferOwnership-address-)
- [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-)
-#### IERC7786Receiver [!toc]
+#### IERC7786Recipient [!toc]
#### IERC7786GatewaySource [!toc]
@@ -100,9 +95,9 @@ equivalent bridge on the destination chain if N of the M gateways agree.
- [Unpaused(account)](#Pausable-Unpaused-address-)
#### Ownable [!toc]
- [OwnershipTransferred(previousOwner, newOwner)](#Ownable-OwnershipTransferred-address-address-)
-#### IERC7786Receiver [!toc]
+#### IERC7786Recipient [!toc]
#### IERC7786GatewaySource [!toc]
-- [MessageSent(sendId, sender, receiver, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---)
+- [MessageSent(sendId, sender, recipient, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---)
@@ -124,7 +119,7 @@ equivalent bridge on the destination chain if N of the M gateways agree.
#### Ownable [!toc]
- [OwnableUnauthorizedAccount(account)](#Ownable-OwnableUnauthorizedAccount-address-)
- [OwnableInvalidOwner(owner)](#Ownable-OwnableInvalidOwner-address-)
-#### IERC7786Receiver [!toc]
+#### IERC7786Recipient [!toc]
#### IERC7786GatewaySource [!toc]
- [UnsupportedAttribute(selector)](#IERC7786GatewaySource-UnsupportedAttribute-bytes4-)
@@ -210,27 +205,27 @@ 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
+
some value for unknown reason. In that case we want to register this gateway having delivered the message and
not revert. Any value accrued that way can be recovered by the admin using the [`ERC7786OpenBridge.sweep`](#ERC7786OpenBridge-sweep-address-payable-) function.
-
@@ -731,21 +726,21 @@ Recovery method in case value is ever received through [`ERC7786OpenBridge.recei
```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.
While both ERC-7786 and Axelar do support non-evm chains, this adaptor does not. This limitation comes from
+
the translation of the ERC-7930 interoperable address (binary objects -- bytes) to strings. This is necessary
because Axelar uses string to represent addresses. For EVM network, this adapter uses a checksum hex string
representation. Other networks would require a different encoding. Ideally we would have a single encoding for all
networks (could be base58, base64, ...) but Axelar doesn't support that.
-
@@ -794,7 +789,7 @@ 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-)
@@ -962,12 +957,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 +1075,14 @@ A chain equivalence has been registered.
@@ -1198,7 +1193,7 @@ A chain equivalence has been registered.
```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,135 +1222,6 @@ Parse the `requestRelay(uint256,uint256,address)` (0x4cbb573a) attribute into it
-
-```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.
-
-
@@ -1369,7 +1235,7 @@ Virtual function that should contain the logic to execute when a cross-chain mes
```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.
@@ -1425,7 +1291,7 @@ Note: only EVM chains are currently supported
- [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---)
+- [MessageSent(sendId, sender, recipient, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---)
@@ -1436,7 +1302,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-)
@@ -1720,12 +1586,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 +1758,14 @@ A chain equivalence has been registered.
-
+
+
+Schedule an operation containing a single transaction.
+
+Emits `CallSalt` if salt is nonzero, and `CallScheduled`.
+
+Requirements:
+
+- the caller must have the 'proposer' role.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
-
+```solidity
+import "@openzeppelin/community-contracts/contracts/interfaces/IERC7786Attributes.sol";
+```
+
+Standard attributes for ERC-7786. These attributes may be standardized in different ERCs.
+
+
-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.
-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.
-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.
-```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.
-
-```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)
-```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.
-
-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
+
-* `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.
+
-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`.
+
-Requires specific authorization. Frozen tokens cannot be transferred by the user.
+Requires specific authorization. Frozen tokens cannot be transferred by the account.
-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.
-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)
@@ -634,7 +696,7 @@ This is often used for allowlist/KYC/KYB/AML checks.
```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 +773,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..1292c7fe 100644
--- a/content/community-contracts/api/proxy.mdx
+++ b/content/community-contracts/api/proxy.mdx
@@ -5,7 +5,7 @@ description: "Smart contract proxy utilities and implementations"
Variants of proxy patterns, which are contracts that allow to forward a call to an implementation contract by using `delegatecall`. This contracts include:
-* [`HybridProxy`](#HybridProxy): An ERC-1967 proxy that uses the implementation slot as a beacon in a way that a user can upgrade to an implementation of their choice.
+- [`HybridProxy`](#HybridProxy): An ERC-1967 proxy that uses the implementation slot as a beacon in a way that a user can upgrade to an implementation of their choice.
## General
@@ -24,7 +24,7 @@ Variants of proxy patterns, which are contracts that allow to forward a call to
```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.
@@ -36,9 +36,9 @@ checks that are not compatible with this proxy design.
The fallback mechanism relies on the implementation not to define the `IBeacon-implementation` function.
+
Consider that if your implementation has this function, it'll be assumed as the beacon address, meaning that
the returned address will be used as this proxy's implementation.
-
Functions
@@ -86,9 +86,10 @@ Returns the current implementation address according to ERC-1967's implementatio
The way this function identifies whether the implementation is a beacon, is by checking
+
if it implements the `IBeacon-implementation` function. Consider that an actual implementation could
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..ab1b9292 100644
--- a/content/community-contracts/api/token.mdx
+++ b/content/community-contracts/api/token.mdx
@@ -5,12 +5,12 @@ description: "Smart contract token utilities and implementations"
Set of extensions and utilities for tokens (e.g ERC-20, ERC-721, ERC-1155) and derivated ERCs (e.g. ERC-4626, ERC-1363).
-* [`OnTokenTransferAdapter`](#OnTokenTransferAdapter): Adapter of the ERC-1363 receiver interface to comply with Chainlink’s 667 interface.
-* [`ERC20Allowlist`](#ERC20Allowlist): Extension of ERC20 with transfers and approvals that require users to be registered into an allowlist.
-* [`ERC20Blocklist`](#ERC20Blocklist): Extension of ERC20 with transfers and approvals that can be disabled by adding users into a blocklist.
-* [`ERC20Collateral`](#ERC20Collateral): Oracle-agnostic extension of ERC20 that limits the total supply based on a collateral amount.
-* [`ERC20Custodian`](#ERC20Custodian): Extension of ERC20 that implements an access-control agnostic approach to define a custodian that can freeze user’s transfers and approvals.
-* [`ERC4626Fees`](#ERC4626Fees): ERC4626 vault with fees on entry (deposit/mint) or exit (withdraw/redeem).
+- [`OnTokenTransferAdapter`](#OnTokenTransferAdapter): Adapter of the ERC-1363 receiver interface to comply with Chainlink's 667 interface.
+- [`ERC20Allowlist`](#ERC20Allowlist): Extension of ERC20 with transfers and approvals that require users to be registered into an allowlist.
+- [`ERC20Blocklist`](#ERC20Blocklist): Extension of ERC20 with transfers and approvals that can be disabled by adding users into a blocklist.
+- [`ERC20Collateral`](#ERC20Collateral): Oracle-agnostic extension of ERC20 that limits the total supply based on a collateral amount.
+- [`ERC20Custodian`](#ERC20Custodian): Extension of ERC20 that implements an access-control agnostic approach to define a custodian that can freeze user's transfers and approvals.
+- [`ERC4626Fees`](#ERC4626Fees): ERC4626 vault with fees on entry (deposit/mint) or exit (withdraw/redeem).
## General
@@ -41,10 +41,10 @@ Set of extensions and utilities for tokens (e.g ERC-20, ERC-721, ERC-1155) and d
```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,7 +62,7 @@ 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-)
@@ -72,14 +72,14 @@ Deprecated. Use [`ERC20Restricted`](#ERC20Restricted) instead.
- [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]
@@ -269,10 +269,10 @@ The operation failed because the user is not allowed.
```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,7 +290,7 @@ 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-)
@@ -300,14 +300,14 @@ Deprecated. Use [`ERC20Restricted`](#ERC20Restricted) instead.
- [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]
@@ -497,10 +497,10 @@ The operation failed because the user is blocked.
```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
@@ -521,14 +521,14 @@ data. This function can call external oracles or use any local storage.
- [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-)
@@ -720,10 +720,10 @@ Collateral amount has expired.
```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,7 +751,7 @@ 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]
@@ -759,14 +759,14 @@ Deprecated. Use [`ERC20Freezable`](#ERC20Freezable) instead.
- [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-)
@@ -911,7 +911,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.
@@ -1015,38 +1015,38 @@ Error thrown when a non-custodian account attempts to perform a custodian-only o
```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-).
-The operation failed because the user has insufficient unfrozen balance.
+The operation failed because the account has insufficient unfrozen balance.
@@ -1187,40 +1187,40 @@ The operation failed because the user has insufficient unfrozen balance.
```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.
@@ -1296,8 +1296,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 +1320,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-)).
@@ -1459,38 +1459,40 @@ The operation failed because the user account is restricted.
```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.
-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.
-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
-emits values that consistently reflect the actual amount of tokens that are frozen.
+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
-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.
This function uses [`ERC20Allowlist._update`](#ERC20Allowlist-_update-address-address-uint256-) to perform the transfer, ensuring all standard ERC20
+
side effects (such as balance updates and events) are preserved. If you override [`ERC20Allowlist._update`](#ERC20Allowlist-_update-address-address-uint256-)
to add additional restrictions or logic, those changes will also apply here.
Consider overriding this function to bypass newer restrictions if needed.
-
@@ -1710,7 +1716,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 +1748,7 @@ function _checkEnforcer(address from, address to, uint256 amount) internal view
-
_checkFreezer(address user, uint256 amount)
+
_checkFreezer(address account, uint256 amount)
internal
#
@@ -1755,7 +1761,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) {}
```
@@ -1774,7 +1780,7 @@ function _checkFreezer(address user, uint256 amount) internal view override only
```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`.
@@ -2076,3 +2084,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..7992481d 100644
--- a/content/community-contracts/api/utils.mdx
+++ b/content/community-contracts/api/utils.mdx
@@ -5,8 +5,8 @@ description: "Smart contract utils utilities and implementations"
Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives.
-* [`EnumerableSetExtended`](#EnumerableSetExtended) and [`EnumerableMapExtended`](#EnumerableMapExtended): Extensions of the `EnumerableSet` and `EnumerableMap` libraries with more types, including non-value types.
-* [`Masks`](#Masks): Library to handle `bytes32` masks.
+- [`EnumerableSetExtended`](#EnumerableSetExtended) and [`EnumerableMapExtended`](#EnumerableMapExtended): Extensions of the `EnumerableSet` and `EnumerableMap` libraries with more types, including non-value types.
+- [`Masks`](#Masks): Library to handle `bytes32` masks.
## Structs
@@ -31,7 +31,7 @@ Miscellaneous contracts and libraries containing utility functions you can use t
```solidity
-import "@openzeppelin/community-contracts/utils/Masks.sol";
+import "@openzeppelin/community-contracts/contracts/utils/Masks.sol";
```
Library for handling bit masks
@@ -217,7 +217,7 @@ Returns the symmetric difference (∆) of two masks, also known as disjunctive u
```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
@@ -348,8 +345,8 @@ 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.
+function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
@@ -467,10 +464,10 @@ 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.
-
@@ -491,10 +488,10 @@ 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.
-
@@ -555,8 +552,8 @@ 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.
+function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
@@ -674,10 +671,10 @@ 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.
-
@@ -698,10 +695,10 @@ 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.
-
@@ -753,7 +750,7 @@ Query for a nonexistent map key.
```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
@@ -862,8 +856,8 @@ 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.
+function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.
@@ -942,10 +936,10 @@ 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.
-
@@ -966,10 +960,11 @@ 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.
-
+
diff --git a/content/community-contracts/api/utils/cryptography.mdx b/content/community-contracts/api/utils/cryptography.mdx
index 1e46a40f..742b7569 100644
--- a/content/community-contracts/api/utils/cryptography.mdx
+++ b/content/community-contracts/api/utils/cryptography.mdx
@@ -5,33 +5,25 @@ 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.
+- [`ZKEmailUtils`](#ZKEmailUtils): Library for ZKEmail signature validation utilities, enabling email-based authentication through zero-knowledge proofs.
+- [`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.
+- [`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)
-
@@ -45,7 +37,7 @@ A collection of contracts and libraries that implement various signature validat
```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
@@ -129,12 +121,12 @@ 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
-validation in derived contracts if needed.
+validation in derived contracts if needed.
@@ -154,12 +146,12 @@ 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.
-Consider adding validation in derived contracts if needed.
+Consider adding validation in derived contracts if needed.
@@ -179,128 +171,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.
-
-
-
-
-
-
-
-
-```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)
-
-
-
-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
-
-
-
-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.
@@ -318,7 +189,7 @@ cause revert/panic.
```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 +230,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 +275,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`"]`).
@@ -426,8 +297,8 @@ returns true and the calldata view at the object. Otherwise, returns false and a
The returned `emailProof` object should not be accessed if `success` is false. Trying to access the data may
-cause revert/panic.
+cause revert/panic.
@@ -452,86 +323,6 @@ into a uint256 array in the order expected by the verifier circuit.
-
-
-
-
-```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.
-
-
-
-
-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.
-
-
-
-
@@ -545,7 +336,7 @@ the raw `r` and `s` values from the signature.
```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.
@@ -582,9 +373,9 @@ contract MyAccountZKEmail is Account, SignerZKEmail, Initializable {
Failing to call [`SignerZKEmail._setAccountSalt`](#SignerZKEmail-_setAccountSalt-bytes32-), [`SignerZKEmail._setDKIMRegistry`](#SignerZKEmail-_setDKIMRegistry-contract-IDKIMRegistry-), and [`SignerZKEmail._setVerifier`](#SignerZKEmail-_setVerifier-contract-IGroth16Verifier-)
+
either during construction (if used standalone) or during initialization (if used as a clone) may
leave the signer either front-runnable or unusable.
-
-
-```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.
-
-
-
-
-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
-
-
-
-
@@ -834,7 +567,7 @@ SHOULD return 0xffffffff or revert if the key is empty
```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.
@@ -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/contracts/5.x/api/access.mdx b/content/contracts/5.x/api/access.mdx
index b2d6fc6a..949778d4 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`
-
+
@@ -182,6 +182,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 +428,7 @@ May emit a [`IAccessControl.RoleRevoked`](#IAccessControl-RoleRevoked-bytes32-ad
## `IAccessControl`
-
+
@@ -679,7 +686,7 @@ Don't confuse with [`IAccessControl.AccessControlUnauthorizedAccount`](#IAccessC
## `Ownable`
-
+
@@ -912,165 +919,13 @@ The owner is not a valid owner account. (eg. `address(0)`)
-
-
-
-
-```solidity
-import "@openzeppelin/contracts/access/Ownable2Step.sol";
-```
-
-Contract module which provides access control mechanism, where
-there is an account (an owner) that can be granted exclusive access to
-specific functions.
-
-This extension of the [`Ownable`](#Ownable) contract includes a two-step mechanism to transfer
-ownership, where the new owner must call [`Ownable2Step.acceptOwnership`](#Ownable2Step-acceptOwnership--) in order to replace the
-old one. This can help prevent common mistakes, such as transfers of ownership to
-incorrect accounts, or to contracts that are unable to interact with the
-permission system.
-
-The initial owner is specified at deployment time in the constructor for `Ownable`. This
-can later be changed with [`Ownable.transferOwnership`](#Ownable-transferOwnership-address-) and [`Ownable2Step.acceptOwnership`](#Ownable2Step-acceptOwnership--).
-
-This module is used through inheritance. It will make available all functions
-from parent (Ownable).
-
-
-
-Starts the ownership transfer of the contract to a new account. Replaces the pending transfer if there is one.
-Can only be called by the current owner.
-
-Setting `newOwner` to the zero address is allowed; this can be used to cancel an initiated ownership transfer.
-
-
## `AccessControlDefaultAdminRules`
-
+
@@ -1503,7 +1358,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 +1402,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 +1508,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 +1550,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 +1603,7 @@ See [`AccessControlDefaultAdminRules.defaultAdminDelayIncreaseWait`](#AccessCont
## `AccessControlEnumerable`
-
+
@@ -1938,7 +1793,7 @@ Overload [`AccessControl._revokeRole`](#AccessControl-_revokeRole-bytes32-addres
## `IAccessControlDefaultAdminRules`
-
+
@@ -2112,7 +1967,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 +1992,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 +2060,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 +2083,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 +2255,7 @@ the operation must wait until `schedule`.
## `IAccessControlEnumerable`
-
+
@@ -2497,7 +2352,7 @@ together with [`AccessControlEnumerable.getRoleMember`](#AccessControlEnumerable
## `AccessManaged`
-
+
@@ -2570,22 +2425,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 +2555,7 @@ is less than 4 bytes long.
## `AccessManager`
-
+
@@ -2850,6 +2703,7 @@ mindful of the danger associated with functions such as [`Ownable.renounceOwners
- [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-)
@@ -3147,6 +3001,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 +3108,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 +3132,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 +3156,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 +3632,7 @@ The identifier of the public role. Automatically granted to all addresses with n
## `AuthorityUtils`
-
+
@@ -3816,7 +3674,7 @@ This helper function takes care of invoking `canCall` in a backwards compatible
## `IAccessManaged`
-
+
@@ -3973,7 +3831,7 @@ Authority that manages this contract was updated.
## `IAccessManager`
-
+
@@ -4044,6 +3902,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 +4165,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 +4272,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 +4296,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 +4320,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 +4659,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 +4859,21 @@ Admin delay for a given `target` will be updated to `delay` when `since` is reac
+
+
+
@@ -5092,7 +4970,7 @@ Admin delay for a given `target` will be updated to `delay` when `since` is reac
## `IAuthority`
-
+
@@ -5128,3 +5006,155 @@ Returns true if the caller can invoke on a target the function identified by a f
+
+```solidity
+import "@openzeppelin/contracts/access/Ownable2Step.sol";
+```
+
+Contract module which provides access control mechanism, where
+there is an account (an owner) that can be granted exclusive access to
+specific functions.
+
+This extension of the [`Ownable`](#Ownable) contract includes a two-step mechanism to transfer
+ownership, where the new owner must call [`Ownable2Step.acceptOwnership`](#Ownable2Step-acceptOwnership--) in order to replace the
+old one. This can help prevent common mistakes, such as transfers of ownership to
+incorrect accounts, or to contracts that are unable to interact with the
+permission system.
+
+The initial owner is specified at deployment time in the constructor for `Ownable`. This
+can later be changed with [`Ownable.transferOwnership`](#Ownable-transferOwnership-address-) and [`Ownable2Step.acceptOwnership`](#Ownable2Step-acceptOwnership--).
+
+This module is used through inheritance. It will make available all functions
+from parent (Ownable).
+
+
+
+Starts the ownership transfer of the contract to a new account. Replaces the pending transfer if there is one.
+Can only be called by the current owner.
+
+Setting `newOwner` to the zero address is allowed; this can be used to cancel an initiated ownership transfer.
+
+
+
diff --git a/content/contracts/5.x/api/account.mdx b/content/contracts/5.x/api/account.mdx
index 8d16aab0..7fc1f8c0 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`
-
+
@@ -353,9 +353,9 @@ Unauthorized call to the account.
-## `AccountERC7579`
+## `AccountERC7579`
-
+
@@ -382,8 +382,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 +391,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
@@ -923,7 +920,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 +981,9 @@ The provided initData/deInitData for a fallback module is too short to extract a
-## `AccountERC7579Hooked`
+## `AccountERC7579Hooked`
-
+
@@ -999,7 +996,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
@@ -1271,9 +1268,9 @@ A hook module is already present. This contract only supports one hook module.
-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 +1398,9 @@ function _erc7821AuthorizedExecutor(
@@ -1445,9 +1442,9 @@ Returns the address of the delegate if `account` has an EIP-7702 delegation setu
-## `IEntryPointExtra`
+## `IEntryPointExtra`
-
+
@@ -1485,9 +1482,9 @@ This is available on all entrypoint since v0.4.0, but is not formally part of th
#
@@ -1536,7 +1536,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 +1559,24 @@ Packs the validation data into a single uint256. See [`ERC4337Utils.parseValidat
+
+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 +1589,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.
+
+
+
+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 +1629,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 +1853,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.
+
+
-## `ERC7579Utils`
+## `ERC7579Utils`
-
+
@@ -2285,9 +2345,9 @@ Input calldata not properly formatted and possibly malicious.
-## `eqCallType`
+## `eqCallType`
-
+
@@ -2320,9 +2380,9 @@ Compares two `CallType` values for equality.
-## `eqExecType`
+## `eqExecType`
-
+
@@ -2355,9 +2415,9 @@ Compares two `ExecType` values for equality.
-## `eqModeSelector`
+## `eqModeSelector`
-
+
@@ -2390,9 +2450,9 @@ Compares two `ModeSelector` values for equality.
-## `eqModePayload`
+## `eqModePayload`
-
+
@@ -2420,3 +2480,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..5c4998e7 100644
--- a/content/contracts/5.x/api/crosschain.mdx
+++ b/content/contracts/5.x/api/crosschain.mdx
@@ -5,48 +5,280 @@ 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)
+
+
```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.
+
+
+
+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`.
+
+
+
+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).
+
+
+
+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.
+
+
+
+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.
+
+
+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`
-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-).
+
+
+
+
+
+
+```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.
+
+Endpoint allowing the controller to reconfigure the executor. This must be called by the executor itself
+following an instruction from the controller.
+
+
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.
+
+
+
+```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
+
+
+
+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.
+
+
+
+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.
+
+
+
+
+```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.
+
+
+
+```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.
+
+
+
+```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.
+
+
+
+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.
+
+
+
+```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.
+
+
+
+```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.
+
+
+
+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.
+
+
+
+
+```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.
+
+
+
+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.
+
+
+
+
+```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.
+
+
+
+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.
+
+
+
+
+```solidity
+import "@openzeppelin/contracts/crosschain/bridges/BridgeERC20Core.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.
+
+
+
diff --git a/content/contracts/5.x/api/finance.mdx b/content/contracts/5.x/api/finance.mdx
index 3dea4798..2415528e 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`
-
+
@@ -383,9 +383,9 @@ an asset given its total historical allocation.
-## `VestingWalletCliff`
+## `VestingWalletCliff`
-
+
@@ -524,3 +524,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..16af3c51 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`
-
+
@@ -335,7 +338,6 @@ 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-)
@@ -367,7 +369,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 +647,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 +890,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 +1293,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 +1477,9 @@ quorum depending on values such as the totalSupply of a token at this timepoint
-## `IGovernor`
+## `IGovernor`
-
+
@@ -1544,7 +1563,6 @@ 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-)
@@ -2428,23 +2446,6 @@ Queue operation is not implemented for this governor. Execute should be called d
@@ -2501,9 +2502,9 @@ The given `account` is unable to cancel the proposal with given `proposalId`.
-## `TimelockController`
+## `TimelockController`
-
+
@@ -2705,6 +2706,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 +3278,9 @@ The caller account is not authorized.
-## `GovernorCountingFractional`
+## `GovernorCountingFractional`
-
+
@@ -3431,7 +3439,6 @@ _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-)
@@ -3634,9 +3641,9 @@ A fractional vote params uses more votes than are available for that user.
-## `GovernorCountingOverridable`
+## `GovernorCountingOverridable`
-
+
@@ -3786,7 +3793,6 @@ 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-)
@@ -4092,9 +4098,9 @@ A delegated vote on `proposalId` was overridden by `weight`
+
+```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).
+
+
+
+Send crosschain instruction to an arbitrary remote executor via an arbitrary ERC-7786 gateway.
+
+
+
+
-## `GovernorNoncesKeyed`
+## `GovernorNoncesKeyed`
-
+
@@ -4518,7 +4713,6 @@ 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-)
@@ -4595,9 +4789,9 @@ Side effects may be skipped depending on the linearization of the function.
-## `GovernorProposalGuardian`
+## `GovernorProposalGuardian`
-
+
@@ -5056,7 +5249,6 @@ 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-)
@@ -5166,9 +5358,9 @@ Override [`Governor._validateCancel`](#Governor-_validateCancel-uint256-address-
-## `GovernorTimelockAccess`
+## `GovernorTimelockAccess`
-
+
@@ -6343,7 +6531,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
@@ -6499,7 +6687,6 @@ 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-)
@@ -6848,9 +7035,9 @@ Emits a [`IGovernor.ProposalCanceled`](#IGovernor-ProposalCanceled-uint256-) eve
-## `GovernorTimelockCompound`
+## `GovernorTimelockCompound`
-
+
@@ -6997,7 +7184,6 @@ 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-)
@@ -7186,7 +7372,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 +7401,9 @@ Emitted when the timelock controller used for proposal execution is modified.
-## `GovernorTimelockControl`
+## `GovernorTimelockControl`
-
+
@@ -7367,7 +7555,6 @@ 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-)
@@ -7532,7 +7719,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 +7748,9 @@ Emitted when the timelock controller used for proposal execution is modified.
-## `GovernorVotes`
+## `GovernorVotes`
-
+
@@ -7699,7 +7888,6 @@ 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-)
@@ -7799,9 +7987,9 @@ Machine-readable description of the clock as specified in ERC-6372.
-## `GovernorVotesQuorumFraction`
+## `GovernorVotesQuorumFraction`
-
+
@@ -7950,7 +8138,6 @@ 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-)
@@ -8154,9 +8341,9 @@ The quorum set is not a valid fraction.
-## `GovernorVotesSuperQuorumFraction`
+## `GovernorVotesSuperQuorumFraction`
-
+
@@ -8322,7 +8509,6 @@ 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-)
@@ -8573,9 +8759,9 @@ The quorum set is not valid as it exceeds the super quorum.
-## `IVotes`
+## `IVotes`
-
+
@@ -8780,9 +8966,9 @@ The signature used has expired.
-## `Votes`
+## `Votes`
-
+
@@ -9206,9 +9392,9 @@ Lookup to future votes is not available.
-## `VotesExtended`
+## `VotesExtended`
-
+
@@ -9396,3 +9582,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..00fcd245 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`
-
+
@@ -313,733 +340,310 @@ caller's tokens and then calls [`IERC1363Spender.onApprovalReceived`](#IERC1363S
```solidity
-import "@openzeppelin/contracts/interfaces/IERC1363Receiver.sol";
+import "@openzeppelin/contracts/interfaces/IERC1967.sol";
```
-Interface for any contract that wants to support `transferAndCall` or `transferFromAndCall`
-from ERC-1363 token contracts.
+ERC-1967: Proxy Storage Slots. This interface contains the events defined in the ERC.
-Whenever ERC-1363 tokens are transferred to this contract via `transferAndCall` or `transferFromAndCall`
-by `operator` from `from`, this function is called.
+Emitted when the implementation is upgraded.
-
-To accept the transfer, this must return
-`bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)"))`
-(i.e. 0x88a7ca5c, or its own function selector).
-
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC1363Spender.sol";
+import "@openzeppelin/contracts/interfaces/IERC2309.sol";
```
-Interface for any contract that wants to support `approveAndCall`
-from ERC-1363 token contracts.
+ERC-2309: ERC-721 Consecutive Transfer Extension.
-Whenever an ERC-1363 token `owner` approves this contract via `approveAndCall`
-to spend their tokens, this function is called.
+
-
-To accept the approval, this must return
-`bytes4(keccak256("onApprovalReceived(address,uint256,bytes)"))`
-(i.e. 0x7b04a2d0, or its own function selector).
-
+Emitted when the tokens from `fromTokenId` to `toTokenId` are transferred from `fromAddress` to `toAddress`.
```solidity
-import "@openzeppelin/contracts/interfaces/IERC1820Implementer.sol";
+import "@openzeppelin/contracts/interfaces/IERC2981.sol";
```
-Interface for an ERC-1820 implementer, as defined in the
-[ERC](https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface).
-Used by contracts that will be registered as implementers in the
-[`IERC1820Registry`](#IERC1820Registry).
+Interface for the NFT Royalty Standard.
+
+A standardized way to retrieve royalty payment information for non-fungible tokens (NFTs) to enable universal
+support for royalty payments across all NFT marketplaces and ecosystem participants.
-Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract
-implements `interfaceHash` for `account`.
+Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of
+exchange. The royalty amount is denominated and should be paid in that same unit of exchange.
-See [`IERC1820Registry.setInterfaceImplementer`](#IERC1820Registry-setInterfaceImplementer-address-bytes32-address-).
+
+ERC-2981 allows setting the royalty to 100% of the price. In that case all the price would be sent to the
+royalty receiver and 0 tokens to the seller. Contracts dealing with royalty should consider empty transfers.
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC1820Registry.sol";
+import "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
```
-Interface of the global ERC-1820 Registry, as defined in the
-[ERC](https://eips.ethereum.org/EIPS/eip-1820). Accounts may register
-implementers for interfaces in this registry, as well as query support.
-
-Implementers may be shared by multiple accounts, and can also implement more
-than a single interface for each account. Contracts can implement interfaces
-for themselves, but externally-owned accounts (EOA) must delegate this to a
-contract.
-
-[`IERC165`](/contracts/5.x/api/utils#IERC165) interfaces can also be queried via the registry.
-
-For an in-depth explanation and source code analysis, see the ERC text.
+Interface of the ERC-3156 FlashBorrower, as defined in
+[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
-Sets `newManager` as the manager for `account`. A manager of an
-account is able to set interface implementers for it.
+Receive a flash loan.
-By default, each account is its own manager. Passing a value of `0x0` in
-`newManager` will reset the manager to this initial state.
+
+
-Emits a [`IERC1820Registry.ManagerChanged`](#IERC1820Registry-ManagerChanged-address-address-) event.
+
-Requirements:
+
-- the caller must be the current manager for `account`.
+## `IERC3156FlashLender`
+
+
+
+
+
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC3156FlashLender.sol";
+```
+
+Interface of the ERC-3156 FlashLender, as defined in
+[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
+
-Returns the manager for `account`.
-
-See [`IERC1820Registry.setManager`](#IERC1820Registry-setManager-address-address-).
+The amount of currency available to be lent.
-Sets the `implementer` contract as ``account``'s implementer for
-`interfaceHash`.
-
-`account` being the zero address is an alias for the caller's address.
-The zero address can also be used in `implementer` to remove an old one.
-
-See [`IERC1820Registry.interfaceHash`](#IERC1820Registry-interfaceHash-string-) to learn how these are created.
-
-Emits an [`IERC1820Registry.InterfaceImplementerSet`](#IERC1820Registry-InterfaceImplementerSet-address-bytes32-address-) event.
-
-Requirements:
-
-- the caller must be the current manager for `account`.
-- `interfaceHash` must not be an [`IERC165`](/contracts/5.x/api/utils#IERC165) interface id (i.e. it must not
-end in 28 zeroes).
-- `implementer` must implement [`IERC1820Implementer`](#IERC1820Implementer) and return true when
-queried for support, unless `implementer` is the caller. See
-[`IERC1820Implementer.canImplementInterfaceForAddress`](#IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-).
+The fee to be charged for a given loan.
-Returns the implementer of `interfaceHash` for `account`. If no such
-implementer is registered, returns the zero address.
-
-If `interfaceHash` is an [`IERC165`](/contracts/5.x/api/utils#IERC165) interface id (i.e. it ends with 28
-zeroes), `account` will be queried for support of it.
-
-`account` being the zero address is an alias for the caller's address.
+Initiate a flash loan.
-
-Returns the interface hash for an `interfaceName`, as defined in the
-corresponding
-[section of the ERC](https://eips.ethereum.org/EIPS/eip-1820#interface-name).
-
-
-
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC1967.sol";
-```
-
-ERC-1967: Proxy Storage Slots. This interface contains the events defined in the ERC.
-
-
-
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC2981.sol";
-```
-
-Interface for the NFT Royalty Standard.
-
-A standardized way to retrieve royalty payment information for non-fungible tokens (NFTs) to enable universal
-support for royalty payments across all NFT marketplaces and ecosystem participants.
-
-
-
-Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of
-exchange. The royalty amount is denominated and should be paid in that same unit of exchange.
-
-
-ERC-2981 allows setting the royalty to 100% of the price. In that case all the price would be sent to the
-royalty receiver and 0 tokens to the seller. Contracts dealing with royalty should consider empty transfers.
-
-
-
-
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
-```
-
-Interface of the ERC-3156 FlashBorrower, as defined in
-[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
-
-
-
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC3156FlashLender.sol";
-```
-
-Interface of the ERC-3156 FlashLender, as defined in
-[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
-
-
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC6909.sol";
+```
-Emitted when the allowance of a `spender` for an `owner` is set for a token of type `id`.
-The new allowance is `amount`.
+Optional extension of [`IERC6909`](#IERC6909) that adds content URI functions.
+
+
-Emitted when `amount` tokens of type `id` are moved from `sender` to `receiver` initiated by `caller`.
+Returns the URI for the token of type `id`.
-
+
-## `IERC6909Metadata`
+## `IERC6909TokenSupply`
-
+
@@ -2095,14 +1879,12 @@ Emitted when `amount` tokens of type `id` are moved from `sender` to `receiver`
import "@openzeppelin/contracts/interfaces/IERC6909.sol";
```
-Optional extension of [`IERC6909`](#IERC6909) that adds metadata functions.
+Optional extension of [`IERC6909`](#IERC6909) that adds a token supply function.
-Returns the ticker symbol of the token of type `id`.
+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
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC1822.sol";
+```
+
+ERC-1822: Universal Upgradeable Proxy Standard (UUPS) documents a method for upgradeability through a simplified
+proxy whose upgrades are fully controlled by the current implementation.
+
+
-Returns the number of decimals for the token of type `id`.
+Returns the storage slot that the proxiable contract assumes is being used to store the implementation
+address.
+
+
+A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
+bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
+function revert if invoked through a proxy.
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC6909.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
```
-Optional extension of [`IERC6909`](#IERC6909) that adds content URI functions.
+A [user operation](https://github.com/ethereum/ercs/blob/master/ERCS/erc-4337.md#useroperation) is composed of the following elements:
+- `sender` (`address`): The account making the operation
+- `nonce` (`uint256`): Anti-replay parameter (see “Semi-abstracted Nonce Support” )
+- `factory` (`address`): account factory, only for new accounts
+- `factoryData` (`bytes`): data for account factory (only if account factory exists)
+- `callData` (`bytes`): The data to pass to the sender during the main execution call
+- `callGasLimit` (`uint256`): The amount of gas to allocate the main execution call
+- `verificationGasLimit` (`uint256`): The amount of gas to allocate for the verification step
+- `preVerificationGas` (`uint256`): Extra gas to pay the bundler
+- `maxFeePerGas` (`uint256`): Maximum fee per gas (similar to EIP-1559 max_fee_per_gas)
+- `maxPriorityFeePerGas` (`uint256`): Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas)
+- `paymaster` (`address`): Address of paymaster contract, (or empty, if account pays for itself)
+- `paymasterVerificationGasLimit` (`uint256`): The amount of gas to allocate for the paymaster validation code
+- `paymasterPostOpGasLimit` (`uint256`): The amount of gas to allocate for the paymaster post-operation code
+- `paymasterData` (`bytes`): Data for paymaster (only if paymaster exists)
+- `signature` (`bytes`): Data passed into the account to verify authorization
+
+When passed to on-chain contracts, the following packed version is used.
+- `sender` (`address`)
+- `nonce` (`uint256`)
+- `initCode` (`bytes`): concatenation of factory address and factoryData (or empty)
+- `callData` (`bytes`)
+- `accountGasLimits` (`bytes32`): concatenation of verificationGas (16 bytes) and callGas (16 bytes)
+- `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`)
+
+
+
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+```
+
+Aggregates and validates multiple signatures for a batch of user operations.
+
+A contract could implement this interface with custom validation schemes that allow signature aggregation,
+enabling significant optimizations and gas savings for execution and transaction data cost.
+
+Bundlers and clients whitelist supported aggregators.
+
+See [ERC-7766](https://eips.ethereum.org/EIPS/eip-7766)
-Returns the URI for the token of type `id`.
+Validates that the aggregated signature is valid for the user operations.
+
+Requirements:
+
+- The aggregated signature MUST match the given list of operations.
+Nonces are used in accounts as a replay protection mechanism and to ensure the order of user operations.
+To avoid limiting the number of operations an account can perform, the interface allows using parallel
+nonces by using a `key` parameter.
+
+See [ERC-4337 semi-abstracted nonce support](https://eips.ethereum.org/EIPS/eip-4337#semi-abstracted-nonce-support).
-Returns the total supply of the token of type `id`.
+Returns the nonce for a `sender` account and a `key`.
+
+Nonces for a certain `key` are always increasing.
```solidity
-import "@openzeppelin/contracts/interfaces/IERC7751.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
```
-Wrapping of bubbled up reverts
-Interface of the [ERC-7751](https://eips.ethereum.org/EIPS/eip-7751) wrapping of bubbled up reverts.
+Handle stake management for entities (i.e. accounts, paymasters, factories).
+
+The EntryPoint must implement the following API to let entities like paymasters have a stake,
+and thus have more flexibility in their storage access
+(see [reputation, throttling and banning.](https://eips.ethereum.org/EIPS/eip-4337#reputation-scoring-and-throttlingbanning-for-global-entities))
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC777.sol";
-```
+Deposits `msg.value` to the account.
-Interface of the ERC-777 Token standard as defined in the ERC.
+
+
-This contract uses the
-[ERC-1820 registry standard](https://eips.ethereum.org/EIPS/eip-1820) to let
-token holders and recipients react to token movements by using setting implementers
-for the associated interfaces in said registry. See [`IERC1820Registry`](#IERC1820Registry) and
-[`IERC1820Implementer`](#IERC1820Implementer).
+
-
-Returns the smallest part of the token that is not divisible. This
-means all token operations (creation, movement and destruction) must have
-amounts that are a multiple of this number.
+Withdraws the stake of the account to `withdrawAddress`.
-For most token contracts, this value will equal 1.
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+```
+
+Entry point for user operations.
+
+User operations are validated and executed by this contract.
+
+
-Moves `amount` tokens from the caller's account to `recipient`.
-
-If send or receive hooks are registered for the caller and `recipient`,
-the corresponding functions will be called with `data` and empty
-`operatorData`. See [`IERC777Sender`](#IERC777Sender) and [`IERC777Recipient`](#IERC777Recipient).
-
-Emits a [`IERC777.Sent`](#IERC777-Sent-address-address-address-uint256-bytes-bytes-) event.
-
-Requirements
-
-- the caller must have at least `amount` tokens.
-- `recipient` cannot be the zero address.
-- if `recipient` is a contract, it must implement the [`IERC777Recipient`](#IERC777Recipient)
-interface.
+A user operation at `opIndex` failed with `reason`.
-Destroys `amount` tokens from the caller's account, reducing the
-total supply.
+A user operation at `opIndex` failed with `reason` and `inner` returned data.
-If a send hook is registered for the caller, the corresponding function
-will be called with `data` and empty `operatorData`. See [`IERC777Sender`](#IERC777Sender).
+
+
-Emits a [`IERC777.Burned`](#IERC777-Burned-address-address-uint256-bytes-bytes-) event.
+
-Requirements
+
-- the caller must have at least `amount` tokens.
+## `IAccount`
+
+
+
+
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+```
+
+Base interface for an ERC-4337 account.
+
+
-Returns true if an account is an operator of `tokenHolder`.
-Operators can send and burn tokens on behalf of their owners. All
-accounts are their own operator.
+Validates a user operation.
-See [`IERC777.operatorSend`](#IERC777-operatorSend-address-address-uint256-bytes-bytes-) and [`IERC777.operatorBurn`](#IERC777-operatorBurn-address-uint256-bytes-bytes-).
+* MUST validate the caller is a trusted EntryPoint
+* MUST validate that the signature is a valid signature of the userOpHash, and SHOULD
+ return SIG_VALIDATION_FAILED (and not revert) on signature mismatch. Any other error MUST revert.
+* MUST pay the entryPoint (caller) at least the “missingAccountFunds” (which might
+ be zero, in case the current account’s deposit is high enough)
-
-
+Returns an encoded packed validation data that is composed of the following elements:
-
+- `authorizer` (`address`): 0 for success, 1 for failure, otherwise the address of an authorizer contract
+- `validUntil` (`uint48`): The UserOp is valid only up to this time. Zero for “infinite”.
+- `validAfter` (`uint48`): The UserOp is valid only after this time.
-
-Make an account an operator of the caller.
+
-See [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-).
+
-Emits an [`IERC777.AuthorizedOperator`](#IERC777-AuthorizedOperator-address-address-) event.
+## `IAccountExecute`
-Requirements
+
+
+
-- `operator` cannot be calling address.
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+```
+
+Support for executing user operations by prepending the [`IAccountExecute.executeUserOp`](#IAccountExecute-executeUserOp-struct-PackedUserOperation-bytes32-) function selector
+to the UserOperation's `callData`.
+
-Revoke an account's operator status for the caller.
+Executes a user operation.
-See [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-) and [`IERC777.defaultOperators`](#IERC777-defaultOperators--).
+
+
-Emits a [`IERC777.RevokedOperator`](#IERC777-RevokedOperator-address-address-) event.
+
-Requirements
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+```
+
+Interface for a paymaster contract that agrees to pay for the gas costs of a user operation.
+
+
+A paymaster must hold a stake to cover the required entrypoint stake and also the gas for the transaction.
+
+
+
-Returns the list of default operators. These accounts are operators
-for all token holders, even if [`IERC777.authorizeOperator`](#IERC777-authorizeOperator-address-) was never called on
-them.
+Validates whether the paymaster is willing to pay for the user operation. See
+[`IAccount.validateUserOp`](#IAccount-validateUserOp-struct-PackedUserOperation-bytes32-uint256-) for additional information on the return value.
-This list is immutable, but individual holders may revoke these via
-[`IERC777.revokeOperator`](#IERC777-revokeOperator-address-), in which case [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-) will return false.
+
+Bundlers will reject this method if it modifies the state, unless it's whitelisted.
+
-Moves `amount` tokens from `sender` to `recipient`. The caller must
-be an operator of `sender`.
+Verifies the sender is the entrypoint.
-If send or receive hooks are registered for `sender` and `recipient`,
-the corresponding functions will be called with `data` and
-`operatorData`. See [`IERC777Sender`](#IERC777Sender) and [`IERC777Recipient`](#IERC777Recipient).
+
+
-Emits a [`IERC777.Sent`](#IERC777-Sent-address-address-address-uint256-bytes-bytes-) event.
+
-Requirements
+
-- `sender` cannot be the zero address.
-- `sender` must have at least `amount` tokens.
-- the caller must be an operator for `sender`.
-- `recipient` cannot be the zero address.
-- if `recipient` is a contract, it must implement the [`IERC777Recipient`](#IERC777Recipient)
-interface.
+## `IERC20Errors`
+
+
+
+
+
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
+```
+
+Standard ERC-20 Errors
+Interface of the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors for ERC-20 tokens.
+
-Destroys `amount` tokens from `account`, reducing the total supply.
-The caller must be an operator of `account`.
-
-If a send hook is registered for `account`, the corresponding function
-will be called with `data` and `operatorData`. See [`IERC777Sender`](#IERC777Sender).
-
-Emits a [`IERC777.Burned`](#IERC777-Burned-address-address-uint256-bytes-bytes-) event.
-
-Requirements
-
-- `account` cannot be the zero address.
-- `account` must have at least `amount` tokens.
-- the caller must be an operator for `account`.
+Indicates an error related to the current `balance` of a `sender`. Used in transfers.
-Emitted when `amount` tokens are created by `operator` and assigned to `to`.
-
-Note that some additional user `data` and `operatorData` can be logged in the event.
+Indicates a failure with the token `sender`. Used in transfers.
-Emitted when `operator` destroys `amount` tokens from `account`.
-
-Note that some additional user `data` and `operatorData` can be logged in the event.
+Indicates a failure with the token `receiver`. Used in transfers.
-Emitted when `operator` is revoked its operator status for `tokenHolder`.
+Indicates a failure with the `approver` of a token to be approved. Used in approvals.
```solidity
-import "@openzeppelin/contracts/interfaces/IERC777Recipient.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
```
-Interface of the ERC-777 Tokens Recipient standard as defined in the ERC.
-
-Accounts can be notified of [`IERC777`](#IERC777) tokens being sent to them by having a
-contract implement this interface (contract holders can be their own
-implementer) and registering it on the
-[ERC-1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
-
-See [`IERC1820Registry`](#IERC1820Registry) and [`IERC1820Implementer`](#IERC1820Implementer).
+Standard ERC-721 Errors
+Interface of the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors for ERC-721 tokens.
-Called by an [`IERC777`](#IERC777) token contract whenever tokens are being
-moved or created into a registered account (`to`). The type of operation
-is conveyed by `from` being the zero address or not.
-
-This call occurs _after_ the token contract's state is updated, so
-[`IERC777.balanceOf`](#IERC777-balanceOf-address-), etc., can be used to query the post-operation state.
-
-This function may revert to prevent the operation from being executed.
+Indicates that an address can't be an owner. For example, `address(0)` is a forbidden owner in ERC-721.
+Used in balance queries.
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC777Sender.sol";
-```
-
-Interface of the ERC-777 Tokens Sender standard as defined in the ERC.
-
-[`IERC777`](#IERC777) Token holders can be notified of operations performed on their
-tokens by having a contract implement this interface (contract holders can be
-their own implementer) and registering it on the
-[ERC-1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
-
-See [`IERC1820Registry`](#IERC1820Registry) and [`IERC1820Implementer`](#IERC1820Implementer).
+Indicates a `tokenId` whose `owner` is the zero address.
-
-
Functions
-
-- [tokensToSend(operator, from, to, amount, userData, operatorData)](#IERC777Sender-tokensToSend-address-address-address-uint256-bytes-bytes-)
-Called by an [`IERC777`](#IERC777) token contract whenever a registered holder's
-(`from`) tokens are about to be moved or destroyed. The type of operation
-is conveyed by `to` being the zero address or not.
+Indicates an error related to the ownership over a particular token. Used in transfers.
-This call occurs _before_ the token contract's state is updated, so
-[`IERC777.balanceOf`](#IERC777-balanceOf-address-), etc., can be used to query the pre-operation state.
+
+
-This function may revert to prevent the operation from being executed.
+
+
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC7913.sol";
-```
-
-Signature verifier interface.
+Indicates a failure with the token `receiver`. Used in transfers.
-
-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
+Indicates a failure with the `operator`’s approval. Used in transfers.
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC1822.sol";
-```
-
-ERC-1822: Universal Upgradeable Proxy Standard (UUPS) documents a method for upgradeability through a simplified
-proxy whose upgrades are fully controlled by the current implementation.
+Indicates a failure with the `approver` of a token to be approved. Used in approvals.
-
-Returns the storage slot that the proxiable contract assumes is being used to store the implementation
-address.
-
-
-A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
-bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
-function revert if invoked through a proxy.
-
+Indicates a failure with the `operator` to be approved. Used in approvals.
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
```
-A [user operation](https://github.com/ethereum/ercs/blob/master/ERCS/erc-4337.md#useroperation) is composed of the following elements:
-- `sender` (`address`): The account making the operation
-- `nonce` (`uint256`): Anti-replay parameter (see “Semi-abstracted Nonce Support” )
-- `factory` (`address`): account factory, only for new accounts
-- `factoryData` (`bytes`): data for account factory (only if account factory exists)
-- `callData` (`bytes`): The data to pass to the sender during the main execution call
-- `callGasLimit` (`uint256`): The amount of gas to allocate the main execution call
-- `verificationGasLimit` (`uint256`): The amount of gas to allocate for the verification step
-- `preVerificationGas` (`uint256`): Extra gas to pay the bundler
-- `maxFeePerGas` (`uint256`): Maximum fee per gas (similar to EIP-1559 max_fee_per_gas)
-- `maxPriorityFeePerGas` (`uint256`): Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas)
-- `paymaster` (`address`): Address of paymaster contract, (or empty, if account pays for itself)
-- `paymasterVerificationGasLimit` (`uint256`): The amount of gas to allocate for the paymaster validation code
-- `paymasterPostOpGasLimit` (`uint256`): The amount of gas to allocate for the paymaster post-operation code
-- `paymasterData` (`bytes`): Data for paymaster (only if paymaster exists)
-- `signature` (`bytes`): Data passed into the account to verify authorization
+Standard ERC-1155 Errors
+Interface of the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors for ERC-1155 tokens.
+
+
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
-```
+Indicates a failure with the token `sender`. Used in transfers.
-Aggregates and validates multiple signatures for a batch of user operations.
+
+
-A contract could implement this interface with custom validation schemes that allow signature aggregation,
-enabling significant optimizations and gas savings for execution and transaction data cost.
+
-Bundlers and clients whitelist supported aggregators.
+
-Validates the signature for a user operation.
-Returns an alternative signature that should be used during bundling.
+Indicates a failure with the `operator`’s approval. Used in transfers.
-Returns an aggregated signature for a batch of user operation's signatures.
+Indicates a failure with the `approver` of a token to be approved. Used in approvals.
-Validates that the aggregated signature is valid for the user operations.
+Indicates a failure with the `operator` to be approved. Used in approvals.
-Requirements:
+
+
-- The aggregated signature MUST match the given list of operations.
+
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Handle nonce management for accounts.
+
-Nonces are used in accounts as a replay protection mechanism and to ensure the order of user operations.
-To avoid limiting the number of operations an account can perform, the interface allows using parallel
-nonces by using a `key` parameter.
+
-Returns the nonce for a `sender` account and a `key`.
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+```
-Nonces for a certain `key` are always increasing.
+
+
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Handle stake management for entities (i.e. accounts, paymasters, factories).
+
-The EntryPoint must implement the following API to let entities like paymasters have a stake,
-and thus have more flexibility in their storage access
-(see [reputation, throttling and banning.](https://eips.ethereum.org/EIPS/eip-4337#reputation-scoring-and-throttlingbanning-for-global-entities))
+
-Adds stake to the account with an unstake delay of `unstakeDelaySec`.
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+```
+
+ERC-7579 Validation module (type 1).
+
+A module that implements logic to validate user operations and signatures.
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Entry point for user operations.
+ERC-7579 Hooks module (type 4).
-User operations are validated and executed by this contract.
+A module that implements logic to execute before and after the account executes a user operation,
+either individually or batched.
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Base interface for an ERC-4337 account.
+ERC-7579 Execution.
+
+Accounts should implement this interface so that the Entrypoint and ERC-7579 modules can execute operations.
-Validates a user operation.
+Executes a transaction on behalf of the account.
-* MUST validate the caller is a trusted EntryPoint
-* MUST validate that the signature is a valid signature of the userOpHash, and SHOULD
- return SIG_VALIDATION_FAILED (and not revert) on signature mismatch. Any other error MUST revert.
-* MUST pay the entryPoint (caller) at least the “missingAccountFunds” (which might
- be zero, in case the current account’s deposit is high enough)
+
+
-Returns an encoded packed validation data that is composed of the following elements:
+
-- `authorizer` (`address`): 0 for success, 1 for failure, otherwise the address of an authorizer contract
-- `validUntil` (`uint48`): The UserOp is valid only up to this time. Zero for “infinite”.
-- `validAfter` (`uint48`): The UserOp is valid only after this time.
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Support for executing user operations by prepending the [`IAccountExecute.executeUserOp`](#IAccountExecute-executeUserOp-struct-PackedUserOperation-bytes32-) function selector
-to the UserOperation's `callData`.
+ERC-7579 Account Config.
+
+Accounts should implement this interface to expose information that identifies the account, supported modules and capabilities.
-
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
-```
-
-Interface for a paymaster contract that agrees to pay for the gas costs of a user operation.
-
-
-A paymaster must hold a stake to cover the required entrypoint stake and also the gas for the transaction.
-
+Returns the account id of the smart account
-
-Validates whether the paymaster is willing to pay for the user operation. See
-[`IAccount.validateUserOp`](#IAccount-validateUserOp-struct-PackedUserOperation-bytes32-uint256-) for additional information on the return value.
-
-
-Bundlers will reject this method if it modifies the state, unless it's whitelisted.
-
+Function to check if the account supports a certain execution mode (see above)
-Indicates that an address can't be an owner. For example, `address(0)` is a forbidden owner in ERC-721.
-Used in balance queries.
+Set the temporary allowance, allowing `spender` to withdraw (within the same transaction) assets
+held by the caller.
+Interface for ERC-7786 source gateways.
-Indicates an error related to the ownership over a particular token. Used in transfers.
+See ERC-7786 for more details
+
-Indicates a failure with the `operator`’s approval. Used in transfers.
+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 `sendId` 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.
-Indicates a failure with the `approver` of a token to be approved. Used in approvals.
+Event emitted when a message is created. If `sendId` is zero, no further processing is necessary. If
+`sendId` is not zero, then further (gateway specific, and non-standardized) action is required.
-Indicates a failure with the `operator` to be approved. Used in approvals.
+This error is thrown when a message creation fails because of an unsupported attribute being specified.
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7786.sol";
```
-Standard ERC-1155 Errors
-Interface of the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors for ERC-1155 tokens.
+Interface for the ERC-7786 client contract (receiver).
+
+See ERC-7786 for more details
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-```
-
-
+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
-## `MODULE_TYPE_VALIDATOR`
+Supported modes:
+- `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.
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-```
+For calldata compression efficiency, if a Call.to is `address(0)`,
+it will be replaced with `address(this)`.
-
+
-
-
-
+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`.
+
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-```
+Whenever ERC-1363 tokens are transferred to this contract via `transferAndCall` or `transferFromAndCall`
+by `operator` from `from`, this function is called.
-
+
+To accept the transfer, this must return
+`bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)"))`
+(i.e. 0x88a7ca5c, or its own function selector).
+
+
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+import "@openzeppelin/contracts/interfaces/IERC1363Spender.sol";
```
-Minimal configuration interface for ERC-7579 modules
+Interface for any contract that wants to support `approveAndCall`
+from ERC-1363 token contracts.
-This function is called by the smart account during installation of the module
+Whenever an ERC-1363 token `owner` approves this contract via `approveAndCall`
+to spend their tokens, this function is called.
+
+
+To accept the approval, this must return
+`bytes4(keccak256("onApprovalReceived(address,uint256,bytes)"))`
+(i.e. 0x7b04a2d0, or its own function selector).
+
-This function is called by the smart account during uninstallation of the module
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC1820Implementer.sol";
+```
+
+Interface for an ERC-1820 implementer, as defined in the
+[ERC](https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface).
+Used by contracts that will be registered as implementers in the
+[`IERC1820Registry`](#IERC1820Registry).
+
-Returns boolean value if module is a certain type
+Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract
+implements `interfaceHash` for `account`.
+
+See [`IERC1820Registry.setInterfaceImplementer`](#IERC1820Registry-setInterfaceImplementer-address-bytes32-address-).
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+import "@openzeppelin/contracts/interfaces/IERC1820Registry.sol";
```
-ERC-7579 Validation module (type 1).
+Interface of the global ERC-1820 Registry, as defined in the
+[ERC](https://eips.ethereum.org/EIPS/eip-1820). Accounts may register
+implementers for interfaces in this registry, as well as query support.
-A module that implements logic to validate user operations and signatures.
+Implementers may be shared by multiple accounts, and can also implement more
+than a single interface for each account. Contracts can implement interfaces
+for themselves, but externally-owned accounts (EOA) must delegate this to a
+contract.
+
+[`IERC165`](/contracts/5.x/api/utils#IERC165) interfaces can also be queried via the registry.
+
+For an in-depth explanation and source code analysis, see the ERC text.
-Validates a UserOperation
+Sets `newManager` as the manager for `account`. A manager of an
+account is able to set interface implementers for it.
+
+By default, each account is its own manager. Passing a value of `0x0` in
+`newManager` will reset the manager to this initial state.
+
+Emits a [`IERC1820Registry.ManagerChanged`](#IERC1820Registry-ManagerChanged-address-address-) event.
+
+Requirements:
+
+- the caller must be the current manager for `account`.
-Validates a signature using ERC-1271
+Returns the manager for `account`.
+
+See [`IERC1820Registry.setManager`](#IERC1820Registry-setManager-address-address-).
-## `IERC7579Hook`
+Sets the `implementer` contract as ``account``'s implementer for
+`interfaceHash`.
-
-
-
+`account` being the zero address is an alias for the caller's address.
+The zero address can also be used in `implementer` to remove an old one.
-
+See [`IERC1820Registry.interfaceHash`](#IERC1820Registry-interfaceHash-string-) to learn how these are created.
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-```
+Emits an [`IERC1820Registry.InterfaceImplementerSet`](#IERC1820Registry-InterfaceImplementerSet-address-bytes32-address-) event.
-ERC-7579 Hooks module (type 4).
+Requirements:
-A module that implements logic to execute before and after the account executes a user operation,
-either individually or batched.
+- the caller must be the current manager for `account`.
+- `interfaceHash` must not be an [`IERC165`](/contracts/5.x/api/utils#IERC165) interface id (i.e. it must not
+end in 28 zeroes).
+- `implementer` must implement [`IERC1820Implementer`](#IERC1820Implementer) and return true when
+queried for support, unless `implementer` is the caller. See
+[`IERC1820Implementer.canImplementInterfaceForAddress`](#IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-).
-
-Called by the smart account before execution
+Returns the implementer of `interfaceHash` for `account`. If no such
+implementer is registered, returns the zero address.
+
+If `interfaceHash` is an [`IERC165`](/contracts/5.x/api/utils#IERC165) interface id (i.e. it ends with 28
+zeroes), `account` will be queried for support of it.
+
+`account` being the zero address is an alias for the caller's address.
-Called by the smart account after execution
+Returns the interface hash for an `interfaceName`, as defined in the
+corresponding
+[section of the ERC](https://eips.ethereum.org/EIPS/eip-1820#interface-name).
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+import "@openzeppelin/contracts/interfaces/IERC2612.sol";
```
-ERC-7579 Account Config.
-
-Accounts should implement this interface to expose information that identifies the account, supported modules and capabilities.
-
-Function to check if the account supports a certain execution mode (see above)
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC7751.sol";
+```
+
+Wrapping of bubbled up reverts
+Interface of the [ERC-7751](https://eips.ethereum.org/EIPS/eip-7751) wrapping of bubbled up reverts.
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+import "@openzeppelin/contracts/interfaces/IERC777.sol";
```
-ERC-7579 Module Config.
+Interface of the ERC-777 Token standard as defined in the ERC.
-Accounts should implement this interface to allow installing and uninstalling modules.
+This contract uses the
+[ERC-1820 registry standard](https://eips.ethereum.org/EIPS/eip-1820) to let
+token holders and recipients react to token movements by using setting implementers
+for the associated interfaces in said registry. See [`IERC1820Registry`](#IERC1820Registry) and
+[`IERC1820Implementer`](#IERC1820Implementer).
-Returns whether a module is installed on the smart account
+Returns the smallest part of the token that is not divisible. This
+means all token operations (creation, movement and destruction) must have
+amounts that are a multiple of this number.
+
+For most token contracts, this value will equal 1.
-
-
-
+Moves `amount` tokens from the caller's account to `recipient`.
-
+If send or receive hooks are registered for the caller and `recipient`,
+the corresponding functions will be called with `data` and empty
+`operatorData`. See [`IERC777Sender`](#IERC777Sender) and [`IERC777Recipient`](#IERC777Recipient).
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7674.sol";
-```
+Emits a [`IERC777.Sent`](#IERC777-Sent-address-address-address-uint256-bytes-bytes-) event.
-Temporary Approval Extension for ERC-20 ([ERC-7674](https://github.com/ethereum/ERCs/pull/358))
+Requirements
-
+- the caller must have at least `amount` tokens.
+- `recipient` cannot be the zero address.
+- if `recipient` is a contract, it must implement the [`IERC777Recipient`](#IERC777Recipient)
+interface.
-
-Set the temporary allowance, allowing `spender` to withdraw (within the same transaction) assets
-held by the caller.
-
-
-
+Destroys `amount` tokens from the caller's account, reducing the
+total supply.
-
+If a send hook is registered for the caller, the corresponding function
+will be called with `data` and empty `operatorData`. See [`IERC777Sender`](#IERC777Sender).
-
+Emits a [`IERC777.Burned`](#IERC777-Burned-address-address-uint256-bytes-bytes-) event.
-## `IERC7786GatewaySource`
+Requirements
-
-
-
+- the caller must have at least `amount` tokens.
+
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7786.sol";
-```
-
-Interface for ERC-7786 source gateways.
-
-See ERC-7786 for more details
+
-
+Returns true if an account is an operator of `tokenHolder`.
+Operators can send and burn tokens on behalf of their owners. All
+accounts are their own operator.
+
+See [`IERC777.operatorSend`](#IERC777-operatorSend-address-address-uint256-bytes-bytes-) and [`IERC777.operatorBurn`](#IERC777-operatorBurn-address-uint256-bytes-bytes-).
-
-Getter to check whether an attribute is supported or not.
+Make an account an operator of the caller.
+
+See [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-).
+
+Emits an [`IERC777.AuthorizedOperator`](#IERC777-AuthorizedOperator-address-address-) event.
+
+Requirements
+
+- `operator` cannot be calling address.
-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 `sendId` must be returned. Otherwise, the
-message MUST be sent and this function must return 0.
+Revoke an account's operator status for the caller.
+
+See [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-) and [`IERC777.defaultOperators`](#IERC777-defaultOperators--).
-* MUST emit a [`IERC7786GatewaySource.MessageSent`](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) event.
+Emits a [`IERC777.RevokedOperator`](#IERC777-RevokedOperator-address-address-) 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.
+Requirements
+
+- `operator` cannot be calling address.
-Event emitted when a message is created. If `sendId` is zero, no further processing is necessary. If
-`sendId` is not zero, then further (gateway specific, and non-standardized) action is required.
+Returns the list of default operators. These accounts are operators
+for all token holders, even if [`IERC777.authorizeOperator`](#IERC777-authorizeOperator-address-) was never called on
+them.
+
+This list is immutable, but individual holders may revoke these via
+[`IERC777.revokeOperator`](#IERC777-revokeOperator-address-), in which case [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-) will return false.
-This error is thrown when a message creation fails because of an unsupported attribute being specified.
-
-
-
-
-
-
-
-
-## `IERC7786Recipient`
-
-
-
-
+Moves `amount` tokens from `sender` to `recipient`. The caller must
+be an operator of `sender`.
-
+If send or receive hooks are registered for `sender` and `recipient`,
+the corresponding functions will be called with `data` and
+`operatorData`. See [`IERC777Sender`](#IERC777Sender) and [`IERC777Recipient`](#IERC777Recipient).
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7786.sol";
-```
+Emits a [`IERC777.Sent`](#IERC777-Sent-address-address-address-uint256-bytes-bytes-) event.
-Interface for the ERC-7786 client contract (receiver).
+Requirements
-See ERC-7786 for more details
+- `sender` cannot be the zero address.
+- `sender` must have at least `amount` tokens.
+- the caller must be an operator for `sender`.
+- `recipient` cannot be the zero address.
+- if `recipient` is a contract, it must implement the [`IERC777Recipient`](#IERC777Recipient)
+interface.
-
-Endpoint for receiving cross-chain message.
-
-This function may be called directly by the gateway.
-
-
-
+Destroys `amount` tokens from `account`, reducing the total supply.
+The caller must be an operator of `account`.
-
+If a send hook is registered for `account`, the corresponding function
+will be called with `data` and `operatorData`. See [`IERC777Sender`](#IERC777Sender).
-
+Emits a [`IERC777.Burned`](#IERC777-Burned-address-address-uint256-bytes-bytes-) event.
-## `IERC7802`
+Requirements
-
-
-
+- `account` cannot be the zero address.
+- `account` must have at least `amount` tokens.
+- the caller must be an operator for `account`.
+
+
+Emitted when `amount` tokens are created by `operator` and assigned to `to`.
+
+Note that some additional user `data` and `operatorData` can be logged in the event.
+
+Emitted when `operator` destroys `amount` tokens from `account`.
+
+Note that some additional user `data` and `operatorData` can be logged in the event.
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7821.sol";
+import "@openzeppelin/contracts/interfaces/IERC777Recipient.sol";
```
-Interface for minimal batch executor.
+Interface of the ERC-777 Tokens Recipient standard as defined in the ERC.
+
+Accounts can be notified of [`IERC777`](#IERC777) tokens being sent to them by having a
+contract implement this interface (contract holders can be their own
+implementer) and registering it on the
+[ERC-1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+
+See [`IERC1820Registry`](#IERC1820Registry) and [`IERC1820Implementer`](#IERC1820Implementer).
-Executes the calls in `executionData`.
-Reverts and bubbles up error if any call fails.
+Called by an [`IERC777`](#IERC777) token contract whenever tokens are being
+moved or created into a registered account (`to`). The type of operation
+is conveyed by `from` being the zero address or not.
-`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
+This call occurs _after_ the token contract's state is updated, so
+[`IERC777.balanceOf`](#IERC777-balanceOf-address-), etc., can be used to query the post-operation state.
-Supported modes:
-- `bytes32(0x01000000000000000000...)`: does not support optional `opData`.
-- `bytes32(0x01000000000078210001...)`: supports optional `opData`.
+This function may revert to prevent the operation from being executed.
-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.
+
-For calldata compression efficiency, if a Call.to is `address(0)`,
-it will be replaced with `address(this)`.
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC777Sender.sol";
+```
+Interface of the ERC-777 Tokens Sender standard as defined in the ERC.
+
+[`IERC777`](#IERC777) Token holders can be notified of operations performed on their
+tokens by having a contract implement this interface (contract holders can be
+their own implementer) and registering it on the
+[ERC-1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+
+See [`IERC1820Registry`](#IERC1820Registry) and [`IERC1820Implementer`](#IERC1820Implementer).
+
+
+
Functions
+
+- [tokensToSend(operator, from, to, amount, userData, operatorData)](#IERC777Sender-tokensToSend-address-address-address-uint256-bytes-bytes-)
-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`.
+Called by an [`IERC777`](#IERC777) token contract whenever a registered holder's
+(`from`) tokens are about to be moved or destroyed. The type of operation
+is conveyed by `to` being the zero address or not.
+
+This call occurs _before_ the token contract's state is updated, so
+[`IERC777.balanceOf`](#IERC777-balanceOf-address-), etc., can be used to query the pre-operation state.
+
+This function may revert to prevent the operation from being executed.
+
diff --git a/content/contracts/5.x/api/metatx.mdx b/content/contracts/5.x/api/metatx.mdx
index 4fcbd986..966c6b41 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,
@@ -258,6 +258,7 @@ used to execute arbitrary code.
Errors
+- [ERC2771ForwarderFailureInAtomicBatch()](#ERC2771Forwarder-ERC2771ForwarderFailureInAtomicBatch--)
- [ERC2771ForwarderInvalidSigner(signer, from)](#ERC2771Forwarder-ERC2771ForwarderInvalidSigner-address-address-)
- [ERC2771ForwarderMismatchedValue(requestedValue, msgValue)](#ERC2771Forwarder-ERC2771ForwarderMismatchedValue-uint256-uint256-)
- [ERC2771ForwarderExpiredRequest(deadline)](#ERC2771Forwarder-ERC2771ForwarderExpiredRequest-uint48-)
@@ -304,7 +305,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 +331,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 +348,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 +364,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 +388,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 +409,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 +434,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 +495,23 @@ the requested call to run out of gas.
+
+One of the calls in an atomic batch failed.
+
+
+
+
@@ -561,3 +579,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..9be54050 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.
@@ -517,8 +526,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 +562,53 @@ the [`eth_getStorageAt`](https://eth.wiki/json-rpc/API#eth_getstorageat) RPC cal
+
+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.
+
+
+
-## `ERC1967Utils`
+## `ERC1967Utils`
-
+
@@ -645,7 +697,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 +758,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 +839,9 @@ An upgrade function sees `msg.value > 0` that may be lost.
-## `Proxy`
+## `Proxy`
-
+
@@ -801,8 +855,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 +902,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 +948,9 @@ function in the contract matches the call data.
-## `BeaconProxy`
+## `BeaconProxy`
-
+
@@ -912,8 +966,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
@@ -997,9 +1053,9 @@ Returns the beacon.
-## `IBeacon`
+## `IBeacon`
-
+
@@ -1037,164 +1093,13 @@ Must return an address that can be used as a delegate call target.
-
-```solidity
-import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";
-```
-
-This contract is used in conjunction with one or more instances of [`BeaconProxy`](#BeaconProxy) to determine their
-implementation contract, which is where they will delegate all function calls.
-
-An owner is able to change the implementation the beacon points to, thus upgrading the proxies that use this beacon.
-
-
-
-Upgrades the beacon to a new implementation.
-
-Emits an [`IERC1967.Upgraded`](/contracts/5.x/api/interfaces#IERC1967-Upgraded-address-) event.
-
-Requirements:
-
-- msg.sender must be the owner of the contract.
-- `newImplementation` must be a contract.
-
-
```solidity
-import "@openzeppelin/contracts/proxy/utils/Initializable.sol";
-```
-
-This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed
-behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an
-external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer
-function so it can only be called once. The [`Initializable.initializer`](#Initializable-initializer--) modifier provided by this contract will have this effect.
-
-The initialization functions use a version number. Once a version number is used, it is consumed and cannot be
-reused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps in
-case an upgrade adds a module that needs to be initialized.
-
-For example:
-
-[.hljs-theme-light.nopadding]
-```solidity
-contract MyToken is ERC20Upgradeable {
- function initialize() initializer public {
- __ERC20_init("MyToken", "MTK");
- }
-}
-
-contract MyTokenV2 is MyToken, ERC20PermitUpgradeable {
- function initializeV2() reinitializer(2) public {
- __ERC20Permit_init("MyToken");
- }
-}
+import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
```
-
-To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as
-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
-that all initializers are idempotent. This is not verified automatically as constructors are by Solidity.
+An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an
+[`ERC1967Proxy`](#ERC1967Proxy), when this contract is set as the implementation behind such a proxy.
-
-Avoid leaving a contract uninitialized.
+A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is
+reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing
+`UUPSUpgradeable` with a custom implementation of upgrades.
-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
-the [`Initializable._disableInitializers`](#Initializable-_disableInitializers--) function in the constructor to automatically lock it when it is deployed:
+The [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-) function must be overridden to include access restriction to the upgrade mechanism.
-[.hljs-theme-light.nopadding]
-```
-/// @custom:oz-upgrades-unsafe-allow constructor
-constructor() {
- _disableInitializers();
-}
-```
-
+@custom:stateless
+
+Check that the execution is being performed through a delegatecall call and that the execution context is
+a proxy contract with an implementation (as defined in ERC-1967) pointing to self. This should only be the case
+for UUPS and transparent proxies that are using the current contract as their implementation. Execution of a
+function through ERC-1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed to
+fail.
+
+
+
+Check that the execution is not being performed through a delegate call. This allows a function to be
+callable on the implementing contract but not through proxies.
+
+
+
+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.
+
+
+A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
+bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
+function revert if invoked through a proxy. This is guaranteed by the `notDelegated` modifier.
+
+
+
+
+Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
+encoded in `data`.
+
+Calls [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-).
+
+Emits an [`UpgradeableBeacon.Upgraded`](#UpgradeableBeacon-Upgraded-address-) event.
+
+
+
+Reverts if the execution is not performed via delegatecall or the execution
+context is not of a proxy with an ERC-1967 compliant implementation pointing to self.
+
+
+
+Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by
+[`ERC1967Utils.upgradeToAndCall`](#ERC1967Utils-upgradeToAndCall-address-bytes-).
+
+Normally, this function will use an [access control](/contracts/5.x/api/access) modifier such as [`Ownable.onlyOwner`](/contracts/5.x/api/access#Ownable-onlyOwner--).
+
+```solidity
+function _authorizeUpgrade(address) internal onlyOwner {}
+```
+
+
+
+The version of the upgrade interface of the contract. If this getter is missing, both `upgradeTo(address)`
+and `upgradeToAndCall(address,bytes)` are present, and `upgradeTo` must be used if no function should be called,
+while `upgradeToAndCall` will invoke the `receive` function if the second argument is the empty byte string.
+If the getter returns `"5.0.0"`, only `upgradeToAndCall(address,bytes)` is present, and the second argument must
+be the empty byte string if no function should be called, making it impossible to invoke the `receive` function
+during an upgrade.
+
+
+
+```solidity
+import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";
+```
+
+This contract is used in conjunction with one or more instances of [`BeaconProxy`](#BeaconProxy) to determine their
+implementation contract, which is where they will delegate all function calls.
+
+An owner is able to change the implementation the beacon points to, thus upgrading the proxies that use this beacon.
+
+
+
+Upgrades the beacon to a new implementation.
+
+Emits an [`UpgradeableBeacon.Upgraded`](#UpgradeableBeacon-Upgraded-address-) event.
+
+Requirements:
+
+- msg.sender must be the owner of the contract.
+- `newImplementation` must be a contract.
+
+
+
+```solidity
+import "@openzeppelin/contracts/proxy/utils/Initializable.sol";
+```
+
+This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed
+behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an
+external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer
+function so it can only be called once. The [`Initializable.initializer`](#Initializable-initializer--) modifier provided by this contract will have this effect.
+
+The initialization functions use a version number. Once a version number is used, it is consumed and cannot be
+reused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps in
+case an upgrade adds a module that needs to be initialized.
+
+For example:
+
+[.hljs-theme-light.nopadding]
+```solidity
+contract MyToken is ERC20Upgradeable {
+ function initialize() initializer public {
+ __ERC20_init("MyToken", "MTK");
+ }
+}
+
+contract MyTokenV2 is MyToken, ERC20PermitUpgradeable {
+ function initializeV2() reinitializer(2) public {
+ __ERC20Permit_init("MyToken");
+ }
+}
+```
+
+
+To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as
+possible by providing the encoded function call as the `_data` argument to [`ERC1967Proxy.constructor`](#ERC1967Proxy-constructor-address-bytes-).
+
+
+
+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.
+
+
+[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
+the [`Initializable._disableInitializers`](#Initializable-_disableInitializers--) function in the constructor to automatically lock it when it is deployed:
+
+[.hljs-theme-light.nopadding]
+```
+/// @custom:oz-upgrades-unsafe-allow constructor
+constructor() {
+ _disableInitializers();
+}
+```
+
+
-
-```solidity
-import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
-```
-
-An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an
-[`ERC1967Proxy`](#ERC1967Proxy), when this contract is set as the implementation behind such a proxy.
-
-A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is
-reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing
-`UUPSUpgradeable` with a custom implementation of upgrades.
-
-The [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-) function must be overridden to include access restriction to the upgrade mechanism.
-
-@custom:stateless
-
-
-
-Check that the execution is being performed through a delegatecall call and that the execution context is
-a proxy contract with an implementation (as defined in ERC-1967) pointing to self. This should only be the case
-for UUPS and transparent proxies that are using the current contract as their implementation. Execution of a
-function through ERC-1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed to
-fail.
-
-
-
-Check that the execution is not being performed through a delegate call. This allows a function to be
-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. It is used to validate the implementation's compatibility when performing an upgrade.
-
-
-A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
-bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
-function revert if invoked through a proxy. This is guaranteed by the `notDelegated` modifier.
-
-
-
-
-Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
-encoded in `data`.
-
-Calls [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-).
-
-Emits an [`IERC1967.Upgraded`](/contracts/5.x/api/interfaces#IERC1967-Upgraded-address-) event.
-
-
-
-Reverts if the execution is not performed via delegatecall or the execution
-context is not of a proxy with an ERC-1967 compliant implementation pointing to self.
-
-
-
-Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by
-[`ERC1967Utils.upgradeToAndCall`](#ERC1967Utils-upgradeToAndCall-address-bytes-).
-
-Normally, this function will use an [access control](/contracts/5.x/api/access) modifier such as [`Ownable.onlyOwner`](/contracts/5.x/api/access#Ownable-onlyOwner--).
-
-```solidity
-function _authorizeUpgrade(address) internal onlyOwner {}
-```
-
-
-
-The version of the upgrade interface of the contract. If this getter is missing, both `upgradeTo(address)`
-and `upgradeToAndCall(address,bytes)` are present, and `upgradeTo` must be used if no function should be called,
-while `upgradeToAndCall` will invoke the `receive` function if the second argument is the empty byte string.
-If the getter returns `"5.0.0"`, only `upgradeToAndCall(address,bytes)` is present, and the second argument must
-be the empty byte string if no function should be called, making it impossible to invoke the `receive` function
-during an upgrade.
-
-
-
-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..acdcbe2b 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-)
@@ -316,7 +321,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 +341,23 @@ acceptance magic value.
+
+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 +382,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 +410,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.
+
+
+
+
+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 +481,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 +564,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 +614,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 +645,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 +655,9 @@ Requirements:
-## `IERC1155`
+## `IERC1155`
-
+
@@ -671,7 +724,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 +821,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 +920,9 @@ returned by [`IERC1155MetadataURI.uri`](#IERC1155MetadataURI-uri-uint256-).
-## `IERC1155Receiver`
+## `IERC1155Receiver`
-
+
@@ -945,9 +998,9 @@ To accept the transfer(s), this must return
-## `ERC1155Burnable`
+## `ERC1155Burnable`
-
+
@@ -974,8 +1027,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-)
@@ -1057,13 +1112,198 @@ own tokens and those that they have been approved to use.
+
+```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),
+
+
+
+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
+
+TransferFrom variant of [`ERC1155Crosschain.crosschainTransferFrom`](#ERC1155Crosschain-crosschainTransferFrom-address-bytes-uint256---uint256---), using ERC1155 allowance from the sender to the caller.
+
+
+
+"Unlocking" tokens is achieved through minting
+
+
+
+
-## `ERC1155Pausable`
+## `ERC1155Pausable`
-
+
@@ -1082,8 +1322,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.
@@ -1106,7 +1346,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-)
@@ -1189,9 +1431,9 @@ Requirements:
-## `ERC1155Supply`
+## `ERC1155Supply`
-
+
@@ -1204,16 +1446,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
@@ -1231,7 +1475,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-)
@@ -1295,7 +1541,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 +1575,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 +1604,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 +1614,9 @@ The ERC-1155 acceptance check is not performed in this function. See [`ERC1155._
-## `ERC1155URIStorage`
+## `ERC1155URIStorage`
-
+
@@ -1397,8 +1643,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-)
@@ -1520,9 +1768,9 @@ Sets `baseURI` as the `_baseURI` for all tokens
-## `IERC1155MetadataURI`
+## `IERC1155MetadataURI`
-
+
@@ -1587,9 +1835,9 @@ clients with the actual token type ID.
-## `ERC1155Holder`
+## `ERC1155Holder`
-
+
@@ -1676,9 +1924,9 @@ This function call must use less than 30 000 gas.
+
diff --git a/content/contracts/5.x/api/token/ERC20.mdx b/content/contracts/5.x/api/token/ERC20.mdx
index f0473dda..272a596c 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
@@ -180,7 +183,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 +323,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 +371,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 +403,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 +431,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 +451,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 +475,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 +501,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 +525,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 +562,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 +571,9 @@ Does not emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-a
-## `IERC20`
+## `IERC20`
-
+
@@ -652,7 +655,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 +673,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 +707,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 +730,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,46 +769,57 @@ 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.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC1363.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Crosschain.sol";
```
-Extension of [`ERC20`](#ERC20) tokens that adds support for code execution after transfers and approvals
-on recipient contracts. Calls after transfers are enabled through the [`ERC1363.transferAndCall`](#ERC1363-transferAndCall-address-uint256-bytes-) and
-[`ERC1363.transferFromAndCall`](#ERC1363-transferFromAndCall-address-address-uint256-bytes-) methods while calls after approvals can be made with [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-)
+Extension of [`ERC20`](#ERC20) that makes it natively cross-chain using the ERC-7786 based [`BridgeFungible`](/contracts/5.x/api/crosschain#BridgeFungible).
-_Available since v5.1._
+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.
-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.
+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.
-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
-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`).
+"Locking" tokens is achieved through burning
-
+
-
transferAndCall(address to, uint256 value, bytes data) → bool
-Variant of [`IERC1363.transferAndCall`](../interfaces#IERC1363-transferAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with
-no specified format.
+"Unlocking" tokens is achieved through minting
+
+```solidity
+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 [`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,
+[`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.
+
+
+
-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
-if the call succeeded.
-
-Requirements:
+Returns the maximum amount of tokens available for loan.
-- 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`).
+
+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.
+
-
+
-
transferFromAndCall(address from, address to, uint256 value, bytes data) → bool
-Variant of [`IERC1363.transferFromAndCall`](../interfaces#IERC1363-transferFromAndCall-address-address-uint256-bytes-) that accepts an additional `data` parameter with
-no specified format.
+Returns the fee applied when doing flash loans. This function calls
+the [`ERC20FlashMint._flashFee`](#ERC20FlashMint-_flashFee-address-uint256-) function which returns the fee applied when doing flash
+loans.
-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`.
-Returns a flag that indicates if the call succeeded.
+Returns the fee applied when doing flash loans. By default this
+implementation has 0 fees. This function can be overloaded to make
+the flash loan mechanism deflationary.
-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`).
+
+
-
+Returns the receiver address of the flash fee. By default this
+implementation returns the address(0) which means the fee amount will be burnt.
+This function can be overloaded to change the fee receiver.
+
+
-Variant of [`IERC1363.approveAndCall`](../interfaces#IERC1363-approveAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with
-no specified format.
+Performs a flash loan. New tokens are minted and sent to the
+`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.
-Indicates a failure within the [`IERC6909.transfer`](../interfaces#IERC6909-transfer-address-uint256-uint256-) part of a transferAndCall operation.
+The loan token is not valid.
-Indicates a failure within the [`IERC6909.transferFrom`](../interfaces#IERC6909-transferFrom-address-address-uint256-uint256-) part of a transferFromAndCall operation.
+The requested loan exceeds the max loan value for `token`.
-Indicates a failure within the [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-uint256-) part of a approveAndCall operation.
+The receiver of a flashloan is not a valid [`IERC3156FlashBorrower.onFlashLoan`](/contracts/5.x/api/interfaces#IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-) implementer.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";
```
-Extension of [`ERC20`](#ERC20) that allows token holders to destroy both their own
-tokens and those that they have an allowance for, in a way that can be
-recognized off-chain (via event analysis).
+Implementation of the ERC-20 Permit extension allowing approvals to be made via signatures, as defined in
+[ERC-2612](https://eips.ethereum.org/EIPS/eip-2612).
+
+Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) method, which can be used to change an account's ERC-20 allowance (see [`IERC20.allowance`](#IERC20-allowance-address-address-)) by
+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.
-Destroys a `value` amount of tokens from the caller.
+Initializes the [`EIP712`](/contracts/5.x/api/utils/cryptography#EIP712) domain separator using the `name` parameter, and setting `version` to `"1"`.
-See [`ERC20._burn`](#ERC20-_burn-address-uint256-).
+It's a good idea to use the same `name` that is defined as the ERC-20 token name.
-Destroys a `value` amount of tokens from `account`, deducting from
-the caller's allowance.
+Sets `value` as the allowance of `spender` over ``owner``'s tokens,
+given ``owner``'s signed approval.
-See [`ERC20._burn`](#ERC20-_burn-address-uint256-) and [`ERC20.allowance`](#ERC20-allowance-address-address-).
+
+The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related to transaction
+ordering also applies here.
+
+
+Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
Requirements:
-- the caller must have allowance for ``accounts``'s tokens of at least
-`value`.
+- `spender` cannot be the zero address.
+- `deadline` must be a timestamp in the future.
+- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
+over the EIP712-formatted function arguments.
+- the signature must use ``owner``'s current nonce (see [`ERC20Permit.nonces`](#ERC20Permit-nonces-address-)).
+
+For more information on the signature format, see the
+[relevant EIP
+section](https://eips.ethereum.org/EIPS/eip-2612#specification).
+
+
+See Security Considerations above.
+
+
+Returns the current nonce for `owner`. This value must be
+included whenever a signature is generated for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-).
+
+Every successful call to [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) increases ``owner``'s nonce by one. This
+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`](/contracts/5.x/api/utils/cryptography#EIP712).
+
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol";
```
-Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens.
+Extension of ERC-20 to support Compound-like voting and delegation. This version is more generic than Compound's,
+and supports token supply up to 2^208^ - 1, while COMP is limited to 2^96^ - 1.
+
+
+This contract does not provide interface compatibility with Compound's COMP token.
+
+
+This extension keeps a history (checkpoints) of each account's vote power. Vote power can be delegated either
+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.
-Sets the value of the `cap`. This value is immutable, it can only be
-set once during construction.
+Maximum token supply. Defaults to `type(uint208).max` (2^208^ - 1).
+
+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.
-Returns the cap on the token's total supply.
+Move voting power when tokens are transferred.
+
+Emits a [`IVotes.DelegateVotesChanged`](/contracts/5.x/api/governance#IVotes-DelegateVotesChanged-address-uint256-uint256-) event.
-Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from`
-(or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding
-this function.
+Returns the voting units of an `account`.
-Emits a [`IERC6909.Transfer`](../interfaces#IERC6909-Transfer-address-address-address-uint256-uint256-) event.
+
+Overriding this function may compromise the internal vote accounting.
+`ERC20Votes` assumes tokens map to voting units 1:1 and this is not easy to change.
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20FlashMint.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Wrapper.sol";
```
-Implementation of the ERC-3156 Flash loans extension, as defined in
-[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
+Extension of the ERC-20 token contract to support token wrapping.
-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-).
+Users can deposit and withdraw "underlying tokens" and receive a matching number of "wrapped tokens". This is useful
+in conjunction with other modules. For example, combining this wrapping mechanism with [`ERC20Votes`](#ERC20Votes) will allow the
+wrapping of an existing "basic" ERC-20 into a governance token.
-
-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.
+
+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.
-
-Returns the fee applied when doing flash loans. This function calls
-the [`ERC20FlashMint._flashFee`](#ERC20FlashMint-_flashFee-address-uint256-) function which returns the fee applied when doing flash
-loans.
-
-
-Returns the fee applied when doing flash loans. By default this
-implementation has 0 fees. This function can be overloaded to make
-the flash loan mechanism deflationary.
-
-Returns the receiver address of the flash fee. By default this
-implementation returns the address(0) which means the fee amount will be burnt.
-This function can be overloaded to change the fee receiver.
+Returns the address of the underlying ERC-20 token that is being wrapped.
-Performs a flash loan. New tokens are minted and sent to the
-`receiver`, who is required to implement the [`IERC3156FlashBorrower`](../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.
+Allow a user to deposit underlying tokens and mint the corresponding number of wrapped tokens.
-The requested loan exceeds the max loan value for `token`.
+Mint wrapped token to cover any underlyingTokens that would have been transferred by mistake or acquired from
+rebasing mechanisms. Internal function that can be exposed with access control if desired.
-The receiver of a flashloan is not a valid [`IERC3156FlashBorrower.onFlashLoan`](../interfaces#IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-) implementer.
+The underlying token couldn't be wrapped.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
```
-ERC-20 token with pausable token transfers, minting and burning.
+Implementation of the ERC-4626 "Tokenized Vault Standard" as defined in
+[ERC-4626](https://eips.ethereum.org/EIPS/eip-4626).
-Useful for scenarios such as preventing trades until the end of an evaluation
-period, or having an emergency switch for freezing all token transfers in the
-event of a large bug.
+This extension allows the minting and burning of "shares" (represented using the ERC-20 inheritance) in exchange for
+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.
-
-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
-make the contract pause mechanism of the contract unreachable, and thus unusable.
-
+[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
+similarly be affected by slippage. Users can protect against this attack as well as unexpected slippage in general by
+verifying the amount received is as expected, using a wrapper that performs these checks such as
+[ERC4626Router](https://github.com/fei-protocol/ERC4626#erc4626router-and-base).
+
+Since v4.9, this implementation introduces configurable virtual assets and shares to help developers mitigate that risk.
+The `_decimalsOffset()` corresponds to an offset in the decimal representation between the underlying asset's decimals
+and the vault decimals. This offset also determines the rate of virtual shares to virtual assets in the vault, which
+itself determines the initial exchange rate. While not fully preventing the attack, analysis shows that the default
+offset (0) makes it non-profitable even if an attacker is able to capture value from multiple user deposits, as a result
+of the value being captured by the virtual shares (out of the attacker's donation) matching the attacker's expected gains.
+With a larger offset, the attack becomes orders of magnitude more expensive than it is profitable. More details about the
+underlying math can be found [here](/contracts/5.x/erc4626#inflation-attack).
+
+The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued
+to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets
+will cause the first user to exit to experience reduced losses in detriment to the last users that will experience
+bigger losses. Developers willing to revert back to the pre-v4.9 behavior just need to override the
+`_convertToShares` and `_convertToAssets` functions.
+
+To learn more, check out our [ERC-4626 guide](/contracts/5.x/erc4626).
+#### [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 [`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.
+
+* [`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 [`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.
-See [`ERC20._update`](#ERC20-_update-address-address-uint256-).
-
-Requirements:
-
-- the contract must not be paused.
+Set the underlying asset contract. This must be an ERC20-compatible contract (ERC-20 or ERC-777).
-```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";
-```
-
-Implementation of the ERC-20 Permit extension allowing approvals to be made via signatures, as defined in
-[ERC-2612](https://eips.ethereum.org/EIPS/eip-2612).
+Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This
+"original" value is cached during construction of the vault contract. If this read operation fails (e.g., the
+asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals.
-Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) method, which can be used to change an account's ERC-20 allowance (see [`IERC20.allowance`](#IERC20-allowance-address-address-)) by
-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.
+See [`IERC20Metadata.decimals`](#IERC20Metadata-decimals--).
-
+
+Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.
+
+- MUST be an ERC-20 token contract.
+- MUST NOT revert.
-
-Initializes the [`EIP712`](../utils/cryptography#EIP712) domain separator using the `name` parameter, and setting `version` to `"1"`.
+Returns the total amount of the underlying asset that is “managed” by Vault.
-It's a good idea to use the same `name` that is defined as the ERC-20 token name.
+- SHOULD include any compounding that occurs from yield.
+- MUST be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT revert.
-Sets `value` as the allowance of `spender` over ``owner``'s tokens,
-given ``owner``'s signed approval.
+Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal
+scenario where all the conditions are met.
-
-The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related to transaction
-ordering also applies here.
+- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT show any variations depending on the caller.
+- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
+- MUST NOT revert.
+
+
+This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
+“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
+from.
-Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event.
+
+
-Requirements:
+
-- `spender` cannot be the zero address.
-- `deadline` must be a timestamp in the future.
-- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
-over the EIP712-formatted function arguments.
-- the signature must use ``owner``'s current nonce (see [`ERC20Permit.nonces`](#ERC20Permit-nonces-address-)).
+
-For more information on the signature format, see the
-[relevant EIP
-section](https://eips.ethereum.org/EIPS/eip-2612#specification).
+Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal
+scenario where all the conditions are met.
+
+- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT show any variations depending on the caller.
+- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
+- MUST NOT revert.
-CAUTION: See Security Considerations above.
+
+This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
+“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
+from.
+
-Returns the current nonce for `owner`. This value must be
-included whenever a signature is generated for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-).
+Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver,
+through a deposit call.
-Every successful call to [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) increases ``owner``'s nonce by one. This
-prevents a signature from being used multiple times.
+- MUST return a limited value if receiver is subject to some deposit limit.
+- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited.
+- MUST NOT revert.
-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 maximum amount of the Vault shares that can be minted for the receiver, through a mint call.
+- MUST return a limited value if receiver is subject to some mint limit.
+- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted.
+- MUST NOT revert.
-Permit deadline has expired.
+Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the
+Vault, through a withdraw call.
+
+- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
+- MUST NOT revert.
-Mismatched signature.
+Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault,
+through a redeem call.
+
+- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
+- MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock.
+- MUST NOT revert.
-```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol";
-```
+Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given
+current on-chain conditions.
-Extension of ERC-20 to support Compound-like voting and delegation. This version is more generic than Compound's,
-and supports token supply up to 2^208^ - 1, while COMP is limited to 2^96^ - 1.
+- MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit
+ call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called
+ in the same transaction.
+- MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the
+ deposit would be accepted, regardless if the user has enough tokens approved, etc.
+- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
+- MUST NOT revert.
-This contract does not provide interface compatibility with Compound's COMP token.
+any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by depositing.
-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 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.
+
-
+
+Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given
+current on-chain conditions.
+
+- MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call
+ in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the
+ same transaction.
+- MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint
+ would be accepted, regardless if the user has enough tokens approved, etc.
+- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
+- MUST NOT revert.
+
+
+any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by minting.
+
-
-
+Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block,
+given current on-chain conditions.
+
+- MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw
+ call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if
+ called
+ in the same transaction.
+- MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though
+ the withdrawal would be accepted, regardless if the user has enough shares, etc.
+- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
+- MUST NOT revert.
+
+
+any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by depositing.
+
+
+
-Maximum token supply. Defaults to `type(uint208).max` (2^208^ - 1).
+Allows an on-chain or off-chain user to simulate the effects of their redemption at the current block,
+given current on-chain conditions.
-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
-additional logic requires it. When resolving override conflicts on this function, the minimum should be
-returned.
+- MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call
+ in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the
+ same transaction.
+- MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the
+ redemption would be accepted, regardless if the user has enough shares, etc.
+- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
+- MUST NOT revert.
+
+
+any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by redeeming.
+
-Move voting power when tokens are transferred.
+Deposit `assets` underlying tokens and send the corresponding number of vault shares (`shares`) to `receiver`.
-Emits a [`IVotes.DelegateVotesChanged`](../governance#IVotes-DelegateVotesChanged-address-uint256-uint256-) event.
+- MUST emit the Deposit event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ deposit execution, and are accounted for during deposit.
+- MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not
+ approving enough underlying tokens to the Vault contract, etc).
+
+
+most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
+
-Returns the voting units of an `account`.
+Mints exactly `shares` vault shares to `receiver` in exchange for `assets` underlying tokens.
-
-Overriding this function may compromise the internal vote accounting.
-`ERC20Votes` assumes tokens map to voting units 1:1 and this is not easy to change.
+- MUST emit the Deposit event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint
+ execution, and are accounted for during mint.
+- MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not
+ approving enough underlying tokens to the Vault contract, etc).
+
+
+most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
-Get number of checkpoints for `account`.
+Burns shares from owner and sends exactly assets of underlying tokens to receiver.
+
+- MUST emit the Withdraw event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ withdraw execution, and are accounted for during withdraw.
+- MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner
+ not having enough shares, etc).
+
+Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
+Those methods should be performed separately.
-Get the `pos`-th checkpoint for `account`.
+Burns exactly shares from owner and sends assets of underlying tokens to receiver.
+
+- MUST emit the Withdraw event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ redeem execution, and are accounted for during redeem.
+- MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner
+ not having enough shares, etc).
+
+
+some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
+Those methods should be performed separately.
+
-Total supply cap has been exceeded, introducing a risk of votes overflowing.
+Internal conversion function (from assets to shares) with support for rounding direction.
+
+
-```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Wrapper.sol";
-```
-
-Extension of the ERC-20 token contract to support token wrapping.
-
-Users can deposit and withdraw "underlying tokens" and receive a matching number of "wrapped tokens". This is useful
-in conjunction with other modules. For example, combining this wrapping mechanism with [`ERC20Votes`](#ERC20Votes) will allow the
-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
-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.
-
+Deposit/mint common workflow.
-
+Performs a transfer in of underlying assets. The default implementation uses `SafeERC20`. Used by [`ERC4626._deposit`](#ERC4626-_deposit-address-address-uint256-uint256-).
+
+Performs a transfer out of underlying assets. The default implementation uses `SafeERC20`. Used by [`ERC4626._withdraw`](#ERC4626-_withdraw-address-address-address-uint256-uint256-).
+
-Allow a user to deposit underlying tokens and mint the corresponding number of wrapped tokens.
+Attempted to deposit more assets than the max amount for `receiver`.
-Allow a user to burn a number of wrapped tokens and withdraw the corresponding number of underlying tokens.
+Attempted to mint more shares than the max amount for `receiver`.
-Mint wrapped token to cover any underlyingTokens that would have been transferred by mistake or acquired from
-rebasing mechanisms. Internal function that can be exposed with access control if desired.
+Attempted to withdraw more assets than the max amount for `owner`.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
```
-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
-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
-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
-similarly be affected by slippage. Users can protect against this attack as well as unexpected slippage in general by
-verifying the amount received is as expected, using a wrapper that performs these checks such as
-[ERC4626Router](https://github.com/fei-protocol/ERC4626#erc4626router-and-base).
-
-Since v4.9, this implementation introduces configurable virtual assets and shares to help developers mitigate that risk.
-The `_decimalsOffset()` corresponds to an offset in the decimal representation between the underlying asset's decimals
-and the vault decimals. This offset also determines the rate of virtual shares to virtual assets in the vault, which
-itself determines the initial exchange rate. While not fully preventing the attack, analysis shows that the default
-offset (0) makes it non-profitable even if an attacker is able to capture value from multiple user deposits, as a result
-of the value being captured by the virtual shares (out of the attacker's donation) matching the attacker's expected gains.
-With a larger offset, the attack becomes orders of magnitude more expensive than it is profitable. More details about the
-underlying math can be found [here](/contracts/5.x/erc4626#inflation-attack).
-
-The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued
-to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets
-will cause the first user to exit to experience reduced losses in detriment to the last users that will experience
-bigger losses. Developers willing to revert back to the pre-v4.9 behavior just need to override the
-`_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:
-
-* 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.
-
-* 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
-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
-always return successfully.
-
+Interface for the optional metadata functions from the ERC-20 standard.
-Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This
-"original" value is cached during construction of the vault contract. If this read operation fails (e.g., the
-asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals.
-
-See [`IERC20Metadata.decimals`](#IERC20Metadata-decimals--).
+Returns the symbol of the token.
-Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.
-
-- MUST be an ERC-20 token contract.
-- MUST NOT revert.
+Returns the decimals places of the token.
-Returns the total amount of the underlying asset that is “managed” by Vault.
+```solidity
+import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Permit.sol";
+```
-- SHOULD include any compounding that occurs from yield.
-- MUST be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT revert.
+Interface of the ERC-20 Permit extension allowing approvals to be made via signatures, as defined in
+[ERC-2612](https://eips.ethereum.org/EIPS/eip-2612).
+
+Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) method, which can be used to change an account's ERC-20 allowance (see [`IERC20.allowance`](#IERC20-allowance-address-address-)) by
+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
+
+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
+considered as an intention to spend the allowance in any specific way. The second is that because permits have
+built-in replay protection and can be submitted by anyone, they can be frontrun. A protocol that uses permits should
+take this into consideration and allow a `permit` call to fail. Combining these two aspects, a pattern that may be
+generally recommended is:
+
+```solidity
+function doThingWithPermit(..., uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public {
+ try token.permit(msg.sender, address(this), value, deadline, v, r, s) {} catch {}
+ doThing(..., value);
+}
+
+function doThing(..., uint256 value) public {
+ token.safeTransferFrom(msg.sender, address(this), value);
+ ...
+}
+```
+Observe that: 1) `msg.sender` is used as the owner, leaving no ambiguity as to the signer intent, and 2) the use of
+`try/catch` allows the permit to fail and makes the code tolerant to frontrunning. (See also
+[`SafeERC20.safeTransferFrom`](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-)).
+
+Additionally, note that smart contract wallets (such as Argent or Safe) are not able to produce permit signatures, so
+contracts should have entry points that don't rely on permit.
+
+
-Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal
-scenario where all the conditions are met.
+Sets `value` as the allowance of `spender` over ``owner``'s tokens,
+given ``owner``'s signed approval.
-- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT show any variations depending on the caller.
-- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
-- MUST NOT revert.
+
+The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related to transaction
+ordering also applies here.
+
-
-This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
-“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
-from.
+Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
+
+Requirements:
+
+- `spender` cannot be the zero address.
+- `deadline` must be a timestamp in the future.
+- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
+over the EIP712-formatted function arguments.
+- the signature must use ``owner``'s current nonce (see [`ERC20Permit.nonces`](#ERC20Permit-nonces-address-)).
+
+For more information on the signature format, see the
+[relevant EIP
+section](https://eips.ethereum.org/EIPS/eip-2612#specification).
+
+
+See Security Considerations above.
-Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal
-scenario where all the conditions are met.
-
-- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT show any variations depending on the caller.
-- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
-- MUST NOT revert.
+Returns the current nonce for `owner`. This value must be
+included whenever a signature is generated for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-).
-
-This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
-“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
-from.
-
+Every successful call to [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) increases ``owner``'s nonce by one. This
+prevents a signature from being used multiple times.
-Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver,
-through a deposit call.
-
-- MUST return a limited value if receiver is subject to some deposit limit.
-- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited.
-- MUST NOT revert.
+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).
+
+```solidity
+import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20TemporaryApproval.sol";
+```
+
+Extension of [`ERC20`](#ERC20) that adds support for temporary allowances following ERC-7674.
+
+
+This is a draft contract. The corresponding ERC is still subject to changes.
+
+
+_Available since v5.1._
+
+
-Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call.
-- MUST return a limited value if receiver is subject to some mint limit.
-- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted.
-- MUST NOT revert.
+
-Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the
-Vault, through a withdraw call.
-
-- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
-- MUST NOT revert.
+[`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.
-Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault,
-through a redeem call.
-
-- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
-- MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock.
-- MUST NOT revert.
+Internal getter for the current temporary allowance that `spender` has over `owner` tokens.
-Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given
-current on-chain conditions.
+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.
-- MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit
- call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called
- in the same transaction.
-- MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the
- deposit would be accepted, regardless if the user has enough tokens approved, etc.
-- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
-- MUST NOT revert.
+Returns a boolean value indicating whether the operation succeeded.
-
-any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by depositing.
-
+Requirements:
+- `spender` cannot be the zero address.
+
+Does NOT emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
-Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given
-current on-chain conditions.
+Sets `value` as the temporary allowance of `spender` over the `owner`'s tokens.
-- MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call
- in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the
- same transaction.
-- MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint
- would be accepted, regardless if the user has enough tokens approved, etc.
-- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
-- MUST NOT revert.
+This internal function is equivalent to `temporaryApprove`, and can be used to e.g. set automatic allowances
+for certain subsystems, etc.
-
-any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by minting.
-
+Requirements:
+- `owner` cannot be the zero address.
+- `spender` cannot be the zero address.
+
+Does NOT emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
-Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block,
-given current on-chain conditions.
-
-- MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw
- call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if
- called
- in the same transaction.
-- MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though
- the withdrawal would be accepted, regardless if the user has enough shares, etc.
-- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
-- MUST NOT revert.
-
+[`ERC20._spendAllowance`](#ERC20-_spendAllowance-address-address-uint256-) override that consumes the temporary allowance (if any) before eventually falling back
+to consuming the persistent allowance.
-any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by depositing.
+This function skips calling `super._spendAllowance` if the temporary allowance
+is enough to cover the spending.
+
-Allows an on-chain or off-chain user to simulate the effects of their redemption at the current block,
-given current on-chain conditions.
+
-- MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call
- in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the
- same transaction.
-- MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the
- redemption would be accepted, regardless if the user has enough shares, etc.
-- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
-- MUST NOT revert.
+## `SafeERC20`
-
-any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by redeeming.
-
+
+
+
-
-#
+Wrappers around ERC-20 operations that throw on failure (when the token
+contract returns false). Tokens that return no value (and instead revert or
+throw on failure) are also supported, non-reverting calls are assumed to be
+successful.
+To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract,
+which allows you to call the safe operations as `token.safeTransfer(...)`, etc.
+
+
+
Functions
+
+- [safeTransfer(token, to, value)](#SafeERC20-safeTransfer-contract-IERC20-address-uint256-)
+- [safeTransferFrom(token, from, to, value)](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-)
+- [trySafeTransfer(token, to, value)](#SafeERC20-trySafeTransfer-contract-IERC20-address-uint256-)
+- [trySafeTransferFrom(token, from, to, value)](#SafeERC20-trySafeTransferFrom-contract-IERC20-address-address-uint256-)
+- [safeIncreaseAllowance(token, spender, value)](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-)
+- [safeDecreaseAllowance(token, spender, requestedDecrease)](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-)
+- [forceApprove(token, spender, value)](#SafeERC20-forceApprove-contract-IERC20-address-uint256-)
+- [transferAndCallRelaxed(token, to, value, data)](#SafeERC20-transferAndCallRelaxed-contract-IERC1363-address-uint256-bytes-)
+- [transferFromAndCallRelaxed(token, from, to, value, data)](#SafeERC20-transferFromAndCallRelaxed-contract-IERC1363-address-address-uint256-bytes-)
+- [approveAndCallRelaxed(token, to, value, data)](#SafeERC20-approveAndCallRelaxed-contract-IERC1363-address-uint256-bytes-)
-
-
-Deposit `assets` underlying tokens and send the corresponding number of vault shares (`shares`) to `receiver`.
-
-- MUST emit the Deposit event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- deposit execution, and are accounted for during deposit.
-- MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not
- approving enough underlying tokens to the Vault contract, etc).
-
-
-most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
-
+
-Mints exactly `shares` vault shares to `receiver` in exchange for `assets` underlying tokens.
-
-- MUST emit the Deposit event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint
- execution, and are accounted for during mint.
-- MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not
- approving enough underlying tokens to the Vault contract, etc).
-
-
-most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
-
+Transfer `value` amount of `token` from the calling contract to `to`. If `token` returns no value,
+non-reverting calls are assumed to be successful.
-Burns shares from owner and sends exactly assets of underlying tokens to receiver.
-
-- MUST emit the Withdraw event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- withdraw execution, and are accounted for during withdraw.
-- MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner
- not having enough shares, etc).
-
-Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
-Those methods should be performed separately.
+Transfer `value` amount of `token` from `from` to `to`, spending the approval given by `from` to the
+calling contract. If `token` returns no value, non-reverting calls are assumed to be successful.
-Burns exactly shares from owner and sends assets of underlying tokens to receiver.
-
-- MUST emit the Withdraw event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- redeem execution, and are accounted for during redeem.
-- MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner
- not having enough shares, etc).
-
-
-some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
-Those methods should be performed separately.
-
+Variant of [`SafeERC20.safeTransfer`](#SafeERC20-safeTransfer-contract-IERC20-address-uint256-) that returns a bool instead of reverting if the operation is not successful.
-Internal conversion function (from assets to shares) with support for rounding direction.
+Variant of [`SafeERC20.safeTransferFrom`](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-) that returns a bool instead of reverting if the operation is not successful.
-Internal conversion function (from shares to assets) with support for rounding direction.
+Increase the calling contract's allowance toward `spender` by `value`. If `token` returns no value,
+non-reverting calls are assumed to be successful.
+
+
+If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
+smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
+this function. Performing a [`SafeERC20.safeIncreaseAllowance`](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-) or [`SafeERC20.safeDecreaseAllowance`](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-) operation on a token contract
+that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
+
-Deposit/mint common workflow.
+Decrease the calling contract's allowance toward `spender` by `requestedDecrease`. If `token` returns no
+value, non-reverting calls are assumed to be successful.
+
+
+If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
+smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
+this function. Performing a [`SafeERC20.safeIncreaseAllowance`](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-) or [`SafeERC20.safeDecreaseAllowance`](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-) operation on a token contract
+that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
+
-Withdraw/redeem common workflow.
+Set the calling contract's allowance toward `spender` to `value`. If `token` returns no value,
+non-reverting calls are assumed to be successful. Meant to be used with tokens that require the approval
+to be set to zero before setting it to a non-zero value, such as USDT.
+
+
+If the token implements ERC-7674, this function will not modify any temporary allowance. This function
+only sets the "standard" allowance. Any temporary allowance will remain active, in addition to the value being
+set here.
+
-
+
-
_decimalsOffset() → uint8
+
transferAndCallRelaxed(contract IERC1363 token, address to, uint256 value, bytes data)
+Performs an [`ERC1363`](#ERC1363) transferAndCall, with a fallback to the simple [`ERC20`](#ERC20) transfer if the target has no
+code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that relies on [`ERC1363`](#ERC1363) checks when
+targeting contracts.
+
+Reverts if the returned value is other than `true`.
+
-Attempted to deposit more assets than the max amount for `receiver`.
+Performs an [`ERC1363`](#ERC1363) transferFromAndCall, with a fallback to the simple [`ERC20`](#ERC20) transferFrom if the target
+has no code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that relies on [`ERC1363`](#ERC1363) checks when
+targeting contracts.
+
+Reverts if the returned value is other than `true`.
-Attempted to mint more shares than the max amount for `receiver`.
+Performs an [`ERC1363`](#ERC1363) approveAndCall, with a fallback to the simple [`ERC20`](#ERC20) approve if the target has no
+code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that rely on [`ERC1363`](#ERC1363) checks when
+targeting contracts.
+
+
+When the recipient address (`to`) has no code (i.e. is an EOA), this function behaves as [`SafeERC20.forceApprove`](#SafeERC20-forceApprove-contract-IERC20-address-uint256-).
+Oppositely, when the recipient address (`to`) has code, this function only attempts to call [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-)
+once without retrying, and relies on the returned value to be true.
+
+
+Reverts if the returned value is other than `true`.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC1363.sol";
```
-Interface for the optional metadata functions from the ERC-20 standard.
+Extension of [`ERC20`](#ERC20) tokens that adds support for code execution after transfers and approvals
+on recipient contracts. Calls after transfers are enabled through the [`ERC1363.transferAndCall`](#ERC1363-transferAndCall-address-uint256-bytes-) and
+[`ERC1363.transferFromAndCall`](#ERC1363-transferFromAndCall-address-address-uint256-bytes-) methods while calls after approvals can be made with [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-)
+
+_Available since v5.1._
+
+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.
+
+
+
+Moves a `value` amount of tokens from the caller's account to `to`
+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`](/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`).
+
+
+
+
+
-
name() → string
+
transferAndCall(address to, uint256 value, bytes data) → bool
-Returns the name of the token.
+Variant of [`ERC1363.transferAndCall`](#ERC1363-transferAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with
+no specified format.
-
+
-
symbol() → string
+
transferFromAndCall(address from, address to, uint256 value) → bool
-Returns the symbol of the token.
+Moves a `value` amount of tokens from `from` to `to` using the allowance mechanism
+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`](/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`).
-
+
-
decimals() → uint8
+
transferFromAndCall(address from, address to, uint256 value, bytes data) → bool
-Returns the decimals places of the token.
+Variant of [`ERC1363.transferFromAndCall`](#ERC1363-transferFromAndCall-address-address-uint256-bytes-) that accepts an additional `data` parameter with
+no specified format.
-```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Permit.sol";
-```
-
-Interface of the ERC-20 Permit extension allowing approvals to be made via signatures, as defined in
-[ERC-2612](https://eips.ethereum.org/EIPS/eip-2612).
-
-Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) method, which can be used to change an account's ERC-20 allowance (see [`IERC20.allowance`](#IERC20-allowance-address-address-)) by
-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
-
-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
-considered as an intention to spend the allowance in any specific way. The second is that because permits have
-built-in replay protection and can be submitted by anyone, they can be frontrun. A protocol that uses permits should
-take this into consideration and allow a `permit` call to fail. Combining these two aspects, a pattern that may be
-generally recommended is:
-
-```solidity
-function doThingWithPermit(..., uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public {
- try token.permit(msg.sender, address(this), value, deadline, v, r, s) {} catch {}
- doThing(..., value);
-}
-
-function doThing(..., uint256 value) public {
- token.safeTransferFrom(msg.sender, address(this), value);
- ...
-}
-```
+Sets a `value` amount of tokens as the allowance of `spender` over the
+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.
-Observe that: 1) `msg.sender` is used as the owner, leaving no ambiguity as to the signer intent, and 2) the use of
-`try/catch` allows the permit to fail and makes the code tolerant to frontrunning. (See also
-[`SafeERC20.safeTransferFrom`](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-)).
+Requirements:
-Additionally, note that smart contract wallets (such as Argent or Safe) are not able to produce permit signatures, so
-contracts should have entry points that don't rely on permit.
+- The target has code (i.e. is a contract).
+- 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`).
-
-Sets `value` as the allowance of `spender` over ``owner``'s tokens,
-given ``owner``'s signed approval.
-
-
-The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related to transaction
-ordering also applies here.
-
-
-Emits an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event.
+Variant of [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with
+no specified format.
-Requirements:
+
+
-- `spender` cannot be the zero address.
-- `deadline` must be a timestamp in the future.
-- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
-over the EIP712-formatted function arguments.
-- the signature must use ``owner``'s current nonce (see [`ERC20Permit.nonces`](#ERC20Permit-nonces-address-)).
+
-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.
+Indicates a failure within the [`ERC20.transfer`](#ERC20-transfer-address-uint256-) part of a transferAndCall operation.
-Returns the current nonce for `owner`. This value must be
-included whenever a signature is generated for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-).
-
-Every successful call to [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) increases ``owner``'s nonce by one. This
-prevents a signature from being used multiple times.
+Indicates a failure within the [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-) part of a transferFromAndCall operation.
-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).
+Indicates a failure within the [`ERC20.approve`](#ERC20-approve-address-uint256-) part of a approveAndCall operation.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
```
-ERC20 extension that implements the standard token interface according to
-[ERC-7802](https://eips.ethereum.org/EIPS/eip-7802).
-
-
+Extension of [`ERC20`](#ERC20) that allows token holders to destroy both their own
+tokens and those that they have an allowance for, in a way that can be
+recognized off-chain (via event analysis).
Functions
-- [supportsInterface(interfaceId)](#ERC20Bridgeable-supportsInterface-bytes4-)
-- [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]
+- [burn(value)](#ERC20Burnable-burn-uint256-)
+- [burnFrom(account, value)](#ERC20Burnable-burnFrom-address-uint256-)
#### ERC20 [!toc]
- [name()](#ERC20-name--)
- [symbol()](#ERC20-symbol--)
@@ -3461,11 +3742,6 @@ ERC20 extension that implements the standard token interface according to
Events
-#### IERC7802 [!toc]
-- [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]
@@ -3478,9 +3754,6 @@ ERC20 extension that implements the standard token interface according to
Errors
-#### IERC7802 [!toc]
-#### ERC165 [!toc]
-#### IERC165 [!toc]
#### ERC20 [!toc]
#### IERC20Errors [!toc]
- [ERC20InsufficientBalance(sender, balance, needed)](#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-)
@@ -3494,133 +3767,74 @@ ERC20 extension that implements the standard token interface according to
-
-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.
-
-
+Destroys a `value` amount of tokens from the caller.
-See [`IERC7802.crosschainBurn`](../interfaces#IERC7802-crosschainBurn-address-uint256-). Emits a [`IERC7802.CrosschainBurn`](../interfaces#IERC7802-CrosschainBurn-address-uint256-address-) event.
+See [`ERC20._burn`](#ERC20-_burn-address-uint256-).
-Checks if the caller is a trusted token bridge. MUST revert otherwise.
+Destroys a `value` amount of tokens from `account`, deducting from
+the caller's allowance.
-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).
+See [`ERC20._burn`](#ERC20-_burn-address-uint256-) and [`ERC20.allowance`](#ERC20-allowance-address-address-).
+
+Requirements:
+
+- the caller must have allowance for ``accounts``'s tokens of at least
+`value`.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20TemporaryApproval.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol";
```
-Extension of [`ERC20`](#ERC20) that adds support for temporary allowances following ERC-7674.
-
-
-This is a draft contract. The corresponding ERC is still subject to changes.
-
-
-_Available since v5.1._
+Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens.
-[`IERC6909.allowance`](../interfaces#IERC6909-allowance-address-address-uint256-) 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.
+Sets the value of the `cap`. This value is immutable, it can only be
+set once during construction.
-Alternative to [`IERC6909.approve`](../interfaces#IERC6909-approve-address-uint256-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.
-
-Requirements:
-- `spender` cannot be the zero address.
+Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from`
+(or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding
+this function.
-Does NOT emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-address-uint256-uint256-) event.
+Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event.
-Sets `value` as the temporary allowance of `spender` over the `owner`'s tokens.
-
-This internal function is equivalent to `temporaryApprove`, and can be used to e.g. set automatic allowances
-for certain subsystems, etc.
-
-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.
+Total supply cap has been exceeded.
-[`ERC20._spendAllowance`](#ERC20-_spendAllowance-address-address-uint256-) override that consumes the temporary allowance (if any) before eventually falling back
-to consuming the persistent allowance.
-
-This function skips calling `super._spendAllowance` if the temporary allowance
-is enough to cover the spending.
-
+The supplied cap is not a valid cap.
```solidity
-import "@openzeppelin/contracts/token/ERC20/utils/ERC1363Utils.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
```
-Library that provides common ERC-1363 utility functions.
+ERC-20 token with pausable token transfers, minting and burning.
-See [ERC-1363](https://eips.ethereum.org/EIPS/eip-1363).
+Useful for scenarios such as preventing trades until the end of an evaluation
+period, or having an emergency switch for freezing all token transfers in the
+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`](/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.
+
-
-Performs a call to [`IERC1363Receiver.onTransferReceived`](../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.
+
-Performs a call to [`IERC1363Spender.onApprovalReceived`](../interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) on a target address.
+See [`ERC20._update`](#ERC20-_update-address-address-uint256-).
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.
-
-
```solidity
-import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol";
```
-Wrappers around ERC-20 operations that throw on failure (when the token
-contract returns false). Tokens that return no value (and instead revert or
-throw on failure) are also supported, non-reverting calls are assumed to be
-successful.
-To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract,
-which allows you to call the safe operations as `token.safeTransfer(...)`, etc.
-
+ERC20 extension that implements the standard token interface according to
+[ERC-7802](https://eips.ethereum.org/EIPS/eip-7802).
+
-
Functions
+
Modifiers
-- [safeTransfer(token, to, value)](#SafeERC20-safeTransfer-contract-IERC20-address-uint256-)
-- [safeTransferFrom(token, from, to, value)](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-)
-- [trySafeTransfer(token, to, value)](#SafeERC20-trySafeTransfer-contract-IERC20-address-uint256-)
-- [trySafeTransferFrom(token, from, to, value)](#SafeERC20-trySafeTransferFrom-contract-IERC20-address-address-uint256-)
-- [safeIncreaseAllowance(token, spender, value)](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-)
-- [safeDecreaseAllowance(token, spender, requestedDecrease)](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-)
-- [forceApprove(token, spender, value)](#SafeERC20-forceApprove-contract-IERC20-address-uint256-)
-- [transferAndCallRelaxed(token, to, value, data)](#SafeERC20-transferAndCallRelaxed-contract-IERC1363-address-uint256-bytes-)
-- [transferFromAndCallRelaxed(token, from, to, value, data)](#SafeERC20-transferFromAndCallRelaxed-contract-IERC1363-address-address-uint256-bytes-)
-- [approveAndCallRelaxed(token, to, value, data)](#SafeERC20-approveAndCallRelaxed-contract-IERC1363-address-uint256-bytes-)
+- [onlyTokenBridge()](#ERC20Bridgeable-onlyTokenBridge--)
-
-Transfer `value` amount of `token` from the calling contract to `to`. If `token` returns no value,
-non-reverting calls are assumed to be successful.
+
-Transfer `value` amount of `token` from `from` to `to`, spending the approval given by `from` to the
-calling contract. If `token` returns no value, non-reverting calls are assumed to be successful.
+Modifier to restrict access to the token bridge.
-
+
-
trySafeTransfer(contract IERC20 token, address to, uint256 value) → bool
-Variant of [`SafeERC20.safeTransfer`](#SafeERC20-safeTransfer-contract-IERC20-address-uint256-) that returns a bool instead of reverting if the operation is not successful.
+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.
-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.
+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.
-Increase the calling contract's allowance toward `spender` by `value`. If `token` returns no value,
-non-reverting calls are assumed to be successful.
-
-
-If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
-smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
-this function. Performing a [`SafeERC20.safeIncreaseAllowance`](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-) or [`SafeERC20.safeDecreaseAllowance`](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-) operation on a token contract
-that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
-
+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.
-Decrease the calling contract's allowance toward `spender` by `requestedDecrease`. If `token` returns no
-value, non-reverting calls are assumed to be successful.
+Checks if the caller is a trusted token bridge. MUST revert otherwise.
-
-If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
-smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
-this function. Performing a [`SafeERC20.safeIncreaseAllowance`](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-) or [`SafeERC20.safeDecreaseAllowance`](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-) operation on a token contract
-that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
-
+Developers should implement this function using an access control mechanism that allows
+customizing the list of allowed senders. Consider using [`AccessControl`](/contracts/5.x/api/access#AccessControl) or [`AccessManaged`](/contracts/5.x/api/access#AccessManaged).
-Set the calling contract's allowance toward `spender` to `value`. If `token` returns no value,
-non-reverting calls are assumed to be successful. Meant to be used with tokens that require the approval
-to be set to zero before setting it to a non-zero value, such as USDT.
+## `ERC1363Utils`
-
-If the token implements ERC-7674, this function will not modify any temporary allowance. This function
-only sets the "standard" allowance. Any temporary allowance will remain active, in addition to the value being
-set here.
-
+
+
+
-
+Library that provides common ERC-1363 utility functions.
-Performs an [`ERC1363`](#ERC1363) transferAndCall, with a fallback to the simple [`ERC20`](#ERC20) transfer if the target has no
-code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that relies on [`ERC1363`](#ERC1363) checks when
-targeting contracts.
+See [ERC-1363](https://eips.ethereum.org/EIPS/eip-1363).
-Reverts if the returned value is other than `true`.
+
-Performs an [`ERC1363`](#ERC1363) transferFromAndCall, with a fallback to the simple [`ERC20`](#ERC20) transferFrom if the target
-has no code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that relies on [`ERC1363`](#ERC1363) checks when
-targeting contracts.
+Performs a call to [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on a target address.
-Reverts if the returned value is other than `true`.
+Requirements:
+
+- The target has code (i.e. is a contract).
+- 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.
-
+
-
approveAndCallRelaxed(contract IERC1363 token, address to, uint256 value, bytes data)
-Performs an [`ERC1363`](#ERC1363) approveAndCall, with a fallback to the simple [`ERC20`](#ERC20) approve if the target has no
-code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that rely on [`ERC1363`](#ERC1363) checks when
-targeting contracts.
+Performs a call to [`IERC1363Spender.onApprovalReceived`](/contracts/5.x/api/interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) on a target address.
-
-When the recipient address (`to`) has no code (i.e. is an EOA), this function behaves as [`SafeERC20.forceApprove`](#SafeERC20-forceApprove-contract-IERC20-address-uint256-).
-Oppositely, when the recipient address (`to`) has code, this function only attempts to call [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-)
-once without retrying, and relies on the returned value to be true.
-
+Requirements:
-Reverts if the returned value is other than `true`.
+- The target has code (i.e. is a contract).
+- 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.
-Indicates a failed `decreaseAllowance` request.
+Indicates a failure with the token `spender`. Used in approvals.
+
diff --git a/content/contracts/5.x/api/token/ERC6909.mdx b/content/contracts/5.x/api/token/ERC6909.mdx
index 5430787f..c0272555 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`
-
+
@@ -265,10 +265,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 +290,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 +314,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 +339,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 +361,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 +388,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 +415,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 +514,9 @@ Does not emit an [`IERC6909.Approval`](../interfaces#IERC6909-Approval-address-a
-## `ERC6909ContentURI`
+## `ERC6909ContentURI`
-
+
@@ -531,13 +531,13 @@ 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-)
- [balanceOf(owner, id)](#ERC6909-balanceOf-address-uint256-)
- [allowance(owner, spender, id)](#ERC6909-allowance-address-address-uint256-)
- [isOperator(owner, spender)](#ERC6909-isOperator-address-address-)
@@ -591,6 +591,28 @@ Implementation of the Content URI extension defined in ERC6909.
+
+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 +659,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 +678,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 +724,9 @@ See [`IERC1155.URI`](/contracts/5.x/api/token/ERC1155#IERC1155-URI-string-uint25
-## `ERC6909Metadata`
+## `ERC6909Metadata`
-
+
@@ -722,12 +744,12 @@ 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-)
- [balanceOf(owner, id)](#ERC6909-balanceOf-address-uint256-)
- [allowance(owner, spender, id)](#ERC6909-allowance-address-address-uint256-)
- [isOperator(owner, spender)](#ERC6909-isOperator-address-address-)
@@ -833,6 +855,28 @@ Returns the number of decimals for the token of type `id`.
+
+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 +990,9 @@ The decimals value for token of type `id` was updated to `newDecimals`.
-## `ERC6909TokenSupply`
+## `ERC6909TokenSupply`
-
+
@@ -965,10 +1009,10 @@ 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-)
- [balanceOf(owner, id)](#ERC6909-balanceOf-address-uint256-)
- [allowance(owner, spender, id)](#ERC6909-allowance-address-address-uint256-)
- [isOperator(owner, spender)](#ERC6909-isOperator-address-address-)
@@ -1036,6 +1080,28 @@ Returns the total supply of the token of type `id`.
+
+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 +1118,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..feb48797 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`
-
+
@@ -308,7 +311,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 +340,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 +379,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 +404,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 +425,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 +434,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 +461,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 +490,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 +634,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 +666,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 +690,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 +733,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 +751,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 +780,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 +791,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 +831,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 +850,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 +873,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 +902,9 @@ Overrides to ownership logic should be done to [`ERC721._ownerOf`](#ERC721-_owne
-## `IERC721`
+## `IERC721`
-
+
@@ -997,11 +1000,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 +1029,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 +1055,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 +1064,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 +1093,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 +1111,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 +1157,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 +1218,9 @@ Emitted when `owner` enables or disables (`approved`) `operator` to manage all o
-## `IERC721Receiver`
+## `IERC721Receiver`
-
+
@@ -1265,9 +1268,9 @@ The selector can be obtained in Solidity with `IERC721Receiver.onERC721Received.
-## `ERC721Consecutive`
+## `ERC721Consecutive`
-
+
@@ -1406,7 +1409,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.
@@ -1568,12 +1571,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 +1601,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 +1694,191 @@ Batch burn is not supported.
+
+```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),
+
+
+
+Crosschain variant of [`ERC721.transferFrom`](#ERC721-transferFrom-address-address-uint256-), using the allowance system from the underlying ERC-721 token.
+
+
+
+"Unlocking" tokens is achieved through minting
+
+
+
+
-## `ERC721Enumerable`
+## `ERC721Enumerable`
-
+
@@ -1706,8 +1891,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
@@ -1830,7 +2017,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 +2052,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 +2075,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 +2141,9 @@ Batch mint is not allowed.
-## `ERC721Pausable`
+## `ERC721Pausable`
-
+
@@ -1975,8 +2162,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.
@@ -2095,9 +2282,9 @@ Requirements:
-## `ERC721Royalty`
+## `ERC721Royalty`
-
+
@@ -2232,9 +2419,9 @@ voluntarily pay royalties together with sales, but note that this standard is no
-## `ERC721URIStorage`
+## `ERC721URIStorage`
-
+
@@ -2252,6 +2439,7 @@ 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-)
+- [_suffixURI(tokenId)](#ERC721URIStorage-_suffixURI-uint256-)
#### ERC721 [!toc]
- [balanceOf(owner)](#ERC721-balanceOf-address-)
- [ownerOf(tokenId)](#ERC721-ownerOf-uint256-)
@@ -2381,7 +2569,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-).
+
+
-## `ERC721Votes`
+## `ERC721Votes`
-
+
@@ -2402,7 +2607,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
@@ -2553,7 +2758,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 +2805,9 @@ See [`ERC721._increaseBalance`](#ERC721-_increaseBalance-address-uint128-). We n
-## `ERC721Wrapper`
+## `ERC721Wrapper`
-
+
@@ -2771,7 +2976,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 +3042,9 @@ The received ERC-721 token couldn't be wrapped.
-## `IERC721Enumerable`
+## `IERC721Enumerable`
-
+
@@ -2913,7 +3118,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 +3136,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 +3145,9 @@ Use along with [`IERC6909TokenSupply.totalSupply`](../interfaces#IERC6909TokenSu
-## `IERC721Metadata`
+## `IERC721Metadata`
-
+
@@ -3041,9 +3246,9 @@ Returns the Uniform Resource Identifier (URI) for `tokenId` token.
+
diff --git a/content/contracts/5.x/api/token/common.mdx b/content/contracts/5.x/api/token/common.mdx
index a1f70f22..5985aff5 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`
-
+
@@ -280,3 +280,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..00dc1578 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).
-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.
+
+
+
+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.
+
+
+
+
+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.
+
+
+
+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.
+
+
+
+
+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.
+
+
+
+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.
+
+
+
+
+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.
-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
+
+
+
+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.
+
+
+
+
+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
-## `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.
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.
-
-`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
-## `Panic`
+## `Panic`
-
+
@@ -6857,9 +7080,9 @@ the internal constants with predefined codes.
-## `Pausable`
+## `Pausable`
-
+
@@ -7122,9 +7345,9 @@ The operation failed because the contract is not paused.
-## `RLP`
+## `RLP`
-
+
@@ -7143,6 +7366,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 +7622,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 +7642,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.
-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 +7697,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 +7715,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 +7725,7 @@ Encode an array of bytes as RLP.
-
encode(struct RLP.Encoder self) → bytes result
+
encode(struct RLP.Encoder self) → bytes
internal
#
@@ -7491,7 +7750,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 +7773,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 +7799,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 +7829,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 +7853,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 +7870,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 +7887,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 +8013,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,930 +8033,702 @@ 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.
```solidity
-import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+import "@openzeppelin/contracts/utils/RelayedCall.sol";
```
-Contract module that helps prevent reentrant calls to a function.
+Library for performing external calls through dynamically deployed relay contracts that hide the original
+caller's address from the target contract. This pattern is used in ERC-4337's EntryPoint for account factory
+calls and ERC-6942 for safe factory interactions.
-Inheriting from `ReentrancyGuard` will make the [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--) modifier
-available, which can be applied to functions to make sure there are no nested
-(reentrant) calls to them.
+When privileged contracts need to make arbitrary external calls based on user input, calling the target directly
+can be risky because the target sees the privileged contract as `msg.sender` and could exploit this trust
+relationship. This library solves this by deploying minimal relay contracts that act as intermediaries, ensuring
+the target only sees the unprivileged relay address as `msg.sender`.
-Note that because there is a single `nonReentrant` guard, functions marked as
-`nonReentrant` may not call one another. This can be worked around by making
-those functions `private`, and then adding `external` `nonReentrant` entry
-points to them.
+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`.
-If EIP-1153 (transient storage) is available on the chain you're deploying at,
-consider using [`ReentrancyGuardTransient`](#ReentrancyGuardTransient) instead.
+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.
-
-If you would like to learn more about reentrancy and alternative ways
-to protect against it, check out our blog post
-[Reentrancy After Istanbul](https://blog.openzeppelin.com/reentrancy-after-istanbul/).
-
-
-
-Deprecated. This storage-based reentrancy guard will be removed and replaced
-by the [`ReentrancyGuardTransient`](#ReentrancyGuardTransient) variant in v6.0.
-
-
-@custom:stateless
-
-
-Prevents a contract from calling itself, directly or indirectly.
-Calling a `nonReentrant` function from another `nonReentrant`
-function is not supported. It is possible to prevent this from happening
-by making the `nonReentrant` function external, and making it call a
-`private` function that does the actual work.
+Relays a call to the target contract through a dynamically deployed relay contract.
-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
-status. Use it only on view functions. For payable or non-payable functions,
-use the standard [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--) modifier instead.
+Same as `relayCall-address-bytes` but with a value.
-Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
-`nonReentrant` function in the call stack.
+Same as `relayCall-address-bytes` but with a salt and a value.
```solidity
-import "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol";
+import "@openzeppelin/contracts/utils/ShortStrings.sol";
```
-Variant of [`ReentrancyGuard`](#ReentrancyGuard) that uses transient storage.
+
-
-This variant only works on networks where EIP-1153 is available.
-
+
-_Available since v5.1._
+## `ShortStrings`
-@custom:stateless
+
+
+
-
+```solidity
+import "@openzeppelin/contracts/utils/ShortStrings.sol";
+```
+
+This library provides functions to convert short memory strings
+into a `ShortString` type that can be used as an immutable variable.
+
+Strings of arbitrary length can be optimized using this library if
+they are short enough (up to 31 bytes) by packing them with their
+length (1 byte) in a single EVM word (32 bytes). Additionally, a
+fallback mechanism can be used for every other case.
+
+Usage example:
+
+```solidity
+contract Named {
+ using ShortStrings for *;
+
+ ShortString private immutable _name;
+ string private _nameFallback;
+
+ constructor(string memory contractName) {
+ _name = contractName.toShortStringWithFallback(_nameFallback);
+ }
+
+ function name() external view returns (string memory) {
+ return _name.toStringWithFallback(_nameFallback);
+ }
+}
+```
+
-Prevents a contract from calling itself, directly or indirectly.
-Calling a `nonReentrant` function from another `nonReentrant`
-function is not supported. It is possible to prevent this from happening
-by making the `nonReentrant` function external, and making it call a
-`private` function that does the actual work.
+Encode a string of at most 31 chars into a `ShortString`.
+
+This will trigger a `StringTooLong` error is the input string is too long.
-A `view` only version of [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--). Use to block view functions
-from being called, preventing reading from inconsistent contract state.
+Return the length of a `ShortString`.
-CAUTION: 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.
+
-Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
-`nonReentrant` function in the call stack.
+Decode a string that was encoded to `ShortString` or written to storage using [`ShortStrings.toShortStringWithFallback`](#ShortStrings-toShortStringWithFallback-string-string-).
+Return the length of a string that was encoded to `ShortString` or written to storage using
+[`ShortStrings.toShortStringWithFallback`](#ShortStrings-toShortStringWithFallback-string-string-).
+
+
+This will return the "byte length" of the string. This may not reflect the actual length in terms of
+actual characters as the UTF-8 encoding of a single character can span over multiple bytes.
+
+
```solidity
-import "@openzeppelin/contracts/utils/RelayedCall.sol";
+import "@openzeppelin/contracts/utils/SimulateCall.sol";
```
-Library for performing external calls through dynamically deployed relay contracts that hide the original
-caller's address from the target contract. This pattern is used in ERC-4337's EntryPoint for account factory
-calls and ERC-6942 for safe factory interactions.
-
-When privileged contracts need to make arbitrary external calls based on user input, calling the target directly
-can be risky because the target sees the privileged contract as `msg.sender` and could exploit this trust
-relationship. This library solves this by deploying minimal relay contracts that act as intermediaries, ensuring
-the target only sees the unprivileged relay address as `msg.sender`.
+Library for simulating external calls and inspecting the result of the call while reverting any state changes
+of events the call may have produced.
-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 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.
-
-Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-bytes32-) but with a value.
-
+- [simulateCall(target, data)](#SimulateCall-simulateCall-address-bytes-)
+- [simulateCall(target, value, data)](#SimulateCall-simulateCall-address-uint256-bytes-)
+- [getSimulator()](#SimulateCall-getSimulator--)
-Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-bytes32-) but with a salt.
+Simulates a call to the target contract through a dynamically deployed simulator.
-Same as [`RelayedCall.relayCall`](#RelayedCall-relayCall-address-uint256-bytes-bytes32-) but with a salt and a value.
+Same as `simulateCall-address-bytes` but with a value.
+The simulator REVERTs on success and RETURNs on failure, preserving the return data in both cases.
-Returns the relayer address for a given salt.
+* 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.
```solidity
-import "@openzeppelin/contracts/utils/ShortStrings.sol";
+import "@openzeppelin/contracts/utils/SlotDerivation.sol";
```
-This library provides functions to convert short memory strings
-into a `ShortString` type that can be used as an immutable variable.
-
-Strings of arbitrary length can be optimized using this library if
-they are short enough (up to 31 bytes) by packing them with their
-length (1 byte) in a single EVM word (32 bytes). Additionally, a
-fallback mechanism can be used for every other case.
+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.
-Usage example:
+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 Named {
- using ShortStrings for *;
+contract Example {
+ // Add the library methods
+ using StorageSlot for bytes32;
+ using SlotDerivation for *;
- ShortString private immutable _name;
- string private _nameFallback;
+ // Declare a namespace
+ string private constant _NAMESPACE = ""; // eg. OpenZeppelin.Slot
- constructor(string memory contractName) {
- _name = contractName.toShortStringWithFallback(_nameFallback);
+ function setValueInNamespace(uint256 key, address newValue) internal {
+ _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value = newValue;
}
- function name() external view returns (string memory) {
- return _name.toStringWithFallback(_nameFallback);
+ function getValueInNamespace(uint256 key) internal view returns (address) {
+ return _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value;
}
}
```
+
+Consider using this library along with [`StorageSlot`](#StorageSlot).
+
+
+
+This library provides a way to manipulate storage locations in a non-standard way. Tooling for checking
+upgrade safety will ignore the slots accessed through this library.
+
+
+_Available since v5.1._
+
-Encode a string of at most 31 chars into a `ShortString`.
-
-This will trigger a `StringTooLong` error is the input string is too long.
+Add an offset to a slot to get the n-th element of a structure or an array.
-Decode a string that was encoded to `ShortString` or written to storage using [`ShortStrings.toShortStringWithFallback`](#ShortStrings-toShortStringWithFallback-string-string-).
+Derive the location of a mapping element from the key.
-Return the length of a string that was encoded to `ShortString` or written to storage using
-[`ShortStrings.toShortStringWithFallback`](#ShortStrings-toShortStringWithFallback-string-string-).
-
-
-This will return the "byte length" of the string. This may not reflect the actual length in terms of
-actual characters as the UTF-8 encoding of a single character can span over multiple bytes.
-
+Derive the location of a mapping element from the key.
-
+
-
StringTooLong(string str)
+
deriveMapping(bytes32 slot, int256 key) → bytes32 result
-
-```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 {
- _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value = newValue;
- }
-
- function getValueInNamespace(uint256 key) internal view returns (address) {
- return _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value;
- }
-}
-```
-
-
-Consider using this library along with [`StorageSlot`](#StorageSlot).
-
-
-
-This library provides a way to manipulate storage locations in a non-standard way. Tooling for checking
-upgrade safety will ignore the slots accessed through this library.
-
-
-_Available since v5.1._
-
-
-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 +9196,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 +9217,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 +9260,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 +9282,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 +9304,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 +9347,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 +9369,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 +9390,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 +9415,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 +9432,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 +9453,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 +9471,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 +9496,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 +9560,9 @@ The string being parsed is not a properly formatted address.
-## `TransientSlot`
+## `TransientSlot`
-
+
@@ -9802,9 +9879,9 @@ Store `value` at location `slot` in transient storage.
-## `InteroperableAddress`
+## `InteroperableAddress`
-
+
@@ -9874,7 +9951,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 +9969,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 +9986,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 +10004,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 +10081,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 +10180,9 @@ Variant of [`InteroperableAddress.tryParseEvmV1`](#InteroperableAddress-tryParse
-## `ERC165`
+## `ERC165`
-
+
@@ -10107,7 +10194,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
@@ -10150,9 +10237,9 @@ This function call must use less than 30 000 gas.
-## `ERC165Checker`
+## `ERC165Checker`
-
+
@@ -10289,9 +10376,9 @@ Interface identification is specified in ERC-165.
-## `IERC165`
+## `IERC165`
-
+
@@ -10342,9 +10429,9 @@ This function call must use less than 30 000 gas.
-## `Math`
+## `Math`
-
+
@@ -11065,9 +11152,9 @@ Counts the number of leading zero bits in a uint256.
-## `SafeCast`
+## `SafeCast`
-
+
@@ -12759,7 +12846,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 +12863,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 +12897,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 +12906,9 @@ An uint value doesn't fit in an int of `bits` size.
-## `SignedMath`
+## `SignedMath`
-
+
@@ -12940,9 +13027,9 @@ Returns the absolute unsigned value of a signed value.
-## `Accumulators`
+## `Accumulators`
-
+
@@ -12960,14 +13047,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 +13178,9 @@ Flatten all the bytes entries in an Accumulator into a single buffer
-## `BitMaps`
+## `BitMaps`
-
+
@@ -13197,9 +13284,9 @@ Unsets the bit at `index`.
-## `Checkpoints`
+## `Checkpoints`
-
+
@@ -13889,9 +13976,9 @@ A value was attempted to be inserted on a past checkpoint.
-## `CircularBuffer`
+## `CircularBuffer`
-
+
@@ -13910,6 +13997,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 +14015,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 +14204,9 @@ Error emitted when trying to setup a buffer with a size of 0.
-Removes the item at the end of the queue and returns it.
+Attempts to insert an item at the end of the queue.
-Reverts with [`Panic.EMPTY_ARRAY_POP`](#Panic-EMPTY_ARRAY_POP-uint256) if the queue is empty.
+Returns `false` if the queue is full. Never reverts.
-Inserts an item at the beginning of the queue.
+Removes the item at the end of the queue and returns it.
-Reverts with [`Panic.RESOURCE_ERROR`](#Panic-RESOURCE_ERROR-uint256) if the queue is full.
+Reverts with [`Panic.EMPTY_ARRAY_POP`](#Panic-EMPTY_ARRAY_POP-uint256) if the queue is empty.
-
+
-
popFront(struct DoubleEndedQueue.Bytes32Deque deque) → bytes32 value
+
tryPopBack(struct DoubleEndedQueue.Bytes32Deque deque) → bool success, bytes32 value
-Removes the item at the beginning of the queue and returns it.
+Attempts to remove the item at the end of the queue and return it.
+
+Returns `(false, 0x00)` if the queue is empty. Never reverts.
+
+
+
+Removes the item at the beginning of the queue and returns it.
Reverts with [`Panic.EMPTY_ARRAY_POP`](#Panic-EMPTY_ARRAY_POP-uint256) if the queue is empty.
+
+
+
+
+
tryPopFront(struct DoubleEndedQueue.Bytes32Deque deque) → bool success, bytes32 value
+
+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 +14579,9 @@ Returns true if the queue is empty.
-## `EnumerableMap`
+## `EnumerableMap`
-
+
@@ -14382,15 +14624,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 +14727,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 +16621,14 @@ uncallable if the map grows to a point where copying to memory consumes too much
-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.
@@ -16424,21 +16676,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.
-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 +16741,14 @@ Requirements:
-
+
-
tryGet(struct EnumerableMap.BytesToBytesMap map, bytes key) → bool exists, bytes value
+
tryGet(struct EnumerableMap.Bytes4ToAddressMap map, bytes4 key) → bool exists, address value
-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.
-Query for a nonexistent map key.
+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.
-## `EnumerableSet`
+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.
+
+
-```solidity
-import "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
-```
+
-Library for managing
-[sets](https://en.wikipedia.org/wiki/Set_(abstract_data_type)) of primitive
-types.
+
-Sets have the following properties:
+Returns true if the key is in the map. O(1).
-- Elements are added, removed, and checked for existence in constant time
-(O(1)).
-- Elements are enumerated in O(n). No guarantees are made on the ordering.
-- Set can be cleared (all elements removed) in O(n).
+
+
-```solidity
-contract Example {
- // Add the library methods
- using EnumerableSet for EnumerableSet.AddressSet;
+
- // Declare a set state variable
- EnumerableSet.AddressSet private mySet;
-}
-```
+
-The following types are supported:
+Returns the number of key-value pairs in the map. O(1).
-- `bytes32` (`Bytes32Set`) since v3.3.0
-- `address` (`AddressSet`) since v3.3.0
-- `uint256` (`UintSet`) since v3.3.0
-- `string` (`StringSet`) since v5.4.0
-- `bytes` (`BytesSet`) since v5.4.0
+
+
-
-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.
+
+
+
at(struct EnumerableMap.BytesToBytesMap map, uint256 index) → bytes key, bytes value
+
+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
+
+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.
+
+
+
+
+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.
+
+
+```solidity
+import "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+```
+
+Library for managing
+[sets](https://en.wikipedia.org/wiki/Set_(abstract_data_type)) of primitive
+types.
+
+Sets have the following properties:
+
+- Elements are added, removed, and checked for existence in constant time
+(O(1)).
+- Elements are enumerated in O(n). No guarantees are made on the ordering.
+- Set can be cleared (all elements removed) in O(n).
+
+```solidity
+contract Example {
+ // Add the library methods
+ using EnumerableSet for EnumerableSet.AddressSet;
+
+ // Declare a set state variable
+ EnumerableSet.AddressSet private mySet;
+}
+```
+
+The following types are supported:
+
+- `bytes32` (`Bytes32Set`) since v3.3.0
+- `address` (`AddressSet`) since v3.3.0
+- `uint256` (`UintSet`) since v3.3.0
+- `string` (`StringSet`) since v5.4.0
+- `bytes` (`BytesSet`) since v5.4.0
+- `bytes4` (`Bytes4Set`) since v5.6.0
+
+[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 +17134,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,14 +17345,14 @@ uncallable if the set grows to a point where copying to memory consumes too much
+
+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.
+
+
+
+
+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.
+
+
+
+
+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.
+
+
+
+
+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-).
+
+
@@ -17554,9 +18189,9 @@ uncallable if the set grows to a point where copying to memory consumes too much
-## `Heap`
+## `Heap`
-
+
@@ -17573,9 +18208,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 +18434,9 @@ Removes all elements in the heap.
-## `MerkleTree`
+## `MerkleTree`
-
+
@@ -18066,9 +18702,9 @@ Error emitted when the proof used during an update is invalid (could not reprodu
-## `Time`
+## `Time`
-
+
@@ -18240,3 +18876,331 @@ pack the components into a Delay object.
+
+```solidity
+import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+```
+
+Contract module that helps prevent reentrant calls to a function.
+
+Inheriting from `ReentrancyGuard` will make the [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--) modifier
+available, which can be applied to functions to make sure there are no nested
+(reentrant) calls to them.
+
+Note that because there is a single `nonReentrant` guard, functions marked as
+`nonReentrant` may not call one another. This can be worked around by making
+those functions `private`, and then adding `external` `nonReentrant` entry
+points to them.
+
+
+If EIP-1153 (transient storage) is available on the chain you're deploying at,
+consider using [`ReentrancyGuardTransient`](#ReentrancyGuardTransient) instead.
+
+
+
+If you would like to learn more about reentrancy and alternative ways
+to protect against it, check out our blog post
+[Reentrancy After Istanbul](https://blog.openzeppelin.com/reentrancy-after-istanbul/).
+
+
+
+Deprecated. This storage-based reentrancy guard will be removed and replaced
+by the [`ReentrancyGuardTransient`](#ReentrancyGuardTransient) variant in v6.0.
+
+
+@custom:stateless
+
+
+
+Prevents a contract from calling itself, directly or indirectly.
+Calling a `nonReentrant` function from another `nonReentrant`
+function is not supported. It is possible to prevent this from happening
+by making the `nonReentrant` function external, and making it call a
+`private` function that does the actual work.
+
+
+
+A `view` only version of [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--). Use to block view functions
+from being called, preventing reading from inconsistent contract state.
+
+
+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.
+
+
+
+
+```solidity
+import "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol";
+```
+
+Variant of [`ReentrancyGuard`](#ReentrancyGuard) that uses transient storage.
+
+
+This variant only works on networks where EIP-1153 is available.
+
+
+_Available since v5.1._
+
+@custom:stateless
+
+
+
+Prevents a contract from calling itself, directly or indirectly.
+Calling a `nonReentrant` function from another `nonReentrant`
+function is not supported. It is possible to prevent this from happening
+by making the `nonReentrant` function external, and making it call a
+`private` function that does the actual work.
+
+
+
+A `view` only version of [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--). Use to block view functions
+from being called, preventing reading from inconsistent contract state.
+
+
+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.
+
+
+
+
diff --git a/content/contracts/5.x/api/utils/cryptography.mdx b/content/contracts/5.x/api/utils/cryptography.mdx
index 13e43174..0f812237 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`
-
+
@@ -478,7 +481,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 +600,9 @@ It only reads from storage if necessary (in case the value is too large to fit i
-## `Hashes`
+## `Hashes`
-
+
@@ -662,9 +666,9 @@ Implementation of keccak256(abi.encode(a, b)) that doesn't allocate or expand me
-## `MerkleProof`
+## `MerkleProof`
-
+
@@ -923,7 +927,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 +958,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 +990,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 +1021,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 +1053,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 +1084,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 +1116,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 +1147,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 +1183,9 @@ The multiproof provided is not valid.
@@ -1281,7 +1311,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 +1339,91 @@ See [`ECDSA.recover`](#ECDSA-recover-bytes32-uint8-bytes32-bytes32-).
+
+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.
+
+
-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 +1507,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 +1542,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 +1551,9 @@ In particular this function checks that x < P and y < P.
-## `RSA`
+## `RSA`
-
+
@@ -1530,9 +1638,9 @@ using a low exponent out of security concerns.
@@ -1582,7 +1691,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 +1737,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
@@ -1647,9 +1771,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 +1809,134 @@ change through time. It could return true at block N and false at block N+1 (or
+
+```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).
+
+
+
+Traverses a proof with a given key and returns the value.
+
+Reverts with [`TrieProof.TrieProofTraversalError`](#TrieProof-TrieProofTraversalError-enum-TrieProof-ProofError-) if proof is invalid.
+
+
+
+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.
+
+
-## `WebAuthn`
+## `WebAuthn`
-
+
@@ -1711,15 +1956,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 +2058,9 @@ cause revert/panic.
-## `ERC7739Utils`
+## `ERC7739Utils`
-
+
@@ -1825,7 +2073,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 +2086,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 +2149,6 @@ Constructed as follows:
This function returns empty if the input format is invalid instead of reverting.
-data instead.
@@ -1921,7 +2170,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 +2206,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 +2257,9 @@ length.
-## `AbstractSigner`
+## `AbstractSigner`
-
+
@@ -2022,7 +2271,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 +2298,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 +2310,9 @@ cryptographic verification. It is important to review and test thoroughly before
-## `MultiSignerERC7913`
+## `MultiSignerERC7913`
-
+
@@ -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`
-
+
@@ -2893,9 +3152,9 @@ Thrown when the arrays lengths don't match. See [`MultiSignerERC7913Weighted._se
-## `SignerECDSA`
+## `SignerECDSA`
-
+
@@ -2905,9 +3164,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:
@@ -3002,7 +3261,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 +3273,9 @@ cryptographic verification. It is important to review and test thoroughly before
-## `SignerEIP7702`
+## `SignerEIP7702`
-
+
@@ -3024,7 +3285,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
@@ -3057,9 +3318,9 @@ Validates the signature using the EOA's address (i.e. `address(this)`).
-## `SignerERC7913`
+## `SignerERC7913`
-
+
@@ -3072,7 +3333,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`.
@@ -3168,7 +3429,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 +3439,9 @@ with [`SignerECDSA.signer`](#SignerECDSA-signer--), `hash` and `signature`.
-## `SignerP256`
+## `SignerP256`
-
+
@@ -3190,9 +3451,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:
@@ -3295,7 +3556,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 +3583,9 @@ cryptographic verification. It is important to review and test thoroughly before
-## `SignerRSA`
+## `SignerRSA`
-
+
@@ -3332,9 +3595,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:
@@ -3441,9 +3704,9 @@ encoding as per section 9.2 (step 1) of the RFC.
-## `SignerWebAuthn`
+## `SignerWebAuthn`
-
+
@@ -3510,9 +3773,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 +3782,9 @@ the raw `r` and `s` values from the signature.
-## `ERC7739`
+## `ERC7739`
-
+
@@ -3538,11 +3799,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)).
@@ -3600,9 +3863,9 @@ A nested EIP-712 type might be presented in 2 different ways:
-## `ERC7913P256Verifier`
+## `ERC7913P256Verifier`
-
+
@@ -3649,9 +3912,9 @@ SHOULD return 0xffffffff or revert if the key is empty
-## `ERC7913RSAVerifier`
+## `ERC7913RSAVerifier`
-
+
@@ -3698,9 +3961,9 @@ SHOULD return 0xffffffff or revert if the key is empty
-## `ERC7913WebAuthnVerifier`
+## `ERC7913WebAuthnVerifier`
-
+
@@ -3716,7 +3979,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.
@@ -3753,3 +4016,4 @@ SHOULD return 0xffffffff or revert if the key is empty
+
From cd2d32e0870559171e1e486975395b5d589005fd Mon Sep 17 00:00:00 2001
From: stevep0z <255929980+stevep0z@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:36:27 -0500
Subject: [PATCH 03/11] feat: collapsible inherited functions in API reference
TOC sections
Wrap inherited function/event/error listings in /
toggles so the contract's own items are prominent and inherited items
are accessible but not overwhelming.
Only renders toggles for inherited contracts that have items for that
section (no empty toggles).
Also regenerates API reference output with updated template.
---
content/community-contracts/api/access.mdx | 9 +-
content/community-contracts/api/account.mdx | 378 +++--
.../community-contracts/api/crosschain.mdx | 157 +-
.../community-contracts/api/governance.mdx | 73 +-
.../community-contracts/api/interfaces.mdx | 54 +-
content/community-contracts/api/proxy.mdx | 12 +-
content/community-contracts/api/token.mdx | 350 ++--
content/community-contracts/api/utils.mdx | 18 +-
.../api/utils/cryptography.mdx | 34 +-
content/contracts/5.x/api/access.mdx | 180 +-
content/contracts/5.x/api/account.mdx | 96 +-
content/contracts/5.x/api/crosschain.mdx | 375 +++--
content/contracts/5.x/api/finance.mdx | 49 +-
content/contracts/5.x/api/governance.mdx | 1469 ++++++++++-------
content/contracts/5.x/api/interfaces.mdx | 204 ++-
content/contracts/5.x/api/metatx.mdx | 29 +-
content/contracts/5.x/api/proxy.mdx | 80 +-
content/contracts/5.x/api/token/ERC1155.mdx | 290 ++--
content/contracts/5.x/api/token/ERC20.mdx | 550 +++---
content/contracts/5.x/api/token/ERC6909.mdx | 104 +-
content/contracts/5.x/api/token/ERC721.mdx | 532 +++---
content/contracts/5.x/api/token/common.mdx | 6 -
content/contracts/5.x/api/utils.mdx | 13 +-
.../contracts/5.x/api/utils/cryptography.mdx | 77 +-
docgen/templates-md/contract.hbs | 48 +-
25 files changed, 3115 insertions(+), 2072 deletions(-)
diff --git a/content/community-contracts/api/access.mdx b/content/community-contracts/api/access.mdx
index 6023bc9c..4594dfc6 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
```solidity
-import "@openzeppelin/community-contracts/contracts/access/manager/AccessManagerLight.sol";
+import "@openzeppelin/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.
diff --git a/content/community-contracts/api/account.mdx b/content/community-contracts/api/account.mdx
index ae6ac946..3d969298 100644
--- a/content/community-contracts/api/account.mdx
+++ b/content/community-contracts/api/account.mdx
@@ -60,16 +60,16 @@ This directory includes contracts to build accounts for ERC-4337. These include:
```solidity
-import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579MultisigWeighted.sol";
+import "@openzeppelin/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
```solidity
-import "@openzeppelin/community-contracts/contracts/account/paymaster/PaymasterCore.sol";
+import "@openzeppelin/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
diff --git a/content/community-contracts/api/crosschain.mdx b/content/community-contracts/api/crosschain.mdx
index 1995d1fd..9bf23c6b 100644
--- a/content/community-contracts/api/crosschain.mdx
+++ b/content/community-contracts/api/crosschain.mdx
@@ -25,16 +25,16 @@ Developers can access interoperability protocols through gateway adapters. The l
```solidity
-import "@openzeppelin/community-contracts/contracts/crosschain/ERC7786OpenBridge.sol";
+import "@openzeppelin/contracts/crosschain/ERC7786OpenBridge.sol";
```
N of M gateway: Sends your message through M independent gateways. It will be delivered to the recipient by an
@@ -62,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-)
-#### IERC7786Recipient [!toc]
-#### IERC7786GatewaySource [!toc]
+
+
@@ -90,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-)
-#### IERC7786Recipient [!toc]
-#### IERC7786GatewaySource [!toc]
+
+
+
+IERC7786GatewaySource
+
- [MessageSent(sendId, sender, recipient, payload, value, attributes)](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---)
+
+
@@ -113,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-)
-#### IERC7786Recipient [!toc]
-#### IERC7786GatewaySource [!toc]
+
+
+
+IERC7786GatewaySource
+
- [UnsupportedAttribute(selector)](#IERC7786GatewaySource-UnsupportedAttribute-bytes4-)
+
+
@@ -717,16 +745,16 @@ Recovery method in case value is ever received through [`ERC7786OpenBridge.recei
```solidity
-import "@openzeppelin/community-contracts/contracts/crosschain/utils/ERC7786Attributes.sol";
+import "@openzeppelin/contracts/crosschain/utils/ERC7786Attributes.sol";
```
Library of helper to parse/process ERC-7786 attributes
@@ -1226,16 +1277,16 @@ Parse the `requestRelay(uint256,uint256,address)` (0x4cbb573a) attribute into it
diff --git a/content/community-contracts/api/governance.mdx b/content/community-contracts/api/governance.mdx
index b0a3ff62..c8f9ab83 100644
--- a/content/community-contracts/api/governance.mdx
+++ b/content/community-contracts/api/governance.mdx
@@ -15,16 +15,16 @@ This directory includes extensions and utilities for on-chain governance.
diff --git a/content/community-contracts/api/interfaces.mdx b/content/community-contracts/api/interfaces.mdx
index 3cb609d2..e5f34825 100644
--- a/content/community-contracts/api/interfaces.mdx
+++ b/content/community-contracts/api/interfaces.mdx
@@ -20,16 +20,16 @@ These interfaces are available as `.sol` files. These are useful to interact wit
```solidity
-import "@openzeppelin/community-contracts/contracts/interfaces/IERC7786Attributes.sol";
+import "@openzeppelin/contracts/interfaces/IERC7786Attributes.sol";
```
Standard attributes for ERC-7786. These attributes may be standardized in different ERCs.
@@ -60,16 +60,16 @@ Standard attributes for ERC-7786. These attributes may be standardized in differ
@@ -309,7 +314,6 @@ import "@openzeppelin/community-contracts/contracts/interfaces/IERC7943.sol";
- [ERC7943CannotTransact(account)](#IERC7943NonFungible-ERC7943CannotTransact-address-)
- [ERC7943CannotTransfer(from, to, tokenId)](#IERC7943NonFungible-ERC7943CannotTransfer-address-address-uint256-)
- [ERC7943InsufficientUnfrozenBalance(account, tokenId)](#IERC7943NonFungible-ERC7943InsufficientUnfrozenBalance-address-uint256-)
-#### IERC165 [!toc]
@@ -478,16 +482,16 @@ This can involve checks like allowlists, blocklists, transfer limits and other p
@@ -518,7 +525,6 @@ import "@openzeppelin/community-contracts/contracts/interfaces/IERC7943.sol";
- [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-)
-#### IERC165 [!toc]
@@ -687,16 +693,16 @@ This can involve checks like allowlists, blocklists, transfer limits and other p
```solidity
-import "@openzeppelin/community-contracts/contracts/interfaces/IERC7969.sol";
+import "@openzeppelin/contracts/interfaces/IERC7969.sol";
```
This interface provides a standard way to register and validate DKIM public key hashes onchain
diff --git a/content/community-contracts/api/proxy.mdx b/content/community-contracts/api/proxy.mdx
index 1292c7fe..c0d7864b 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
```solidity
-import "@openzeppelin/community-contracts/contracts/proxy/HybridProxy.sol";
+import "@openzeppelin/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.
diff --git a/content/community-contracts/api/token.mdx b/content/community-contracts/api/token.mdx
index ab1b9292..5e4e7a87 100644
--- a/content/community-contracts/api/token.mdx
+++ b/content/community-contracts/api/token.mdx
@@ -32,16 +32,16 @@ Set of extensions and utilities for tokens (e.g ERC-20, ERC-721, ERC-1155) and d
```solidity
-import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Collateral.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Collateral.sol";
```
Extension of `ERC20` that limits the supply of tokens based
@@ -515,8 +521,9 @@ 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--)
@@ -532,22 +539,21 @@ data. This function can call external oracles or use any local storage.
- [_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]
+
+
```solidity
-import "@openzeppelin/community-contracts/contracts/token/OnTokenTransferAdapter.sol";
+import "@openzeppelin/contracts/token/OnTokenTransferAdapter.sol";
```
This contract exposes the 667 `onTokenTransfer` hook on top of `IERC1363Receiver-onTransferReceived`.
@@ -2065,8 +2115,12 @@ 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 7992481d..8993dc5e 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
```solidity
-import "@openzeppelin/community-contracts/contracts/utils/Masks.sol";
+import "@openzeppelin/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
```solidity
-import "@openzeppelin/community-contracts/contracts/utils/structs/EnumerableMapExtended.sol";
+import "@openzeppelin/contracts/utils/structs/EnumerableMapExtended.sol";
```
Library for managing an enumerable variant of Solidity's
@@ -741,16 +741,16 @@ Query for a nonexistent map key.
```solidity
-import "@openzeppelin/community-contracts/contracts/utils/structs/EnumerableSetExtended.sol";
+import "@openzeppelin/contracts/utils/structs/EnumerableSetExtended.sol";
```
Library for managing
diff --git a/content/community-contracts/api/utils/cryptography.mdx b/content/community-contracts/api/utils/cryptography.mdx
index 742b7569..30a523fa 100644
--- a/content/community-contracts/api/utils/cryptography.mdx
+++ b/content/community-contracts/api/utils/cryptography.mdx
@@ -28,16 +28,16 @@ A collection of contracts and libraries that implement various signature validat
```solidity
-import "@openzeppelin/community-contracts/contracts/utils/cryptography/ZKEmailUtils.sol";
+import "@openzeppelin/contracts/utils/cryptography/ZKEmailUtils.sol";
```
Library for [ZKEmail](https://docs.zk.email) Groth16 proof validation utilities.
@@ -327,16 +330,16 @@ into a uint256 array in the order expected by the verifier circuit.
```solidity
-import "@openzeppelin/community-contracts/contracts/utils/cryptography/verifiers/ERC7913ZKEmailVerifier.sol";
+import "@openzeppelin/contracts/utils/cryptography/verifiers/ERC7913ZKEmailVerifier.sol";
```
ERC-7913 signature verifier that supports ZKEmail accounts.
@@ -600,7 +601,6 @@ Example of overriding _decodeKey to enforce a specific verifier, registry:
@@ -2387,25 +2419,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]
@@ -1292,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]
@@ -1300,7 +1295,6 @@ Only supports single batch mode (`0x01000000000000000000`). Does not support opt
@@ -982,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--)
+
+
@@ -1118,29 +1125,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-)
+
+
@@ -1707,13 +1738,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]
+
+
@@ -1721,9 +1755,12 @@ An owner is able to change the implementation the beacon points to, thus upgradi
diff --git a/content/contracts/5.x/api/utils/cryptography.mdx b/content/contracts/5.x/api/utils/cryptography.mdx
index 0f812237..0f496a59 100644
--- a/content/contracts/5.x/api/utils/cryptography.mdx
+++ b/content/contracts/5.x/api/utils/cryptography.mdx
@@ -448,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]
@@ -2373,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]
@@ -2383,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]
@@ -2395,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]
@@ -2884,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-)
@@ -2892,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]
+
+
@@ -2900,11 +2903,14 @@ least two signers (e.g., one with weight 1 and one with weight 3). See [`MultiSi
@@ -3191,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]
@@ -3293,7 +3301,6 @@ Implementation of [`AbstractSigner`](#AbstractSigner) for implementation for an
@@ -3364,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]
@@ -3478,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]
@@ -3486,7 +3491,6 @@ or during initialization (if used as a clone) may leave the signer either front-
@@ -3622,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]
@@ -3743,19 +3746,25 @@ or during initialization (if used as a clone) may leave the signer either front-
From c14adacc73dda21d142a79920a1399ae2570bbe3 Mon Sep 17 00:00:00 2001
From: stevep0z <255929980+stevep0z@users.noreply.github.com>
Date: Thu, 2 Apr 2026 14:27:51 -0500
Subject: [PATCH 04/11] feat: add template injection to generate-api-docs.js
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The script now injects canonical MDX templates from docgen/templates-md/
into the cloned source repo before running docgen. This means source
repos don't need to have MDX templates committed — the docs monorepo
is the single source of truth.
- Copies templates-md/ and config-md.js into cloned repo
- Customizes API_DOCS_PATH, GitHub link, and import path per source repo
- Patches hardhat config to use config-md
- Overwrites config.js so prepare-docs.sh scripts still work
- Handles local paths, broken symlinks, both .js and .ts hardhat configs
- Adds --skip-template-inject flag for repos that already have MDX templates
---
scripts/generate-api-docs.js | 202 +++++++++++++++++++++++++++--------
1 file changed, 158 insertions(+), 44 deletions(-)
diff --git a/scripts/generate-api-docs.js b/scripts/generate-api-docs.js
index d7c41c62..60ea22a2 100755
--- a/scripts/generate-api-docs.js
+++ b/scripts/generate-api-docs.js
@@ -3,17 +3,23 @@
import { promises as fs } from "node:fs";
import path from "node:path";
import { execSync } 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,
};
for (let i = 0; i < args.length; i++) {
@@ -44,6 +50,9 @@ function parseArgs() {
case "-e":
options.examplesOutputDir = args[++i];
break;
+ case "--skip-template-inject":
+ options.skipTemplateInject = true;
+ break;
default:
console.error(`Unknown option: ${arg}`);
showHelp();
@@ -61,20 +70,134 @@ 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)
+ --skip-template-inject Skip injecting canonical templates (use source repo's own)
-h, --help Show this help message
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
+ node generate-api-docs.js --repo https://github.com/OpenZeppelin/openzeppelin-contracts.git --branch master
+ node generate-api-docs.js --repo /path/to/local/repo --api-output content/community-contracts/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,6 +205,7 @@ async function generateApiDocs(options) {
tempDir,
apiOutputDir,
examplesOutputDir,
+ skipTemplateInject,
} = options;
console.log("🔄 Generating OpenZeppelin Contracts API documentation...");
@@ -109,15 +233,20 @@ async function generateApiDocs(options) {
// Create output directory
await fs.mkdir(apiOutputDir, { recursive: true });
- // Clone the contracts repository
+ // Clone the contracts repository (works for both URLs and local paths)
console.log("📦 Cloning contracts repository...");
execSync(
- `git clone --depth 1 --revision "${contractsBranch}" --recurse-submodules "${contractsRepo}" "${tempDir}"`,
+ `git clone --depth 1 --branch "${contractsBranch}" --recurse-submodules "${contractsRepo}" "${tempDir}"`,
{
stdio: "inherit",
},
);
+ // Inject canonical templates if not skipped
+ if (!skipTemplateInject) {
+ await injectTemplates(tempDir, options);
+ }
+
// Navigate to contracts directory and install dependencies
console.log("📚 Installing dependencies...");
const originalDir = process.cwd();
@@ -126,11 +255,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 +272,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 +293,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 +310,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 +317,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);
From 5ac92e2c1756ec2702b756201f5776e1c160aaf4 Mon Sep 17 00:00:00 2001
From: stevep0z <255929980+stevep0z@users.noreply.github.com>
Date: Thu, 2 Apr 2026 15:08:06 -0500
Subject: [PATCH 05/11] docs: regenerate all API references using updated
script
Regenerated via generate-api-docs.js with template injection for:
- openzeppelin-contracts (master) -> content/contracts/5.x/api/
- openzeppelin-community-contracts (master) -> content/community-contracts/api/
- openzeppelin-confidential-contracts (master) -> content/confidential-contracts/api/
All repos: 0 link errors, clean build.
---
content/community-contracts/api/access.mdx | 6 +-
content/community-contracts/api/account.mdx | 142 +-
.../community-contracts/api/crosschain.mdx | 24 +-
.../community-contracts/api/governance.mdx | 10 +-
.../community-contracts/api/interfaces.mdx | 24 +-
content/community-contracts/api/proxy.mdx | 10 +-
content/community-contracts/api/token.mdx | 54 +-
content/community-contracts/api/utils.mdx | 34 +-
.../api/utils/cryptography.mdx | 32 +-
.../confidential-contracts/api/finance.mdx | 943 +++-
.../confidential-contracts/api/governance.mdx | 59 +-
.../confidential-contracts/api/interfaces.mdx | 299 +-
content/confidential-contracts/api/token.mdx | 813 ++-
content/confidential-contracts/api/utils.mdx | 742 +--
content/contracts/5.x/api/access.mdx | 328 +-
content/contracts/5.x/api/crosschain.mdx | 205 -
content/contracts/5.x/api/interfaces.mdx | 4810 ++++++++---------
content/contracts/5.x/api/proxy.mdx | 834 +--
content/contracts/5.x/api/token/ERC20.mdx | 3476 ++++++------
content/contracts/5.x/api/utils.mdx | 1636 +++---
examples/AccessManagerEnumerable.sol | 161 +
examples/ERC4626Fees.sol | 4 +-
examples/account/MyAccountEIP7702.sol | 20 +
examples/account/MyFactoryAccount.sol | 22 +-
.../crosschain/MyERC7786GatewaySource.sol | 2 +-
25 files changed, 7669 insertions(+), 7021 deletions(-)
create mode 100644 examples/AccessManagerEnumerable.sol
create mode 100644 examples/account/MyAccountEIP7702.sol
diff --git a/content/community-contracts/api/access.mdx b/content/community-contracts/api/access.mdx
index 4594dfc6..3280f887 100644
--- a/content/community-contracts/api/access.mdx
+++ b/content/community-contracts/api/access.mdx
@@ -5,7 +5,7 @@ description: "Smart contract access utilities and implementations"
This directory contains utility contracts to restrict access control in smart contracts. These include:
-- [`AccessManagerLight`](#AccessManagerLight): A simpler version of an AccessManager that uses `bytes8` roles to allow function calls identified by their 4-bytes selector.
+* [`AccessManagerLight`](#AccessManagerLight): A simpler version of an AccessManager that uses `bytes8` roles to allow function calls identified by their 4-bytes selector.
## AccessManager
@@ -17,14 +17,14 @@ This directory contains utility contracts to restrict access control in smart co
## `AccessManagerLight`
-
+
```solidity
-import "@openzeppelin/contracts/access/manager/AccessManagerLight.sol";
+import "@openzeppelin/community-contracts/contracts/access/manager/AccessManagerLight.sol";
```
Light version of an AccessManager contract that defines `bytes8` roles
diff --git a/content/community-contracts/api/account.mdx b/content/community-contracts/api/account.mdx
index 3d969298..bc1f6c66 100644
--- a/content/community-contracts/api/account.mdx
+++ b/content/community-contracts/api/account.mdx
@@ -5,20 +5,20 @@ description: "Smart contract account utilities and implementations"
This directory includes contracts to build accounts for ERC-4337. These include:
-- [`ERC7579Executor`](#ERC7579Executor): An executor module that enables executing calls from accounts where the it's installed.
-- [`ERC7579DelayedExecutor`](#ERC7579DelayedExecutor): An executor module that adds a delay before executing an account operation.
-- [`ERC7579SelectorExecutor`](#ERC7579SelectorExecutor): An executor module that restricts execution to specific function selectors.
-- [`ERC7579Validator`](#ERC7579Validator): Abstract validator module for ERC-7579 accounts that provides base implementation for signature validation.
-- [`ERC7579Signature`](#ERC7579Signature): Implementation of [`ERC7579Validator`](#ERC7579Validator) using ERC-7913 signature verification for address-less cryptographic keys and account signatures.
-- [`ERC7579Multisig`](#ERC7579Multisig): An extension of [`ERC7579Validator`](#ERC7579Validator) that enables validation using ERC-7913 signer keys.
-- [`ERC7579MultisigWeighted`](#ERC7579MultisigWeighted): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows different weights to be assigned to signers.
-- [`ERC7579MultisigConfirmation`](#ERC7579MultisigConfirmation): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that requires each signer to provide a confirmation signature.
-- [`ERC7579MultisigStorage`](#ERC7579MultisigStorage): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows storing presigned approvals in storage.
-- [`PaymasterCore`](#PaymasterCore): An ERC-4337 paymaster implementation that includes the core logic to validate and pay for user operations.
-- [`PaymasterERC20`](#PaymasterERC20): A paymaster that allows users to pay for user operations using ERC-20 tokens.
-- [`PaymasterERC20Guarantor`](#PaymasterERC20Guarantor): A paymaster that enables third parties to guarantee user operations by pre-funding gas costs, with the option for users to repay or for guarantors to absorb the cost.
-- [`PaymasterERC721Owner`](#PaymasterERC721Owner): A paymaster that allows users to pay for user operations based on ERC-721 ownership.
-- [`PaymasterSigner`](#PaymasterSigner): A paymaster that allows users to pay for user operations using an authorized signature.
+* [`ERC7579Executor`](#ERC7579Executor): An executor module that enables executing calls from accounts where the it’s installed.
+* [`ERC7579DelayedExecutor`](#ERC7579DelayedExecutor): An executor module that adds a delay before executing an account operation.
+* [`ERC7579SelectorExecutor`](#ERC7579SelectorExecutor): An executor module that restricts execution to specific function selectors.
+* [`ERC7579Validator`](#ERC7579Validator): Abstract validator module for ERC-7579 accounts that provides base implementation for signature validation.
+* [`ERC7579Signature`](#ERC7579Signature): Implementation of [`ERC7579Validator`](#ERC7579Validator) using ERC-7913 signature verification for address-less cryptographic keys and account signatures.
+* [`ERC7579Multisig`](#ERC7579Multisig): An extension of [`ERC7579Validator`](#ERC7579Validator) that enables validation using ERC-7913 signer keys.
+* [`ERC7579MultisigWeighted`](#ERC7579MultisigWeighted): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows different weights to be assigned to signers.
+* [`ERC7579MultisigConfirmation`](#ERC7579MultisigConfirmation): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that requires each signer to provide a confirmation signature.
+* [`ERC7579MultisigStorage`](#ERC7579MultisigStorage): An extension of [`ERC7579Multisig`](#ERC7579Multisig) that allows storing presigned approvals in storage.
+* [`PaymasterCore`](#PaymasterCore): An ERC-4337 paymaster implementation that includes the core logic to validate and pay for user operations.
+* [`PaymasterERC20`](#PaymasterERC20): A paymaster that allows users to pay for user operations using ERC-20 tokens.
+* [`PaymasterERC20Guarantor`](#PaymasterERC20Guarantor): A paymaster that enables third parties to guarantee user operations by pre-funding gas costs, with the option for users to repay or for guarantors to absorb the cost.
+* [`PaymasterERC721Owner`](#PaymasterERC721Owner): A paymaster that allows users to pay for user operations based on ERC-721 ownership.
+* [`PaymasterSigner`](#PaymasterSigner): A paymaster that allows users to pay for user operations using an authorized signature.
## Modules
@@ -62,14 +62,14 @@ This directory includes contracts to build accounts for ERC-4337. These include:
## `ERC7579DelayedExecutor`
-
+
```solidity
-import "@openzeppelin/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
@@ -106,8 +106,8 @@ authorization logic, such as requiring specific signers or roles.
Use [`ERC7579DelayedExecutor._scheduleAt`](#ERC7579DelayedExecutor-_scheduleAt-address-bytes32-bytes32-bytes-uint48-uint32-) to schedule operations at a specific points in time. This is
-
useful to pre-schedule operations for non-deployed accounts (e.g. subscriptions).
+
Functions
@@ -446,16 +446,16 @@ and respecting the previous delay and expiration values.
This function does not clean up scheduled operations. This means operations
-
could potentially be re-executed if the module is reinstalled later. This is a deliberate
design choice for efficiency, but module implementations may want to override this behavior
to clear scheduled operations during uninstallation for their specific use cases.
+
Calling this function directly will remove the expiration ([`ERC7579DelayedExecutor.getExpiration`](#ERC7579DelayedExecutor-getExpiration-address-)) value and
-
will schedule a reset of the delay ([`ERC7579DelayedExecutor.getDelay`](#ERC7579DelayedExecutor-getDelay-address-)) to `0` for the account. Reinstalling the
module will not immediately reset the delay if the delay reset hasn't taken effect yet.
+
@@ -476,9 +476,9 @@ Returns `data` as the execution calldata. See [`ERC7579Executor._execute`](#ERC7
This function relies on the operation state validation in [`ERC7579DelayedExecutor._execute`](#ERC7579DelayedExecutor-_execute-address-bytes32-bytes32-bytes-) for
-
authorization. Extensions of this module should override this function to implement
additional validation logic if needed.
+
@@ -801,14 +801,14 @@ The module is not installed on the account.
## `ERC7579Executor`
-
+
```solidity
-import "@openzeppelin/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
@@ -821,9 +821,9 @@ derived contracts.
This is a simplified executor that directly executes operations without delay or expiration
-
mechanisms. For a more advanced implementation with time-delayed execution patterns and
security features, see [`ERC7579DelayedExecutor`](#ERC7579DelayedExecutor).
+
Functions
@@ -915,9 +915,9 @@ Example extension:
Pack extra data in the `data` arguments (e.g. a signature) to be used in the
-
validation process. Calldata can be sliced to extract it and return only the
execution calldata.
+
@@ -967,14 +967,14 @@ Emitted when an operation is executed.
## `ERC7579Multisig`
-
+
```solidity
-import "@openzeppelin/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
@@ -1063,8 +1063,8 @@ disabled until they are added later.
An account can only call onInstall once. If called directly by the account,
-
the signer will be set to the provided data. Future installations will behave as a no-op.
+
@@ -1088,8 +1088,8 @@ See [`ERC7579DelayedExecutor.onUninstall`](#ERC7579DelayedExecutor-onUninstall-b
This function has unbounded gas costs and may become uncallable if the set grows too large.
-
See `EnumerableSet-clear`.
+
@@ -1112,9 +1112,9 @@ Using `start = 0` and `end = type(uint64).max` will return the entire set of sig
Depending on the `start` and `end`, this operation can copy a large amount of data to memory, which
-
can be expensive. This is designed for view accessors queried without gas fees. Using it in state-changing
functions may become uncallable if the slice grows too large.
+
@@ -1537,14 +1537,14 @@ The `threshold` is unreachable given the number of `signers`.
## `ERC7579MultisigConfirmation`
-
+
```solidity
-import "@openzeppelin/contracts/account/modules/ERC7579MultisigConfirmation.sol";
+import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579MultisigConfirmation.sol";
```
Extension of [`ERC7579Multisig`](#ERC7579Multisig) that requires explicit confirmation signatures
@@ -1556,8 +1556,8 @@ consent to be added. Each signer must sign an EIP-712 message to confirm their a
Use this module to ensure that all guardians in a social recovery or multisig setup have
-
explicitly agreed to their roles.
+
Functions
@@ -1728,14 +1728,14 @@ Error thrown when a confirmation signature has expired
## `ERC7579MultisigStorage`
-
+
```solidity
-import "@openzeppelin/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.
@@ -1853,8 +1853,8 @@ signed, otherwise acts as a no-op.
Does not check if the signer is authorized for the account. Valid signatures from
-
invalid signers won't be executable. See [`ERC7579Multisig._validateSignatures`](#ERC7579Multisig-_validateSignatures-address-bytes32-bytes---bytes---) for more details.
+
@@ -1903,14 +1903,14 @@ Emitted when a signer signs a hash
## `ERC7579MultisigWeighted`
-
+
```solidity
-import "@openzeppelin/contracts/account/modules/ERC7579MultisigWeighted.sol";
+import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579MultisigWeighted.sol";
```
Extension of [`ERC7579Multisig`](#ERC7579Multisig) that supports weighted signatures.
@@ -1928,9 +1928,9 @@ after the time delay has passed.
When setting a threshold value, ensure it matches the scale used for signer weights.
-
For example, if signers have weights like 1, 2, or 3, then a threshold of 4 would require
signatures with a total weight of at least 4 (e.g., one with weight 1 and one with weight 3).
+
Functions
@@ -2027,8 +2027,8 @@ If weights are not provided but signers are, all signers default to weight 1.
An account can only call onInstall once. If called directly by the account,
-
the signer will be set to the provided data. Future installations will behave as a no-op.
+
@@ -2189,10 +2189,10 @@ Override to validate threshold against total weight instead of signer count.
This function intentionally does not call `super._validateReachableThreshold` because the base implementation
-
assumes each signer has a weight of 1, which is a subset of this weighted implementation. Consider that multiple
implementations of this function may exist in the contract, so important side effects may be missed
depending on the linearization order.
+
@@ -2214,8 +2214,8 @@ Overrides the base implementation to use weights instead of count.
This function intentionally does not call `super._validateThreshold` because the base implementation
-
assumes each signer has a weight of 1, which is incompatible with this weighted implementation.
+
@@ -2237,8 +2237,8 @@ Emitted when a signer's weight is changed.
Not emitted in [`ERC7579Multisig._addSigners`](#ERC7579Multisig-_addSigners-address-bytes---) or [`ERC7579Multisig._removeSigners`](#ERC7579Multisig-_removeSigners-address-bytes---). Indexers must rely on [`ERC7579Multisig.ERC7913SignerAdded`](#ERC7579Multisig-ERC7913SignerAdded-address-bytes-)
-
and [`ERC7579Multisig.ERC7913SignerRemoved`](#ERC7579Multisig-ERC7913SignerRemoved-address-bytes-) to index a default weight of 1. See [`ERC7579MultisigWeighted.signerWeight`](#ERC7579MultisigWeighted-signerWeight-address-bytes-).
+
@@ -2283,14 +2283,14 @@ Thrown when the arrays lengths don't match.
## `ERC7579SelectorExecutor`
-
+
```solidity
-import "@openzeppelin/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
@@ -2375,8 +2375,8 @@ Returns the set of authorized selectors for the specified account.
This operation copies the entire selectors set to memory, which
-
can be expensive or may result in unbounded computation.
+
@@ -2416,8 +2416,8 @@ Clears all selectors.
This function has unbounded gas costs and may become uncallable if the set grows too large.
-
See [`EnumerableSetExtended.clear`](/community-contracts/api/utils#EnumerableSetExtended-clear-struct-EnumerableSetExtended-Bytes32x2Set-).
+
@@ -2566,14 +2566,14 @@ Error thrown when attempting to execute a non-authorized selector
## `ERC7579Signature`
-
+
```solidity
-import "@openzeppelin/contracts/account/modules/ERC7579Signature.sol";
+import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579Signature.sol";
```
Implementation of [`ERC7579Validator`](#ERC7579Validator) module using ERC-7913 signature verification.
@@ -2654,8 +2654,8 @@ See `IERC7579Module-onInstall`.
An account can only call onInstall once. If called directly by the account,
-
the signer will be set to the provided data. Future installations will behave as a no-op.
+
@@ -2676,9 +2676,9 @@ See `IERC7579Module-onUninstall`.
The signer's key will be removed if the account calls this function, potentially
-
making the account unusable. As an account operator, make sure to uninstall to a predefined path
in your account that properly handles side effects of uninstallation. See `AccountERC7579-uninstallModule`.
+
@@ -2781,14 +2781,14 @@ Thrown when the signer length is less than 20 bytes.
## `ERC7579Validator`
-
+
```solidity
-import "@openzeppelin/contracts/account/modules/ERC7579Validator.sol";
+import "@openzeppelin/community-contracts/contracts/account/modules/ERC7579Validator.sol";
```
Abstract validator module for ERC-7579 accounts.
@@ -2923,8 +2923,8 @@ Validation algorithm.
Validation is a critical security function. Implementations must carefully
-
handle cryptographic verification to prevent unauthorized access.
+
@@ -2935,14 +2935,14 @@ handle cryptographic verification to prevent unauthorized access.
## `PaymasterCore`
-
+
```solidity
-import "@openzeppelin/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
@@ -2959,8 +2959,8 @@ through the internal functions [`PaymasterCore.deposit`](#PaymasterCore-deposit-
See [Paymaster's unstaked reputation rules](https://eips.ethereum.org/EIPS/eip-7562#unstaked-paymasters-reputation-rules)
-
for more details on the paymaster's storage access limitations.
+
Modifiers
@@ -3126,8 +3126,8 @@ is returned by [`PaymasterCore.validatePaymasterUserOp`](#PaymasterCore-validate
The `actualUserOpFeePerGas` is not `tx.gasprice`. A user operation can be bundled with other transactions
-
making the gas price of the user operation to differ.
+
@@ -3281,14 +3281,14 @@ Unauthorized call to the paymaster.
## `PaymasterERC20`
-
+
```solidity
-import "@openzeppelin/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.
@@ -3402,9 +3402,9 @@ Returns a `prefundContext` that's passed to the [`PaymasterCore._postOp`](#Payma
Consider not reverting if the prefund fails when overriding this function. This is to avoid reverting
-
during the validation phase of the user operation, which may penalize the paymaster's reputation according
to ERC-7562 validation rules.
+
@@ -3427,9 +3427,9 @@ Reverts with [`PaymasterERC20.PaymasterERC20FailedRefund`](#PaymasterERC20-Payma
This function may revert after the user operation has been executed without
-
reverting the user operation itself. Consider implementing a mechanism to handle
this case gracefully.
+
@@ -3601,14 +3601,14 @@ and the `actualAmount` of `token`.
## `PaymasterERC20Guarantor`
-
+
```solidity
-import "@openzeppelin/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.
@@ -3737,8 +3737,8 @@ Otherwise, fallback to [`PaymasterERC20._refund`](#PaymasterERC20-_refund-contra
For guaranteed user operations where the user paid the `actualGasCost` back, this function
-
doesn't call `super._refund`. Consider whether there are side effects in the parent contract that need to be executed.
+
@@ -3759,8 +3759,8 @@ Fetches the guarantor address and validation data from the user operation.
Return `address(0)` to disable the guarantor feature. If supported, ensure
-
explicit consent (e.g., signature verification) to prevent unauthorized use.
+
@@ -3806,14 +3806,14 @@ Emitted when a user operation identified by `userOpHash` is guaranteed by a `gua
## `PaymasterERC721Owner`
-
+
```solidity
-import "@openzeppelin/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.
@@ -3932,8 +3932,8 @@ Returns the context to be passed to postOp and the validation data.
The default `context` is `bytes(0)`. Developers that add a context when overriding this function MUST
-
also override [`PaymasterCore._postOp`](#PaymasterCore-_postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) to process the context passed along.
+
@@ -3962,14 +3962,14 @@ Emitted when the paymaster token is set.
## `PaymasterSigner`
-
+
```solidity
-import "@openzeppelin/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`.
@@ -4083,8 +4083,8 @@ Returns the context to be passed to postOp and the validation data.
The `context` returned is `bytes(0)`. Developers overriding this function MUST
-
override [`PaymasterCore._postOp`](#PaymasterCore-_postOp-enum-IPaymaster-PostOpMode-bytes-uint256-uint256-) to process the context passed along.
+
diff --git a/content/community-contracts/api/crosschain.mdx b/content/community-contracts/api/crosschain.mdx
index 9bf23c6b..fe69d513 100644
--- a/content/community-contracts/api/crosschain.mdx
+++ b/content/community-contracts/api/crosschain.mdx
@@ -5,11 +5,11 @@ 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.
-- [`ERC7786OpenBridge`](#ERC7786OpenBridge): ERC-7786 "N out of M" gateway. Sends a message through M gateways and executes on the destination if N received it.
+* [`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:
-- [`AxelarGatewayAdapter`](#AxelarGatewayAdapter): ERC-7786 gateway adapter for Axelar.
+* [`AxelarGatewayAdapter`](#AxelarGatewayAdapter): ERC-7786 gateway adapter for Axelar.
## Gateways
@@ -27,14 +27,14 @@ Developers can access interoperability protocols through gateway adapters. The l
## `ERC7786OpenBridge`
-
+
```solidity
-import "@openzeppelin/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 recipient by an
@@ -251,9 +251,9 @@ This function emits:
interface requires this function to be payable. Even if we don't expect any value, a gateway may pass
-
some value for unknown reason. In that case we want to register this gateway having delivered the message and
not revert. Any value accrued that way can be recovered by the admin using the [`ERC7786OpenBridge.sweep`](#ERC7786OpenBridge-sweep-address-payable-) function.
+
@@ -747,14 +747,14 @@ Recovery method in case value is ever received through [`ERC7786OpenBridge.recei
## `AxelarGatewayAdapter`
-
+
```solidity
-import "@openzeppelin/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.
@@ -764,11 +764,11 @@ workflow into the standard ERC-7786.
While both ERC-7786 and Axelar do support non-evm chains, this adaptor does not. This limitation comes from
-
the translation of the ERC-7930 interoperable address (binary objects -- bytes) to strings. This is necessary
because Axelar uses string to represent addresses. For EVM network, this adapter uses a checksum hex string
representation. Other networks would require a different encoding. Ideally we would have a single encoding for all
networks (could be base58, base64, ...) but Axelar doesn't support that.
+
Functions
@@ -1237,14 +1237,14 @@ A chain equivalence has been registered.
## `ERC7786Attributes`
-
+
```solidity
-import "@openzeppelin/contracts/crosschain/utils/ERC7786Attributes.sol";
+import "@openzeppelin/community-contracts/contracts/crosschain/utils/ERC7786Attributes.sol";
```
Library of helper to parse/process ERC-7786 attributes
@@ -1279,14 +1279,14 @@ Parse the `requestRelay(uint256,uint256,address)` (0x4cbb573a) attribute into it
## `WormholeGatewayAdapter`
-
+
```solidity
-import "@openzeppelin/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.
diff --git a/content/community-contracts/api/governance.mdx b/content/community-contracts/api/governance.mdx
index c8f9ab83..8e5bbda8 100644
--- a/content/community-contracts/api/governance.mdx
+++ b/content/community-contracts/api/governance.mdx
@@ -5,7 +5,7 @@ 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.
+* [`TimelockControllerEnumerable`](#TimelockControllerEnumerable): Extension of OpenZeppelin’s TimelockController with enumerable operations support.
## Timelock
@@ -17,14 +17,14 @@ This directory includes extensions and utilities for on-chain governance.
## `TimelockControllerEnumerable`
-
+
```solidity
-import "@openzeppelin/contracts/governance/TimelockControllerEnumerable.sol";
+import "@openzeppelin/community-contracts/contracts/governance/TimelockControllerEnumerable.sol";
```
Extends the TimelockController to allow for enumerable operations
@@ -235,8 +235,8 @@ Requirements:
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.
+
@@ -324,8 +324,8 @@ Return the operation with the given id
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.
+
diff --git a/content/community-contracts/api/interfaces.mdx b/content/community-contracts/api/interfaces.mdx
index e5f34825..7e85e3d4 100644
--- a/content/community-contracts/api/interfaces.mdx
+++ b/content/community-contracts/api/interfaces.mdx
@@ -7,8 +7,8 @@ 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.
-- `IERC7913SignatureVerifier`
-- `IERC7943`
+* `IERC7913SignatureVerifier`
+* `IERC7943`
## Detailed ABI
@@ -22,14 +22,14 @@ These interfaces are available as `.sol` files. These are useful to interact wit
## `IERC7786Attributes`
-
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC7786Attributes.sol";
+import "@openzeppelin/community-contracts/contracts/interfaces/IERC7786Attributes.sol";
```
Standard attributes for ERC-7786. These attributes may be standardized in different ERCs.
@@ -62,14 +62,14 @@ Standard attributes for ERC-7786. These attributes may be standardized in differ
## `IERC7943Fungible`
-
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC7943.sol";
+import "@openzeppelin/community-contracts/contracts/interfaces/IERC7943.sol";
```
@@ -273,14 +273,14 @@ This can involve checks like allowlists, blocklists, transfer limits and other p
## `IERC7943NonFungible`
-
+
@@ -695,14 +695,14 @@ This can involve checks like allowlists, blocklists, transfer limits and other p
## `IDKIMRegistry`
-
+
```solidity
-import "@openzeppelin/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
diff --git a/content/community-contracts/api/proxy.mdx b/content/community-contracts/api/proxy.mdx
index c0d7864b..1cb68017 100644
--- a/content/community-contracts/api/proxy.mdx
+++ b/content/community-contracts/api/proxy.mdx
@@ -5,7 +5,7 @@ description: "Smart contract proxy utilities and implementations"
Variants of proxy patterns, which are contracts that allow to forward a call to an implementation contract by using `delegatecall`. This contracts include:
-- [`HybridProxy`](#HybridProxy): An ERC-1967 proxy that uses the implementation slot as a beacon in a way that a user can upgrade to an implementation of their choice.
+* [`HybridProxy`](#HybridProxy): An ERC-1967 proxy that uses the implementation slot as a beacon in a way that a user can upgrade to an implementation of their choice.
## General
@@ -17,14 +17,14 @@ Variants of proxy patterns, which are contracts that allow to forward a call to
## `HybridProxy`
-
+
```solidity
-import "@openzeppelin/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.
@@ -36,9 +36,9 @@ checks that are not compatible with this proxy design.
The fallback mechanism relies on the implementation not to define the `IBeacon-implementation` function.
-
Consider that if your implementation has this function, it'll be assumed as the beacon address, meaning that
the returned address will be used as this proxy's implementation.
+
Functions
@@ -90,9 +90,9 @@ Returns the current implementation address according to ERC-1967's implementatio
The way this function identifies whether the implementation is a beacon, is by checking
-
if it implements the `IBeacon-implementation` function. Consider that an actual implementation could
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 5e4e7a87..bb76aa70 100644
--- a/content/community-contracts/api/token.mdx
+++ b/content/community-contracts/api/token.mdx
@@ -5,12 +5,12 @@ description: "Smart contract token utilities and implementations"
Set of extensions and utilities for tokens (e.g ERC-20, ERC-721, ERC-1155) and derivated ERCs (e.g. ERC-4626, ERC-1363).
-- [`OnTokenTransferAdapter`](#OnTokenTransferAdapter): Adapter of the ERC-1363 receiver interface to comply with Chainlink's 667 interface.
-- [`ERC20Allowlist`](#ERC20Allowlist): Extension of ERC20 with transfers and approvals that require users to be registered into an allowlist.
-- [`ERC20Blocklist`](#ERC20Blocklist): Extension of ERC20 with transfers and approvals that can be disabled by adding users into a blocklist.
-- [`ERC20Collateral`](#ERC20Collateral): Oracle-agnostic extension of ERC20 that limits the total supply based on a collateral amount.
-- [`ERC20Custodian`](#ERC20Custodian): Extension of ERC20 that implements an access-control agnostic approach to define a custodian that can freeze user's transfers and approvals.
-- [`ERC4626Fees`](#ERC4626Fees): ERC4626 vault with fees on entry (deposit/mint) or exit (withdraw/redeem).
+* [`OnTokenTransferAdapter`](#OnTokenTransferAdapter): Adapter of the ERC-1363 receiver interface to comply with Chainlink’s 667 interface.
+* [`ERC20Allowlist`](#ERC20Allowlist): Extension of ERC20 with transfers and approvals that require users to be registered into an allowlist.
+* [`ERC20Blocklist`](#ERC20Blocklist): Extension of ERC20 with transfers and approvals that can be disabled by adding users into a blocklist.
+* [`ERC20Collateral`](#ERC20Collateral): Oracle-agnostic extension of ERC20 that limits the total supply based on a collateral amount.
+* [`ERC20Custodian`](#ERC20Custodian): Extension of ERC20 that implements an access-control agnostic approach to define a custodian that can freeze user’s transfers and approvals.
+* [`ERC4626Fees`](#ERC4626Fees): ERC4626 vault with fees on entry (deposit/mint) or exit (withdraw/redeem).
## General
@@ -34,14 +34,14 @@ Set of extensions and utilities for tokens (e.g ERC-20, ERC-721, ERC-1155) and d
## `ERC20Allowlist`
-
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Allowlist.sol";
+import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Allowlist.sol";
```
Extension of `ERC20` that allows to implement an allowlist
@@ -265,14 +265,14 @@ The operation failed because the user is not allowed.
## `ERC20Blocklist`
-
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Blocklist.sol";
+import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Blocklist.sol";
```
Extension of `ERC20` that allows to implement a blocklist
@@ -496,14 +496,14 @@ The operation failed because the user is blocked.
## `ERC20Collateral`
-
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Collateral.sol";
+import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Collateral.sol";
```
Extension of `ERC20` that limits the supply of tokens based
@@ -719,14 +719,14 @@ Collateral amount has expired.
## `ERC20Custodian`
-
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Custodian.sol";
+import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Custodian.sol";
```
Extension of `ERC20` that allows to implement a custodian
@@ -1017,14 +1017,14 @@ Error thrown when a non-custodian account attempts to perform a custodian-only o
## `ERC20Freezable`
-
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Freezable.sol";
+import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Freezable.sol";
```
Extension of `ERC20` that allows to implement a freezing
@@ -1192,14 +1192,14 @@ The operation failed because the account has insufficient unfrozen balance.
## `ERC20Restricted`
-
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Restricted.sol";
+import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20Restricted.sol";
```
Extension of `ERC20` that allows to implement user account transfer restrictions
@@ -1467,14 +1467,14 @@ The operation failed because the user account is restricted.
## `ERC20uRWA`
-
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20uRWA.sol";
+import "@openzeppelin/community-contracts/contracts/token/ERC20/extensions/ERC20uRWA.sol";
```
Extension of `ERC20` according to [EIP-7943](https://eips.ethereum.org/EIPS/eip-7943).
@@ -1666,8 +1666,8 @@ See [`IERC7943Fungible.canTransfer`](/community-contracts/api/interfaces#IERC794
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.
+
@@ -1705,8 +1705,8 @@ See [`IERC7943Fungible.setFrozenTokens`](/community-contracts/api/interfaces#IER
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.
+
@@ -1730,10 +1730,10 @@ to the new balance after the transfer.
This function uses [`ERC20Allowlist._update`](#ERC20Allowlist-_update-address-address-uint256-) to perform the transfer, ensuring all standard ERC20
-
side effects (such as balance updates and events) are preserved. If you override [`ERC20Allowlist._update`](#ERC20Allowlist-_update-address-address-uint256-)
to add additional restrictions or logic, those changes will also apply here.
Consider overriding this function to bypass newer restrictions if needed.
+
@@ -1811,14 +1811,14 @@ function _checkFreezer(address account, uint256 amount) internal view override o
## `ERC4626Fees`
-
+
```solidity
-import "@openzeppelin/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).
@@ -2096,14 +2096,14 @@ Send exit fee to [`ERC4626Fees._exitFeeRecipient`](#ERC4626Fees-_exitFeeRecipien
## `OnTokenTransferAdapter`
-
+
```solidity
-import "@openzeppelin/contracts/token/OnTokenTransferAdapter.sol";
+import "@openzeppelin/community-contracts/contracts/token/OnTokenTransferAdapter.sol";
```
This contract exposes the 667 `onTokenTransfer` hook on top of `IERC1363Receiver-onTransferReceived`.
diff --git a/content/community-contracts/api/utils.mdx b/content/community-contracts/api/utils.mdx
index 8993dc5e..4897ad49 100644
--- a/content/community-contracts/api/utils.mdx
+++ b/content/community-contracts/api/utils.mdx
@@ -5,8 +5,8 @@ description: "Smart contract utils utilities and implementations"
Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives.
-- [`EnumerableSetExtended`](#EnumerableSetExtended) and [`EnumerableMapExtended`](#EnumerableMapExtended): Extensions of the `EnumerableSet` and `EnumerableMap` libraries with more types, including non-value types.
-- [`Masks`](#Masks): Library to handle `bytes32` masks.
+* [`EnumerableSetExtended`](#EnumerableSetExtended) and [`EnumerableMapExtended`](#EnumerableMapExtended): Extensions of the `EnumerableSet` and `EnumerableMap` libraries with more types, including non-value types.
+* [`Masks`](#Masks): Library to handle `bytes32` masks.
## Structs
@@ -24,14 +24,14 @@ Miscellaneous contracts and libraries containing utility functions you can use t
## `Masks`
-
+
```solidity
-import "@openzeppelin/contracts/utils/Masks.sol";
+import "@openzeppelin/community-contracts/contracts/utils/Masks.sol";
```
Library for handling bit masks
@@ -210,14 +210,14 @@ Returns the symmetric difference (∆) of two masks, also known as disjunctive u
## `EnumerableMapExtended`
-
+
```solidity
-import "@openzeppelin/contracts/utils/structs/EnumerableMapExtended.sol";
+import "@openzeppelin/community-contracts/contracts/utils/structs/EnumerableMapExtended.sol";
```
Library for managing an enumerable variant of Solidity's
@@ -345,8 +345,8 @@ 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.
+
@@ -464,10 +464,10 @@ 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.
+
@@ -488,10 +488,10 @@ 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.
+
@@ -552,8 +552,8 @@ 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.
+
@@ -671,10 +671,10 @@ 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.
+
@@ -695,10 +695,10 @@ 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.
+
@@ -743,14 +743,14 @@ Query for a nonexistent map key.
## `EnumerableSetExtended`
-
+
```solidity
-import "@openzeppelin/contracts/utils/structs/EnumerableSetExtended.sol";
+import "@openzeppelin/community-contracts/contracts/utils/structs/EnumerableSetExtended.sol";
```
Library for managing
@@ -856,8 +856,8 @@ 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.
+
@@ -936,10 +936,10 @@ 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.
+
@@ -960,10 +960,10 @@ 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.
+
diff --git a/content/community-contracts/api/utils/cryptography.mdx b/content/community-contracts/api/utils/cryptography.mdx
index 30a523fa..5847fc69 100644
--- a/content/community-contracts/api/utils/cryptography.mdx
+++ b/content/community-contracts/api/utils/cryptography.mdx
@@ -5,10 +5,10 @@ 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.
-- [`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.
-- [`ERC7913ZKEmailVerifier`](#ERC7913ZKEmailVerifier): Ready to use ERC-7913 signature verifiers for ZKEmail.
+* [`ZKEmailUtils`](#ZKEmailUtils): Library for ZKEmail signature validation utilities, enabling email-based authentication through zero-knowledge proofs.
+* [`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.
+* [`ERC7913ZKEmailVerifier`](#ERC7913ZKEmailVerifier): Ready to use ERC-7913 signature verifiers for ZKEmail.
## Utils
@@ -30,14 +30,14 @@ A collection of contracts and libraries that implement various signature validat
## `DKIMRegistry`
-
+
```solidity
-import "@openzeppelin/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
@@ -128,8 +128,8 @@ Emits a [`IDKIMRegistry.KeyHashRegistered`](/community-contracts/api/interfaces#
This function does not validate that keyHash is non-zero. Consider adding
-
validation in derived contracts if needed.
+
@@ -153,8 +153,8 @@ Emits a [`IDKIMRegistry.KeyHashRegistered`](/community-contracts/api/interfaces#
This function does not validate that the keyHashes array is non-empty.
-
Consider adding validation in derived contracts if needed.
+
@@ -185,14 +185,14 @@ Emits a [`IDKIMRegistry.KeyHashRevoked`](/community-contracts/api/interfaces#IDK
## `ZKEmailUtils`
-
+
```solidity
-import "@openzeppelin/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.
@@ -300,8 +300,8 @@ returns true and the calldata view at the object. Otherwise, returns false and a
The returned `emailProof` object should not be accessed if `success` is false. Trying to access the data may
-
cause revert/panic.
+
@@ -332,14 +332,14 @@ into a uint256 array in the order expected by the verifier circuit.
## `SignerZKEmail`
-
+
```solidity
-import "@openzeppelin/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.
@@ -376,9 +376,9 @@ contract MyAccountZKEmail is Account, SignerZKEmail, Initializable {
Failing to call [`SignerZKEmail._setAccountSalt`](#SignerZKEmail-_setAccountSalt-bytes32-), [`SignerZKEmail._setDKIMRegistry`](#SignerZKEmail-_setDKIMRegistry-contract-IDKIMRegistry-), and [`SignerZKEmail._setVerifier`](#SignerZKEmail-_setVerifier-contract-IGroth16Verifier-)
-
either during construction (if used standalone) or during initialization (if used as a clone) may
leave the signer either front-runnable or unusable.
+
```solidity
-import "@openzeppelin/contracts/utils/cryptography/verifiers/ERC7913ZKEmailVerifier.sol";
+import "@openzeppelin/community-contracts/contracts/utils/cryptography/verifiers/ERC7913ZKEmailVerifier.sol";
```
ERC-7913 signature verifier that supports ZKEmail accounts.
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)
+
+
+
+
+
+```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.
+
+
+
+
+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 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.
+
+
+
+
+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.
+
+
+
+
+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`.
+
+
+
+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.
+
+
+
+
+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.
+
+
+
+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`)
+
+
+
+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.
+
+
+
+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
+
+
+
+The `batchId` does not exist. Batch IDs start at 1 and must be less than or equal to [`BatcherConfidential.currentBatchId`](#BatcherConfidential-currentBatchId--).
+
+
+
+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-).
+
+
+
+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`.
+
+
```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
```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.
```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.
```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
+
+
+
+
+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.
+
+
+
+
+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.
+
+
```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.
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
-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.
-
-
-
```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]
+
+
+
+`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.
+
+
+
+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
+
+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-).
+
+
+
-`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`.
-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.
-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)
-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.
+
+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`.
+
+
-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
@@ -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.
```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
```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
-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.
```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.
@@ -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.
@@ -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.
-
+
@@ -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:
```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.
```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
```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.
@@ -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.
```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.
-
-```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.
-
-
-
-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.
-
-
-
-
-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).
-
-
-
-
-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.
-
-
-
-
-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).
-
-
-
-
-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.
-
-
-
-
-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).
-
-
-
-
-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.
-
-
-
-
-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).
-
-
-
+
+```solidity
+import "@openzeppelin/contracts/access/Ownable2Step.sol";
+```
+
+Contract module which provides access control mechanism, where
+there is an account (an owner) that can be granted exclusive access to
+specific functions.
+
+This extension of the [`Ownable`](#Ownable) contract includes a two-step mechanism to transfer
+ownership, where the new owner must call [`Ownable2Step.acceptOwnership`](#Ownable2Step-acceptOwnership--) in order to replace the
+old one. This can help prevent common mistakes, such as transfers of ownership to
+incorrect accounts, or to contracts that are unable to interact with the
+permission system.
+
+The initial owner is specified at deployment time in the constructor for `Ownable`. This
+can later be changed with [`Ownable.transferOwnership`](#Ownable-transferOwnership-address-) and [`Ownable2Step.acceptOwnership`](#Ownable2Step-acceptOwnership--).
+
+This module is used through inheritance. It will make available all functions
+from parent (Ownable).
+
+
+
+Starts the ownership transfer of the contract to a new account. Replaces the pending transfer if there is one.
+Can only be called by the current owner.
+
+Setting `newOwner` to the zero address is allowed; this can be used to cancel an initiated ownership transfer.
+
+
-
-```solidity
-import "@openzeppelin/contracts/access/Ownable2Step.sol";
-```
-
-Contract module which provides access control mechanism, where
-there is an account (an owner) that can be granted exclusive access to
-specific functions.
-
-This extension of the [`Ownable`](#Ownable) contract includes a two-step mechanism to transfer
-ownership, where the new owner must call [`Ownable2Step.acceptOwnership`](#Ownable2Step-acceptOwnership--) in order to replace the
-old one. This can help prevent common mistakes, such as transfers of ownership to
-incorrect accounts, or to contracts that are unable to interact with the
-permission system.
-
-The initial owner is specified at deployment time in the constructor for `Ownable`. This
-can later be changed with [`Ownable.transferOwnership`](#Ownable-transferOwnership-address-) and [`Ownable2Step.acceptOwnership`](#Ownable2Step-acceptOwnership--).
-
-This module is used through inheritance. It will make available all functions
-from parent (Ownable).
-
-
-
-Starts the ownership transfer of the contract to a new account. Replaces the pending transfer if there is one.
-Can only be called by the current owner.
-
-Setting `newOwner` to the zero address is allowed; this can be used to cancel an initiated ownership transfer.
-
-
-
-```solidity
-import "@openzeppelin/contracts/crosschain/bridges/BridgeERC20Core.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.
-
-
```solidity
-import "@openzeppelin/contracts/interfaces/IERC1967.sol";
+import "@openzeppelin/contracts/interfaces/IERC1363Receiver.sol";
```
-ERC-1967: Proxy Storage Slots. This interface contains the events defined in the ERC.
+Interface for any contract that wants to support `transferAndCall` or `transferFromAndCall`
+from ERC-1363 token contracts.
+Whenever ERC-1363 tokens are transferred to this contract via `transferAndCall` or `transferFromAndCall`
+by `operator` from `from`, this function is called.
-Emitted when the beacon is changed.
+
+To accept the transfer, this must return
+`bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)"))`
+(i.e. 0x88a7ca5c, or its own function selector).
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC2309.sol";
+import "@openzeppelin/contracts/interfaces/IERC1363Spender.sol";
```
-ERC-2309: ERC-721 Consecutive Transfer Extension.
+Interface for any contract that wants to support `approveAndCall`
+from ERC-1363 token contracts.
-Emitted when the tokens from `fromTokenId` to `toTokenId` are transferred from `fromAddress` to `toAddress`.
+Whenever an ERC-1363 token `owner` approves this contract via `approveAndCall`
+to spend their tokens, this function is called.
+
+
+To accept the approval, this must return
+`bytes4(keccak256("onApprovalReceived(address,uint256,bytes)"))`
+(i.e. 0x7b04a2d0, or its own function selector).
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC2981.sol";
+import "@openzeppelin/contracts/interfaces/IERC1820Implementer.sol";
```
-Interface for the NFT Royalty Standard.
-
-A standardized way to retrieve royalty payment information for non-fungible tokens (NFTs) to enable universal
-support for royalty payments across all NFT marketplaces and ecosystem participants.
+Interface for an ERC-1820 implementer, as defined in the
+[ERC](https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface).
+Used by contracts that will be registered as implementers in the
+[`IERC1820Registry`](#IERC1820Registry).
-Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of
-exchange. The royalty amount is denominated and should be paid in that same unit of exchange.
+Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract
+implements `interfaceHash` for `account`.
-
-ERC-2981 allows setting the royalty to 100% of the price. In that case all the price would be sent to the
-royalty receiver and 0 tokens to the seller. Contracts dealing with royalty should consider empty transfers.
-
+See [`IERC1820Registry.setInterfaceImplementer`](#IERC1820Registry-setInterfaceImplementer-address-bytes32-address-).
```solidity
-import "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
+import "@openzeppelin/contracts/interfaces/IERC1820Registry.sol";
```
-Interface of the ERC-3156 FlashBorrower, as defined in
-[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
+Interface of the global ERC-1820 Registry, as defined in the
+[ERC](https://eips.ethereum.org/EIPS/eip-1820). Accounts may register
+implementers for interfaces in this registry, as well as query support.
+
+Implementers may be shared by multiple accounts, and can also implement more
+than a single interface for each account. Contracts can implement interfaces
+for themselves, but externally-owned accounts (EOA) must delegate this to a
+contract.
+
+[`IERC165`](/contracts/5.x/api/utils#IERC165) interfaces can also be queried via the registry.
+
+For an in-depth explanation and source code analysis, see the ERC text.
-
-## `IERC3156FlashLender`
+Sets `newManager` as the manager for `account`. A manager of an
+account is able to set interface implementers for it.
-
-
-
+By default, each account is its own manager. Passing a value of `0x0` in
+`newManager` will reset the manager to this initial state.
-
+Emits a [`IERC1820Registry.ManagerChanged`](#IERC1820Registry-ManagerChanged-address-address-) event.
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC3156FlashLender.sol";
-```
+Requirements:
-Interface of the ERC-3156 FlashLender, as defined in
-[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
+- the caller must be the current manager for `account`.
-
-The amount of currency available to be lent.
+Returns the manager for `account`.
+
+See [`IERC1820Registry.setManager`](#IERC1820Registry-setManager-address-address-).
-The fee to be charged for a given loan.
+Sets the `implementer` contract as ``account``'s implementer for
+`interfaceHash`.
+
+`account` being the zero address is an alias for the caller's address.
+The zero address can also be used in `implementer` to remove an old one.
+
+See [`IERC1820Registry.interfaceHash`](#IERC1820Registry-interfaceHash-string-) to learn how these are created.
+
+Emits an [`IERC1820Registry.InterfaceImplementerSet`](#IERC1820Registry-InterfaceImplementerSet-address-bytes32-address-) event.
+
+Requirements:
+
+- the caller must be the current manager for `account`.
+- `interfaceHash` must not be an [`IERC165`](/contracts/5.x/api/utils#IERC165) interface id (i.e. it must not
+end in 28 zeroes).
+- `implementer` must implement [`IERC1820Implementer`](#IERC1820Implementer) and return true when
+queried for support, unless `implementer` is the caller. See
+[`IERC1820Implementer.canImplementInterfaceForAddress`](#IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-).
-
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC4626.sol";
-```
-
-Interface of the ERC-4626 "Tokenized Vault Standard", as defined in
-[ERC-4626](https://eips.ethereum.org/EIPS/eip-4626).
-
-
+Returns the implementer of `interfaceHash` for `account`. If no such
+implementer is registered, returns the zero address.
-
-
Events
-
-- [Deposit(sender, owner, assets, shares)](#IERC4626-Deposit-address-address-uint256-uint256-)
-- [Withdraw(sender, receiver, owner, assets, shares)](#IERC4626-Withdraw-address-address-address-uint256-uint256-)
-
-IERC20
+If `interfaceHash` is an [`IERC165`](/contracts/5.x/api/utils#IERC165) interface id (i.e. it ends with 28
+zeroes), `account` will be queried for support of it.
-- [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-)
-- [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-)
+`account` being the zero address is an alias for the caller's address.
-
-Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.
-
-- MUST be an ERC-20 token contract.
-- MUST NOT revert.
+Returns the interface hash for an `interfaceName`, as defined in the
+corresponding
+[section of the ERC](https://eips.ethereum.org/EIPS/eip-1820#interface-name).
-Returns the total amount of the underlying asset that is “managed” by Vault.
-
-- SHOULD include any compounding that occurs from yield.
-- MUST be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT revert.
-
-Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal
-scenario where all the conditions are met.
-
-- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT show any variations depending on the caller.
-- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
-- MUST NOT revert.
-
-
-This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
-“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
-from.
-
-
-Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal
-scenario where all the conditions are met.
-
-- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT show any variations depending on the caller.
-- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
-- MUST NOT revert.
-
-
-This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
-“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
-from.
-
-
-
-Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver,
-through a deposit call.
-- MUST return a limited value if receiver is subject to some deposit limit.
-- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited.
-- MUST NOT revert.
+
-Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given
-current on-chain conditions.
+
+
-- MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit
- call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called
- in the same transaction.
-- MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the
- deposit would be accepted, regardless if the user has enough tokens approved, etc.
-- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
-- MUST NOT revert.
+
-
-any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by depositing.
-
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC1967.sol";
+```
+ERC-1967: Proxy Storage Slots. This interface contains the events defined in the ERC.
+
+
-
-Deposit `assets` underlying tokens and send the corresponding number of vault shares (`shares`) to `receiver`.
-- MUST emit the Deposit event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- deposit execution, and are accounted for during deposit.
-- MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not
- approving enough underlying tokens to the Vault contract, etc).
+
-
-most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
-
+Emitted when the implementation is upgraded.
-Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call.
-- MUST return a limited value if receiver is subject to some mint limit.
-- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted.
-- MUST NOT revert.
+Emitted when the admin account has changed.
-Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given
-current on-chain conditions.
-
-- MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call
- in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the
- same transaction.
-- MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint
- would be accepted, regardless if the user has enough tokens approved, etc.
-- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
-- MUST NOT revert.
-
-
-any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by minting.
-
-
-
-
-Mints exactly `shares` vault shares to `receiver` in exchange for `assets` underlying tokens.
-- MUST emit the Deposit event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint
- execution, and are accounted for during mint.
-- MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not
- approving enough underlying tokens to the Vault contract, etc).
+
-
-most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
-
+
-Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the
-Vault, through a withdraw call.
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC2309.sol";
+```
-- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
-- MUST NOT revert.
+ERC-2309: ERC-721 Consecutive Transfer Extension.
+
-
-Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block,
-given current on-chain conditions.
-- MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw
- call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if
- called
- in the same transaction.
-- MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though
- the withdrawal would be accepted, regardless if the user has enough shares, etc.
-- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
-- MUST NOT revert.
+
-
-any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by depositing.
-
+Emitted when the tokens from `fromTokenId` to `toTokenId` are transferred from `fromAddress` to `toAddress`.
-Burns shares from owner and sends exactly assets of underlying tokens to receiver.
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC2612.sol";
+```
-- MUST emit the Withdraw event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- withdraw execution, and are accounted for during withdraw.
-- MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner
- not having enough shares, etc).
+
+
Functions
+
+
+IERC20Permit
-Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
-Those methods should be performed separately.
+- [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--)
+
-Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault,
-through a redeem call.
+## `IERC2981`
-- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
-- MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock.
-- MUST NOT revert.
+
+
+
-
+Interface for the NFT Royalty Standard.
-Allows an on-chain or off-chain user to simulate the effects of their redemption at the current block,
-given current on-chain conditions.
+A standardized way to retrieve royalty payment information for non-fungible tokens (NFTs) to enable universal
+support for royalty payments across all NFT marketplaces and ecosystem participants.
-- MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call
- in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the
- same transaction.
-- MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the
- redemption would be accepted, regardless if the user has enough shares, etc.
-- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
-- MUST NOT revert.
+
+
Functions
+
+- [royaltyInfo(tokenId, salePrice)](#IERC2981-royaltyInfo-uint256-uint256-)
+
+IERC165
-
-any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by redeeming.
-
+- [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-)
+
-Burns exactly shares from owner and sends assets of underlying tokens to receiver.
-
-- MUST emit the Withdraw event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- redeem execution, and are accounted for during redeem.
-- MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner
- not having enough shares, etc).
+Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of
+exchange. The royalty amount is denominated and should be paid in that same unit of exchange.
-some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
-Those methods should be performed separately.
+ERC-2981 allows setting the royalty to 100% of the price. In that case all the price would be sent to the
+royalty receiver and 0 tokens to the seller. Contracts dealing with royalty should consider empty transfers.
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
+```
+Interface of the ERC-3156 FlashBorrower, as defined in
+[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
+
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC4626.sol";
+```
+
+Interface of the ERC-4626 "Tokenized Vault Standard", as defined in
+[ERC-4626](https://eips.ethereum.org/EIPS/eip-4626).
+
+
-This event emits when the metadata of a token is changed.
-So that the third-party platforms such as NFT market could
-timely update the images and related attributes of the NFT.
+Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.
+
+- MUST be an ERC-20 token contract.
+- MUST NOT revert.
-This event emits when the metadata of a range of tokens is changed.
-So that the third-party platforms such as NFT market could
-timely update the images and related attributes of the NFTs.
+Returns the total amount of the underlying asset that is “managed” by Vault.
+
+- SHOULD include any compounding that occurs from yield.
+- MUST be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT revert.
-## `IERC5267`
+Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal
+scenario where all the conditions are met.
-
-
-
+- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT show any variations depending on the caller.
+- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
+- MUST NOT revert.
+
+
+This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
+“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
+from.
+
+
+
+Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal
+scenario where all the conditions are met.
+
+- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT show any variations depending on the caller.
+- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
+- MUST NOT revert.
+
+
+This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
+“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
+from.
+
-
-returns the fields and values that describe the domain separator used by this contract for EIP-712
-signature.
+Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver,
+through a deposit call.
+
+- MUST return a limited value if receiver is subject to some deposit limit.
+- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited.
+- MUST NOT revert.
+
+Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given
+current on-chain conditions.
+
+- MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit
+ call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called
+ in the same transaction.
+- MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the
+ deposit would be accepted, regardless if the user has enough tokens approved, etc.
+- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
+- MUST NOT revert.
+
+
+any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by depositing.
+
+
-MAY be emitted to signal that the domain could have changed.
+Deposit `assets` underlying tokens and send the corresponding number of vault shares (`shares`) to `receiver`.
+
+- MUST emit the Deposit event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ deposit execution, and are accounted for during deposit.
+- MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not
+ approving enough underlying tokens to the Vault contract, etc).
+
+
+most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
+
-## `IERC5313`
+Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call.
+- MUST return a limited value if receiver is subject to some mint limit.
+- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted.
+- MUST NOT revert.
-
-
-
+
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC5313.sol";
-```
+Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given
+current on-chain conditions.
-Interface for the Light Contract Ownership Standard.
+- MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call
+ in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the
+ same transaction.
+- MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint
+ would be accepted, regardless if the user has enough tokens approved, etc.
+- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
+- MUST NOT revert.
-A standardized minimal interface required to identify an account that controls a contract
+
+any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by minting.
+
-
-Gets the address of the owner.
+Mints exactly `shares` vault shares to `receiver` in exchange for `assets` underlying tokens.
+
+- MUST emit the Deposit event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint
+ execution, and are accounted for during mint.
+- MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not
+ approving enough underlying tokens to the Vault contract, etc).
+
+
+most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
+
-## `IERC5805`
+Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the
+Vault, through a withdraw call.
-
-
-
+- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
+- MUST NOT revert.
+
-- [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-)
+Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block,
+given current on-chain conditions.
-
-
-IERC6372
+- MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw
+ call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if
+ called
+ in the same transaction.
+- MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though
+ the withdrawal would be accepted, regardless if the user has enough shares, etc.
+- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
+- MUST NOT revert.
-- [clock()](#IERC6372-clock--)
-- [CLOCK_MODE()](#IERC6372-CLOCK_MODE--)
+
+any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by depositing.
+
-
+
+Burns shares from owner and sends exactly assets of underlying tokens to receiver.
+
+- MUST emit the Withdraw event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ withdraw execution, and are accounted for during withdraw.
+- MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner
+ not having enough shares, etc).
+
+Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
+Those methods should be performed separately.
-
-
+Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault,
+through a redeem call.
-
+- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
+- MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock.
+- MUST NOT revert.
-## `IERC6372`
+
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC6372.sol";
-```
+Allows an on-chain or off-chain user to simulate the effects of their redemption at the current block,
+given current on-chain conditions.
+
+- MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call
+ in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the
+ same transaction.
+- MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the
+ redemption would be accepted, regardless if the user has enough shares, etc.
+- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
+- MUST NOT revert.
+
+
+any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by redeeming.
+
-
-Clock used for flagging checkpoints. Can be overridden to implement timestamp based checkpoints (and voting).
+Burns exactly shares from owner and sends assets of underlying tokens to receiver.
+
+- MUST emit the Withdraw event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ redeem execution, and are accounted for during redeem.
+- MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner
+ not having enough shares, etc).
+
+
+some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
+Those methods should be performed separately.
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC6909.sol";
+import "@openzeppelin/contracts/interfaces/IERC4906.sol";
```
-Required interface of an ERC-6909 compliant contract, as defined in the
-[ERC](https://eips.ethereum.org/EIPS/eip-6909).
-
Functions
-- [balanceOf(owner, id)](#IERC6909-balanceOf-address-uint256-)
-- [allowance(owner, spender, id)](#IERC6909-allowance-address-address-uint256-)
-- [isOperator(owner, spender)](#IERC6909-isOperator-address-address-)
-- [approve(spender, id, amount)](#IERC6909-approve-address-uint256-uint256-)
-- [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-)
+
+IERC721
+
+- [balanceOf(owner)](#IERC721-balanceOf-address-)
+- [ownerOf(tokenId)](#IERC721-ownerOf-uint256-)
+- [safeTransferFrom(from, to, tokenId, data)](#IERC721-safeTransferFrom-address-address-uint256-bytes-)
+- [safeTransferFrom(from, to, tokenId)](#IERC721-safeTransferFrom-address-address-uint256-)
+- [transferFrom(from, to, tokenId)](#IERC721-transferFrom-address-address-uint256-)
+- [approve(to, tokenId)](#IERC721-approve-address-uint256-)
+- [setApprovalForAll(operator, approved)](#IERC721-setApprovalForAll-address-bool-)
+- [getApproved(tokenId)](#IERC721-getApproved-uint256-)
+- [isApprovedForAll(owner, operator)](#IERC721-isApprovedForAll-address-address-)
+
+IERC165
@@ -1546,237 +1647,203 @@ Required interface of an ERC-6909 compliant contract, as defined in the
-Returns true if `spender` is set as an operator for `owner`.
+This event emits when the metadata of a token is changed.
+So that the third-party platforms such as NFT market could
+timely update the images and related attributes of the NFT.
-Sets an approval to `spender` for `amount` of tokens of type `id` from the caller's tokens. An `amount` of
-`type(uint256).max` signifies an unlimited approval.
+
-Must return true.
+This event emits when the metadata of a range of tokens is changed.
+So that the third-party platforms such as NFT market could
+timely update the images and related attributes of the NFTs.
-Transfers `amount` of token type `id` from `sender` to `receiver`.
-
-Must return true.
+returns the fields and values that describe the domain separator used by this contract for EIP-712
+signature.
-Emitted when the allowance of a `spender` for an `owner` is set for a token of type `id`.
-The new allowance is `amount`.
+MAY be emitted to signal that the domain could have changed.
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC5313.sol";
+```
-Emitted when `owner` grants or revokes operator status for a `spender`.
+Interface for the Light Contract Ownership Standard.
+
+A standardized minimal interface required to identify an account that controls a contract
+
-Returns the ticker symbol of the token of type `id`.
+Clock used for flagging checkpoints. Can be overridden to implement timestamp based checkpoints (and voting).
-Returns the URI for the token of type `id`.
+Returns the amount of tokens of type `id` that `spender` is allowed to spend on behalf of `owner`.
+
+
+Does not include operator allowances.
+
-
-IERC6909
+Sets an approval to `spender` for `amount` of tokens of type `id` from the caller's tokens. An `amount` of
+`type(uint256).max` signifies an unlimited approval.
-- [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-)
+Must return true.
-
-Returns the total supply of the token of type `id`.
+Grants or revokes unlimited transfer permission of any token id to `spender` for the caller's tokens.
+
+Must return true.
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC7913.sol";
-```
+Transfers `amount` of token type `id` from the caller's account to `receiver`.
-Signature verifier interface.
+Must return true.
-
-Verifies `signature` as a valid signature of `hash` by `key`.
+Transfers `amount` of token type `id` from `sender` to `receiver`.
-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
+Must return true.
-ERC-1822: Universal Upgradeable Proxy Standard (UUPS) documents a method for upgradeability through a simplified
-proxy whose upgrades are fully controlled by the current implementation.
+Emitted when the allowance of a `spender` for an `owner` is set for a token of type `id`.
+The new allowance is `amount`.
-
-Returns the storage slot that the proxiable contract assumes is being used to store the implementation
-address.
+
-
-A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
-bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
-function revert if invoked through a proxy.
-
+Emitted when `owner` grants or revokes operator status for a `spender`.
-A [user operation](https://github.com/ethereum/ercs/blob/master/ERCS/erc-4337.md#useroperation) is composed of the following elements:
-- `sender` (`address`): The account making the operation
-- `nonce` (`uint256`): Anti-replay parameter (see “Semi-abstracted Nonce Support” )
-- `factory` (`address`): account factory, only for new accounts
-- `factoryData` (`bytes`): data for account factory (only if account factory exists)
-- `callData` (`bytes`): The data to pass to the sender during the main execution call
-- `callGasLimit` (`uint256`): The amount of gas to allocate the main execution call
-- `verificationGasLimit` (`uint256`): The amount of gas to allocate for the verification step
-- `preVerificationGas` (`uint256`): Extra gas to pay the bundler
-- `maxFeePerGas` (`uint256`): Maximum fee per gas (similar to EIP-1559 max_fee_per_gas)
-- `maxPriorityFeePerGas` (`uint256`): Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas)
-- `paymaster` (`address`): Address of paymaster contract, (or empty, if account pays for itself)
-- `paymasterVerificationGasLimit` (`uint256`): The amount of gas to allocate for the paymaster validation code
-- `paymasterPostOpGasLimit` (`uint256`): The amount of gas to allocate for the paymaster post-operation code
-- `paymasterData` (`bytes`): Data for paymaster (only if paymaster exists)
-- `signature` (`bytes`): Data passed into the account to verify authorization
+Emitted when `amount` tokens of type `id` are moved from `sender` to `receiver` initiated by `caller`.
-When passed to on-chain contracts, the following packed version is used.
-- `sender` (`address`)
-- `nonce` (`uint256`)
-- `initCode` (`bytes`): concatenation of factory address and factoryData (or empty)
-- `callData` (`bytes`)
-- `accountGasLimits` (`bytes32`): concatenation of verificationGas (16 bytes) and callGas (16 bytes)
-- `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`)
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/IERC6909.sol";
```
-Aggregates and validates multiple signatures for a batch of user operations.
-
-A contract could implement this interface with custom validation schemes that allow signature aggregation,
-enabling significant optimizations and gas savings for execution and transaction data cost.
-
-Bundlers and clients whitelist supported aggregators.
-
-See [ERC-7766](https://eips.ethereum.org/EIPS/eip-7766)
+Optional extension of [`IERC6909`](#IERC6909) that adds metadata functions.
+
+
+IERC165
-Validates the signature for a user operation.
-Returns an alternative signature that should be used during bundling.
+- [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-)
+
-Validates that the aggregated signature is valid for the user operations.
-
-Requirements:
-
-- The aggregated signature MUST match the given list of operations.
-
-
-
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
-```
+Returns the name of the token of type `id`.
-Handle nonce management for accounts.
+
+
-Nonces are used in accounts as a replay protection mechanism and to ensure the order of user operations.
-To avoid limiting the number of operations an account can perform, the interface allows using parallel
-nonces by using a `key` parameter.
+
-See [ERC-4337 semi-abstracted nonce support](https://eips.ethereum.org/EIPS/eip-4337#semi-abstracted-nonce-support).
+
-Returns the nonce for a `sender` account and a `key`.
-
-Nonces for a certain `key` are always increasing.
+Returns the number of decimals for the token of type `id`.
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/IERC6909.sol";
```
-Handle stake management for entities (i.e. accounts, paymasters, factories).
-
-The EntryPoint must implement the following API to let entities like paymasters have a stake,
-and thus have more flexibility in their storage access
-(see [reputation, throttling and banning.](https://eips.ethereum.org/EIPS/eip-4337#reputation-scoring-and-throttlingbanning-for-global-entities))
+Optional extension of [`IERC6909`](#IERC6909) that adds content URI functions.
-Unlocks the stake of the account.
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC7751.sol";
+```
+
+Wrapping of bubbled up reverts
+Interface of the [ERC-7751](https://eips.ethereum.org/EIPS/eip-7751) wrapping of bubbled up reverts.
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+import "@openzeppelin/contracts/interfaces/IERC777.sol";
```
-Entry point for user operations.
+Interface of the ERC-777 Token standard as defined in the ERC.
-User operations are validated and executed by this contract.
+This contract uses the
+[ERC-1820 registry standard](https://eips.ethereum.org/EIPS/eip-1820) to let
+token holders and recipients react to token movements by using setting implementers
+for the associated interfaces in said registry. See [`IERC1820Registry`](#IERC1820Registry) and
+[`IERC1820Implementer`](#IERC1820Implementer).
-A user operation at `opIndex` failed with `reason`.
+Returns the smallest part of the token that is not divisible. This
+means all token operations (creation, movement and destruction) must have
+amounts that are a multiple of this number.
+
+For most token contracts, this value will equal 1.
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
-```
-
-Base interface for an ERC-4337 account.
+Returns the amount of tokens owned by an account (`owner`).
-
-Validates a user operation.
+Moves `amount` tokens from the caller's account to `recipient`.
-* MUST validate the caller is a trusted EntryPoint
-* MUST validate that the signature is a valid signature of the userOpHash, and SHOULD
- return SIG_VALIDATION_FAILED (and not revert) on signature mismatch. Any other error MUST revert.
-* MUST pay the entryPoint (caller) at least the “missingAccountFunds” (which might
- be zero, in case the current account’s deposit is high enough)
+If send or receive hooks are registered for the caller and `recipient`,
+the corresponding functions will be called with `data` and empty
+`operatorData`. See [`IERC777Sender`](#IERC777Sender) and [`IERC777Recipient`](#IERC777Recipient).
-Returns an encoded packed validation data that is composed of the following elements:
+Emits a [`IERC777.Sent`](#IERC777-Sent-address-address-address-uint256-bytes-bytes-) event.
-- `authorizer` (`address`): 0 for success, 1 for failure, otherwise the address of an authorizer contract
-- `validUntil` (`uint48`): The UserOp is valid only up to this time. Zero for “infinite”.
-- `validAfter` (`uint48`): The UserOp is valid only after this time.
+Requirements
+
+- the caller must have at least `amount` tokens.
+- `recipient` cannot be the zero address.
+- if `recipient` is a contract, it must implement the [`IERC777Recipient`](#IERC777Recipient)
+interface.
-## `IAccountExecute`
+Destroys `amount` tokens from the caller's account, reducing the
+total supply.
-
-
-
+If a send hook is registered for the caller, the corresponding function
+will be called with `data` and empty `operatorData`. See [`IERC777Sender`](#IERC777Sender).
-
+Emits a [`IERC777.Burned`](#IERC777-Burned-address-address-uint256-bytes-bytes-) event.
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
-```
+Requirements
-Support for executing user operations by prepending the [`IAccountExecute.executeUserOp`](#IAccountExecute-executeUserOp-struct-PackedUserOperation-bytes32-) function selector
-to the UserOperation's `callData`.
+- the caller must have at least `amount` tokens.
-
-Executes a user operation.
+Returns true if an account is an operator of `tokenHolder`.
+Operators can send and burn tokens on behalf of their owners. All
+accounts are their own operator.
+
+See [`IERC777.operatorSend`](#IERC777-operatorSend-address-address-uint256-bytes-bytes-) and [`IERC777.operatorBurn`](#IERC777-operatorBurn-address-uint256-bytes-bytes-).
-
-
-
+Make an account an operator of the caller.
-
+See [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-).
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
-```
+Emits an [`IERC777.AuthorizedOperator`](#IERC777-AuthorizedOperator-address-address-) event.
-Interface for a paymaster contract that agrees to pay for the gas costs of a user operation.
+Requirements
-
-A paymaster must hold a stake to cover the required entrypoint stake and also the gas for the transaction.
-
+- `operator` cannot be calling address.
-
-Validates whether the paymaster is willing to pay for the user operation. See
-[`IAccount.validateUserOp`](#IAccount-validateUserOp-struct-PackedUserOperation-bytes32-uint256-) for additional information on the return value.
+Revoke an account's operator status for the caller.
-
-Bundlers will reject this method if it modifies the state, unless it's whitelisted.
-
+See [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-) and [`IERC777.defaultOperators`](#IERC777-defaultOperators--).
+
+Emits a [`IERC777.RevokedOperator`](#IERC777-RevokedOperator-address-address-) event.
+
+Requirements
+
+- `operator` cannot be calling address.
-Verifies the sender is the entrypoint.
+Returns the list of default operators. These accounts are operators
+for all token holders, even if [`IERC777.authorizeOperator`](#IERC777-authorizeOperator-address-) was never called on
+them.
+
+This list is immutable, but individual holders may revoke these via
+[`IERC777.revokeOperator`](#IERC777-revokeOperator-address-), in which case [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-) will return false.
-
-
-
+Moves `amount` tokens from `sender` to `recipient`. The caller must
+be an operator of `sender`.
-
+If send or receive hooks are registered for `sender` and `recipient`,
+the corresponding functions will be called with `data` and
+`operatorData`. See [`IERC777Sender`](#IERC777Sender) and [`IERC777Recipient`](#IERC777Recipient).
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
-```
+Emits a [`IERC777.Sent`](#IERC777-Sent-address-address-address-uint256-bytes-bytes-) event.
-Standard ERC-20 Errors
-Interface of the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors for ERC-20 tokens.
+Requirements
+
+- `sender` cannot be the zero address.
+- `sender` must have at least `amount` tokens.
+- the caller must be an operator for `sender`.
+- `recipient` cannot be the zero address.
+- if `recipient` is a contract, it must implement the [`IERC777Recipient`](#IERC777Recipient)
+interface.
-
-Indicates an error related to the current `balance` of a `sender`. Used in transfers.
+Destroys `amount` tokens from `account`, reducing the total supply.
+The caller must be an operator of `account`.
+
+If a send hook is registered for `account`, the corresponding function
+will be called with `data` and `operatorData`. See [`IERC777Sender`](#IERC777Sender).
+
+Emits a [`IERC777.Burned`](#IERC777-Burned-address-address-uint256-bytes-bytes-) event.
+
+Requirements
+
+- `account` cannot be the zero address.
+- `account` must have at least `amount` tokens.
+- the caller must be an operator for `account`.
-Indicates a failure with the token `sender`. Used in transfers.
+Emitted when `amount` tokens are created by `operator` and assigned to `to`.
+
+Note that some additional user `data` and `operatorData` can be logged in the event.
-Indicates a failure with the token `receiver`. Used in transfers.
+Emitted when `operator` destroys `amount` tokens from `account`.
+
+Note that some additional user `data` and `operatorData` can be logged in the event.
-Indicates a failure with the `approver` of a token to be approved. Used in approvals.
+Emitted when `operator` is revoked its operator status for `tokenHolder`.
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
+import "@openzeppelin/contracts/interfaces/IERC777Recipient.sol";
```
-Standard ERC-721 Errors
-Interface of the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors for ERC-721 tokens.
+Interface of the ERC-777 Tokens Recipient standard as defined in the ERC.
+
+Accounts can be notified of [`IERC777`](#IERC777) tokens being sent to them by having a
+contract implement this interface (contract holders can be their own
+implementer) and registering it on the
+[ERC-1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+
+See [`IERC1820Registry`](#IERC1820Registry) and [`IERC1820Implementer`](#IERC1820Implementer).
-Indicates that an address can't be an owner. For example, `address(0)` is a forbidden owner in ERC-721.
-Used in balance queries.
+Called by an [`IERC777`](#IERC777) token contract whenever tokens are being
+moved or created into a registered account (`to`). The type of operation
+is conveyed by `from` being the zero address or not.
-
-
+This call occurs _after_ the token contract's state is updated, so
+[`IERC777.balanceOf`](#IERC777-balanceOf-address-), etc., can be used to query the post-operation state.
-
+This function may revert to prevent the operation from being executed.
-
+Interface of the ERC-777 Tokens Sender standard as defined in the ERC.
-Indicates a failure with the token `sender`. Used in transfers.
+[`IERC777`](#IERC777) Token holders can be notified of operations performed on their
+tokens by having a contract implement this interface (contract holders can be
+their own implementer) and registering it on the
+[ERC-1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+See [`IERC1820Registry`](#IERC1820Registry) and [`IERC1820Implementer`](#IERC1820Implementer).
+
+
+
Functions
+
+- [tokensToSend(operator, from, to, amount, userData, operatorData)](#IERC777Sender-tokensToSend-address-address-address-uint256-bytes-bytes-)
-Indicates a failure with the token `receiver`. Used in transfers.
+Called by an [`IERC777`](#IERC777) token contract whenever a registered holder's
+(`from`) tokens are about to be moved or destroyed. The type of operation
+is conveyed by `to` being the zero address or not.
-
-
+This call occurs _before_ the token contract's state is updated, so
+[`IERC777.balanceOf`](#IERC777-balanceOf-address-), etc., can be used to query the pre-operation state.
-
+This function may revert to prevent the operation from being executed.
-
-Indicates a failure with the `approver` of a token to be approved. Used in approvals.
+```solidity
+import "@openzeppelin/contracts/interfaces/IERC7913.sol";
+```
+
+Signature verifier interface.
+
-Indicates a failure with the `operator` to be approved. Used in approvals.
+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
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC1822.sol";
```
-Standard ERC-1155 Errors
-Interface of the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors for ERC-1155 tokens.
+ERC-1822: Universal Upgradeable Proxy Standard (UUPS) documents a method for upgradeability through a simplified
+proxy whose upgrades are fully controlled by the current implementation.
-Indicates an error related to the current `balance` of a `sender`. Used in transfers.
+Returns the storage slot that the proxiable contract assumes is being used to store the implementation
+address.
+
+
+A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
+bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
+function revert if invoked through a proxy.
+
+A [user operation](https://github.com/ethereum/ercs/blob/master/ERCS/erc-4337.md#useroperation) is composed of the following elements:
+- `sender` (`address`): The account making the operation
+- `nonce` (`uint256`): Anti-replay parameter (see “Semi-abstracted Nonce Support” )
+- `factory` (`address`): account factory, only for new accounts
+- `factoryData` (`bytes`): data for account factory (only if account factory exists)
+- `callData` (`bytes`): The data to pass to the sender during the main execution call
+- `callGasLimit` (`uint256`): The amount of gas to allocate the main execution call
+- `verificationGasLimit` (`uint256`): The amount of gas to allocate for the verification step
+- `preVerificationGas` (`uint256`): Extra gas to pay the bundler
+- `maxFeePerGas` (`uint256`): Maximum fee per gas (similar to EIP-1559 max_fee_per_gas)
+- `maxPriorityFeePerGas` (`uint256`): Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas)
+- `paymaster` (`address`): Address of paymaster contract, (or empty, if account pays for itself)
+- `paymasterVerificationGasLimit` (`uint256`): The amount of gas to allocate for the paymaster validation code
+- `paymasterPostOpGasLimit` (`uint256`): The amount of gas to allocate for the paymaster post-operation code
+- `paymasterData` (`bytes`): Data for paymaster (only if paymaster exists)
+- `signature` (`bytes`): Data passed into the account to verify authorization
-Indicates a failure with the token `receiver`. Used in transfers.
+When passed to on-chain contracts, the following packed version is used.
+- `sender` (`address`)
+- `nonce` (`uint256`)
+- `initCode` (`bytes`): concatenation of factory address and factoryData (or empty)
+- `callData` (`bytes`)
+- `accountGasLimits` (`bytes32`): concatenation of verificationGas (16 bytes) and callGas (16 bytes)
+- `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`)
-
-Indicates a failure with the `operator`’s approval. Used in transfers.
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
+```
+
+Aggregates and validates multiple signatures for a batch of user operations.
+
+A contract could implement this interface with custom validation schemes that allow signature aggregation,
+enabling significant optimizations and gas savings for execution and transaction data cost.
+
+Bundlers and clients whitelist supported aggregators.
+See [ERC-7766](https://eips.ethereum.org/EIPS/eip-7766)
+
+
-Indicates a failure with the `approver` of a token to be approved. Used in approvals.
+Validates the signature for a user operation.
+Returns an alternative signature that should be used during bundling.
-Indicates a failure with the `operator` to be approved. Used in approvals.
+Returns an aggregated signature for a batch of user operation's signatures.
-Indicates an array length mismatch between ids and values in a safeBatchTransferFrom operation.
-Used in batch transfers.
-
-
-
-
-
-
-
+Validates that the aggregated signature is valid for the user operations.
-## `VALIDATION_SUCCESS`
+Requirements:
-
-
-
+- The aggregated signature MUST match the given list of operations.
+Handle nonce management for accounts.
-## `MODULE_TYPE_EXECUTOR`
+Nonces are used in accounts as a replay protection mechanism and to ensure the order of user operations.
+To avoid limiting the number of operations an account can perform, the interface allows using parallel
+nonces by using a `key` parameter.
-
-
-
+See [ERC-4337 semi-abstracted nonce support](https://eips.ethereum.org/EIPS/eip-4337#semi-abstracted-nonce-support).
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
```
-Minimal configuration interface for ERC-7579 modules
+Handle stake management for entities (i.e. accounts, paymasters, factories).
+
+The EntryPoint must implement the following API to let entities like paymasters have a stake,
+and thus have more flexibility in their storage access
+(see [reputation, throttling and banning.](https://eips.ethereum.org/EIPS/eip-4337#reputation-scoring-and-throttlingbanning-for-global-entities))
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
-```
-
-ERC-7579 Validation module (type 1).
-
-A module that implements logic to validate user operations and signatures.
-
-
-
Functions
-
-- [validateUserOp(userOp, userOpHash)](#IERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-)
-- [isValidSignatureWithSender(sender, hash, signature)](#IERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-)
-
-IERC7579Module
-
-- [onInstall(data)](#IERC7579Module-onInstall-bytes-)
-- [onUninstall(data)](#IERC7579Module-onUninstall-bytes-)
-- [isModuleType(moduleTypeId)](#IERC7579Module-isModuleType-uint256-)
+Adds stake to the account with an unstake delay of `unstakeDelaySec`.
-
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
```
-ERC-7579 Hooks module (type 4).
+Entry point for user operations.
-A module that implements logic to execute before and after the account executes a user operation,
-either individually or batched.
+User operations are validated and executed by this contract.
+
+Validates a user operation.
+
+* MUST validate the caller is a trusted EntryPoint
+* MUST validate that the signature is a valid signature of the userOpHash, and SHOULD
+ return SIG_VALIDATION_FAILED (and not revert) on signature mismatch. Any other error MUST revert.
+* MUST pay the entryPoint (caller) at least the “missingAccountFunds” (which might
+ be zero, in case the current account’s deposit is high enough)
+
+Returns an encoded packed validation data that is composed of the following elements:
-
-
-
+- `authorizer` (`address`): 0 for success, 1 for failure, otherwise the address of an authorizer contract
+- `validUntil` (`uint48`): The UserOp is valid only up to this time. Zero for “infinite”.
+- `validAfter` (`uint48`): The UserOp is valid only after this time.
+
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
```
-ERC-7579 Execution.
-
-Accounts should implement this interface so that the Entrypoint and ERC-7579 modules can execute operations.
+Support for executing user operations by prepending the [`IAccountExecute.executeUserOp`](#IAccountExecute-executeUserOp-struct-PackedUserOperation-bytes32-) function selector
+to the UserOperation's `callData`.
-
-Executes a transaction on behalf of the account.
-
+- [executeUserOp(userOp, userOpHash)](#IAccountExecute-executeUserOp-struct-PackedUserOperation-bytes32-)
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
```
-ERC-7579 Account Config.
+Interface for a paymaster contract that agrees to pay for the gas costs of a user operation.
-Accounts should implement this interface to expose information that identifies the account, supported modules and capabilities.
+
+A paymaster must hold a stake to cover the required entrypoint stake and also the gas for the transaction.
+
+Validates whether the paymaster is willing to pay for the user operation. See
+[`IAccount.validateUserOp`](#IAccount-validateUserOp-struct-PackedUserOperation-bytes32-uint256-) for additional information on the return value.
-Function to check if the account supports a certain execution mode (see above)
+
+Bundlers will reject this method if it modifies the state, unless it's whitelisted.
+
-
-IERC20
-
-- [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-)
-- [Approval(owner, spender, value)](#IERC20-Approval-address-address-uint256-)
+Indicates a failure with the `approver` of a token to be approved. Used in approvals.
-
-Set the temporary allowance, allowing `spender` to withdraw (within the same transaction) assets
-held by the caller.
+Indicates a failure with the `spender` to be approved. Used in approvals.
```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7786.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
```
-Interface for ERC-7786 source gateways.
-
-See ERC-7786 for more details
+Standard ERC-721 Errors
+Interface of the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) custom errors for ERC-721 tokens.
-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 `sendId` 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.
+Indicates an error related to the ownership over a particular token. Used in transfers.
-Event emitted when a message is created. If `sendId` is zero, no further processing is necessary. If
-`sendId` is not zero, then further (gateway specific, and non-standardized) action is required.
+Indicates a failure with the token `sender`. Used in transfers.
-This error is thrown when a message creation fails because of an unsupported attribute being specified.
+Indicates a failure with the token `receiver`. Used in transfers.
-Endpoint for receiving cross-chain message.
-
-This function may be called directly by the gateway.
+Indicates a failure with the `operator` to be approved. Used in approvals.
-
-```solidity
-import "@openzeppelin/contracts/interfaces/draft-IERC7821.sol";
-```
-
-Interface for minimal batch executor.
+Indicates a failure with the `operator`’s approval. Used in transfers.
-
-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:
-- `bytes32(0x01000000000000000000...)`: does not support optional `opData`.
-- `bytes32(0x01000000000078210001...)`: supports optional `opData`.
+Indicates a failure with the `approver` of a token to be approved. Used in approvals.
-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.
+
-For calldata compression efficiency, if a Call.to is `address(0)`,
-it will be replaced with `address(this)`.
+
-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`.
+Indicates an array length mismatch between ids and values in a safeBatchTransferFrom operation.
+Used in batch transfers.
```solidity
-import "@openzeppelin/contracts/interfaces/IERC1363Receiver.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Interface for any contract that wants to support `transferAndCall` or `transferFromAndCall`
-from ERC-1363 token contracts.
+
-
-Whenever ERC-1363 tokens are transferred to this contract via `transferAndCall` or `transferFromAndCall`
-by `operator` from `from`, this function is called.
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+```
-
-To accept the transfer, this must return
-`bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)"))`
-(i.e. 0x88a7ca5c, or its own function selector).
-
+
+
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC1363Spender.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Interface for any contract that wants to support `approveAndCall`
-from ERC-1363 token contracts.
+
-
-Whenever an ERC-1363 token `owner` approves this contract via `approveAndCall`
-to spend their tokens, this function is called.
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+```
-
-To accept the approval, this must return
-`bytes4(keccak256("onApprovalReceived(address,uint256,bytes)"))`
-(i.e. 0x7b04a2d0, or its own function selector).
-
+
+
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC1820Implementer.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Interface for an ERC-1820 implementer, as defined in the
-[ERC](https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface).
-Used by contracts that will be registered as implementers in the
-[`IERC1820Registry`](#IERC1820Registry).
+Minimal configuration interface for ERC-7579 modules
-Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract
-implements `interfaceHash` for `account`.
-
-See [`IERC1820Registry.setInterfaceImplementer`](#IERC1820Registry-setInterfaceImplementer-address-bytes32-address-).
+This function is called by the smart account during installation of the module
-
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC1820Registry.sol";
-```
-
-Interface of the global ERC-1820 Registry, as defined in the
-[ERC](https://eips.ethereum.org/EIPS/eip-1820). Accounts may register
-implementers for interfaces in this registry, as well as query support.
-
-Implementers may be shared by multiple accounts, and can also implement more
-than a single interface for each account. Contracts can implement interfaces
-for themselves, but externally-owned accounts (EOA) must delegate this to a
-contract.
-
-[`IERC165`](/contracts/5.x/api/utils#IERC165) interfaces can also be queried via the registry.
-
-For an in-depth explanation and source code analysis, see the ERC text.
+
-
-Sets `newManager` as the manager for `account`. A manager of an
-account is able to set interface implementers for it.
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+```
-By default, each account is its own manager. Passing a value of `0x0` in
-`newManager` will reset the manager to this initial state.
+ERC-7579 Validation module (type 1).
-Emits a [`IERC1820Registry.ManagerChanged`](#IERC1820Registry-ManagerChanged-address-address-) event.
+A module that implements logic to validate user operations and signatures.
-Requirements:
+
+
Functions
+
+- [validateUserOp(userOp, userOpHash)](#IERC7579Validator-validateUserOp-struct-PackedUserOperation-bytes32-)
+- [isValidSignatureWithSender(sender, hash, signature)](#IERC7579Validator-isValidSignatureWithSender-address-bytes32-bytes-)
+
+IERC7579Module
-- the caller must be the current manager for `account`.
+- [onInstall(data)](#IERC7579Module-onInstall-bytes-)
+- [onUninstall(data)](#IERC7579Module-onUninstall-bytes-)
+- [isModuleType(moduleTypeId)](#IERC7579Module-isModuleType-uint256-)
+
-Sets the `implementer` contract as ``account``'s implementer for
-`interfaceHash`.
+Validates a signature using ERC-1271
-`account` being the zero address is an alias for the caller's address.
-The zero address can also be used in `implementer` to remove an old one.
+
+
-See [`IERC1820Registry.interfaceHash`](#IERC1820Registry-interfaceHash-string-) to learn how these are created.
+
-Emits an [`IERC1820Registry.InterfaceImplementerSet`](#IERC1820Registry-InterfaceImplementerSet-address-bytes32-address-) event.
+
-Requirements:
+## `IERC7579Hook`
-- the caller must be the current manager for `account`.
-- `interfaceHash` must not be an [`IERC165`](/contracts/5.x/api/utils#IERC165) interface id (i.e. it must not
-end in 28 zeroes).
-- `implementer` must implement [`IERC1820Implementer`](#IERC1820Implementer) and return true when
-queried for support, unless `implementer` is the caller. See
-[`IERC1820Implementer.canImplementInterfaceForAddress`](#IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-).
+
+
+
-
+ERC-7579 Hooks module (type 4).
-Returns the implementer of `interfaceHash` for `account`. If no such
-implementer is registered, returns the zero address.
+A module that implements logic to execute before and after the account executes a user operation,
+either individually or batched.
-If `interfaceHash` is an [`IERC165`](/contracts/5.x/api/utils#IERC165) interface id (i.e. it ends with 28
-zeroes), `account` will be queried for support of it.
+
+
Functions
+
+- [preCheck(msgSender, value, msgData)](#IERC7579Hook-preCheck-address-uint256-bytes-)
+- [postCheck(hookData)](#IERC7579Hook-postCheck-bytes-)
+
+IERC7579Module
-`account` being the zero address is an alias for the caller's address.
+- [onInstall(data)](#IERC7579Module-onInstall-bytes-)
+- [onUninstall(data)](#IERC7579Module-onUninstall-bytes-)
+- [isModuleType(moduleTypeId)](#IERC7579Module-isModuleType-uint256-)
+
-Returns the interface hash for an `interfaceName`, as defined in the
-corresponding
-[section of the ERC](https://eips.ethereum.org/EIPS/eip-1820#interface-name).
+Called by the smart account before execution
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
+```
+
+ERC-7579 Execution.
+
+Accounts should implement this interface so that the Entrypoint and ERC-7579 modules can execute operations.
+
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC2612.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
+ERC-7579 Account Config.
+
+Accounts should implement this interface to expose information that identifies the account, supported modules and capabilities.
+
-
-
-
+Returns the account id of the smart account
+
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC7751.sol";
-```
+
-Wrapping of bubbled up reverts
-Interface of the [ERC-7751](https://eips.ethereum.org/EIPS/eip-7751) wrapping of bubbled up reverts.
+
```solidity
-import "@openzeppelin/contracts/interfaces/IERC777.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
```
-Interface of the ERC-777 Token standard as defined in the ERC.
+ERC-7579 Module Config.
-This contract uses the
-[ERC-1820 registry standard](https://eips.ethereum.org/EIPS/eip-1820) to let
-token holders and recipients react to token movements by using setting implementers
-for the associated interfaces in said registry. See [`IERC1820Registry`](#IERC1820Registry) and
-[`IERC1820Implementer`](#IERC1820Implementer).
+Accounts should implement this interface to allow installing and uninstalling modules.
-Returns the smallest part of the token that is not divisible. This
-means all token operations (creation, movement and destruction) must have
-amounts that are a multiple of this number.
-
-For most token contracts, this value will equal 1.
+Returns whether a module is installed on the smart account
-Moves `amount` tokens from the caller's account to `recipient`.
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7674.sol";
+```
-If send or receive hooks are registered for the caller and `recipient`,
-the corresponding functions will be called with `data` and empty
-`operatorData`. See [`IERC777Sender`](#IERC777Sender) and [`IERC777Recipient`](#IERC777Recipient).
+Temporary Approval Extension for ERC-20 ([ERC-7674](https://github.com/ethereum/ERCs/pull/358))
-Emits a [`IERC777.Sent`](#IERC777-Sent-address-address-address-uint256-bytes-bytes-) event.
+
+
Functions
+
+- [temporaryApprove(spender, value)](#IERC7674-temporaryApprove-address-uint256-)
+
+IERC20
-Requirements
+- [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-)
-- the caller must have at least `amount` tokens.
-- `recipient` cannot be the zero address.
-- if `recipient` is a contract, it must implement the [`IERC777Recipient`](#IERC777Recipient)
-interface.
+
+
-Destroys `amount` tokens from the caller's account, reducing the
-total supply.
+Set the temporary allowance, allowing `spender` to withdraw (within the same transaction) assets
+held by the caller.
-If a send hook is registered for the caller, the corresponding function
-will be called with `data` and empty `operatorData`. See [`IERC777Sender`](#IERC777Sender).
+
+
-Emits a [`IERC777.Burned`](#IERC777-Burned-address-address-uint256-bytes-bytes-) event.
+
-Requirements
+
-- the caller must have at least `amount` tokens.
+## `IERC7786GatewaySource`
+
+
+
+
-
-
-Returns true if an account is an operator of `tokenHolder`.
-Operators can send and burn tokens on behalf of their owners. All
-accounts are their own operator.
-See [`IERC777.operatorSend`](#IERC777-operatorSend-address-address-uint256-bytes-bytes-) and [`IERC777.operatorBurn`](#IERC777-operatorBurn-address-uint256-bytes-bytes-).
+
-Make an account an operator of the caller.
-
-See [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-).
-
-Emits an [`IERC777.AuthorizedOperator`](#IERC777-AuthorizedOperator-address-address-) event.
-
-Requirements
-
-- `operator` cannot be calling address.
+Getter to check whether an attribute is supported or not.
-Revoke an account's operator status for the caller.
-
-See [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-) and [`IERC777.defaultOperators`](#IERC777-defaultOperators--).
-
-Emits a [`IERC777.RevokedOperator`](#IERC777-RevokedOperator-address-address-) event.
+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 `sendId` must be returned. Otherwise, the
+message MUST be sent and this function must return 0.
-Requirements
+* MUST emit a [`IERC7786GatewaySource.MessageSent`](#IERC7786GatewaySource-MessageSent-bytes32-bytes-bytes-bytes-uint256-bytes---) event.
-- `operator` cannot be calling address.
+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.
-Returns the list of default operators. These accounts are operators
-for all token holders, even if [`IERC777.authorizeOperator`](#IERC777-authorizeOperator-address-) was never called on
-them.
+
-This list is immutable, but individual holders may revoke these via
-[`IERC777.revokeOperator`](#IERC777-revokeOperator-address-), in which case [`IERC777.isOperatorFor`](#IERC777-isOperatorFor-address-address-) will return false.
+Event emitted when a message is created. If `sendId` is zero, no further processing is necessary. If
+`sendId` is not zero, then further (gateway specific, and non-standardized) action is required.
-Moves `amount` tokens from `sender` to `recipient`. The caller must
-be an operator of `sender`.
+This error is thrown when a message creation fails because of an unsupported attribute being specified.
-If send or receive hooks are registered for `sender` and `recipient`,
-the corresponding functions will be called with `data` and
-`operatorData`. See [`IERC777Sender`](#IERC777Sender) and [`IERC777Recipient`](#IERC777Recipient).
+
+
-Emits a [`IERC777.Sent`](#IERC777-Sent-address-address-address-uint256-bytes-bytes-) event.
+
-Requirements
+
-- `sender` cannot be the zero address.
-- `sender` must have at least `amount` tokens.
-- the caller must be an operator for `sender`.
-- `recipient` cannot be the zero address.
-- if `recipient` is a contract, it must implement the [`IERC777Recipient`](#IERC777Recipient)
-interface.
+## `IERC7786Recipient`
+
+
+
+
+
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7786.sol";
+```
+
+Interface for the ERC-7786 client contract (receiver).
+
+See ERC-7786 for more details
+
+
-Destroys `amount` tokens from `account`, reducing the total supply.
-The caller must be an operator of `account`.
+Endpoint for receiving cross-chain message.
-If a send hook is registered for `account`, the corresponding function
-will be called with `data` and `operatorData`. See [`IERC777Sender`](#IERC777Sender).
+This function may be called directly by the gateway.
-Emits a [`IERC777.Burned`](#IERC777-Burned-address-address-uint256-bytes-bytes-) event.
+
+
-Requirements
+
-- `account` cannot be the zero address.
-- `account` must have at least `amount` tokens.
-- the caller must be an operator for `account`.
+
+```solidity
+import "@openzeppelin/contracts/interfaces/draft-IERC7802.sol";
+```
-Emitted when `amount` tokens are created by `operator` and assigned to `to`.
+
+
Functions
+
+- [crosschainMint(_to, _amount)](#IERC7802-crosschainMint-address-uint256-)
+- [crosschainBurn(_from, _amount)](#IERC7802-crosschainBurn-address-uint256-)
+
+IERC165
-Note that some additional user `data` and `operatorData` can be logged in the event.
+- [supportsInterface(interfaceId)](#IERC165-supportsInterface-bytes4-)
+
-Emitted when `operator` destroys `amount` tokens from `account`.
-
-Note that some additional user `data` and `operatorData` can be logged in the event.
-
```solidity
-import "@openzeppelin/contracts/interfaces/IERC777Recipient.sol";
+import "@openzeppelin/contracts/interfaces/draft-IERC7821.sol";
```
-Interface of the ERC-777 Tokens Recipient standard as defined in the ERC.
-
-Accounts can be notified of [`IERC777`](#IERC777) tokens being sent to them by having a
-contract implement this interface (contract holders can be their own
-implementer) and registering it on the
-[ERC-1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
-
-See [`IERC1820Registry`](#IERC1820Registry) and [`IERC1820Implementer`](#IERC1820Implementer).
+Interface for minimal batch executor.
-Called by an [`IERC777`](#IERC777) token contract whenever tokens are being
-moved or created into a registered account (`to`). The type of operation
-is conveyed by `from` being the zero address or not.
-
-This call occurs _after_ the token contract's state is updated, so
-[`IERC777.balanceOf`](#IERC777-balanceOf-address-), etc., can be used to query the post-operation state.
-
-This function may revert to prevent the operation from being executed.
-
-
-
-
-
-
-
-
-## `IERC777Sender`
-
-
-
-
+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
-```solidity
-import "@openzeppelin/contracts/interfaces/IERC777Sender.sol";
-```
+Supported modes:
+- `bytes32(0x01000000000000000000...)`: does not support optional `opData`.
+- `bytes32(0x01000000000078210001...)`: supports optional `opData`.
-Interface of the ERC-777 Tokens Sender standard as defined in the ERC.
+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.
-[`IERC777`](#IERC777) Token holders can be notified of operations performed on their
-tokens by having a contract implement this interface (contract holders can be
-their own implementer) and registering it on the
-[ERC-1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+`opData` may be used to store additional data for authentication,
+paymaster data, gas limits, etc.
-See [`IERC1820Registry`](#IERC1820Registry) and [`IERC1820Implementer`](#IERC1820Implementer).
+For calldata compression efficiency, if a Call.to is `address(0)`,
+it will be replaced with `address(this)`.
-
-
Functions
-
-- [tokensToSend(operator, from, to, amount, userData, operatorData)](#IERC777Sender-tokensToSend-address-address-address-uint256-bytes-bytes-)
-Called by an [`IERC777`](#IERC777) token contract whenever a registered holder's
-(`from`) tokens are about to be moved or destroyed. The type of operation
-is conveyed by `to` being the zero address or not.
-
-This call occurs _before_ the token contract's state is updated, so
-[`IERC777.balanceOf`](#IERC777-balanceOf-address-), etc., can be used to query the pre-operation state.
-
-This function may revert to prevent the operation from being executed.
+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`.
diff --git a/content/contracts/5.x/api/proxy.mdx b/content/contracts/5.x/api/proxy.mdx
index 7e79550b..8f7d0d77 100644
--- a/content/contracts/5.x/api/proxy.mdx
+++ b/content/contracts/5.x/api/proxy.mdx
@@ -1100,6 +1100,166 @@ Must return an address that can be used as a delegate call target.
+
+```solidity
+import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";
+```
+
+This contract is used in conjunction with one or more instances of [`BeaconProxy`](#BeaconProxy) to determine their
+implementation contract, which is where they will delegate all function calls.
+
+An owner is able to change the implementation the beacon points to, thus upgrading the proxies that use this beacon.
+
+
+
+Upgrades the beacon to a new implementation.
+
+Emits an [`UpgradeableBeacon.Upgraded`](#UpgradeableBeacon-Upgraded-address-) event.
+
+Requirements:
+
+- msg.sender must be the owner of the contract.
+- `newImplementation` must be a contract.
+
+
```solidity
-import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
+import "@openzeppelin/contracts/proxy/utils/Initializable.sol";
```
-An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an
-[`ERC1967Proxy`](#ERC1967Proxy), when this contract is set as the implementation behind such a proxy.
+This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed
+behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an
+external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer
+function so it can only be called once. The [`Initializable.initializer`](#Initializable-initializer--) modifier provided by this contract will have this effect.
-A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is
-reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing
-`UUPSUpgradeable` with a custom implementation of upgrades.
+The initialization functions use a version number. Once a version number is used, it is consumed and cannot be
+reused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps in
+case an upgrade adds a module that needs to be initialized.
-The [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-) function must be overridden to include access restriction to the upgrade mechanism.
+For example:
-@custom:stateless
+[.hljs-theme-light.nopadding]
+```solidity
+contract MyToken is ERC20Upgradeable {
+ function initialize() initializer public {
+ __ERC20_init("MyToken", "MTK");
+ }
+}
+
+contract MyTokenV2 is MyToken, ERC20PermitUpgradeable {
+ function initializeV2() reinitializer(2) public {
+ __ERC20Permit_init("MyToken");
+ }
+}
+```
+
+
+To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as
+possible by providing the encoded function call as the `_data` argument to [`ERC1967Proxy.constructor`](#ERC1967Proxy-constructor-address-bytes-).
+
+
+
+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.
+
+
+[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
+the [`Initializable._disableInitializers`](#Initializable-_disableInitializers--) function in the constructor to automatically lock it when it is deployed:
+
+[.hljs-theme-light.nopadding]
+```
+/// @custom:oz-upgrades-unsafe-allow constructor
+constructor() {
+ _disableInitializers();
+}
+```
-Check that the execution is being performed through a delegatecall call and that the execution context is
-a proxy contract with an implementation (as defined in ERC-1967) pointing to self. This should only be the case
-for UUPS and transparent proxies that are using the current contract as their implementation. Execution of a
-function through ERC-1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed to
-fail.
+A modifier that defines a protected initializer function that can be invoked at most once. In its scope,
+`onlyInitializing` functions can be used to initialize parent contracts.
+
+Similar to `reinitializer(1)`, except that in the context of a constructor an `initializer` may be invoked any
+number of times. This behavior in the constructor can be useful during testing and is not expected to be used in
+production.
+
+Emits an [`Initializable.Initialized`](#Initializable-Initialized-uint64-) event.
-Check that the execution is not being performed through a delegate call. This allows a function to be
-callable on the implementing contract but not through proxies.
+A modifier that defines a protected reinitializer function that can be invoked at most once, and only if the
+contract hasn't been initialized to a greater version before. In its scope, `onlyInitializing` functions can be
+used to initialize parent contracts.
+
+A reinitializer may be used after the original initialization step. This is essential to configure modules that
+are added through upgrades and that require initialization.
+
+When `version` is 1, this modifier is similar to `initializer`, except that functions marked with `reinitializer`
+cannot be nested. If one is invoked in the context of another, execution will revert.
+
+Note that versions can jump in increments greater than 1; this implies that if multiple reinitializers coexist in
+a contract, executing them in the right order is up to the developer or operator.
+
+
+Setting the version to 2**64 - 1 will prevent any future reinitialization.
+
+
+Emits an [`Initializable.Initialized`](#Initializable-Initialized-uint64-) event.
-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.
+
-
-A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
-bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
-function revert if invoked through a proxy. This is guaranteed by the `notDelegated` modifier.
-
+Modifier to protect an initialization function so that it can only be invoked by functions with the
+[`Initializable.initializer`](#Initializable-initializer--) and [`Initializable.reinitializer`](#Initializable-reinitializer-uint64-) modifiers, directly or indirectly.
-Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
-encoded in `data`.
+Reverts if the contract is not in an initializing state. See [`Initializable.onlyInitializing`](#Initializable-onlyInitializing--).
-Calls [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-).
+
+
-Emits an [`UpgradeableBeacon.Upgraded`](#UpgradeableBeacon-Upgraded-address-) event.
+
+
+
+
+Locks the contract, preventing any future reinitialization. This cannot be part of an initializer call.
+Calling this in the constructor of a contract will prevent that contract from being initialized or reinitialized
+to any version. It is recommended to use this to lock implementation contracts that are designed to be called
+through proxies.
+
+Emits an [`Initializable.Initialized`](#Initializable-Initialized-uint64-) event the first time it is successfully executed.
-Reverts if the execution is not performed via delegatecall or the execution
-context is not of a proxy with an ERC-1967 compliant implementation pointing to self.
+Returns the highest version that has been initialized. See [`Initializable.reinitializer`](#Initializable-reinitializer-uint64-).
-Reverts if the execution is performed via delegatecall.
-See [`UUPSUpgradeable.notDelegated`](#UUPSUpgradeable-notDelegated--).
+Returns `true` if the contract is currently initializing. See [`Initializable.onlyInitializing`](#Initializable-onlyInitializing--).
-Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by
-[`ERC1967Utils.upgradeToAndCall`](#ERC1967Utils-upgradeToAndCall-address-bytes-).
-
-Normally, this function will use an [access control](/contracts/5.x/api/access) modifier such as [`Ownable.onlyOwner`](/contracts/5.x/api/access#Ownable-onlyOwner--).
+Pointer to storage slot. Allows integrators to override it with a custom storage location.
-```solidity
-function _authorizeUpgrade(address) internal onlyOwner {}
-```
+
+Consider following the ERC-7201 formula to derive storage locations.
+
-The version of the upgrade interface of the contract. If this getter is missing, both `upgradeTo(address)`
-and `upgradeToAndCall(address,bytes)` are present, and `upgradeTo` must be used if no function should be called,
-while `upgradeToAndCall` will invoke the `receive` function if the second argument is the empty byte string.
-If the getter returns `"5.0.0"`, only `upgradeToAndCall(address,bytes)` is present, and the second argument must
-be the empty byte string if no function should be called, making it impossible to invoke the `receive` function
-during an upgrade.
+Triggered when the contract has been initialized or reinitialized.
```solidity
-import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";
+import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
```
-This contract is used in conjunction with one or more instances of [`BeaconProxy`](#BeaconProxy) to determine their
-implementation contract, which is where they will delegate all function calls.
+An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an
+[`ERC1967Proxy`](#ERC1967Proxy), when this contract is set as the implementation behind such a proxy.
-An owner is able to change the implementation the beacon points to, thus upgrading the proxies that use this beacon.
+A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is
+reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing
+`UUPSUpgradeable` with a custom implementation of upgrades.
-
-
Functions
-
-- [constructor(implementation_, initialOwner)](#UpgradeableBeacon-constructor-address-address-)
-- [implementation()](#UpgradeableBeacon-implementation--)
-- [upgradeTo(newImplementation)](#UpgradeableBeacon-upgradeTo-address-)
-
-Ownable
+The [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-) function must be overridden to include access restriction to the upgrade mechanism.
-- [owner()](#Ownable-owner--)
-- [_checkOwner()](#Ownable-_checkOwner--)
-- [renounceOwnership()](#Ownable-renounceOwnership--)
-- [transferOwnership(newOwner)](#Ownable-transferOwnership-address-)
-- [_transferOwnership(newOwner)](#Ownable-_transferOwnership-address-)
+@custom:stateless
-
+
-Sets the address of the initial implementation, and the initial owner who can upgrade the beacon.
+Check that the execution is being performed through a delegatecall call and that the execution context is
+a proxy contract with an implementation (as defined in ERC-1967) pointing to self. This should only be the case
+for UUPS and transparent proxies that are using the current contract as their implementation. Execution of a
+function through ERC-1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed to
+fail.
-Returns the current implementation address.
+Check that the execution is not being performed through a delegate call. This allows a function to be
+callable on the implementing contract but not through proxies.
-Upgrades the beacon to a new implementation.
-
-Emits an [`UpgradeableBeacon.Upgraded`](#UpgradeableBeacon-Upgraded-address-) event.
-
-Requirements:
-
-- msg.sender must be the owner of the contract.
-- `newImplementation` must be a contract.
-
-
-
-```solidity
-import "@openzeppelin/contracts/proxy/utils/Initializable.sol";
-```
-
-This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed
-behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an
-external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer
-function so it can only be called once. The [`Initializable.initializer`](#Initializable-initializer--) modifier provided by this contract will have this effect.
-
-The initialization functions use a version number. Once a version number is used, it is consumed and cannot be
-reused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps in
-case an upgrade adds a module that needs to be initialized.
-
-For example:
-
-[.hljs-theme-light.nopadding]
-```solidity
-contract MyToken is ERC20Upgradeable {
- function initialize() initializer public {
- __ERC20_init("MyToken", "MTK");
- }
-}
-
-contract MyTokenV2 is MyToken, ERC20PermitUpgradeable {
- function initializeV2() reinitializer(2) public {
- __ERC20Permit_init("MyToken");
- }
-}
-```
-
-
-To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as
-possible by providing the encoded function call as the `_data` argument to [`ERC1967Proxy.constructor`](#ERC1967Proxy-constructor-address-bytes-).
-
-
-
-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.
-
-
-[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
-the [`Initializable._disableInitializers`](#Initializable-_disableInitializers--) function in the constructor to automatically lock it when it is deployed:
-
-[.hljs-theme-light.nopadding]
-```
-/// @custom:oz-upgrades-unsafe-allow constructor
-constructor() {
- _disableInitializers();
-}
-```
-
-
-
-A modifier that defines a protected initializer function that can be invoked at most once. In its scope,
-`onlyInitializing` functions can be used to initialize parent contracts.
-
-Similar to `reinitializer(1)`, except that in the context of a constructor an `initializer` may be invoked any
-number of times. This behavior in the constructor can be useful during testing and is not expected to be used in
-production.
-
-Emits an [`Initializable.Initialized`](#Initializable-Initialized-uint64-) event.
-
-
-
-A modifier that defines a protected reinitializer function that can be invoked at most once, and only if the
-contract hasn't been initialized to a greater version before. In its scope, `onlyInitializing` functions can be
-used to initialize parent contracts.
-
-A reinitializer may be used after the original initialization step. This is essential to configure modules that
-are added through upgrades and that require initialization.
-
-When `version` is 1, this modifier is similar to `initializer`, except that functions marked with `reinitializer`
-cannot be nested. If one is invoked in the context of another, execution will revert.
-
-Note that versions can jump in increments greater than 1; this implies that if multiple reinitializers coexist in
-a contract, executing them in the right order is up to the developer or operator.
+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.
-Setting the version to 2**64 - 1 will prevent any future reinitialization.
+A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
+bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
+function revert if invoked through a proxy. This is guaranteed by the `notDelegated` modifier.
-Emits an [`Initializable.Initialized`](#Initializable-Initialized-uint64-) event.
-
-Modifier to protect an initialization function so that it can only be invoked by functions with the
-[`Initializable.initializer`](#Initializable-initializer--) and [`Initializable.reinitializer`](#Initializable-reinitializer-uint64-) modifiers, directly or indirectly.
-
-
-
-
-
+Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
+encoded in `data`.
-
+Calls [`UUPSUpgradeable._authorizeUpgrade`](#UUPSUpgradeable-_authorizeUpgrade-address-).
-Reverts if the contract is not in an initializing state. See [`Initializable.onlyInitializing`](#Initializable-onlyInitializing--).
+Emits an [`UpgradeableBeacon.Upgraded`](#UpgradeableBeacon-Upgraded-address-) event.
-Locks the contract, preventing any future reinitialization. This cannot be part of an initializer call.
-Calling this in the constructor of a contract will prevent that contract from being initialized or reinitialized
-to any version. It is recommended to use this to lock implementation contracts that are designed to be called
-through proxies.
-
-Emits an [`Initializable.Initialized`](#Initializable-Initialized-uint64-) event the first time it is successfully executed.
+Reverts if the execution is not performed via delegatecall or the execution
+context is not of a proxy with an ERC-1967 compliant implementation pointing to self.
-Returns the highest version that has been initialized. See [`Initializable.reinitializer`](#Initializable-reinitializer-uint64-).
+Reverts if the execution is performed via delegatecall.
+See [`UUPSUpgradeable.notDelegated`](#UUPSUpgradeable-notDelegated--).
+Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by
+[`ERC1967Utils.upgradeToAndCall`](#ERC1967Utils-upgradeToAndCall-address-bytes-).
-Pointer to storage slot. Allows integrators to override it with a custom storage location.
+Normally, this function will use an [access control](/contracts/5.x/api/access) modifier such as [`Ownable.onlyOwner`](/contracts/5.x/api/access#Ownable-onlyOwner--).
-
-Consider following the ERC-7201 formula to derive storage locations.
-
+```solidity
+function _authorizeUpgrade(address) internal onlyOwner {}
+```
-Triggered when the contract has been initialized or reinitialized.
+The version of the upgrade interface of the contract. If this getter is missing, both `upgradeTo(address)`
+and `upgradeToAndCall(address,bytes)` are present, and `upgradeTo` must be used if no function should be called,
+while `upgradeToAndCall` will invoke the `receive` function if the second argument is the empty byte string.
+If the getter returns `"5.0.0"`, only `upgradeToAndCall(address,bytes)` is present, and the second argument must
+be the empty byte string if no function should be called, making it impossible to invoke the `receive` function
+during an upgrade.
-The contract is not initializing.
+The storage `slot` is unsupported as a UUID.
diff --git a/content/contracts/5.x/api/token/ERC20.mdx b/content/contracts/5.x/api/token/ERC20.mdx
index 92bb6555..4c9d8b45 100644
--- a/content/contracts/5.x/api/token/ERC20.mdx
+++ b/content/contracts/5.x/api/token/ERC20.mdx
@@ -775,63 +775,38 @@ a call to [`ERC20.approve`](#ERC20-approve-address-uint256-). `value` is the new
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Crosschain.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC1363.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).
+Extension of [`ERC20`](#ERC20) tokens that adds support for code execution after transfers and approvals
+on recipient contracts. Calls after transfers are enabled through the [`ERC1363.transferAndCall`](#ERC1363-transferAndCall-address-uint256-bytes-) and
+[`ERC1363.transferFromAndCall`](#ERC1363-transferFromAndCall-address-address-uint256-bytes-) methods while calls after approvals can be made with [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-)
-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.
+_Available since v5.1._
-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.
+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.
-"Locking" tokens is achieved through burning
+Moves a `value` amount of tokens from the caller's account to `to`
+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`](/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`).
-
+
-
_onReceive(address to, uint256 amount)
+
transferAndCall(address to, uint256 value, bytes data) → bool
-"Unlocking" tokens is achieved through minting
+Variant of [`ERC1363.transferAndCall`](#ERC1363-transferAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with
+no specified format.
-```solidity
-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 [`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,
-[`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.
-
+Moves a `value` amount of tokens from `from` to `to` using the allowance mechanism
+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.
-
-
Functions
-
-- [maxFlashLoan(token)](#ERC20FlashMint-maxFlashLoan-address-)
-- [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-)
-
-ERC20
+Requirements:
-- [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-)
+- The target has code (i.e. is a contract).
+- 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`).
-
-Returns the maximum amount of tokens available for loan.
+Sets a `value` amount of tokens as the allowance of `spender` over the
+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.
-
-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.
-
+Requirements:
+
+- The target has code (i.e. is a contract).
+- 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`).
-Returns the fee applied when doing flash loans. This function calls
-the [`ERC20FlashMint._flashFee`](#ERC20FlashMint-_flashFee-address-uint256-) function which returns the fee applied when doing flash
-loans.
+Variant of [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with
+no specified format.
-Returns the fee applied when doing flash loans. By default this
-implementation has 0 fees. This function can be overloaded to make
-the flash loan mechanism deflationary.
+Indicates a failure within the [`ERC20.transfer`](#ERC20-transfer-address-uint256-) part of a transferAndCall operation.
-Returns the receiver address of the flash fee. By default this
-implementation returns the address(0) which means the fee amount will be burnt.
-This function can be overloaded to change the fee receiver.
+Indicates a failure within the [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-) part of a transferFromAndCall operation.
-Performs a flash loan. New tokens are minted and sent to the
-`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.
+Indicates a failure within the [`ERC20.approve`](#ERC20-approve-address-uint256-) part of a approveAndCall operation.
+
+```solidity
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
+```
+
+Extension of [`ERC20`](#ERC20) that allows token holders to destroy both their own
+tokens and those that they have an allowance for, in a way that can be
+recognized off-chain (via event analysis).
+
+
-The requested loan exceeds the max loan value for `token`.
+Destroys a `value` amount of tokens from the caller.
+
+See [`ERC20._burn`](#ERC20-_burn-address-uint256-).
-The receiver of a flashloan is not a valid [`IERC3156FlashBorrower.onFlashLoan`](/contracts/5.x/api/interfaces#IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-) implementer.
+Destroys a `value` amount of tokens from `account`, deducting from
+the caller's allowance.
+
+See [`ERC20._burn`](#ERC20-_burn-address-uint256-) and [`ERC20.allowance`](#ERC20-allowance-address-address-).
+
+Requirements:
+
+- the caller must have allowance for ``accounts``'s tokens of at least
+`value`.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol";
```
-Implementation of the ERC-20 Permit extension allowing approvals to be made via signatures, as defined in
-[ERC-2612](https://eips.ethereum.org/EIPS/eip-2612).
-
-Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) method, which can be used to change an account's ERC-20 allowance (see [`IERC20.allowance`](#IERC20-allowance-address-address-)) by
-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.
+Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens.
Functions
-- [constructor(name)](#ERC20Permit-constructor-string-)
-- [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
-
-- [_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--)
-
-
+- [constructor(cap_)](#ERC20Capped-constructor-uint256-)
+- [cap()](#ERC20Capped-cap--)
+- [_update(from, to, value)](#ERC20Capped-_update-address-address-uint256-)
ERC20
@@ -1267,7 +1229,6 @@ need to send a transaction, and thus is not required to hold Ether at all.
- [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-)
@@ -1282,12 +1243,6 @@ need to send a transaction, and thus is not required to hold Ether at all.
Events
-IERC5267
-
-- [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--)
-
-
-IERC20
- [Transfer(from, to, value)](#IERC20-Transfer-address-address-uint256-)
@@ -1300,14 +1255,8 @@ need to send a transaction, and thus is not required to hold Ether at all.
Errors
-- [ERC2612ExpiredSignature(deadline)](#ERC20Permit-ERC2612ExpiredSignature-uint256-)
-- [ERC2612InvalidSigner(signer, owner)](#ERC20Permit-ERC2612InvalidSigner-address-address-)
-
-Nonces
-
-- [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-)
-
-
+- [ERC20ExceededCap(increasedSupply, cap)](#ERC20Capped-ERC20ExceededCap-uint256-uint256-)
+- [ERC20InvalidCap(cap)](#ERC20Capped-ERC20InvalidCap-uint256-)
IERC20Errors
@@ -1322,212 +1271,151 @@ need to send a transaction, and thus is not required to hold Ether at all.
-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.
+Sets the value of the `cap`. This value is immutable, it can only be
+set once during construction.
-Sets `value` as the allowance of `spender` over ``owner``'s tokens,
-given ``owner``'s signed approval.
-
-
-The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related to transaction
-ordering also applies here.
-
-
-Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
-
-Requirements:
-
-- `spender` cannot be the zero address.
-- `deadline` must be a timestamp in the future.
-- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
-over the EIP712-formatted function arguments.
-- the signature must use ``owner``'s current nonce (see [`ERC20Permit.nonces`](#ERC20Permit-nonces-address-)).
-
-For more information on the signature format, see the
-[relevant EIP
-section](https://eips.ethereum.org/EIPS/eip-2612#specification).
-
-
-See Security Considerations above.
-
+Returns the cap on the token's total supply.
-Returns the current nonce for `owner`. This value must be
-included whenever a signature is generated for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-).
-
-Every successful call to [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) increases ``owner``'s nonce by one. This
-prevents a signature from being used multiple times.
-
-
+Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from`
+(or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding
+this function.
-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).
+Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Crosschain.sol";
```
-Extension of ERC-20 to support Compound-like voting and delegation. This version is more generic than Compound's,
-and supports token supply up to 2^208^ - 1, while COMP is limited to 2^96^ - 1.
-
-
-This contract does not provide interface compatibility with Compound's COMP token.
-
+Extension of [`ERC20`](#ERC20) that makes it natively cross-chain using the ERC-7786 based [`BridgeFungible`](/contracts/5.x/api/crosschain#BridgeFungible).
-This extension keeps a history (checkpoints) of each account's vote power. Vote power can be delegated either
-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-).
+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).
-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.
+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
-- [_maxSupply()](#ERC20Votes-_maxSupply--)
-- [_update(from, to, value)](#ERC20Votes-_update-address-address-uint256-)
-- [_getVotingUnits(account)](#ERC20Votes-_getVotingUnits-address-)
-- [numCheckpoints(account)](#ERC20Votes-numCheckpoints-address-)
-- [checkpoints(account, pos)](#ERC20Votes-checkpoints-address-uint32-)
+- [crosschainTransferFrom(from, to, amount)](#ERC20Crosschain-crosschainTransferFrom-address-bytes-uint256-)
+- [_onSend(from, amount)](#ERC20Crosschain-_onSend-address-uint256-)
+- [_onReceive(to, amount)](#ERC20Crosschain-_onReceive-address-uint256-)
-Votes
+BridgeFungible
-- [clock()](#Votes-clock--)
-- [CLOCK_MODE()](#Votes-CLOCK_MODE--)
-- [_validateTimepoint(timepoint)](#Votes-_validateTimepoint-uint256-)
-- [getVotes(account)](#Votes-getVotes-address-)
-- [getPastVotes(account, timepoint)](#Votes-getPastVotes-address-uint256-)
-- [getPastTotalSupply(timepoint)](#Votes-getPastTotalSupply-uint256-)
-- [_getTotalSupply()](#Votes-_getTotalSupply--)
-- [delegates(account)](#Votes-delegates-address-)
-- [delegate(delegatee)](#Votes-delegate-address-)
-- [delegateBySig(delegatee, nonce, expiry, v, r, s)](#Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-)
-- [_delegate(account, delegatee)](#Votes-_delegate-address-address-)
-- [_transferVotingUnits(from, to, amount)](#Votes-_transferVotingUnits-address-address-uint256-)
-- [_moveDelegateVotes(from, to, amount)](#Votes-_moveDelegateVotes-address-address-uint256-)
-- [_numCheckpoints(account)](#Votes-_numCheckpoints-address-)
-- [_checkpoints(account, pos)](#Votes-_checkpoints-address-uint32-)
+- [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-)
-Nonces
+CrosschainLinked
-- [nonces(owner)](#Nonces-nonces-address-)
-- [_useNonce(owner)](#Nonces-_useNonce-address-)
-- [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-)
+- [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-)
-EIP712
+ERC7786Recipient
-- [_domainSeparatorV4()](#EIP712-_domainSeparatorV4--)
-- [_hashTypedDataV4(structHash)](#EIP712-_hashTypedDataV4-bytes32-)
-- [eip712Domain()](#EIP712-eip712Domain--)
-- [_EIP712Name()](#EIP712-_EIP712Name--)
-- [_EIP712Version()](#EIP712-_EIP712Version--)
+- [receiveMessage(receiveId, sender, payload)](#ERC7786Recipient-receiveMessage-bytes32-bytes-bytes-)
@@ -1543,6 +1431,7 @@ requires users to delegate to themselves in order to activate checkpoints and ha
- [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-)
@@ -1557,16 +1446,16 @@ requires users to delegate to themselves in order to activate checkpoints and ha
Events
-IVotes
+BridgeFungible
-- [DelegateChanged(delegator, fromDelegate, toDelegate)](#IVotes-DelegateChanged-address-address-address-)
-- [DelegateVotesChanged(delegate, previousVotes, newVotes)](#IVotes-DelegateVotesChanged-address-uint256-uint256-)
+- [CrosschainFungibleTransferSent(sendId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferSent-bytes32-address-bytes-uint256-)
+- [CrosschainFungibleTransferReceived(receiveId, from, to, amount)](#BridgeFungible-CrosschainFungibleTransferReceived-bytes32-bytes-address-uint256-)
-IERC5267
+CrosschainLinked
-- [EIP712DomainChanged()](#IERC5267-EIP712DomainChanged--)
+- [LinkRegistered(gateway, counterpart)](#CrosschainLinked-LinkRegistered-address-bytes-)
@@ -1582,24 +1471,16 @@ requires users to delegate to themselves in order to activate checkpoints and ha
Errors
-- [ERC20ExceededSafeSupply(increasedSupply, cap)](#ERC20Votes-ERC20ExceededSafeSupply-uint256-uint256-)
-
-Votes
-
-- [ERC6372InconsistentClock()](#Votes-ERC6372InconsistentClock--)
-- [ERC5805FutureLookup(timepoint, clock)](#Votes-ERC5805FutureLookup-uint256-uint48-)
-
-
-IVotes
+CrosschainLinked
-- [VotesExpiredSignature(expiry)](#IVotes-VotesExpiredSignature-uint256-)
+- [LinkAlreadyRegistered(chain)](#CrosschainLinked-LinkAlreadyRegistered-bytes-)
-Nonces
+ERC7786Recipient
-- [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-uint256-)
+- [ERC7786RecipientUnauthorizedGateway(gateway, sender)](#ERC7786Recipient-ERC7786RecipientUnauthorizedGateway-address-bytes-)
@@ -1616,165 +1497,99 @@ requires users to delegate to themselves in order to activate checkpoints and ha
-
+
-
_maxSupply() → uint256
+
crosschainTransferFrom(address from, bytes to, uint256 amount) → bytes32
-Maximum token supply. Defaults to `type(uint208).max` (2^208^ - 1).
-
-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.
+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.
-Move voting power when tokens are transferred.
-
-Emits a [`IVotes.DelegateVotesChanged`](/contracts/5.x/api/governance#IVotes-DelegateVotesChanged-address-uint256-uint256-) event.
+"Locking" tokens is achieved through burning
-
-Returns the voting units of an `account`.
-
-
-Overriding this function may compromise the internal vote accounting.
-`ERC20Votes` assumes tokens map to voting units 1:1 and this is not easy to change.
-
-
-
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Wrapper.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20FlashMint.sol";
```
-Extension of the ERC-20 token contract to support token wrapping.
+Implementation of the ERC-3156 Flash loans extension, as defined in
+[ERC-3156](https://eips.ethereum.org/EIPS/eip-3156).
-Users can deposit and withdraw "underlying tokens" and receive a matching number of "wrapped tokens". This is useful
-in conjunction with other modules. For example, combining this wrapping mechanism with [`ERC20Votes`](#ERC20Votes) will allow the
-wrapping of an existing "basic" ERC-20 into a governance token.
+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-).
-
-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.
+
+When this extension is used along with the [`ERC20Capped`](#ERC20Capped) or [`ERC20Votes`](#ERC20Votes) extensions,
+[`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.
-- [ERC20InvalidUnderlying(token)](#ERC20Wrapper-ERC20InvalidUnderlying-address-)
+- [ERC3156UnsupportedToken(token)](#ERC20FlashMint-ERC3156UnsupportedToken-address-)
+- [ERC3156ExceededMaxLoan(maxLoan)](#ERC20FlashMint-ERC3156ExceededMaxLoan-uint256-)
+- [ERC3156InvalidReceiver(receiver)](#ERC20FlashMint-ERC3156InvalidReceiver-address-)
IERC20Errors
@@ -1824,222 +1641,208 @@ for recovering value accrued to the wrapper.
+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.
+
+
+Returns the fee applied when doing flash loans. This function calls
+the [`ERC20FlashMint._flashFee`](#ERC20FlashMint-_flashFee-address-uint256-) function which returns the fee applied when doing flash
+loans.
+
-Returns the address of the underlying ERC-20 token that is being wrapped.
+Returns the fee applied when doing flash loans. By default this
+implementation has 0 fees. This function can be overloaded to make
+the flash loan mechanism deflationary.
-Allow a user to deposit underlying tokens and mint the corresponding number of wrapped tokens.
+Returns the receiver address of the flash fee. By default this
+implementation returns the address(0) which means the fee amount will be burnt.
+This function can be overloaded to change the fee receiver.
-Allow a user to burn a number of wrapped tokens and withdraw the corresponding number of underlying tokens.
+Performs a flash loan. New tokens are minted and sent to the
+`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.
-Mint wrapped token to cover any underlyingTokens that would have been transferred by mistake or acquired from
-rebasing mechanisms. Internal function that can be exposed with access control if desired.
+The loan token is not valid.
+
+The receiver of a flashloan is not a valid [`IERC3156FlashBorrower.onFlashLoan`](/contracts/5.x/api/interfaces#IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-) implementer.
+
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
```
-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 [`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.
-
-[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
-similarly be affected by slippage. Users can protect against this attack as well as unexpected slippage in general by
-verifying the amount received is as expected, using a wrapper that performs these checks such as
-[ERC4626Router](https://github.com/fei-protocol/ERC4626#erc4626router-and-base).
-
-Since v4.9, this implementation introduces configurable virtual assets and shares to help developers mitigate that risk.
-The `_decimalsOffset()` corresponds to an offset in the decimal representation between the underlying asset's decimals
-and the vault decimals. This offset also determines the rate of virtual shares to virtual assets in the vault, which
-itself determines the initial exchange rate. While not fully preventing the attack, analysis shows that the default
-offset (0) makes it non-profitable even if an attacker is able to capture value from multiple user deposits, as a result
-of the value being captured by the virtual shares (out of the attacker's donation) matching the attacker's expected gains.
-With a larger offset, the attack becomes orders of magnitude more expensive than it is profitable. More details about the
-underlying math can be found [here](/contracts/5.x/erc4626#inflation-attack).
-
-The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued
-to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets
-will cause the first user to exit to experience reduced losses in detriment to the last users that will experience
-bigger losses. Developers willing to revert back to the pre-v4.9 behavior just need to override the
-`_convertToShares` and `_convertToAssets` functions.
-
-To learn more, check out our [ERC-4626 guide](/contracts/5.x/erc4626).
-#### [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 [`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.
+ERC-20 token with pausable token transfers, minting and burning.
-* [`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.
+Useful for scenarios such as preventing trades until the end of an evaluation
+period, or having an emergency switch for freezing all token transfers in the
+event of a large bug.
-* 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.
+
+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`](/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.
+
-Set the underlying asset contract. This must be an ERC20-compatible contract (ERC-20 or ERC-777).
+See [`ERC20._update`](#ERC20-_update-address-address-uint256-).
+
+Requirements:
+
+- the contract must not be paused.
-Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This
-"original" value is cached during construction of the vault contract. If this read operation fails (e.g., the
-asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals.
+## `ERC20Permit`
-See [`IERC20Metadata.decimals`](#IERC20Metadata-decimals--).
+
+
+
-
+Implementation of the ERC-20 Permit extension allowing approvals to be made via signatures, as defined in
+[ERC-2612](https://eips.ethereum.org/EIPS/eip-2612).
-Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.
+Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) method, which can be used to change an account's ERC-20 allowance (see [`IERC20.allowance`](#IERC20-allowance-address-address-)) by
+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.
-- MUST be an ERC-20 token contract.
-- MUST NOT revert.
+
-Returns the total amount of the underlying asset that is “managed” by Vault.
+
+
Errors
+
+- [ERC2612ExpiredSignature(deadline)](#ERC20Permit-ERC2612ExpiredSignature-uint256-)
+- [ERC2612InvalidSigner(signer, owner)](#ERC20Permit-ERC2612InvalidSigner-address-address-)
+
+Nonces
-- SHOULD include any compounding that occurs from yield.
-- MUST be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT revert.
+- [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-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-)
+
-Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal
-scenario where all the conditions are met.
-
-- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT show any variations depending on the caller.
-- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
-- MUST NOT revert.
+Initializes the [`EIP712`](/contracts/5.x/api/utils/cryptography#EIP712) domain separator using the `name` parameter, and setting `version` to `"1"`.
-
-This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
-“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
-from.
-
+It's a good idea to use the same `name` that is defined as the ERC-20 token name.
-Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal
-scenario where all the conditions are met.
+Sets `value` as the allowance of `spender` over ``owner``'s tokens,
+given ``owner``'s signed approval.
-- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
-- MUST NOT show any variations depending on the caller.
-- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
-- MUST NOT revert.
+
+The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related to transaction
+ordering also applies here.
+
-
-This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
-“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
-from.
+Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
+
+Requirements:
+
+- `spender` cannot be the zero address.
+- `deadline` must be a timestamp in the future.
+- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
+over the EIP712-formatted function arguments.
+- the signature must use ``owner``'s current nonce (see [`ERC20Permit.nonces`](#ERC20Permit-nonces-address-)).
+
+For more information on the signature format, see the
+[relevant EIP
+section](https://eips.ethereum.org/EIPS/eip-2612#specification).
+
+
+See Security Considerations above.
-Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver,
-through a deposit call.
+Returns the current nonce for `owner`. This value must be
+included whenever a signature is generated for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-).
-- MUST return a limited value if receiver is subject to some deposit limit.
-- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited.
-- MUST NOT revert.
+Every successful call to [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) increases ``owner``'s nonce by one. This
+prevents a signature from being used multiple times.
-Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call.
-- MUST return a limited value if receiver is subject to some mint limit.
-- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted.
-- MUST NOT revert.
+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).
-Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the
-Vault, through a withdraw call.
-
-- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
-- MUST NOT revert.
+Permit deadline has expired.
-Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault,
-through a redeem call.
-
-- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
-- MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock.
-- MUST NOT revert.
+Mismatched signature.
-Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given
-current on-chain conditions.
+```solidity
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol";
+```
-- MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit
- call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called
- in the same transaction.
-- MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the
- deposit would be accepted, regardless if the user has enough tokens approved, etc.
-- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
-- MUST NOT revert.
+Extension of ERC-20 to support Compound-like voting and delegation. This version is more generic than Compound's,
+and supports token supply up to 2^208^ - 1, while COMP is limited to 2^96^ - 1.
-any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by depositing.
+This contract does not provide interface compatibility with Compound's COMP token.
-
-
+This extension keeps a history (checkpoints) of each account's vote power. Vote power can be delegated either
+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.
-
+- [_maxSupply()](#ERC20Votes-_maxSupply--)
+- [_update(from, to, value)](#ERC20Votes-_update-address-address-uint256-)
+- [_getVotingUnits(account)](#ERC20Votes-_getVotingUnits-address-)
+- [numCheckpoints(account)](#ERC20Votes-numCheckpoints-address-)
+- [checkpoints(account, pos)](#ERC20Votes-checkpoints-address-uint32-)
+
+Votes
-Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given
-current on-chain conditions.
+- [clock()](#Votes-clock--)
+- [CLOCK_MODE()](#Votes-CLOCK_MODE--)
+- [_validateTimepoint(timepoint)](#Votes-_validateTimepoint-uint256-)
+- [getVotes(account)](#Votes-getVotes-address-)
+- [getPastVotes(account, timepoint)](#Votes-getPastVotes-address-uint256-)
+- [getPastTotalSupply(timepoint)](#Votes-getPastTotalSupply-uint256-)
+- [_getTotalSupply()](#Votes-_getTotalSupply--)
+- [delegates(account)](#Votes-delegates-address-)
+- [delegate(delegatee)](#Votes-delegate-address-)
+- [delegateBySig(delegatee, nonce, expiry, v, r, s)](#Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-)
+- [_delegate(account, delegatee)](#Votes-_delegate-address-address-)
+- [_transferVotingUnits(from, to, amount)](#Votes-_transferVotingUnits-address-address-uint256-)
+- [_moveDelegateVotes(from, to, amount)](#Votes-_moveDelegateVotes-address-address-uint256-)
+- [_numCheckpoints(account)](#Votes-_numCheckpoints-address-)
+- [_checkpoints(account, pos)](#Votes-_checkpoints-address-uint32-)
-- MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call
- in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the
- same transaction.
-- MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint
- would be accepted, regardless if the user has enough tokens approved, etc.
-- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
-- MUST NOT revert.
+
+
+Nonces
-
-any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by minting.
-
+- [nonces(owner)](#Nonces-nonces-address-)
+- [_useNonce(owner)](#Nonces-_useNonce-address-)
+- [_useCheckedNonce(owner, nonce)](#Nonces-_useCheckedNonce-address-uint256-)
-
-Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block,
-given current on-chain conditions.
+
+
Events
+
+
+IVotes
-- MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw
- call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if
- called
- in the same transaction.
-- MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though
- the withdrawal would be accepted, regardless if the user has enough shares, etc.
-- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
-- MUST NOT revert.
+- [DelegateChanged(delegator, fromDelegate, toDelegate)](#IVotes-DelegateChanged-address-address-address-)
+- [DelegateVotesChanged(delegate, previousVotes, newVotes)](#IVotes-DelegateVotesChanged-address-uint256-uint256-)
-
-any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by depositing.
-
+
+
+IERC5267
-
-Allows an on-chain or off-chain user to simulate the effects of their redemption at the current block,
-given current on-chain conditions.
+
+
Errors
+
+- [ERC20ExceededSafeSupply(increasedSupply, cap)](#ERC20Votes-ERC20ExceededSafeSupply-uint256-uint256-)
+
+Votes
-- MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call
- in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the
- same transaction.
-- MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the
- redemption would be accepted, regardless if the user has enough shares, etc.
-- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
-- MUST NOT revert.
+- [ERC6372InconsistentClock()](#Votes-ERC6372InconsistentClock--)
+- [ERC5805FutureLookup(timepoint, clock)](#Votes-ERC5805FutureLookup-uint256-uint48-)
-
-any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in
-share price or some other type of condition, meaning the depositor will lose assets by redeeming.
-
+
+
+IVotes
+
+- [VotesExpiredSignature(expiry)](#IVotes-VotesExpiredSignature-uint256-)
+
+
+
+Nonces
+
+- [InvalidAccountNonce(account, currentNonce)](#Nonces-InvalidAccountNonce-address-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-)
+
+
-Deposit `assets` underlying tokens and send the corresponding number of vault shares (`shares`) to `receiver`.
-
-- MUST emit the Deposit event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- deposit execution, and are accounted for during deposit.
-- MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not
- approving enough underlying tokens to the Vault contract, etc).
+Maximum token supply. Defaults to `type(uint208).max` (2^208^ - 1).
-
-most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
-
+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.
-Mints exactly `shares` vault shares to `receiver` in exchange for `assets` underlying tokens.
-
-- MUST emit the Deposit event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint
- execution, and are accounted for during mint.
-- MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not
- approving enough underlying tokens to the Vault contract, etc).
+Move voting power when tokens are transferred.
-
-most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
-
+Emits a [`IVotes.DelegateVotesChanged`](/contracts/5.x/api/governance#IVotes-DelegateVotesChanged-address-uint256-uint256-) event.
-Burns shares from owner and sends exactly assets of underlying tokens to receiver.
-
-- MUST emit the Withdraw event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- withdraw execution, and are accounted for during withdraw.
-- MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner
- not having enough shares, etc).
+Returns the voting units of an `account`.
-Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
-Those methods should be performed separately.
+
+Overriding this function may compromise the internal vote accounting.
+`ERC20Votes` assumes tokens map to voting units 1:1 and this is not easy to change.
+
-Burns exactly shares from owner and sends assets of underlying tokens to receiver.
-
-- MUST emit the Withdraw event.
-- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
- redeem execution, and are accounted for during redeem.
-- MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner
- not having enough shares, etc).
-
-
-some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
-Those methods should be performed separately.
-
+Get number of checkpoints for `account`.
-Internal conversion function (from shares to assets) with support for rounding direction.
+Total supply cap has been exceeded, introducing a risk of votes overflowing.
-Deposit/mint common workflow.
+```solidity
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Wrapper.sol";
+```
+
+Extension of the ERC-20 token contract to support token wrapping.
+Users can deposit and withdraw "underlying tokens" and receive a matching number of "wrapped tokens". This is useful
+in conjunction with other modules. For example, combining this wrapping mechanism with [`ERC20Votes`](#ERC20Votes) will allow the
+wrapping of an existing "basic" ERC-20 into a governance token.
+
+
+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.
+
+
+
-Performs a transfer in of underlying assets. The default implementation uses `SafeERC20`. Used by [`ERC4626._deposit`](#ERC4626-_deposit-address-address-uint256-uint256-).
-
-Performs a transfer out of underlying assets. The default implementation uses `SafeERC20`. Used by [`ERC4626._withdraw`](#ERC4626-_withdraw-address-address-address-uint256-uint256-).
-
-Attempted to deposit more assets than the max amount for `receiver`.
+Allow a user to deposit underlying tokens and mint the corresponding number of wrapped tokens.
-Attempted to mint more shares than the max amount for `receiver`.
+Allow a user to burn a number of wrapped tokens and withdraw the corresponding number of underlying tokens.
-Attempted to withdraw more assets than the max amount for `owner`.
+Mint wrapped token to cover any underlyingTokens that would have been transferred by mistake or acquired from
+rebasing mechanisms. Internal function that can be exposed with access control if desired.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
```
-Interface for the optional metadata functions from the ERC-20 standard.
+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 [`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.
+
+[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
+similarly be affected by slippage. Users can protect against this attack as well as unexpected slippage in general by
+verifying the amount received is as expected, using a wrapper that performs these checks such as
+[ERC4626Router](https://github.com/fei-protocol/ERC4626#erc4626router-and-base).
+
+Since v4.9, this implementation introduces configurable virtual assets and shares to help developers mitigate that risk.
+The `_decimalsOffset()` corresponds to an offset in the decimal representation between the underlying asset's decimals
+and the vault decimals. This offset also determines the rate of virtual shares to virtual assets in the vault, which
+itself determines the initial exchange rate. While not fully preventing the attack, analysis shows that the default
+offset (0) makes it non-profitable even if an attacker is able to capture value from multiple user deposits, as a result
+of the value being captured by the virtual shares (out of the attacker's donation) matching the attacker's expected gains.
+With a larger offset, the attack becomes orders of magnitude more expensive than it is profitable. More details about the
+underlying math can be found [here](/contracts/5.x/erc4626#inflation-attack).
+
+The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued
+to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets
+will cause the first user to exit to experience reduced losses in detriment to the last users that will experience
+bigger losses. Developers willing to revert back to the pre-v4.9 behavior just need to override the
+`_convertToShares` and `_convertToAssets` functions.
+
+To learn more, check out our [ERC-4626 guide](/contracts/5.x/erc4626).
+#### [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 [`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.
+
+* [`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 [`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.
+
+Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This
+"original" value is cached during construction of the vault contract. If this read operation fails (e.g., the
+asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals.
+
+See [`IERC20Metadata.decimals`](#IERC20Metadata-decimals--).
+
+
-Returns the symbol of the token.
+Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.
+
+- MUST be an ERC-20 token contract.
+- MUST NOT revert.
-Returns the decimals places of the token.
+Returns the total amount of the underlying asset that is “managed” by Vault.
+
+- SHOULD include any compounding that occurs from yield.
+- MUST be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT revert.
-```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Permit.sol";
-```
-
-Interface of the ERC-20 Permit extension allowing approvals to be made via signatures, as defined in
-[ERC-2612](https://eips.ethereum.org/EIPS/eip-2612).
-
-Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) method, which can be used to change an account's ERC-20 allowance (see [`IERC20.allowance`](#IERC20-allowance-address-address-)) by
-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
-
-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
-considered as an intention to spend the allowance in any specific way. The second is that because permits have
-built-in replay protection and can be submitted by anyone, they can be frontrun. A protocol that uses permits should
-take this into consideration and allow a `permit` call to fail. Combining these two aspects, a pattern that may be
-generally recommended is:
-
-```solidity
-function doThingWithPermit(..., uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public {
- try token.permit(msg.sender, address(this), value, deadline, v, r, s) {} catch {}
- doThing(..., value);
-}
-
-function doThing(..., uint256 value) public {
- token.safeTransferFrom(msg.sender, address(this), value);
- ...
-}
-```
+Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal
+scenario where all the conditions are met.
-Observe that: 1) `msg.sender` is used as the owner, leaving no ambiguity as to the signer intent, and 2) the use of
-`try/catch` allows the permit to fail and makes the code tolerant to frontrunning. (See also
-[`SafeERC20.safeTransferFrom`](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-)).
+- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT show any variations depending on the caller.
+- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
+- MUST NOT revert.
-Additionally, note that smart contract wallets (such as Argent or Safe) are not able to produce permit signatures, so
-contracts should have entry points that don't rely on permit.
+
+This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
+“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
+from.
+
-
-Sets `value` as the allowance of `spender` over ``owner``'s tokens,
-given ``owner``'s signed approval.
-
-
-The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related to transaction
-ordering also applies here.
-
-
-Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
-
-Requirements:
-
-- `spender` cannot be the zero address.
-- `deadline` must be a timestamp in the future.
-- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
-over the EIP712-formatted function arguments.
-- the signature must use ``owner``'s current nonce (see [`ERC20Permit.nonces`](#ERC20Permit-nonces-address-)).
+Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal
+scenario where all the conditions are met.
-For more information on the signature format, see the
-[relevant EIP
-section](https://eips.ethereum.org/EIPS/eip-2612#specification).
+- MUST NOT be inclusive of any fees that are charged against assets in the Vault.
+- MUST NOT show any variations depending on the caller.
+- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
+- MUST NOT revert.
-
-See Security Considerations above.
+
+This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
+“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
+from.
-Returns the current nonce for `owner`. This value must be
-included whenever a signature is generated for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-).
+Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver,
+through a deposit call.
-Every successful call to [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) increases ``owner``'s nonce by one. This
-prevents a signature from being used multiple times.
+- MUST return a limited value if receiver is subject to some deposit limit.
+- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited.
+- MUST NOT revert.
-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).
+Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call.
+- MUST return a limited value if receiver is subject to some mint limit.
+- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted.
+- MUST NOT revert.
-## `ERC20TemporaryApproval`
+Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the
+Vault, through a withdraw call.
-
-
-
+- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
+- MUST NOT revert.
+
-```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20TemporaryApproval.sol";
-```
-
-Extension of [`ERC20`](#ERC20) that adds support for temporary allowances following ERC-7674.
-
-
-This is a draft contract. The corresponding ERC is still subject to changes.
-
+
-_Available since v5.1._
+
-- [allowance(owner, spender)](#ERC20TemporaryApproval-allowance-address-address-)
-- [_temporaryAllowance(owner, spender)](#ERC20TemporaryApproval-_temporaryAllowance-address-address-)
-- [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-)
-
-ERC20
+Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault,
+through a redeem call.
-- [name()](#ERC20-name--)
-- [symbol()](#ERC20-symbol--)
-- [decimals()](#ERC20-decimals--)
-- [totalSupply()](#ERC20-totalSupply--)
-- [balanceOf(account)](#ERC20-balanceOf-address-)
-- [transfer(to, value)](#ERC20-transfer-address-uint256-)
-- [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-)
+- MUST return a limited value if owner is subject to some withdrawal limit or timelock.
+- MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock.
+- MUST NOT revert.
-
-
-IERC20Errors
+Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given
+current on-chain conditions.
+
+- MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit
+ call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called
+ in the same transaction.
+- MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the
+ deposit would be accepted, regardless if the user has enough tokens approved, etc.
+- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
+- MUST NOT revert.
-- [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-)
+
+any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by depositing.
+
-
-[`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.
+Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given
+current on-chain conditions.
+
+- MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call
+ in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the
+ same transaction.
+- MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint
+ would be accepted, regardless if the user has enough tokens approved, etc.
+- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
+- MUST NOT revert.
+
+
+any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by minting.
+
-Internal getter for the current temporary allowance that `spender` has over `owner` tokens.
+Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block,
+given current on-chain conditions.
+
+- MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw
+ call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if
+ called
+ in the same transaction.
+- MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though
+ the withdrawal would be accepted, regardless if the user has enough shares, etc.
+- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
+- MUST NOT revert.
+
+
+any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by depositing.
+
-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.
+Allows an on-chain or off-chain user to simulate the effects of their redemption at the current block,
+given current on-chain conditions.
-Requirements:
-- `spender` cannot be the zero address.
+- MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call
+ in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the
+ same transaction.
+- MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the
+ redemption would be accepted, regardless if the user has enough shares, etc.
+- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
+- MUST NOT revert.
-Does NOT emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
+
+any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in
+share price or some other type of condition, meaning the depositor will lose assets by redeeming.
+
-Sets `value` as the temporary allowance of `spender` over the `owner`'s tokens.
-
-This internal function is equivalent to `temporaryApprove`, and can be used to e.g. set automatic allowances
-for certain subsystems, etc.
+Deposit `assets` underlying tokens and send the corresponding number of vault shares (`shares`) to `receiver`.
-Requirements:
-- `owner` cannot be the zero address.
-- `spender` cannot be the zero address.
+- MUST emit the Deposit event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ deposit execution, and are accounted for during deposit.
+- MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not
+ approving enough underlying tokens to the Vault contract, etc).
-Does NOT emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
+
+most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
+
-[`ERC20._spendAllowance`](#ERC20-_spendAllowance-address-address-uint256-) override that consumes the temporary allowance (if any) before eventually falling back
-to consuming the persistent allowance.
+Mints exactly `shares` vault shares to `receiver` in exchange for `assets` underlying tokens.
+
+- MUST emit the Deposit event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint
+ execution, and are accounted for during mint.
+- MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not
+ approving enough underlying tokens to the Vault contract, etc).
+
-This function skips calling `super._spendAllowance` if the temporary allowance
-is enough to cover the spending.
+most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
-```solidity
-import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
-```
+Burns shares from owner and sends exactly assets of underlying tokens to receiver.
-Wrappers around ERC-20 operations that throw on failure (when the token
-contract returns false). Tokens that return no value (and instead revert or
-throw on failure) are also supported, non-reverting calls are assumed to be
-successful.
-To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract,
-which allows you to call the safe operations as `token.safeTransfer(...)`, etc.
+- MUST emit the Withdraw event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ withdraw execution, and are accounted for during withdraw.
+- MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner
+ not having enough shares, etc).
-
-
Functions
-
-- [safeTransfer(token, to, value)](#SafeERC20-safeTransfer-contract-IERC20-address-uint256-)
-- [safeTransferFrom(token, from, to, value)](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-)
-- [trySafeTransfer(token, to, value)](#SafeERC20-trySafeTransfer-contract-IERC20-address-uint256-)
-- [trySafeTransferFrom(token, from, to, value)](#SafeERC20-trySafeTransferFrom-contract-IERC20-address-address-uint256-)
-- [safeIncreaseAllowance(token, spender, value)](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-)
-- [safeDecreaseAllowance(token, spender, requestedDecrease)](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-)
-- [forceApprove(token, spender, value)](#SafeERC20-forceApprove-contract-IERC20-address-uint256-)
-- [transferAndCallRelaxed(token, to, value, data)](#SafeERC20-transferAndCallRelaxed-contract-IERC1363-address-uint256-bytes-)
-- [transferFromAndCallRelaxed(token, from, to, value, data)](#SafeERC20-transferFromAndCallRelaxed-contract-IERC1363-address-address-uint256-bytes-)
-- [approveAndCallRelaxed(token, to, value, data)](#SafeERC20-approveAndCallRelaxed-contract-IERC1363-address-uint256-bytes-)
-
-
+Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
+Those methods should be performed separately.
-
-Transfer `value` amount of `token` from the calling contract to `to`. If `token` returns no value,
-non-reverting calls are assumed to be successful.
+Burns exactly shares from owner and sends assets of underlying tokens to receiver.
+
+- MUST emit the Withdraw event.
+- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
+ redeem execution, and are accounted for during redeem.
+- MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner
+ not having enough shares, etc).
+
+
+some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
+Those methods should be performed separately.
+
-
+
-
safeTransferFrom(contract IERC20 token, address from, address to, uint256 value)
-Transfer `value` amount of `token` from `from` to `to`, spending the approval given by `from` to the
-calling contract. If `token` returns no value, non-reverting calls are assumed to be successful.
+Internal conversion function (from assets to shares) with support for rounding direction.
-
+
-
trySafeTransfer(contract IERC20 token, address to, uint256 value) → bool
-Variant of [`SafeERC20.safeTransfer`](#SafeERC20-safeTransfer-contract-IERC20-address-uint256-) that returns a bool instead of reverting if the operation is not successful.
+Internal conversion function (from shares to assets) with support for rounding direction.
-Variant of [`SafeERC20.safeTransferFrom`](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-) that returns a bool instead of reverting if the operation is not successful.
+Deposit/mint common workflow.
-
-Increase the calling contract's allowance toward `spender` by `value`. If `token` returns no value,
-non-reverting calls are assumed to be successful.
-
-
-If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
-smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
-this function. Performing a [`SafeERC20.safeIncreaseAllowance`](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-) or [`SafeERC20.safeDecreaseAllowance`](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-) operation on a token contract
-that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
-
+#
+
-Decrease the calling contract's allowance toward `spender` by `requestedDecrease`. If `token` returns no
-value, non-reverting calls are assumed to be successful.
-
-
-If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
-smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
-this function. Performing a [`SafeERC20.safeIncreaseAllowance`](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-) or [`SafeERC20.safeDecreaseAllowance`](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-) operation on a token contract
-that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
-
+Performs a transfer in of underlying assets. The default implementation uses `SafeERC20`. Used by [`ERC4626._deposit`](#ERC4626-_deposit-address-address-uint256-uint256-).
-Set the calling contract's allowance toward `spender` to `value`. If `token` returns no value,
-non-reverting calls are assumed to be successful. Meant to be used with tokens that require the approval
-to be set to zero before setting it to a non-zero value, such as USDT.
-
-
-If the token implements ERC-7674, this function will not modify any temporary allowance. This function
-only sets the "standard" allowance. Any temporary allowance will remain active, in addition to the value being
-set here.
-
+Performs a transfer out of underlying assets. The default implementation uses `SafeERC20`. Used by [`ERC4626._withdraw`](#ERC4626-_withdraw-address-address-address-uint256-uint256-).
-
+
-
transferAndCallRelaxed(contract IERC1363 token, address to, uint256 value, bytes data)
-Performs an [`ERC1363`](#ERC1363) transferAndCall, with a fallback to the simple [`ERC20`](#ERC20) transfer if the target has no
-code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that relies on [`ERC1363`](#ERC1363) checks when
-targeting contracts.
-
-Reverts if the returned value is other than `true`.
-
-Performs an [`ERC1363`](#ERC1363) transferFromAndCall, with a fallback to the simple [`ERC20`](#ERC20) transferFrom if the target
-has no code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that relies on [`ERC1363`](#ERC1363) checks when
-targeting contracts.
-
-Reverts if the returned value is other than `true`.
+Attempted to deposit more assets than the max amount for `receiver`.
-
+
-
approveAndCallRelaxed(contract IERC1363 token, address to, uint256 value, bytes data)
-Performs an [`ERC1363`](#ERC1363) approveAndCall, with a fallback to the simple [`ERC20`](#ERC20) approve if the target has no
-code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that rely on [`ERC1363`](#ERC1363) checks when
-targeting contracts.
-
-
-When the recipient address (`to`) has no code (i.e. is an EOA), this function behaves as [`SafeERC20.forceApprove`](#SafeERC20-forceApprove-contract-IERC20-address-uint256-).
-Oppositely, when the recipient address (`to`) has code, this function only attempts to call [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-)
-once without retrying, and relies on the returned value to be true.
-
-
-Reverts if the returned value is other than `true`.
+Attempted to mint more shares than the max amount for `receiver`.
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC1363.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
```
-Extension of [`ERC20`](#ERC20) tokens that adds support for code execution after transfers and approvals
-on recipient contracts. Calls after transfers are enabled through the [`ERC1363.transferAndCall`](#ERC1363-transferAndCall-address-uint256-bytes-) and
-[`ERC1363.transferFromAndCall`](#ERC1363-transferFromAndCall-address-address-uint256-bytes-) methods while calls after approvals can be made with [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-)
-
-_Available since v5.1._
+Interface for the optional metadata functions from the ERC-20 standard.
-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.
+Returns the name of the token.
-Moves a `value` amount of tokens from the caller's account to `to`
-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`](/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`).
+Returns the symbol of the token.
-
+
-
transferAndCall(address to, uint256 value, bytes data) → bool
-Variant of [`ERC1363.transferAndCall`](#ERC1363-transferAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with
-no specified format.
+Returns the decimals places of the token.
-
-
-
-
-
transferFromAndCall(address from, address to, uint256 value) → bool
+
-Moves a `value` amount of tokens from `from` to `to` using the allowance mechanism
-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:
+## `IERC20Permit`
-- The target has code (i.e. is a contract).
-- 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`).
+
+
+
-
+Interface of the ERC-20 Permit extension allowing approvals to be made via signatures, as defined in
+[ERC-2612](https://eips.ethereum.org/EIPS/eip-2612).
-Variant of [`ERC1363.transferFromAndCall`](#ERC1363-transferFromAndCall-address-address-uint256-bytes-) that accepts an additional `data` parameter with
-no specified format.
+Adds the [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) method, which can be used to change an account's ERC-20 allowance (see [`IERC20.allowance`](#IERC20-allowance-address-address-)) by
+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
-
+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
+considered as an intention to spend the allowance in any specific way. The second is that because permits have
+built-in replay protection and can be submitted by anyone, they can be frontrun. A protocol that uses permits should
+take this into consideration and allow a `permit` call to fail. Combining these two aspects, a pattern that may be
+generally recommended is:
-
+```solidity
+function doThingWithPermit(..., uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public {
+ try token.permit(msg.sender, address(this), value, deadline, v, r, s) {} catch {}
+ doThing(..., value);
+}
-Sets a `value` amount of tokens as the allowance of `spender` over the
-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.
+function doThing(..., uint256 value) public {
+ token.safeTransferFrom(msg.sender, address(this), value);
+ ...
+}
+```
-Requirements:
+Observe that: 1) `msg.sender` is used as the owner, leaving no ambiguity as to the signer intent, and 2) the use of
+`try/catch` allows the permit to fail and makes the code tolerant to frontrunning. (See also
+[`SafeERC20.safeTransferFrom`](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-)).
-- The target has code (i.e. is a contract).
-- 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`).
+Additionally, note that smart contract wallets (such as Argent or Safe) are not able to produce permit signatures, so
+contracts should have entry points that don't rely on permit.
+
-Variant of [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-) that accepts an additional `data` parameter with
-no specified format.
+Sets `value` as the allowance of `spender` over ``owner``'s tokens,
+given ``owner``'s signed approval.
-
-
+
+The same issues [`IERC20.approve`](#IERC20-approve-address-uint256-) has related to transaction
+ordering also applies here.
+
-
+Emits an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
-
+Requirements:
-Indicates a failure within the [`ERC20.transfer`](#ERC20-transfer-address-uint256-) part of a transferAndCall operation.
+- `spender` cannot be the zero address.
+- `deadline` must be a timestamp in the future.
+- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
+over the EIP712-formatted function arguments.
+- the signature must use ``owner``'s current nonce (see [`ERC20Permit.nonces`](#ERC20Permit-nonces-address-)).
+
+For more information on the signature format, see the
+[relevant EIP
+section](https://eips.ethereum.org/EIPS/eip-2612#specification).
+
+
+See Security Considerations above.
+
-Indicates a failure within the [`ERC20.transferFrom`](#ERC20-transferFrom-address-address-uint256-) part of a transferFromAndCall operation.
+Returns the current nonce for `owner`. This value must be
+included whenever a signature is generated for [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-).
+
+Every successful call to [`ERC20Permit.permit`](#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-) increases ``owner``'s nonce by one. This
+prevents a signature from being used multiple times.
-Indicates a failure within the [`ERC20.approve`](#ERC20-approve-address-uint256-) part of a approveAndCall operation.
+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).
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol";
```
-Extension of [`ERC20`](#ERC20) that allows token holders to destroy both their own
-tokens and those that they have an allowance for, in a way that can be
-recognized off-chain (via event analysis).
+ERC20 extension that implements the standard token interface according to
+[ERC-7802](https://eips.ethereum.org/EIPS/eip-7802).
+
+
-Destroys a `value` amount of tokens from the caller.
+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.
-See [`ERC20._burn`](#ERC20-_burn-address-uint256-).
+This function call must use less than 30 000 gas.
-Destroys a `value` amount of tokens from `account`, deducting from
-the caller's allowance.
+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.
-See [`ERC20._burn`](#ERC20-_burn-address-uint256-) and [`ERC20.allowance`](#ERC20-allowance-address-address-).
+
+
-Requirements:
+
-- the caller must have allowance for ``accounts``'s tokens of at least
-`value`.
+
+
+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`](/contracts/5.x/api/access#AccessControl) or [`AccessManaged`](/contracts/5.x/api/access#AccessManaged).
+
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol";
+import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20TemporaryApproval.sol";
```
-Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens.
+Extension of [`ERC20`](#ERC20) that adds support for temporary allowances following ERC-7674.
+
+
+This is a draft contract. The corresponding ERC is still subject to changes.
+
+
+_Available since v5.1._
Functions
-- [constructor(cap_)](#ERC20Capped-constructor-uint256-)
-- [cap()](#ERC20Capped-cap--)
-- [_update(from, to, value)](#ERC20Capped-_update-address-address-uint256-)
+- [allowance(owner, spender)](#ERC20TemporaryApproval-allowance-address-address-)
+- [_temporaryAllowance(owner, spender)](#ERC20TemporaryApproval-_temporaryAllowance-address-address-)
+- [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-)
ERC20
@@ -3917,15 +3927,14 @@ Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens.
- [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-)
@@ -3947,8 +3956,6 @@ Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens.
Errors
-- [ERC20ExceededCap(increasedSupply, cap)](#ERC20Capped-ERC20ExceededCap-uint256-uint256-)
-- [ERC20InvalidCap(cap)](#ERC20Capped-ERC20InvalidCap-uint256-)
IERC20Errors
@@ -3963,528 +3970,521 @@ Extension of [`ERC20`](#ERC20) that adds a cap to the supply of tokens.
-Sets the value of the `cap`. This value is immutable, it can only be
-set once during construction.
+[`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.
-Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from`
-(or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding
-this function.
+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.
-Emits a [`IERC20.Transfer`](#IERC20-Transfer-address-address-uint256-) event.
+Returns a boolean value indicating whether the operation succeeded.
+
+Requirements:
+- `spender` cannot be the zero address.
+
+Does NOT emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
-Total supply cap has been exceeded.
+Sets `value` as the temporary allowance of `spender` over the `owner`'s tokens.
+
+This internal function is equivalent to `temporaryApprove`, and can be used to e.g. set automatic allowances
+for certain subsystems, etc.
+
+Requirements:
+- `owner` cannot be the zero address.
+- `spender` cannot be the zero address.
+
+Does NOT emit an [`IERC20.Approval`](#IERC20-Approval-address-address-uint256-) event.
-The supplied cap is not a valid cap.
+[`ERC20._spendAllowance`](#ERC20-_spendAllowance-address-address-uint256-) override that consumes the temporary allowance (if any) before eventually falling back
+to consuming the persistent allowance.
+
+This function skips calling `super._spendAllowance` if the temporary allowance
+is enough to cover the spending.
+
```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
+import "@openzeppelin/contracts/token/ERC20/utils/ERC1363Utils.sol";
```
-ERC-20 token with pausable token transfers, minting and burning.
-
-Useful for scenarios such as preventing trades until the end of an evaluation
-period, or having an emergency switch for freezing all token transfers in the
-event of a large bug.
+Library that provides common ERC-1363 utility functions.
-
-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`](/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.
-
+See [ERC-1363](https://eips.ethereum.org/EIPS/eip-1363).
-
-Pausable
-
-- [EnforcedPause()](#Pausable-EnforcedPause--)
-- [ExpectedPause()](#Pausable-ExpectedPause--)
+Performs a call to [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on a target address.
-
-
-IERC20Errors
+Requirements:
-- [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-)
+- The target has code (i.e. is a contract).
+- 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.
-
-See [`ERC20._update`](#ERC20-_update-address-address-uint256-).
+Performs a call to [`IERC1363Spender.onApprovalReceived`](/contracts/5.x/api/interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) on a target address.
Requirements:
-- the contract must not be paused.
+- The target has code (i.e. is a contract).
+- 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.
-```solidity
-import "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol";
-```
-
-ERC20 extension that implements the standard token interface according to
-[ERC-7802](https://eips.ethereum.org/EIPS/eip-7802).
+Indicates a failure with the token `receiver`. Used in transfers.
-
+
+```solidity
+import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+```
+
+Wrappers around ERC-20 operations that throw on failure (when the token
+contract returns false). Tokens that return no value (and instead revert or
+throw on failure) are also supported, non-reverting calls are assumed to be
+successful.
+To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract,
+which allows you to call the safe operations as `token.safeTransfer(...)`, etc.
+
+
+
Functions
+
+- [safeTransfer(token, to, value)](#SafeERC20-safeTransfer-contract-IERC20-address-uint256-)
+- [safeTransferFrom(token, from, to, value)](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-)
+- [trySafeTransfer(token, to, value)](#SafeERC20-trySafeTransfer-contract-IERC20-address-uint256-)
+- [trySafeTransferFrom(token, from, to, value)](#SafeERC20-trySafeTransferFrom-contract-IERC20-address-address-uint256-)
+- [safeIncreaseAllowance(token, spender, value)](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-)
+- [safeDecreaseAllowance(token, spender, requestedDecrease)](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-)
+- [forceApprove(token, spender, value)](#SafeERC20-forceApprove-contract-IERC20-address-uint256-)
+- [transferAndCallRelaxed(token, to, value, data)](#SafeERC20-transferAndCallRelaxed-contract-IERC1363-address-uint256-bytes-)
+- [transferFromAndCallRelaxed(token, from, to, value, data)](#SafeERC20-transferFromAndCallRelaxed-contract-IERC1363-address-address-uint256-bytes-)
+- [approveAndCallRelaxed(token, to, value, data)](#SafeERC20-approveAndCallRelaxed-contract-IERC1363-address-uint256-bytes-)
-Modifier to restrict access to the token bridge.
+Transfer `value` amount of `token` from the calling contract to `to`. If `token` returns no value,
+non-reverting calls are assumed to be successful.
-
+
-
supportsInterface(bytes4 interfaceId) → bool
+
safeTransferFrom(contract IERC20 token, address from, address to, uint256 value)
-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.
+Transfer `value` amount of `token` from `from` to `to`, spending the approval given by `from` to the
+calling contract. If `token` returns no value, non-reverting calls are assumed to be successful.
-
+
-
crosschainMint(address to, uint256 value)
+
trySafeTransfer(contract IERC20 token, address to, uint256 value) → bool
-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.
+Variant of [`SafeERC20.safeTransfer`](#SafeERC20-safeTransfer-contract-IERC20-address-uint256-) that returns a bool instead of reverting if the operation is not successful.
-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.
+Variant of [`SafeERC20.safeTransferFrom`](#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-) that returns a bool instead of reverting if the operation is not successful.
-Checks if the caller is a trusted token bridge. MUST revert otherwise.
+Increase the calling contract's allowance toward `spender` by `value`. If `token` returns no value,
+non-reverting calls are assumed to be successful.
-Developers should implement this function using an access control mechanism that allows
-customizing the list of allowed senders. Consider using [`AccessControl`](/contracts/5.x/api/access#AccessControl) or [`AccessManaged`](/contracts/5.x/api/access#AccessManaged).
+
+If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
+smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
+this function. Performing a [`SafeERC20.safeIncreaseAllowance`](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-) or [`SafeERC20.safeDecreaseAllowance`](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-) operation on a token contract
+that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
+
-## `ERC1363Utils`
+Decrease the calling contract's allowance toward `spender` by `requestedDecrease`. If `token` returns no
+value, non-reverting calls are assumed to be successful.
-
-
-
+
+If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
+smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
+this function. Performing a [`SafeERC20.safeIncreaseAllowance`](#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-) or [`SafeERC20.safeDecreaseAllowance`](#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-) operation on a token contract
+that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
+
+
-```solidity
-import "@openzeppelin/contracts/token/ERC20/utils/ERC1363Utils.sol";
-```
+
-Library that provides common ERC-1363 utility functions.
+
-See [ERC-1363](https://eips.ethereum.org/EIPS/eip-1363).
+Set the calling contract's allowance toward `spender` to `value`. If `token` returns no value,
+non-reverting calls are assumed to be successful. Meant to be used with tokens that require the approval
+to be set to zero before setting it to a non-zero value, such as USDT.
+
+
+If the token implements ERC-7674, this function will not modify any temporary allowance. This function
+only sets the "standard" allowance. Any temporary allowance will remain active, in addition to the value being
+set here.
+
-
-
+Performs an [`ERC1363`](#ERC1363) transferAndCall, with a fallback to the simple [`ERC20`](#ERC20) transfer if the target has no
+code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that relies on [`ERC1363`](#ERC1363) checks when
+targeting contracts.
+
+Reverts if the returned value is other than `true`.
+
+
+
+
+
-
checkOnERC1363TransferReceived(address operator, address from, address to, uint256 value, bytes data)
-Performs a call to [`IERC1363Receiver.onTransferReceived`](/contracts/5.x/api/interfaces#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-) on a target address.
-
-Requirements:
+Performs an [`ERC1363`](#ERC1363) transferFromAndCall, with a fallback to the simple [`ERC20`](#ERC20) transferFrom if the target
+has no code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that relies on [`ERC1363`](#ERC1363) checks when
+targeting contracts.
-- The target has code (i.e. is a contract).
-- 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.
+Reverts if the returned value is other than `true`.
-Performs a call to [`IERC1363Spender.onApprovalReceived`](/contracts/5.x/api/interfaces#IERC1363Spender-onApprovalReceived-address-uint256-bytes-) on a target address.
+Performs an [`ERC1363`](#ERC1363) approveAndCall, with a fallback to the simple [`ERC20`](#ERC20) approve if the target has no
+code. This can be used to implement an [`ERC721`](/contracts/5.x/api/token/ERC721#ERC721)-like safe transfer that rely on [`ERC1363`](#ERC1363) checks when
+targeting contracts.
-Requirements:
+
+When the recipient address (`to`) has no code (i.e. is an EOA), this function behaves as [`SafeERC20.forceApprove`](#SafeERC20-forceApprove-contract-IERC20-address-uint256-).
+Oppositely, when the recipient address (`to`) has code, this function only attempts to call [`ERC1363.approveAndCall`](#ERC1363-approveAndCall-address-uint256-bytes-)
+once without retrying, and relies on the returned value to be true.
+
-- The target has code (i.e. is a contract).
-- 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.
+Reverts if the returned value is other than `true`.
-Indicates a failure with the token `spender`. Used in approvals.
+Indicates a failed `decreaseAllowance` request.
diff --git a/content/contracts/5.x/api/utils.mdx b/content/contracts/5.x/api/utils.mdx
index 5f8fe667..de595447 100644
--- a/content/contracts/5.x/api/utils.mdx
+++ b/content/contracts/5.x/api/utils.mdx
@@ -8046,921 +8046,1248 @@ The item is not properly formatted and cannot be decoded.
```solidity
-import "@openzeppelin/contracts/utils/RelayedCall.sol";
+import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
```
-Library for performing external calls through dynamically deployed relay contracts that hide the original
-caller's address from the target contract. This pattern is used in ERC-4337's EntryPoint for account factory
-calls and ERC-6942 for safe factory interactions.
+Contract module that helps prevent reentrant calls to a function.
-When privileged contracts need to make arbitrary external calls based on user input, calling the target directly
-can be risky because the target sees the privileged contract as `msg.sender` and could exploit this trust
-relationship. This library solves this by deploying minimal relay contracts that act as intermediaries, ensuring
-the target only sees the unprivileged relay address as `msg.sender`.
+Inheriting from `ReentrancyGuard` will make the [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--) modifier
+available, which can be applied to functions to make sure there are no nested
+(reentrant) calls to them.
-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`.
+Note that because there is a single `nonReentrant` guard, functions marked as
+`nonReentrant` may not call one another. This can be worked around by making
+those functions `private`, and then adding `external` `nonReentrant` entry
+points to them.
-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.
+If EIP-1153 (transient storage) is available on the chain you're deploying at,
+consider using [`ReentrancyGuardTransient`](#ReentrancyGuardTransient) instead.
+
+
+
+If you would like to learn more about reentrancy and alternative ways
+to protect against it, check out our blog post
+[Reentrancy After Istanbul](https://blog.openzeppelin.com/reentrancy-after-istanbul/).
+
+
+
+Deprecated. This storage-based reentrancy guard will be removed and replaced
+by the [`ReentrancyGuardTransient`](#ReentrancyGuardTransient) variant in v6.0.
+@custom:stateless
+
+
-Relays a call to the target contract through a dynamically deployed relay contract.
+Prevents a contract from calling itself, directly or indirectly.
+Calling a `nonReentrant` function from another `nonReentrant`
+function is not supported. It is possible to prevent this from happening
+by making the `nonReentrant` function external, and making it call a
+`private` function that does the actual work.
-Same as `relayCall-address-bytes` but with a value.
+A `view` only version of [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--). Use to block view functions
+from being called, preventing reading from inconsistent contract state.
+
+
+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.
+
-Same as `relayCall-address-bytes` but with a salt and a value.
+Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
+`nonReentrant` function in the call stack.
-
-```solidity
-import "@openzeppelin/contracts/utils/ShortStrings.sol";
-```
-
-This library provides functions to convert short memory strings
-into a `ShortString` type that can be used as an immutable variable.
-
-Strings of arbitrary length can be optimized using this library if
-they are short enough (up to 31 bytes) by packing them with their
-length (1 byte) in a single EVM word (32 bytes). Additionally, a
-fallback mechanism can be used for every other case.
-
-Usage example:
-
-```solidity
-contract Named {
- using ShortStrings for *;
-
- ShortString private immutable _name;
- string private _nameFallback;
-
- constructor(string memory contractName) {
- _name = contractName.toShortStringWithFallback(_nameFallback);
- }
-
- function name() external view returns (string memory) {
- return _name.toStringWithFallback(_nameFallback);
- }
-}
-```
-Encode a string of at most 31 chars into a `ShortString`.
+
-This will trigger a `StringTooLong` error is the input string is too long.
+Prevents a contract from calling itself, directly or indirectly.
+Calling a `nonReentrant` function from another `nonReentrant`
+function is not supported. It is possible to prevent this from happening
+by making the `nonReentrant` function external, and making it call a
+`private` function that does the actual work.
-Decode a `ShortString` back to a "normal" string.
+A `view` only version of [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--). Use to block view functions
+from being called, preventing reading from inconsistent contract state.
+
+
+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.
+
-Return the length of a `ShortString`.
+Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
+`nonReentrant` function in the call stack.
-Decode a string that was encoded to `ShortString` or written to storage using [`ShortStrings.toShortStringWithFallback`](#ShortStrings-toShortStringWithFallback-string-string-).
+Unauthorized reentrant call.
-Return the length of a string that was encoded to `ShortString` or written to storage using
-[`ShortStrings.toShortStringWithFallback`](#ShortStrings-toShortStringWithFallback-string-string-).
+```solidity
+import "@openzeppelin/contracts/utils/RelayedCall.sol";
+```
-
-This will return the "byte length" of the string. This may not reflect the actual length in terms of
-actual characters as the UTF-8 encoding of a single character can span over multiple bytes.
+Library for performing external calls through dynamically deployed relay contracts that hide the original
+caller's address from the target contract. This pattern is used in ERC-4337's EntryPoint for account factory
+calls and ERC-6942 for safe factory interactions.
+
+When privileged contracts need to make arbitrary external calls based on user input, calling the target directly
+can be risky because the target sees the privileged contract as `msg.sender` and could exploit this trust
+relationship. This library solves this by deploying minimal relay contracts that act as intermediaries, ensuring
+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.
+
-```solidity
-import "@openzeppelin/contracts/utils/SimulateCall.sol";
-```
-
-Library for simulating external calls and inspecting the result of the call while reverting any state changes
-of events the call may have produced.
-
-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.
+Same as `relayCall-address-bytes` but with a salt.
-
-Same as `simulateCall-address-bytes` but with a value.
+Same as [`RelayedCall.getRelayer`](#RelayedCall-getRelayer-bytes32-) but with a `bytes32(0)` default salt.
-Returns the simulator address.
+Returns the relayer address for a given salt.
-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.
+
+
+
```solidity
-import "@openzeppelin/contracts/utils/SlotDerivation.sol";
+import "@openzeppelin/contracts/utils/ShortStrings.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.
+This library provides functions to convert short memory strings
+into a `ShortString` type that can be used as an immutable variable.
-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).
+Strings of arbitrary length can be optimized using this library if
+they are short enough (up to 31 bytes) by packing them with their
+length (1 byte) in a single EVM word (32 bytes). Additionally, a
+fallback mechanism can be used for every other case.
+
+Usage example:
-Example usage:
```solidity
-contract Example {
- // Add the library methods
- using StorageSlot for bytes32;
- using SlotDerivation for *;
+contract Named {
+ using ShortStrings for *;
- // Declare a namespace
- string private constant _NAMESPACE = ""; // eg. OpenZeppelin.Slot
+ ShortString private immutable _name;
+ string private _nameFallback;
- function setValueInNamespace(uint256 key, address newValue) internal {
- _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value = newValue;
+ constructor(string memory contractName) {
+ _name = contractName.toShortStringWithFallback(_nameFallback);
}
- function getValueInNamespace(uint256 key) internal view returns (address) {
- return _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value;
+ function name() external view returns (string memory) {
+ return _name.toStringWithFallback(_nameFallback);
}
}
```
-
-Consider using this library along with [`StorageSlot`](#StorageSlot).
-
-
-
-This library provides a way to manipulate storage locations in a non-standard way. Tooling for checking
-upgrade safety will ignore the slots accessed through this library.
-
-
-_Available since v5.1._
-
-Derive an ERC-7201 slot from a string (namespace).
+Encode a string of at most 31 chars into a `ShortString`.
+
+This will trigger a `StringTooLong` error is the input string is too long.
-
+
-
offset(bytes32 slot, uint256 pos) → bytes32 result
-Derive the location of a mapping element from the key.
+Decode a string that was encoded to `ShortString` or written to storage using [`ShortStrings.toShortStringWithFallback`](#ShortStrings-toShortStringWithFallback-string-string-).
-
+
-
deriveMapping(bytes32 slot, bytes32 key) → bytes32 result
-Derive the location of a mapping element from the key.
+Return the length of a string that was encoded to `ShortString` or written to storage using
+[`ShortStrings.toShortStringWithFallback`](#ShortStrings-toShortStringWithFallback-string-string-).
+
+
+This will return the "byte length" of the string. This may not reflect the actual length in terms of
+actual characters as the UTF-8 encoding of a single character can span over multiple bytes.
+
-
+
-
deriveMapping(bytes32 slot, uint256 key) → bytes32 result
+
+```solidity
+import "@openzeppelin/contracts/utils/SimulateCall.sol";
+```
+
+Library for simulating external calls and inspecting the result of the call while reverting any state changes
+of events the call may have produced.
+
+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.
+
+
-Derive the location of a mapping element from the key.
+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.
```solidity
-import "@openzeppelin/contracts/utils/StorageSlot.sol";
+import "@openzeppelin/contracts/utils/SlotDerivation.sol";
```
-Library for reading and writing primitive types to specific storage slots.
-
-Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts.
-This library helps with reading and writing to such slots without the need for inline assembly.
+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.
-The functions in this library return Slot structs that contain a `value` member that can be used to read or write.
+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 to set ERC-1967 implementation slot:
+Example usage:
```solidity
-contract ERC1967 {
- // Define the slot. Alternatively, use the SlotDerivation library to derive the slot.
- bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
+contract Example {
+ // Add the library methods
+ using StorageSlot for bytes32;
+ using SlotDerivation for *;
- function _getImplementation() internal view returns (address) {
- return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value;
+ // Declare a namespace
+ string private constant _NAMESPACE = ""; // eg. OpenZeppelin.Slot
+
+ function setValueInNamespace(uint256 key, address newValue) internal {
+ _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value = newValue;
}
- function _setImplementation(address newImplementation) internal {
- require(newImplementation.code.length > 0);
- StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation;
+ function getValueInNamespace(uint256 key) internal view returns (address) {
+ return _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value;
}
}
```
-Consider using this library along with [`SlotDerivation`](#SlotDerivation).
+Consider using this library along with [`StorageSlot`](#StorageSlot).
+
+
+
+This library provides a way to manipulate storage locations in a non-standard way. Tooling for checking
+upgrade safety will ignore the slots accessed through this library.
+_Available since v5.1._
+
-Returns a `Bytes32Slot` with member `value` located at `slot`.
+Derive the location of the first element in an array from the slot where the length is stored.
-
+
-
getUint256Slot(bytes32 slot) → struct StorageSlot.Uint256Slot r
+
deriveMapping(bytes32 slot, address key) → bytes32 result
+
+```solidity
+import "@openzeppelin/contracts/utils/StorageSlot.sol";
+```
+
+Library for reading and writing primitive types to specific storage slots.
+
+Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts.
+This library helps with reading and writing to such slots without the need for inline assembly.
+
+The functions in this library return Slot structs that contain a `value` member that can be used to read or write.
+
+Example usage to set ERC-1967 implementation slot:
+```solidity
+contract ERC1967 {
+ // Define the slot. Alternatively, use the SlotDerivation library to derive the slot.
+ bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
+
+ function _getImplementation() internal view returns (address) {
+ return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value;
+ }
+
+ function _setImplementation(address newImplementation) internal {
+ require(newImplementation.code.length > 0);
+ StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation;
+ }
+}
+```
+
+
+Consider using this library along with [`SlotDerivation`](#SlotDerivation).
+
+
+
-
-Insert a new leaf in the tree, and compute the new root. Returns the position of the inserted leaf in the
-tree, and the resulting root.
-
-Hashing the leaf before calling this function is recommended as a protection against
-second pre-image attacks.
-
-This variant uses [`Hashes.commutativeKeccak256`](/contracts/5.x/api/utils/cryptography#Hashes-commutativeKeccak256-bytes32-bytes32-) to hash internal nodes. It should only be used on merkle trees
-that were setup using the same (default) hashing function (i.e. by calling
-[the default setup](#MerkleTree-setup-struct-MerkleTree-Bytes32PushTree-uint8-bytes32-) function).
-
-
-
-Insert a new leaf in the tree, and compute the new root. Returns the position of the inserted leaf in the
-tree, and the resulting root.
-
-Hashing the leaf before calling this function is recommended as a protection against
-second pre-image attacks.
-
-This variant uses a custom hashing function to hash internal nodes. It should only be called with the same
-function as the one used during the initial setup of the merkle tree.
-
-
-
-Change the value of the leaf at position `index` from `oldValue` to `newValue`. Returns the recomputed "old"
-root (before the update) and "new" root (after the update). The caller must verify that the reconstructed old
-root is the last known one.
-
-The `proof` must be an up-to-date inclusion proof for the leaf being updated. This means that this function is
-vulnerable to front-running. Any [`RLP.push`](#RLP-push-struct-RLP-Encoder-struct-RLP-Encoder-) or [`MerkleTree.update`](#MerkleTree-update-struct-MerkleTree-Bytes32PushTree-uint256-bytes32-bytes32-bytes32---function--bytes32-bytes32--view-returns--bytes32--) operation (that changes the root of the tree) would render
-all "in flight" updates invalid.
-
-This variant uses [`Hashes.commutativeKeccak256`](/contracts/5.x/api/utils/cryptography#Hashes-commutativeKeccak256-bytes32-bytes32-) to hash internal nodes. It should only be used on merkle trees
-that were setup using the same (default) hashing function (i.e. by calling
-[the default setup](#MerkleTree-setup-struct-MerkleTree-Bytes32PushTree-uint8-bytes32-) function).
-
-
-
-Change the value of the leaf at position `index` from `oldValue` to `newValue`. Returns the recomputed "old"
-root (before the update) and "new" root (after the update). The caller must verify that the reconstructed old
-root is the last known one.
-
-The `proof` must be an up-to-date inclusion proof for the leaf being update. This means that this function is
-vulnerable to front-running. Any [`RLP.push`](#RLP-push-struct-RLP-Encoder-struct-RLP-Encoder-) or [`MerkleTree.update`](#MerkleTree-update-struct-MerkleTree-Bytes32PushTree-uint256-bytes32-bytes32-bytes32---function--bytes32-bytes32--view-returns--bytes32--) operation (that changes the root of the tree) would render
-all "in flight" updates invalid.
-
-This variant uses a custom hashing function to hash internal nodes. It should only be called with the same
-function as the one used during the initial setup of the merkle tree.
-
-
-
-```solidity
-import "@openzeppelin/contracts/utils/types/Time.sol";
-```
-
-This library provides helpers for manipulating time-related objects.
-
-It uses the following types:
-- `uint48` for timepoints
-- `uint32` for durations
-
-While the library doesn't provide specific types for timepoints and duration, it does provide:
-- a `Delay` type to represent duration that can be programmed to change value automatically at a given point
-- additional helper functions
-
-
-
-Get the current value plus the pending value and effect timepoint if there is a scheduled change. If the
-effect timepoint is 0, then the pending value should not be considered.
-
-
-
-Update a Delay object so that it takes a new duration after a timepoint that is automatically computed to
-enforce the old delay at the moment of the update. Returns the updated Delay object and the timestamp when the
-new delay becomes effective.
-
-
-
-```solidity
-import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
-```
-
-Contract module that helps prevent reentrant calls to a function.
-
-Inheriting from `ReentrancyGuard` will make the [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--) modifier
-available, which can be applied to functions to make sure there are no nested
-(reentrant) calls to them.
-
-Note that because there is a single `nonReentrant` guard, functions marked as
-`nonReentrant` may not call one another. This can be worked around by making
-those functions `private`, and then adding `external` `nonReentrant` entry
-points to them.
-
-
-If EIP-1153 (transient storage) is available on the chain you're deploying at,
-consider using [`ReentrancyGuardTransient`](#ReentrancyGuardTransient) instead.
-
-
-
-If you would like to learn more about reentrancy and alternative ways
-to protect against it, check out our blog post
-[Reentrancy After Istanbul](https://blog.openzeppelin.com/reentrancy-after-istanbul/).
-
-
-
-Deprecated. This storage-based reentrancy guard will be removed and replaced
-by the [`ReentrancyGuardTransient`](#ReentrancyGuardTransient) variant in v6.0.
-
-
-@custom:stateless
-
-
+Insert a new leaf in the tree, and compute the new root. Returns the position of the inserted leaf in the
+tree, and the resulting root.
+
+Hashing the leaf before calling this function is recommended as a protection against
+second pre-image attacks.
+
+This variant uses [`Hashes.commutativeKeccak256`](/contracts/5.x/api/utils/cryptography#Hashes-commutativeKeccak256-bytes32-bytes32-) to hash internal nodes. It should only be used on merkle trees
+that were setup using the same (default) hashing function (i.e. by calling
+[the default setup](#MerkleTree-setup-struct-MerkleTree-Bytes32PushTree-uint8-bytes32-) function).
-
-Prevents a contract from calling itself, directly or indirectly.
-Calling a `nonReentrant` function from another `nonReentrant`
-function is not supported. It is possible to prevent this from happening
-by making the `nonReentrant` function external, and making it call a
-`private` function that does the actual work.
+Insert a new leaf in the tree, and compute the new root. Returns the position of the inserted leaf in the
+tree, and the resulting root.
+
+Hashing the leaf before calling this function is recommended as a protection against
+second pre-image attacks.
+
+This variant uses a custom hashing function to hash internal nodes. It should only be called with the same
+function as the one used during the initial setup of the merkle tree.
-A `view` only version of [`ReentrancyGuard.nonReentrant`](#ReentrancyGuard-nonReentrant--). Use to block view functions
-from being called, preventing reading from inconsistent contract state.
+Change the value of the leaf at position `index` from `oldValue` to `newValue`. Returns the recomputed "old"
+root (before the update) and "new" root (after the update). The caller must verify that the reconstructed old
+root is the last known one.
-
-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.
-
+The `proof` must be an up-to-date inclusion proof for the leaf being updated. This means that this function is
+vulnerable to front-running. Any [`RLP.push`](#RLP-push-struct-RLP-Encoder-struct-RLP-Encoder-) or [`MerkleTree.update`](#MerkleTree-update-struct-MerkleTree-Bytes32PushTree-uint256-bytes32-bytes32-bytes32---function--bytes32-bytes32--view-returns--bytes32--) operation (that changes the root of the tree) would render
+all "in flight" updates invalid.
+
+This variant uses [`Hashes.commutativeKeccak256`](/contracts/5.x/api/utils/cryptography#Hashes-commutativeKeccak256-bytes32-bytes32-) to hash internal nodes. It should only be used on merkle trees
+that were setup using the same (default) hashing function (i.e. by calling
+[the default setup](#MerkleTree-setup-struct-MerkleTree-Bytes32PushTree-uint8-bytes32-) function).
+Change the value of the leaf at position `index` from `oldValue` to `newValue`. Returns the recomputed "old"
+root (before the update) and "new" root (after the update). The caller must verify that the reconstructed old
+root is the last known one.
+
+The `proof` must be an up-to-date inclusion proof for the leaf being update. This means that this function is
+vulnerable to front-running. Any [`RLP.push`](#RLP-push-struct-RLP-Encoder-struct-RLP-Encoder-) or [`MerkleTree.update`](#MerkleTree-update-struct-MerkleTree-Bytes32PushTree-uint256-bytes32-bytes32-bytes32---function--bytes32-bytes32--view-returns--bytes32--) operation (that changes the root of the tree) would render
+all "in flight" updates invalid.
+
+This variant uses a custom hashing function to hash internal nodes. It should only be called with the same
+function as the one used during the initial setup of the merkle tree.
+
-Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
-`nonReentrant` function in the call stack.
+Tree's depth (set at initialization)
```solidity
-import "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol";
+import "@openzeppelin/contracts/utils/types/Time.sol";
```
-Variant of [`ReentrancyGuard`](#ReentrancyGuard) that uses transient storage.
-
-
-This variant only works on networks where EIP-1153 is available.
-
+This library provides helpers for manipulating time-related objects.
-_Available since v5.1._
+It uses the following types:
+- `uint48` for timepoints
+- `uint32` for durations
-@custom:stateless
+While the library doesn't provide specific types for timepoints and duration, it does provide:
+- a `Delay` type to represent duration that can be programmed to change value automatically at a given point
+- additional helper functions