.. _v2-package-specification: V2 Specification ================ .. warning:: EthPM V2 is now deprecated. All tooling supports V3, and should be updated if not. .. include:: _include.rst This document defines the specification for an EthPM package manifest. A package manifest provides metadata about a |Package|, and in most cases should provide sufficient information about the packaged contracts and its dependencies to do bytecode verification of its contracts. .. only:: asciidoc .. note:: A `hosted version `_ of this specification is available via GitHub Pages. This EIP and the hosted HTML document were both autogenerated from the same documentation source. ---- Guiding Principles ------------------ This specification makes the following assumptions about the document lifecycle. 1. Package manifests are intended to be generated programatically by package management software as part of the release process. 2. Package manifests will be consumed by package managers during tasks like installing package dependencies or building and deploying new releases. 3. Package manifests will typically **not** be stored alongside the source, but rather by package registries *or* referenced by package registries and stored in something akin to IPFS. ---- Conventions ----------- RFC2119 ~~~~~~~ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. - https://www.ietf.org/rfc/rfc2119.txt Prefixed vs Unprefixed ~~~~~~~~~~~~~~~~~~~~~~ A |prefixed| hexadecimal value begins with ``0x``. |Unprefixed| values have no prefix. Unless otherwise specified, all hexadecimal values **should** be represented with the ``0x`` prefix. :Prefixed: ``0xdeadbeef`` :Unprefixed: ``deadbeef`` ---- Document Format --------------- The canonical format is a single JSON object. Packages **must** conform to the following serialization rules. - The document **must** be tightly packed, meaning no linebreaks or extra whitespace. - The keys in all objects must be sorted alphabetically. - Duplicate keys in the same object are invalid. - The document **must** use `UTF-8 `_ encoding. - The document **must** not have a trailing newline. ---- Document Specification ---------------------- The following fields are defined for the package. Custom fields **may** be included. Custom fields **should** be prefixed with ``x-`` to prevent name collisions with future versions of the specification. :See Also: Formalized (`JSON-Schema `_) version of this specification: `package.spec.json `_ :Jump To: `Definitions`_ .. _manifest-version: ---- EthPM Manifest Version: ``manifest_version`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``manifest_version`` field defines the specification version that this document conforms to. Packages **must** include this field. :Required: Yes :Key: ``manifest_version`` :Type: String :Allowed Values: ``2`` .. _package names: ---- Package Name: ``package_name`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``package_name`` field defines a human readable name for this package. Packages **must** include this field. Package names **must** begin with a lowercase letter and be comprised of only lowercase letters, numeric characters, and the dash character ``-``. Package names **must** not exceed 255 characters in length. :Required: Yes :Key: ``package_name`` :Type: String :Format: **must** match the regular expression ``^[a-z][a-z0-9_-]{0,255}$`` ---- Package Meta: ``meta`` ~~~~~~~~~~~~~~~~~~~~~~ The ``meta`` field defines a location for metadata about the package which is not integral in nature for package installation, but may be important or convenient to have on-hand for other reasons. This field **should** be included in all Packages. :Required: No :Key: ``meta`` :Type: `package-meta-object-v2`_ ---- Version: ``version`` ~~~~~~~~~~~~~~~~~~~~ The ``version`` field declares the version number of this release. This value **must** be included in all Packages. This value **should** conform to the `semver `__ version numbering specification. :Required: Yes :Key: ``version`` :Type: String ---- Sources: ``sources`` ~~~~~~~~~~~~~~~~~~~~ The ``sources`` field defines a source tree that **should** comprise the full source tree necessary to recompile the contracts contained in this release. Sources are declared in a key/value mapping. :Key: ``sources`` :Type: Object (String: String) :Format: See Below. Format ^^^^^^ Keys **must** be relative filesystem paths beginning with a ``./``. Paths **must** resolve to a path that is within the current working directory. Values **must** conform to *one of* the following formats. - Source string. - |ContentAddressableURI|. When the value is a source string the key should be interpreted as a file path. - If the resulting document is a directory the key should be interpreted as a directory path. - If the resulting document is a file the key should be interpreted as a file path. ---- Contract Types: ``contract_types`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``contract_types`` field holds the |ContractTypes| which have been included in this release. |Packages| **should** only include contract types that can be found in the source files for this package. Packages **should not** include contract types from dependencies. Packages **should not** include abstract contracts in the contract types section of a release. :Key: ``contract_types`` :Type: Object (String: `contract-type-object-v2`_) :Format: Keys **must** be valid |ContractAliases|. Values **must** conform to the `contract-type-object-v2`_ definition. ---- Deployments: ``deployments`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``deployments`` field holds the information for the chains on which this release has |ContractInstances| as well as the |ContractTypes| and other deployment details for those deployed contract instances. The set of chains defined by the :ref:`BIP122 URI` keys for this object **must** be unique. There cannot be two different URI keys in a deployments field representing the same blockchain. :Key: ``deployments`` :Type: Object (String: Object(String: `contract-instance-object-v2`_)) :Format: See Below. Format ^^^^^^ Keys **must** be a valid BIP122 URI chain definition. Values **must** be objects which conform to the following format. - Keys **must** be valid |ContractInstanceNames|. - Values **must** be a valid `contract-instance-object-v2`_. ---- Build Dependencies: ``build_dependencies`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``build_dependencies`` field defines a key/value mapping of Ethereum |Packages| that this project depends on. :Required: No :Key: ``build_dependencies`` :Type: Object (String: String) :Format: Keys **must** be valid `package names`_ matching the regular expression ``[a-z][-a-z0-9]{0,255}``. Values **must** be a |ContentAddressableURI| which resolves to a valid package. ---- Definitions ----------- Definitions for different objects used within the Package. All objects allow custom fields to be included. Custom fields **should** be prefixed with ``x-`` to prevent name collisions with future versions of the specification. ---- .. _link-reference-object-v2: The *Link Reference* Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~ A |LinkReference| object has the following key/value pairs. All link references are assumed to be associated with some corresponding |Bytecode|. Offsets: ``offsets`` ^^^^^^^^^^^^^^^^^^^^ The ``offsets`` field is an array of integers, corresponding to each of the start positions where the link reference appears in the bytecode. Locations are 0-indexed from the beginning of the bytes representation of the corresponding bytecode. This field is invalid if it references a position that is beyond the end of the bytecode. :Required: Yes :Type: Array Length: ``length`` ^^^^^^^^^^^^^^^^^^ The ``length`` field is an integer which defines the length in bytes of the link reference. This field is invalid if the end of the defined link reference exceeds the end of the bytecode. :Required: Yes :Type: Integer Name: ``name`` ^^^^^^^^^^^^^^ The ``name`` field is a string which **must** be a valid |Identifier|. Any link references which **should** be linked with the same link value **should** be given the same name. :Required: No :Type: String :Format: **must** conform to the |Identifier| format. ---- .. _link-value-object-v2: The *Link Value* Object ~~~~~~~~~~~~~~~~~~~~~~~ Describes a single |LinkValue|. A **Link Value object** is defined to have the following key/value pairs. .. _offset-v2: Offsets: ``offsets`` ^^^^^^^^^^^^^^^^^^^^ The ``offsets`` field defines the locations within the corresponding bytecode where the ``value`` for this link value was written. These locations are 0-indexed from the beginning of the bytes representation of the corresponding bytecode. :Required: Yes :Type: Integer :Format: See Below. **Format** Array of integers, where each integer **must** conform to all of the following. - greater than or equal to zero - strictly less than the length of the unprefixed hexadecimal representation of the corresponding bytecode. Type: ``type`` ^^^^^^^^^^^^^^ The ``type`` field defines the ``value`` type for determining what is encoded when |linking| the corresponding bytecode. :Required: Yes :Type: String :Allowed Values: ``"literal"`` for bytecode literals ``"reference"`` for named references to a particular |ContractInstance| Value: ``value`` ^^^^^^^^^^^^^^^^ The ``value`` field defines the value which should be written when |linking| the corresponding bytecode. :Required: Yes :Type: String :Format: Determined based on ``type``, see below. **Format** For static value *literals* (e.g. address), value **must** be a *byte string* To reference the address of a |ContractInstance| from the current package the value should be the name of that contract instance. - This value **must** be a valid contract instance name. - The chain definition under which the contract instance that this link value belongs to must contain this value within its keys. - This value **may not** reference the same contract instance that this link value belongs to. To reference a contract instance from a |Package| from somewhere within the dependency tree the value is constructed as follows. - Let ``[p1, p2, .. pn]`` define a path down the dependency tree. - Each of ``p1, p2, pn`` **must** be valid package names. - ``p1`` **must** be present in keys of the ``build_dependencies`` for the current package. - For every ``pn`` where ``n > 1``, ``pn`` **must** be present in the keys of the ``build_dependencies`` of the package for ``pn-1``. - The value is represented by the string ``::<...>::`` where all of ````, ````, ```` are valid package names and ```` is a valid |ContractName|. - The ```` value **must** be a valid |ContractInstanceName|. - Within the package of the dependency defined by ````, all of the following must be satisfiable: - There **must** be *exactly* one chain defined under the ``deployments`` key which matches the chain definition that this link value is nested under. - The ```` value **must** be present in the keys of the matching chain. ---- The *Bytecode* Object ~~~~~~~~~~~~~~~~~~~~~ A bytecode object has the following key/value pairs. Bytecode: ``bytecode`` ^^^^^^^^^^^^^^^^^^^^^^ The ``bytecode`` field is a string containing the ``0x`` prefixed hexadecimal representation of the bytecode. :Required: Yes :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: No :Type: Array :Format: All values **must** be valid :ref:`Link Reference objects `. See also below. **Format** This field is considered invalid if *any* of the |LinkReferences| are invalid when applied to the corresponding ``bytecode`` field, *or* if any of the link references intersect. Intersection is defined as two link references which overlap. Link Dependencies: ``link_dependencies`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``link_dependencies`` defines the |LinkValues| that have been used to link the corresponding bytecode. :Required: No :Type: Array :Format: All values **must** be valid :ref:`Link Value objects `. See also below. **Format** Validation of this field includes the following: - Two link value objects **must not** contain any of the same values for ``offsets``. - Each :ref:`link value object ` **must** have a corresponding :ref:`link reference object ` under the ``link_references`` field. - The length of the resolved ``value`` **must** be equal to the ``length`` of the corresponding |LinkReference|. ---- .. _package-meta-object-v2: The *Package Meta* Object ~~~~~~~~~~~~~~~~~~~~~~~~~ The *Package Meta* object is defined to have the following key/value pairs. Authors: ``authors`` ^^^^^^^^^^^^^^^^^^^^ The ``authors`` field defines a list of human readable names for the authors of this package. Packages **may** include this field. :Required: No :Key: ``authors`` :Type: Array (String) License: ``license`` ^^^^^^^^^^^^^^^^^^^^ The ``license`` field declares the license under which this package is released. This value **should** conform to the `SPDX `__ format. Packages **should** include this field. :Required: No :Key: ``license`` :Type: String Description: ``description`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``description`` field provides additional detail that may be relevant for the package. Packages **may** include this field. :Required: No :Key: ``description`` :Type: String Keywords: ``keywords`` ^^^^^^^^^^^^^^^^^^^^^^ The ``keywords`` field provides relevant keywords related to this package. :Required: No :Key: ``keywords`` :Type: List of Strings Links: ``links`` ^^^^^^^^^^^^^^^^ The ``links`` field provides URIs to relevant resources associated with this package. When possible, authors **should** use the following keys for the following common resources. - ``website``: Primary website for the package. - ``documentation``: Package Documentation - ``repository``: Location of the project source code. :Key: ``links`` :Type: Object (String: String) ---- .. _contract-type-object-v2: The *Contract Type* Object ~~~~~~~~~~~~~~~~~~~~~~~~~~ A *Contract Type* object is defined to have the following key/value pairs. Contract Name: ``contract_name`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``contract_name`` field defines the |ContractName| for this |ContractType|. :Required: If the |ContractName| and |ContractAlias| are not the same. :Type: String :Format: **must** be a valid |ContractName|. Deployment Bytecode: ``deployment_bytecode`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``deployment_bytecode`` field defines the bytecode for this |ContractType|. :Required: No :Type: Object :Format: **must** conform to `the Bytecode Object`_ format. Runtime Bytecode: ``runtime_bytecode`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``runtime_bytecode`` field defines the unlinked ``0x``-prefixed runtime portion of |Bytecode| for this |ContractType|. :Required: No :Type: Object :Format: **must** conform to `the Bytecode Object`_ format. ABI: ``abi`` ^^^^^^^^^^^^ :Required: No :Type: List :Format: **must** conform to the `Ethereum Contract ABI JSON format `_. Natspec: ``natspec`` ^^^^^^^^^^^^^^^^^^^^ :Required: No :Type: Object :Format: The union of the `UserDoc `_ and `DevDoc `_ formats. Compiler: ``compiler`` ^^^^^^^^^^^^^^^^^^^^^^ :Required: No :Type: Object :Format: **must** conform to `the Compiler Information object`_ format. ---- .. _contract-instance-object-v2: The *Contract Instance* Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A **Contract Instance Object** represents a single deployed |ContractInstance| and is defined to have the following key/value pairs. Contract Type: ``contract_type`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``contract_type`` field defines the |ContractType| for this |ContractInstance|. This can reference any of the contract types included in this |Package| *or* any of the contract types found in any of the package dependencies from the ``build_dependencies`` section of the |PackageManifest|. :Required: Yes :Type: String :Format: See Below. **Format** Values for this field **must** conform to *one of* the two formats herein. To reference a contract type from this Package, use the format ````. - The ```` value **must** be a valid |ContractAlias|. - The value **must** be present in the keys of the ``contract_types`` section of this Package. To reference a contract type from a dependency, use the format ``:``. - The ```` value **must** be present in the keys of the ``build_dependencies`` of this Package. - The ```` value **must** be be a valid |ContractAlias|. - The resolved package for ```` must contain the ```` value in the keys of the ``contract_types`` section. Address: ``address`` ^^^^^^^^^^^^^^^^^^^^ The ``address`` field defines the |Address| of the |ContractInstance|. :Required: Yes :Type: String :Format: Hex encoded ``0x`` prefixed Ethereum address matching the regular expression ``0x[0-9a-fA-F]{40}``. Transaction: ``transaction`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``transaction`` field defines the transaction hash in which this |ContractInstance| was created. :Required: No :Type: String :Format: ``0x`` prefixed hex encoded transaction hash. Block: ``block`` ^^^^^^^^^^^^^^^^ The ``block`` field defines the block hash in which this the transaction which created this *contract instance* was mined. :Required: No :Type: String :Format: ``0x`` prefixed hex encoded block hash. Runtime Bytecode: ``runtime_bytecode`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``runtime_bytecode`` field defines the runtime portion of bytecode for this |ContractInstance|. When present, the value from this field supersedes the ``runtime_bytecode`` from the |ContractType| for this |ContractInstance|. :Required: No :Type: Object :Format: **must** conform to `the Bytecode Object`_ format. Every entry in the ``link_references`` for this bytecode **must** have a corresponding entry in the ``link_dependencies`` section. Compiler: ``compiler`` ^^^^^^^^^^^^^^^^^^^^^^ The ``compiler`` field defines the compiler information that was used during compilation of this |ContractInstance|. This field **should** be present in all |ContractTypes| which include ``bytecode`` or ``runtime_bytecode``. :Required: No :Type: Object :Format: **must** conform to the `compiler-information-object-v2`_ format. ---- .. _compiler-information-object-v2: The *Compiler Information* Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``compiler`` field defines the compiler information that was used during compilation of this |ContractInstance|. This field **should** be present in all contract instances that locally declare ``runtime_bytecode``. A *Compiler Information* object is defined to have the following key/value pairs. Name ``name`` ^^^^^^^^^^^^^ The ``name`` field defines which compiler was used in compilation. :Required: Yes :Key: ``name`` :Type: String Version: ``version`` ^^^^^^^^^^^^^^^^^^^^ The ``version`` field defines the version of the compiler. The field **should** be OS agnostic (OS not included in the string) and take the form of either the stable version in `semver `__ format or if built on a nightly should be denoted in the form of ``-`` ex: ``0.4.8-commit.60cc1668``. :Required: Yes :Key: ``version`` :Type: String Settings: ``settings`` ^^^^^^^^^^^^^^^^^^^^^^ The ``settings`` field defines any settings or configuration that was used in compilation. For the ``"solc"`` compiler, this **should** conform to the `Compiler Input and Output Description `_. :Required: No :Key: ``settings`` :Type: Object ---- .. _bip122-v2: BIP122 URIs ~~~~~~~~~~~ BIP122 URIs are used to define a blockchain via a subset of the `BIP-122 `__ spec. :: blockchain:///block/ The ```` represents the blockhash of the first block on the chain, and ```` represents the hash of the latest block that's been reliably confirmed (package managers should be free to choose their desired level of confirmations).