[WIP - Do not merge] EthPM Integration

packages/web3-eth-packaging/USE_CASES.md

@@ -0,0 +1,89 @@
+# Use cases
+
+There are four main steps to using the Web3 EthPM API:
+
+1. Selecting a **registry** (and optionally setting a provider)
+2. Retrieving the **package artifact** by name (and optionally version)
+3. Extracting the **contract artifact** from the package artifact (since one package can have multiple contracts)
+4. Using the **contract artifact** with Web3.js
+
+## 1. Selecting a registry
+
+### With implicit provider
+
+```js
+web3.packaging.registry('packages.ethpm.eth')
+```
+
+Returns a `Packaging` object with the registry address saved, using the provider already inside the `web3` instance.
+
+### With explicit provider
+
+```js
+web3.packaging.registry('packages.ethlibs.eth', { provider: rinkebyProvider })
+```
+
+Returns a `Packaging` object with the registry address saved, using the provider passed in explicitly.
+
+## 2. Retrieving package artifact
+
+### By package name alone
+
+```js
+web3.packaging.registry('packages.ethpm.eth')
+              .getPackage('SimpleToken')
+```
+
+Returns a Promise that will resolve to a package artifact.
+
+### By package name and version
+
+```js
+web3.packaging.registry('packages.ethpm.eth')
+              .getPackage('SimpleToken', { version: '^1.1.5' })
+```
+
+Returns a Promise that will resolve to a package artifact.
+
+## 3. Extracting contract artifact
+
+Since each package artifact may contain more than one contract, we need a way to get specific contract artifacts from each package artifact object.
+
+```js
+// retrieve package artifact
+const MyPackage = await web3.packaging.registry('packages.ethpm.eth')
+                                      .getPackage('MyPackage')
+
+// destructure contract artifacts from package artifact
+const { SimpleToken, MathLib } = MyPackage
+```
+
+## 4. Using the contract artifact
+
+### Deploying a contract
+
+Assume that `SimpleToken` is a contract artifact object.
+
+```js
+const options = {
+  data: SimpleToken.data,     // byte code of the contract
+  from: "0xabC...777"         // account which funds deployment
+};
+
+const instance = new web3.eth.Contract(SimpleToken.abi, options);
+await instance.deploy().send();
+```
+
+### Interact with pre-deployed contract
+
+Assume that `MathLib` is a contract artifact object.
+
+```js
+const options = {   
+  address: MathLib.address,   
+  from: "0xabc...777"
+}; 
+
+const instance = new web3.eth.Contract(MathLib.abi, options);
+const sum = await instance.methods.safeAdd(5,7).call();
+```

packages/web3-eth-packaging/package.json

@@ -0,0 +1,10 @@
+{
+    "name": "web3-eth-packaging",
+    "namespace": "ethereum",
+    "version": "1.0.0-beta.36",
+    "description": "Web3 module to interact with EthPM.",
+    "repository": "https://github.com/ethereum/web3.js/tree/master/packages/web3-eth-packaging",
+    "license": "LGPL-3.0",
+    "main": "src/index.js",
+    "dependencies": {}
+}

packages/web3-eth-packaging/src/Packaging.js

@@ -0,0 +1,51 @@
+/*
+    This file is part of web3.js.
+    web3.js is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+    web3.js is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+    You should have received a copy of the GNU Lesser General Public License
+    along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/**
+ * @file packaging.js
+ *
+ * @author Adrian Li <[email protected]>
+ * @date 2018
+ */
+
+"use strict";
+
+/**
+ * Constructs a new instance of Packaging
+ *
+ * @method Packaging
+ * @param {Object} eth
+ * @constructor
+ */
+function Packaging(eth) {
+    this.eth = eth;
+    this.provider = null;
+    this.registryUrl = null;
+}
+
+Packaging.prototype.hello = function () {
+    return "Hello World";
+}
+
+Packaging.prototype.registry = function(registry, options) {
+    this.registryUrl = registry;
+    this.provider = this.eth.currentProvider;
+
+    if (options && options.provider) {
+        this.provider = options.provider
+    }
+
+    return this;
+}
+
+module.exports = Packaging;

packages/web3-eth-packaging/src/index.js

@@ -0,0 +1,25 @@
+/*
+    This file is part of web3.js.
+    web3.js is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+    web3.js is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+    You should have received a copy of the GNU Lesser General Public License
+    along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/**
+ * @file index.js
+ *
+ * @author Adrian Li <[email protected]>
+ * @date 2018
+ */
+
+"use strict";
+
+var Packaging = require('./Packaging');
+
+module.exports = Packaging;