Clean up metadata and clarify what small changes affect

Updates from review
This commit is contained in:
Chris Ward 2018-08-22 12:53:39 +02:00
parent 410d288dfc
commit 9340fb9881

View File

@ -4,28 +4,28 @@ Contract Metadata
.. index:: metadata, contract verification .. index:: metadata, contract verification
The Solidity compiler automatically generates a JSON file, the The Solidity compiler automatically generates a JSON file, the contract
contract metadata, that contains information about the current contract. metadata, that contains information about the current contract. You can use
It can be used to query the compiler version, the sources used, the ABI this file to query the compiler version, the sources used, the ABI and NatSpec
and NatSpec documentation in order to more safely interact with the contract documentation to more safely interact with the contract and verify its source
and to verify its source code. code.
The compiler appends a Swarm hash of the metadata 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) You have to publish the metadata file to Swarm (or another service) so that
so that others can access it. The file can be output by using ``solc --metadata`` others can access it. You create the file by using the ``solc --metadata``
and the file will be called ``ContractName_meta.json``. command that generates a file called ``ContractName_meta.json``. It contains
It will contain Swarm references to the source code, so you have to upload Swarm references to the source code, so you have to upload all source files and
all source files and the metadata file. 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
human-readable way. Properly formatted metadata should use quotes correctly, human-readable way. Properly formatted metadata should use quotes correctly,
reduce whitespace to a minimum and sort the keys of all objects to arrive at a reduce whitespace to a minimum and sort the keys of all objects to arrive at a
unique formatting. unique formatting. Comments are not permitted and used here only for
Comments are of course also not permitted and used here only for explanatory purposes. explanatory purposes.
.. code-block:: none .. code-block:: none
@ -96,11 +96,11 @@ Comments are of course also not permitted and used here only for explanatory pur
.. note:: .. note::
Note the ABI definition above has no fixed order. It can change with compiler versions. Note the ABI definition above has no fixed order. It can change with compiler versions.
.. note:: Since the bytecode of the resulting contract contains the metadata hash, any
Since the bytecode of the resulting contract contains the metadata hash, any change to change to the metadata results in a change of the bytecode. This includes
the metadata will result in a change of the bytecode. Furthermore, since the metadata changes to a filename or path, and since the metadata includes a hash of all the
includes a hash of all the sources used, a single whitespace change in any of the source sources used, a single whitespace change results in different metadata, and
codes will result in a different metadata, and subsequently a different bytecode. different bytecode.
Encoding of the Metadata Hash in the Bytecode Encoding of the Metadata Hash in the Bytecode
============================================= =============================================
@ -131,7 +131,7 @@ 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.
Additional information about Ethereum Natural Specification (NatSpec) can be found `here <https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format>`_. Additional information about Ethereum Natural Specification (NatSpec) can be found `here <https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format>`_.
Usage for Source Code Verification Usage for Source Code Verification
================================== ==================================