ethpm-spec
v3.0.0
Published
Ethereum Package Manager Specifications
Downloads
1,201
Readme
EthPM Package Specification
Overview
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 <[email protected]>"
],
"description": "Reusable contracts which implement a privileged 'owner' model for authorization.",
"keywords": [
"authorization"
],
"links": {
"documentation": "ipfs://QmUYcVzTfSwJoigggMxeo2g5STWAgJdisQsqcXHws7b1FW"
}
},
"sources": {
"contracts/Owned.sol": {
"type": "solidity",
"urls": [
"ipfs://Qme4otpS88NV8yQi8TfTP89EsQC5bko3F5N1yhRoi6cwGV"
],
"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 manifestv3-pretty.json
: ethpm v3 manifest (pretty printed)contracts/
: Directory containing the source contracts for the examplemetadata/
: Directory containing example ethpm compliant compiler metadata output for each example contract
Specification
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.
Contributing
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
cd docs
make html
Docs are written in reStructuredText and built using the Sphinx documentation generator.
Running tests locally
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 forinvalid
tests. - The
reason
field, which is a human readable description of the error, is included forinvalid
tests. - The
errorCode
field, which is a machine readable description of the error, is included forinvalid
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.