Merge branch 'master' into erc721-tests

Amxx · web-flow · commit 0e324741c2c7 · 2025-01-24T17:30:29.000+01:00
diff --git a/.github/actions/gas-compare/action.yml b/.github/actions/gas-compare/action.yml
@@ -44,7 +44,8 @@ runs:
       shell: bash
     - name: Save report
       if: github.event_name != 'pull_request'
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: gasreport
+        overwrite: true
         path: ${{ inputs.out_report }}
diff --git a/.github/actions/storage-layout/action.yml b/.github/actions/storage-layout/action.yml
@@ -50,7 +50,8 @@ runs:
       shell: bash
     - name: Save artifacts
       if: github.event_name != 'pull_request'
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: layout
+        overwrite: true
         path: ${{ inputs.out_layout }}
diff --git a/.gitignore b/.gitignore
@@ -37,6 +37,7 @@ npm-debug.log
 
 # docs artifacts
 docs/modules/api
+build/site
 
 # only used to package @openzeppelin/contracts
 contracts/build/
diff --git a/contracts/governance/Governor.sol b/contracts/governance/Governor.sol
@@ -455,7 +455,7 @@ abstract contract Governor is Context, ERC165, EIP712, Nonces, IGovernor, IERC72
      * performed (for example adding a vault/timelock).
      *
      * NOTE: 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 {execute} or {_execute}.
+     * true or emit the `ProposalExecuted` event. Executing a proposal should be done using {execute}.
      */
     function _executeOperations(
         uint256 /* proposalId */,
diff --git a/contracts/governance/README.adoc b/contracts/governance/README.adoc
@@ -68,7 +68,7 @@ NOTE: Functions of the `Governor` contract do not include access control. If you
 
 {{GovernorCountingFractional}}
 
-{{GovernorCountingOverride}}
+{{GovernorCountingOverridable}}
 
 {{GovernorVotes}}
 
@@ -103,7 +103,7 @@ In a governance system, the {TimelockController} contract is in charge of introd
 [[timelock-terminology]]
 ==== Terminology
 
-* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution (see xref:access-control.adoc#operation_lifecycle[operation lifecycle]). If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content.
+* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution. If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content.
 * *Operation status:*
 ** *Unset:* An operation that is not part of the timelock mechanism.
 ** *Waiting:* An operation that has been scheduled, before the timer expires.
diff --git a/contracts/governance/extensions/GovernorStorage.sol b/contracts/governance/extensions/GovernorStorage.sol
@@ -50,7 +50,7 @@ abstract contract GovernorStorage is Governor {
     }
 
     /**
-     * @dev Version of {IGovernorTimelock-queue} with only `proposalId` as an argument.
+     * @dev Version of {IGovernor-queue} with only `proposalId` as an argument.
      */
     function queue(uint256 proposalId) public virtual {
         // here, using storage is more efficient than memory
diff --git a/contracts/governance/extensions/GovernorTimelockAccess.sol b/contracts/governance/extensions/GovernorTimelockAccess.sol
@@ -277,7 +277,7 @@ abstract contract GovernorTimelockAccess is Governor {
     }
 
     /**
-     * @dev See {IGovernor-_cancel}
+     * @dev See {Governor-_cancel}
      */
     function _cancel(
         address[] memory targets,
diff --git a/contracts/proxy/utils/UUPSUpgradeable.sol b/contracts/proxy/utils/UUPSUpgradeable.sol
@@ -91,7 +91,6 @@ abstract contract UUPSUpgradeable is IERC1822Proxiable {
     /**
      * @dev 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.
-     * See {_onlyProxy}.
      */
     function _checkProxy() internal view virtual {
         if (
diff --git a/contracts/token/ERC1155/IERC1155.sol b/contracts/token/ERC1155/IERC1155.sol
@@ -81,7 +81,7 @@ interface IERC1155 is IERC165 {
      * @dev Transfers a `value` amount of tokens of type `id` from `from` to `to`.
      *
      * WARNING: This function can potentially allow a reentrancy attack when transferring tokens
-     * to an untrusted contract, when invoking {onERC1155Received} on the receiver.
+     * to an untrusted contract, when invoking {IERC1155Receiver-onERC1155Received} on the receiver.
      * Ensure to follow the checks-effects-interactions pattern and consider employing
      * reentrancy guards when interacting with untrusted contracts.
      *
@@ -101,7 +101,7 @@ interface IERC1155 is IERC165 {
      * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {safeTransferFrom}.
      *
      * WARNING: This function can potentially allow a reentrancy attack when transferring tokens
-     * to an untrusted contract, when invoking {onERC1155BatchReceived} on the receiver.
+     * to an untrusted contract, when invoking {IERC1155Receiver-onERC1155BatchReceived} on the receiver.
      * Ensure to follow the checks-effects-interactions pattern and consider employing
      * reentrancy guards when interacting with untrusted contracts.
      *
diff --git a/contracts/token/ERC1155/utils/ERC1155Utils.sol b/contracts/token/ERC1155/utils/ERC1155Utils.sol
@@ -15,7 +15,7 @@ import {IERC1155Errors} from "../../../interfaces/draft-IERC6093.sol";
  */
 library ERC1155Utils {
     /**
-     * @dev Performs an acceptance check for the provided `operator` by calling {IERC1155-onERC1155Received}
+     * @dev Performs an acceptance check for the provided `operator` by calling {IERC1155Receiver-onERC1155Received}
      * on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
      *
      * The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).
@@ -50,7 +50,7 @@ library ERC1155Utils {
     }
 
     /**
-     * @dev Performs a batch acceptance check for the provided `operator` by calling {IERC1155-onERC1155BatchReceived}
+     * @dev Performs a batch acceptance check for the provided `operator` by calling {IERC1155Receiver-onERC1155BatchReceived}
      * on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
      *
      * The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).
diff --git a/contracts/token/ERC20/extensions/ERC4626.sol b/contracts/token/ERC20/extensions/ERC4626.sol
@@ -34,7 +34,7 @@ import {Math} from "../../../utils/math/Math.sol";
  * 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 xref:erc4626.adoc#inflation-attack[here].
+ * underlying math can be found xref:ROOT:erc4626.adoc#inflation-attack[here].
  *
  * 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
diff --git a/contracts/token/ERC721/extensions/ERC721Consecutive.sol b/contracts/token/ERC721/extensions/ERC721Consecutive.sol
@@ -159,7 +159,7 @@ abstract contract ERC721Consecutive is IERC2309, ERC721 {
     }
 
     /**
-     * @dev Used to offset the first token id in {_nextConsecutiveId}
+     * @dev Used to offset the first token id in `_nextConsecutiveId`
      */
     function _firstConsecutiveId() internal view virtual returns (uint96) {
         return 0;
diff --git a/contracts/token/ERC721/extensions/ERC721URIStorage.sol b/contracts/token/ERC721/extensions/ERC721URIStorage.sol
@@ -52,7 +52,7 @@ abstract contract ERC721URIStorage is IERC4906, ERC721 {
     /**
      * @dev Sets `_tokenURI` as the tokenURI of `tokenId`.
      *
-     * Emits {MetadataUpdate}.
+     * Emits {IERC4906-MetadataUpdate}.
      */
     function _setTokenURI(uint256 tokenId, string memory _tokenURI) internal virtual {
         _tokenURIs[tokenId] = _tokenURI;
diff --git a/contracts/token/ERC721/utils/ERC721Utils.sol b/contracts/token/ERC721/utils/ERC721Utils.sol
@@ -15,7 +15,7 @@ import {IERC721Errors} from "../../../interfaces/draft-IERC6093.sol";
  */
 library ERC721Utils {
     /**
-     * @dev Performs an acceptance check for the provided `operator` by calling {IERC721-onERC721Received}
+     * @dev Performs an acceptance check for the provided `operator` by calling {IERC721Receiver-onERC721Received}
      * on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
      *
      * The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).
diff --git a/contracts/utils/Multicall.sol b/contracts/utils/Multicall.sol
@@ -13,10 +13,10 @@ import {Context} from "./Context.sol";
  * careful about sending transactions invoking {multicall}. For example, a relay address that filters function
  * selectors won't filter calls nested within a {multicall} operation.
  *
- * NOTE: Since 5.0.1 and 4.9.4, this contract identifies non-canonical contexts (i.e. `msg.sender` is not {_msgSender}).
+ * NOTE: Since 5.0.1 and 4.9.4, this contract identifies non-canonical contexts (i.e. `msg.sender` is not {Context-_msgSender}).
  * If a non-canonical context is identified, the following self `delegatecall` appends the last bytes of `msg.data`
  * to the subcall. This makes it safe to use with {ERC2771Context}. Contexts that don't affect the resolution of
- * {_msgSender} are not propagated to subcalls.
+ * {Context-_msgSender} are not propagated to subcalls.
  */
 abstract contract Multicall is Context {
     /**
diff --git a/contracts/utils/ShortStrings.sol b/contracts/utils/ShortStrings.sol
@@ -95,7 +95,7 @@ library ShortStrings {
     }
 
     /**
-     * @dev Decode a string that was encoded to `ShortString` or written to storage using {setWithFallback}.
+     * @dev Decode a string that was encoded to `ShortString` or written to storage using {toShortStringWithFallback}.
      */
     function toStringWithFallback(ShortString value, string storage store) internal pure returns (string memory) {
         if (ShortString.unwrap(value) != FALLBACK_SENTINEL) {
@@ -107,7 +107,7 @@ library ShortStrings {
 
     /**
      * @dev Return the length of a string that was encoded to `ShortString` or written to storage using
-     * {setWithFallback}.
+     * {toShortStringWithFallback}.
      *
      * WARNING: 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.
diff --git a/contracts/utils/Strings.sol b/contracts/utils/Strings.sol
@@ -139,7 +139,7 @@ library Strings {
     }
 
     /**
-     * @dev Variant of {parseUint} that parses a substring of `input` located between position `begin` (included) and
+     * @dev Variant of {parseUint-string} that parses a substring of `input` located between position `begin` (included) and
      * `end` (excluded).
      *
      * Requirements:
@@ -177,7 +177,7 @@ library Strings {
     }
 
     /**
-     * @dev Implementation of {tryParseUint} that does not check bounds. Caller should make sure that
+     * @dev Implementation of {tryParseUint-string-uint256-uint256} that does not check bounds. Caller should make sure that
      * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
      */
     function _tryParseUintUncheckedBounds(
@@ -250,7 +250,7 @@ library Strings {
     }
 
     /**
-     * @dev Implementation of {tryParseInt} that does not check bounds. Caller should make sure that
+     * @dev Implementation of {tryParseInt-string-uint256-uint256} that does not check bounds. Caller should make sure that
      * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
      */
     function _tryParseIntUncheckedBounds(
@@ -287,7 +287,7 @@ library Strings {
     }
 
     /**
-     * @dev Variant of {parseHexUint} that parses a substring of `input` located between position `begin` (included) and
+     * @dev Variant of {parseHexUint-string} that parses a substring of `input` located between position `begin` (included) and
      * `end` (excluded).
      *
      * Requirements:
@@ -325,7 +325,7 @@ library Strings {
     }
 
     /**
-     * @dev Implementation of {tryParseHexUint} that does not check bounds. Caller should make sure that
+     * @dev Implementation of {tryParseHexUint-string-uint256-uint256} that does not check bounds. Caller should make sure that
      * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
      */
     function _tryParseHexUintUncheckedBounds(
@@ -346,7 +346,7 @@ library Strings {
             result *= 16;
             unchecked {
                 // Multiplying by 16 is equivalent to a shift of 4 bits (with additional overflow check).
-                // This guaratees that adding a value < 16 will not cause an overflow, hence the unchecked.
+                // This guarantees that adding a value < 16 will not cause an overflow, hence the unchecked.
                 result += chr;
             }
         }
@@ -364,7 +364,7 @@ library Strings {
     }
 
     /**
-     * @dev Variant of {parseAddress} that parses a substring of `input` located between position `begin` (included) and
+     * @dev Variant of {parseAddress-string} that parses a substring of `input` located between position `begin` (included) and
      * `end` (excluded).
      *
      * Requirements:
@@ -378,15 +378,15 @@ library Strings {
 
     /**
      * @dev Variant of {parseAddress-string} that returns false if the parsing fails because the input is not a properly
-     * formatted address. See {parseAddress} requirements.
+     * formatted address. See {parseAddress-string} requirements.
      */
     function tryParseAddress(string memory input) internal pure returns (bool success, address value) {
         return tryParseAddress(input, 0, bytes(input).length);
     }
 
     /**
      * @dev Variant of {parseAddress-string-uint256-uint256} that returns false if the parsing fails because input is not a properly
-     * formatted address. See {parseAddress} requirements.
+     * formatted address. See {parseAddress-string-uint256-uint256} requirements.
      */
     function tryParseAddress(
         string memory input,
diff --git a/contracts/utils/cryptography/EIP712.sol b/contracts/utils/cryptography/EIP712.sol
@@ -109,7 +109,7 @@ abstract contract EIP712 is IERC5267 {
     }
 
     /**
-     * @dev See {IERC-5267}.
+     * @inheritdoc IERC5267
      */
     function eip712Domain()
         public
diff --git a/docs/modules/ROOT/pages/crowdsales.adoc b/docs/modules/ROOT/pages/crowdsales.adoc
diff --git a/docs/modules/ROOT/pages/drafts.adoc b/docs/modules/ROOT/pages/drafts.adoc
diff --git a/docs/modules/ROOT/pages/governance.adoc b/docs/modules/ROOT/pages/governance.adoc
@@ -52,7 +52,7 @@ If your project already has a live token that does not include ERC20Votes and is
 include::api:example$governance/MyTokenWrapped.sol[]
 ```
 
-NOTE: The only other source of voting power available in OpenZeppelin Contracts currently is xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]. ERC-721 tokens that don't provide this functionality can be wrapped into a voting tokens using a combination of xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`] and xref:api:token/ERC721Wrapper.adoc#ERC721Wrapper[`ERC721Wrapper`].
+NOTE: The only other source of voting power available in OpenZeppelin Contracts currently is xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]. ERC-721 tokens that don't provide this functionality can be wrapped into a voting tokens using a combination of xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`] and xref:api:token/ERC721.adoc#ERC721Wrapper[`ERC721Wrapper`].
 
 NOTE: The internal clock used by the token to store voting balances will dictate the operating mode of the Governor contract attached to it. By default, block numbers are used. Since v4.9, developers can override the xref:api:interfaces.adoc#IERC6372[IERC6372] clock to use timestamps instead of block numbers.
 
diff --git a/docs/templates/contract.hbs b/docs/templates/contract.hbs
@@ -2,6 +2,10 @@
 :{{name}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]]
 {{/each}}
 
+{{#each functions}}
+:{{fullname}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]]
+{{/each}}
+
 [.contract]
 [[{{anchor}}]]
 === `++{{name}}++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}[{github-icon},role=heading-link]
diff --git a/docs/templates/properties.js b/docs/templates/properties.js
@@ -17,6 +17,22 @@ module.exports.anchor = function anchor({ item, contract }) {
   return res;
 };
 
+module.exports.fullname = function fullname({ item }) {
+  let res = '';
+  res += item.name;
+  if ('parameters' in item) {
+    const signature = item.parameters.parameters.map(v => v.typeName.typeDescriptions.typeString).join(',');
+    res += slug('(' + signature + ')');
+  }
+  if (isNodeType('VariableDeclaration', item)) {
+    res += '-' + slug(item.typeName.typeDescriptions.typeString);
+  }
+  if (res.charAt(res.length - 1) === '-') {
+    return res.slice(0, -1);
+  }
+  return res;
+};
+
 module.exports.inheritance = function ({ item, build }) {
   if (!isNodeType('ContractDefinition', item)) {
     throw new Error('used inherited-items on non-contract');

Original file line number	Diff line number	Diff line change
`@@ -455,7 +455,7 @@ abstract contract Governor is Context, ERC165, EIP712, Nonces, IGovernor, IERC72`
`455`	`455`	`* performed (for example adding a vault/timelock).`
`456`	`456`	`*`
`457`	`457`	`* NOTE: Calling this function directly will NOT check the current state of the proposal, set the executed flag to`
`458`		- * true or emit the `ProposalExecuted` event. Executing a proposal should be done using {execute} or {_execute}.
	`458`	+ * true or emit the `ProposalExecuted` event. Executing a proposal should be done using {execute}.
`459`	`459`	`*/`
`460`	`460`	`function _executeOperations(`
`461`	`461`	`uint256 /* proposalId */,`
Original file line number	Diff line number	Diff line change
`@@ -50,7 +50,7 @@ abstract contract GovernorStorage is Governor {`
`50`	`50`	`}`
`51`	`51`
`52`	`52`	`/**`
`53`		- * @dev Version of {IGovernorTimelock-queue} with only `proposalId` as an argument.
	`53`	+ * @dev Version of {IGovernor-queue} with only `proposalId` as an argument.
`54`	`54`	`*/`
`55`	`55`	`function queue(uint256 proposalId) public virtual {`
`56`	`56`	`// here, using storage is more efficient than memory`
Original file line number	Diff line number	Diff line change
`@@ -277,7 +277,7 @@ abstract contract GovernorTimelockAccess is Governor {`
`277`	`277`	`}`
`278`	`278`
`279`	`279`	`/**`
`280`		`- * @dev See {IGovernor-_cancel}`
	`280`	`+ * @dev See {Governor-_cancel}`
`281`	`281`	`*/`
`282`	`282`	`function _cancel(`
`283`	`283`	`address[] memory targets,`
Original file line number	Diff line number	Diff line change
`@@ -81,7 +81,7 @@ interface IERC1155 is IERC165 {`
`81`	`81`	* @dev Transfers a `value` amount of tokens of type `id` from `from` to `to`.
`82`	`82`	`*`
`83`	`83`	`* WARNING: This function can potentially allow a reentrancy attack when transferring tokens`
`84`		`- * to an untrusted contract, when invoking {onERC1155Received} on the receiver.`
	`84`	`+ * to an untrusted contract, when invoking {IERC1155Receiver-onERC1155Received} on the receiver.`
`85`	`85`	`* Ensure to follow the checks-effects-interactions pattern and consider employing`
`86`	`86`	`* reentrancy guards when interacting with untrusted contracts.`
`87`	`87`	`*`
`@@ -101,7 +101,7 @@ interface IERC1155 is IERC165 {`
`101`	`101`	`* @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {safeTransferFrom}.`
`102`	`102`	`*`
`103`	`103`	`* WARNING: This function can potentially allow a reentrancy attack when transferring tokens`
`104`		`- * to an untrusted contract, when invoking {onERC1155BatchReceived} on the receiver.`
	`104`	`+ * to an untrusted contract, when invoking {IERC1155Receiver-onERC1155BatchReceived} on the receiver.`
`105`	`105`	`* Ensure to follow the checks-effects-interactions pattern and consider employing`
`106`	`106`	`* reentrancy guards when interacting with untrusted contracts.`
`107`	`107`	`*`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@ import {IERC1155Errors} from "../../../interfaces/draft-IERC6093.sol";`
`15`	`15`	`*/`
`16`	`16`	`library ERC1155Utils {`
`17`	`17`	`/**`
`18`		- * @dev Performs an acceptance check for the provided `operator` by calling {IERC1155-onERC1155Received}
	`18`	+ * @dev Performs an acceptance check for the provided `operator` by calling {IERC1155Receiver-onERC1155Received}
`19`	`19`	* on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
`20`	`20`	`*`
`21`	`21`	`* The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).`
`@@ -50,7 +50,7 @@ library ERC1155Utils {`
`50`	`50`	`}`
`51`	`51`
`52`	`52`	`/**`
`53`		- * @dev Performs a batch acceptance check for the provided `operator` by calling {IERC1155-onERC1155BatchReceived}
	`53`	+ * @dev Performs a batch acceptance check for the provided `operator` by calling {IERC1155Receiver-onERC1155BatchReceived}
`54`	`54`	* on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
`55`	`55`	`*`
`56`	`56`	`* The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).`