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)
- 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).
<divid="package-specification"></div>
## Specification
This document defines the specification for an EthPM package manifest. A
package manifest provides metadata about a *package*, and
in most cases should provide sufficient information about the packaged
contracts and its dependencies to do bytecode verification of its
contracts.
A [hosted version](http://ethpm.github.io/ethpm-spec)
of this specification is available via GitHub Pages. This EIP and the
hosted HTML document were both autogenerated from the same documentation
source.
### 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.
### 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.
-<https://www.ietf.org/rfc/rfc2119.txt>
#### Prefixed vs Unprefixed
A [prefixed](#term-prefixed) hexadecimal value begins with `0x`.
[Unprefixed](#term-unprefixed) values have no prefix. Unless otherwise
specified, all hexadecimal values **should** be represented with the
`0x` prefix.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Prefixed</p></td>
<td><p><code>0xdeadbeef</code></p></td>
</tr>
<trclass="even">
<td><p>Unprefixed</p></td>
<td><p><code>deadbeef</code></p></td>
</tr>
</tbody>
</table>
### 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](https://en.wikipedia.org/wiki/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.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>See Also</p></td>
<td><p>Formalized (<ahref="https://json-schema.org">JSON-Schema</a>) version of this specification: <ahref="https://github.com/ethpm/ethpm-spec/blob/master/spec/v3.spec.json">package.spec.json</a></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>
</tr>
</tbody>
</table>
Format
For static value *literals* (e.g. address), value **must** be a *byte
string*
To reference the address of a [Contract
Instance](#term-contract-instance) from the current package the value
should be the name of that contract instance.
- This value **must** be a valid [Contract Instance
Name](#term-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 [Package](#term-package) 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 the `buildDependencies` for the
current package.
- For every `pn` where `n > 1`, `pn`**must** be present in the keys
of the `buildDependencies` of the package for `pn-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](#term-contract-name).
- The `<contract-instance>` value **must** be a valid [Contract
Instance Name](#term-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.
<divid="bytecode-object"></div>
### The *Bytecode* Object
A bytecode object has the following key/value pairs.
#### Bytecode: `bytecode`
The `bytecode` field is a string containing the `0x` prefixed
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>
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
<divid="term-content-addressable-uri"></div>
Content Addressable URI
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.
<divid="term-contract-alias"></div>
Contract Alias
This is a name used to reference a specific [Contract
Type](#term-contract-type). Contract aliases **must** be unique within a
single [Package](#term-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](#term-contract-name) for this contract type.
The `<identifier>` portion **must** match the regular expression
`^[-a-zA-Z0-9]{1,256}$`.
<divid="term-contract-instance"></div>
Contract Instance
A contract instance a specific deployed version of a [Contract
Type](#term-contract-type).
All contract instances have an [Address](#term-address) on some specific
chain.
<divid="term-contract-instance-name"></div>
Contract Instance Name
A name which refers to a specific [Contract
Instance](#term-contract-instance) on a specific chain from the
deployments of a single [Package](#term-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](#term-contract-type), package managers **should** use the
[Contract Alias](#term-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.
<divid="term-contract-name"></div>
Contract Name
The name found in the source code that defines a specific [Contract
Type](#term-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.
<divid="term-contract-type"></div>
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`.
<divid="term-identifier"></div>
Identifier
Refers generally to a named entity in the [Package](#term-package).
A string matching the regular expression
`^[a-zA-Z][-_a-zA-Z0-9]{0,255}$`
<divid="term-link-reference"></div>
Link Reference
A location within a contract’s bytecode which needs to be linked. A link
reference has the following properties.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p><code>offset</code></p></td>
<td><p>Defines the location within the bytecode where the link reference begins.</p></td>
</tr>
<trclass="even">
<td><p><code>length</code></p></td>
<td><p>Defines the length of the reference.</p></td>
</tr>
<trclass="odd">
<td><p><code>name</code></p></td>
<td><p>(optional) A string to identify the reference</p></td>
</tr>
</tbody>
</table>
<divid="term-link-value"></div>
Link Value
A link value is the value which can be inserted in place of a [Link
Reference](#term-link-reference)
<divid="term-linking"></div>
Linking
The act of replacing [Link References](#term-link-reference) with [Link
Values](#term-link-value) within some [Bytecode](#term-bytecode).
<divid="term-package"></div>
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](#term-package-manifest).
<divid="term-package-manifest"></div>
Package Manifest
A machine-readable description of a package.
<divid="term-prefixed"></div>
Prefixed
[Bytecode](#term-bytecode) string with leading `0x`.
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Example</p></td>
<td><p><code>0xdeadbeef</code></p></td>
</tr>
</tbody>
</table>
<divid="term-unprefixed"></div>
Unprefixed
Not [Prefixed](#term-prefixed).
<table>
<colgroup>
<colstyle="width: 50%"/>
<colstyle="width: 50%"/>
</colgroup>
<tbody>
<trclass="odd">
<td><p>Example</p></td>
<td><p><code>deadbeef</code></p></td>
</tr>
</tbody>
</table>
## Rationale
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>
</tr>
</table>
Each use case builds incrementally on the previous one.
