@ethernity-cloud/sdk-js 1.5.9 → 1.5.12

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.
@@ -91,6 +101,11 @@ const CONTAINER_MARK = '_ecld_state';
 
 class StatePermissionError extends Error {}
 
+// A commit's idempotency nonce was already used: the dApp supplied `nonce` on
+// commit() and it is not greater than the last accepted nonce for the key --
+// a duplicate (or out-of-order) submission. The state was NOT changed.
+class StateNonceError extends Error {}
+
 function unwrapStored(stored) {
   if (stored && typeof stored === 'object' && stored[CONTAINER_MARK] === 1) {
     return [stored.acl || null, stored.data];
@@ -98,13 +113,25 @@ function unwrapStored(stored) {
   return [null, stored];
 }
 
-function wrapStored(acl, data, committedBy = null) {
+/** Last accepted idempotency nonce carried by a stored blob (0 if none). */
+function storedNonce(stored) {
+  if (stored && typeof stored === 'object' && stored[CONTAINER_MARK] === 1) {
+    const n = parseInt(stored.nonce, 10);
+    return Number.isFinite(n) ? n : 0;
+  }
+  return 0;
+}
+
+function wrapStored(acl, data, committedBy = null, nonce = null) {
   // For owned state, bind the authoring caller (committedBy) INTO the blob, so
   // it lands in the CID -- the field the securelock signs -- making the caller
   // cryptographically bound to the commit, not merely a re-stampable sidecar.
-  if (!acl) return data;                 // unowned keeps the legacy shape
-  const container = { [CONTAINER_MARK]: 1, acl, data };
+  // Unowned state keeps the legacy bare shape -- unless a nonce must be
+  // carried, which forces the container so the nonce survives in the blob.
+  if (!acl && nonce == null) return data;
+  const container = { [CONTAINER_MARK]: 1, acl: acl || null, data };
   if (committedBy) container.committedBy = committedBy;
+  if (nonce != null) container.nonce = Math.trunc(nonce);
   return container;
 }
 
@@ -318,6 +345,15 @@ class StateRegistry {
     return esr_wallet.deriveWalletAddress(_identityPriv);
   }
 
+  /**
+   * Alias of walletAddress — the ENCLAVE's own on-chain address (its identity,
+   * and the namespace all its state keys live under). Preferred name in new
+   * code; walletAddress remains for compatibility.
+   */
+  get enclaveAddress() {
+    return this.walletAddress;
+  }
+
   _signer() {
     // Reuse esr_wallet's derivation rather than repeating it here: two copies
     // would eventually disagree, and the address a client funds would stop
@@ -329,6 +365,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);
   }
 
@@ -356,11 +394,11 @@ class StateRegistry {
     return data;
   }
 
-  /** [acl, data, version, cid] for `key`; NO permission check here. */
+  /** [acl, data, version, cid, nonce] for `key`; NO permission check here. */
   async _readContainer(key, fallback = {}) {
     const [cid, version] = await this._contract().getState(this.walletAddress, keyHash(key));
     if (!version || !cid) {
-      return [null, fallback, 0, null];
+      return [null, fallback, 0, null, 0];
     }
     if (!looksLikeCID(cid)) {
       throw new Error(
@@ -371,7 +409,23 @@ class StateRegistry {
     const blob = await this._fetch(key, cid);
     const stored = JSON.parse(decrypt(blob).toString('utf8'));
     const [acl, data] = unwrapStored(stored);
-    return [acl, data, Number(version), cid];
+    return [acl, data, Number(version), cid, storedNonce(stored)];
+  }
+
+  /**
+   * The last accepted idempotency nonce for `key` (0 if none was ever used).
+   * A dApp that wants duplicate suppression reads this, picks a greater value
+   * (e.g. +1, or a timestamp), and passes it to commit(..., { nonce }).
+   */
+  async getNonce(key) {
+    const [acl, , , , nonce] = await this._readContainer(key);
+    if (!canRead(acl)) {
+      throw new StatePermissionError(
+        `caller ${_taskCaller || '<anonymous>'} has no read permission on ` +
+          `state key '${key}' (owner: ${acl.owner})`
+      );
+    }
+    return nonce;
   }
 
   /**
@@ -381,7 +435,14 @@ class StateRegistry {
    * commit lands in between, the contract rejects ours and we re-read and
    * retry, so concurrent tasks cannot silently lose updates.
    */
-  async commit(key, mutate, attempts = 3) {
+  async commit(key, mutate, opts = 3) {
+    // Back-compat: the third arg used to be `attempts` (a number); it may now
+    // also be { attempts, nonce }. `nonce` is an idempotency guard the dApp
+    // controls: it must be STRICTLY GREATER than the last accepted nonce for
+    // the key (see getNonce). A duplicate or stale nonce throws
+    // StateNonceError and the state is NOT changed.
+    const { attempts = 3, nonce = null } =
+      typeof opts === 'number' ? { attempts: opts } : (opts || {});
     const transform = async (acl, data) => {
       if (!canWrite(acl)) {
         throw new StatePermissionError(
@@ -393,7 +454,7 @@ class StateRegistry {
       if (!nextAcl && _taskCaller) nextAcl = newAcl(_taskCaller); // first-writer-owns
       return [nextAcl, await mutate(data)];
     };
-    const [, newData] = await this._commitTransform(key, transform, attempts);
+    const [, newData] = await this._commitTransform(key, transform, attempts, nonce);
     return newData;
   }
 
@@ -403,16 +464,33 @@ class StateRegistry {
    * data while unowned). On a version race we re-read and retry, so
    * concurrent tasks cannot silently lose updates.
    */
-  async _commitTransform(key, transform, attempts = 3) {
+  async _commitTransform(key, transform, attempts = 3, nonce = null) {
     let lastError = null;
     for (let attempt = 0; attempt < attempts; attempt += 1) {
       // eslint-disable-next-line no-await-in-loop
-      const [acl, data, currentVersion] = await this._readContainer(key);
+      const [acl, data, currentVersion, , priorNonce] = await this._readContainer(key);
+      // The nonce check re-runs on every retry against the freshly read state,
+      // so a racing commit that consumed the same nonce fails this one.
+      let finalNonce;
+      if (nonce != null) {
+        const n = Math.trunc(nonce);
+        if (n <= priorNonce) {
+          throw new StateNonceError(
+            `nonce ${n} was already used for state key '${key}' (last accepted: ` +
+              `${priorNonce}); duplicate commit suppressed, state unchanged`
+          );
+        }
+        finalNonce = n;
+      } else {
+        // Preserve the stored nonce so a nonce-less commit cannot reset the
+        // guard and reopen replays.
+        finalNonce = priorNonce > 0 ? priorNonce : null;
+      }
       // eslint-disable-next-line no-await-in-loop
       const [nextAcl, newData] = await transform(acl, data, currentVersion);
       // Bind the authoring caller into the blob (hence the CID/signature) for
       // owned state.
-      const stored = wrapStored(nextAcl, newData, nextAcl ? _taskCaller : null);
+      const stored = wrapStored(nextAcl, newData, nextAcl ? _taskCaller : null, finalNonce);
 
       const blob = encrypt(Buffer.from(JSON.stringify(stored), 'utf8'));
       // Compute the CID from OUR bytes — never accept one from the node.
@@ -515,6 +593,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 +686,16 @@ async function esrAcl(key) {
   return { ...acl };
 }
 
+function setTaskCaller(caller) { _taskCaller = normAddr(caller); }
+
+/**
+ * The last accepted idempotency nonce for `key` (0 if none). See
+ * StateRegistry.getNonce / commit(key, mutate, { nonce }).
+ */
+async function esrNonce(key) {
+  return new StateRegistry().getNonce(key);
+}
+
 module.exports = {
   StateRegistry,
   configure,
@@ -607,12 +703,19 @@ module.exports = {
   looksLikeCID,
   ledgerSnapshot,
   taskCaller,
+  setTaskCaller,
   restampLedgerCaller,
   StatePermissionError,
+  StateNonceError,
   esrGrant,
   esrRevoke,
   esrSetPublicRead,
   esrTransfer,
   esrOwner,
-  esrAcl
+  esrAcl,
+  esrNonce,
+  // 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 };