This document defines the specification for a Package. The Package JSON document provides metadata about itself and in most cases should provide sufficient information about the packaged contracts and its dependencies to do bytecode verification of its contracts.
The Package specification makes the following assumptions about the document lifecycle.
- Packages are intended to be generated programatically by package management software as part of the release process.
- Packages will be consumed by package managers during tasks like installing package dependencies or building and deploying new releases.
- Packages 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.
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.
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
The name found in the source code which defines a specific . 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.
This is a name used to reference a specific . Contract aliases must be unique within a single .
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}\]
.
A name which refers to a specific on a specific chain from the
deployments of a single . 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 , 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.
A string matching the regular expression [a-zA-Z][-_a-zA-Z0-9]{0,255}
A string matching the regular expression [a-zA-Z][-_a-zA-Z0-9]{0,255}
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.
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
The canonical format for the Package JSON document containing 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.
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.
The manifest_version
field defines the specification version that this
document conforms to. Packages must include this field.
Required
YesKey
manifest_version
Type
StringAllowed Values
2
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.
Required
YesKey
package_name
Type
StringFormat
must be a valid package name.
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.
Required
NoKey
meta
Type
Object (String: Package Meta object)
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 version numbering
specification.
Required
YesKey
version
Type
String
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.
Key
sources
Type
Object (String: String)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.
- 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.
The contract_types
field holds the which have been included in this
release. should only include contract types that can be found in the
source files for this package. Packages should not include contract
types from dependencies.
Key
contract_types
Type
Object (String: Contract Type Object)Format
- Keys must be valid contract aliases.
- Values must conform to the Contract Type Object definition.
Packages should not include abstract contracts in the contract types section of a release.
The deployments
field holds the information for the chains on which
this release has as well as the and other deployment details for those
deployed contract instances. The set of chains defined by the BIP122 URI
keys for this object must be unique.
Key
deployments
Type
Object (String: Object(String: Contract Instance Object))Format
- Keys must be a valid BIP122 URI chain definition.
- Values must be objects which conform to the format:
- Keys must be a valid Contract Instance Name.
- Values must be a valid Contract Instance Object.
The build_dependencies
field defines a key/value mapping of ethereum
packages that this project depends on.
Key
dependencies
Type
Object (String: String)Format
- Keys must be valid package names matching the regular expression
[a-z][-a-z0-9]{0,213}
- Values must be valid IPFS URIs which resolve to a valid Package
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.
A object has the following key/value pairs. All link references are assumed to be associated with some corresponding bytecode.
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.
Required
YesType
Array
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.
Required
YesType
Integer
The name
field is a string which must be a valid
Identifier. Any link references which should be
linked with the same link value should be given the same name.
Required
NoType
StringFormat
must conform to the Identifier format.
A object is defined to have the following key/value pairs.
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.
Required
YesType
IntegerFormat
Array of integers, where each integer must conform to all of the following:
- be greater than or equal to zero
- strictly less than the length of the unprefixed hexadecimal representation of the corresponding bytecode.
The type
field defines the value
type for determining what is
encoded when the corresponding bytecode.
Required
YesType
StringAllowed Values
'literal'
for bytecode literals'reference'
for named references to a particular
The value
field defines the value which should be written when the
corresponding bytecode.
Required
YesType
StringFormat
determined based ontype
:
Type
literal
For static value literals (e.g. address), value must be a byte stringType
reference
To reference the address of a 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 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 thebuild_dependencies
for the current package.- For every
pn
wheren > 1
,pn
must be present in the keys of thebuild_dependencies
of the package forpn-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.- The
<contract-instance>
value must be a valid 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.
A bytecode object has the following key/value pairs.
The bytecode
field is a string containing the 0x
prefixed
hexadecimal representation of the bytecode.
Required
YesType
StringFormat
0x prefixed hexadecimal.
The link_references
field defines the locations in the corresponding
bytecode which require .
Required
NoType
ArrayFormat
All values must be valid Link Reference objects
This field is considered invalid if any of the 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.
The link_dependencies
defines the that have been used to link the
corresponding bytecode.
- Required: No
- Type: Array
- Format: All values must be valid Link Value objects
Validation of this field includes the following:
- No two link value objects may contain any of the same values for
offsets
. - Each link value object must have a
corresponding link reference object
under the
link_references
field. - The length of the resolved
value
must be equal to thelength
of the corresponding .
The Package Meta object is defined to have the following key/value pairs.
The authors
field defines a list of human readable names for the
authors of this package. Packages may include this field.
Required
NoKey
authors
Type
List of Strings
The license
field declares the license under which this package is
released. This value should conform to the
SPDX
format. Packages should include this field.
Required
NoKey
license
Type
String
The description
field provides additional detail that may be relevant
for the package. Packages may include this field.
Required
NoKey
description
Type
String
The keywords
field provides relevant keywords related to this package.
Required
NoKey
keywords
Type
List of Strings
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.Key
links
Type
Object (String: String)
A Contract Type object is defined to have the following key/value pairs.
The contract_name
field defines the contract name
for this .
Required
If the contract name and contract alias are not the same.Type
StringFormat
must be a valid contract name.
The deployment_bytecode
field defines the bytecode for this .
Required
NoType
ObjectFormat
must conform to the Bytecode Object format.
The runtime_bytecode
field defines the unlinked '0x'
prefixed
runtime portion of for this .
Required
NoType
ObjectFormat
must conform to the Bytecode Object format.
Required
NoType
ListFormat
see https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#json
Required
NoType
ObjectFormat
The Merged UserDoc and*DevDoc*
Required
NoType
ObjectFormat
must conform to the Compiler Information object format.
A Object is defined to have the following key/value pairs.
The contract_type
field defines the for this . This can reference any
of the contract types included in this or any of the contract types
found in any of the package dependencies from the build_dependencies
section of the .
Required
YesType
StringFormat
must conform to one of the following formats
To reference a contract type from this Package, use the format
<contract-alias>
.
- The
<contract-alias>
value must be a valid 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 thebuild_dependencies
of this Package. - The
<contract-alias>
value must be be a valid contract alias. - The resolved package for
<package-name>
must contain the<contract-alias>
value in the keys of thecontract_types
section.
The address
field defines the of the .
Required
YesType
StringFormat
Hex encoded'0x'
prefixed Ethereum address matching the regular expression0x[0-9a-fA-F]{40}
.
The transaction
field defines the transaction hash in which this was
created.
Required
NoType
StringFormat
0x
prefixed hex encoded transaction hash.
The block
field defines the block hash in which this the transaction
which created this contract instance was mined.
Required
NoType
StringFormat
0x
prefixed hex encoded block hash.
The runtime_bytecode
field defines the runtime portion of bytecode for
this . When present, the value from this field supersedes the
runtime_bytecode
from the for this .
Required
NoType
ObjectFormat
must conform to the Bytecode Object format.
Every entry in the link_references
for this bytecode must have a
corresponding entry in the link_dependencies
section.
The compiler
field defines the compiler information that was used
during compilation of this . This field should be present in all
which include bytecode
or runtime_bytecode
.
Required
NoType
ObjectFormat
must conform to the Compiler Information Object format.
The compiler
field defines the compiler information that was used
during compilation of this . 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.
The name
field defines which compiler was used in compilation.
Required
YesKey
type
:Type
String
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
YesKey
version
:Type
String
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
NoKey
settings
:Type
Object
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
f