Transpile d438fa08

CHANGELOG.md

@@ -4,7 +4,7 @@
  * Enumerables: Improve gas cost of removal in `EnumerableSet` and `EnumerableMap`.
  * Enumerables: Improve gas cost of lookup in `EnumerableSet` and `EnumerableMap`.
 
-## Unreleased
+## 4.1.0 (2021-04-29)
 
  * `IERC20Metadata`: add a new extended interface that includes the optional `name()`, `symbol()` and `decimals()` functions. ([#2561](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2561))
  * `ERC777`: make reception acquirement optional in `_mint`. ([#2552](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2552))

contracts/access/README.adoc

-= Access
+= Access Control
 
 [.readme-notice]
 NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/access

contracts/package.json

 {
   "name": "@openzeppelin/contracts-upgradeable",
   "description": "Secure Smart Contract library for Solidity",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "files": [
     "**/*.sol",
     "/build/contracts/*.json",

contracts/proxy/README.adoc

@@ -58,10 +58,6 @@ By default, the upgrade functionality included in {UUPSUpgradeable} contains a s
 
 {{ERC1967Upgrade}}
 
-== UUPS
-
-{{UUPSUpgradeable}}
-
 == Transparent Proxy
 
 {{TransparentUpgradeableProxy}}
@@ -83,3 +79,5 @@ By default, the upgrade functionality included in {UUPSUpgradeable} contains a s
 == Utils
 
 {{Initializable}}
+
+{{UUPSUpgradeable}}

contracts/proxy/utils/UUPSUpgradeable.sol

@@ -6,11 +6,14 @@ import "../ERC1967/ERC1967UpgradeUpgradeable.sol";
 import "./Initializable.sol";
 
 /**
- * @dev Base contract for building openzeppelin-upgrades compatible implementations for the {ERC1967Proxy}. It includes
- * publicly available upgrade functions that are called by the plugin and by the secure upgrade mechanism to verify
- * continuation of the upgradability.
+ * @dev An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an
+ * {ERC1967Proxy}, when this contract is set as the implementation behind such a proxy.
  *
- * The {_authorizeUpgrade} function MUST be overridden to include access restriction to the upgrade mechanism.
+ * 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 {_authorizeUpgrade} function must be overridden to include access restriction to the upgrade mechanism.
  *
  * _Available since v4.1._
  */
@@ -22,16 +25,41 @@ abstract contract UUPSUpgradeable is Initializable, ERC1967UpgradeUpgradeable {
 
     function __UUPSUpgradeable_init_unchained() internal initializer {
     }
+    /**
+     * @dev Upgrade the implementation of the proxy to `newImplementation`.
+     *
+     * Calls {_authorizeUpgrade}.
+     *
+     * Emits an {Upgraded} event.
+     */
     function upgradeTo(address newImplementation) external virtual {
         _authorizeUpgrade(newImplementation);
         _upgradeToAndCallSecure(newImplementation, bytes(""), false);
     }
 
+    /**
+     * @dev Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
+     * encoded in `data`.
+     *
+     * Calls {_authorizeUpgrade}.
+     *
+     * Emits an {Upgraded} event.
+     */
     function upgradeToAndCall(address newImplementation, bytes memory data) external payable virtual {
         _authorizeUpgrade(newImplementation);
         _upgradeToAndCallSecure(newImplementation, data, true);
     }
 
+    /**
+     * @dev Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by
+     * {upgradeTo} and {upgradeToAndCall}.
+     *
+     * Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.
+     *
+     * ```solidity
+     * function _authorizeUpgrade(address) internal override onlyOwner {}
+     * ```
+     */
     function _authorizeUpgrade(address newImplementation) internal virtual;
     uint256[50] private __gap;
 }

docs/modules/ROOT/pages/upgradeable.adoc

@@ -6,6 +6,8 @@ This variant is available as a separate package called `@openzeppelin/contracts-
 
 It follows all of the rules for xref:upgrades-plugins::writing-upgradeable.adoc[Writing Upgradeable Contracts]: constructors are replaced by initializer functions, state variables are initialized in initializer functions, and we additionally check for storage incompatibilities across minor versions.
 
+TIP: OpenZeppelin provides a full suite of tools for deploying and securing upgradeable smart contracts. xref:openzeppelin::upgrades.adoc[Check out the full list of resources].
+
 == Overview
 
 === Installation

package.json

@@ -2,7 +2,7 @@
   "private": true,
   "name": "openzeppelin-solidity",
   "description": "Secure Smart Contract library for Solidity",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "files": [
     "/contracts/**/*.sol",
     "/build/contracts/*.json",