A standard interface for smart contract package registries.
This EIP specifies an interface for publishing to and retrieving assets from smart contract package registries. It is a companion EIP to 1123 which defines a standard for smart contract package manifests.
The goal is to establish a framework that allows smart contract publishers to design and deploy code registries with arbitrary business logic while exposing a set of common endpoints that tooling can use to retrieve assets for contract consumers.
A clear standard would help the existing EthPM Package Registry evolve from a centralized, single-project community resource into a decentralized multi-registry system whose constituents are bound together by the proposed interface. In turn, these registries could be ENS name-spaced, enabling installation conventions familiar to users of npm and other package managers.
Examples
$ ethpm install packages.zeppelin.eth/Ownership
const SimpleToken = await web3.packaging
.registry('packages.ethpm.eth')
.getPackage('simple-token')
.getVersion('^1.1.5');
The specification describes a small read/write API whose components are mandatory. It allows registries to manage versioned releases using the conventions of semver without imposing this as a requirement. It assumes registries will share the following structure and conventions:
bytes32 releaseId which must be unique for a given package name and release version string pair.Package Names / Release Versions
"simple-token" # package name
"1.0.1" # version string
Release IDs
Implementations are free to choose any scheme for generating a releaseId. A common approach would be to hash the strings together as below:
// Hashes package name and a release version string
function generateReleaseId(string packageName, string version)
public
view
returns (bytes32 releaseId)
{
return keccak256(abi.encodePacked(packageName, version));
}
Implementations must expose this id generation logic as part of their public read API so
tooling can easily map a string based release query to the registry's unique identifier for that release.
Manifest URIs
Any IPFS or Swarm URI meets the definition of manifestURI.
Another example is content on GitHub addressed by its SHA-1 hash. The Base64 encoded content at this hash can be obtained by running:
$ curl https://api.github.com/repos/:owner/:repo/git/blobs/:file_sha
# Example
$ curl https://api.github.com/repos/rstallman/hello/git/blobs/ce013625030ba8dba906f756967f9e9ca394464a
The string "hello" can have its GitHub SHA-1 hash independently verified by comparing it to the output of:
$ printf "blob 6\000hello\n" | sha1sum
> ce013625030ba8dba906f756967f9e9ca394464a
The write API consists of a single method, release. It passes the registry the package name, a
version identifier for the release, and a URI specifying the location of a manifest which
details the contents of the release.
function release(string packageName, string version, string manifestURI) public
returns (bytes32 releaseId);
MUST be triggered when release is successfully called.
event VersionRelease(string packageName, string version, string manifestURI)
The read API consists of a set of methods that allows tooling to extract all consumable data from a registry.
// Retrieves a slice of the list of all unique package identifiers in a registry.
// `offset` and `limit` enable paginated responses / retrieval of the complete set. (See note below)
function getAllPackageIds(uint offset, uint limit) public view
returns (
bytes32[] packageIds,
uint pointer
);
// Retrieves the unique string `name` associated with a package's id.
function getPackageName(bytes32 packageId) public view returns (string packageName);
// Retrieves the registry's unique identifier for an existing release of a package.
function getReleaseId(string packageName, string version) public view returns (bytes32 releaseId);
// Retrieves a slice of the list of all release ids for a package.
// `offset` and `limit` enable paginated responses / retrieval of the complete set. (See note below)
function getAllReleaseIds(string packageName, uint offset, uint limit) public view
returns (
bytes32[] releaseIds,
uint pointer
);
// Retrieves package name, release version and URI location data for a release id.
function getReleaseData(bytes32 releaseId) public view
returns (
string packageName,
string version,
string manifestURI
);
// Retrieves the release id a registry *would* generate for a package name and version pair
// when executing a release.
function generateReleaseId(string packageName, string version)
public
view
returns (bytes32 releaseId);
// Returns the total number of unique packages in a registry.
function numPackageIds() public view returns (uint totalCount);
// Returns the total number of unique releases belonging to the given packageName in a registry.
function numReleaseIds(string packageName) public view returns (uint totalCount);
Pagination
getAllPackageIds and getAllReleaseIds support paginated requests because it's possible that the return values for these methods could become quite large. The methods should return a pointer that points to the next available item in a list of all items such that a caller can use it to pick up from where the previous request left off. (See here for a discussion of the merits and demerits of various pagination strategies.) The limit parameter defines the maximum number of items a registry should return per request.
The proposal hopes to accomplish the following:
Registries may offer more complex read APIs that manage requests for packages within a semver range or at latest etc. This EIP is agnostic about how tooling or registries might implement these. It recommends that registries implement EIP-165 and avail themselves of resources to publish more complex interfaces such as EIP-926.
No existing standard exists for package registries. The package registry currently deployed by EthPM would not comply with the standard since it implements only one of the method signatures described in the specification.
A reference implementation of this proposal is in active development at the EthPM organization on GitHub here.
Copyright and related rights waived via CC0.