Merge pull request #13397 from kuzdogan/patch-1

Update Metadata docs

Author: Leo

docs/metadata.rst

@@ -46,20 +46,20 @@ explanatory purposes.
       // to the language.
       "compiler": {
         // Required for Solidity: Version of the compiler
-        "version": "0.4.6+commit.2dabbdf0.Emscripten.clang",
+        "version": "0.8.2+commit.661d1103",
         // Optional: Hash of the compiler binary which produced this output
         "keccak256": "0x123..."
       },
-      // Required: Compilation source files/source units, keys are file names
+      // Required: Compilation source files/source units, keys are file paths
       "sources":
       {
-        "myFile.sol": {
+        "myDirectory/myFile.sol": {
           // Required: keccak256 hash of the source file
           "keccak256": "0x123...",
           // Required (unless "content" is used, see below): Sorted URL(s)
-          // to the source file, protocol is more or less arbitrary, but a
-          // Swarm URL is recommended
-          "urls": [ "bzzr://56ab..." ],
+          // to the source file, protocol is more or less arbitrary, but an
+          // IPFS URL is recommended
+          "urls": [ "bzz-raw://7d7a...", "dweb:/ipfs/QmN..." ],
           // Optional: SPDX license identifier as given in the source file
           "license": "MIT"
         },
@@ -73,7 +73,7 @@ explanatory purposes.
       // Required: Compiler settings
       "settings":
       {
-        // Required for Solidity: Sorted list of remappings
+        // Required for Solidity: Sorted list of import remappings
         "remappings": [ ":g=/dir" ],
         // Optional: Optimizer settings. The fields "enabled" and "runs" are deprecated
         // and are only given for backwards-compatibility.
@@ -100,15 +100,15 @@ explanatory purposes.
           }
         },
         "metadata": {
-          // Reflects the setting used in the input json, defaults to false
+          // Reflects the setting used in the input json, defaults to "false"
           "useLiteralContent": true,
           // Reflects the setting used in the input json, defaults to "ipfs"
           "bytecodeHash": "ipfs"
         },
-        // Required for Solidity: File and name of the contract or library this
+        // Required for Solidity: File path and the name of the contract or library this
         // metadata is created for.
         "compilationTarget": {
-          "myFile.sol": "MyContract"
+          "myDirectory/myFile.sol": "MyContract"
         },
         // Required for Solidity: Addresses for libraries used
         "libraries": {
@@ -118,12 +118,66 @@ explanatory purposes.
       // Required: Generated information about the contract.
       "output":
       {
-        // Required: ABI definition of the contract
+        // Required: ABI definition of the contract. See "Contract ABI Specification"
         "abi": [/* ... */],
+        // Required: NatSpec developer documentation of the contract.
+        "devdoc": {
+          "version": 1 // NatSpec version
+          "kind": "dev",
+          // Contents of the @author NatSpec field of the contract
+          "author": "John Doe",
+          // Contents of the @title NatSpec field of the contract
+          "title": "MyERC20: an example ERC20"
+          // Contents of the @dev NatSpec field of the contract
+          "details": "Interface of the ERC20 standard as defined in the EIP. See https://eips.ethereum.org/EIPS/eip-20 for details",
+          "methods": {
+            "transfer(address,uint256)": {
+              // Contents of the @dev NatSpec field of the method
+              "details": "Returns a boolean value indicating whether the operation succeeded. Must be called by the token holder address",
+              // Contents of the @param NatSpec fields of the method
+              "params": {
+                "_value": "The amount tokens to be transferred",
+                "_to": "The receiver address"
+              }
+              // Contents of the @return NatSpec field.
+              "returns": {
+                // Return var name (here "success") if exists. "_0" as key if return var is unnamed
+                "success": "a boolean value indicating whether the operation succeeded"
+              }
+            }
+          },
+          "stateVariables": {
+            "owner": {
+              // Contents of the @dev NatSpec field of the state variable
+              "details": "Must be set during contract creation. Can then only be changed by the owner"
+            }
+          }
+          "events": {
+             "Transfer(address,address,uint256)": {
+               "details": "Emitted when `value` tokens are moved from one account (`from`) toanother (`to`)."
+               "params": {
+                 "from": "The sender address"
+                 "to": "The receiver address"
+                 "value": "The token amount"
+               }
+             }
+          }
+        },
         // Required: NatSpec user documentation of the contract
-        "userdoc": [/* ... */],
-        // Required: NatSpec developer documentation of the contract
-        "devdoc": [/* ... */]
+        "userdoc": {
+          "version": 1 // NatSpec version
+          "kind": "user",
+          "methods": {
+            "transfer(address,uint256)": {
+              "notice": "Transfers `_value` tokens to address `_to`"
+            }
+          },
+          "events": {
+            "Transfer(address,address,uint256)": {
+              "notice": "`_value` tokens have been moved from `from` to `to`"
+            }
+          }
+        }
       }
     }
 
@@ -160,7 +214,7 @@ to the end of the deployed bytecode
     0x00 0x33
 
 So in order to retrieve the data, the end of the deployed bytecode can be checked
-to match that pattern and use the IPFS hash to retrieve the file.
+to match that pattern and the IPFS hash can be used to retrieve the file (if pinned/published).
 
 Whereas release builds of solc use a 3 byte encoding of the version as shown
 above (one byte each for major, minor and patch version number), prerelease builds
@@ -184,14 +238,15 @@ Usage for Automatic Interface Generation and NatSpec
 ====================================================
 
 The metadata is used in the following way: A component that wants to interact
-with a contract (e.g. Mist or any wallet) retrieves the code of the contract,
-from that the IPFS/Swarm hash of a file which is then retrieved.  That file
+with a contract (e.g. a wallet) retrieves the code of the contract.
+It decodes the CBOR encoded section containing the IPFS/Swarm hash of the
+metadata file. With that hash, the metadata file is retrieved. That file
 is JSON-decoded into a structure like above.
 
 The component can then use the ABI to automatically generate a rudimentary
 user interface for the contract.
 
-Furthermore, the wallet can use the NatSpec user documentation to display a confirmation message to the user
+Furthermore, the wallet can use the NatSpec user documentation to display a human-readable confirmation message to the user
 whenever they interact with the contract, together with requesting
 authorization for the transaction signature.