forked from DecentralizedClimateFoundation/DCIPs
67 lines
3.6 KiB
Markdown
67 lines
3.6 KiB
Markdown
---
|
|
eip: 2942
|
|
title: EthPM URI Specification
|
|
author: Nick Gheorghita (@njgheorghita), Piper Merriam (@pipermerriam), g. nicholas d'andrea (@gnidan), Benjamin Hauser (@iamdefinitelyahuman)
|
|
discussions-to: https://ethereum-magicians.org/t/ethpm-v3-specification-working-group/4086/7
|
|
status: Stagnant
|
|
type: Standards Track
|
|
category: ERC
|
|
created: 2020-09-04
|
|
requires: 2678
|
|
---
|
|
|
|
## Simple Summary
|
|
A custom URI scheme to identify an EthPM registry, package, release, or specific contract asset within a release.
|
|
|
|
## Abstract
|
|
When interacting with the EthPM ecosystem, users and tooling can benefit from a URI scheme to identify EthPM assets. Being able to specify a package, registry, or release with a single string makes simplifies the steps required to install, publish, or distribute EthPM packages.
|
|
|
|
## Specification
|
|
`scheme://registry_address[:chain_id][/package_name[@package_version[/json_pointer]]]`
|
|
|
|
#### `scheme`
|
|
- Required
|
|
- Must be one of `ethpm` or `erc1319`. If future versions of the EthPM registry standard are designed and published via the ERC process, those ERCs will also be valid schemes.
|
|
|
|
#### `registry_address`
|
|
- Required
|
|
- This **SHOULD** be either an ENS name or a 0x-prefixed, checksummed address. ENS names are more suitable for cases where mutability of the underlying asset is acceptable and there is implicit trust in the owner of the name. 0x prefixed addresses are more preferable in higher security cases to avoid needing to trust the controller of the name.
|
|
|
|
#### `chain_id`
|
|
- Optional
|
|
- Integer representing the chain id on which the registry is located
|
|
- If omitted, defaults to `1` (mainnet).
|
|
|
|
#### `package_name`
|
|
- Optional
|
|
- String of the target package name
|
|
|
|
#### `package_version`
|
|
- Optional
|
|
- String of the target package version
|
|
- If the package version contains any [url unsafe characters](https://en.wikipedia.org/wiki/Percent-encoding), they **MUST** be safely escaped
|
|
- Since semver is not strictly enforced by the ethpm spec, if the `package_version` is omitted from a uri, tooling **SHOULD** avoid guessing in the face of any ambiguity and present the user with a choice from the available versions.
|
|
|
|
#### `json_pointer`
|
|
- Optional
|
|
- A path that identifies a specific asset within a versioned package release.
|
|
- This path **MUST** conform to the [JSON pointer](https://tools.ietf.org/html/rfc6901) spec and resolve to an available asset within the package.
|
|
|
|
## Rationale
|
|
Most interactions within the EthPM ecosystem benefit from a single-string representation of EthPM assets; from installing a package, to identifying a registry, to distributing a package. A single string that can faithfully represent any kind of EthPM asset, across the mainnet or testnets, reduces the mental overload for new users, minimizes configuration requirements for frameworks, and simplifies distribution of packages for package authors.
|
|
|
|
## Test Cases
|
|
A JSON file for testing various URIs can be found in the [`ethpm-spec`](https://github.com/ethpm/ethpm-spec/) repository fixtures.
|
|
|
|
## Implementation
|
|
The EthPM URI scheme has been implemented in the following libraries:
|
|
- [Brownie](https://eth-brownie.readthedocs.io/en/stable/)
|
|
- [Truffle](https://www.trufflesuite.com/docs/truffle/overview)
|
|
- [EthPM CLI](https://ethpm-cli.readthedocs.io/en/latest/)
|
|
|
|
## Security Considerations
|
|
In most cases, an EthPM URI points to an immutable asset, giving full security that the target asset has not been modified. However, in the case where an EthPM URI uses an ENS name as its registry address, it is possible that the ENS name has been redirected to a new registry, in which case the guarantee of immutability no longer exists.
|
|
|
|
## Copyright
|
|
Copyright and related rights waived via [CC0](../LICENSE.md).
|