Skip to content

API Documentation

Jump to bottom Edit New page
Pascal Precht edited this page Feb 20, 2020 · 19 revisions

Core

Stack

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

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:

namesystem

module type: stack component

API

requests

name: namesystem:node:register arguments:

  • name - string - Provider name for node to be registered
  • startFunction - function - Function to boot up node to be registered
  • executeCommand - function - Generic function to delegate commands such as resolve, lookup etc

Registers a node with the Embark namesystem

name: namesystem:node:start arguments:

  • namesystemConfig - NamesystemConfig - Namesystem configuration object
  • callback - function - A callback function to be called once the node is started

Starts a namesystem node.

name: namesystem:resolve arguments:

  • name - string - Name to be resolved.

Resolves a name based on the nodes registrar.

name: namesystem:lookup arguments:

  • address - string - Address to be looked p

Looks up and address based on the nodes registrar

name: namesystem:registerSubdomain arguments:

  • name - string - Subdomain name
  • address - string - Subdomain address to map to

Registers a subdomain with the nodes registrar using name and address.

name: module:namesystem:reset

Resets the nodes registrar

blockchain

module type: stack component

API

requests
blockchain:node:register
  • name: blockchain:node:register
  • description: Registers a blockchain client
  • arguments:
    • clientName {string} - name of the client (e.g 'geth')
    • clientFunctions {object} - object containing functions that interact with the blockchain node being registered. Object properties (all required):
      • isStartedFn {function} - function that determines if the node is already started
      • launchFn {function} - function that starts the blockchain
      • stopFn {function} - function that stops the blockchain
      • provider {function} - function that returns a provider for the blockchain. Defaults to a Web3 provider connecting to the endpoint specified in the blockchain config.
    • cb {function} - callback function called after registration is completed.
blockchain:node:start
  • name: blockchain:node:start
  • description: Starts a blockchain name according to the config given. Will start one of the nodes previously registered with blockchain:node:register. If the registered isStartedFn returns true, the node is already running and not attempted to be started again. If isStartedFn returns false, launchFn is called.
  • arguments:
    • blockchainConfig {object} - blockchain config (taken from dapp config/blockchain.js)
    • cb {function} - function that is fired once the blockchain node has started
blockchain:node:stop
  • name: blockchain:node:stop
  • description: Stops a blockchain node, by calling the registered stopFn. Will stop one of the nodes previously registered with blockchain:node:register.
  • arguments:
    • clientName {string} - name of the registered blockchain node
    • cb {function} - function that is fired once the blockchain node has stopped
blockchain:node:provider
  • name: blockchain:node:provider
  • description: Gets a blockchain node's provider, by calling the registered provider function. Will get the provider of the nodes previously registered with blockchain:node:register. A node provider is a provider that allows a direct connection to the node, without going through Embark's proxy. It is not recommended to use this provider unless a direct connection to the node is explicitly needed. In most cases, blockchain:client:provider should be used instead.
  • arguments:
    • clientName {string} - name of the registered blockchain node
    • cb {function} - callback function called with an error and value of the provider
blockchain:client:register
  • name: blockchain:client:register
  • description: Registers a function that returns a client provider for the node. A client provider is to be used by modules that want to connect to Embark's proxy, which is recommended for all modules that do not need a direct connection to the node (which is all modules except the proxy in most cases).
  • arguments:
    • clientName {string} - name of the registered blockchain client provider
    • getProviderFunction {function} - function that accepts a parameter endpoint {string} and returns a provider (ie a Web3 provider)
    • cb {function} - callback function called after completion
blockchain:client:provider
  • name: blockchain:client:provider
  • description: Calls the client provider function registered using blockchain:client:register, and passes in the endpoint of the proxy. A client provider is to be used by modules that want to connect to Embark's proxy, which is recommended for all modules that do not need a direct connection to the node (which is all modules except the proxy in most cases).
  • arguments:
    • clientName {string} - name of the registered blockchain client provider
    • cb {function} - callback function called with an error and the value of the provider

Actions used

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

Events emited

  • blockchain:started - emitted when blockchain node starts
  • blockchain:stopped - emitted when blockchain node stops

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

contracts-manager

module type: stack component

API

requests

name: contracts:reset

Resets the internal contracts memory.

name: contracts:build arguments:

  • contractsConfig - ContractsConfig - Smart Contract configuration object
  • compiledContracts - CompiledContracts - Map of compiled Smart Contract objects

Builds Contract objects from contractsConfig and compiledContracts.

name: contracts:list

Returns a list of built contracts.

name: contracts:state

Returns messages that describe the deployment state of each individual Smart Contract.

name: contracts:contract arguments:

  • contractsName - string - Name of contract to be returned

Returns a Contract by given contractsName

name: contracts:add arguments:

  • contract - ContractConfig - Configuration of single Smart Contract

Creates a Contract from contract and adds it to internal contract memory.

name: contracts:all

Returns list of Smart Contracts from internal contract memory.

name: contracts:dependencies

Returns contracts dependencies mapping based on currently compiled contracts (requires contract:build to be run first)

name: contracts:contract:byTxHash arguments:

  • txHash - string - A transaction hash

Returns a Contract by given hash.

name: contracts:reset:dependencies

Resets internal dependencies mapping.

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
Add a custom footer

http://embark.status.im/

Clone this wiki locally