Merge pull request ethereum#2 from xDeSAT/feat/use-erc7578-name

Improve documentation and standard naming

ERCS/erc-7578.md

@@ -59,8 +59,8 @@ When a token has a valid properties, if the token burns, the properties MUST be
 pragma solidity ^0.8.21;
 
 /**
- * @notice A struct containing data for redemption properties
- * @param tokenIssuer The network or entity minting the tokens
+ * @notice Struct encapsulating fields required to by the ERC-7578 standard to represent the physical asset
+ * @param tokenIssuer The network or entity minting the token
  * @param assetHolder The legal owner of the physical asset
  * @param storedLocation The physical storage location
  * @param terms Link to IPFS contract, agreement or terms
@@ -77,7 +77,7 @@ struct Properties {
 }
 
 /**
- * @notice A struct for amount values
+ * @notice Struct encapsulating fields describing the declared value of the physical asset
  * @param currency The currency of the amount
  * @param value The value of the amount
  */
@@ -87,32 +87,38 @@ struct Amount {
 }
 
 /**
- * @notice Interface for the PhysicalAssetRedemption contract
+ * @notice Required interface of an ERC-7578 compliant contract
  */
-interface IPhysicalAssetRedemption {
+interface IERC7578 {
     /**
-     * @notice Emitted when properties are set
+     * @notice Emitted when the properties of the `tokenId` token are set
+     *
      * @param tokenId The ID of the token
      * @param properties The properties of the token
      */
     event PropertiesSet(uint256 indexed tokenId, Properties properties);
 
     /**
-     * @notice Emitted when properties are removed
+     * @notice Emitted when the properties of the `tokenId` token are removed
+     *
      * @param tokenId The ID of the token
      * @param properties The properties of the token
      */
     event PropertiesRemoved(uint256 indexed tokenId, Properties properties);
 
     /**
-     * @notice Retrieves all the properties of a token
+     * @notice Retrieves all the properties of the `tokenId` token
+     * @dev Does NOT revert if token doesn't exist
      * @param tokenId The token ID of the minted token
      */
     function getProperties(uint256 tokenId) external view returns (Properties memory properties);
 
     /**
-     * @notice Properties required to be set when minting a token
-     * @param tokenId The token ID of the minted token
+     * @notice Sets the properties of the `tokenId` token
+     *
+     * IMPORTANT: Properties required to be set when minting a token
+     *
+     * @param tokenId The ID of the token
      * @param properties The properties of the token
      */
     function setProperties(uint256 tokenId, Properties calldata properties) external;
@@ -143,31 +149,37 @@ This standard is compatible with ERC-721.
 
 ## Reference Implementation
 
-An example of an ERC-721 that includes the Physical Asset Redemption using the OpenZeppelin ERC-721 v5 library:
+An example of an ERC-721 that includes the ERC-7578 using the OpenZeppelin ERC-721 v5 library:
 
 ```solidity
 pragma solidity ^0.8.21;
 
-import { ERC721 } from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
-import { IPhysicalAssetRedemption, Properties, Amount } from "./interfaces/IPhysicalAssetRedemption.sol";
+import { ERC721 } from "@openzeppelin/contracts-v5/token/ERC721/ERC721.sol";
+import { IERC7578, Properties, Amount } from "./interfaces/IERC7578.sol";
 
 /**
- * @title Physical Asset Redemption Contract
+ * @title ERC7578
  * @author DESAT
- * @notice Contract for Physical Asset Redemption Standard
+ * @notice Implementation of the ERC-7578: Physical Asset Redemption standard
  **/
-contract PhysicalAssetRedemption is IPhysicalAssetRedemption, ERC721 {
+contract ERC7578 is IERC7578, ERC721 {
     /**
-     * @notice Constructor for the PhysicalAssetRedemption contract
-     * @param _name The name of the token
-     * @param _symbol The symbol of the token
+     * @notice Thrown when the properties of a token are not initialized
      */
-    constructor(string memory _name, string memory _symbol) ERC721(_name, _symbol) {}
+    error PropertiesUninitialized();
 
+    /**
+     * @notice Retrieves the properties of the `tokenId` token
+     */
     mapping(uint256 tokenId => Properties) private _properties;
 
     /**
-     * @inheritdoc IPhysicalAssetRedemption
+     * @notice Initializes the ERC721 dependency contract by setting a `name` and a `symbol` to the token collection
+     */
+    constructor(string memory _name, string memory _symbol) ERC721(_name, _symbol) {}
+
+    /**
+     * @inheritdoc IERC7578
      */
     function setProperties(uint256 tokenId, Properties calldata properties) public {
         _properties[tokenId] = Properties({
@@ -186,31 +198,32 @@ contract PhysicalAssetRedemption is IPhysicalAssetRedemption, ERC721 {
     }
 
     /**
-     * @inheritdoc IPhysicalAssetRedemption
+     * @inheritdoc IERC7578
      */
     function getProperties(uint256 tokenId) public view override returns (Properties memory properties) {
         properties = _properties[tokenId];
     }
 
     /**
-     * @notice Internal function to remove the properties of a token
-     * @param tokenId The token ID of the minted token
+     * @notice Removes the properties of the `tokenId` token
+     * @param tokenId The ID of the token from which to remove the properties
      */
     function _removeProperties(uint256 tokenId) internal {
         delete _properties[tokenId];
         emit PropertiesRemoved(tokenId, _properties[tokenId]);
     }
 
     /**
-     * @notice Override of the {_update} function to remove the properties of a token or check if they are set before minting
-     * @param tokenId The token ID of the minted or burned token
+     * @notice Override of the {_update} function to remove the properties of the `tokenId` token or
+     * to check if they are set before minting
+     * @param tokenId The ID of the token being minted or burned
      */
     function _update(address to, uint256 tokenId, address auth) internal override returns (address) {
         address from = _ownerOf(tokenId);
         if (to == address(0)) {
             _removeProperties(tokenId);
         } else if (from == address(0)) {
-            require(bytes(_properties[tokenId].tokenIssuer).length != 0, "Properties not initialized");
+            if (bytes(_properties[tokenId].tokenIssuer).length == 0) revert PropertiesUninitialized();
         }
 
         return super._update(to, tokenId, auth);