@ethernity-cloud/sdk-js 1.5.9 → 1.5.11

package/README.md

@@ -65,11 +65,46 @@ The sdk has been tested on the following operating systems:
   ```
   Required after build, to build and integrate the secure certificates that will be used during executions and to register the project to the Ethernity Cloud Image Register.
 
-- **Run**: To run the project, run:
+- **Test (local, no chain)**: To run your backend locally with the enclave's own
+  executor — no SGX, no gas, instant — run:
   ```sh
-  npm run start
+  npx ecld-test 'hello("World")'
+  npx ecld-test --file payload.js
+  npx ecld-test --input data.json 'processData(___etny_data_set___)'
+  ```
+  This validates the *call* (function names, arguments, result wiring) before a
+  single on-chain request is paid for. If your dApp uses ESR (Enclave State
+  Registry), state is emulated locally and **on by default**: `require('../ecld_state').StateRegistry`
+  get/commit, ownership/ACL, and `taskCaller()` all work in-process against an
+  in-memory registry, and persist between runs in `.ecld-esr-local.*.json`. The
+  task caller defaults to your developer address; override it with `--caller`.
+  `npx ecld-test serve` starts a local API so the runner's LOCAL mode drives your
+  real integration end to end. Exit code 0 on `SUCCESS`, 1 otherwise.
+
+- **Run (on the network)**: To submit a payload to the network and print the
+  decrypted result, run:
+  ```sh
+  npx ecld-run 'hello("World")'
+  npx ecld-run --file payload.js
+  npx ecld-run --input data.json 'processData(___etny_data_set___)'
+  npx ecld-run --json 'esrIncrement()'
+  ```
+  This is the network-side sibling of `ecld-test`: instead of executing locally
+  it drives the runner end to end — encrypt → IPFS → on-chain request → wait for
+  a node → download and decrypt the result. It **costs gas and needs a funded
+  key**. Network and enclaves come from `.env` (`BLOCKCHAIN_NETWORK`,
+  `PROJECT_NAME`, `TRUSTED_ZONE_IMAGE`), overridable with
+  `--network`/`--securelock`/`--trustedzone`; the signing key is `PRIVATE_KEY`
+  (or `ECLD_PRIVATE_KEY`) — a funded `0x` key that pays for the order. Resources
+  are tunable with `--task-price`/`--cpu`/`--memory`/`--storage`/`--bandwidth`/`--duration`/`--validators`.
+  Exit code 0 on a `SUCCESS` task result, 1 otherwise.
+
+- **Inspect (read-only)**: To read enclave and on-chain diagnostics — network,
+  trustedzone/securelock registration, and ESR state — without spending gas, run:
+  ```sh
+  npx ecld-info
+  npx ecld-info esr state <key>
   ```
-  command to start the demo application and test the integration.
 
 ## Project Structure
 

package/nodenithy/build/securelock/src/ecld_state.js

@@ -50,6 +50,16 @@ let _bucket = null;
 let _contractAddress = null;
 let _provider = null;
 
+// LOCAL TESTING ONLY (esr_local). In the real enclave these stay null: the node
+// applies commitFor on-chain and _contract() builds a real ethers.Contract. The
+// local ESR emulator overrides the "contract" with an in-memory object and
+// applies commits itself, so ecld-test runs state-using backends with no chain.
+let _contractOverride = null;
+let _localCommitApply = null;
+
+function setContractOverride(obj) { _contractOverride = obj; }
+function setLocalCommitApply(fn) { _localCommitApply = fn; }
+
 /**
  * Wire the registry to the enclave's identity, storage and chain access.
  * Called by securelock at task start; payload code never calls this.
@@ -329,6 +339,8 @@ class StateRegistry {
   }
 
   _contract(signerOrProvider) {
+    // Local emulator: use the in-memory contract object instead of a real one.
+    if (_contractOverride) return _contractOverride;
     return new ethers.Contract(_contractAddress, ESR_ABI, signerOrProvider || _provider);
   }
 
@@ -515,6 +527,14 @@ class StateRegistry {
     await _swift.putFileContent(
       _bucket, `esr.commit.${Number(relayNonce)}.json`, '',
       Buffer.from(JSON.stringify(auth), 'utf8'));
+
+    // LOCAL TESTING: with no node to relay commitFor, apply the commit to the
+    // in-memory registry now so getState/getVersion reflect it. No-op in the
+    // real enclave (hook is null) -- there the node applies it on-chain.
+    if (_localCommitApply) {
+      await _localCommitApply(enclave, keyHashHex, cid, Number(expectedVersion));
+    }
+
     return { relayed: true, relayNonce: Number(relayNonce) };
   }
 }
@@ -600,6 +620,8 @@ async function esrAcl(key) {
   return { ...acl };
 }
 
+function setTaskCaller(caller) { _taskCaller = normAddr(caller); }
+
 module.exports = {
   StateRegistry,
   configure,
@@ -607,6 +629,7 @@ module.exports = {
   looksLikeCID,
   ledgerSnapshot,
   taskCaller,
+  setTaskCaller,
   restampLedgerCaller,
   StatePermissionError,
   esrGrant,
@@ -614,5 +637,9 @@ module.exports = {
   esrSetPublicRead,
   esrTransfer,
   esrOwner,
-  esrAcl
+  esrAcl,
+  // local-testing hooks (esr_local only)
+  setContractOverride,
+  setLocalCommitApply,
+  normAddr
 };

package/nodenithy/build/securelock/src/esr_local.js

@@ -0,0 +1,161 @@
+/**
+ * Local ESR emulator for `ecld-test` -- run state-using backends with no chain.
+ *
+ * In-memory stand-ins for the two external things StateRegistry talks to, so
+ * get/commit/esrGrant/... behave EXACTLY as on-chain but in-process, instantly,
+ * with zero orders and zero gas:
+ *
+ *   MemSwift    -- state-blob store (replaces SwiftStream): putFileContent /
+ *                  getFileContentBytes over a Map, optionally mirrored to a JSON
+ *                  file so state survives across `ecld-test` runs.
+ *   MemContract -- the ESR contract methods StateRegistry calls
+ *                  (getState / getVersion / relayNonce / commitDigest) plus the
+ *                  commit APPLY the node would do on-chain, keyed by
+ *                  (enclave, keyHash) -> { cid, version }.
+ *
+ * install(ecldState, { caller, filePrefix }) wires these into ecld_state via its
+ * local-testing hooks. Used only by the local test harness; the real enclave
+ * never requires this file.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const { ethers } = require('ethers');
+
+function key(enclave, keyHash) {
+  return `${String(enclave).toLowerCase()}|${String(keyHash).toLowerCase()}`;
+}
+
+class MemSwift {
+  constructor(file) {
+    this._file = file || null;
+    this._store = new Map();
+    if (this._file && fs.existsSync(this._file)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(this._file, 'utf8'));
+        for (const [k, v] of Object.entries(raw)) this._store.set(k, Buffer.from(v, 'base64'));
+      } catch (e) { /* start empty */ }
+    }
+  }
+
+  _persist() {
+    if (!this._file) return;
+    try {
+      const obj = {};
+      for (const [k, v] of this._store) obj[k] = Buffer.from(v).toString('base64');
+      fs.writeFileSync(this._file + '.tmp', JSON.stringify(obj));
+      fs.renameSync(this._file + '.tmp', this._file);
+    } catch (e) { /* best-effort */ }
+  }
+
+  async putFileContent(bucket, name, _prefix, data) {
+    const buf = Buffer.isBuffer(data) ? data
+      : (typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data));
+    this._store.set(`${bucket}/${name}`, buf);
+    this._persist();
+    return true;
+  }
+
+  async getFileContentBytes(bucket, name) {
+    const v = this._store.get(`${bucket}/${name}`);
+    return v === undefined ? null : v;
+  }
+
+  async getFileContent(bucket, name) {
+    const v = await this.getFileContentBytes(bucket, name);
+    return v === null ? null : v.toString('utf8');
+  }
+
+  async createBucket() { return true; }
+}
+
+class MemContract {
+  constructor(file) {
+    this._file = file || null;
+    this._entries = {};   // key -> { cid, version, updatedAt }
+    this._nonce = {};     // enclave -> n
+    if (this._file && fs.existsSync(this._file)) {
+      try {
+        const d = JSON.parse(fs.readFileSync(this._file, 'utf8'));
+        this._entries = d.entries || {};
+        this._nonce = d.nonce || {};
+      } catch (e) { /* start empty */ }
+    }
+  }
+
+  _persist() {
+    if (!this._file) return;
+    try {
+      fs.writeFileSync(this._file + '.tmp', JSON.stringify({ entries: this._entries, nonce: this._nonce }));
+      fs.renameSync(this._file + '.tmp', this._file);
+    } catch (e) { /* best-effort */ }
+  }
+
+  // ---- the ethers.Contract methods StateRegistry calls ----
+  async getState(enclave, keyHash) {
+    const e = this._entries[key(enclave, keyHash)];
+    if (!e) return ['', ethers.BigNumber.from(0), ethers.BigNumber.from(0)];
+    return [e.cid, ethers.BigNumber.from(e.version), ethers.BigNumber.from(e.updatedAt || 0)];
+  }
+
+  async getVersion(enclave, keyHash) {
+    const e = this._entries[key(enclave, keyHash)];
+    return ethers.BigNumber.from(e ? e.version : 0);
+  }
+
+  async relayNonce(enclave) {
+    return ethers.BigNumber.from(this._nonce[String(enclave).toLowerCase()] || 0);
+  }
+
+  async commitDigest(enclave, keyHash, cid, expectedVersion, relayNonce) {
+    // Deterministic 32-byte digest (no real signing needed locally; the
+    // securelock still signs it with the local test key).
+    return ethers.utils.id(JSON.stringify([String(enclave).toLowerCase(), keyHash, cid,
+      Number(expectedVersion), Number(relayNonce)]));
+  }
+
+  async entryCount() {
+    return ethers.BigNumber.from(Object.keys(this._entries).length);
+  }
+
+  // ---- the on-chain commitFor, applied locally ----
+  applyCommit(enclave, keyHash, cid, expectedVersion) {
+    const k = key(enclave, keyHash);
+    const cur = this._entries[k] ? Number(this._entries[k].version) : 0;
+    if (Number(expectedVersion) !== cur) {
+      throw new Error(`VersionMismatch: expected ${expectedVersion} but current is ${cur}`);
+    }
+    this._entries[k] = { cid, version: cur + 1, updatedAt: 0 };
+    const e = String(enclave).toLowerCase();
+    this._nonce[e] = (this._nonce[e] || 0) + 1;
+    this._persist();
+  }
+}
+
+// A fixed local test identity so walletAddress is stable across runs.
+const LOCAL_IDENTITY = Buffer.from('ecld-local-test-identity-key-0001');
+
+function install(ecldState, { caller = null, filePrefix = '.ecld-esr-local' } = {}) {
+  const swiftFile = filePrefix ? `${filePrefix}.swift.json` : null;
+  const regFile = filePrefix ? `${filePrefix}.registry.json` : null;
+  const swift = new MemSwift(swiftFile);
+  const contract = new MemContract(regFile);
+
+  ecldState.configure({
+    identityPriv: LOCAL_IDENTITY,
+    swiftStreamService: swift,
+    bucket: 'ecld-local',
+    contractAddress: '0xLOCAL',
+    provider: null,
+    caller,
+  });
+  ecldState.setContractOverride(contract);
+  ecldState.setLocalCommitApply(
+    (enclave, keyHash, cid, expectedVersion) =>
+      contract.applyCommit(enclave, keyHash, cid, expectedVersion));
+
+  return { swift, contract };
+}
+
+module.exports = { install, MemSwift, MemContract };

package/nodenithy/build/securelock/src/etny_exec.js

@@ -121,7 +121,7 @@ function emptyRequiredConfig() {
     );
 }
 
-function executeTask(payload, input) {
+async function executeTask(payload, input) {
     const missing = emptyRequiredConfig();
     if (missing.length) {
         return [
@@ -161,7 +161,7 @@ function executeTask(payload, input) {
     return exec(payload, input, scope);
 }
 
-function exec(payload, input, globals = null) {
+async function exec(payload, input, globals = null) {
     try {
         if (payload && payload !== "") {
             const scope = globals || {};
@@ -172,7 +172,12 @@ function exec(payload, input, globals = null) {
             // the payload by bare name — matching how payloads are written
             // (e.g. `processData(___etny_data_set___)`).
             with (scope) {
-                const value = eval(payload);
+                // ESR reads/commits are async, so a state-using payload
+                // (`esrIncrement()`, `await reg.commit(...)`) evaluates to a
+                // Promise. Await it so the finished value -- not the pending
+                // Promise -- is what gets wrapped. Non-async payloads await to
+                // themselves, so this is transparent for plain results.
+                const value = await eval(payload);
                 // A payload that called ecldResult/___etny_result___ itself
                 // already holds the finished [0, envelopeJson] tuple -- pass
                 // it through instead of wrapping the result a second time.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@ethernity-cloud/sdk-js",
-  "version": "1.5.9",
+  "version": "1.5.11",
   "description": "A package to run ethernity cloud build scripts",
   "scripts": {
     "ecld-build": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/build.js",
     "ecld-publish": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/publish.js",
     "ecld-init": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/init.js",
-    "ecld-run": "cross-env ecld-run",
+    "ecld-run": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/run.js",
     "postinstall": "node postinstall.js",
     "ecld-test": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/test.js",
     "ecld-info": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/info.js"
@@ -17,7 +17,8 @@
     "ecld-init": "./init.js",
     "postinstall": "./postinstall.js",
     "ecld-test": "./test.js",
-    "ecld-info": "./info.js"
+    "ecld-info": "./info.js",
+    "ecld-run": "./run.js"
   },
   "files": [
     "nodenithy/*",
@@ -25,28 +26,31 @@
     "build.js",
     "init.js",
     "publish.js",
-    "postinstall.js"
+    "postinstall.js",
+    "test.js",
+    "info.js",
+    "run.js"
   ],
   "dependencies": {
-    "@ethernity-cloud/runner": "^0.0.26",
+    "@ethernity-cloud/runner": "^0.4.4",
+    "acorn": "^8.11.0",
+    "adm-zip": "^0.5.14",
     "axios": "^1.7.2",
+    "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
+    "cross-env": "^7.0.3",
     "dotenv": "^16.4.5",
     "eth-lib": "^0.1.29",
     "ethers": "^5.5.4",
     "kubo-rpc-client": "^4.1.1",
-    "web3": "^4.9.0",
-    "cross-env": "^7.0.3",
-    "shelljs": "^0.8.5",
-    "shx": "^0.3.4",
     "node-forge": "^1.3.1",
-    "cli-progress": "^3.12.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-scripts": "^5.0.1",
+    "shelljs": "^0.8.5",
+    "shx": "^0.3.4",
     "web-vitals": "^2.1.4",
-    "adm-zip": "^0.5.14",
-    "acorn": "^8.11.0"
+    "web3": "^4.9.0"
   },
   "author": "Alexandru Luca",
   "license": "AGPL-3.0"

package/run.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/* ecld-run — submit a payload to the Ethernity Cloud network and print the result.
+ *
+ * The network-side sibling of `ecld-test`: same payload flags (a code string,
+ * --file, --input/--input-text), but instead of executing locally it drives the
+ * real runner (@ethernity-cloud/runner's EthernityCloudRunner) end to end —
+ * encrypt the payload, push to IPFS, place the on-chain DO request, wait for a
+ * node to process it, download and decrypt the result.
+ *
+ * Where ecld-test answers "does my CALL work?", ecld-run answers "does it work
+ * on the network, on the enclave I published?" — it costs gas and needs a
+ * funded key.
+ *
+ * Network and enclave come from the project's .env (written by ecld-init /
+ * ecld-publish), matching how ethernity_task drives a run:
+ *
+ *   BLOCKCHAIN_NETWORK   e.g. "Bloxberg_Testnet" -> the network token address
+ *   PROJECT_NAME         the securelock enclave to run
+ *   TRUSTED_ZONE_IMAGE   the trustedzone enclave
+ *   PRIVATE_KEY          a funded 0x key — it pays for the order
+ *
+ * Usage, from the project root:
+ *
+ *   npx ecld-run 'hello("World")'
+ *   npx ecld-run --file payload.js
+ *   npx ecld-run --input data.json 'processData(___etny_data_set___)'
+ *   npx ecld-run --network BLOXBERG_TESTNET --task-price 3 'esrIncrement()'
+ *   npx ecld-run --json 'hello("World")'      # machine-readable result
+ *
+ * The runner is ESM; this CJS entry loads it with dynamic import().
+ *
+ * Exit code 0 on a SUCCESS task result, 1 otherwise.
+ */
+
+'use strict';
+
+const fs = require('fs');
+try { require('dotenv').config(); } catch (e) { /* dotenv optional */ }
+
+const DEFAULT_IPFS = 'https://ipfs.ethernity.cloud/api/v0';
+
+/* Map a BLOCKCHAIN_NETWORK token (as ecld-init writes it, spaces -> underscores)
+ * to the runner's network token ADDRESS. Built from the runner's own ECAddress
+ * so it can't drift. Accepts a few spellings per network. */
+function networkAddress(ECAddress, raw) {
+  const key = String(raw || '').trim().toUpperCase().replace(/\s+/g, '_');
+  const table = {
+    BLOXBERG_TESTNET: ECAddress.BLOXBERG.TESTNET_ADDRESS,
+    BLOXBERG_MAINNET: ECAddress.BLOXBERG.MAINNET_ADDRESS,
+    POLYGON_MAINNET: ECAddress.POLYGON.MAINNET_ADDRESS,
+    POLYGON_AMOY: ECAddress.POLYGON.TESTNET_ADDRESS,
+    POLYGON_AMOY_TESTNET: ECAddress.POLYGON.TESTNET_ADDRESS,
+    IOTEX_TESTNET: ECAddress.IOTEX && ECAddress.IOTEX.TESTNET_ADDRESS,
+    ETHEREUM_SEPOLIA: ECAddress.SEPOLIA && ECAddress.SEPOLIA.TESTNET_ADDRESS,
+    SEPOLIA: ECAddress.SEPOLIA && ECAddress.SEPOLIA.TESTNET_ADDRESS,
+    LITVM_LITEFORGE: ECAddress.LITVM && ECAddress.LITVM.TESTNET_ADDRESS,
+    LITVM: ECAddress.LITVM && ECAddress.LITVM.TESTNET_ADDRESS,
+  };
+  return { key, address: table[key] || null, known: Object.keys(table) };
+}
+
+function parseArgs(argv) {
+  const opts = { ipfs: DEFAULT_IPFS, timeout: 600, taskPrice: 3, cpu: 1, memory: 1, storage: 10, bandwidth: 1, duration: 1, validators: 1, node: '' };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--file' || a === '-f') opts.file = argv[++i];
+    else if (a === '--input' || a === '-i') opts.inputFile = argv[++i];
+    else if (a === '--input-text') opts.inputText = argv[++i];
+    else if (a === '--network') opts.network = argv[++i];
+    else if (a === '--securelock') opts.securelock = argv[++i];
+    else if (a === '--trustedzone') opts.trustedzone = argv[++i];
+    else if (a === '--node') opts.node = argv[++i];
+    else if (a === '--ipfs') opts.ipfs = argv[++i];
+    else if (a === '--timeout') opts.timeout = parseInt(argv[++i], 10);
+    else if (a === '--task-price') opts.taskPrice = parseInt(argv[++i], 10);
+    else if (a === '--cpu') opts.cpu = parseInt(argv[++i], 10);
+    else if (a === '--memory') opts.memory = parseInt(argv[++i], 10);
+    else if (a === '--storage') opts.storage = parseInt(argv[++i], 10);
+    else if (a === '--bandwidth') opts.bandwidth = parseInt(argv[++i], 10);
+    else if (a === '--duration') opts.duration = parseInt(argv[++i], 10);
+    else if (a === '--validators') opts.validators = parseInt(argv[++i], 10);
+    else if (a === '--json') opts.json = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else positional.push(a);
+  }
+  return { opts, positional };
+}
+
+const HELP = `ecld-run — submit a payload to the Ethernity Cloud network (costs gas; needs a funded key).
+Local sibling: ecld-test.
+
+usage: ecld-run 'hello("World")' | ecld-run --file payload.js | ecld-run --input data.json 'fn(___etny_data_set___)'
+
+payload:   a code string, or --file <path>; input via --input <file> / --input-text <str>
+network:   --network BLOXBERG_TESTNET (default: BLOCKCHAIN_NETWORK from .env)
+enclaves:  --securelock <name> (default PROJECT_NAME), --trustedzone <name> (default TRUSTED_ZONE_IMAGE)
+key:       PRIVATE_KEY (a funded 0x key) from .env / env, or ECLD_PRIVATE_KEY
+resources: --task-price 3 --cpu 1 --memory 1 --storage 10 --bandwidth 1 --duration 1 --validators 1
+other:     --node <addr>  --ipfs <url>  --timeout <sec>  --json`;
+
+async function main() {
+  const { opts, positional } = parseArgs(process.argv.slice(2));
+  if (opts.help) { console.log(HELP); process.exit(0); }
+
+  // ---- payload ----
+  let code;
+  if (opts.file) code = fs.readFileSync(opts.file, 'utf8');
+  else if (positional.length) code = positional.join(' ');
+  else if ((process.env.ECLD_TEST_CODE || '').trim()) code = process.env.ECLD_TEST_CODE.trim();
+  else { console.error("ecld-run: provide a payload string, --file, or ECLD_TEST_CODE\n\n" + HELP); process.exit(2); }
+
+  if (opts.inputFile !== undefined && opts.inputText !== undefined) {
+    console.error('ecld-run: --input and --input-text are mutually exclusive'); process.exit(2);
+  }
+  let input = null;
+  if (opts.inputFile !== undefined) input = fs.readFileSync(opts.inputFile, 'utf8');
+  else if (opts.inputText !== undefined) input = opts.inputText;
+  // The enclave executor exposes the input as ___etny_data_set___; the runner
+  // passes it as part of the code's scope, so a payload references it by name.
+  // ecld-run mirrors ecld-test: input is delivered via the payload call itself.
+
+  // ---- runner (ESM) ----
+  let EthernityCloudRunner, ECStatus, ECEvent, ECAddress, ECOrderTaskStatus;
+  try {
+    const runnerMod = await import('@ethernity-cloud/runner');
+    EthernityCloudRunner = runnerMod.default || runnerMod.EthernityCloudRunner;
+    const enums = await import('@ethernity-cloud/runner/enums.js');
+    ({ ECStatus, ECEvent, ECAddress, ECOrderTaskStatus } = enums);
+  } catch (e) {
+    console.error('ecld-run: the runner package is not installed or is too old '
+      + '(need @ethernity-cloud/runner >= 0.4.4): ' + e.message);
+    process.exit(1);
+  }
+
+  // ---- network / enclaves / key ----
+  const rawNetwork = opts.network || process.env.BLOCKCHAIN_NETWORK || 'BLOXBERG_TESTNET';
+  const { key: netKey, address, known } = networkAddress(ECAddress, rawNetwork);
+  if (!address) {
+    console.error(`ecld-run: unknown network '${rawNetwork}'. Known: ${known.join(', ')}`);
+    process.exit(1);
+  }
+  const securelock = opts.securelock || process.env.PROJECT_NAME;
+  const trustedzone = opts.trustedzone || process.env.TRUSTED_ZONE_IMAGE;  // may be undefined -> run() default
+  if (!securelock) {
+    console.error('ecld-run: no securelock enclave: set PROJECT_NAME in .env '
+      + '(run ecld-init/ecld-publish) or pass --securelock.');
+    process.exit(1);
+  }
+
+  let privateKey = (process.env.PRIVATE_KEY || process.env.ECLD_PRIVATE_KEY || '').trim();
+  if (!privateKey) {
+    console.error('ecld-run: no signing key. Set PRIVATE_KEY (a funded 0x key) in .env '
+      + '(ecld-publish stores it) or ECLD_PRIVATE_KEY.');
+    process.exit(1);
+  }
+  if (!privateKey.startsWith('0x')) privateKey = '0x' + privateKey;
+
+  console.log(`network    : ${netKey} (${address})`);
+  console.log(`securelock : ${securelock}`);
+  console.log(`trustedzone: ${trustedzone || '(runner default)'}`);
+  console.log(`payload    : ${JSON.stringify(code)}`);
+  console.log(`input      : ${input === null ? '<empty>' : JSON.stringify(input.slice(0, 80))}`);
+
+  // ---- drive the runner ----
+  let runner;
+  try {
+    runner = new EthernityCloudRunner(address, { privateKey });
+  } catch (e) {
+    console.error('ecld-run: could not initialise the runner: ' + e.message);
+    process.exit(1);
+  }
+  runner.initializeStorage(opts.ipfs);
+
+  let lastPhase = null;
+  const onProgress = (e) => {
+    const d = (e && e.detail) || {};
+    if (d.progress !== lastPhase) { lastPhase = d.progress; console.log(`[${d.progress}] ${d.message}`); }
+    else if (d.message) console.log(`          ${d.message}`);
+  };
+  runner.addEventListener(ECStatus.DEFAULT, onProgress);
+
+  const resources = {
+    taskPrice: opts.taskPrice, cpu: opts.cpu, memory: opts.memory,
+    storage: opts.storage, bandwidth: opts.bandwidth, duration: opts.duration, validators: opts.validators,
+  };
+  console.log(`resources  : ${JSON.stringify(resources)}`);
+  console.log('submitting order... (this places an on-chain request and costs gas)');
+
+  const done = new Promise((resolve) => {
+    runner.addEventListener(ECStatus.SUCCESS, () => resolve('SUCCESS'));
+    runner.addEventListener(ECStatus.ERROR, (e) => {
+      const msg = (e && e.detail && e.detail.message) || 'unknown error';
+      resolve({ error: msg });
+    });
+  });
+
+  // run() resolves when the task terminates; the events resolve `done`. Race a
+  // timeout so a stuck order doesn't hang the CLI forever.
+  const timeoutMs = (opts.timeout || 600) * 1000;
+  let timer;
+  const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve('TIMEOUT'), timeoutMs); });
+
+  try {
+    const runArgs = [resources, securelock, code, opts.node];
+    if (trustedzone) runArgs.push(trustedzone);
+    // Fire the run; its own promise also settles on completion.
+    const runPromise = runner.run(...runArgs).catch((e) => ({ error: e.message }));
+    const outcome = await Promise.race([done, timeout, runPromise]);
+    clearTimeout(timer);
+
+    if (outcome === 'TIMEOUT') {
+      console.error(`\necld-run: no result after ${opts.timeout}s; the order may still process on-chain.`);
+      process.exit(1);
+    }
+    if (outcome && outcome.error) {
+      console.error(`\nstatus     : ERROR`);
+      console.error(`error      : ${outcome.error}`);
+      process.exit(1);
+    }
+
+    // SUCCESS
+    const result = await runner.getResult();
+    const typed = (runner.getStructuredResult && runner.getStructuredResult()) || null;
+    const taskCode = runner.resultTaskCode;
+    const taskName = runner.resultTaskCodeName
+      || (ECOrderTaskStatus && taskCode !== undefined ? ECOrderTaskStatus[taskCode] : undefined);
+
+    if (opts.json) {
+      console.log(JSON.stringify({ task_code: taskCode, task_code_name: taskName, value: result, structured: typed }, null, 2));
+    } else {
+      if (taskName && taskName !== 'SUCCESS') console.log(`task code  : ${taskCode} (${taskName})`);
+      console.log('result     :');
+      console.log(result);
+    }
+    // A non-zero enclave task code is a failed run even though the order landed.
+    process.exit(taskCode === undefined || taskCode === 0 ? 0 : 1);
+  } catch (e) {
+    clearTimeout(timer);
+    console.error('ecld-run: run failed: ' + (e && e.stack ? e.stack : e));
+    process.exit(1);
+  }
+}
+
+main().catch((e) => { console.error(e && e.stack ? e.stack : String(e)); process.exit(1); });

package/test.js

@@ -24,6 +24,14 @@
  * @ethernity-cloud/runner >= 0.3.6 executes every run() against this API
  * instead of the blockchain.
  *
+ * ESR (Enclave State Registry) is emulated locally and ON by default: a
+ * state-using backend -- `require('../ecld_state').StateRegistry`, get/commit,
+ * the ownership/ACL API -- runs fully in-process against an in-memory registry
+ * + store, with no chain, node, or SGX. State persists between runs in
+ * .ecld-esr-local.*.json so a counter advances exactly as it would on-chain.
+ * The task caller (the DO owner the trustedzone attests) defaults to your
+ * developer address and is set for every task; override with --caller.
+ *
  * Exit code 0 on TaskStatus SUCCESS, 1 otherwise.
  */
 
@@ -32,6 +40,7 @@ const os = require('os');
 const path = require('path');
 const http = require('http');
 const crypto = require('crypto');
+const { ethers } = require('ethers');
 
 const TASK_STATUS_NAMES = {
   0: 'SUCCESS',
@@ -62,10 +71,21 @@ function copyDir(src, dest) {
 /* Stage the executor + the project's backend the way ecld-build does inside
  * the enclave image, then load the REAL executor from the staged copy. */
 function loadExecutor(projectSrc) {
-  const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'ecld-test-'));
-  for (const f of ['etny_exec.js', 'task_status.js']) {
-    fs.copyFileSync(path.join(VENDORED_SRC, f), path.join(stage, f));
+  // Stage INSIDE the SDK tree (not the OS temp dir) so the executor's
+  // `require('ethers')` and other runtime deps resolve by walking up to the
+  // SDK's own node_modules -- exactly what binary-fs gives the enclave.
+  const stageRoot = path.join(VENDORED_SRC, '..', '.ecld-test-stage');
+  fs.mkdirSync(stageRoot, { recursive: true });
+  const stage = fs.mkdtempSync(path.join(stageRoot, 'run-'));
+  const cleanup = () => { try { fs.rmSync(stage, { recursive: true, force: true }); } catch (e) {} };
+  process.on('exit', cleanup);
+  // `serve` runs until interrupted -- clean the stage on Ctrl-C / kill too.
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(sig, () => { cleanup(); process.exit(130); });
   }
+  // Stage the ENTIRE vendored securelock src so `require('./ecld_state')`,
+  // esr_local, and their deps all resolve, exactly as inside the enclave image.
+  copyDir(VENDORED_SRC, stage);
   const backendDir = path.join(projectSrc, 'serverless');
   const backendJs = path.join(backendDir, 'backend.js');
   if (fs.existsSync(backendJs)) {
@@ -78,11 +98,56 @@ function loadExecutor(projectSrc) {
   } else {
     console.log('backend : none found — running with bare globals, like a stock enclave');
   }
-  return require(path.join(stage, 'etny_exec.js'));
+  const executor = require(path.join(stage, 'etny_exec.js'));
+  executor.__stageDir = stage;
+  return executor;
+}
+
+/* The task caller for local runs -- the DEVELOPER'S address, mirroring the
+ * trustedzone-attested DO owner the real securelock receives. Resolution:
+ *   1. --caller / ECLD_TEST_CALLER
+ *   (a) WALLET_ADDRESS in .env (written at publish time)
+ *   (b) derive from ECLD_PRIVATE_KEY
+ *   else DEFAULT_TEST_CALLER (a well-known dev address). */
+const DEFAULT_TEST_CALLER = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+
+function resolveCaller(explicit) {
+  const chosen = explicit || process.env.ECLD_TEST_CALLER;
+  if (chosen) return chosen.trim();
+  if (process.env.WALLET_ADDRESS) return process.env.WALLET_ADDRESS.trim();     // (a)
+  const pk = process.env.ECLD_PRIVATE_KEY;                                       // (b)
+  if (pk) {
+    try { return new ethers.Wallet(pk.startsWith('0x') ? pk : '0x' + pk).address; }
+    catch (e) { /* fall through */ }
+  }
+  console.log(`[ecld-test] no developer address configured; using default test caller `
+    + `${DEFAULT_TEST_CALLER} (set ECLD_TEST_CALLER or WALLET_ADDRESS)`);
+  return DEFAULT_TEST_CALLER;
+}
+
+/* Install the local ESR emulator + set the task caller (ON by default). */
+function installEsr(executor, caller) {
+  try {
+    const stage = executor.__stageDir;
+    const ecldState = require(path.join(stage, 'ecld_state.js'));
+    const esrLocal = require(path.join(stage, 'esr_local.js'));
+    esrLocal.install(ecldState, { caller, filePrefix: '.ecld-esr-local' });
+    return { ecldState };
+  } catch (e) {
+    console.log(`esr     : emulation unavailable (${e.message})`);
+    return null;
+  }
 }
 
-function runTask(executor, payload, input) {
-  const [code, resultRaw] = executor.executeTask(payload, input || '');
+async function runTask(executor, payload, input, esr, caller) {
+  // Set the task caller EXACTLY as the real securelock does after the
+  // trustedzone hands it the DO owner -- for every task, ESR or not.
+  if (esr && esr.ecldState) {
+    try { esr.ecldState.setTaskCaller(caller || null); } catch (e) { /* ignore */ }
+  }
+  // executeTask is async (ESR reads/commits await); the real securelock awaits
+  // it too (securelock.js: `await executeTask(...)`).
+  const [code, resultRaw] = await executor.executeTask(payload, input || '');
   const result = typeof resultRaw === 'string' ? resultRaw : JSON.stringify(resultRaw);
   const checksum = crypto.createHash('sha256').update(result, 'utf8').digest('hex');
   const challenge = Array.from({ length: 20 }, () =>
@@ -98,7 +163,7 @@ function runTask(executor, payload, input) {
   };
 }
 
-function serve(executor, host, port) {
+function serve(executor, host, port, esr, defaultCaller) {
   const server = http.createServer((req, res) => {
     const send = (status, obj) => {
       const body = JSON.stringify(obj);
@@ -128,9 +193,13 @@ function serve(executor, host, port) {
           if (input !== undefined && input !== null && typeof input !== 'string') {
             input = JSON.stringify(input);
           }
-          const out = runTask(executor, body.payload, input);
-          console.log(`[local-api] task -> ${out.task_code} (${out.task_code_name})`);
-          return send(200, out);
+          const caller = body.caller !== undefined ? body.caller : defaultCaller;
+          runTask(executor, body.payload, input, esr, caller)
+            .then((out) => {
+              console.log(`[local-api] task -> ${out.task_code} (${out.task_code_name})`);
+              send(200, out);
+            })
+            .catch((e) => send(500, { error: e.message }));
         } catch (e) {
           if (e instanceof SyntaxError) return send(400, { error: 'invalid JSON body' });
           return send(500, { error: e.message });
@@ -145,7 +214,7 @@ function serve(executor, host, port) {
   });
 }
 
-function main() {
+async function main() {
   const argv = process.argv.slice(2);
   const opts = { src: 'src', host: '127.0.0.1', port: 8745 };
   const positional = [];
@@ -157,6 +226,7 @@ function main() {
     else if (a === '--src') opts.src = argv[++i];
     else if (a === '--host') opts.host = argv[++i];
     else if (a === '--port') opts.port = parseInt(argv[++i], 10);
+    else if (a === '--caller') opts.caller = argv[++i];
     else positional.push(a);
   }
 
@@ -169,8 +239,16 @@ function main() {
     serve.backendFunctions = [];
   }
 
+  // ESR emulation ON by default so a state-using backend runs locally exactly
+  // as in an ESR-enabled enclave (no chain/node/SGX). Caller (default: your dev
+  // address) is set for every task, so taskCaller() and the ACL behave as
+  // on-chain.
+  const caller = resolveCaller(opts.caller);
+  const esr = installEsr(executor, caller);
+  if (esr) console.log(`esr     : local emulation ON   caller ${caller}`);
+
   if (positional[0] === 'serve') {
-    return serve(executor, opts.host, opts.port);
+    return serve(executor, opts.host, opts.port, esr, caller);
   }
 
   let payload;
@@ -191,7 +269,7 @@ function main() {
 
   console.log(`payload : ${JSON.stringify(payload)}`);
   console.log(`input   : ${input === null ? '<empty>' : JSON.stringify(input.slice(0, 80))}`);
-  const out = runTask(executor, payload, input);
+  const out = await runTask(executor, payload, input, esr, caller);
   console.log(`task code: ${out.task_code} (${out.task_code_name})`);
   console.log(`result   : ${JSON.stringify(out.result)}`);
   if (out.task_code !== 0) {
@@ -201,4 +279,4 @@ function main() {
   process.exit(out.task_code === 0 ? 0 : 1);
 }
 
-main();
+main().catch((e) => { console.error(e && e.stack ? e.stack : String(e)); process.exit(1); });