Complete minimal documentation

contracts/account/README.adoc

@@ -0,0 +1,15 @@
+= Account
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/community-contracts/api/account
+
+This directory includes contracts to build accounts for ERC-4337.
+
+== Core
+
+{{AccountCore}}
+
+{{Account}}
+
+== Extensions
+
+{{AccountSignerERC7702}}

contracts/account/draft-Account.sol

@@ -10,10 +10,10 @@ import {AccountCore} from "./draft-AccountCore.sol";
 /**
  * @dev Extension of {AccountCore} with recommended feature that most account abstraction implementation will want:
  *
- * * {ERC721Holder} for ERC-721 token handling
- * * {ERC1155Holder} for ERC-1155 token handling
+ * * {ERC721Holder} and {ERC1155Holder} to accept ERC-712 and ERC-1155 token transfers transfers.
  * * {ERC7739Signer} for ERC-1271 signature support with ERC-7739 replay protection
  *
- * NOTE: This needs to be combine with a signer implementation such as {SignerECDSA}, {SignerP256} or {SignerRSA}
+ * NOTE: To use this contract, the {ERC7739Signer-_rawSignatureValidation} function must be
+ * implemented using a specific signature verification algorithm. See {SignerECDSA}, {SignerP256} or {SignerRSA}.
  */
 abstract contract Account is AccountCore, ERC721Holder, ERC1155Holder, ERC7739Signer {}

contracts/account/draft-AccountCore.sol

@@ -13,10 +13,10 @@ import {AbstractSigner} from "../utils/cryptography/AbstractSigner.sol";
  * @dev A simple ERC4337 account implementation. This base implementation only includes the minimal logic to process
  * user operations.
  *
- * Developers must implement the {_rawSignatureValidation} function to define the account's validation logic.
+ * Developers must implement the {AbstractSigner-_rawSignatureValidation} function to define the account's validation logic.
  *
  * IMPORTANT: Implementing a mechanism to validate signatures is a security-sensitive operation as it may allow an
- * attacker to bypass the account's security measures. Check out {AccountECDSA}, {AccountP256}, or {AccountRSA} for
+ * attacker to bypass the account's security measures. Check out {SignerECDSA}, {SignerP256}, or {SignerRSA} for
  * digital signature validation implementations.
  */
 abstract contract AccountCore is AbstractSigner, EIP712, IAccount, IAccountExecute {

contracts/account/extensions/AccountSignerERC7702.sol

@@ -5,9 +5,12 @@ pragma solidity ^0.8.20;
 import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
 import {AccountCore} from "../draft-AccountCore.sol";
 
+/**
+ * @dev {Account} implementation whose low-level signature validation is done by an EOA.
+ */
 abstract contract AccountSignerERC7702 is AccountCore {
     /**
-     * @dev Validates the signature using the account's address.
+     * @dev Validates the signature using the EOA's address (ie. `address(this)`).
      */
     function _rawSignatureValidation(
         bytes32 hash,

contracts/utils/README.adoc

@@ -5,16 +5,26 @@ NOTE: This document is better viewed at https://docs.openzeppelin.com/community-
 
 Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives.
 
- * {Masks}: Library to handle `bytes32` masks.
- * {ERC7739Utils}: Utilities library that implements a defensive rehashing mechanism to prevent replayability of smart contract signatures based on ERC-7739.
+ * {AbstractSigner}: Abstract contract for internal signature validation in smart contracts.
  * {ERC7739Signer}: An abstract contract to validate signatures following the rehashing scheme from `ERC7739Utils`.
+ * {ERC7739Utils}: Utilities library that implements a defensive rehashing mechanism to prevent replayability of smart contract signatures based on ERC-7739.
+ * {SignerECDSA}, {SignerP256}, {SignerRSA}: Implementations of an {AbstractSigner} with specific signature validation algorithms.
+ * {Masks}: Library to handle `bytes32` masks.
 
 == Cryptography
 
+{{AbstractSigner}}
+
 {{ERC7739Signer}}
 
 {{ERC7739Utils}}
 
+{{SignerECDSA}}
+
+{{SignerP256}}
+
+{{SignerRSA}}
+
 == Libraries
 
 {{Masks}}

contracts/utils/cryptography/AbstractSigner.sol

@@ -2,13 +2,19 @@
 
 pragma solidity ^0.8.20;
 
+/**
+ * @dev Abstract contract for signature validation.
+ *
+ * Developers must implement {_rawSignatureValidation} and use it as the lowest-level signature validation mechanism.
+ */
 abstract contract AbstractSigner {
     /**
      * @dev Signature validation algorithm.
      *
      * WARNING: 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}, {P256} or {RSA}).
+     * using one of the signature verification libraries (https://docs.openzeppelin.com/contracts/api/utils#ECDSA[ECDSA],
+     * https://docs.openzeppelin.com/contracts/api/utils#P256[P256] or https://docs.openzeppelin.com/contracts/api/utils#RSA[RSA]).
      */
     function _rawSignatureValidation(bytes32 hash, bytes calldata signature) internal view virtual returns (bool);
 }

contracts/utils/cryptography/SignerECDSA.sol

@@ -6,10 +6,11 @@ import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
 import {AbstractSigner} from "./AbstractSigner.sol";
 
 /**
- * @dev Implementation of {AbstractSigner} using {ECDSA} signatures.
+ * @dev Implementation of {AbstractSigner} using
+ * https://docs.openzeppelin.com/contracts/api/utils#ECDSA[ECDSA] signatures.
  *
- * An {_initializeSigner} function is provided to set the account's signer address. Doing so it's
- * easier for a factory, whose likely to use initializable clones of this contract.
+ * For {Account} usage, an {_initializeSigner} function is provided to set the {signer} address.
+ * Doing so it's easier for a factory, whose likely to use initializable clones of this contract.
  *
  * Example of usage:
  *
@@ -25,34 +26,32 @@ import {AbstractSigner} from "./AbstractSigner.sol";
  * ```
  *
  * IMPORTANT: Avoiding to call {_initializeSigner} either during construction (if used standalone)
- * or during initialization (if used as a clone) may leave the account either front-runnable or unusable.
+ * or during initialization (if used as a clone) may leave the signer either front-runnable or unusable.
  */
 abstract contract SignerECDSA is AbstractSigner {
     /**
      * @dev The {signer} is already initialized.
      */
-    error AccountECDSAUninitializedSigner(address signer);
+    error SignerECDSAUninitializedSigner(address signer);
 
     address private _signer;
 
     /**
-     * @dev Initializes the account with the address of the native signer. This function can be called only once.
+     * @dev Initializes the signer with the address of the native signer. This function can be called only once.
      */
     function _initializeSigner(address signerAddr) internal {
-        if (_signer != address(0)) revert AccountECDSAUninitializedSigner(signerAddr);
+        if (_signer != address(0)) revert SignerECDSAUninitializedSigner(signerAddr);
         _signer = signerAddr;
     }
 
     /**
-     * @dev Return the account's signer address.
+     * @dev Return the signer's address.
      */
     function signer() public view virtual returns (address) {
         return _signer;
     }
 
-    /**
-     * @dev Validates the signature using the account's signer.
-     */
+    // @inheritdoc AbstractSigner
     function _rawSignatureValidation(
         bytes32 hash,
         bytes calldata signature

contracts/utils/cryptography/SignerP256.sol

@@ -6,10 +6,11 @@ import {P256} from "@openzeppelin/contracts/utils/cryptography/P256.sol";
 import {AbstractSigner} from "./AbstractSigner.sol";
 
 /**
- * @dev Implementation of {AbstractSigner} using {P256} signatures.
+ * @dev Implementation of {AbstractSigner} using
+ * https://docs.openzeppelin.com/contracts/api/utils#P256[P256] signatures.
  *
- * An {_initializeSigner} function is provided to set the account's signer address. Doing so it's
- * easier for a factory, whose likely to use initializable clones of this contract.
+ * For {Account} usage, an {_initializeSigner} function is provided to set the {signer} public key.
+ * Doing so it's easier for a factory, whose likely to use initializable clones of this contract.
  *
  * Example of usage:
  *
@@ -25,36 +26,34 @@ import {AbstractSigner} from "./AbstractSigner.sol";
  * ```
  *
  * IMPORTANT: Avoiding to call {_initializeSigner} either during construction (if used standalone)
- * or during initialization (if used as a clone) may leave the account either front-runnable or unusable.
+ * or during initialization (if used as a clone) may leave the signer either front-runnable or unusable.
  */
 abstract contract SignerP256 is AbstractSigner {
     /**
      * @dev The {signer} is already initialized.
      */
-    error AccountP256UninitializedSigner(bytes32 qx, bytes32 qy);
+    error SignerP256UninitializedSigner(bytes32 qx, bytes32 qy);
 
     bytes32 private _qx;
     bytes32 private _qy;
 
     /**
-     * @dev Initializes the account with the P256 public key. This function can be called only once.
+     * @dev Initializes the signer with the P256 public key. This function can be called only once.
      */
     function _initializeSigner(bytes32 qx, bytes32 qy) internal {
-        if (_qx != 0 || _qy != 0) revert AccountP256UninitializedSigner(qx, qy);
+        if (_qx != 0 || _qy != 0) revert SignerP256UninitializedSigner(qx, qy);
         _qx = qx;
         _qy = qy;
     }
 
     /**
-     * @dev Return the account's signer P256 public key.
+     * @dev Return the signer's P256 public key.
      */
     function signer() public view virtual returns (bytes32 qx, bytes32 qy) {
         return (_qx, _qy);
     }
 
-    /**
-     * @dev Validates the signature using the account's signer.
-     */
+    /// @inheritdoc AbstractSigner
     function _rawSignatureValidation(
         bytes32 hash,
         bytes calldata signature

contracts/utils/cryptography/SignerRSA.sol

@@ -6,10 +6,11 @@ import {RSA} from "@openzeppelin/contracts/utils/cryptography/RSA.sol";
 import {AbstractSigner} from "./AbstractSigner.sol";
 
 /**
- * @dev Implementation of {AbstractSigner} using {RSA} signatures.
+ * @dev Implementation of {AbstractSigner} using
+ * https://docs.openzeppelin.com/contracts/api/utils#RSA[RSA] signatures.
  *
- * An {_initializeSigner} function is provided to set the account's signer address. Doing so it's
- * easier for a factory, whose likely to use initializable clones of this contract.
+ * For {Account} usage, an {_initializeSigner} function is provided to set the {signer} public key.
+ * Doing so it's easier for a factory, whose likely to use initializable clones of this contract.
  *
  * Example of usage:
  *
@@ -25,36 +26,34 @@ import {AbstractSigner} from "./AbstractSigner.sol";
  * ```
  *
  * IMPORTANT: Avoiding to call {_initializeSigner} either during construction (if used standalone)
- * or during initialization (if used as a clone) may leave the account either front-runnable or unusable.
+ * or during initialization (if used as a clone) may leave the signer either front-runnable or unusable.
  */
 abstract contract SignerRSA is AbstractSigner {
     /**
      * @dev The {signer} is already initialized.
      */
-    error AccountRSAUninitializedSigner(bytes e, bytes n);
+    error SignerRSAUninitializedSigner(bytes e, bytes n);
 
     bytes private _e;
     bytes private _n;
 
     /**
-     * @dev Initializes the account with the RSA public key. This function can be called only once.
+     * @dev Initializes the signer with the RSA public key. This function can be called only once.
      */
     function _initializeSigner(bytes memory e, bytes memory n) internal {
-        if (_e.length != 0 || _n.length != 0) revert AccountRSAUninitializedSigner(e, n);
+        if (_e.length != 0 || _n.length != 0) revert SignerRSAUninitializedSigner(e, n);
         _e = e;
         _n = n;
     }
 
     /**
-     * @dev Return the account's signer RSA public key.
+     * @dev Return the signer's RSA public key.
      */
     function signer() public view virtual returns (bytes memory e, bytes memory n) {
         return (_e, _n);
     }
 
-    /**
-     * @dev Validates the signature using the account's signer.
-     */
+    /// @inheritdoc AbstractSigner
     function _rawSignatureValidation(
         bytes32 hash,
         bytes calldata signature

contracts/utils/cryptography/draft-ERC7739Signer.sol

@@ -18,9 +18,11 @@ import {ERC7739Utils} from "./draft-ERC7739Utils.sol";
  * This contract requires implementing the {_rawSignatureValidation} function, which passes the wrapped message hash,
  * which may be either an typed data or a personal sign nested type.
  *
- * NOTE: {EIP712} uses {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).
+ * NOTE: https://docs.openzeppelin.com/contracts/api/utils#EIP712[EIP-712] uses
+ * https://docs.openzeppelin.com/contracts/api/utils#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
+ * https://eips.ethereum.org/EIPS/eip-7562#storage-rules[ERC-7562 storage access rules]).
  */
 abstract contract ERC7739Signer is AbstractSigner, EIP712, IERC1271 {
     using ERC7739Utils for *;

contracts/utils/cryptography/draft-ERC7739Utils.sol

@@ -7,18 +7,20 @@ pragma solidity ^0.8.20;
  * 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 application's {EIP712-_domainSeparatorV4} and preserves
- * readability of the signed content using an EIP-712 nested approach.
+ * rehashing mechanism that includes the application's
+ * https://docs.openzeppelin.com/contracts/api/utils#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:
  *
- * - As an application validating a typed data signature. See {toNestedTypedDataHash}.
- * - As a smart contract validating a raw message signature. See {toNestedPersonalSignHash}.
+ * - As an application validating a typed data signature. See {typedDataSignStructHash}.
+ * - As a smart contract validating a raw message signature. See {personalSignStructHash}.
  *
  * NOTE: 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} signature, as is for example specified for {EIP712}.
+ * of an https://docs.openzeppelin.com/contracts/api/utils#ECDSA[ECDSA] signature, as is for
+ * example specified for https://docs.openzeppelin.com/contracts/api/utils#EIP712[EIP-712].
  */
 library ERC7739Utils {
     /**