title: Revised Ethereum Smart Contract Packaging Standard (EthPM v3)
author: g. nicholas d’andrea (@gnidan), Piper Merriam (@pipermerriam), Nick Gheorghita (@njgheorghita), Christian Reitwiessner(@chriseth), Ben Hauser (@iamdefinitelyahuman), Bryant Eisenbach (@fubuloubu)
This document presents a natural language description of a formal
specification for version **3** 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.
- Updates the schema for a *package manifest* to be compatible with
the [metadata](https://solidity.readthedocs.io/en/latest/metadata.html) output for compilers.
- Updates the `"sources"` object definition to support a wider range of source file types and serve as [JSON input](https://solidity.readthedocs.io/en/latest/using-the-compiler.html#compiler-input-and-output-json-description) for a compiler.
- Moves compiler definitions to a top-level `"compilers"` array in order to:
- Simplify the links between a compiler version, sources, and the
compiled assets.
- Simplify packages that use multiple compiler versions.
- Updates key formatting from `snake_case` to `camelCase` to be
more consistent with [JSON convention](https://google.github.io/styleguide/jsoncstyleguide.xml?showone=Property_Name_Format#Property_Name_Format).
### 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.
4. Package manifests can be used to verify public deployments of source
The following use cases were considered during the creation of this
specification.
<table>
<colgroup>
<colstyle="width: 30%"/>
<colstyle="width: 70%"/>
</colgroup>
<tbody>
<trclass="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>
<trclass="even">
<td><p>transferable</p></td>
<td><p>A package which has a single dependency.</p></td>
</tr>
<trclass="odd">
<td><p>standard-token</p></td>
<td><p>A package which contains a reusable contract.</p></td>
</tr>
<trclass="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>
<trclass="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>
<trclass="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>
<trclass="even">
<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>
<trclass="odd">
<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>
<trclass="even">
<td><p>simple-auction</p></td>
<td><p>Compiler <code>"metadata"</code> field output.</p></td>
<td><p>Formalized (<ahref="https://json-schema.org">JSON-Schema</a>) version of this specification: [package.spec.json](../assets/eip-2678/package.spec.json)</p></td>
<td><p>Keys <strong>must</strong> be a valid BIP122 URI chain definition.</p>
<p>Values <strong>must</strong> be objects which conform to the following format:</p>
<p>- Keys <strong>must</strong> be valid <ahref="#term-contract-instance-name">Contract Instance Names</a>.</p>
<p>- Values <strong>must</strong> be a valid <ahref="#contract-instance-object">Contract Instance Object</a>.</p></td>
</tr>
</tbody>
</table>
<divid="build-dependencies"></div>
### Build Dependencies: `buildDependencies`
The `buildDependencies` field defines a key/value mapping of EthPM
packages that this project depends on.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Key</p></td>
<td><p><code>buildDependencies</code></p></td>
</tr>
<trclass="odd">
<td><p>Type</p></td>
<td><p>Object (String: String)</p></td>
</tr>
<trclass="even">
<td><p>Format</p></td>
<td><p>Keys <strong>must</strong> be valid <ahref="#name">package names</a>.</p>
<p>Values <strong>must</strong> be a <ahref="#term-content-addressable-uri">Content Addressable URI</a> which resolves to a valid package that conforms the same EthPM manifest version as its parent.</p></td>
</tr>
</tbody>
</table>
<divid="object-definitions"></div>
### 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.
<divid="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>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<trclass="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>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<trclass="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>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p><strong>must</strong> conform to the <ahref="#term-identifier">Identifier</a> format.</p></td>
</tr>
</tbody>
</table>
<divid="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.
#### 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>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>Integer</p></td>
</tr>
<trclass="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>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<trclass="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 <ahref="#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>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p>Determined based on <code>type</code>, see below.</p></td>
Array of urls that resolve to the same source file.
- Urls **should** be stored on a content-addressable filesystem.
**If** they are not, then either `content` or `checksum`**must** be
included.
- Urls **must** be prefixed with a scheme.
- If the resulting document is a directory the key **should** be
interpreted as a directory path.
- If the resulting document is a file the key **should** be
interpreted as a file path.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>If <code>content</code> is not included.</p></td>
</tr>
<trclass="even">
<td><p>Key</p></td>
<td><p><code>urls</code></p></td>
</tr>
<trclass="odd">
<td><p>Value</p></td>
<td><p>Array(String)</p></td>
</tr>
</tbody>
</table>
#### Content: `content`
Inlined contract source. If both `urls` and `content` are provided, the `content` value
**must** match the content of the files identified in `urls`.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>If <code>urls</code> is not included.</p></td>
</tr>
<trclass="even">
<td><p>Key</p></td>
<td><p><code>content</code></p></td>
</tr>
<trclass="odd">
<td><p>Value</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
#### Install Path: `installPath`
Filesystem path of source file.
-**Must** be a relative filesystem path that begins with a `./`.
-**Must** resolve to a path that is within the current virtual
working directory.
-**Must** be unique across all included sources.
-**Must not** contain `../` to avoid accessing files outside of
the source folder in improper implementations.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>This field <strong>must</strong> be included for the package to be writable to disk.</p></td>
</tr>
<trclass="even">
<td><p>Key</p></td>
<td><p><code>installPath</code></p></td>
</tr>
<trclass="odd">
<td><p>Value</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
#### Type: `type`
The `type` field declares the type of the source file. The field
**should** be one of the following values: `solidity`, `vyper`,
`abi-json`, `solidity-ast-json`.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Key</p></td>
<td><p><code>type</code></p></td>
</tr>
<trclass="odd">
<td><p>Value</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
#### License: `license`
The `license` field declares the type of license associated with
this source file. When defined, this license overrides the
package-scoped [meta license](#meta-license).
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Key</p></td>
<td><p><code>license</code></p></td>
</tr>
<trclass="odd">
<td><p>Value</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
<divid="checksum-object"></div>
### The *Checksum* Object
A *Checksum* object is defined to have the following key/value pairs.
#### Algorithm: `algorithm`
The `algorithm` used to generate the corresponding hash. Possible
algorithms include, but are not limited to `sha3`, `sha256`, `md5`,
`keccak256`.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
#### Hash: `hash`
The `hash` of a source files contents generated with the corresponding
algorithm.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
</tbody>
</table>
<divid="contract-type-object"></div>
### The *Contract Type* Object
A *Contract Type* object is defined to have the following key/value
pairs.
#### Contract Name: `contractName`
The `contractName` field defines the [Contract
Name](#term-contract-name) for this [Contract
Type](#term-contract-type).
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>If the <ahref="#term-contract-name">Contract Name</a> and <ahref="#term-contract-alias">Contract Alias</a> are not the same.</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p><strong>Must</strong> be a valid <ahref="#term-contract-name">Contract Name</a>.</p></td>
</tr>
</tbody>
</table>
#### Source ID: `sourceId`
The global source identifier for the source file from which this
contract type was generated.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p><strong>Must</strong> match a unique source ID included in the <ahref="#sources-object">Sources Object</a> for this package.</p></td>
</tr>
</tbody>
</table>
#### Deployment Bytecode: `deploymentBytecode`
The `deploymentBytecode` field defines the bytecode for this [Contract
Type](#term-contract-type).
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p><strong>Must</strong> conform to <ahref="#bytecode-object">the Bytecode object</a> format.</p></td>
</tr>
</tbody>
</table>
#### Runtime Bytecode: `runtimeBytecode`
The `runtimeBytecode` field defines the unlinked `0x`-prefixed runtime
portion of [Bytecode](#term-bytecode) for this [Contract
Type](#term-contract-type).
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p><strong>Must</strong> conform to <ahref="#bytecode-object">the Bytecode object</a> format.</p></td>
</tr>
</tbody>
</table>
#### ABI: `abi`
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>Array</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p><strong>Must</strong> conform to <ahref="https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#json">Ethereum Contract ABI JSON</a> format.</p></td>
</tr>
</tbody>
</table>
#### UserDoc: `userdoc`
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p><strong>Must</strong> conform to <ahref="https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format#user-documentation">UserDoc</a> format.</p></td>
</tr>
</tbody>
</table>
#### DevDoc: `devdoc`
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>No</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>Object</p></td>
</tr>
<trclass="odd">
<td><p>Format</p></td>
<td><p><strong>Must</strong> conform to <ahref="https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format#developer-documentation">DevDoc</a> format.</p></td>
</tr>
</tbody>
</table>
<divid="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: `contractType`
The `contractType` 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
`buildDependencies` section of the [Package
Manifest](#term-package-manifest).
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Required</p></td>
<td><p>Yes</p></td>
</tr>
<trclass="even">
<td><p>Type</p></td>
<td><p>String</p></td>
</tr>
<trclass="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 `contractTypes`
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
`buildDependencies` 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 `contractTypes` section.
#### Address: `address`
The `address` field defines the [Address](#term-address) of the
A public identifier for an account on a particular chain
<divid="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>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="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 <ahref="#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>
<td><p>The hexadecimal representation of a contract’s EVM instructions which has had all <ahref="#term-link-reference">Link References</a> replaced with the desired <ahref="#term-link-value">Link Values</a>.</p>
