cerc-io/solidity
10
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update metadata documentation

Browse Source
This commit is contained in:
Alex Beregszaszi 2016-11-30 10:12:28 +00:00 committed by chriseth
parent 6a7ff039df
commit 35325ee7c3
3 changed files with 26 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Changelog.md
View File

@ -1,7 +1,7 @@
### 0.4.7 (unreleased) ### 0.4.7 (unreleased)
Features: Features:
* Code generator: Inject the swarm hash of a metadata file into the bytecode. * Code generator: Inject the Swarm hash of a metadata file into the bytecode.
* Optimizer: Some dead code elimination. * Optimizer: Some dead code elimination.
Bugfixes: Bugfixes:

46
docs/miscellaneous.rst
View File

@ -236,21 +236,21 @@ If ``solc`` is called with the option ``--link``, all input files are interprete
Contract Metadata Contract Metadata
***************** *****************
The Solidity compiler automatically generates a json file, the The Solidity compiler automatically generates a JSON file, the
contract metadata, that contains information about the current contract. contract metadata, that contains information about the current contract.
It can be used to query the compiler version, the sourcecode, the ABI It can be used to query the compiler version, the sources used, the ABI
and NatSpec documentation in order to more safely interact with the contract and NatSpec documentation in order to more safely interact with the contract
and to verify its source code. and to verify its source code.
The compiler appends a swarm hash (32 bytes) of that file to the end of the The compiler appends a Swarm hash of the metadata file to the end of the
bytecode (for details, see below) of each contract, so that you can retrieve bytecode (for details, see below) of each contract, so that you can retrieve
the file in an authenticated way without having to resort to a centralized the file in an authenticated way without having to resort to a centralized
data provider. data provider.
Of course, you have to publish the metadata file to swarm (or some other service) Of course, you have to publish the metadata file to Swarm (or some other service)
so that others can access it. The file can be output by using ``solc --metadata`` so that others can access it. The file can be output by using ``solc --metadata``
and the file will be called ``ContractName_meta.json``. and the file will be called ``ContractName_meta.json``.
It will contain swarm references to the source code, so you have to upload It will contain Swarm references to the source code, so you have to upload
all source files and the metadata file. all source files and the metadata file.
The metadata file has the following format. The example below is presented in a The metadata file has the following format. The example below is presented in a
@ -282,12 +282,13 @@ Comments are of course also not permitted and used here only for explanatory pur
// Required: keccak256 hash of the source file // Required: keccak256 hash of the source file
"keccak256": "0x123...", "keccak256": "0x123...",
// Required (unless "content" is used, see below): URL to the // Required (unless "content" is used, see below): URL to the
// source file, protocol is more or less arbitrary, but a swarm // source file, protocol is more or less arbitrary, but a Swarm
// URL is recommended // URL is recommended
"url": "bzzr://56ab..." "url": "bzzr://56ab..."
}, },
"mortal": { "mortal": {
"keccak256": "0x123...", // Required: keccak256 hash of the source file
"keccak256": "0x234...",
// Required (unless "url" is used): literal contents of the source file // Required (unless "url" is used): literal contents of the source file
"content": "contract mortal is owned { function kill() { if (msg.sender == owner) selfdestruct(owner); } }" "content": "contract mortal is owned { function kill() { if (msg.sender == owner) selfdestruct(owner); } }"
} }
@ -296,15 +297,18 @@ Comments are of course also not permitted and used here only for explanatory pur
settings: settings:
{ {
// Required for Solidity: Sorted list of remappings // Required for Solidity: Sorted list of remappings
remappings: [":g/dir"], remappings: [ ":g/dir" ],
// Optional: Optimizer settings (enabled defaults to false) // Optional: Optimizer settings (enabled defaults to false)
optimizer: {enabled: true, runs: 500}, optimizer: {
enabled: true,
runs: 500
},
// Required for Solidity: File and name of the contract or library this // Required for Solidity: File and name of the contract or library this
// metadata is created for. // metadata is created for.
compilationTarget: { compilationTarget: {
"myFile.sol": "MyContract" "myFile.sol": "MyContract"
}, },
// Required for Solidity: Addresses for libraries // Required for Solidity: Addresses for libraries used
libraries: { libraries: {
"MyLib": "0x123123..." "MyLib": "0x123123..."
} }
@ -326,7 +330,7 @@ Encoding of the Metadata Hash in the Bytecode
--------------------------------------------- ---------------------------------------------
Because we might support other ways to retrieve the metadata file in the future, Because we might support other ways to retrieve the metadata file in the future,
the mapping ``{"bzzr0": <swarm hash>}`` is stored the mapping ``{"bzzr0": <Swarm hash>}`` is stored
[CBOR](https://tools.ietf.org/html/rfc7049)-encoded. Since the beginning of that [CBOR](https://tools.ietf.org/html/rfc7049)-encoded. Since the beginning of that
encoding is not easy to find, its length is added in a two-byte big-endian encoding is not easy to find, its length is added in a two-byte big-endian
encoding. The current version of the Solidity compiler thus adds the following encoding. The current version of the Solidity compiler thus adds the following
@ -334,35 +338,33 @@ to the end of the deployed bytecode::
0xa1 0x65 'b' 'z' 'z' 'r' '0' 0x58 0x20 <32 bytes swarm hash> 0x00 0x29 0xa1 0x65 'b' 'z' 'z' 'r' '0' 0x58 0x20 <32 bytes swarm hash> 0x00 0x29
So in order to retrieve the data, you can check the end of the deployed So in order to retrieve the data, the end of the deployed bytecode can be checked
bytecode to match that pattern and use the swarm hash to retrieve the to match that pattern and use the Swarm hash to retrieve the file.
file.
Usage for Automatic Interface Generation and NatSpec Usage for Automatic Interface Generation and NatSpec
---------------------------------------------------- ----------------------------------------------------
The metadata is used in the following way: A component that wants to interact The metadata is used in the following way: A component that wants to interact
with a contract (e.g. mist) retrieves the code of the contract, from that with a contract (e.g. Mist) retrieves the code of the contract, from that
the swarm hash of a file which is then retrieved. the Swarm hash of a file which is then retrieved.
That file is JSON-decoded into a structure like above. That file is JSON-decoded into a structure like above.
The component can then use the abi to automatically generate a rudimentary The component can then use the ABI to automatically generate a rudimentary
user interface for the contract. user interface for the contract.
Furthermore, mist can use the userdoc to display a confirmation message to the user Furthermore, Mist can use the userdoc to display a confirmation message to the user
whenever they interact with the contract. whenever they interact with the contract.
Usage for Source Code Verification Usage for Source Code Verification
---------------------------------- ----------------------------------
In order to verify the compilation, sources can be retrieved from swarm In order to verify the compilation, sources can be retrieved from Swarm
via the link in the metadata file. via the link in the metadata file.
The compiler of the correct version (which is checked to be part of the "official" compilers) The compiler of the correct version (which is checked to be part of the "official" compilers)
is invoked on that input with the specified settings. The resulting is invoked on that input with the specified settings. The resulting
bytecode is compared to the data of the creation transaction or CREATE opcode data. bytecode is compared to the data of the creation transaction or CREATE opcode data.
This automatically verifies the metadata since This automatically verifies the metadata since its hash is part of the bytecode.
its hash is part of the bytecode. Excess data corresponds to the constructor input data, which should be decoded
Excess data is constructor input data which should be decoded
according to the interface and presented to the user. according to the interface and presented to the user.

2
solc/CommandLineInterface.cpp
View File

@ -482,7 +482,7 @@ Allowed options)",
(g_argSignatureHashes.c_str(), "Function signature hashes of the contracts.") (g_argSignatureHashes.c_str(), "Function signature hashes of the contracts.")
(g_argNatspecUserStr.c_str(), "Natspec user documentation of all contracts.") (g_argNatspecUserStr.c_str(), "Natspec user documentation of all contracts.")
(g_argNatspecDevStr.c_str(), "Natspec developer documentation of all contracts.") (g_argNatspecDevStr.c_str(), "Natspec developer documentation of all contracts.")
(g_argMetadata.c_str(), "Combined metadata JSON whose swarm hash is stored on-chain.") (g_argMetadata.c_str(), "Combined Metadata JSON whose Swarm hash is stored on-chain.")
("formal", "Translated source suitable for formal analysis."); ("formal", "Translated source suitable for formal analysis.");
desc.add(outputComponents); desc.add(outputComponents);