.. _v3-package-specification: V3 Specification ================ .. 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. - To ensure backwards compatibility, `manifest_version` is a forbidden top-level key. ---- 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`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``manifest`` field defines the specification version that this document conforms to. - Packages **must** include this field. :Required: Yes :Key: ``manifest`` :Type: String :Allowed Values: ``ethpm/3`` .. _package-names: ---- Package Name: ``name`` ~~~~~~~~~~~~~~~~~~~~~~ The ``name`` field defines a human readable name for this package. - Packages **should** include this field to be released on an EthPM registry. - 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: If ``version`` is included. :Key: ``name`` :Type: String :Format: **must** match the regular expression ``^[a-z][-a-z0-9]{0,255}$`` ---- Package Version: ``version`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``version`` field declares the version number of this release. - Packages **should** include this field to be released on an EthPM registry. - This value **should** conform to the `semver `__ version numbering specification. :Required: If ``name`` is included. :Key: ``version`` :Type: String ---- Package Metadata: ``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`_ ---- 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. :Required: No :Key: ``sources`` :Type: Object (String: `Sources Object`_) ---- Contract Types: ``contractTypes`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``contractTypes`` field hosts 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. :Required: No :Key: ``contractTypes`` :Type: Object (String: `Contract Type Object`_) :Format: - Keys **must** be valid |ContractAliases|. - Values **must** conform to the `Contract Type Object`_ definition. ---- Compilers: ``compilers`` ~~~~~~~~~~~~~~~~~~~~~~~~ The ``compilers`` field holds the information about the compilers and their settings that have been used to generate the various ``contractTypes`` included in this release. :Required: No :Key: ``compilers`` :Type: Array (`the Compiler Information object`_) ---- 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. :Required: No :Key: ``deployments`` :Type: Object (String: Object(String: `Contract Instance Object`_)) :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`_. ---- Build Dependencies: ``buildDependencies`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``buildDependencies`` field defines a key/value mapping of Ethereum |Packages| that this project depends on. :Required: No :Key: ``buildDependencies`` :Type: Object (String: String) :Format: - Keys **must** be valid `package-names`_. - Values **must** be a |ContentAddressableURI| which resolves to a valid package that conforms the same EthPM manifest version as its parent. ---- 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: 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: The *Link Value* Object ~~~~~~~~~~~~~~~~~~~~~~~ Describes a single |LinkValue|. A **Link Value object** is defined to have the following key/value pairs. .. _offset-offset-1: 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 |ContractInstanceName|. - 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: ``linkReferences`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``linkReferences`` 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: ``linkDependencies`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``linkDependencies`` 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 ``linkReferences`` field. - The length of the resolved ``value`` **must** be equal to the ``length`` of the corresponding |LinkReference|. ---- .. _Package Meta Object: 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) .. _Meta License: License: ``license`` ^^^^^^^^^^^^^^^^^^^^ The ``license`` field declares the license associated with this package. This value **should** conform to the `SPDX `__ format. Packages **should** include this field. If a file `Source Object`_ defines its own license, that license takes precedence for that particular file over this package-scoped ``meta`` license. :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: Array(String) 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) ---- .. _Sources Object: The *Sources* Object ~~~~~~~~~~~~~~~~~~~~ A *Sources* object is defined to have the following fields. :Key: A unique identifier for the source file. (string) :Value: `SourceObject`_ .. _SourceObject: Source Object ^^^^^^^^^^^^^ Checksum: ``checksum`` ^^^^^^^^^^^^^^^^^^^^^^ Hash of the source file. :Required: **If** there are no URLs present that contain a content hash. :Key: ``checksum`` :Value: `ChecksumObject`_ URLs: ``urls`` ^^^^^^^^^^^^^^ Array of urls that resolve to the same source file. - Urls **should** be stored on a content-addressable filesystem. **If** they are not, then either ``content`` or ``checksum`` **must** be included. - Urls **must** be prefixed with a scheme. - 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. :Required: If ``content`` is not included. :Key: ``urls`` :Value: Array(string) Content: ``content`` ^^^^^^^^^^^^^^^^^^^^ Inlined contract source. :Required: If ``urls`` is not included. :Key: ``content`` :Value: string Install Path: ``installPath`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Filesystem path of source file. - **Must** be a relative filesystem path that begins with a ``./``. - **Must** resolve to a path that is within the current virtual working directory. - **Must** be unique across all included sources. - While this field might not be directly useful for certain compilers (i.e. Vyper), it is still required to ensure cross-tooling compatibility of packages. :Required: This field **must** be included for the package to be writable to disk. :Key: ``installPath`` :Value: string Type: ``type`` ^^^^^^^^^^^^^^ The ``type`` field declares the type of the source file. The field **should** be one of the following values: ``solidity``, ``vyper``, ``abi-json``, ``solidity-ast-json``. :Required: No :Key: ``type`` :Type: String License: ``license`` ^^^^^^^^^^^^^^^^^^^^ The ``license`` field declares the type of license associated with this source file. When defined, this license overrides the package-scoped `Meta License`_. :Required: No :Key: ``license`` :Type: String ---- .. _ChecksumObject: The *Checksum* Object ~~~~~~~~~~~~~~~~~~~~~~~~~~ A *Checksum* object is defined to have the following key/value pairs. Algorithm: ``algorithm`` ^^^^^^^^^^^^^^^^^^^^^^^^ The ``algorithm`` used to generate the corresponding hash. :Required: Yes :Type: String Hash: ``hash`` ^^^^^^^^^^^^^^ The ``hash`` of a source files contents generated with the corresponding algorithm. :Required: Yes :Type: String ---- .. _Contract Type Object: The *Contract Type* Object ~~~~~~~~~~~~~~~~~~~~~~~~~~ A *Contract Type* object is defined to have the following key/value pairs. Contract Name: ``contractName`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``contractName`` 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|. Source ID: ``sourceId`` ^^^^^^^^^^^^^^^^^^^^^^^ The global source identifier for the source file from which this contract type was generated. :Required: No :Type: String :Value: **Must** match a unique source ID included in the `Sources Object`_ for this package. Deployment Bytecode: ``deploymentBytecode`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``deploymentBytecode`` field defines the bytecode for this |ContractType|. :Required: No :Type: Object :Format: **Must** conform to `the Bytecode Object`_ format. Runtime Bytecode: ``runtimeBytecode`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``runtimeBytecode`` 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: Array :Format: **Must** conform to the `Ethereum Contract ABI JSON format `_. UserDoc: ``userdoc`` ^^^^^^^^^^^^^^^^^^^^ :Required: No :Type: Object :Format: **Must** conform to the `UserDoc `_ format. DevDoc: ``devdoc`` ^^^^^^^^^^^^^^^^^^^^ :Required: No :Type: Object :Format: **Must** conform to the `DevDoc `_ format. ---- .. _Contract Instance Object: 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: ``contractType`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``contractType`` 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 ``buildDependencies`` 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 ``contractTypes`` 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 ``buildDependencies`` of this Package. - The ```` value **must** be be a valid |ContractAlias|. - The resolved package for ```` must contain the ```` value in the keys of the ``contractTypes`` section. .. _address: 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-1: Runtime Bytecode: ``runtimeBytecode`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``runtimeBytecode`` field defines the runtime portion of bytecode for this |ContractInstance|. When present, the value from this field supersedes the ``runtimeBytecode`` from the |ContractType| for this |ContractInstance|. :Required: No :Type: Object :Format: **must** conform to `the Bytecode Object`_ format. Every entry in the ``linkReferences`` for this bytecode **must** have a corresponding entry in the ``linkDependencies`` section. ---- .. _compiler information object: The *Compiler Information* Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``compilers`` field defines the various compilers and settings used during compilation of any |ContractTypes| or |ContractInstance| included in this pacakge. 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-1: 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 Contract Types: ``contractTypes`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A list of the |ContractAlias| in this package that used this compiler to generate its outputs. - All ``contractTypes`` that locally declare ``runtimeBytecode`` **should** be attributed for by a compiler object. - A single ``contractTypes`` **must** not be attributed to more than one compiler. :Required: No :Key: ``contractTypes`` :Type: Array(|ContractAlias|) ---- .. _bip122-bip122-1: 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).