TypeScript icon, indicating that this package has built-in type declarations

3.0.0 • Public • Published

EthPM Package Specification


Join the chat at

This repository comprises the formal specification and documentation source for the EthPM package manifest data format.

This data format is designed to be produced/consumed by Ethereum development tools. As such, this repository is intended for tool developers wishing to integrate with EthPM.

Package manifests are JSON-encoded, tightly-packed, with objects’ keys sorted in lexicographic order. Package manifests may live on disk, but are intended to be produced programmatically and uploaded directly to a content-addressable storage network (e.g. IPFS). A package manifest describes a single package, including package name, version, dependencies, and references to distributed source files.

Repository Contents

Examples / Use Cases

Package: owned (prettified)

    "name": "owned",
    "version": "1.0.0",
    "manifest": "ethpm/3",
    "meta": {
        "license": "MIT",
        "authors": [
            "Piper Merriam <>"
        "description": "Reusable contracts which implement a privileged 'owner' model for authorization.",
        "keywords": [
        "links": {
            "documentation": "ipfs://QmUYcVzTfSwJoigggMxeo2g5STWAgJdisQsqcXHws7b1FW"
    "sources": {
        "contracts/Owned.sol": {
            "type": "solidity",
            "urls": [
            "installPath": "./contracts/Owned.sol"

Please see Use Cases for documented examples of different kinds of packages with varying levels of complexity. Source for use case examples can be found in the examples/ directory of this repository.

Each example directory contains..

  • 1.0.0.json: ethpm v2 manifest (deprecated)
  • 1.0.0-pretty.json: ethpm v2 manifest (pretty printed) (deprecated)
  • v3.json: ethpm v3 manifest
  • v3-pretty.json: ethpm v3 manifest (pretty printed)
  • contracts/: Directory containing the source contracts for the example
  • metadata/: Directory containing example ethpm compliant compiler metadata output for each example contract


The EthPM package manifest format is formally specified as a JSON-Schema.

Please see Package Specification for a natural-language description of this schema, or see package.spec.json for the machine-readable version.


Requirements: Python 3, pip, make Fork and clone this repo to get started. Then, activate a virtual environment in the cloned repo's directory and run pip install -r requirements.txt

Building Sphinx docs locally

  1. cd docs
  2. make html

Docs are written in reStructuredText and built using the Sphinx documentation generator.

Running tests locally

  1. pytest tests/

Test fixture schema

Each test fixture contains a package field with a raw, json encoded string of the manifest.

Each test fixture contains a testCase field that indicates whether the associated package is invalid or valid.

Each invalid test fixture contains an errorInfo field.

  • The errorPointer field, which is a jsonpointer pointing towards the cause of the invalid error, is included for invalid tests.
  • The reason field, which is a human readable description of the error, is included for invalid tests.
  • The errorCode field, which is a machine readable description of the error, is included for invalid tests according to the following table.

N0001 - Invalid "manifest" field. N0002 - Invalid "name" field. N0003 - Invalid "version" field. N0004 - Invalid "sources" field. N0005 - Invalid "contractTypes" field. N0006 - Invalid "deployments" field. N0007 - Invalid "compilers" field. N0008 - Invalid "buildDependencies" field. N0009 - Invalid "meta" field.

Package Sidebar


npm i ethpm-spec

Weekly Downloads






Unpacked Size

514 kB

Total Files


Last publish


  • rizedr
  • jeff.smale
  • kevinbluer
  • davidmurdoch
  • cds-amal
  • gnidan
  • nickghita
  • tcoulter