mirror of
https://github.com/ethereum/solidity
synced 2023-10-03 13:03:40 +00:00
Update contract metadata docs
This commit is contained in:
kuzdogan
parent
22a0c46eae
commit
5849fc3bf1
@ -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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user