# EIP-2678: Revised Ethereum Smart Contract Packaging Standard (EthPM v3) Source

Author g. nicholas d’andrea, Piper Merriam, Nick Gheorghita, Christian Reitwiessner, Ben Hauser, Bryant Eisenbach https://ethereum-magicians.org/t/ethpm-v3-specification-working-group/4086 Final Standards Track ERC 2020-05-26

## 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. Packages are then published to on-chain EthPM registries, defined in EIP-1319, from where they can be freely accessed.

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 output for compilers.
• Updates the "sources" object definition to support a wider range of source file types and serve as JSON input 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.

### 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 contracts.

### Use Cases

The following use cases were considered during the creation of this specification.

• owned: 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.
• transferable: A package which has a single dependency.
• standard-token: A package which contains a reusable contract.
• safe-math-lib: A package which contains deployed instance of one of the package contracts.
• piper-coin: A package which contains a deployed instance of a reusable contract from a dependency.
• escrow: A package which contains a deployed instance of a local contract which is linked against a deployed instance of a local library.
• wallet: A package with a deployed instance of a local contract which is linked against a deployed instance of a library from a dependency.
• wallet-with-send: A package with a deployed instance which links against a deep dependency.
• simple-auction: Compiler "metadata" field output.

## Package Specification

### 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.

#### Prefixed vs Unprefixed

A prefixed hexadecimal value begins with 0x. Unprefixed values have no prefix. Unless otherwise specified, all hexadecimal values should be represented with the 0x prefix.

• Prefixed: 0xdeadbeef
• Unprefixed: deadbeef

### Document Format

The canonical format is a single JSON object. Packages must conform to the following serialization rules.

• The document must be tightly packed, meaning no linebreaks or extra whitespace.

• The keys in all objects must be sorted alphabetically.

• Duplicate keys in the same object are invalid.

• The document must use UTF-8 encoding.

• The document must not have a trailing newline.

• To ensure backwards compatibility, manifest_version is a forbidden top-level key.

### Document Specification

The following fields are defined for the package. Custom fields may be included. Custom fields should be prefixed with x- to prevent name collisions with future versions of the specification.

### EthPM Manifest Version

The manifest field defines the specification version that this document conforms to.

• Packages must include this field.

• Required: Yes
• Key: manifest
• Type: String
• Allowed Values: ethpm/3

### Package Name

The name field defines a human readable name for this package.

• Packages should include this field to be released on an EthPM registry.

• Package names must begin with a lowercase letter and be comprised of only the lowercase letters a-z, numeric characters 0-9, and the dash character -.

• Package names must not exceed 255 characters in length.

• Required: If version is included.
• Key: name
• Type: String

#### Transaction: transaction

The transaction field defines the transaction hash in which this Contract Instance was created.

• Required: No
• Type: String
• Format: 0x prefixed hex encoded transaction hash.

#### Block: block

The block field defines the block hash in which this the transaction which created this contract instance was mined.

• Required: No
• Type: String
• Format: 0x prefixed hex encoded block hash.

#### Runtime Bytecode: runtimeBytecode

The runtimeBytecode field defines the runtime portion of bytecode for this Contract Instance. When present, the value from this field supersedes the runtimeBytecode from the Contract Type for this Contract Instance.

• Required: No
• Type: Object
• Format: Must conform to the Bytecode Object format.

Every entry in the linkReferences for this bytecode must have a corresponding entry in the linkDependencies section.

### The Compiler Information Object

The compilers field defines the various compilers and settings used during compilation of any Contract Types or Contract Instance included in this package.

A Compiler Information object is defined to have the following key/value pairs.

#### Name: name

The name field defines which compiler was used in compilation.

• Required: Yes
• Key: name
• Type: String

#### Version: version

The version field defines the version of the compiler. The field should be OS agnostic (OS not included in the string) and take the form of either the stable version in semver format or if built on a nightly should be denoted in the form of <semver>-<commit-hash> ex: 0.4.8-commit.60cc1668.

• Required: Yes
• Key: version
• Type: String

#### Settings: settings

The settings field defines any settings or configuration that was used in compilation. For the "solc" compiler, this should conform to the Compiler Input and Output Description.

• Required: No
• Key: settings
• Type: Object

#### Contract Types: contractTypes

A list of the Contract Alias or Contract Types in this package that used this compiler to generate its outputs.

• All contractTypes that locally declare runtimeBytecode should be attributed for by a compiler object.

• A single contractTypes must not be attributed to more than one compiler.

• Required: No
• Key: contractTypes
• Type: Array(Contract Alias)

### BIP122 URI

BIP122 URIs are used to define a blockchain via a subset of the BIP-122 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).

### Glossary

The terms in this glossary have been updated to reflect the changes made in V3.

#### ABI

The JSON representation of the application binary interface. See the official specification for more information.

A public identifier for an account on a particular chain

#### 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 with 0x.

• Unlinked Bytecode: The hexadecimal representation of a contract’s EVM instructions that contains sections of code that requires linking for the contract to be functional.
The sections of code which are unlinked must be filled in with zero bytes.
Example: 0x606060405260e06000730000000000000000000000000000000000000000634d536f
• Linked Bytecode: The hexadecimal representation of a contract’s EVM instructions which has had all Link References replaced with the desired Link Values. Example: 0x606060405260e06000736fe36000604051602001526040518160e060020a634d536f

#### Chain Definition

This definition originates from BIP122 URI.

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

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.

#### Contract Alias

This is a name used to reference a specific Contract Type. Contract aliases must be unique within a single 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 for this contract type.

The <identifier> portion must match the regular expression ^[-a-zA-Z0-9]{1,256}$. #### Contract Instance A contract instance a specific deployed version of a Contract Type. All contract instances have an Address on some specific chain. #### Contract Instance Name A name which refers to a specific Contract Instance on a specific chain from the deployments of a single 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, package managers should use the 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.

The name found in the source code that defines a specific 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. #### 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. #### Identifier Refers generally to a named entity in the Package. A string matching the regular expression ^[a-zA-Z][-_a-zA-Z0-9]{0,255}$

A location within a contract’s bytecode which needs to be linked. A link reference has the following properties.

• offset: Defines the location within the bytecode where the link reference begins.
• length: Defines the length of the reference.
• name: (optional) A string to identify the reference.

A link value is the value which can be inserted in place of a Link Reference

The act of replacing Link References with Link Values within some Bytecode.

#### 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.

#### Package Manifest

A machine-readable description of a package.

#### Prefixed

Bytecode string with leading 0x.

• Example: 0xdeadbeef

#### Unprefixed

Not Prefixed.

• Example: deadbeef

## Rationale

### Minification

EthPM packages are distributed as alphabetically-ordered & minified JSON to ensure consistency. Since packages are published on content-addressable filesystems (eg. IPFS), this restriction guarantees that any given set of contract assets will always resolve to the same content-addressed URI.

### Package Names

Package names are restricted to lower-case characters, numbers, and - to improve the readability of the package name, in turn improving the security properties for a package. A user is more likely to accurately identify their target package with this restricted set of characters, and not confuse a malicious package that disguises itself as a trusted package with similar but different characters (e.g. O and 0).

### BIP122

The BIP-122 standard has been used since EthPM v1 since it is an industry standard URI scheme for identifying different blockchains and distinguishing between forks.

### Compilers

Compilers are now defined in a top-level array, simplifying the task for tooling to identify the compiler types needed to interact with or validate the contract assets. This also removes unnecessarily duplicated information, should multiple contractTypes share the same compiler type.

## Backwards Compatibility

To improve understanding and readability of the EthPM spec, the manifest_version field was updated to manifest in v3. To ensure backwards compatibility, v3 packages must define a top-level "manifest" with a value of "ethpm/3". Additionally, "manifest_version" is a forbidden top-level key in v3 packages.

## Security Considerations

Using EthPM packages implicitly requires importing &/or executing code written by others. The EthPM spec guarantees that when using a properly constructed and released EthPM package, the user will have the exact same code that was included in the package by the package author. However, it is impossible to guarantee that this code is safe to interact with. Therefore, it is critical that end users only interact with EthPM packages authored and released by individuals or organizations that they trust to include non-malicious code.

Copyright and related rights waived via CC0.