Ethereum Package Registry (V2)

Install

$ npm install
$ docker pull ethereum/client-go:v1.8.6

Test

$ npm test        # vs. ganache-cli
$ npm test:geth   # vs. geth

Coverage

$ npm run coverage

Lint

For help, see the Solium documentation <https://github.com/duaraghav8/Solium>.

$ npm run lint

Authority

IndexedOrderedSetLib

library IndexedOrderedSetLib
Title:Library implementing an array type which allows O(1) lookups on values.
Author:Piper Merriam <pipermerriam@gmail.com>
modifier requireValue(IndexedOrderedSet storage self, bytes32 value)
function size(IndexedOrderedSet storage self)
 public
 view
 returns (uint)

Returns the size of the set

Parameters:
  • self – The set
function contains(IndexedOrderedSet storage self, bytes32 value)
 public
 view
 returns (bool)

Returns boolean if the key is in the set

Parameters:
  • self – The set
  • value – The value to check
function indexOf(IndexedOrderedSet storage self, bytes32 value)
 public
 view
 requireValue(self, value)
 returns (uint)

Returns the index of the value in the set.

Parameters:
  • self – The set
  • value – The value to look up the index for.
function pop(IndexedOrderedSet storage self, uint idx)
 public
 returns (bytes32)

Removes the element at index idx from the set and returns it.

Parameters:
  • self – The set
  • idx – The index to remove and return.
function remove(IndexedOrderedSet storage self, bytes32 value)
 public
 requireValue(self, value)
 returns (bool)

Removes the element at index idx from the set

Parameters:
  • self – The set
  • value – The value to remove from the set.
function get(IndexedOrderedSet storage self, uint idx)
 public
 view
 returns (bytes32)

Retrieves the element at the provided index.

Parameters:
  • self – The set
  • idx – The index to retrieve.
function add(IndexedOrderedSet storage self, bytes32 value)
 public
 returns (bool)

Pushes the new value onto the set

Parameters:
  • self – The set
  • value – The value to push.

PackageDB

contract PackageDB is Authorized
Title:Database contract for a package index package data.
Author:Tim Coulter <tim.coulter@consensys.net>, Piper Merriam <pipermerriam@gmail.com>
mapping (bytes32 => Package) _recordedPackages
IndexedOrderedSetLib.IndexedOrderedSet _allPackageNameHashes
event PackageReleaseAdd(bytes32 indexed nameHash, bytes32 indexed releaseHash)
event PackageReleaseRemove(bytes32 indexed nameHash, bytes32 indexed releaseHash)
event PackageCreate(bytes32 indexed nameHash)
event PackageDelete(bytes32 indexed nameHash, string reason)
event PackageOwnerUpdate(bytes32 indexed nameHash, address indexed oldOwner, address indexed newOwner)
modifier onlyIfPackageExists(bytes32 nameHash)
function setPackage(string name)
 public
 auth
 returns (bool)

Creates or updates a release for a package. Returns success.

Parameters:
  • name – Package name
function removePackage(bytes32 nameHash, string reason)
 public
 auth
 onlyIfPackageExists(nameHash)
 returns (bool)

Removes a package from the package db. Packages with existing releases may not be removed. Returns success.

Parameters:
  • nameHash – The name hash of a package.
function setPackageOwner(bytes32 nameHash, address newPackageOwner)
 public
 auth
 onlyIfPackageExists(nameHash)
 returns (bool)

Sets the owner of a package to the provided address. Returns success.

Parameters:
  • nameHash – The name hash of a package.
  • newPackageOwner – The address of the new owner.
function packageExists(bytes32 nameHash)
 public
 view
 returns (bool)

Query the existence of a package with the given name. Returns boolean indicating whether the package exists.

Parameters:
  • nameHash – The name hash of a package.
function getNumPackages()
 public
 view
 returns (uint)

Return the total number of packages

function getPackageNameHash(uint idx)
 public
 view
 returns (bytes32)

Returns package namehash at the provided index from the set of all known name hashes.

Parameters:
  • idx – The index of the package name hash to retrieve.
function getPackageData(bytes32 nameHash)
 public
 view
 onlyIfPackageExists(nameHash)
 returns (address packageOwner, uint createdAt, uint updatedAt)

Returns information about the package.

Parameters:
  • nameHash – The name hash to look up.
function getPackageName(bytes32 nameHash)
 public
 view
 onlyIfPackageExists(nameHash)
 returns (string)

Returns the package name for the given namehash

Parameters:
  • nameHash – The name hash to look up.
function getAllPackageIds(uint _offset, uint limit)
 public
 view
 returns (bytes32[] packageIds, uint offset)

Returns a slice of the array of all package hashes for the named package.

Parameters:
  • offset – The starting index for the slice.
  • limit – The length of the slice
function hashName(string name)
 public
 pure
 returns (bytes32)

Returns name hash for a given package name.

Parameters:
  • name – Package name

PackageIndex

PackageIndexInterface

ReleaseDB

contract ReleaseDB is Authorized
Title:Database contract for a package index.
Author:Tim Coulter <tim.coulter@consensys.net>, Piper Merriam <pipermerriam@gmail.com>
mapping (bytes32 => Release) _recordedReleases
mapping (bytes32 => bool) _removedReleases
IndexedOrderedSetLib.IndexedOrderedSet _allReleaseIds
mapping (bytes32 => IndexedOrderedSetLib.IndexedOrderedSet) _releaseIdsByNameHash
mapping (bytes32 => string) _recordedVersions
mapping (bytes32 => bool) _versionExists
event ReleaseCreate(bytes32 indexed releaseId)
event ReleaseUpdate(bytes32 indexed releaseId)
event ReleaseDelete(bytes32 indexed releaseId, string reason)
modifier onlyIfVersionExists(bytes32 versionHash)
modifier onlyIfReleaseExists(bytes32 releaseId)
function setRelease(bytes32 nameHash, bytes32 versionHash, string manifestURI)
 public
 auth
 returns (bool)

Creates or updates a release for a package. Returns success.

Parameters:
  • nameHash – The name hash of the package.
  • versionHash – The version hash for the release version.
  • manifestURI – The URI for the release manifest for this release.
function removeRelease(bytes32 releaseId, string reason)
 public
 auth
 onlyIfReleaseExists(releaseId)
 returns (bool)

Removes a release from a package. Returns success.

Parameters:
  • releaseId – The release hash to be removed
  • reason – Explanation for why the removal happened.
function setVersion(string version)
 public
 auth
 returns (bytes32)

Adds the given version to the local version database. Returns the versionHash for the provided version.

Parameters:
  • version – Version string (ex: ‘1.0.0’)
function getAllReleaseIds(bytes32 nameHash, uint _offset, uint limit)
 public
 view
 returns (bytes32[] releaseIds, uint offset)

Returns a slice of the array of all releases hashes for the named package.

Parameters:
  • offset – The starting index for the slice.
  • limit – The length of the slice
function getNumReleasesForNameHash(bytes32 nameHash)
 public
 view
 returns (uint)

Get the total number of releases

Parameters:
  • nameHash – the name hash to lookup.
function getReleaseIdForNameHash(bytes32 nameHash, uint idx)
 public
 view
 returns (bytes32)

Release hash for a Package at a given index

Parameters:
  • nameHash – the name hash to lookup.
  • idx – The index of the release hash to retrieve.
function releaseExists(bytes32 releaseId)
 public
 view
 returns (bool)

Query the existence of a release at the provided version for a package. Returns boolean indicating whether such a release exists.

Parameters:
  • releaseId – The release hash to query.
function releaseExisted(bytes32 releaseHash)
 public
 view
 returns (bool)

Query the past existence of a release at the provided version for a package. Returns boolean indicating whether such a release ever existed.

Parameters:
  • releaseHash – The release hash to query.
function versionExists(bytes32 versionHash)
 public
 view
 returns (bool)

Query the existence of the provided version in the recorded versions. Returns boolean indicating whether such a version exists.

Parameters:
  • versionHash – the version hash to check.
function getReleaseData(bytes32 releaseId)
 public
 view
 onlyIfReleaseExists(releaseId)
 returns (bytes32 nameHash, bytes32 versionHash, uint createdAt, uint updatedAt)

Returns the releaseData for the given release has a package.

Parameters:
  • releaseId – The release hash.
function getVersion(bytes32 versionHash)
 public
 view
 onlyIfVersionExists(versionHash)
 returns (string)

Returns string version identifier from the version of the given release hash.

Parameters:
  • versionHash – the version hash
function getManifestURI(bytes32 releaseId)
 public
 view
 onlyIfReleaseExists(releaseId)
 returns (string)

Returns the URI of the release manifest for the given release hash.

Parameters:
  • releaseId – Release hash
function hashVersion(string version)
 public
 pure
 returns (bytes32)

Returns version hash for the given semver version.

Parameters:
  • version – Version string
function hashRelease(bytes32 nameHash, bytes32 versionHash)
 public
 pure
 returns (bytes32)

Returns release hash for the given release

Parameters:
  • nameHash – The name hash of the package name.
  • versionHash – The version hash for the release version.

ReleaseValidator

contract ReleaseValidator
Title:Database contract for a package index.
Author:Piper Merriam <pipermerriam@gmail.com>
function validateRelease(PackageDB packageDb, ReleaseDB releaseDb, address callerAddress, string name, string version, string manifestURI)
 public
 view
 returns (bool)

Runs validation on all of the data needed for releasing a package. Returns success.

Parameters:
  • packageDb – The address of the PackageDB
  • releaseDb – The address of the ReleaseDB
  • callerAddress – The address which is attempting to create the release.
  • name – The name of the package.
  • version – The version string of the package (ex: 1.0.0)
  • manifestURI – The URI of the release manifest.
function validateAuthorization(PackageDB packageDb, address callerAddress, string name)
 public
 view
 returns (bool)

Validate whether the callerAddress is authorized to make this release.

Parameters:
  • packageDb – The address of the PackageDB
  • callerAddress – The address which is attempting to create the release.
  • name – The name of the package.
function validateIsNewRelease(PackageDB packageDb, ReleaseDB releaseDb, string name, string version)
 public
 view
 returns (bool)

Validate that the version being released has not already been released.

Parameters:
  • packageDb – The address of the PackageDB
  • releaseDb – The address of the ReleaseDB
  • name – The name of the package.
  • version – The version string for the release
uint constant DIGIT_0
uint constant DIGIT_9
uint constant LETTER_a
uint constant LETTER_z
bytes1 constant DASH
function validatePackageName(PackageDB packageDb, string name)
 public
 view
 returns (bool)

Returns boolean whether the provided package name is valid.

Parameters:
  • packageDb – The address of the PackageDB
  • name – The name of the package.
function validateStringIdentifier(string value)
 public
 pure
 returns (bool)

Returns boolean whether the input string has a length

Parameters:
  • value – The string to validate.

SemVersionLib

Appendix: Gas Usage

·---------------------------------------------------------------------------------|----------------------------·
|                                       Gas                                       ·  Block limit: 6721975 gas  │
················································|·································|·····························
|  Methods                                      ·           6 gwei/gas            ·       488.16 eur/eth       │
·······················|························|·········|···········|···········|··············|··············
|  Contract            ·  Method                ·  Min    ·  Max      ·  Avg      ·  # calls     ·  eur (avg)  │
·······················|························|·········|···········|···········|··············|··············
|  PackageDB           ·  removePackage         ·      -  ·        -  ·    43401  ·           3  ·       0.13  │
·······················|························|·········|···········|···········|··············|··············
|  PackageDB           ·  setPackage            ·  29045  ·   174607  ·   116382  ·           5  ·       0.34  │
·······················|························|·········|···········|···········|··············|··············
|  PackageDB           ·  setPackageOwner       ·      -  ·        -  ·    53768  ·           3  ·       0.16  │
·······················|························|·········|···········|···········|··············|··············
|  PackageIndex        ·  release               ·  61302  ·  1084901  ·   542985  ·          67  ·       1.59  │
·······················|························|·········|···········|···········|··············|··············
|  PackageIndex        ·  setPackageDb          ·  13711  ·    43702  ·    35990  ·           6  ·       0.11  │
·······················|························|·········|···········|···········|··············|··············
|  PackageIndex        ·  setReleaseDb          ·  13909  ·    44098  ·    36343  ·           6  ·       0.11  │
·······················|························|·········|···········|···········|··············|··············
|  PackageIndex        ·  setReleaseValidator   ·  27312  ·    43592  ·    40323  ·           5  ·       0.12  │
·······················|························|·········|···········|···········|··············|··············
|  PackageIndex        ·  transferPackageOwner  ·  39416  ·    71980  ·    61083  ·           3  ·       0.18  │
·······················|························|·········|···········|···········|··············|··············
|  ReleaseDB           ·  removeRelease         ·  73622  ·    84244  ·    81088  ·           4  ·       0.24  │
·······················|························|·········|···········|···········|··············|··············
|  ReleaseDB           ·  setAuthority          ·  14602  ·    45703  ·    41531  ·          19  ·       0.12  │
·······················|························|·········|···········|···········|··············|··············
|  ReleaseDB           ·  setOwner              ·      -  ·        -  ·    30373  ·           2  ·       0.09  │
·······················|························|·········|···········|···········|··············|··············
|  ReleaseDB           ·  setRelease            ·  92285  ·   402299  ·   351358  ·          28  ·       1.03  │
·······················|························|·········|···········|···········|··············|··············
|  ReleaseDB           ·  setVersion            ·  26710  ·   209149  ·   117459  ·           3  ·       0.34  │
·······················|························|·········|···········|···········|··············|··············
|  ReleaseDB           ·  updateLatestTree      ·  62345  ·   125091  ·    80059  ·          42  ·       0.23  │
·······················|························|·········|···········|···········|··············|··············
|  WhitelistAuthority  ·  setAnyoneCanCall      ·  44969  ·    46249  ·    46204  ·          65  ·       0.14  │
·······················|························|·········|···········|···········|··············|··············
|  WhitelistAuthority  ·  setCanCall            ·  46952  ·    48232  ·    47959  ·          15  ·       0.14  │
·······················|························|·········|···········|···········|··············|··············
|  Deployments                                  ·                                 ·  % of limit  ·             │
················································|·········|···········|···········|··············|··············
|  IndexedOrderedSetLib                         ·      -  ·        -  ·   442132  ·       6.6 %  ·       1.29  │
················································|·········|···········|···········|··············|··············
|  PackageDB                                    ·      -  ·        -  ·  1414712  ·        21 %  ·       4.14  │
················································|·········|···········|···········|··············|··············
|  PackageIndex                                 ·      -  ·        -  ·  4812689  ·      71.6 %  ·      14.10  │
················································|·········|···········|···········|··············|··············
|  ReleaseDB                                    ·      -  ·        -  ·  3254763  ·      48.4 %  ·       9.53  │
················································|·········|···········|···········|··············|··············
|  ReleaseValidator                             ·      -  ·        -  ·  2467348  ·      36.7 %  ·       7.23  │
················································|·········|···········|···········|··············|··············
|  SemVersionLib                                ·      -  ·        -  ·  1727350  ·      25.7 %  ·       5.06  │
················································|·········|···········|···········|··············|··············
|  WhitelistAuthority                           ·      -  ·        -  ·   940365  ·        14 %  ·       2.75  │
·-----------------------------------------------|---------|-----------|-----------|--------------|-------------·

Indices and tables