From 5849fc3bf154a5ecb90614ec0befdaf591a937f6 Mon Sep 17 00:00:00 2001 From: kuzdogan Date: Thu, 25 Aug 2022 15:25:39 +0200 Subject: [PATCH] Update contract metadata docs --- docs/metadata.rst | 91 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 73 insertions(+), 18 deletions(-) diff --git a/docs/metadata.rst b/docs/metadata.rst index e92a7c0d5..317ad2204 100644 --- a/docs/metadata.rst +++ b/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.