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 :

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

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:

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:

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 :

register(appName) for each parameter : setParam(uid, paramName, paramValue) 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:

register(appName) for each parameter : setParam(uid, paramName, paramValue) setPending(uid) 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.