Setup documentation

Author: ernestognw

contracts/access/README.adoc

@@ -0,0 +1,15 @@
+= Utilities
+
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/community-contracts/proxy
+
+This directory contains utility contracts to restrict access control in smart contracts. These include:
+
+ * {AccessManagerLight}: A simpler version of an AccessManager that uses `bytes8` roles to allow function calls identified by their 4-bytes selector.
+
+== AccessManager
+
+{{AccessManagerLight}}
+
+
+

contracts/access/manager/AccessManagerLight.sol

@@ -5,84 +5,104 @@ pragma solidity ^0.8.20;
 import {IAuthority} from "@openzeppelin/contracts/access/manager/IAuthority.sol";
 import {Masks} from "../../utils/Masks.sol";
 
+/**
+ * @dev Light version of an AccessManager contract that defines `bytes8` roles
+ * that are stored as requirements (see {getRequirements}) for each function.
+ *
+ * Each requirement is a bitmask of roles that are allowed to call a function
+ * identified by its `bytes4` selector. Users have their permissioned stored
+ * as a bitmask of roles they belong to.
+ *
+ * The admin role is a special role that has access to all functions and can
+ * manage the roles of other users.
+ */
 contract AccessManagerLight is IAuthority {
     using Masks for *;
 
-    uint8 public constant ADMIN = 0x00;
-    uint8 public constant PUBLIC = 0xFF;
-    Masks.Mask public immutable ADMIN_MASK = ADMIN.toMask();
-    Masks.Mask public immutable PUBLIC_MASK = PUBLIC.toMask();
+    uint8 public constant ADMIN_ROLE = 0x00;
+    uint8 public constant PUBLIC_ROLE = 0xFF;
+    Masks.Mask public immutable ADMIN_MASK = ADMIN_ROLE.toMask();
+    Masks.Mask public immutable PUBLIC_MASK = PUBLIC_ROLE.toMask();
 
-    mapping(address => Masks.Mask) private _permissions;
-    mapping(address => mapping(bytes4 => Masks.Mask)) private _restrictions;
+    mapping(address => Masks.Mask) private _groups;
+    mapping(address => mapping(bytes4 => Masks.Mask)) private _requirements;
     mapping(uint8 => Masks.Mask) private _admin;
 
     event GroupAdded(address indexed user, uint8 indexed group);
     event GroupRemoved(address indexed user, uint8 indexed group);
     event GroupAdmins(uint8 indexed group, Masks.Mask admins);
-    event Requirements(address indexed target, bytes4 indexed selector, Masks.Mask groups);
+    event RequirementsSet(address indexed target, bytes4 indexed selector, Masks.Mask groups);
 
-    error MissingPermissions(address user, Masks.Mask permissions, Masks.Mask restriction);
+    error MissingPermissions(address user, Masks.Mask permissions, Masks.Mask requirement);
 
-    modifier onlyRole(Masks.Mask restriction) {
+    /// @dev Throws if the specified requirement is not met by the caller's permissions (see {getGroups}).
+    modifier onlyRole(Masks.Mask requirement) {
         Masks.Mask permissions = getGroups(msg.sender);
-        if (permissions.intersection(restriction).isEmpty()) {
-            revert MissingPermissions(msg.sender, permissions, restriction);
+        if (permissions.intersection(requirement).isEmpty()) {
+            revert MissingPermissions(msg.sender, permissions, requirement);
         }
         _;
     }
 
+    /// @dev Initializes the contract with the `admin` as the first member of the admin group.
     constructor(address admin) {
         _addGroup(admin, 0);
     }
 
-    // Getters
+    /// @dev Returns whether the `caller` has the required permissions to call the `target` with the `selector`.
     function canCall(address caller, address target, bytes4 selector) public view returns (bool) {
         return !getGroups(caller).intersection(getRequirements(target, selector)).isEmpty();
     }
 
+    /// @dev Returns the groups that the `user` belongs to.
     function getGroups(address user) public view returns (Masks.Mask) {
-        return _permissions[user].union(PUBLIC_MASK);
+        return _groups[user].union(PUBLIC_MASK);
     }
 
+    /// @dev Returns the admins of the `group`.
     function getGroupAdmins(uint8 group) public view returns (Masks.Mask) {
         return _admin[group].union(ADMIN_MASK); // Admin have power over all groups
     }
 
+    /// @dev Returns the requirements for the `target` and `selector`.
     function getRequirements(address target, bytes4 selector) public view returns (Masks.Mask) {
-        return _restrictions[target][selector].union(ADMIN_MASK); // Admins can call an function
+        return _requirements[target][selector].union(ADMIN_MASK); // Admins can call an function
     }
 
-    // Group management
+    /// @dev Adds the `user` to the `group`. Emits {GroupAdded} event.
     function addGroup(address user, uint8 group) public onlyRole(getGroupAdmins(group)) {
         _addGroup(user, group);
     }
 
+    /// @dev Removes the `user` from the `group`. Emits {GroupRemoved} event.
     function remGroup(address user, uint8 group) public onlyRole(getGroupAdmins(group)) {
         _remGroup(user, group);
     }
 
+    /// @dev Internal version of {addGroup} without access control.
     function _addGroup(address user, uint8 group) internal {
-        _permissions[user] = _permissions[user].union(group.toMask());
+        _groups[user] = _groups[user].union(group.toMask());
         emit GroupAdded(user, group);
     }
 
+    /// @dev Internal version of {remGroup} without access control.
     function _remGroup(address user, uint8 group) internal {
-        _permissions[user] = _permissions[user].difference(group.toMask());
+        _groups[user] = _groups[user].difference(group.toMask());
         emit GroupRemoved(user, group);
     }
 
-    // Group admin management
+    /// @dev Sets the `admins` of the `group`. Emits {GroupAdmins} event.
     function setGroupAdmins(uint8 group, uint8[] calldata admins) public onlyRole(ADMIN_MASK) {
         _setGroupAdmins(group, admins.toMask());
     }
 
+    /// @dev Internal version of {_setGroupAdmins} without access control.
     function _setGroupAdmins(uint8 group, Masks.Mask admins) internal {
         _admin[group] = admins;
         emit GroupAdmins(group, admins);
     }
 
-    // Requirement management
+    /// @dev Sets the `groups` requirements for the `selectors` of the `target`.
     function setRequirements(
         address target,
         bytes4[] calldata selectors,
@@ -94,8 +114,9 @@ contract AccessManagerLight is IAuthority {
         }
     }
 
+    /// @dev Internal version of {_setRequirements} without access control.
     function _setRequirements(address target, bytes4 selector, Masks.Mask groups) internal {
-        _restrictions[target][selector] = groups;
-        emit Requirements(target, selector, groups);
+        _requirements[target][selector] = groups;
+        emit RequirementsSet(target, selector, groups);
     }
 }

contracts/mocks/docs/MyStablecoinAllowlist.sol

@@ -0,0 +1,18 @@
+// contracts/MyStablecoinAllowlist.sol
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import {AccessManaged} from "@openzeppelin/contracts/access/manager/AccessManaged.sol";
+import {ERC20Allowlist, ERC20} from "../../token/ERC20/extensions/ERC20Allowlist.sol";
+
+contract MyStablecoinAllowlist is ERC20Allowlist, AccessManaged {
+    constructor(address initialAuthority) ERC20("MyStablecoin", "MST") AccessManaged(initialAuthority) {}
+
+    function allowUser(address user) public restricted {
+        _allowUser(user);
+    }
+
+    function disallowUser(address user) public restricted {
+        _disallowUser(user);
+    }
+}

contracts/proxy/HybridProxy.sol

@@ -7,14 +7,35 @@ import {ERC1967Utils} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Utils.s
 import {Proxy} from "@openzeppelin/contracts/proxy/Proxy.sol";
 import {Address} from "@openzeppelin/contracts/utils/Address.sol";
 
+/**
+ * @dev A version of an ERC-1967 proxy that uses the address stored in the implementation slot as a beacon.
+ *
+ * The design allows to set an initial beacon that the contract may quit by upgrading to its own implementation
+ * afterwards.
+ *
+ * WARNING: 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.
+ */
 contract HybridProxy is Proxy {
+    /**
+     * @dev Initializes the proxy with an initial implementation. If data is present, it will be used to initialize the
+     * implementation using a delegate call.
+     */
     constructor(address implementation, bytes memory data) {
         ERC1967Utils.upgradeToAndCall(implementation, "");
         if (data.length > 0) {
             Address.functionDelegateCall(_implementation(), data);
         }
     }
 
+    /**
+     * @dev Returns the current implementation address according to ERC-1967's implementation slot.
+     *
+     * IMPORTANT: 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.
+     */
     function _implementation() internal view override returns (address) {
         address implementation = ERC1967Utils.getImplementation();
         try IBeacon(implementation).implementation() returns (address result) {

contracts/proxy/README.adoc

@@ -0,0 +1,15 @@
+= Utilities
+
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/community-contracts/proxy
+
+Variants of proxy patterns, which are contracts that allow to forward a call to an implementation contract by using `delegatecall`. This contracts include:
+
+ * {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
+
+{{HybridProxy}}
+
+
+

contracts/token/README.adoc

@@ -0,0 +1,32 @@
+= Utilities
+
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/community-contracts/token
+
+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}: Adapter of the ERC-1363 receiver interface to comply with Chainlink's 667 interface.
+ * {ERC20Allowlist}: Extension of ERC20 with transfers and approvals that require users to be registered into an allowlist.
+ * {ERC20Blocklist}: Extension of ERC20 with transfers and approvals that can be disabled by adding users into a blocklist.
+ * {ERC20Collateral}: Oracle-agnostic extension of ERC20 that limits the total supply based on a collateral amount.
+ * {ERC20Custodian}: Extension of ERC20 that implements an access-control agnostic approach to define a custodian that can freeze user's transfers and approvals.
+ * {ERC4626Fees}: ERC4626 vault with fees on entry (deposit/mint) or exit (withdraw/redeem).
+
+== General
+
+{{OnTokenTransferAdapter}}
+
+== ERC20
+
+{{ERC20Allowlist}}
+
+{{ERC20Blocklist}}
+
+{{ERC20Collateral}}
+
+{{ERC20Custodial}}
+
+{{ERC4626Fees}}
+
+
+

contracts/utils/README.adoc

@@ -0,0 +1,21 @@
+= Utilities
+
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/community-contracts/utils
+
+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.
+ * {ERC7739Signer}: An abstract contract to validate signatures following the rehashing scheme from `ERC7739Utils`.
+
+== Cryptography
+
+{{ERC7739Signer}}
+
+{{ERC7739Utils}}
+
+== Libraries
+
+{{Masks}}
+

docs/README.md

@@ -0,0 +1,16 @@
+Documentation is hosted at https://docs.openzeppelin.com/contracts.
+
+All of the content for the site is in this repository. The guides are in the
+[docs](/docs) directory, and the API Reference is extracted from comments in
+the source code. If you want to help improve the content, this is the
+repository you should be contributing to.
+
+[`solidity-docgen`](https://github.com/OpenZeppelin/solidity-docgen) is the
+program that extracts the API Reference from source code.
+
+The [`docs.openzeppelin.com`](https://github.com/OpenZeppelin/docs.openzeppelin.com)
+repository hosts the configuration for the entire site, which includes
+documentation for all of the OpenZeppelin projects.
+
+To run the docs locally you should run `npm run docs:watch` on this
+repository.

docs/antora.yml

@@ -0,0 +1,7 @@
+name: community-contracts
+title: Community Contracts
+version: 0.0.0-alpha.0
+prerelease: true
+nav:
+  - modules/ROOT/nav.adoc
+  - modules/api/nav.adoc

docs/config.js

@@ -0,0 +1,21 @@
+const path = require('path');
+const fs = require('fs');
+
+/** @type import('solidity-docgen/dist/config').UserConfig */
+module.exports = {
+  outputDir: 'docs/modules/api/pages',
+  templates: 'docs/templates',
+  exclude: ['mocks'],
+  pageExtension: '.adoc',
+  pages: (_, file, config) => {
+    // For each contract file, find the closest README.adoc and return its location as the output page path.
+    const sourcesDir = path.resolve(config.root, config.sourcesDir);
+    let dir = path.resolve(config.root, file.absolutePath);
+    while (dir.startsWith(sourcesDir)) {
+      dir = path.dirname(dir);
+      if (fs.existsSync(path.join(dir, 'README.adoc'))) {
+        return path.relative(sourcesDir, dir) + config.pageExtension;
+      }
+    }
+  },
+};