From 4c2cf99b22b6db075d2a32215fe65d5ed997d8bd Mon Sep 17 00:00:00 2001 From: Nick Gheorghita Date: Thu, 23 Aug 2018 19:57:40 -0600 Subject: [PATCH 1/2] Update bytecode object in docs --- docs/source/package-spec.rst | 51 +++++++++++++++++++++++++++--------- 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/docs/source/package-spec.rst b/docs/source/package-spec.rst index 6e0a346..1317d65 100644 --- a/docs/source/package-spec.rst +++ b/docs/source/package-spec.rst @@ -405,10 +405,10 @@ within the dependency tree the value is constructed as follows. ---- -The *Bytecode* Object -~~~~~~~~~~~~~~~~~~~~~ +The *UnlinkedBytecode* Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A bytecode object has the following key/value pairs. +An unlinked bytecode object, representing a |ContractType|, has the following key/value pairs. Bytecode: ``bytecode`` ^^^^^^^^^^^^^^^^^^^^^^ @@ -420,14 +420,13 @@ hexadecimal representation of the bytecode. :Type: String :Format: ``0x`` prefixed hexadecimal. - Link References: ``link_references`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``link_references`` field defines the locations in the corresponding -bytecode which require |linking|. +bytecode which require |linking|. If bytecode contains no link references, this field should be an empty array. - :Required: No + :Required: Yes :Type: Array :Format: All values **must** be valid :ref:`Link Reference objects `. See also below. @@ -440,17 +439,45 @@ any of the link references intersect. Intersection is defined as two link references which overlap. +---- + +The *LinkedBytecode* Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A linked bytecode object, representing a deployed |ContractInstance|, has the following key/value pairs. + Link Dependencies: ``link_dependencies`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``link_dependencies`` defines the |LinkValues| that have been used to link the corresponding bytecode. - :Required: No + :Required: Yes :Type: Array :Format: All values **must** be valid :ref:`Link Value objects `. See also below. +Bytecode: ``bytecode`` +^^^^^^^^^^^^^^^^^^^^^^ + +The ``bytecode`` field is a string containing the ``0x`` prefixed +hexadecimal representation of the bytecode. + + :Required: Only if a |LinkValue| differs from its corresponding |ContractType|. + :Type: String + :Format: ``0x`` prefixed hexadecimal. + +Link References: ``link_references`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``link_references`` field defines the locations in the corresponding +bytecode which require |linking|. + + :Required: Only if a |LinkValue| differs from its corresponding |ContractType|. + :Type: Array + :Format: All values **must** be valid :ref:`Link Reference objects `. + See also below. + **Format** Validation of this field includes the following: @@ -459,8 +486,8 @@ Validation of this field includes the following: ``offsets``. - Each :ref:`link value object ` **must** have a - corresponding :ref:`link reference object ` under - the ``link_references`` field. + corresponding :ref:`link reference object ` in its + corresponding |ContractType| or in the ``link_references`` field. - The length of the resolved ``value`` **must** be equal to the ``length`` of the corresponding |LinkReference|. @@ -561,7 +588,7 @@ The ``deployment_bytecode`` field defines the bytecode for this |ContractType|. :Required: No :Type: Object - :Format: **must** conform to `the Bytecode Object`_ format. + :Format: **must** conform to `the UnlinkedBytecode Object`_ format. Runtime Bytecode: ``runtime_bytecode`` @@ -572,7 +599,7 @@ runtime portion of |Bytecode| for this |ContractType|. :Required: No :Type: Object - :Format: **must** conform to `the Bytecode Object`_ format. + :Format: **must** conform to `the UnlinkedBytecode Object`_ format. ABI: ``abi`` ^^^^^^^^^^^^ @@ -685,7 +712,7 @@ the ``runtime_bytecode`` from the |ContractType| for this |ContractInstance|. :Required: No :Type: Object - :Format: **must** conform to `the Bytecode Object`_ format. + :Format: **must** conform to `the LinkedBytecode Object`_ format. Every entry in the ``link_references`` for this bytecode **must** have a corresponding entry in the ``link_dependencies`` section. From 7d17b9c777343c635879dc784433d3d5b720407f Mon Sep 17 00:00:00 2001 From: Nick Gheorghita Date: Fri, 24 Aug 2018 11:42:00 -0600 Subject: [PATCH 2/2] Add line about pre-linked libraries --- docs/source/package-spec.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/source/package-spec.rst b/docs/source/package-spec.rst index 1317d65..af4562a 100644 --- a/docs/source/package-spec.rst +++ b/docs/source/package-spec.rst @@ -424,13 +424,24 @@ Link References: ``link_references`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``link_references`` field defines the locations in the corresponding -bytecode which require |linking|. If bytecode contains no link references, this field should be an empty array. +bytecode which require |linking|. If bytecode contains no link references, this field **must** be an empty array. :Required: Yes :Type: Array :Format: All values **must** be valid :ref:`Link Reference objects `. See also below. +Link Dependencies: ``link_dependencies`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``link_dependencies`` defines the |LinkValues| that have been used to link +the corresponding bytecode. For example, if a contract type references a deployed library. + + :Required: No + :Type: Array + :Format: All values **must** be valid :ref:`Link Value objects `. + See also below. + **Format** This field is considered invalid if *any* of the |LinkReferences| are