iExec API now Open Source (minimalistic version)

An antique Porsche.

We’re open sourcing the initial version of the iExec application interface for Ethereum Dapps developpers. These are solidity contracts that allow developers to submit off-chain task execution. We gave two examples of applications that can be built with the API :

• VanityGen : a vanity bitcoin address generator
• Stockfish : an off-chain artificial intelligence engine

You are invited to start using this API. But proceed with caution, since it is still work in progress. The API may evolve drastically in the future, and you may probably have to modify your application.

Summary of smart contract methods :

• UID register(UID uid)
• UID submit(String appName, String commandLineParameter)
• void setParam (UID uid, String paramName, String paramValue)
• void setPending (UID uid)
• String getParam (UID uid, String paramName)
• String getStatus (UID uid)
• String submitAndWait(String appName, String commandLineParameter, String pattern)
• String waitResult (UID uid, String commandLineParameter, String pattern)
• void remove(UID uid)

https://github.com/iExecBlockchainComputing/ApiSolidity

Next sections detail each method.

Register

This registers a new work for the provided application. The job status is set to UNAVAILABLE so that it is not eligible to scheduling. This lets a chance to set different parameters. To make the work eligible to scheduling, setPending() must be called.

UID register (String appName)

• appName: the name of the application
• returns the new work UID
• Exception thrown if application is not found, or submission failed

Submit

This submits a new work for the provided application. The job status is set to PENDING so that it is schedulable. This is useful to submit a work with no param but the command line one, eventually, in a single call.

UID submit (String appName, String commandLineParameter)

• appName: the name of the application
• commandLineParameter: command line parameter
• returns the work UID
• Exception thrown if application is not found, or submission failed

SetParam

This sets a parameter for the work.

void setParam (UID uid, String paramName, String paramValue)

• uid: work UID
• paramName : name of the parameter to set
• paramValue: parameter value to set
• Exception is thrown if work is not found; if work status is not UNAVAILABLE; if parameter name is not valid; if parameter is read only (e.g. status, return code etc.)

SetPending

This makes the work schedulable. This must be called when using register().

void setPending (UID uid)

• uid: work UID
• Exception is thrown if work is not found

GetParam

This retrieves a parameter from work.

String getParam (UID uid, String paramName)

• uid: work UID
• paramName : name of the parameter to retrieve
• returns the parameter value
• Exception is thrown if work is not found, or if parameter name is not valid

GetStatus

This retrieves the work status.

• String getStatus (UID uid)
• uid: work UID
• returns the work status.
  Possible status: PENDING, RUNNING, COMPLETED, ERROR, UNAVAILABLE
• Exception is thrown if work is not found

GetResultPath

This retrieves the path of the result stored on local FS.

• Path getResultPath (UID uid)
• uid: work UID
• returns the path of the result
• Exception is thrown if work is not found; if work status is on ERROR (see status() )

GetStdout

This retrieves the content of the work stdout.

• String getStdout (UID uid)
• uid: work UID
• returns the content of the work stdout
• Exception is thrown if work is not found; if work status is ERROR (see status() )

Remove

This deletes work. This is unrecoverable.

• void remove (UID uid)
• uid: work UID

SubmitAndWait

This submits a new work and wait for its completion.

String submitAndWait(appName, cmdLineParam, pattern)

• appName: the name of the application
• commandLineParameter: command line parameter
• pattern: the pattern to be retrieved in the work stdout
• returns the value of the pattern found in stdout
• Exception thrown if application is not found, if submission failed, or if pattern is not found in stdout

WaitResult

This waits for the work to be completed and searches the provided pattern in the work result.

String waitResult(UID uid, String pattern)

• uid: work UID
• pattern: the pattern to be retrieved in the work stdout
• returns the value of the found pattern
• Exception is thrown work is not found, if submission failed, if work status is ERROR (see status() ), or if pattern not found in stdout

Workflows

This section introduces typical workflows.

Asynchronized

This is the simplest case where work is submitted without any parameter but the command line, eventually. User does not want to wait for result and may come later to retrieve its results asynchronously.

This is done calling:

1. submit(appName, commandLineParameters, pattern)

Synchronized

This is the synchronized case where the user waits its results. This is how the PoC used to work.

This is done calling:

1. submitAndWait(appName, commandLineParameters, pattern)

Asynchronized with parameters

This case permits to set some work parameters. User does not want to wait for result and may come later to retrieve its results asynchronously.

This is done calling :

1. register(appName)
2. for each parameter : setParam(uid, paramName, paramValue)
3. setPending(uid)

Synchronized with parameters

This is the synchronized case permitting to set some parameters. Here the user waits its results.

This is done calling:

1. register(appName)
2. for each parameter : setParam(uid, paramName, paramValue)
3. setPending(uid)
4. wait(uid, pattern)

Conclusion

In the coming weeks, we’ll release a simple tutorial, so that developers can start glancing at it and prototype their applications. You are invited to join us on our slack.