The iExec Software Development Kit (SDK) is a CLI and a JS library offering developers the tools to interact with iExec. The SDK allows to easily contribute resources and monetize datasets as well as run off-chain computations and interact with the iExec marketplace. For iExec V3, the SDK has been given a major upgrade, including higher security as well as changes to developer workflow for improvements to general ease-of-use.

In case you missed it, read our post about what is to come for iExec V3: Enterprise Edition

This development letter will detail the technical changes between the old version and upgraded SDK V3 with new features. Find the SDK here:

Contents:

Changes to Wallet and Wallet Management Developer Workflow New Marketplace Order Types Requester Workflow

Changes to Wallet and Wallet Management

New secure encrypted wallet: To interact with the iExec Smart contracts, the iExec SDK uses an Ethereum wallet. This wallet identifies their owner by a unique Ethereum address and stores their assets (ether and RLC).

In the older version of the SDK, wallets were stored in the form of unencrypted .json files called ‘wallet.json’ located in the working directory. For SDK V3 we decided to standardize the wallet management process, allowing for increased security and more flexibility when exporting.

Standard Wallet Keystore

The wallet is now located in the Ethereum keystore. This Ethereum keystore location depends on your OS:

Linux : ~/.ethereum/keystore

Mac: ~/Library/Ethereum/keystore

Windows: ~/AppData/Roaming/Ethereum/keystore

️Note: If you are using the docker version of the iExec SDK, you will need to bind the keystores volumes. See: iExec install documentation

Using standard UTC/JSON encrypted wallet file

From V3 iExec will use the standard UTC/JSON encrypted wallet file. Using an encrypted wallet will lower the risk of leaking of private keys.

Additional feature: UTC/JSON format can be shared between multiple applications. This means that you will be able to use the same wallet file with iExec and your other Ethereum applications.

In order to use the wallet, the SDK command line will simply prompt the user to enter the wallet password.

Using Multiple Wallets

As the iExec SDK V3 uses UTC/JSON format, it is now possible to use multiple wallets from the keystore.

As default, the most recent wallet in the keystore will be used.

You can specify the address of the wallet to use

$ iexec wallet show --wallet-address 0xC08C3def622Af1476f2Db0E3CC8CcaeAd07BE3bB

..or specify the full name

$ iexec wallet show --wallet-file UTC--2019-01-00T10-56-30.572000000Z --A540FCf5f097c3F996e680F5cb266629600F064A

Generating a new secure encrypted wallet

$ iexec wallet create

You will be asked to choose an encryption password — and that’s it!

You now have your new and more flexible Ethereum wallet. Make sure to back up the generated file and to make note of your password, there is no ‘Forgotten password’ button!

When you create a wallet, the wallet address that is displayed is your Ethereum address, remember it because, as noted above, you will need it to specify which wallet to use.

Now let’s show the wallet: you can check the wallet balances as well as find the public and private keys, wallet address and balances.

$ iexec wallet show

You probably noticed that private key is no longer automatically displayed on the screen upon viewing the wallet. To uncover it, use the following option:

$ iexec wallet show --show-private-key

Backward compatibility with V2 wallet.

If you already have a wallet.json file from V2 in your working directory, it will be loaded first, so that you can continue using the iExec SDK as before.

Despite that fact that using wallet.json is still possible, we strongly recommend switching to using an encrypted wallet.

To convert your ‘wallet.json’ to an encrypted wallet, you will need to import it with the private key.

First, take your private key from your old wallet.json, then use the command:

$ iexec wallet import <privatekey>

V3 workflow

The V3 version of PoCo introduces multiple changes in the iExec workflow. You can find more information about the updates to PoCo in this article

New Types of Orders

V3 introduces four new types of orders:

workerpool order : defines what a computing provider (or Workerpool) wants to sell, (replaces V2 sell order).

: defines what a computing provider (or Workerpool) wants to sell, (replaces V2 sell order). request order : defines what a requester (an individual or enterprise requesting the use of cloud resources through iExec) wants to buy (in V2 this was the act of filling a sell order)

: defines what a requester (an individual or enterprise requesting the use of cloud resources through iExec) wants to buy (in V2 this was the act of filling a sell order) app order : defines what a dapp provider wants to sell, this new type of order allows the dapp provider set it pricing as well as other parameters.

: defines what a dapp provider wants to sell, this new type of order allows the dapp provider set it pricing as well as other parameters. dataset order: defines what a dataset provider wants to sell, this new type of order for the V3 Data Store.

The deal is a matching between compatible orders, it describes the contract between the signers. Several tasks can be gathered in the same deal

As soon as a deal is concluded, RLC are locked by the clerk until every task of the deal is completed

The iExec SDK V3 allows for easy manipulation of all these orders.

Changes to Developer Workflow SDK V3 for Dapp Developers

The iExec Dapp developer dockerizes their app and registers it on the iExec smart contract to sell decentralized executions on a pay-per-task basis.

Application Deployment

Deploying an app on iExec V3 is much the same as V2, only some fields differs:

“app”: {

“owner”: “0xb45930519b8dac8b80b20c3e84c6ba98cf91cbad”,

“name”: “hello-world”,

“type”: “DOCKER”,

“multiaddr”: “registry.hub.docker.com/hello-world:linux”,

“checksum”: “0x90bef26b4e016c47ef0814cc02db77e56ca7aef0dca5b079b48326a2a7326ca5”,

“mrenclave”: “”

}

App fields:

owner: the eth address of the dapp owner, only the dapp owner can sign apporders

the eth address of the dapp owner, only the dapp owner can sign apporders name: name of your dapp

name of your dapp type : type of packaging of your dapp

: type of packaging of your dapp multiaddr : URI of the app

: URI of the app checksum : 0x prefixed sha256 of the app

: 0x prefixed sha256 of the app mrenclave: indentify a TEE dapp

In V3, the dapp price is no longer specified in the deployed dapp. Dapp execution price is specified in the apporder.

Once your dapp is published, you will need to produce an apporder to allow requesters to use your dapp.

Application Monetization

First, init an apporder

$ iexec order init --app

This will create order.apporder field in the iexec.json file

“order”: {

“apporder”: {

“app”: “0x44e47D75B156e970c497a9f8461aB92abdE3a710”,

“appprice”: “0”,

“volume”: “100000”,

“tag”: “0x0000000000000000000000000000000000000000000000000000000000000000”,

“datasetrestrict”: “0x0000000000000000000000000000000000000000”,

“workerpoolrestrict”: “0x0000000000000000000000000000000000000000”,

“requesterrestrict”: “0x0000000000000000000000000000000000000000”

}

}

Apporder fields:

app: eth address of your dapp

appprice: Price per run

volume: volume of runs allowed by the order

tag: ill allow to specify runtime restrictions (default no restriction)

datasetrestrict: allow only a specific dataset to be used (default no restriction)

workerpoolrestrict: allow only a specific workerpool to run your dapp (default no restriction)

requesterrestrict: allow only a specific requester to use your dapp (default no restriction)

Modify it as needed to specify your selling conditions:

We recommend dapp developers create apporders with a sufficient volume to satisfy requests.

Next, you must sign your apporder

$ iexec order sign --app

This produces a signed apporder in the orders.json file.

You can now share this signed order with the other users.

$ iexec order publish --app

You can check all the published orders for your application:

$ iexec orderbook app <appAddress>

To renew your apporder use the command:

$ iexec order sign --app && iexec order publish --app

Workflow for Pool Managers in the SDK V3

A worker pool is managed by a pool manager is the essential actor of the infrastructure. It will be in charge of distributing the works submitted by the users to the different workers that are connected to this pool.

Registering: Workerpool Deployment

The Workflow for deploying a Workerpool is similar for iExec V3. Only the fields differ:

“workerpool”: {

“owner”: “0xb45930519b8dac8b80b20c3e84c6ba98cf91cbad”,

“description”: “my-workerpool”

}

owner : this is the eth address of the workerpool owner (only the workerpool owner can sign workerpoolorders)

: this is the eth address of the workerpool owner (only the workerpool owner can sign workerpoolorders) description: name of your workerpool

Workers: Monetizing Computing power

Once your workerpool is deployed you will need to produce a workerpoolorder to allow requesters to use your workerpool.

First init a workerpoolorder

$ iexec order init --workerpool

This will create order.workerpoolorder field in your iexec.json

“order”: {

“workerpoolorder”: {

“workerpool”: “0x37667527709684BcBb425dfb5BD72E717AE1BA53”,

“workerpoolprice”: “0”,

“volume”: “1”,

“category”: “1”,

“trust”: “100”,

“tag”: “0x0000000000000000000000000000000000000000000000000000000000000000”,

“apprestrict”: “0x0000000000000000000000000000000000000000”,

“datasetrestrict”: “0x0000000000000000000000000000000000000000”,

“requesterrestrict”: “0x0000000000000000000000000000000000000000”

}

}

workerpoolorder fields:

workerpool : Ethereum address of your workerpool

: Ethereum address of your workerpool workerpoolprice : price per run

: price per run volume: volume of runs allowed by the order

volume of runs allowed by the order category: execution category

execution category trust: trust level provided by your workerpool (see PoCo)

trust level provided by your workerpool (see PoCo) tag: will allow to specify run restrictions (default no restriction)

will allow to specify run restrictions (default no restriction) apprestrict: allow only a specific app to be run by your workerpool (default no restriction)

allow only a specific app to be run by your workerpool (default no restriction) datasetrestrict: allow only a specific dataset to be used (default no restriction)

allow only a specific dataset to be used (default no restriction) requesterrestrict: allow only a specific requester to use your workerpool (default no restriction)

Modify it to specify your selling conditions.

You must now sign your workerpoolorder

$ iexec order sign --workerpool

This will produce a signed workerpoolorder in the orders.json file.

This order can be shared with your partners or be published on iExec Marketplace.

$ iexec order publish --workerpool

You can now review and check the orders you have published for your Workerpool:

$ iexec orderbook workerpool <workerpoolAddress>

To renew your workerpoolorder use:

$ iexec order sign --workerpool && iexec order publish --workerpool

SDK V3 Workflow for Requesters

Requester is the name given to an individual or enterprise requesting the use of cloud resources through iExec. Requesters can be individuals or enterprises who want to purchase resources on iExec.