forked from DecentralizedClimateFoundation/DCIPs
1882 lines
45 KiB
Markdown
1882 lines
45 KiB
Markdown
---
|
||
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>"literal"</code> for bytecode literals</p>
|
||
<p><code>"reference"</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).
|