embark-area-51/README.md

464 lines
11 KiB
Markdown
Raw Normal View History

2016-09-23 05:03:20 +00:00
2015-05-25 12:21:53 +00:00
What is embark
======
2015-05-26 14:35:07 +00:00
[![Join the chat at https://gitter.im/iurimatias/embark-framework](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/iurimatias/embark-framework?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
2015-06-22 02:14:22 +00:00
2016-10-16 19:14:48 +00:00
Embark is a framework that allows you to easily develop and deploy DApps.
2015-06-22 02:14:22 +00:00
With Embark you can:
* Automatically deploy contracts and make them available in your JS code. Embark watches for changes, and if you update a contract, Embark will automatically redeploy the contracts (if needed) and the dapp.
2016-10-16 19:14:48 +00:00
* Use any build pipeline or tool you wish, including grunt and meteor. (for 1.x, plugins coming soon for 2.x series)
2015-06-22 02:14:22 +00:00
* Do Test Driven Development with Contracts using Javascript.
* Easily deploy to & use decentralized systems such as IPFS.
2015-08-31 12:33:15 +00:00
* Keep track of deployed contracts, deploy only when truly needed.
2015-10-12 22:33:00 +00:00
* Manage different chains (e.g testnet, private net, livenet)
2016-10-16 19:14:48 +00:00
* Quickly create advanced DApps using multiple contracts that can interact with decentralized infrastructure for storage and comunication.
2015-06-22 10:07:46 +00:00
2016-10-18 09:37:40 +00:00
Table of Contents
======
2016-10-18 09:40:47 +00:00
* [Installation](#installation)
* [Usage Demo](#usage---demo)
* [Dashboard](#dashboard)
* [Creating a new DApp](#creating-a-new-dapp)
* [Using and Configuring Contracts](#dapp-structure)
* [EmbarkJS](#embarkjs)
* [EmbarkJS - Storage (IPFS)](#embarkjs---storage)
* [EmbarkJS - Communication (Whisper)](#embarkjs---communication)
2016-10-18 09:43:01 +00:00
* [Testing Contracts](#tests)
* [Working with different chains](#working-with-different-chains)
* [Custom Application Structure](#structuring-application)
* [Deploying to IPFS](#deploying-to-ipfs)
* [LiveReload Plugin](#livereload-plugin)
* [Donations](#donations)
2016-10-18 09:37:40 +00:00
2015-05-25 12:21:53 +00:00
Installation
======
2016-06-01 02:13:36 +00:00
Requirements: geth (1.4.4 or higher), node (5.0.0) and npm
2016-10-18 09:29:05 +00:00
Optional: serpent (develop) if using contracts with Serpent, testrpc or ethersim if using the simulator or the test functionality.
Further: depending on the dapp stack you choose: [IPFS](https://ipfs.io/)
2015-05-25 12:21:53 +00:00
```Bash
2016-10-16 19:14:48 +00:00
$ npm -g install embark
2016-09-23 22:56:19 +00:00
# If you plan to use the simulator instead of a real ethereum node.
2016-10-16 19:14:48 +00:00
$ npm -g install testrpc
2015-05-25 12:21:53 +00:00
```
2015-06-22 10:07:46 +00:00
See [Complete Installation Instructions](https://github.com/iurimatias/embark-framework/wiki/Installation).
2015-05-25 12:21:53 +00:00
Usage - Demo
======
You can easily create a sample working DApp with the following:
```Bash
$ embark demo
$ cd embark_demo
```
2015-10-12 22:33:00 +00:00
To run a ethereum rpc simulator simply run:
```Bash
$ embark simulator
```
Or Alternatively, you can run a REAL ethereum node for development purposes:
2015-05-25 12:21:53 +00:00
```Bash
$ embark blockchain
```
2015-10-12 22:33:00 +00:00
2016-10-18 00:04:52 +00:00
By default embark blockchain will mine a minimum amount of ether and will only mine when new transactions come in. This is quite usefull to keep a low CPU. The option can be configured at config/blockchain.json
2015-05-25 12:21:53 +00:00
Then, in another command line:
```Bash
$ embark run
```
This will automatically deploy the contracts, update their JS bindings and deploy your DApp to a local server at http://localhost:8000
Note that if you update your code it will automatically be re-deployed, contracts included. There is no need to restart embark, refreshing the page on the browser will do.
2016-10-18 09:36:38 +00:00
Dashboard
=====
Embark 2 comes with a terminal dashboard.
![Dashboard](http://i.imgur.com/s4OQZpu.jpg)
The dashboard will tell you the state of your contracts, the enviroment you are using, and what embark is doing at the moment.
**available services**
Available Services will display the services available to your dapp in green, if one of these is down then it will be displayed in red.
**logs and console**
There is a console at the bottom which can be used to interact with contracts or with embark itself. type ```help``` to see a list of available commands, more commands will be added with each version of Embark.
2015-05-25 12:21:53 +00:00
Creating a new DApp
======
2016-10-18 09:36:38 +00:00
If you want to create a blank new app.
2015-05-25 12:21:53 +00:00
```Bash
$ embark new AppName
$ cd AppName
```
DApp Structure
======
```Bash
app/
2015-08-31 12:33:15 +00:00
|___ contracts/ #solidity or serpent contracts
2015-06-22 02:14:22 +00:00
|___ html/
|___ css/
|___ js/
2015-05-25 12:21:53 +00:00
config/
2016-10-16 19:25:40 +00:00
|___ blockchain.json #environments configuration
|___ contracts.json #contracts configuration
test/
|___ #contracts tests
2015-06-22 02:14:22 +00:00
```
2015-05-25 12:21:53 +00:00
2015-08-31 12:33:15 +00:00
Solidity/Serpent files in the contracts directory will automatically be deployed with embark run. Changes in any files will automatically be reflected in app, changes to contracts will result in a redeployment and update of their JS Bindings
2015-05-25 12:21:53 +00:00
Using Contracts
======
Embark will automatically take care of deployment for you and set all needed JS bindings. For example, the contract below:
```Javascript
# app/contracts/simple_storage.sol
contract SimpleStorage {
2015-06-22 11:54:22 +00:00
uint public storedData;
function SimpleStorage(uint initialValue) {
storedData = initialValue;
}
2015-05-25 12:21:53 +00:00
function set(uint x) {
storedData = x;
}
function get() constant returns (uint retVal) {
return storedData;
}
}
```
Will automatically be available in Javascript as:
```Javascript
# app/js/index.js
SimpleStorage.set(100);
SimpleStorage.get();
2015-06-22 11:54:22 +00:00
SimpleStorage.storedData();
2015-05-25 12:21:53 +00:00
```
2015-06-22 02:14:22 +00:00
You can specify for each contract and environment its gas costs and arguments:
2016-10-16 19:25:40 +00:00
```Json
# config/contracts.json
{
"development": {
"gas": "auto",
"contracts": {
"SimpleStorage": {
"args": [
100
]
}
}
}
}
2015-06-22 02:14:22 +00:00
```
If you are using multiple contracts, you can pass a reference to another contract as ```$ContractName```, Embark will automatically replace this with the correct address for the contract.
2016-10-18 00:02:33 +00:00
```Json
2016-10-16 20:16:09 +00:00
# config/contracts.json
{
2015-06-22 02:14:22 +00:00
...
2016-10-16 20:16:09 +00:00
"development": {
"contracts": {
"SimpleStorage": {
"args": [
100,
$MyStorage
]
},
"MyStorage": {
"args": [
"initial string"
]
},
"MyMainContract": {
"args": [
$SimpleStorage
]
}
}
}
...
}
2015-06-22 02:14:22 +00:00
```
2015-07-15 12:06:40 +00:00
You can now deploy many instances of the same contract. e.g
2016-10-17 23:58:52 +00:00
```Json
# config/contracts.json
{
"development": {
"contracts": {
"Currency": {
"deploy": false,
"args": [
100
]
},
"Usd": {
"instanceOf": "Currency",
"args": [
200
]
},
"MyCoin": {
"instanceOf": "Currency",
"args": [
200
]
}
}
}
}
2015-07-15 12:06:40 +00:00
...
```
Contracts addresses can be defined, If an address is defined the contract wouldn't be deployed but its defined address will be used instead.
2016-10-18 00:02:33 +00:00
```Json
# config/contracts.json
{
2015-07-15 12:06:40 +00:00
...
2016-10-18 00:02:33 +00:00
"development": {
"contracts": {
"UserStorage": {
"address": "0x123456"
},
"UserManagement": {
"args": [
2016-10-18 09:13:54 +00:00
"$UserStorage"
2016-10-18 00:02:33 +00:00
]
}
}
}
2015-08-31 12:33:15 +00:00
...
2016-10-18 00:02:33 +00:00
}
2015-08-31 12:33:15 +00:00
```
2016-10-16 19:50:38 +00:00
EmbarkJS
======
2016-10-18 00:09:27 +00:00
EmbarkJS is a javascript library meant to abstract and facilitate the development of DApps.
2016-10-18 09:27:38 +00:00
**promises**
2016-10-18 09:13:54 +00:00
2016-10-18 09:27:38 +00:00
methods in EmbarkJS contracts will be converted to promises.
2016-10-18 09:13:54 +00:00
2016-10-18 00:09:27 +00:00
```Javascript
var myContract = new EmbarkJS.Contract({abi: abiObject, address: "0x123"});
myContract.get().then(function(value) { console.log("value is " + value.toNumber) });
```
2016-10-18 09:27:38 +00:00
**deployment**
Client side deployment will be automatically available in Embark for existing contracts:
```Javascript
var myContract = new EmbarkJS.Contract({abi: abiObject, code: code});
myContract.deploy().then(function(address) {});
```
or it can be manually definied as
```Javascript
var myContract = new EmbarkJS.Contract({abi: abiObject, code: code});
myContract.deploy().then(function(address) {});
```
2016-10-16 19:50:38 +00:00
EmbarkJS - Storage
======
2016-10-18 09:27:38 +00:00
**initialization**
The current available storage is IPFS. it can be initialized as
```Javascript
EmbarkJS.Storage.setProvider('ipfs',{server: 'localhost', port: '5001'})
```
**Saving Text**
```Javascript
EmbarkJS.Storage.saveText("hello world").then(function(hash) {});
```
**Retrieving Data/Text**
```Javascript
EmbarkJS.Storage.get(hash).then(function(content) {});
```
**Uploading a file**
```HTML
<input type="file">
```
```Javascript
var input = $("input[type=file"]);
EmbarkJS.Storage.uploadFile(input).then(function(hash) {});
```
**Generate URL to file**
```Javascript
EmbarkJS.Storage.getUrl(hash);
```
2016-10-16 19:50:38 +00:00
EmbarkJS - Communication
======
2016-10-18 09:27:38 +00:00
**initialization**
The current available communication is Whisper.
**listening to messages**
```Javascript
EmbarkJS.Messages.listenTo({topic: ["achannel", "anotherchannel"]}).then(function(message) { console.log("received: " + message); })
```
**sending messages**
you can send plain text
```Javascript
EmbarkJS.Messages.sendMessage({topic: "achannel", data: 'hello world'})
```
or an object
```Javascript
EmbarkJS.Messages.sendMessage({topic: "achannel", data: {msg: 'hello world'}})
```
2015-06-22 02:14:22 +00:00
Tests
======
2016-10-16 19:25:40 +00:00
You can run specs with ```embark test```, it will run any test files under ```test/```.
2015-06-22 02:14:22 +00:00
Embark includes a testing lib to fastly run & test your contracts in a EVM.
2015-06-22 02:14:22 +00:00
```Javascript
2015-10-12 22:33:00 +00:00
# test/simple_storage_spec.js
2016-10-16 19:25:40 +00:00
2015-10-12 22:33:00 +00:00
var assert = require('assert');
var Embark = require('embark-framework');
var EmbarkSpec = Embark.initTests();
2016-10-16 19:25:40 +00:00
var web3 = EmbarkSpec.web3;
2015-10-12 22:33:00 +00:00
2016-10-16 19:25:40 +00:00
describe("SimpleStorage", function() {
2015-10-12 22:33:00 +00:00
before(function(done) {
2016-10-16 19:25:40 +00:00
var contractsConfig = {
"SimpleStorage": {
args: [100]
}
};
EmbarkSpec.deployAll(contractsConfig, done);
2015-06-22 02:14:22 +00:00
});
2015-10-12 22:33:00 +00:00
it("should set constructor value", function(done) {
SimpleStorage.storedData(function(err, result) {
assert.equal(result.toNumber(), 100);
done();
});
2015-06-22 02:14:22 +00:00
});
2015-10-12 22:33:00 +00:00
it("set storage value", function(done) {
SimpleStorage.set(150, function() {
SimpleStorage.get(function(err, result) {
assert.equal(result.toNumber(), 150);
done();
});
});
2015-06-22 02:14:22 +00:00
});
2016-10-16 19:25:40 +00:00
});
2015-06-22 02:14:22 +00:00
```
2015-10-12 22:33:00 +00:00
Embark uses [Mocha](http://mochajs.org/) by default, but you can use any testing framework you want.
2015-06-22 02:14:22 +00:00
2015-05-25 12:21:53 +00:00
Working with different chains
======
2015-06-22 10:13:04 +00:00
You can specify which environment to deploy to:
2015-05-25 12:21:53 +00:00
2015-06-22 10:13:04 +00:00
2016-10-18 00:04:52 +00:00
```$ embark blockchain production```
2015-06-22 10:13:04 +00:00
2016-10-18 00:04:52 +00:00
```$ embark run production```
2015-06-22 10:13:04 +00:00
2016-10-18 00:04:52 +00:00
The environment is a specific blockchain configuration that can be managed at config/blockchain.json
2015-05-25 12:21:53 +00:00
2016-10-18 00:04:52 +00:00
```Json
# config/blockchain.json
...
"livenet": {
"networkType": "livenet",
"rpcHost": "localhost",
"rpcPort": 8545,
"rpcCorsDomain": "http://localhost:8000",
"account": {
"password": "config/production/password"
}
},
2015-05-25 12:21:53 +00:00
...
```
Structuring Application
======
2016-10-18 00:04:52 +00:00
Embark is quite flexible and you can configure you're own directory structure using ```embark.json```
2016-10-18 00:04:52 +00:00
```Json
# embark.json
{
"contracts": ["app/contracts/**"],
"app": {
"css/app.css": ["app/css/**"],
"js/app.js": ["embark.js", "app/js/**"],
"index.html": "app/index.html"
},
"buildDir": "dist/",
"config": "config/"
}
```
2015-09-01 02:06:30 +00:00
Deploying to IPFS
======
To deploy a dapp to IPFS, all you need to do is run a local IPFS node and then run ```embark ipfs```.
2016-10-16 19:14:48 +00:00
If you want to deploy to the livenet then after configuring you account on ```config/blockchain.json``` on the ```production``` environment then you can deploy to that chain by specifying the environment ```embark ipfs production```.
2015-09-01 02:06:30 +00:00
2015-05-25 12:21:53 +00:00
LiveReload Plugin
======
Embark works quite well with the LiveReload Plugin
2016-10-18 09:36:38 +00:00
Donations
======
If you like Embark please consider donating to 0x8811FdF0F988f0CD1B7E9DE252ABfA5b18c1cDb1