CLI and JS library allowing developers to easily interact with the iExec stack
Latest commit da71662 Dec 13, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src add timer between deposits tx Dec 3, 2018
test fix test Oct 25, 2018
.dockerignore add Dockerfile Sep 7, 2017
.drone.yml update CI Oct 25, 2018
.eslintrc add _name May 7, 2018
.gitignore bump v1.4.2 + remove ignore dist Dec 18, 2017
.prettierrc add prettier + update contracts deps Apr 18, 2018
Dockerfile update dockerfile May 10, 2018
LICENSE add LICENCE Feb 2, 2018
README.md update tee doc Oct 29, 2018
iexec_sdk_logo.jpg put logo in repo Mar 1, 2018
package.json bump v2.3.1 Dec 13, 2018

README.md

iExec SDK logo

iExec SDK V2

Build Status npm version npm version license Twitter Follow

The iExec SDK is a CLI and a JS library that allows developers to interact with iExec decentralized marketplace in order to run off-chain computations.

Resources

Install

All three major OS are supported (linux, OSX, windows).

Using Nodejs

Requirements: npm version and Git.

npm -g install iexec # install the cli
iexec --version
iexec --help

Using Docker

Requirements: Docker.

# For Linux users
echo 'alias iexec='"'"'docker run -e DEBUG=$DEBUG --interactive --tty --rm -v /tmp:/tmp -v $(pwd):/iexec-project -w /iexec-project iexechub/iexec-sdk'"'"'' >> ~/.bashrc && source ~/.bashrc
# For Mac OSX users
echo 'alias iexec='"'"'docker run -e DEBUG=$DEBUG --interactive --tty --rm -v /tmp:/tmp -v $(pwd):/iexec-project -w /iexec-project iexechub/iexec-sdk'"'"'' >> ~/.bash_profile && source ~/.bash_profile

Now run iexec --version to check all is working.

Upgrade

  • Nodejs: run npm -g install iexec
  • Docker: run docker pull iexechub/iexec-sdk

Tutorials

Video

Katacoda

Katacoda is an in-browser terminal that allows you to remotely follow tutorials without the need to install the SDK on your machine: https://www.katacoda.com/sulliwane/scenarios/sdk-v2-tutorial

Text

Init project

required steps before following any other workflow.

iexec init # create all required files
iexec wallet getETH # ask faucet for ETH
iexec wallet getRLC # ask iExec faucet for RLC
iexec account deposit 200 # deposit nRLC on your iExec account, so you can buy orders
iexec wallet show
iexec account show

Deploy an app

iexec app count # check if you have already deployed apps
iexec app init # reset app fields in iexec.json
iexec app deploy # deploy app on Ethereum
iexec app show # show details of deployed app

Buy & Run work using Marketplace

iexec order init --buy # init work order fields in iexec.json
vi iexec.json # edit iexec.json and customize the buy order fields. Particularly work params field.
iexec orderbook show --category 5 # show orderbook and choose an order ID
iexec order fill <orderID> # fill order using its ID
iexec work show --watch --download # watch progress of the submitted work, and download its result when completed

iExec SDK CLI API

Help & Info

iexec --version
iexec --help
iexec app --help
iexec orderbook --help
iexec info --chain kovan

init

iexec init # create all files necessary to get started

wallet

# OPTIONS
# --chain <chainName>
# --to <address>
# --force
# --hub <address>
# --password <password>
iexec wallet create
iexec wallet getETH
iexec wallet getRLC
iexec wallet show [address] # optional address to show other people's wallet
iexec wallet sendETH <amount> --to <eth_address>
iexec wallet sendRLC <amount> --to <eth_address>
iexec wallet sweep --to <eth_address> # drain all ETH and RLC, sending them back to iExec faucet by default
iexec wallet encrypt --password <password> # save encrypted-wallet.json from wallet.json
iexec wallet decrypt --password <password> # save wallet.json from encrypted-wallet.json

account

# OPTIONS
# --chain <chainName>
# --force
# --hub <address>
iexec account login
iexec account show [address] # optional address to show other people's account
iexec account deposit <amount>
iexec account withdraw <amount>

app

# OPTIONS
# --chain <chainName>
# --hub <address>
# --user <address>
iexec app init # init new app
iexec app deploy # deploy new app
iexec app show [address|index] # show app details
iexec app count --user <userAddress> # count user total number of app

dataset

# OPTIONS
# --chain <chainName>
# --hub <address>
# --user <address>
iexec dataset init # init new app
iexec dataset deploy # deploy new dataset
iexec dataset show [address|index] # show dataset details
iexec dataset count --user <userAddress> # count user total number of dataset

workerpool

# OPTIONS
# --chain <chainName>
# --hub <address>
# --user <address>
iexec workerpool init # init new workerpool
iexec workerpool deploy # deploy new workerpool
iexec workerpool show [address|index] # show workerpool details
iexec workerpool count --user <userAddress> # count user total number of workerpool

orderbook

# OPTIONS
# --chain <chainName>
# --category [ID]
# --pool [address]
iexec orderbook show --category 5 # show orderbook for category 5

order

# OPTIONS
# --chain <chainName>
# --hub <address>
# --sell
# --buy
# --force
iexec order init --buy # init new buy order
iexec order init --sell # init new sell order
iexec order place # place an order at limit price
iexec order show <orderID> # show an order
iexec order fill <orderID> # fill an order at market price and start work execution
iexec order cancel <orderID> # cancel an order
iexec order count # count marketplace total number of order

work

# OPTIONS
# --chain <chainName>
# --watch
# --download [fileName]
iexec work show [address] --watch --download # show a work, watch its status changes and download it when completed

tee

# OPTIONS
# --chain <chainName>
# --application <appName | app0xAddress>
# --keysFolderPath <path>
# --inputsFolderPath <path>
# --encryptedOutputsFolder <path>
# --outputsFolderPath <path>
# --secretManagementService <hostname/IP>
# --remoteFileSystem <serviceName>
iexec tee init # init the TEE folders tree structure
iexec tee encryptedpush --application iexechub/sgx-scone:blender # encrypt work input data + upload it to file hosting service
iexec tee decrypt # decrypt work result

category

# OPTIONS
# --chain <chainName>
# --hub <address>
iexec category init # init new category
iexec category create # create new category
iexec category show <index> # show category details by index
iexec category count # count hub total number of category

registry

iexec registry validate app # validate an object description [app, dataset, workerpool]

scheduler

iexec scheduler show # show scheduler details
iexec scheduler api # direct call of scheduler API methods

iexec.json

The iexec.json file, located in every iExec project, describes the parameters used when creating a [app|datasetcategory|workerPool], or when submitting a work.

{
  "app": {
    "name": "next-dapp1",
    "price": 1,
    "params": {
      "type": "DOCKER",
      "envvars": "XWDOCKERIMAGE=ericro/face-recognition"
    }
  },
  "dataset": {
    "name": "next-dataset",
    "price": 2,
    "params": {
      "uri": "https://data.provider.com"
    }
  },
  "category": {
    "name": "CAT1",
    "description": "my category N°1",
    "workClockTimeRef": 100
  },
  "workerPool": {
    "description": "Qarnot WorkerPool ",
    "subscriptionLockStakePolicy": 100,
    "subscriptionMinimumStakePolicy": 100,
    "subscriptionMinimumScorePolicy": 100
  }
}

chains.json

The chains.json file, located in every iExec project, describes the parameters used when communicating with ethereum nodes and iExec schedulers. They are ordered by chain name, accessible by using the --chain <chainName> option for each command of the SDK.

{
  "default": "kovan",
  "chains": {
    "development": {
      "host": "localhost",
      "id": "*",
      "server": "https://localhost:443"
    },
    "ropsten": {
      "host": "https://ropsten.infura.io/berv5GTB5cSdOJPPnqOq",
      "id": "3",
      "server": "https://testxw.iex.ec:443"
    },
    "rinkeby": {
      "host": "https://rinkeby.infura.io/berv5GTB5cSdOJPPnqOq",
      "id": "4",
      "server": "https://testxw.iex.ec:443"
    },
    "kovan": {
      "host": "https://kovan.infura.io/berv5GTB5cSdOJPPnqOq",
      "id": "42",
      "server": "https://testxw.iex.ec:443"
    },
    "mainnet": {
      "host": "https://mainnet.infura.io/berv5GTB5cSdOJPPnqOq ",
      "id": "1",
      "server": "https://mainxw.iex.ec:443"
    }
  }
}

iExec Library API

[Work In Progress] Although we'll try to avoid any API change, the Lib API may still evolve a little bit based on beta-tester feedbacks.

iExec SDK can be imported in your code as a library/module, and it's compatible with old JS engines:

  • >= Node v6.4
  • >= Firefox v22
  • >= Chrome v28
  • >= IE 9

Methods

wallet.checkBalances

Parameters

  • contracts Object an iexec contracts object
  • address String the address to check balances on
  • options Object [optional] options
    • options.hub String custom hub address

Return (Promise)

  • balances Object
    • balances.wei BN ether balance in wei
    • balances.nRLC BN RLC balance in nano RLC

Example

// wallet.checkBalances

wallet.getETH

Parameters

  • chainName String name of the chain (ropsten|rinkeby|kovan)
  • address String the address to ask ETH for

Return (Promise)

  • responses Array of String String response from each faucet api

Example

// wallet.getETH

wallet.getRLC

Parameters

  • chainName String name of the chain (ropsten|rinkeby|kovan)
  • address String the address to ask ETH for

Return (Promise)

  • responses Array of String String response from each faucet api

Example

// wallet.getRLC

wallet.sendETH

Parameters

  • contracts Object an iexec contracts object
  • amouont String the amount of nano RLC to send to
  • from String the address the is sending ETH
  • to String the address that is receiving the amount of ETH

Return (Promise)

  • txReceipt Object the ethereum transaction receipt

Example

// wallet.sendETH

wallet.sendRLC

Parameters

  • contracts Object an iexec contracts object
  • amount String the amount of nano RLC to send to
  • to String the address that will receive the amount of nRLC
  • options Object [optional] options
    • options.hub String custom hub address

Return (Promise)

  • txReceipt Object the ethereum transaction receipt

Example

// wallet.sendRLC

account.auth

Parameters

  • amount String the amount of nano RLC to send to
  • scheduler Object an iexec scheduler object
  • ethjs Object Ethjs client

Return (Promise)

  • jwtoken String the iExec jwt token

Example

// account.auth

account.deposit

Parameters

  • contracts Object an iexec contracts object
  • amount String the amount of nano RLC to deposit in iExec account
  • options Object [optional] options
    • options.hub String custom hub address

Return (Promise)

  • txReceipt Object the ethereum transaction receipt

Example

// account.deposit

account.withdraw

Parameters

  • contracts Object an iexec contracts object
  • amount String the amount of nano RLC to deposit in iExec account
  • options Object [optional] options
    • options.hub String custom hub address

Return (Promise)

  • txReceipt Object the ethereum transaction receipt

Example

// wallet.withdraw

hub.createObj

Parameters

  • objName String the object type name (app|workerPool|dataset)

Return Below Function:

Parameters

  • contracts Object an iexec contracts object
  • obj Object the object to create
  • options Object [optional] options
    • options.hub String custom hub address

Return (Promise)

  • events Object the decoded logs from the transaction receipt

Example

// hub.createObj

hub.showObj

Parameters

  • objName String the object type name (app|workerPool|dataset)

Return Below Function:

Parameters

  • contracts Object an iexec contracts object
  • objAdressOrIndex String the object address or index
  • userAddress String the user address to query for
  • options Object [optional] options
    • options.hub String custom hub address

Return (Promise)

  • obj Object All the properties of the object

Example

// hub.showObj

hub.countObj

Parameters

  • objName String the object type name (app|workerPool|dataset)

Return Below Function:

Parameters

  • contracts Object an iexec contracts object
  • userAddress String the user address to query for
  • options Object [optional] options
    • options.hub String custom hub address

Return (Promise)

  • objCount BN The total count of object

Example

// hub.countObj

iExec SDK CLI fork/spawn

If your program is not written in javascript, your last option to use the SDK would be to spawn it as a seperate process (sometimes called FORK operation). After each SDK run you should check the exit code returned by the SDK to know if the operation was sucessfull or not echo $?:

  • 0 = successful
  • 1 = error

Finally, you could choose to parse the SDK stdout/stderr to access more information. ex:

  • iexec orderbook show &> out.txt
  • iexec orderbook show |& grep .

Warning:

  • The stdout/stderr is subject to changes (this is what makes this solution brittle)
  • The node and docker version have some slight differences in their stdout/stderr