The JavaScript implementation of the Ethernity CLOUD protocol

Installation

To begin developing with the Ethernity Cloud Runner, you can easily set up your environment by installing the package using npm:

$ npm install @ethernity-cloud/runner --save

This command will install the Ethernity Cloud Runner package and save it as a dependency in your project. With the package installed, you're ready to start utilizing the Ethernity Cloud Runner functionality and explore its capabilities for your application development.

Environment Prerequisites

1. IDE

For a streamlined development process, we recommend using Visual Studio Code—a powerful and versatile code editor that offers a seamless experience for developers. You can download Visual Studio Code from the official website.

After running the IDE, a new workspace will be created, where you can start developing the framework and code.

2. Framework

Using a Terminal within the IDE workspace, follow these steps to set up your framework of choice.

Node.js: Node.js is an open-source, server-side JavaScript runtime environment that allows developers to execute JavaScript code outside of a web browser. It uses an event-driven, non-blocking I/O model, making it highly efficient and suitable for building scalable and real-time applications.

Install Node.js on your local machine by following the instructions provided here: Node.js Download.

3. Wallet Setup

A wallet is a crucial tool within the Ethernity Cloud ecosystem, empowering users to securely store and transfer their data for processing. As a developer, having a Web3 dApp testing wallet is necessary.

The wallet setup process with Metamask is detailed here: Getting started with MetaMask.

Ethernity Cloud runs on several networks. Set up your wallet for the network you intend to use (see the Networks section below for the full list and chain IDs):

• Bloxberg (mainnet and testnet)
• Polygon (mainnet) and Polygon Amoy (testnet)
• IoTeX Testnet, Ethereum Sepolia, and LitVM LiteForge (testnets)

4. Code execution

To execute a new task using the Ethernity Cloud Runner, follow the straightforward template provided below. Simply insert your desired code into the designated section, and the runner will handle the rest, interacting with the IPFS network and processing the task accordingly.

import EthernityCloudRunner from "@ethernity-cloud/runner";
import { ECRunner, ECStatus, ECAddress } from "@ethernity-cloud/runner/enums";

const executeTask = async () => {
    const ipfsAddress = 'https://ipfs.ethernity.cloud';
    const code = `___etny_result___("Hello, World!")`;

    // Progress updates (encrypting, submitting, matching, downloading, ...).
    const onProgress = (e) => {
        console.log(`[${e.detail.progress}] ${e.detail.message}`);
    };

    // Fired once the task completes; fetch the result from the runner.
    const onSuccess = async () => {
        const result = await runner.getResult();
        console.log(`Task Result: ${result}`);
    };

    const onError = (e) => {
        console.error(e.detail.message);
    };

    // No network address -> Bloxberg testnet + the browser wallet.
    // To target another network pass its token address, e.g.
    //   new EthernityCloudRunner(ECAddress.POLYGON.TESTNET_ADDRESS);
    const runner = new EthernityCloudRunner();
    runner.initializeStorage(ipfsAddress);

    // Events are dispatched named by task status (the ECStatus values).
    runner.addEventListener(ECStatus.DEFAULT, onProgress); // "Running" updates
    runner.addEventListener(ECStatus.SUCCESS, onSuccess);
    runner.addEventListener(ECStatus.ERROR, onError);

    const resources = { taskPrice: 10, cpu: 1, memory: 1, storage: 40, bandwidth: 1, duration: 1, validators: 1 };
    // Execute a task with the Python testnet enclave on Bloxberg.
    // Signature: run(resources, secureLockEnclave, code, nodeAddress = '', trustedZoneEnclave)
    await runner.run(resources, ECRunner.BLOXBERG.PYNITHY_RUNNER_TESTNET, code);
}

await executeTask();

___etny_result___ function

The ___etny_result___ function is a special function used in Ethernity Cloud Runner tasks. When executing a task, this function allows the task code to send the result back from the Ethernity Cloud platform.

In the context of the Ethernity Cloud Runner, tasks are executed in a decentralized and distributed manner. The ___etny_result___ function acts as a communication channel between the task code and the Ethernity Cloud platform. When the function is called with the result data as its argument, it sends the result back to the platform, where it can be processed and stored.

This special function plays a crucial role in ensuring that the results of executed tasks are properly recorded and accessible. It enables seamless interaction with the Ethernity Cloud platform, making it a key component of the Ethernity Cloud Runner's functionality.

Events subscription

The runner extends EventTarget and, as a task moves through its lifecycle, dispatches CustomEvents named by the task status. You therefore subscribe using the ECStatus values, not a separate event-name enum:

Event name (ECStatus)	Value	When it fires
ECStatus.DEFAULT	"Running"	Progress updates while the task is encrypting, being submitted, matched, processed, and the result downloaded.
ECStatus.SUCCESS	"Success"	The task finished successfully and a result is available.
ECStatus.ERROR	"Error"	The task failed (e.g. no matching node, insufficient balance, checksum error).

Every event's detail is { message, status, progress }:

• message — a human-readable message for the current step.
• status — the ECStatus value (same as the event name).
• progress — a phase label from ECEvent (e.g. "Encrypting task", "In Progress", "Downloading result", "Finished"), useful for driving a progress UI.

// Progress: use e.detail.progress for the phase and e.detail.message for detail.
const onProgress = (e) => {
    console.log(`[${e.detail.progress}] ${e.detail.message}`);
};

// Success: the result is available on the runner once this fires.
const onSuccess = async () => {
    const result = await runner.getResult();
    console.log(`Task Result: ${result}`);
};

// Error: something went wrong; e.detail.message explains what.
const onError = (e) => {
    console.error(e.detail.message);
};

runner.addEventListener(ECStatus.DEFAULT, onProgress);
runner.addEventListener(ECStatus.SUCCESS, onSuccess);
runner.addEventListener(ECStatus.ERROR, onError);

After ECStatus.SUCCESS, call await runner.getResult() to obtain the decrypted task result.

Task resources

 const resources = { taskPrice: 10, cpu: 1, memory: 1, storage: 40, bandwidth: 1, duration: 1, validators: 1 };

The resources parameter is the first argument to the run method and is an object that defines the resource requirements for executing a new task using the Python/Node.js template. It specifies the amount of various resources needed for the task to be processed on the EthernityCloud network. The resources object contains the following properties:

1. taskPrice: This represents the price in tETNY that a user is willing to pay for the task execution. It determines the priority and readiness of the task for processing.

2. cpu: This specifies the amount of CPU (Central Processing Unit) resources required for the task. It indicates the computational power needed to execute the task's code.

3. memory: This indicates the amount of RAM memory required for the task's execution. It represents the storage space in RAM memory needed to run the task.

4. storage: This property represents the storage space needed for the task's execution. It indicates the amount of disk space required for the task.

5. bandwidth: This defines the amount of network bandwidth required for the task's execution. It represents the data transfer capacity needed to perform the task.

6. duration: This specifies the time duration or the maximum time allowed for the task's execution. It sets a time limit for how long the task can run.

7. validators: This property determines the number of validators required for the task. Validators are nodes on the network responsible for processing and validating tasks.

By providing these resource requirements in the resources object, the task execution engine (EthernityCloudRunner) can use this information to allocate the necessary resources and process the task accordingly on the selected network.

Networks

The network is chosen by passing the network's token contract address (from ECAddress) as the first argument to the constructor. With no argument, the runner targets the Bloxberg testnet.

Network	Type	Chain ID	Constructor address
Bloxberg	mainnet	8995	ECAddress.BLOXBERG.MAINNET_ADDRESS
Bloxberg	testnet	8995	ECAddress.BLOXBERG.TESTNET_ADDRESS
Polygon	mainnet	137	ECAddress.POLYGON.MAINNET_ADDRESS
Polygon Amoy	testnet	80002	ECAddress.POLYGON.TESTNET_ADDRESS
IoTeX	testnet	4690	ECAddress.IOTEX.TESTNET_ADDRESS
Ethereum Sepolia	testnet	11155111	ECAddress.SEPOLIA.TESTNET_ADDRESS
LitVM LiteForge	testnet	4441	ECAddress.LITVM.TESTNET_ADDRESS

import { ECAddress, ECRunner } from "@ethernity-cloud/runner/enums";

// Run on Polygon Amoy
const runner = new EthernityCloudRunner(ECAddress.POLYGON.TESTNET_ADDRESS);
// ...
await runner.run(resources, ECRunner.POLYGON.PYNITHY_RUNNER_TESTNET, code);

The ECRunner enclave-image enum is keyed by network, so use the entry matching the network you constructed the runner with (e.g. ECRunner.IOTEX.PYNITHY_RUNNER_TESTNET). Mainnet variants drop the _TESTNET suffix.

The IoTeX, Sepolia, and LitVM testnets share a single ECLD token address, so the runner reads the chain ID from your wallet/provider to distinguish them — automatic with a browser wallet or an injected provider. On the raw-private-key path, pass the chain ID as the third constructor argument and an rpcUrl in the wallet options:

const runner = new EthernityCloudRunner(
    ECAddress.IOTEX.TESTNET_ADDRESS,
    { privateKey: "0x…", rpcUrl: "https://babel-api.testnet.iotex.io" },
    4690 // IoTeX Testnet chain ID
);