alexxnica / embark-framework

Framework for serverless Decentralized Applications using Ethereum, IPFS and other platforms

What is Embark

Embark is a framework that allows you to easily develop and deploy Decentralized Applications (DApps).

A Decentralized Application is a serverless html5 application that uses one or more decentralized technologies.

Embark currently integrates with EVM blockchains (Ethereum), Decentralized Storages (IPFS), and Decentralized communication platforms (Whisper and Orbit). Swarm is supported for deployment.

With Embark you can:

Blockchain (Ethereum)

• 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.
• Contracts are available in JS with Promises.
• Do Test Driven Development with Contracts using Javascript.
• Keep track of deployed contracts; deploy only when truly needed.
• Manage different chains (e.g testnet, private net, livenet)
• Easily manage complex systems of interdependent contracts.

Decentralized Storage (IPFS)

• Easily Store & Retrieve Data on the DApp through EmbarkJS. Including uploading and retrieving files.
• Deploy the full application to IPFS or Swarm.

Decentralized Communication (Whisper, Orbit)

• Easily send/receive messages through channels in P2P through Whisper or Orbit.

Web Technologies

• Integrate with any web technology including React, Foundation, etc..
• Use any build pipeline or tool you wish, including grunt, gulp and webpack.

Table of Contents

• Installation
• Usage Demo
• Dashboard
• Creating a new DApp
• Libraries and APIs available
• Using and Configuring Contracts
• EmbarkJS
• EmbarkJS - Storage (IPFS)
• EmbarkJS - Communication (Whisper/Orbit)
• Testing Contracts
• Working with different chains
• Custom Application Structure
• Deploying to IPFS
• Extending Functionality with Plugins
• Donations

Installation

Requirements: geth (1.6.7 or higher recommended), node (6.9.1 or higher is recommended) and npm Optional: testrpc (3.0 or higher) if using the simulator Further: depending on the dapp stack you choose: IPFS

$ npm -g install embark

# If you plan to use the simulator instead of a real ethereum node.
$ npm -g install ethereumjs-testrpc

See Complete Installation Instructions.

updating from Embark 1

Embark's npm package has changed from embark-framework to embark, this sometimes can create conflicts. To update first uninstall embark-framework 1 to avoid any conflicts. npm uninstall -g embark-framework then npm install -g embark

Usage - Demo

You can easily create a sample working DApp with the following:

$ embark demo
$ cd embark_demo

You can run a REAL ethereum node for development purposes:

$ embark blockchain

Alternatively, to use an ethereum rpc simulator simply run:

$ embark simulator

By default Embark blockchain will mine a minimum amount of ether and will only mine when new transactions come in. This is quite useful to keep a low CPU. The option can be configured at config/blockchain.json. Note that running a real node requires at least 2GB of free ram, please take this into account if running it in a VM.

Then, in another command line:

$ 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.

Dashboard

Embark 2 comes with a terminal dashboard.

The dashboard will tell you the state of your contracts, the environment 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 a service 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.

Creating a new DApp

If you want to create a blank new app:

$ embark new AppName
$ cd AppName

DApp Structure

  app/
    |___ contracts/ #solidity or serpent contracts
    |___ html/
    |___ css/
    |___ js/
  config/
    |___ blockchain.json #rpc and blockchain configuration
    |___ contracts.json  #ethereum contracts configuration
    |___ storage.json  #ipfs configuration
    |___ communication.json  #whisper/orbit configuration
    |___ webserver.json  #dev webserver configuration
  test/
    |___ #contracts tests

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

Libraries and languages available

Embark can build and deploy contracts coded in Solidity. It will make them available on the client side using EmbarkJS and Web3.js.

Further documentation for these can be found below:

• Smart Contracts: Solidity and Serpent
• Client Side: Web3.js and EmbarkJS

Using Contracts

Embark will automatically take care of deployment for you and set all needed JS bindings. For example, the contract below:

# app/contracts/simple_storage.sol
pragma solidity ^0.4.17;
contract SimpleStorage {
  uint public storedData;

  function SimpleStorage(uint initialValue) public {
    storedData = initialValue;
  }

  function set(uint x) public {
    storedData = x;
  }
  function get() view returns (uint retVal) {
    return storedData;
  }
}

Will automatically be available in Javascript as:

# app/js/index.js
SimpleStorage.methods.set(100).send({from: web3.eth.defaultAccount});
SimpleStorage.methods.get().call().then(function(value) { console.log(value.toNumber()) });
SimpleStorage.methods.storedData().then(function(value) { console.log(value.toNumber()) });

You can specify for each contract and environment its gas costs and arguments:

# config/contracts.json
{
  "development": {
    "gas": "auto",
    "contracts": {
      "SimpleStorage": {
        "args": [
          100
        ],
        "gas": 800000
      }
    }
  }
}

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. You can also specify interfaces and choose to not deploy contracts (for e.g in case they are interfaces)

# config/contracts.json
{
  ...
  "development": {
    "contracts": {
      "SimpleStorage": {
        "args": [
          100,
          "$MyStorage"
        ]
      },
      "MyStorage": {
        "args": [
          "initial string"
        ]
      },
      "MyMainContract": {
        "args": [
          "$SimpleStorage"
        ]
      },
      "MyContractInterface": {
        "deploy": false
      }
    }
  }
  ...
}

You can now deploy many instances of the same contract. e.g

# config/contracts.json
{
  "development": {
    "contracts": {
      "Currency": {
        "deploy": false,
        "args": [
          100
        ]
      },
      "Usd": {
        "instanceOf": "Currency",
        "args": [
          200
        ]
      },
      "MyCoin": {
        "instanceOf": "Currency",
        "args": [
          200
        ]
      }
    }
  }
}
  ...

Contracts addresses can be defined. If an address is defined, Embark uses the defined address instead of deploying the contract.

# config/contracts.json
{
  ...
  "development": {
    "contracts": {
      "UserStorage": {
        "address": "0x123456"
      },
      "UserManagement": {
        "args": [
          "$UserStorage"
        ]
      }
    }
  }
  ...
}

You can Also specify which versions of solc and web3.js to use:

# config/contracts.json
{
  ...
  "development": {
    "versions": {
      "web3.js": "1.0.0-beta",
      "solc": "0.4.17"
    }
  }
  ...
}

You specify which node the contracts should be deploy to and the order of nodes the dapp should connect to. $WEB3 means the dapp will try to use an existing web3 object first if available.

# config/contracts.json
{
  ...
  "development": {
    "deployment": {
      "host": "localhost",
      "port": 8545,
      "type": "rpc"
    },
    "dappConnection": [
      "$WEB3",
      "http://localhost:8545"
    ]
  }
  ...
}

EmbarkJS

EmbarkJS is a javascript library meant to abstract and facilitate the development of DApps.

promises

  var myContract = new EmbarkJS.Contract({abi: abiObject, address: "0x123"});
  myContract.methods.get().call().then(function(value) { console.log("value is " + value.toNumber) });

events:

  myContract.events.eventName({from: web3.eth.accounts}, 'latest').then(function(event) { console.log(event) });

deployment

Client side deployment will be automatically available in Embark for existing contracts:

  SimpleStorage.deploy([args], {options}).then(function(anotherSimpleStorage) {});

or it can be manually definied as

  var myContract = new EmbarkJS.Contract({abi: abiObject, code: code});
  myContract.deploy([args], {options}).then(function(anotherMyContractObject) {});

so you can define your gas as

  myContract.deploy([100, "seconde argument"], {gas: 800000}).then(function(anotherMyContractObject) {});

EmbarkJS - Storage

initialization

The current available storage is IPFS. It can be initialized as

  EmbarkJS.Storage.setProvider('ipfs',{server: 'localhost', port: '5001'})

Saving Text

  EmbarkJS.Storage.saveText("hello world").then(function(hash) {});

Retrieving Data/Text

  EmbarkJS.Storage.get(hash).then(function(content) {});

Uploading a file

  <input type="file">

  var input = $("input[type=file"]);
  EmbarkJS.Storage.uploadFile(input).then(function(hash) {});

Generate URL to file

  EmbarkJS.Storage.getUrl(hash);

note: if not using localhost, the cors needs to be set as ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["your-host-name-port"]

EmbarkJS - Communication

initialization

For Whisper (note: currently requires geth 1.6.0 or higher):

    EmbarkJS.Messages.setProvider('whisper')

For Orbit:

You'll need to use IPFS from master and run it as: ipfs daemon --enable-pubsub-experiment

then set the provider:

  EmbarkJS.Messages.setProvider('orbit', {server: 'localhost', port: 5001})

listening to messages

  EmbarkJS.Messages.listenTo({topic: ["topic1", "topic2"]}).then(function(message) { console.log("received: " + message); })

sending messages

you can send plain text

  EmbarkJS.Messages.sendMessage({topic: "sometopic", data: 'hello world'})

or an object

  EmbarkJS.Messages.sendMessage({topic: "sometopic", data: {msg: 'hello world'}})

note: array of topics are considered an AND. In Whisper you can use another array for OR combinations of several topics e.g ["topic1", ["topic2", "topic3"]] => topic1 AND (topic2 OR topic 3)

Tests

You can run specs with embark test, it will run any test files under test/.

Embark includes a testing lib to rapidly run & test your contracts in a EVM.

# test/simple_storage_spec.js
describe("SimpleStorage", function() {
  before(function(done) {
    this.timeout(0);
    var contractsConfig = {
      "SimpleStorage": {
        args: [100]
      }
    };
    EmbarkSpec.deployAll(contractsConfig, done);
  });

  it("should set constructor value", function(done) {
    SimpleStorage.storedData(function(err, result) {
      assert.equal(result.toNumber(), 100);
      done();
    });
  });

  it("set storage value", function(done) {
    SimpleStorage.set(150, function() {
      SimpleStorage.get(function(err, result) {
        assert.equal(result.toNumber(), 150);
        done();
      });
    });
  });

});

Embark uses Mocha by default, but you can use any testing framework you want.

Working with different chains

You can specify which environment to deploy to:

$ embark blockchain livenet

$ embark run livenet

The environment is a specific blockchain configuration that can be managed at config/blockchain.json

# config/blockchain.json
  ...
   "livenet": {
    "networkType": "livenet",
    "rpcHost": "localhost",
    "rpcPort": 8545,
    "rpcCorsDomain": "http://localhost:8000",
    "account": {
      "password": "config/livenet/password"
    }
  },
  ...

Structuring Application

Embark is quite flexible and you can configure your own directory structure using embark.json

# embark.json
{
  "contracts": ["app/contracts/**"],
  "app": {
    "css/app.css": ["app/css/**"],
    "images/": ["app/images/**"],
    "js/app.js": ["embark.js", "app/js/**"],
    "index.html": "app/index.html"
  },
  "buildDir": "dist/",
  "config": "config/",
  "plugins": {}
}

Deploying to IPFS and Swarm

To deploy a dapp to IPFS, all you need to do is run a local IPFS node and then run embark upload ipfs. If you want to deploy to the livenet then after configuring you account on config/blockchain.json on the livenet environment then you can deploy to that chain by specifying the environment embark ipfs livenet.

To deploy a dapp to SWARM, all you need to do is run a local SWARM node and then run embark upload swarm.

Plugins

It's possible to extend Embark's functionality with plugins. For example, the following is possible:

• plugin to add support for es6, jsx, coffescript, etc (embark.registerPipeline)
• plugin to add standard contracts or a contract framework (embark.registerContractConfiguration and embark.addContractFile)
• plugin to make some contracts available in all environments for use by other contracts or the dapp itself e.g a Token, a DAO, ENS, etc.. (embark.registerContractConfiguration and embark.addContractFile)
• plugin to add a libraries such as react or bootstrap (embark.addFileToPipeline)
• plugin to specify a particular web3 initialization for special provider uses (embark.registerClientWeb3Provider)
• plugin to create a different contract wrapper (embark.registerContractsGeneration)
• plugin to add new console commands (embark.registerConsoleCommand)
• plugin to add support for another contract language such as viper, LLL, etc (embark.registerCompiler)

For more information on how to develop your own plugin, please see the plugin documentation

Donations

If you like Embark, please consider donating to 0xFA239D14c7117C3D2370B2a4c4238534391fadd9