DevLetter 28 — SDK Upgrade: iExec V3

***UPDATE***

iExec V6 has been released, along with an updated SDK and Documentation: https://medium.com/iex-ec/iexec-v6-enclaves-in-production-mode-confidential-computing-upgrades-c5ceb7f27e3e
— -

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.

💡 Want to learn more about iExec? Check out iExec Academy!

iExec Academy aggregates all content related to the project. You’ll find articles, tech documentation, videos, interactive demos, and much more! Whether you are a beginner or an expert, a developer or crypto-enthusiast, you’ll find what you are looking for on iExec Academy!

📚➡️ https://academy.iex.ec

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:

iExecBlockchainComputing/iexec-sdk

Contents:

1. Changes to Wallet and Wallet Management
2. Developer Workflow
3. New Marketplace Order Types
4. 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).
• 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)
• 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.
• 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
• name: name of your dapp
• type: type of packaging of your dapp
• multiaddr: URI of the app
• checksum: 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)
• 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
• workerpoolprice: price per run
• volume: volume of runs allowed by the order
• category: execution category
• trust: trust level provided by your workerpool (see PoCo)
• tag: will allow to specify run restrictions (default no restriction)
• apprestrict: 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)
• 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.

Find an apporder

Get the app address of the dapp you want to run.

Find an open apporder for this app.

$ iexec orderbook app 0xC802175085431c7564c426082E83A4d0AE3B60d1

replace this with the address of the dapp you want to use

This will display the best offers for this dapp, copy the orderHash of the order you want to use.

Find a workerpoolorder

Choose the category of your execution. Now find an open workerpoolorder in this category.

$ iexec orderbook workerpool --category 1

This will display the best orders in the selected category, copy the orderHash of the workerpoolorder you want to use.

Specify your Request Order

requestorder defines what a requester (an individual or enterprise requesting the use of cloud resources through iExec) wants to buy (replaces V2 buy order)

$ iexec order init --request

This will create order.requestorder field in your iexec.json and should appear as below:

“order”: {
  “requestorder”: {
    “app”: “0xC802175085431c7564c426082E83A4d0AE3B60d1”,
    “appmaxprice”: “0”,
    “dataset”: “0x0000000000000000000000000000000000000000”,
    “datasetmaxprice”: “0”,
    “workerpool”: “0x0000000000000000000000000000000000000000”,
    “workerpoolmaxprice”: “0”,
    “volume”: “1”,
    “category”: “1”,
    “trust”: “100”,
    “tag”: “0x0000000000000000000000000000000000000000000000000000000000000000”,
    “beneficiary”: “0x0000000000000000000000000000000000000000”,
    “callback”: “0x0000000000000000000000000000000000000000”,
    “params”: “{ \”0\”: \”--help\” }”,
    “requester”: “0xb45930519b8dac8b80b20c3e84c6ba98cf91cbad”
  }
}

requestorder fields:

• app: Ethereum address of the dapp you want to use
• appmaxprice: maximum price per run for the app
• dataset: Ethereum address of the dataset you want to use (default no dataset)
• datasetmaxprice: maximum price per run for the dataset
• workerpool: Ethereum address of the workerpool you want to use (default any workerpool)
• workerpoolmaxprice: maximum price per run for the workerpool
• volume: volume of runs allowed by the order
• category: execution category
• trust: trust level wanted (see PoCo)
• tag: will allow to specify run restrictions (default no restriction)
• beneficiary: the wallet allowed to download the result (default requester)
• callback: address of the smartcontract to notify when the task is completed
• params: execution parameters, stringified JSON of index-command map
• requester: address that pay for the execution

Modify it as you want to specify your request.

Now, you must sign your requestorder:

$ iexec order sign --request

This will produce a signed requestorder in orders.json file.

Buy computation

Make sure to have enough RLC staked in your account to pay for the computation.

$ iexec account show

Make a deal

$ iexec order fill --app <orderHash> --workerpool <orderHash>

This will give you a deal, you will need it to follow your computation

Each deal may be constituted of one or several tasks, get the taskid of your task:

$ iexec deal show <dealid> --tasks 0

Show the status of your task and download the result of the task when completed:

$ iexec task show <taskid> --download

New scenarios for requesters on iExec V3

iExec V3 will offer new scenarios:

• Placing limit requestorders
• Selling computation at the market
• Trading OTC ‘over the counter,
• Using datasets

For scripting, SDK V3 CLI is now available with raw outputs.

$ iexec info --raw

You can check all the possibilities new to iExec V3 on our GitHub

iExecBlockchainComputing/iexec-sdk

Business Development

To learn more about the recent progress on the business development side of the project, please read January’s Project Update:

iExec Project Update #07 — January 2019

Latest Releases

• Core v3.0.0-alpha2
• Worker v3.0.0-alpha2
• PoCo v3.0.26
• SDK v3.0.21

Connect with us!

Website • Blog • Slack • Telegram • Reddit • Twitter • Facebook •LinkedIn• Youtube • Github • Kakao Talk• Instagram • Docs