p1r0
/
DCIPs
forked from DecentralizedClimateFoundation/DCIPs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
DCIPs/EIPS/eip-1123.md

1882 lines
45 KiB
Markdown
Raw Normal View History

Adding EIPs website fork with some Gem Updates
2023-04-05 16:02:54 +00:00
---
eip: 1123
title: Revised Ethereum Smart Contract Packaging Standard
author: g. nicholas d’andrea (@gnidan), Piper Merriam (@pipermerriam), Nick Gheorghita (@njgheorghita), Danny Ryan (@djrtwo)
discussions-to: https://github.com/ethereum/EIPs/issues/1123
status: Withdrawn
type: Standards Track
category: ERC
created: 2018-06-01
---
This ERC has been abandoned in favor of the EthPM V3 smart contract packaging standard defined in [ERC-2678](./eip-2678.md)
Simple Summary
==============
A data format describing a smart contract software package.
Abstract
==========
This EIP defines a data format for *package manifest* documents,
representing a package of one or more smart contracts, optionally
including source code and any/all deployed instances across multiple
networks. Package manifests are minified JSON objects, to be distributed
via content addressable storage networks, such as IPFS.
This document presents a natural language description of a formal
specification for version **2** of this format.
Motivation
==========
This standard aims to encourage the Ethereum development ecosystem
towards software best practices around code reuse. By defining an open,
community-driven package data format standard, this effort seeks to
provide support for package management tools development by offering a
general-purpose solution that has been designed with observed common
practices in mind.
As version 2 of this specification, this standard seeks to address a
number of areas of improvement found for the previous version (defined
in
[EIP-190](./eip-190.md)).
This version:
- Generalizes storage URIs to represent any content addressable URI
scheme, not only IPFS.
- Renames *release lockfile* to *package manifest*.
- Adds support for languages other than Solidity by generalizing the
compiler information format.
- Redefines link references to be more flexible, to represent
arbitrary gaps in bytecode (besides only addresses), in a more
straightforward way.
- Forces format strictness, requiring that package manifests contain
no extraneous whitespace, and sort object keys in alphabetical
order, to prevent hash mismatches.
<div id="package-specification"></div>
Specification
=============
This document defines the specification for an EthPM package manifest. A
package manifest provides metadata about a [Package](#term-package), and
in most cases should provide sufficient information about the packaged
contracts and its dependencies to do bytecode verification of its
contracts.
> **Note**
>
> A [hosted
> version](https://ethpm.github.io/ethpm-spec) 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 programmatically 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](#term-prefixed) hexadecimal value begins with `0x`.
[Unprefixed](#term-unprefixed) values have no prefix. Unless otherwise
specified, all hexadecimal values **should** be represented with the
`0x` prefix.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Prefixed</p></td>
<td><p><code>0xdeadbeef</code></p></td>
</tr>
<tr class="even">
<td><p>Unprefixed</p></td>
<td><p><code>deadbeef</code></p></td>
</tr>
</tbody>
</table>
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](https://en.wikipedia.org/wiki/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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>See Also</p></td>
<td><p>Formalized (<a href="https://json-schema.org">JSON-Schema</a>) version of this specification: <a href="https://github.com/ethpm/ethpm-spec/tree/v2.0.0/spec/package.spec.json">package.spec.json</a></p></td>
</tr>
<tr class="even">
<td><p>Jump To</p></td>
<td><p><a href="#definitions">Definitions</a></p></td>
</tr>
</tbody>
</table>
<div id="manifest-version"></div>
### EthPM Manifest Version: `manifest_version`
The `manifest_version` field defines the specification version that this
document conforms to. Packages **must** include this field.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>manifest_version</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="even">
<td><p>Allowed Values</p></td>
<td><p><code>2</code></p></td>
</tr>
</tbody>
</table>
<div id="package-names"></div>
### 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 214 characters in length.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>package_name</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="even">
<td><p>Format</p></td>
<td><p><strong>must</strong> match the regular expression <code>^[a-zA-Z][a-zA-Z0-9_]{0,255}$</code></p></td>
</tr>
</tbody>
</table>
### 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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>meta</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p><a href="#package-meta-object">Package Meta Object</a></p></td>
</tr>
</tbody>
</table>
### 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](https://semver.org/) version
numbering specification.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>version</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
### 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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Key</p></td>
<td><p><code>sources</code></p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object (String: String)</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>See Below.</p></td>
</tr>
</tbody>
</table>
#### 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.
- [Content Addressable URI](#term-content-addressable-uri).
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 [Contract
Types](#term-contract-type) which have been included in this release.
[Packages](#term-package) **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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Key</p></td>
<td><p><code>contract_types</code></p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object (String: <a href="#contract-type-object">Contract Type Object</a>)</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>Keys <strong>must</strong> be valid <a href="#term-contract-alias">Contract Aliases</a>.</p>
<p>Values <strong>must</strong> conform to the <a href="#contract-type-object">Contract Type Object</a> definition.</p></td>
</tr>
</tbody>
</table>
### Deployments: `deployments`
The `deployments` field holds the information for the chains on which
this release has [Contract Instances](#term-contract-instance) as well
as the [Contract Types](#term-contract-type) and other deployment
details for those deployed contract instances. The set of chains defined
by the `*BIP122 URI <#bip122-uris>*` keys for this object **must** be
unique.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Key</p></td>
<td><p><code>deployments</code></p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object (String: Object(String: <a href="#contract-instance-object">Contract Instance Object</a>))</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>See Below.</p></td>
</tr>
</tbody>
</table>
#### Format
Keys **must** be a valid BIP122 URI chain definition.
Values **must** be objects which conform to the following format.
- Keys **must** be valid [Contract Instance
Names](#term-contract-instance-name).
- Values **must** be a valid [Contract Instance
Object](#contract-instance-object).
### Build Dependencies: `build_dependencies`
The `build_dependencies` field defines a key/value mapping of Ethereum
[Packages](#term-package) that this project depends on.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>build_dependencies</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>Object (String: String)</p></td>
</tr>
<tr class="even">
<td><p>Format</p></td>
<td><p>Keys <strong>must</strong> be valid <a href="#package-names">package names</a> matching the regular expression <code>[a-z][-a-z0-9]{0,213}</code>.</p>
<p>Values <strong>must</strong> be valid IPFS URIs which resolve to a valid package.</p></td>
</tr>
</tbody>
</table>
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.
<div id="link-reference-object"></div>
### The *Link Reference* Object
A [Link Reference](#term-link-reference) object has the following
key/value pairs. All link references are assumed to be associated with
some corresponding [Bytecode](#term-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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Array</p></td>
</tr>
</tbody>
</table>
#### 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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Integer</p></td>
</tr>
</tbody>
</table>
#### Name: `name`
The `name` field is a string which **must** be a valid
[Identifier](#term-identifier). Any link references which **should** be
linked with the same link value **should** be given the same name.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> conform to the <a href="#term-identifier">Identifier</a> format.</p></td>
</tr>
</tbody>
</table>
<div id="link-value-object"></div>
### The *Link Value* Object
Describes a single [Link Value](#term-link-value).
A **Link Value object** is defined to have the following key/value
pairs.
<div id="offset-offset-1"></div>
#### 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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Integer</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>See Below.</p></td>
</tr>
</tbody>
</table>
**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](#term-linking) the corresponding bytecode.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Allowed Values</p></td>
<td><p><code>&quot;literal&quot;</code> for bytecode literals</p>
<p><code>&quot;reference&quot;</code> for named references to a particular <a href="#term-contract-instance">Contract Instance</a></p></td>
</tr>
</tbody>
</table>
#### Value: `value`
The `value` field defines the value which should be written when
[linking](#term-linking) the corresponding bytecode.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>Determined based on <code>type</code>, see below.</p></td>
</tr>
</tbody>
</table>
**Format**
For static value *literals* (e.g. address), value **must** be a *byte
string*
To reference the address of a [Contract
Instance](#term-contract-instance) 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](#term-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
`<p1>:<p2>:<...>:<pn>:<contract-instance>` where all of `<p1>`,
`<p2>`, `<pn>` are valid package names and `<contract-instance>` is
a valid [Contract Name](#term-contract-name).
- The `<contract-instance>` value **must** be a valid [Contract
Instance Name](#term-contract-instance-name).
- Within the package of the dependency defined by `<pn>`, 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 `<contract-instance>` 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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><code>0x</code> prefixed hexadecimal.</p></td>
</tr>
</tbody>
</table>
#### Link References: `link_references`
The `link_references` field defines the locations in the corresponding
bytecode which require [linking](#term-linking).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Array</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>All values <strong>must</strong> be valid <a href="#link-reference-object">Link Reference objects</a>. See also below.</p></td>
</tr>
</tbody>
</table>
**Format**
This field is considered invalid if *any* of the [Link
References](#term-link-reference) 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 [Link Values](#term-link-value) that
have been used to link the corresponding bytecode.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Array</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>All values <strong>must</strong> be valid <a href="#link-value-object">Link Value objects</a>. See also below.</p></td>
</tr>
</tbody>
</table>
**Format**
Validation of this field includes the following:
- Two link value objects **must not** contain any of the same values
for `offsets`.
- Each [link value object](#link-value-object) **must** have a
corresponding [link reference object](#link-reference-object) under
the `link_references` field.
- The length of the resolved `value` **must** be equal to the `length`
of the corresponding [Link Reference](#term-link-reference).
<div id="package-meta-object"></div>
### 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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>authors</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>Array (String)</p></td>
</tr>
</tbody>
</table>
#### License: `license`
The `license` field declares the license under which this package is
released. This value **should** conform to the
[SPDX](https://en.wikipedia.org/wiki/Software_Package_Data_Exchange)
format. Packages **should** include this field.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>license</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
#### Description: `description`
The `description` field provides additional detail that may be relevant
for the package. Packages **may** include this field.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>description</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
#### Keywords: `keywords`
The `keywords` field provides relevant keywords related to this package.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>keywords</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>List of Strings</p></td>
</tr>
</tbody>
</table>
#### 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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Key</p></td>
<td><p><code>links</code></p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object (String: String)</p></td>
</tr>
</tbody>
</table>
<div id="contract-type-object"></div>
### 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 [Contract
Name](#term-contract-name) for this [Contract
Type](#term-contract-type).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>If the <a href="#term-contract-name">Contract Name</a> and <a href="#term-contract-alias">Contract Alias</a> are not the same.</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> be a valid <a href="#term-contract-name">Contract Name</a>.</p></td>
</tr>
</tbody>
</table>
#### Deployment Bytecode: `deployment_bytecode`
The `deployment_bytecode` field defines the bytecode for this [Contract
Type](#term-contract-type).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> conform to <a href="#the-bytecode-object">the Bytecode Object</a> format.</p></td>
</tr>
</tbody>
</table>
#### Runtime Bytecode: `runtime_bytecode`
The `runtime_bytecode` field defines the unlinked `0x`-prefixed runtime
portion of [Bytecode](#term-bytecode) for this [Contract
Type](#term-contract-type).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> conform to <a href="#the-bytecode-object">the Bytecode Object</a> format.</p></td>
</tr>
</tbody>
</table>
#### ABI: `abi`
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>List</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> conform to the <a href="https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#json">Ethereum Contract ABI JSON format</a>.</p></td>
</tr>
</tbody>
</table>
#### Natspec: `natspec`
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>The union of the <a href="https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format#user-documentation">UserDoc</a> and <a href="https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format#developer-documentation">DevDoc</a> formats.</p></td>
</tr>
</tbody>
</table>
#### Compiler: `compiler`
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> conform to <a href="#the-compiler-information-object">the Compiler Information object</a> format.</p></td>
</tr>
</tbody>
</table>
<div id="contract-instance-object"></div>
### The *Contract Instance* Object
A **Contract Instance Object** represents a single deployed [Contract
Instance](#term-contract-instance) and is defined to have the following
key/value pairs.
#### Contract Type: `contract_type`
The `contract_type` field defines the [Contract
Type](#term-contract-type) for this [Contract
Instance](#term-contract-instance). This can reference any of the
contract types included in this [Package](#term-package) *or* any of the
contract types found in any of the package dependencies from the
`build_dependencies` section of the [Package
Manifest](#term-package-manifest).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>See Below.</p></td>
</tr>
</tbody>
</table>
**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
`<contract-alias>`.
- The `<contract-alias>` value **must** be a valid [Contract
Alias](#term-contract-alias).
- 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
`<package-name>:<contract-alias>`.
- The `<package-name>` value **must** be present in the keys of the
`build_dependencies` of this Package.
- The `<contract-alias>` value **must** be be a valid [Contract
Alias](#term-contract-alias).
- The resolved package for `<package-name>` must contain the
`<contract-alias>` value in the keys of the `contract_types`
section.
#### Address: `address`
The `address` field defines the [Address](#term-address) of the
[Contract Instance](#term-contract-instance).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p>Hex encoded <code>0x</code> prefixed Ethereum address matching the regular expression <code>0x[0-9a-fA-F]{40}</code>.</p></td>
</tr>
</tbody>
</table>
#### Transaction: `transaction`
The `transaction` field defines the transaction hash in which this
[Contract Instance](#term-contract-instance) was created.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><code>0x</code> prefixed hex encoded transaction hash.</p></td>
</tr>
</tbody>
</table>
#### Block: `block`
The `block` field defines the block hash in which this the transaction
which created this *contract instance* was mined.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><code>0x</code> prefixed hex encoded block hash.</p></td>
</tr>
</tbody>
</table>
<div id="runtime-bytecode-runtime-bytecode-1"></div>
#### Runtime Bytecode: `runtime_bytecode`
The `runtime_bytecode` field defines the runtime portion of bytecode for
this [Contract Instance](#term-contract-instance). When present, the
value from this field supersedes the `runtime_bytecode` from the
[Contract Type](#term-contract-type) for this [Contract
Instance](#term-contract-instance).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> conform to <a href="#the-bytecode-object">the Bytecode Object</a> format.</p></td>
</tr>
</tbody>
</table>
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 [Contract Instance](#term-contract-instance).
This field **should** be present in all [Contract
Types](#term-contract-type) which include `bytecode` or
`runtime_bytecode`.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<tr class="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> conform to the <a href="#compiler-information-object">Compiler Information Object</a> format.</p></td>
</tr>
</tbody>
</table>
<div id="compiler-information-object"></div>
### The *Compiler Information* Object
The `compiler` field defines the compiler information that was used
during compilation of this [Contract Instance](#term-contract-instance).
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.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>name</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
#### 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](https://semver.org/) format or if built on a
nightly should be denoted in the form of `<semver>-<commit-hash>` ex:
`0.4.8-commit.60cc1668`.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>version</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
#### 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](https://solidity.readthedocs.io/en/latest/using-the-compiler.html#compiler-input-and-output-json-description).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<tr class="even">
<td><p>Key</p></td>
<td><p><code>settings</code></p></td>
</tr>
<tr class="odd">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
</tbody>
</table>
### BIP122 URIs
BIP122 URIs are used to define a blockchain via a subset of the
[BIP-122](https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki)
spec.
blockchain://<genesis_hash>/block/<latest confirmed block hash>
The `<genesis hash>` represents the blockhash of the first block on the
chain, and `<latest confirmed block hash>` represents the hash of the
latest block that’s been reliably confirmed (package managers should be
free to choose their desired level of confirmations).
Rationale
=========
The following use cases were considered during the creation of this
specification.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>owned</p></td>
<td><p>A package which contains contracts which are not meant to be used by themselves but rather as base contracts to provide functionality to other contracts through inheritance.</p></td>
</tr>
<tr class="even">
<td><p>transferable</p></td>
<td><p>A package which has a single dependency.</p></td>
</tr>
<tr class="odd">
<td><p>standard-token</p></td>
<td><p>A package which contains a reusable contract.</p></td>
</tr>
<tr class="even">
<td><p>safe-math-lib</p></td>
<td><p>A package which contains deployed instance of one of the package contracts.</p></td>
</tr>
<tr class="odd">
<td><p>piper-coin</p></td>
<td><p>A package which contains a deployed instance of a reusable contract from a dependency.</p></td>
</tr>
<tr class="even">
<td><p>escrow</p></td>
<td><p>A package which contains a deployed instance of a local contract which is linked against a deployed instance of a local library.</p></td>
</tr>
<tr class="odd">
<td><p>wallet</p></td>
<td><p>A package with a deployed instance of a local contract which is linked against a deployed instance of a library from a dependency.</p></td>
</tr>
<tr class="even">
<td><p>wallet-with-send</p></td>
<td><p>A package with a deployed instance which links against a deep dependency.</p></td>
</tr>
</tbody>
</table>
Each use case builds incrementally on the previous one.
A full listing of [Use
Cases](https://ethpm.github.io/ethpm-spec/use-cases.html)
can be found on the hosted version of this specification.
Glossary
==========
<div id="term-abi"></div>
ABI
---
The JSON representation of the application binary interface. See the
official
[specification](https://solidity.readthedocs.io/en/develop/abi-spec.html)
for more information.
<div id="term-address"></div>
Address
-------
A public identifier for an account on a particular chain
<div id="term-bytecode"></div>
Bytecode
--------
The set of EVM instructions as produced by a compiler. Unless otherwise
specified this should be assumed to be hexadecimal encoded, representing
a whole number of bytes, and [prefixed](#term-prefixed) with `0x`.
Bytecode can either be linked or unlinked. (see
[Linking](#term-linking))
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Unlinked Bytecode</p></td>
<td><p>The hexadecimal representation of a contract’s EVM instructions that contains sections of code that requires <a href="#term-linking">linking</a> for the contract to be functional.</p>
<p>The sections of code which are unlinked <strong>must</strong> be filled in with zero bytes.</p>
<p><strong>Example</strong>: <code>0x606060405260e06000730000000000000000000000000000000000000000634d536f</code></p></td>
</tr>
<tr class="even">
<td><p>Linked Bytecode</p></td>
<td><p>The hexadecimal representation of a contract’s EVM instructions which has had all <a href="#term-link-reference">Link References</a> replaced with the desired <a href="#term-link-value">Link Values</a>.</p>
<p><strong>Example</strong>: <code>0x606060405260e06000736fe36000604051602001526040518160e060020a634d536f</code></p></td>
</tr>
</tbody>
</table>
<div id="term-chain-definition"></div>
Chain Definition
----------------
This definition originates from [BIP122
URI](https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki).
A URI in the format `blockchain://<chain_id>/block/<block_hash>`
- `chain_id` is the unprefixed hexadecimal representation of the
genesis hash for the chain.
- `block_hash` is the unprefixed hexadecimal representation of the
hash of a block on the chain.
A chain is considered to match a chain definition if the the genesis
block hash matches the `chain_id` and the block defined by `block_hash`
can be found on that chain. It is possible for multiple chains to match
a single URI, in which case all chains are considered valid matches
<div id="term-content-addressable-uri"></div>
Content Addressable URI
-----------------------
Any URI which contains a cryptographic hash which can be used to verify
the integrity of the content found at the URI.
The URI format is defined in RFC3986
It is **recommended** that tools support IPFS and Swarm.
<div id="term-contract-alias"></div>
Contract Alias
--------------
This is a name used to reference a specific [Contract
Type](#term-contract-type). Contract aliases **must** be unique within a
single [Package](#term-package).
The contract alias **must** use *one of* the following naming schemes:
- `<contract-name>`
- `<contract-name>[<identifier>]`
The `<contract-name>` portion **must** be the same as the [Contract
Name](#term-contract-name) for this contract type.
The `[<identifier>]` portion **must** match the regular expression
`\[[-a-zA-Z0-9]{1,256}]`.
<div id="term-contract-instance"></div>
Contract Instance
-----------------
A contract instance a specific deployed version of a [Contract
Type](#term-contract-type).
All contract instances have an [Address](#term-address) on some specific
chain.
<div id="term-contract-instance-name"></div>
Contract Instance Name
----------------------
A name which refers to a specific [Contract
Instance](#term-contract-instance) on a specific chain from the
deployments of a single [Package](#term-package). This name **must** be
unique across all other contract instances for the given chain. The name
must conform to the regular expression `[a-zA-Z][a-zA-Z0-9_]{0,255}`
In cases where there is a single deployed instance of a given [Contract
Type](#term-contract-type), package managers **should** use the
[Contract Alias](#term-contract-alias) for that contract type for this
name.
In cases where there are multiple deployed instances of a given contract
type, package managers **should** use a name which provides some added
semantic information as to help differentiate the two deployed instances
in a meaningful way.
<div id="term-contract-name"></div>
Contract Name
-------------
The name found in the source code that defines a specific [Contract
Type](#term-contract-type). These names **must** conform to the regular
expression `[a-zA-Z][-a-zA-Z0-9_]{0,255}`.
There can be multiple contracts with the same contract name in a
projects source files.
<div id="term-contract-type"></div>
Contract Type
-------------
Refers to a specific contract in the package source. This term can be
used to refer to an abstract contract, a normal contract, or a library.
Two contracts are of the same contract type if they have the same
bytecode.
Example:
contract Wallet {
...
}
A deployed instance of the `Wallet` contract would be of of type
`Wallet`.
<div id="term-identifier"></div>
Identifier
----------
Refers generally to a named entity in the [Package](#term-package).
A string matching the regular expression `[a-zA-Z][-_a-zA-Z0-9]{0,255}`
<div id="term-link-reference"></div>
Link Reference
--------------
A location within a contract’s bytecode which needs to be linked. A link
reference has the following properties.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p><code>offset</code></p></td>
<td><p>Defines the location within the bytecode where the link reference begins.</p></td>
</tr>
<tr class="even">
<td><p><code>length</code></p></td>
<td><p>Defines the length of the reference.</p></td>
</tr>
<tr class="odd">
<td><p><code>name</code></p></td>
<td><p>(optional.) A string to identify the reference</p></td>
</tr>
</tbody>
</table>
<div id="term-link-value"></div>
Link Value
----------
A link value is the value which can be inserted in place of a [Link
Reference](#term-link-reference)
<div id="term-linking"></div>
Linking
-------
The act of replacing [Link References](#term-link-reference) with [Link
Values](#term-link-value) within some [Bytecode](#term-bytecode).
<div id="term-package"></div>
Package
-------
Distribution of an application’s source or compiled bytecode along with
metadata related to authorship, license, versioning, et al.
For brevity, the term **Package** is often used metonymously to mean
[Package Manifest](#term-package-manifest).
<div id="term-package-manifest"></div>
Package Manifest
----------------
A machine-readable description of a package (See
[Specification](#package-specification) for information about the format
for package manifests.)
<div id="term-prefixed"></div>
Prefixed
--------
[Bytecode](#term-bytecode) string with leading `0x`.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Example</p></td>
<td><p><code>0xdeadbeef</code></p></td>
</tr>
</tbody>
</table>
<div id="term-unprefixed"></div>
Unprefixed
----------
Not [Prefixed](#term-prefixed).
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr class="odd">
<td><p>Example</p></td>
<td><p><code>deadbeef</code></p></td>
</tr>
</tbody>
</table>
Backwards Compatibility
=======================
This specification supports backwards compatibility by use of the
[manifest\_version](#manifest-version) property. This
specification corresponds to version `2` as the value for that field.
Implementations
===============
This submission aims to coincide with development efforts towards
widespread implementation in commonly-used development tools.
The following tools are known to have begun or are nearing completion of
a supporting implementation.
- [Truffle](https://trufflesuite.com/)
- [Populus](https://populus.readthedocs.io/en/latest/)
- [Embark](https://embark.status.im/)
Full support in implementation **may** require [Further
Work](#further-work), specified below.
Further Work
============
This EIP addresses only the data format for package descriptions.
Excluded from the scope of this specification are:
- Package registry interface definition
- Tooling integration, or how packages are stored on disk.
These efforts **should** be considered separate, warranting future
dependent EIP submssions.
Acknowledgements
================
The authors of this document would like to thank the original authors of
[EIP-190](./eip-190.md),
[ETHPrize](http://ethprize.io/) for their funding
support, all community
[contributors](https://github.com/ethpm/ethpm-spec/graphs/contributors),
and the Ethereum community at large.
Copyright
=========
Copyright and related rights waived via [CC0](../LICENSE.md).