Update readme

trufflesuite · Aug 11, 2020 · 46618af · 46618af
1 parent 82256c7
commit 46618af
Show file tree

Hide file tree

Showing 11 changed files with 184 additions and 6,787 deletions.
diff --git a/packages/config/src/configDefaults.ts b/packages/config/src/configDefaults.ts
@@ -33,11 +33,13 @@ export const getInitialConfig = ({
     resolver: null,
     artifactor: null,
     ethpm: {
-      ipfs_host: "ipfs.infura.io",
-      ipfs_protocol: "https",
-      registry: "0x8011df4830b4f696cd81393997e5371b93338878",
-      install_provider_uri:
-        "https://ropsten.infura.io/v3/26e88e46be924823983710becd929f36"
+      ipfsHost: "ipfs.infura.io",
+      ipfsProtocol: "https",
+      ipfsPort: "5001",
+      registry: {
+        address: "0x8011df4830b4f696cd81393997e5371b93338878",
+        network: "ropsten"
+      }
     },
     ens: {
       enabled: false,

diff --git a/packages/core/index.js b/packages/core/index.js
@@ -6,8 +6,7 @@ module.exports = {
   create: require("./lib/commands/create/helpers"),
   console: require("./lib/repl"),
   contracts: require("@truffle/workflow-compile"),
-  //package: require("./lib/package"),
   test: require("./lib/test"),
   version: pkg.version,
-  ganache: require("ganache-core/public-exports"),
+  ganache: require("ganache-core/public-exports")
 };
diff --git a/packages/core/lib/commands/install.js b/packages/core/lib/commands/install.js
@@ -7,8 +7,8 @@ const command = {
     options: [
       {
         option: "packageId",
-        description:
-          "(required) Name of the package as listed in the Ethereum Package Registry. Format: packageName@version"
+        description: `(required) Name of the package as listed in the Ethereum Package Registry. 
+          Accepted formats: packageName, packageName@version, ethpm URI, ipfs URI.`
       },
       {
         option: "--alias",

diff --git a/packages/ethpm-v1/README.md b/packages/ethpm-v1/README.md
@@ -1,11 +1,9 @@
 # `ethpm-v1`
 
-> TODO: description
-
 ## Usage
 
 ```
 const ethpmV1 = require('ethpm-v1');
-
-// TODO: DEMONSTRATE API
 ```
+
+This package contains support for the deprecated v1 version of the ethpm specification for backwards compatibility purposes.
diff --git a/packages/ethpm-v1/lib/ethpm-v1.js b/packages/ethpm-v1/lib/ethpm-v1.js
@@ -1,5 +1,3 @@
-"use strict";
-
 const expect = require("@truffle/expect");
 const TruffleError = require("@truffle/error");
 const Networks = require("@truffle/core/lib/networks");

diff --git a/packages/ethpm-v1/package.json b/packages/ethpm-v1/package.json
@@ -6,7 +6,6 @@
     "ethpm",
     "packages"
   ],
-  "author": "Nick Gheorghita <[email protected]>",
   "homepage": "http://www.ethpm.com",
   "license": "MIT",
   "main": "lib/ethpm-v1.js",
@@ -15,7 +14,7 @@
   },
   "directories": {
     "lib": "lib",
-    "test": "__tests__"
+    "test": "tests"
   },
   "files": [
     "lib"
@@ -24,9 +23,6 @@
     "type": "git",
     "url": "git+https://github.com/trufflesuite/truffle.git"
   },
-  "scripts": {
-    "test": "echo \"hellp\""
-  },
   "bugs": {
     "url": "https://github.com/trufflesuite/truffle/issues"
   }

diff --git a/packages/ethpm-v3/README.md b/packages/ethpm-v3/README.md
@@ -1,81 +1,103 @@
-# `ethpm-v3`
+# truffle/ethpm-v3
 
-> TODO: description
+A package that provides truffle support for [ethpm v3](http://ethpm.github.io/ethpm-spec/v3-package-spec.html), the default version in truffle.
 
 ## Usage
+Installing an ethpm package in your truffle project will automatically generate an `_ethpm_packages/` directory to which the package assets will be written. This directory should be treated like a `node_modules/` directory, and not be edited directly.
+
+## Configuration
+To configure ethpm, define the following fields inside your `truffle-config.js`.
+
+```js
+{
+  // required to lookup a registry address via ens
+  ens: {
+    enabled: true    
+  },
+  // below are all of the default config values for ethpm
+  ethpm: {
+    ipfsHost: "ipfs.infura.io",
+    ipfsProtocol: "https",
+    ipfsPort: "5001",
+    registry: {
+      address: "0xabc", // ENS is supported here
+      network: "ropsten" // must match a network with an available provider defined in `networks` field
+    }
+    version: "3" // only supported versions include ("1", "3")
+  }
+}
+```
 
+## List
 ```
-const ethpmV3 = require('ethpm-v3');
+truffle packages
 ```
+Reads all directly available packages on the connected registry.
 
-TODO:
-audit all error messages / include useful links to cli/docs/etc...
-useful comments throughout
-test all the different install scenarios
-- test auto semver detect
-warnings about trusting packages?
-ethpm-v1 tests
-truffle-config: ethpm/registry/network_id -> networkId
-should the network provider be a function? or instance?
-install from github blob uri
-
-is there a better display output workflow for sending publish tx
-do we want timeout errors? // what's the best pattern to catch errors? 
-
-how many deployments/chain does truffle support? if we migrate will it replace a deployment? (probably yes)
-
-there are no contractTypes in compilers from ethpm.js
-
-warning if ppl installed a package with insufficient artifacts - but expect them via deploy?
+## Install
 
-- should we require `name` and `version` in ethpm.json?
-
-QUESTIONS:
-do we support ens in truffle config for the registry address?
-should the network provider be a function? or instance?
-truffle default registry?
-
-# questions
-- how to install `ethpm` npm package as different versions for `ethpm-v1` / `ethpm-v3`
-- can we enforce either v1 / v3 per project? combining manifests seems tricky..
-	- should we have a v1 and v3 resolver?
+### Install the latest version of a package from connected registry
+```
+truffle install owned
+```
+- Will throw an error requiring a specified version if package versioning does not follow semver.
 
-todo: resolver source for both ethpmv1 & v3
 
+### Install a specific version of a package from connected registry
+```
+truffle install [email protected]
+```
 
+### Install the latest version of a package from any registry
 ```
-truffle packages
-````
-todo: test with big registry
-todo: test with no registry
-todo: test with invalid registry
+truffle install owned ethpm://0x123/owned
+truffle install owned ethpm://0x123:1/owned
+```
+- will throw an error requiring a specified version if package versioning does not follow semver.
+- using an ethpm uri overrides the registry set in `truffle-config.js`
 
+### Install a specific version of a package from any registry
+```
+truffle install owned ethpm://0x123/[email protected]
+truffle install owned ethpm://0x123:1/[email protected]
 ```
-truffle install [email protected]
-truffle install ethpm://packages.eth:3/xxx@1.0.0
-truffle install ipfs://Qmasdfa --alias=awesome
+```
+truffle install owned ethpm://libraries.snakecharemers.eth/owned@1.0.0
+truffle install owned ethpm://libraries.snakecharemers.eth:1/[email protected]
 ```
 
-- supports either v1 or v3
+### Install a package under an alias
+```
+truffle install [email protected] --alias owned-2
+```
+- This can be useful for installing multiple packages that have the same name (installed packages share a namespace).
+- This can be useful for adding custom identifiers to installed packages for whatever reason.
 
+## Publish
 ```
 truffle publish
-````
-
-settings required in `ethpm.json`
-
-
-
-escrow: QmNpLojZo471M357NTUZ1qKDwjUZrfYctWhzPtNFEXcSaL
-piper-coin: QmNbvXM5ig6Qtz6abRuG52KgjFqfXDyBCdRTz7QDENgxzv
-owned: QmcxvhkJJVpbxEAa6cgW3B6XwPJb79w9GpNUv2P2THUzZR
-safe-math-lib: QmWnPsiS3Xb8GvCDEBFnnKs8Yk4HaAX6rCqJAaQXGbCoPk
-standard-token: QmQNffBrmbB3TuBCtYfYsJWJVLssatWXa3H6CkGeyNUySA
-transferable: QmYX2yqyrpaJQugHQKnaWYcnkJEdnJC4exKaEVR3RK3TTf
-wallet-with-send: QmX95FoLeVAFbnbj1PEDQaXDAeccmjbK8Zbw4eos9PAxeA
-wallet: QmPtZxv9uEtr671XVjevHDacP9M4Tw9T7p6n1MS1xdyMeC
+```
 
+- Requires that a valid `ethpm.json` file exists in your project root directory.
+- Requires that provider for connected registry has release privileges on that registry.
+- Running `truffle publish` will automatically generate an ethpm manifest from available contract assets and publish it to the connected registry.
+
+#### Sample `ethpm.json`
+```jsonld=
+{
+    "name": "package-name", // required
+    "version": "0.1.0", // required
+    "meta": {
+        "license": "licenseType",
+        "authors": ["author-1", "author-2"],
+        "description": "Description of package.",
+        "keywords": ["keyword1", "keyword2"],
+        "links": {
+            "documentation": "www.documentation.com",
+            "repo": "www.repository.com",
+            "website": "www.website.com"
+        }
+    }
+}
+```
 
-ICEBOX:
-support github uris
-deploy a registry?
diff --git a/packages/ethpm-v3/lib/ethpm-v3.js b/packages/ethpm-v3/lib/ethpm-v3.js
@@ -6,6 +6,7 @@ const semver = require("semver");
 const Web3 = require("web3");
 const path = require("path");
 const fs = require("fs");
+const { isAddress } = require("web3-utils");
 const TruffleContractSchema = require("@truffle/contract-schema");
 const utils = require("./utils");
 
@@ -108,12 +109,24 @@ const PackageV3 = {
       );
     }
 
+    options.logger.log(
+      `! Please use caution when interacting with installed packages.\n! Only use packages that are published on trusted registries, or whose assets you've verified directly.`
+    );
     options.logger.log("Fetching package manifest...");
-    var targetRegistry = options.ethpm.registry.address;
     var targetNetwork = options.ethpm.registry.network;
     var targetNetworkId = options.networks[targetNetwork].network_id;
     var provider = utils.pluckProviderFromConfig(options);
 
+    let targetRegistry;
+    if (!isAddress(options.ethpm.registry.address)) {
+      targetRegistry = await utils.resolveEnsName(
+        options.ethpm.registry.address,
+        provider,
+        options
+      );
+    } else {
+      targetRegistry = options.ethpm.registry.address;
+    }
     // Create an ethpm instance
     let ethpm;
     try {
@@ -148,7 +161,7 @@ const PackageV3 = {
     }
 
     // Parse ethpm URI || packageId
-    if (!manifestUri) {
+    if (!resolvedManifestUri) {
       // Parse ethpm uri
       if (
         options.packageId.startsWith("ethpm://") ||
@@ -173,12 +186,9 @@ const PackageV3 = {
           );
         }
 
-        if (
-          typeof targetRegistry === "undefined" ||
-          typeof targetNetworkId === "undefined"
-        ) {
+        if (!targetRegistry || !targetNetworkId) {
           throw new TruffleError(
-            `Missing an 'ethpm/registry/address' and 'ethpm/registry/network_id' in your truffle config for the target registry.`
+            `Missing an 'ethpm/registry/address' and 'ethpm/registry/network' in your truffle config for the target registry.`
           );
         }
         targetPackageName = packageData[0];
@@ -269,15 +279,11 @@ const PackageV3 = {
     if (ethpmPackage.deployments) {
       ethpmPackage.deployments.forEach((value, key, _) => {
         const foundGenesisBlock = key.host.toLowerCase();
-        if (!(foundGenesisBlock in utils.SUPPORTED_GENESIS_BLOCKS)) {
-          // we probably shouldn't throw here - just skip over unsupported deployments...
-          throw new TruffleError(
-            `Blockchain uri detected with unsupported genesis block: ${foundGenesisBlock}`
-          );
+        if (foundGenesisBlock in utils.SUPPORTED_GENESIS_BLOCKS) {
+          normalizedDeployments[
+            utils.SUPPORTED_GENESIS_BLOCKS[foundGenesisBlock]
+          ] = value;
         }
-        normalizedDeployments[
-          utils.SUPPORTED_GENESIS_BLOCKS[foundGenesisBlock]
-        ] = value;
       });
     }
 
@@ -459,7 +465,7 @@ const PackageV3 = {
     try {
       await w3.eth.sendSignedTransaction(tx.raw);
     } catch (err) {
-      options.logger.log(err);
+      options.logger.log(`Error publishing release data to registry: ${err}`);
       return;
     }
     options.logger.log(