Fix typos and documentation for the 5.6 audit. (#6330)

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

Author: Amxx

contracts/crosschain/ERC7786Recipient.sol

@@ -51,7 +51,12 @@ abstract contract ERC7786Recipient is IERC7786Recipient {
      */
     function _isAuthorizedGateway(address gateway, bytes calldata sender) internal view virtual returns (bool);
 
-    /// @dev Virtual function that should contain the logic to execute when a cross-chain message is received.
+    /**
+     * @dev Virtual function that should contain the logic to execute when a cross-chain message is received.
+     *
+     * NOTE: 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.
+     */
     function _processMessage(
         address gateway,
         bytes32 receiveId,

contracts/metatx/ERC2771Forwarder.sol

@@ -214,7 +214,7 @@ contract ERC2771Forwarder is EIP712, Nonces {
      * @dev Returns a tuple with the recovered the signer of an EIP712 forward request message hash
      * and a boolean indicating if the signature is valid.
      *
-     * NOTE: The signature is considered valid if {ECDSA-tryRecover} indicates no recover error for it.
+     * NOTE: The signature is considered valid if {ECDSA-tryRecoverCalldata} indicates no recover error for it.
      */
     function _recoverForwardRequestSigner(
         ForwardRequestData calldata request

contracts/token/ERC1155/ERC1155.sol

@@ -376,6 +376,7 @@ abstract contract ERC1155 is Context, ERC165, IERC1155, IERC1155MetadataURI, IER
      *
      * Requirements:
      *
+     * - `owner` cannot be the zero address.
      * - `operator` cannot be the zero address.
      */
     function _setApprovalForAll(address owner, address operator, bool approved) internal virtual {

contracts/utils/Arrays.sol

@@ -466,21 +466,21 @@ library Arrays {
     }
 
     /**
-     * @dev Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array.
+     * @dev 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:].
      *
      * NOTE: This function modifies the provided array in place. If you need to preserve the original array, use {slice} instead.
-     * NOTE: replicates the behavior of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice[Javascript's `Array.splice`]
      */
     function splice(address[] memory array, uint256 start) internal pure returns (address[] memory) {
         return splice(array, start, array.length);
     }
 
     /**
-     * @dev Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array. The
+     * @dev 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`.
      *
      * NOTE: This function modifies the provided array in place. If you need to preserve the original array, use {slice} instead.
-     * NOTE: replicates the behavior of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice[Javascript's `Array.splice`]
      */
     function splice(address[] memory array, uint256 start, uint256 end) internal pure returns (address[] memory) {
         // sanitize
@@ -499,7 +499,7 @@ library Arrays {
     /**
      * @dev Replaces elements in `array` starting at `pos` with all elements from `replacement`.
      *
-     * Parameters are clamped to valid ranges (i.e. `pos` is clamped to `[0, array.length]`).
+     * 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.
      *
      * NOTE: This function modifies the provided array in place.
@@ -535,7 +535,7 @@ library Arrays {
         offset = Math.min(offset, replacement.length);
         length = Math.min(length, Math.min(replacement.length - offset, array.length - pos));
 
-        // allocate and copy
+        // replace
         assembly ("memory-safe") {
             mcopy(
                 add(add(array, 0x20), mul(pos, 0x20)),
@@ -548,21 +548,21 @@ library Arrays {
     }
 
     /**
-     * @dev Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array.
+     * @dev 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:].
      *
      * NOTE: This function modifies the provided array in place. If you need to preserve the original array, use {slice} instead.
-     * NOTE: replicates the behavior of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice[Javascript's `Array.splice`]
      */
     function splice(bytes32[] memory array, uint256 start) internal pure returns (bytes32[] memory) {
         return splice(array, start, array.length);
     }
 
     /**
-     * @dev Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array. The
+     * @dev 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`.
      *
      * NOTE: This function modifies the provided array in place. If you need to preserve the original array, use {slice} instead.
-     * NOTE: replicates the behavior of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice[Javascript's `Array.splice`]
      */
     function splice(bytes32[] memory array, uint256 start, uint256 end) internal pure returns (bytes32[] memory) {
         // sanitize
@@ -581,7 +581,7 @@ library Arrays {
     /**
      * @dev Replaces elements in `array` starting at `pos` with all elements from `replacement`.
      *
-     * Parameters are clamped to valid ranges (i.e. `pos` is clamped to `[0, array.length]`).
+     * 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.
      *
      * NOTE: This function modifies the provided array in place.
@@ -617,7 +617,7 @@ library Arrays {
         offset = Math.min(offset, replacement.length);
         length = Math.min(length, Math.min(replacement.length - offset, array.length - pos));
 
-        // allocate and copy
+        // replace
         assembly ("memory-safe") {
             mcopy(
                 add(add(array, 0x20), mul(pos, 0x20)),
@@ -630,21 +630,21 @@ library Arrays {
     }
 
     /**
-     * @dev Moves the content of `array`, from `start` (included) to the end of `array` to the start of that array.
+     * @dev 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:].
      *
      * NOTE: This function modifies the provided array in place. If you need to preserve the original array, use {slice} instead.
-     * NOTE: replicates the behavior of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice[Javascript's `Array.splice`]
      */
     function splice(uint256[] memory array, uint256 start) internal pure returns (uint256[] memory) {
         return splice(array, start, array.length);
     }
 
     /**
-     * @dev Moves the content of `array`, from `start` (included) to `end` (excluded) to the start of that array. The
+     * @dev 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`.
      *
      * NOTE: This function modifies the provided array in place. If you need to preserve the original array, use {slice} instead.
-     * NOTE: replicates the behavior of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice[Javascript's `Array.splice`]
      */
     function splice(uint256[] memory array, uint256 start, uint256 end) internal pure returns (uint256[] memory) {
         // sanitize
@@ -663,7 +663,7 @@ library Arrays {
     /**
      * @dev Replaces elements in `array` starting at `pos` with all elements from `replacement`.
      *
-     * Parameters are clamped to valid ranges (i.e. `pos` is clamped to `[0, array.length]`).
+     * 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.
      *
      * NOTE: This function modifies the provided array in place.
@@ -699,7 +699,7 @@ library Arrays {
         offset = Math.min(offset, replacement.length);
         length = Math.min(length, Math.min(replacement.length - offset, array.length - pos));
 
-        // allocate and copy
+        // replace
         assembly ("memory-safe") {
             mcopy(
                 add(add(array, 0x20), mul(pos, 0x20)),

contracts/utils/Bytes.sol

@@ -98,28 +98,28 @@ library Bytes {
     }
 
     /**
-     * @dev Moves the content of `buffer`, from `start` (included) to the end of `buffer` to the start of that buffer.
+     * @dev 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:].
      *
      * NOTE: This function modifies the provided buffer in place. If you need to preserve the original buffer, use {slice} instead
-     * NOTE: replicates the behavior of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice[Javascript's `Array.splice`]
      */
     function splice(bytes memory buffer, uint256 start) internal pure returns (bytes memory) {
         return splice(buffer, start, buffer.length);
     }
 
     /**
-     * @dev 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`.
+     * @dev 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`.
      *
      * NOTE: This function modifies the provided buffer in place. If you need to preserve the original buffer, use {slice} instead
-     * NOTE: replicates the behavior of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice[Javascript's `Array.splice`]
      */
     function splice(bytes memory buffer, uint256 start, uint256 end) internal pure returns (bytes memory) {
         // sanitize
         end = Math.min(end, buffer.length);
         start = Math.min(start, end);
 
-        // allocate and copy
+        // move and resize
         assembly ("memory-safe") {
             mcopy(add(buffer, 0x20), add(add(buffer, 0x20), start), sub(end, start))
             mstore(buffer, sub(end, start))
@@ -163,7 +163,7 @@ library Bytes {
         offset = Math.min(offset, replacement.length);
         length = Math.min(length, Math.min(replacement.length - offset, buffer.length - pos));
 
-        // allocate and copy
+        // replace
         assembly ("memory-safe") {
             mcopy(add(add(buffer, 0x20), pos), add(add(replacement, 0x20), offset), length)
         }

contracts/utils/LowLevelCall.sol

@@ -23,7 +23,7 @@ library LowLevelCall {
     }
 
     /// @dev 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.
     ///
     /// WARNING: Do not assume that the results are zero if `success` is false. Memory can be already allocated
     /// and this function doesn't zero it out.
@@ -55,7 +55,7 @@ library LowLevelCall {
     }
 
     /// @dev 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.
     ///
     /// WARNING: Do not assume that the results are zero if `success` is false. Memory can be already allocated
     /// and this function doesn't zero it out.
@@ -78,7 +78,7 @@ library LowLevelCall {
     }
 
     /// @dev 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.
     ///
     /// WARNING: Do not assume that the results are zero if `success` is false. Memory can be already allocated
     /// and this function doesn't zero it out.

contracts/utils/Memory.sol

@@ -68,13 +68,13 @@ library Memory {
         }
     }
 
-    /// @dev Offset a memory slice (equivalent to self[start:] for calldata slices)
+    /// @dev Offset a memory slice (equivalent to self[offset:] for calldata slices)
     function slice(Slice self, uint256 offset) internal pure returns (Slice) {
         if (offset > length(self)) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS);
         return _asSlice(length(self) - offset, forward(_pointer(self), offset));
     }
 
-    /// @dev Offset and cut a Slice (equivalent to self[start:start+length] for calldata slices)
+    /// @dev Offset and cut a Slice (equivalent to self[offset:offset+len] for calldata slices)
     function slice(Slice self, uint256 offset, uint256 len) internal pure returns (Slice) {
         if (offset + len > length(self)) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS);
         return _asSlice(len, forward(_pointer(self), offset));

contracts/utils/RLP.sol

@@ -52,7 +52,7 @@ library RLP {
     using Bytes for *;
     using Memory for *;
 
-    /// @dev The item is not properly formatted and cannot de decoded.
+    /// @dev The item is not properly formatted and cannot be decoded.
     error RLPInvalidEncoding();
 
     enum ItemType {
@@ -429,7 +429,7 @@ library RLP {
     }
 
     /**
-     * @dev Decodes an RLP `item`'s `length and type from its prefix.
+     * @dev Decodes an RLP `item`'s length and type from its prefix.
      * Returns the offset, length, and type of the RLP item based on the encoding rules.
      */
     function _decodeLength(Memory.Slice item) private pure returns (uint256, uint256, ItemType) {
@@ -468,7 +468,7 @@ library RLP {
             if (prefix <= LONG_OFFSET + SHORT_THRESHOLD) {
                 // Case: Short list
                 uint256 listLength = prefix - LONG_OFFSET;
-                require(item.length() > listLength, RLPInvalidEncoding());
+                require(itemLength > listLength, RLPInvalidEncoding());
                 return (1, listLength, ItemType.List);
             } else {
                 // Case: Long list

contracts/utils/RelayedCall.sol

@@ -15,6 +15,10 @@ pragma solidity ^0.8.20;
  *
  * For example, instead of `target.call(data)` where the target sees this contract as `msg.sender`, use
  * {relayCall} where the target sees a relay address as `msg.sender`.
+ *
+ * NOTE: 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.
  */
 library RelayedCall {
     /// @dev Relays a call to the target contract through a dynamically deployed relay contract.

contracts/utils/cryptography/TrieProof.sol

@@ -123,7 +123,7 @@ library TrieProof {
                 if (currentNodeIdLength != 32 || keccak256(encoded) != currentNodeId)
                     return (_emptyBytesMemory(), ProofError.INVALID_LARGE_NODE);
             } else {
-                // Small nodes must match directly
+                // Short nodes must match directly
                 if (currentNodeIdLength != encoded.length || bytes32(encoded) != currentNodeId)
                     return (_emptyBytesMemory(), ProofError.INVALID_SHORT_NODE);
             }
@@ -146,12 +146,12 @@ library TrieProof {
                 if (path.length == 0) {
                     return (_emptyBytesMemory(), ProofError.EMPTY_PATH);
                 }
-                uint8 prefix = uint8(path[0]);
+                uint8 prefix = uint8(path[0]); // path encoding nibble (node type + parity), see {Prefix}
                 Memory.Slice keyRemainder = keyExpanded.asSlice().slice(keyIndex); // Remaining key to match
                 Memory.Slice pathRemainder = path.asSlice().slice(2 - (prefix % 2)); // Path after the prefix
                 uint256 pathRemainderLength = pathRemainder.length();
 
-                // pathRemainder must not be longer than keyRemainder, and it must be a prefix of it
+                // pathRemainder must not be longer than keyRemainder and must match the start of keyRemainder
                 if (
                     pathRemainderLength > keyRemainder.length() ||
                     !pathRemainder.equal(keyRemainder.slice(0, pathRemainderLength))
@@ -210,13 +210,21 @@ library TrieProof {
     /**
      * @dev Extracts the node ID (hash or raw data based on size)
      *
-     * For small nodes (encoded length < 32 bytes) the node ID is the node content itself,
+     * For short nodes (encoded length < 32 bytes) the node ID is the node content itself,
      * For larger nodes, the node ID is the hash of the encoded node data.
      *
-     * NOTE: Under normal operation, the input should never be exactly 32-byte inputs. If such an input is provided,
-     * it will be used directly, similarly to how small nodes are processed. The following traversal check whether
-     * the next node is a large one, and whether its hash matches the raw 32 bytes we have here. If that is the case,
-     * the value will be accepted. Otherwise, the next step will return an {INVALID_LARGE_NODE} error.
+     * [NOTE]
+     * ====
+     * Under normal operation, the input should never be exactly 32 bytes nor empty.
+     *
+     * If a 32-byte input is provided, it is used directly (like short nodes). The next traversal step then checks
+     * whether the next node is large and its hash matches those raw bytes. If that is not the case, it returns
+     * {INVALID_LARGE_NODE}.
+     *
+     * If the input is empty (e.g. when traversing a branch node whose target child slot is empty, meaning the key
+     * does not exist in the trie), this returns `nodeIdLength = 0` and the next iteration fails with {INVALID_LARGE_NODE} or
+     * {INVALID_SHORT_NODE} depending on the next proof element, rather than a dedicated "key not in trie" error.
+     * ====
      */
     function _getNodeId(Memory.Slice node) private pure returns (bytes32 nodeId, uint256 nodeIdLength) {
         uint256 nodeLength = node.length();