Add ethpmv3 blog

src/blog/using-ethpm-and-truffle.md

@@ -0,0 +1,261 @@
+[ethpm](https://www.ethpm.com/) is a framework-agnostic, secure protocol for packaging and distributing evm smart contracts and their on-chain deployments. Truffle now comes with built-in support for [ethpm v3](http://ethpm.github.io/ethpm-spec/v3-package-spec.html) to simplify your development workflow.
+
+## use ethpm x truffle to ...
+
+- **explore**
+	- verfied smart contracts & protocols
+	- on-chain deployments from any chain
+-	**install** 
+	- interact with verified deployments from your truffle console
+	- import packaged contracts directly in your own contract
+	- re-deploy packaged contracts on any chain
+	- use existing on-chain libraries, stop re-deploying every library you use
+- **publish**
+	- your smart contracts and deployments for other developers to use in their projects
+
+## some ethpm definitions
+- **package**: a [standardized](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2678.md) JSON object containing the smart contract assets
+- **registry**: a [standardized](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1319.md) on-chain datastore that stores package identifiers
+- **deployment**: a deployed instance of a contract, either on mainnet or any testnet
+- **ethpm uri**: a [standardized](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2942.md) uri scheme used to identify an ethpm registry or a package
+	- format: `ethpm://registry_address:chain_id/package_name@version`
+	- registry example: `ethpm://libraries.ethpm.eth:3`
+	- package example: `ethpm://libraries.ethpm.eth:3/[email protected]`
+
+
+# a word on trust
+In any programming paradigm, using packaged code inherently requires **trust** that the author of the package does not include malicious code. With blockchains, the incentive to create malicious packages is greater - since there is direct access to valuable assets. With ethpm - you are always guaranteed to execute the code of the package author. But, we can **not** guarantee that the package author is trustworthy.
+
+```ONLY INSTALL PACKAGES FROM TRUSTED REGISTRIES!```
+
+There is no central registry in ethpm (eg. npm, pip, etc..). ethpm uses a federated model where individual developers, auditors, and organizations maintain their own, permissioned registry. Only the controlling account of a registry is allowed to publish packages to that registry. As long as you **trust** the controlling account of a registry, it is safe to install packages from their registry.
+
+```ONLY INSTALL PACKAGES FROM TRUSTED REGISTRIES!```
+
+**ANYBODY** can create an ethpm registry. **ANYBODY** can create an ethpm package. You must assume that there will be malicious packages on non-permissioned ethpm registries, trying to steal your crypto. Truffle comes connected to a non-permissioned ethpm registry by default. This is simply to enable experimentation with the ethpm protocol - and packages on this registry should **NEVER** be used in production or to manage valuable assets.
+
+**Always** verify that a registry is maintained by a trusted source. Verification of registry addresses is best done by advertising your registry address via the `README.md` on the Github repository, or Twitter. Connecting your registry address to an ENS domain name further helps simplify the trust-establishment process.
+
+One more time. Just because a package is available, this **DOES NOT** establish that it is safe. Trust in a package's safety is established by verifying the controlling account of the package's host registry. 
+
+tl:dr; ```ONLY INSTALL PACKAGES FROM TRUSTED REGISTRIES!```
+
+# 3 main commands
+- `truffle packages`: list available packages on an ethpm registry
+- `truffle install`:  install a package into your truffle project
+- `truffle publish`: publish your truffle project as an ethpm package
+
+# setting your truffle-config.js
+Below are the default values Truffle needs to know to interact with the ethpm ecosystem. This `ethpm` config is located within a project's `truffle-config.js`. To override any of these default values for your project, simply include the field in your project's `truffle-config.js`.
+```javascript
+  ethpm: {
+    ipfsHost: "ipfs.infura.io",
+    ipfsProtocol: "https",
+    ipfsPort: "5001",
+    registry: {
+      address: "libraries.ethpm.eth",
+      network: "ropsten",
+    },
+    version: "3"
+  },
+```
+* `registry` defines the address and network of the connected registry
+* the specified `network` must have a matching provider available under the `networks` key
+* `address` supports `0x` prefixed addresses or ENS names (to use ENS, make sure you enable ENS in your `truffle-config`)
+
+# finding a package to install
+```ONLY INSTALL PACKAGES FROM REGISTRIES YOU TRUST!```
+
+By default, Truffle comes connected to an un-authorized ethpm registry. This means that **anybody** can publish a package to this registry. Packages hosted on this registry should **not** be considered safe to use, but they will make it easier to start playing around with ethpm.
+
+The best place to find an interesting ethpm package is from the package author. Whether it's the organization's webpage, github repo, or a developer's twitter bio - make sure you source your packages from a registry you trust. If you can't find a registry for the contracts you want - package them up yourself, or tweet at the author to publish their contracts as an ethpm package!
+
+## tutorial package layout
+In this tutorial, we'll be using a package containing the OpenZeppelin ERC20 contract. This package is for tutorial purposes only, it has not been audited and should not be used in production.
+
+- name: `erc20-example`
+- version: `0.1.0`
+- manifest uri: `ipfs://QmYmstuuQmVVaWvde5VHzwxs5zDaJbjGk8nGHeTfZnEgoe`
+- ethpm uri: `ethpm://0x0bd0200357D26A0bB5d1D1c1Fd56C317B68d15d5:3/[email protected]`
+- layout:
+	- `erc20/`
+		- `ERC20.sol`
+		- `IERC20.sol`
+		- `GSN/Context.sol`
+		- `buildDependencies/`
+			- `safe-math`
+				- `SafeMath.sol`
+		- `deployments/`
+			- `ropsten/ERC20`
+			- `goerli/ERC20`
+
+# `truffle packages`
+To list the available packages on Truffle's default registry or the registry defined in your `truffle-config.js` - run `truffle packages`.
+
+```bash
+Searching for packages published on registry located at: 0x586b308Cbef331CE15fED8ff1c56aDeA594636cA
+Registry controlled by account: 0x9182902397B57a8c611D764D4DCD24BA951B4319
+Package: address
+  - 0.1.0 @ ipfs://QmZsDxfqbjrGXZovHMpQQE9QbCPEPwL6rVZLYr5cS9givF
+Package: create2
+  - 0.1.0 @ ipfs://QmbcDBSUyoZWcSQEZvJjpscx2JXqPdgMucAjV2ZPhdxE4Q
+Package: ecdsa
+  - 0.1.0 @ ipfs://QmQtWK7Q9ttuH2EP2r25YX66tCbkSm5jqZZTm2akPncHaC
+Package: enumerable-map
+  - 0.1.0 @ ipfs://QmRzQnzPf63mTjwSc2kA1K4vLTZz4YNMUpLCn259Sveaz5
+Package: enumerable-set
+  - 0.1.0 @ ipfs://QmfWjW8qo6weoQzzKBXNCAgCqYB9J8co97qMPGFCBZhNL6
+Package: math
+  - 0.1.0 @ ipfs://QmQtuNsSbSjnnizxwpx8FuGRfi2Mxbgam3chB2VeKXgV28
+Package: safe-math
+  - 0.1.0 @ ipfs://QmNcgfrYg6u9Xv84oFASSy7yfAf7igNhhewhohPBoY5iVx
+Package: unauthorized
+  - 0.1.0 @ ipfs://QmQPe1C3qSiEwuNEUHUZd6qMYBcNPNDR5bsWDgwWCFHuJr
+```
+
+# `truffle install`
+
+Installing a package will write contract assets and deployments to your project's `build/`, and source contracts to `_ethpm_packages/`. Just like `node_modules/`, you should not edit `_ethpm_packages/` folder directly.
+
+There are a couple different options to install a package...
+
+From the package's registry set in your `truffle-config.js`.
+
+```bash
+truffle install [email protected]
+```
+
+... or to install the latest version of the package.
+
+```bash
+truffle install erc20
+````
+
+Install a package directly with its `ethpm` URI.
+
+```bash
+truffle install ethpm://ethpm.eth:3/[email protected]
+```
+
+Install a package directly with its manifest uri (currently, only ipfs manifest uris are supported).
+
+```bash
+truffle install ipfs://QmYmstuuQmVVaWvde5VHzwxs5zDaJbjGk8nGHeTfZnEgoe
+```
+
+You can install any package under an alias wth the `--alias` flag, and then use the alias to reference the package. This is useful if you want to install two different packages with the same name.
+
+```bash
+truffle install erc20 --alias erc20-version-2
+```
+
+## interact with a deployment from an installed package
+- Run `truffle console` to launch a console connected to the chain defined in your `truffle-config.js`.
+- From the console, list all available deployments from the package with `networks` (only deployments found on the connected chain will be available to interact with from the console).
+- Then, interact with the contracts like any other truffle contract [link](https://www.trufflesuite.com/docs/truffle/getting-started/interacting-with-your-contracts).
+
+## deploy a contract from an installed package
+- Simply reference the target contract with a string in the form of `"package-name/Contract"`, and run your migration like any other contract
+
+```js
+const ERC20 = artifacts.require("erc20-example/ERC20");
+
+module.exports = function (deployer) {
+  deployer.deploy(ERC20, 'test token', 'TEST');
+};
+```
+
+## importing an installed contract into your contract
+- importing a top-level contract
+```js
+import "erc20-example/ERC20.sol"
+```
+- importing a nested contract
+```js
+import "erc20-example/GSN/Context.sol"
+```
+
+## linking to a library contract in a deployment
+Tired of redeploying your libraries over and over? You can find some instances of available libraries on `ethpm://libraries.ethpm.eth:3`. These have not been audited, and are not fit for use in production. 
+
+After installing the `ethpm://libraries.ethpm.eth:1/[email protected]` library, you can link your contracts to it like...
+
+```js
+const MyContract = artifacts.require("MyContract");
+const SafeMath = artifacts.require("safe-math/SafeMath");
+
+module.exports = function(deployer) {
+  deployer.link(SafeMath, MyContract);
+  deployer.deploy(MyContract)
+};
+```
+
+# `truffle publish`
+Publishing ethpm packages makes it easy to distribute your smart contracts and deployments for other developers to use. 
+
+## setting your `ethpm.json`
+Before you can publish a package, you must create an `ethpm.json` config file in the root-level of your truffle project. This file defines the `name`, `version`, and metadata for the published package. The only required fields are `"name"` and `"version"`, but it is recommended to use all of the metadata to describe your package.
+
+```json
+{
+	"name": "my-package",
+	"version": "0.0.1",
+	"meta": {
+		"description": "My awesome project.",
+		"license": "MIT",
+		"links": {
+			"documentation": "www.readthedocs.com",
+			"repository": "www.github.com",
+			"website": "www.project.com"
+		}
+	},
+	"authors": [
+		"Me <[email protected]>",
+		"Someone else <[email protected]"
+	],
+	"keywords": [
+		"ethereum",
+		"ethpm",
+		"solidity",
+		"truffle"
+	]
+}
+```
+
+After setting your `ethpm.json`, just run `truffle publish` to generate and publish your package.
+
+```bash
+Finding publishable artifacts...
+Generating package manifest...
+Publishing package to registry...
+Published [email protected] to 0x586b308Cbef3....
+```
+
+Truffle will automatically package up all available smart contracts and deployments from your truffle project, and publish a package to the registry defined in your `truffle-confg.js`. The provider used to connect to the chain must be configured with a mnemonic to sign the transaction. The signing account must also be authorized to publish a release to the connected registry.
+
+To publish a package doesn't need an entire protocol of smart contracts. A single smart contract can be a useful package. A single deployment can be a useful package. ethpm will store whatever data you find useful in a verifiably safe manner, so you can access your smart contract assets with a single uri.
+
+## setting up your own ethpm registry
+To deploy your own, permissioned ethpm registry, you can use the `ethpm://registry.ethpm.eth:3/standard` package. This is the official ethpm registry package, hosted on a registry maintained by the ethpm team, you can verify the address here on the [github repo](https://github.com/ethpm/solidity-registry/).
+
+`truffle install ethpm://registry.ethpm.eth:3/[email protected]`
+
+Inside your `_ethpm_packages/` directory, you can inspect the source files for the registry contract (remember, don't edit anything inside the `_ethpm_packages/` directory).
+
+Update your migration file to deploy the registry.
+
+```javascript
+const PackageRegistry = artifacts.require("standard/PackageRegistry")
+module.exports = function(deployer) {
+  deployer.deploy(PackageRegistry);
+};
+```
+Now run `truffle migrate` and save the address of your newly deployed ethpm registry.
+
+Note that the address used to deploy this registry will be the only account authorized to release packages onto the registry. However, ownership is transferable. It is also recommended that you connect your registry address to an ENS domain for better usability.
+
+
+# need help?
+- Ask your questions on our [gitter channel](https://gitter.im/ethpm/Lobby?source=orgpage)
+- The [`ethpm-cli`](https://github.com/ethpm/ethpm-cli) is equipped with more useful commands to explore and interact with ethpm.
+- [Documentation](http://docs.ethpm.com/)