API Documentation

Core

• code-runner
• console
• core
• engine
• i18n
• logger
• reset
• utils

Stack

• api
• authenticator
• blockchain-client
• blockchain
• communication
• compiler
• contracts-manager
• deployment
• embarkjs
• library-manager
• namesystem
• pipeline
• process-logs-api-manager
• proxy
• storage
• test-runner
• watcher
• webserver

Plugins

• accounts-manager
• basic-pipeline
• coverage
• debugger
• deploy-tracker
• ens
• ethereum-blockchain-client
• ganache
• geth
• graph
• ipfs
• mocha-tests
• parity
• plugin-cmd
• profiler
• rpc-manager
• scaffolding
• scripts-runner
• snark
• solc
• solidity-tests
• solidity
• specialconfigs
• swarm
• transaction-logger
• transaction-tracker
• vyper
• web3
• whisper-geth
• whisper-parity

EmbarkJS

• embarkjs
• embarkjs-ens
• embarkjs-ipfs
• embarkjs-swarm
• embarkjs-web3
• embarkjs-whisper

Cockpit

• api-client
• ui

---

accounts-manager

module type: plugin

Description

• generates wallet from accounts configuration
• fund accounts according to the accounts configuration
• signs transactions for accounts present in its wallet
  • if it's a node account it just ignores it (since it will be processed at the node)
• overrides eth_getAccounts to return the correct list of accounts

actions used

• blockchain:proxy:request - to sign the transactions
• blockchain:proxy:response - to modify accounts list

proxy

module type: stack

requests

name: proxy:endpoint arguments: no arguments

returns the endpoint (string)

actions

name: blockchain:proxy:request params: {reqData: } description: actions run when a request is made to the blockchain node. In case the plugin hangs (5 seconds), the action continues.

name: blockchain:proxy:response params: {respData: , reqData: } description: actions run when a response is returned from the blockchain node. In case the plugin hangs (5 seconds), the action continues.

api-client

Requests

name: compiler:url description: Returns API URL. params:

• callback - (url) => {} - a callback function with access to the API url

---

name: logs:api:enable description: Enables api server log output params: -

---

name: logs:api:disable description: Disables api server log output params:

blockchain

module type: stack component

API

requests

name: blockchain:node:register arguments:

• clientName {string} - name of the client (e.g 'geth')
• startCb {function} - function that starts the node

registers a client and the function that starts it

name: blockchain:node:start arguments:

• blockchainConfig {object} - blockchain config (taken from dapp config/blockchain.js)
• doneCb {function} - function that is fired once the blockchain node has started

starts a blockchain name according to the config given. will start one of the nodes previously registered with blockchain:node:register

actions used

• pipeline:generateAll:before - to generate blockchain.json config artifact

*events emited

• blockchain:started - emitted when blockchain node starts

blockchain-client

module type: stack component

name: blockchain:client:register (not being used should be removed)

name: blockchain:client:provider arguments:

• clientName {string} - name of blockchain technology (e.g "ethereum")
• cb {function(err, provider)} - callback that returns the blockchain provider

Returns a provider object that allows libraries to connect to the embark's blockchain node

code-runner

module type: core component

API

requests

name: runcode:register arguments:

• varName {string} - name of the variable to be registered in the VM
• code {any} - primitive or object value that will be assign to varName inside the VM

Registers a variable and assigns a value to it inside the VM context.

name: 'runcode:whitelist' arguments:

• varName {string} - name of white node module to be whitelisted for imports inside the VM

Whitelists a node module inside the VM context for imports. Generally, the VM context is sandboxed, making it impossible to require/import any arbitrary module. This API enables whitelisting of such modules.

name : runcode:getContext

Returns the current VM context with its sandbox object and options.

name: runcode:eval arguments:

• code {string} - code to be eval'd inside the sandboxed VM
• cb {function} - callback to be called when the evaluation is done
• tolerateError {boolean}, default: false - If set to true, errors inside the VM are logged (instead of calling back with an error object)
• logCode {boolean}, default: true - log the code if it caused an error
• logError {boolean}, default: true - Also logs the error if there is one emitted by the VM

Runs given code inside a sandboxed VM.

communication

module type: stack component

API

requests

name: communication:node:register arguments:

• clientName {string} - name of the client (e.g 'ipfs')
• startCb {function} - function that starts the node

registers a node and the function that starts it

name: communication:node:start arguments:

• communicationConfig {object} - communication config (taken from dapp config/communication.js)
• doneCb {function} - function that is fired once the blockchain node has started

starts a communication node according to the config given. will start one of the nodes previously registered with communication:node:register

actions used

• pipeline:generateAll:before - to generate communication.json config artifact

*events emited

• communication:started - emitted when communication node starts

console

module type: core component

Description

Component that enables interactive console capabilities in the Embark command line interface as well as graphical user interfaces such as Cockpit.

API

requests

name: console:register:helpCmd arguments:

• cmdOptions {object} - Configuration object for help command to be registered
  • helpCmd {string} - Command to be executed as help command
  • cmdName {string} - Name of help command
• cb {function} - Callback to be called when help command registration is done

Registers a help command with the console.

name console:unregister:helpCmd arguments:

• cmdName {string} - Name of help command

Deregisters help command from the console.

name: console:executeCmd arguments:

• cmd {string} - Command to be executed
• cb {function} - Callback to be called when command finished execution

Executes a given command in Embark virtual machine.

name: console:history arguments:

• historySize {string} - Number of commands to be returned by history
• cb {function} - Callback to be executed once history has been returned

Returns last #n commands of the history, where #n is a number that specifies the amount of commands.e

name: console:executePartial arguments:

• cmd {string} - Command to be executed
• cb {function} - Callback to be called when done

Events used

• runcode:eval - To eval/execute commands inside console:runCmd

whisper

module type: plugin

Description

• whitelists embarkjs & embarkjs-whisper packages in the vm
• generates whisper artifacts
• makes whisper work in the console
• registers api endpoints

actions used

• pipeline:generateAll:after - to register whisper artifact

events used

• blockchain:started - to connect embarkjs whisper to node in the console

compiler

module type: ???

API

Requests

name: compiler:contracts:compile description: Compiles Smart Contracts given a list of Smart Contract files and returns the compilation data. params:

• { contractsFiles: any[], cb: function }module type: ???

API

Requests

name: compiler:contracts:compile description: Compiles Smart Contracts given a list of Smart Contract files and returns the compilation data. params:

• { contractsFiles: any[], cb: function }

test-runner

module type: stack component

API

requests

name: tests:run arguments:

• options - {object}
• doneCb - {function} called when tests are done

run tests with given options

name: tests:runner:register arguments:

• name - {string} pluginName
• matchFn - {function(filepath)} function that returns boolean true if file being matched can be run by the plugin
• addFn - {function(filepath)} function that adds the file to the plugin runlist, throws exception if file doesn't match supported by plugin (should run matchFn first)
• runFn - {function(options, reporter)} function that runs the plugin

registers a test runner plugin

solidity-tests

module type: plugin component

Description

• runs test suites written in solidity using remix-tests
  • ensures existence of the Assert (remix_tests.sol) library
  • ensures test files include the Assert (remix_tests.sol) import statement and injects that statement to files that don't have it
  • compiles & deploys contracts that have been added to this test runner, and then runs tests

mocha-tests

module type: plugin component

description

• runs test suites written in javascript using mocha
  • defines config function that gets exported and exposed in the mocha tests
  • builds, compiles & deploys contracts with the config given
  • instantiates contracts in vanilla web3
  • overrides require to return specified contracts

deployment

module type: stack component

API

requests

name: deployment:contracts:deploy arguments:

• contractsList - Array - array of Contract objects
• contractDependencies - <object(string:[string])> of dependencies key=contractName, value=`

deploys a list of contracts in the order of their dependencies

name: deployment:contract:deploy arguments:

• contract - Contract

deploy contract

name: deployment:deployer:register arguments:

• blockchainType - name of the blockchain tech (e.g "ethereum")
• deployerCb - (contract, doneCb(err)) function that deploys specified contract then on finish calls doneCb

register a deployer for blockchainType for example register an ethereum contract deployer

actions

name: deployment:deployContracts:beforeAll description: actions to run before deploying contracts

name: deployment:deployContracts:afterAll description: actions to run after contracts are deployed

name: deployment:contract:beforeDeploy params: {contract: } description: actions to run before deploying a contract

name: deployment:contract:deployed params: {contract: } description: actions to run after a contract has been deployed

name: deployment:contract:shouldDeploy params: {contract: , shouldDeploy: boolean} description: actions to run before deploying a contract, can change the shouldDeploy flag

embark-embarkjs

type: stack component

requests

request: embarkjs:plugin:register params:

• stackName - e.g "blockchain", "messages", "storage"
• pluginName - e.g "web3", "whisper"
• packageName - e.g "embarkjs-whisper"
• moduleObj - e.g require('embarkjs-whisper')

registers an embarkjs plugin

request: embarkjs:console:register params:

• stackName - e.g "blockchain", "messages", "storage"
• pluginName - e.g "web3", "whisper"
• packageName - e.g "embarkjs-whisper"

request to register embarkjs plugin the embarkjs instance running on the console/vm.

request: embarkjs:console:setProvider params:

• stackName - e.g "blockchain", "messages", "storage"
• pluginName - e.g "web3", "whisper"
• config - config object necessary for the connection

request to connect a provider for the embarkjs instance running on the console/vm

request: embarkjs:contract:generate params:

• contract - contract object
• doneCb - called when done

request to add contract artifact using embarkjs to the pipeline

request: embarkjs:contract:runInVm params:

• contract - contract object
• doneCb - called when done

requests to run contract using embarkjs in the console/vm

actions used

• pipeline:generateAll:before - to generate embarkjs artifact according to registered plugins

namesystem

module type: stack component

API

requests

name: namesystem:node:register arguments:

• clientName - {string} - name of node that starts ENS
• startCb - {function} function to start the node

registers a node and the function that starts it

name: namesystem:node:start arguments:

• namesystemConfig {object} - namesystem config (taken from dapp config/namesystem.js)
• doneCb {function} - function that is fired once the namesystem node has started

starts a namesystem node according to the config given. will start one of the nodes previously registered with namesystem:node:register

actions used

pipeline:generateAll:before - to generate the namesystem.json artifact

ens

module type: plugin component

Description

• deploys & configures the ENS contracts, or uses existing one if connected to a supported chain
• registers any domains or subdomains as configured in the namesystem config
• registers the embarkjs-ens plugin & configures it
• registers console commands to interact with ENS
• registers api endpoints
• whitelists eth-ens-namehash package in the vm

actions used

• deployment:deployContracts:beforeAll - to deploy & configure ENS contracts
• deployment:deployContracts:afterAll - to associate contract addresses to ens domain
• deployment:contract:beforeDeploy - to replace contract arguments if they have ens domains with the associated adddress

scripts-runner

Plugins to execute (migration) scripts inside Embark projects.

Requests

name: scripts-runner:execute description: Takes a path to a file or directory and tries to run the script(s) that the path is pointing to. If a path to a directory is given, all files inside of that directory are considered script files. params:

• target: string - Path to script file or directory containing scripts.
• forceTacking: boolean - Flag to enforce tracking of scripts to be executed. By default, scripts-runner only track scripts that live inside a configured migrations directory.

graph

module type: plugin

Requests

name: graph:create description: Creates a diagram of Smart Contracts architecture. params:

• options - Object - Options to configure graph task
  • skipFunctions - Skip functions in graph generation
  • skipEvents - Skip events in graph generation
  • skipUndeployed - Skip undeployed contracts
  • output - The path to write the diagram to

library-manager

module type: stack

Endpoints

endpoint: /embark-api/versions type: GET params: - response: Array<{value: string, name: string}> - List of available versions for packages.

Requests

name: versions:get:[NAME] description: Returns version of a given package, given NAME. params:

• name - String - Library name (e.g. ipfs, solc etc)

---

name: version:getPackageLocation description: Returns package location, given a name and version number. params:

• name - String - Library name (e.g. ipfs, solc etc)
• version - String - version of library

---

name: version:downloadIfNeeded description: Downloads a library, given its name. params:

• name - String - Library name (e.g. ipfs, solc etc)

---

name: version:getPackagePath description: Returns a path to a package given its name and version params:

• name - String - Library name (e.g. ipfs, solc etc)
• version - String - Library version

embark-pipeline

module type: stack component

API

requests

name: pipeline:generateAll arguments:

• cb {function} - function called once all the files have been generated by the pipeline description: Generates all files registered in the pipeline

name: pipeline:register arguments:

• params {object} - Params used for generating a file with the pipeline. Interface for params:

{
  path {string} - output directory,
  file: {string} - output filename,
  format {string} - output file format (extension),
  content {string} - output file contents
}

• doneCb {function} - function that is fired once the blockchain node has started description: Registers a file to be generated by the pipeline when pipeline:generateAll is called. If a path+file has already been registered before, it will override it.

actions run

• pipeline:generateAll:before - Runs registered actions before the pipeline files are generated. Registering an event for this action is useful for timing when to register a pipeline file.

• pipeline:generateAll:after - Runs registered actions after the pipeline files are generated. Registering an event for this action is useful for timing automated front-end build tools, such as Embark's built-in webpack pipeline.

Endpoints

GET /embark-api/file

• endpoint: /embark-api/file
• type: GET
• description: Retrieves a file for the given path. Ensures that the file exists in the dapp directory.
• params:
  • path {string} - path of the file of the file to retrieve
• response: object - Resulting retrieved file.
  • name {string} - file name
  • content {string} - file content
  • path {string} - file path (equivalent to path parameter)

POST /embark-api/folders

• endpoint: /embark-api/folders
• type: POST
• description: Creates a directory for the given path. Ensures that the directory is in the dapp path.
• params:
  • path {string} - path of the directory to create
• response: object - Resulting retrieved file.
  • name {string} - created directory name
  • path {string} - created directory path (equivalent to path parameter)

POST /embark-api/files

• endpoint: /embark-api/files
• type: POST
• description: Creates a file in the given path. Ensures that the path is in the dapp path.
• params:
  • path {string} - path of the file to create
  • content {string} - content of the file to create
• response: object - Resulting retrieved file.
  • name {string} - created file name
  • path {string} - created file path (equivalent to path parameter)
  • content {string} - created file content (equivalent to content parameter)

DELETE /embark-api/file

• endpoint: /embark-api/file
• type: DELETE
• description: Deletes a file in the given path. Ensures that the path is in the dapp path.
• params:
  • path {string} - path of the file to create
• response: void

GET /embark-api/files

• endpoint: /embark-api/files
• type: GET
• description: Gets an array of all files and directories in the dapp. Directories contain a children property, showing all child files - and directories.
• params: none
• response: Array<File> - An array of files in the dapp.
  • isRoot {boolean} - true if the file or directory exists in the root of the dapp.
  • name {string} - Name of the file or directory.
  • dirname {string} - path of the parent directory.
  • path {string} - Path of the file or directory.
  • ishidden {boolean} - indicates if the file is meant to be hidden in file trees. true if the name begins with "." or the name is "node_modules"
  • children {Array} - An array of files or directories that exist in the current directory. This property only exists for directories.

basic-pipeline

module type: plugin

Description

• runs webpack after pipeline generates files that were registered

actions used

• pipeline:generateAll:after - to run webpack after pipeline has generated files

events used

• config:load:pipeline - to get new pipeline config when it changes

embark-communication

module type: stack component

API

requests

name: communication:node:register arguments:

• clientName {string} - name of the client (e.g 'ipfs')
• startCb {function} - function that starts the node

registers a node and the function that starts it

name: communication:node:start arguments:

• communicationConfig {object} - communication config (taken from dapp config/communication.js)
• doneCb {function} - function that is fired once the blockchain node has started

starts a communication node according to the config given. will start one of the nodes previously registered with communication:node:register

actions used

• pipeline:generateAll:before - to generate communication.json config artifact

*events emited

• communication:started - emitted when communication node starts

embark-whisper

module type: plugin

Description

• whitelists embarkjs & embarkjs-whisper packages in the vm
• generates whisper artifacts
• makes whisper work in the console
• registers api endpoints

actions used

• pipeline:generateAll:after - to register whisper artifact

events used

• blockchain:started - to connect embarkjs whisper to node in the console