@ethernity-cloud/sdk-js 1.5.15 → 1.5.16

package/info.js

@@ -1,324 +1,324 @@
-#!/usr/bin/env node
-/**
- * ecld-info: everything a developer needs to read or troubleshoot an enclave.
- *
- * Read-only and free (eth_call + event logs -- no task, no gas, no private
- * key). Reads your project's identity from .env (PROJECT_NAME / IPFS_HASH /
- * BLOCKCHAIN_NETWORK), then reports:
- *
- *   NETWORK       name, type, chain id, RPC, contract addresses, live block
- *   TRUSTEDZONE   the gatekeeper enclave's Image Registry record
- *   SECURELOCK    the executor enclave's Image Registry record
- *   ESR           registry address, total keys, and -- with --enclave <wallet>
- *                 -- this enclave's recent StateCommitted events
- *
- * Subcommands (default: the full summary):
- *   ecld-info                       full summary
- *   ecld-info network               just the network section
- *   ecld-info trustedzone           just the trustedzone registration
- *   ecld-info securelock            just the securelock registration
- *   ecld-info esr address|count|state|version|nonce|list   ESR inspection
- *
- * Registration is keyed by the image's IPFS hash: pass --ipfs <hash> for an
- * exact record, or --name <n> to resolve the latest registered version of a
- * name. With neither, .env IPFS_HASH / PROJECT_NAME are used.
- *
- * Network: --network NAME, else ESR_NETWORK env, else .env BLOCKCHAIN_NETWORK,
- * else BLOXBERG_TESTNET.
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { ethers } = require('ethers');
-try { require('dotenv').config(); } catch (e) { /* dotenv optional */ }
-
-// Authoritative per-network values (mirror of the Python SDK's network table).
-const NETWORKS = {
-  BLOXBERG_MAINNET: {
-    type: 'mainnet', chainId: 8995, rpc: 'https://core.bloxberg.org',
-    protocol: '0x549A6E06BB2084100148D50F51CF77a3436C3Ae7',
-    imageRegistry: '0x15D73a742529C3fb11f3FA32EF7f0CC3870ACA31',
-    esr: '0xDaFa1e3CAF370765275d853cd86dDEd671Ce29Dd',
-  },
-  BLOXBERG_TESTNET: {
-    type: 'testnet', chainId: 8995, rpc: 'https://core.bloxberg.org',
-    protocol: '0x02882F03097fE8cD31afbdFbB5D72a498B41112c',
-    imageRegistry: '0x15D73a742529C3fb11f3FA32EF7f0CC3870ACA31',
-    esr: '0xD7a7Cb9cbb0Ca1adFb2B8405382f299EA1c6132f',
-  },
-  LITVM_LITEFORGE: {
-    type: 'testnet', chainId: 0, rpc: 'https://liteforge.rpc.caldera.xyz/infra-partner-http',
-    protocol: '', imageRegistry: '', esr: '0x213aA794F29EA717B9226dF81F7317334Ac36169',
-  },
-};
-
-const IMAGE_REGISTRY_ABI = [
-  'function imageDetails(string) view returns (address owner, string ipfsHash, string version, string session, uint256 fee, address rewardAddress, bool validated, bool published, string certPublicKey, string dockerComposeHash, string name)',
-  'function trustedZoneImageDetails(string) view returns (address owner, string ipfsHash, string version, string session, uint256 fee, address rewardAddress, bool validated, bool published, string certPublicKey, string dockerComposeHash, string name)',
-  'function imageVersions(string, uint256) view returns (string)',
-  'function trustedZoneImageVersions(string, uint256) view returns (string)',
-];
-
-const ESR_ABI = [
-  'function getState(address enclave, bytes32 key) view returns (string cid, uint256 version, uint64 updatedAt)',
-  'function getVersion(address enclave, bytes32 key) view returns (uint256)',
-  'function exists(address enclave, bytes32 key) view returns (bool)',
-  // The idempotency nonce is PUBLIC on-chain data, recorded next to the
-  // version and enforced strictly in-order per (enclave, key).
-  'function getNonce(address enclave, bytes32 key) view returns (uint256)',
-  'function entryCount() view returns (uint256)',
-  'function getEntriesFrom(uint256 start, uint256 limit) view returns (address[] enclaves, bytes32[] keys, string[] cids, uint256[] versions, uint64[] updatedAts, uint256 total)',
-  'event StateCommitted(address indexed enclave, bytes32 indexed key, string cid, uint256 version, uint256 seq, uint256 nonce)',
-];
-
-function resolveNetwork(name) {
-  name = (name || process.env.ESR_NETWORK || process.env.BLOCKCHAIN_NETWORK || 'BLOXBERG_TESTNET')
-    .toUpperCase();
-  const net = NETWORKS[name];
-  if (!net) {
-    throw new Error(`Unknown network '${name}'. Known: ${Object.keys(NETWORKS).join(', ')}`);
-  }
-  return { name, net };
-}
-
-function provider(rpc) {
-  return new ethers.providers.JsonRpcProvider(rpc);
-}
-
-function keyHash(key) {
-  return ethers.utils.id(key); // keccak256(utf8(key))
-}
-
-function looksLikeCID(cid) {
-  return typeof cid === 'string' && (cid.startsWith('Qm') || cid.startsWith('bafk')) && cid.length > 20;
-}
-
-function decodeDetails(d, fallbackName) {
-  return {
-    name: d.name || fallbackName,
-    published: Boolean(d.published),
-    validated: Boolean(d.validated),
-    image_ipfs_hash: d.ipfsHash || null,
-    image_version: d.version || null,
-    reward_address: d.rewardAddress,
-    owner: d.owner,
-    docker_compose_hash: d.dockerComposeHash || null,
-    attestation_session: Boolean(d.session),
-    cert_present: Boolean(d.certPublicKey),
-  };
-}
-
-async function lookupRegistration(reg, kind, ipfs, name) {
-  const detailsFn = kind === 'trustedzone' ? 'trustedZoneImageDetails' : 'imageDetails';
-  const versionsFn = kind === 'trustedzone' ? 'trustedZoneImageVersions' : 'imageVersions';
-  if (ipfs) {
-    try { return decodeDetails(await reg[detailsFn](ipfs), ipfs); }
-    catch (e) { return { found: false, error: e.message }; }
-  }
-  if (name) {
-    let latest = null;
-    for (let i = 0; i < 64; i += 1) {
-      let v;
-      try { v = await reg[versionsFn](name, i); } catch (e) { break; }
-      if (!v) break;
-      latest = v;
-    }
-    if (latest) {
-      try { return decodeDetails(await reg[detailsFn](latest), name); }
-      catch (e) { return { found: false, error: e.message }; }
-    }
-    return { found: false, note: `no registered version for name '${name}' -- the Image Registry is keyed by image IPFS hash; pass --ipfs <hash>` };
-  }
-  return { found: false, note: 'no --ipfs or --name to look up' };
-}
-
-async function sectionNetwork(prov, name, net) {
-  const out = {
-    network: name, type: net.type, chain_id: net.chainId, rpc: net.rpc,
-    protocol_contract: net.protocol || '(n/a)',
-    image_registry: net.imageRegistry || '(n/a)',
-    esr_contract: net.esr || '(not deployed)',
-  };
-  try {
-    out.latest_block = await prov.getBlockNumber();
-    out.connected = true;
-  } catch (e) {
-    out.connected = false; out.error = e.message;
-  }
-  return out;
-}
-
-async function sectionRegistration(prov, net, kind, ipfs, name) {
-  if (!net.imageRegistry) return { note: 'no image registry on this network' };
-  const reg = new ethers.Contract(net.imageRegistry, IMAGE_REGISTRY_ABI, prov);
-  return lookupRegistration(reg, kind, ipfs, name);
-}
-
-async function sectionEsr(prov, net, enclaveWallet, eventsN) {
-  if (!net.esr) return { note: 'ESR is not deployed on this network' };
-  const esr = new ethers.Contract(net.esr, ESR_ABI, prov);
-  const out = { esr_contract: net.esr };
-  try { out.total_registry_entries = (await esr.entryCount()).toNumber(); } catch (e) { /* ignore */ }
-  if (enclaveWallet) {
-    try {
-      const latest = await prov.getBlockNumber();
-      const from = Math.max(0, latest - 500000);
-      const flt = esr.filters.StateCommitted(ethers.utils.getAddress(enclaveWallet));
-      let logs = await esr.queryFilter(flt, from, 'latest');
-      logs = logs.slice(-eventsN);
-      out.recent_commits = logs.map((l) => ({
-        key_hash: l.args.key,
-        version: l.args.version.toNumber(),
-        cid: l.args.cid,
-        seq: l.args.seq.toNumber(),
-        // PUBLIC idempotency nonce; 0 = the commit carried no guard.
-        nonce: l.args.nonce.toNumber(),
-        block: l.blockNumber,
-      }));
-    } catch (e) {
-      out.recent_commits_error = e.message;
-    }
-  } else {
-    out.recent_commits_note = 'pass --enclave <ESR wallet> to list this enclave\'s state commits';
-  }
-  return out;
-}
-
-async function esrQuery(prov, name, net, args) {
-  const esrAddr = args.contract || net.esr;
-  const sub = args.esrCmd || 'address';
-  if (sub === 'address') return { network: name, esr_contract: esrAddr || '(not deployed)', rpc: net.rpc };
-  if (!esrAddr) throw new Error(`ESR is not deployed on ${name}.`);
-  const c = new ethers.Contract(esrAddr, ESR_ABI, prov);
-  if (sub === 'count') return { network: name, entry_count: (await c.entryCount()).toNumber() };
-  if (sub === 'version') {
-    const v = (await c.getVersion(ethers.utils.getAddress(args.enclave), keyHash(args.key))).toNumber();
-    return { enclave: args.enclave, key: args.key, version: v };
-  }
-  if (sub === 'nonce') {
-    const n = (await c.getNonce(ethers.utils.getAddress(args.enclave), keyHash(args.key))).toNumber();
-    return {
-      enclave: args.enclave, key: args.key, nonce: n,
-      note: 'last accepted idempotency nonce (PUBLIC data, free eth_call); '
-        + '0 = no guarded commit yet. Pass EXACTLY nonce + 1 to commit() to '
-        + 'guard against duplicates; the contract enforces the sequence '
-        + 'strictly per key (no gaps, no reuse)',
-    };
-  }
-  if (sub === 'state') {
-    const enclave = ethers.utils.getAddress(args.enclave);
-    const kh = keyHash(args.key);
-    const [cid, version, updated] = await c.getState(enclave, kh);
-    const exists = await c.exists(enclave, kh);
-    return {
-      network: name, enclave: args.enclave, key: args.key, key_hash: kh,
-      exists, version: version.toNumber(),
-      // PUBLIC idempotency nonce; 0 = no guarded commit yet.
-      nonce: (await c.getNonce(enclave, kh)).toNumber(),
-      cid: cid || null, cid_valid: looksLikeCID(cid),
-      updated_at: updated.toNumber(),
-      note: 'cid points at ENCRYPTED state; only the enclave can decrypt it',
-    };
-  }
-  if (sub === 'list') {
-    const start = parseInt(args.start || 0, 10);
-    const limit = parseInt(args.limit || 50, 10);
-    const [encs, keys, cids, versions, updated, total] = await c.getEntriesFrom(start, limit);
-    const entries = encs.map((e, i) => ({
-      enclave: e, key_hash: keys[i], cid: cids[i] || null,
-      version: versions[i].toNumber(), updated_at: updated[i].toNumber(),
-    }));
-    return { network: name, total: total.toNumber(), start, returned: entries.length, entries };
-  }
-  throw new Error(`unknown esr subcommand: ${sub}`);
-}
-
-// ---- arg parsing (tiny, dependency-free) -----------------------------------
-
-function parseArgs(argv) {
-  const a = { _: [], json: false };
-  for (let i = 0; i < argv.length; i += 1) {
-    const t = argv[i];
-    if (t === '--json') a.json = true;
-    else if (t.startsWith('--')) { a[t.slice(2)] = argv[i + 1]; i += 1; }
-    else a._.push(t);
-  }
-  return a;
-}
-
-function emit(obj, asJson) {
-  if (asJson) { console.log(JSON.stringify(obj, null, 2)); return; }
-  for (const [k, v] of Object.entries(obj)) {
-    if (Array.isArray(v)) { console.log(`${k}:`); v.forEach((it) => console.log('  ' + JSON.stringify(it))); }
-    else console.log(`${k}: ${v}`);
-  }
-}
-
-function printFull(info) {
-  const n = info.network;
-  console.log('NETWORK');
-  console.log(`  ${n.network} (${n.type}, chain ${n.chain_id})   block ${n.latest_block || '?'}   ${n.connected ? 'connected' : 'NOT CONNECTED'}`);
-  console.log(`  rpc:            ${n.rpc}`);
-  console.log(`  protocol:       ${n.protocol_contract}`);
-  console.log(`  image registry: ${n.image_registry}`);
-  console.log(`  esr:            ${n.esr_contract}`);
-  for (const [label, key] of [['TRUSTEDZONE', 'trustedzone'], ['SECURELOCK', 'securelock']]) {
-    const r = info[key] || {};
-    console.log(label);
-    if (r.published || r.validated || r.image_ipfs_hash) {
-      console.log(`  published:    ${r.published ? 'yes' : 'no'}   validated: ${r.validated ? 'yes' : 'no'}`);
-      console.log(`  image hash:   ${r.image_ipfs_hash}`);
-      console.log(`  version:      ${r.image_version}`);
-      console.log(`  reward addr:  ${r.reward_address}`);
-      console.log(`  attestation:  ${r.attestation_session ? 'MRENCLAVE session present' : 'none'}`);
-    } else {
-      console.log(`  not found     (${r.error || r.note || 'not registered'})`);
-    }
-  }
-  const e = info.esr || {};
-  console.log('ESR');
-  if (e.note) { console.log(`  ${e.note}`); return; }
-  console.log(`  registry:     ${e.esr_contract}`);
-  if ('total_registry_entries' in e) console.log(`  total keys:   ${e.total_registry_entries} (all enclaves)`);
-  if (e.recent_commits) {
-    console.log(`  recent state commits for this enclave: ${e.recent_commits.length}`);
-    e.recent_commits.forEach((c) => console.log(`    v${c.version}  seq ${c.seq}  nonce ${c.nonce}  ${c.key_hash}  ${c.cid}  (block ${c.block})`));
-  } else if (e.recent_commits_note) console.log(`  ${e.recent_commits_note}`);
-  else if (e.recent_commits_error) console.log(`  (could not read commits: ${e.recent_commits_error})`);
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const section = args._[0];               // network | trustedzone | securelock | esr | undefined
-  const { name: netName, net } = resolveNetwork(args.network);
-  const prov = provider(net.rpc);
-
-  const ipfs = args.ipfs || process.env.IPFS_HASH || null;
-  const projName = args.name || process.env.PROJECT_NAME || null;
-
-  if (section === 'esr') {
-    args.esrCmd = args._[1];
-    const obj = await esrQuery(prov, netName, net, args);
-    emit(obj, args.json);
-    return;
-  }
-  if (section === 'network') { emit(await sectionNetwork(prov, netName, net), args.json); return; }
-  if (section === 'trustedzone') { emit(await sectionRegistration(prov, net, 'trustedzone', ipfs, projName), args.json); return; }
-  if (section === 'securelock') { emit(await sectionRegistration(prov, net, 'securelock', ipfs, projName), args.json); return; }
-
-  const info = {
-    project: { name: projName || '(unknown)', dapp_type: process.env.SERVICE_TYPE || process.env.DAPP_TYPE, version: process.env.VERSION },
-    network: await sectionNetwork(prov, netName, net),
-    trustedzone: await sectionRegistration(prov, net, 'trustedzone', ipfs, projName),
-    securelock: await sectionRegistration(prov, net, 'securelock', ipfs, projName),
-    esr: await sectionEsr(prov, net, args.enclave || null, parseInt(args.events || 10, 10)),
-  };
-  if (args.json) { console.log(JSON.stringify(info, null, 2)); return; }
-  const pr = info.project;
-  console.log(`PROJECT  ${pr.name}${pr.dapp_type ? '   type ' + pr.dapp_type : ''}${pr.version != null ? '   version ' + pr.version : ''}`);
-  printFull(info);
-}
-
-main().catch((e) => { console.error(`ecld-info: ${e.message}`); process.exit(1); });
+#!/usr/bin/env node
+/**
+ * ecld-info: everything a developer needs to read or troubleshoot an enclave.
+ *
+ * Read-only and free (eth_call + event logs -- no task, no gas, no private
+ * key). Reads your project's identity from .env (PROJECT_NAME / IPFS_HASH /
+ * BLOCKCHAIN_NETWORK), then reports:
+ *
+ *   NETWORK       name, type, chain id, RPC, contract addresses, live block
+ *   TRUSTEDZONE   the gatekeeper enclave's Image Registry record
+ *   SECURELOCK    the executor enclave's Image Registry record
+ *   ESR           registry address, total keys, and -- with --enclave <wallet>
+ *                 -- this enclave's recent StateCommitted events
+ *
+ * Subcommands (default: the full summary):
+ *   ecld-info                       full summary
+ *   ecld-info network               just the network section
+ *   ecld-info trustedzone           just the trustedzone registration
+ *   ecld-info securelock            just the securelock registration
+ *   ecld-info esr address|count|state|version|nonce|list   ESR inspection
+ *
+ * Registration is keyed by the image's IPFS hash: pass --ipfs <hash> for an
+ * exact record, or --name <n> to resolve the latest registered version of a
+ * name. With neither, .env IPFS_HASH / PROJECT_NAME are used.
+ *
+ * Network: --network NAME, else ESR_NETWORK env, else .env BLOCKCHAIN_NETWORK,
+ * else BLOXBERG_TESTNET.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { ethers } = require('ethers');
+try { require('dotenv').config(); } catch (e) { /* dotenv optional */ }
+
+// Authoritative per-network values (mirror of the Python SDK's network table).
+const NETWORKS = {
+  BLOXBERG_MAINNET: {
+    type: 'mainnet', chainId: 8995, rpc: 'https://core.bloxberg.org',
+    protocol: '0x549A6E06BB2084100148D50F51CF77a3436C3Ae7',
+    imageRegistry: '0x15D73a742529C3fb11f3FA32EF7f0CC3870ACA31',
+    esr: '0x54e0dD4201F530703c7988427d3b7c70c1dCeC94',
+  },
+  BLOXBERG_TESTNET: {
+    type: 'testnet', chainId: 8995, rpc: 'https://core.bloxberg.org',
+    protocol: '0x02882F03097fE8cD31afbdFbB5D72a498B41112c',
+    imageRegistry: '0x15D73a742529C3fb11f3FA32EF7f0CC3870ACA31',
+    esr: '0x421E216087eEc1e27b82188C23E490b0E2cA384d',
+  },
+  LITVM_LITEFORGE: {
+    type: 'testnet', chainId: 0, rpc: 'https://liteforge.rpc.caldera.xyz/infra-partner-http',
+    protocol: '', imageRegistry: '', esr: '0x5f427A78A0f2Bd7379b99A09C7D8fE51DD7E54D7',
+  },
+};
+
+const IMAGE_REGISTRY_ABI = [
+  'function imageDetails(string) view returns (address owner, string ipfsHash, string version, string session, uint256 fee, address rewardAddress, bool validated, bool published, string certPublicKey, string dockerComposeHash, string name)',
+  'function trustedZoneImageDetails(string) view returns (address owner, string ipfsHash, string version, string session, uint256 fee, address rewardAddress, bool validated, bool published, string certPublicKey, string dockerComposeHash, string name)',
+  'function imageVersions(string, uint256) view returns (string)',
+  'function trustedZoneImageVersions(string, uint256) view returns (string)',
+];
+
+const ESR_ABI = [
+  'function getState(address enclave, bytes32 key) view returns (string cid, uint256 version, uint64 updatedAt)',
+  'function getVersion(address enclave, bytes32 key) view returns (uint256)',
+  'function exists(address enclave, bytes32 key) view returns (bool)',
+  // The idempotency nonce is PUBLIC on-chain data, recorded next to the
+  // version and enforced strictly in-order per (enclave, key).
+  'function getNonce(address enclave, bytes32 key) view returns (uint256)',
+  'function entryCount() view returns (uint256)',
+  'function getEntriesFrom(uint256 start, uint256 limit) view returns (address[] enclaves, bytes32[] keys, string[] cids, uint256[] versions, uint64[] updatedAts, uint256 total)',
+  'event StateCommitted(address indexed enclave, bytes32 indexed key, string cid, uint256 version, uint256 seq, uint256 nonce)',
+];
+
+function resolveNetwork(name) {
+  name = (name || process.env.ESR_NETWORK || process.env.BLOCKCHAIN_NETWORK || 'BLOXBERG_TESTNET')
+    .toUpperCase();
+  const net = NETWORKS[name];
+  if (!net) {
+    throw new Error(`Unknown network '${name}'. Known: ${Object.keys(NETWORKS).join(', ')}`);
+  }
+  return { name, net };
+}
+
+function provider(rpc) {
+  return new ethers.providers.JsonRpcProvider(rpc);
+}
+
+function keyHash(key) {
+  return ethers.utils.id(key); // keccak256(utf8(key))
+}
+
+function looksLikeCID(cid) {
+  return typeof cid === 'string' && (cid.startsWith('Qm') || cid.startsWith('bafk')) && cid.length > 20;
+}
+
+function decodeDetails(d, fallbackName) {
+  return {
+    name: d.name || fallbackName,
+    published: Boolean(d.published),
+    validated: Boolean(d.validated),
+    image_ipfs_hash: d.ipfsHash || null,
+    image_version: d.version || null,
+    reward_address: d.rewardAddress,
+    owner: d.owner,
+    docker_compose_hash: d.dockerComposeHash || null,
+    attestation_session: Boolean(d.session),
+    cert_present: Boolean(d.certPublicKey),
+  };
+}
+
+async function lookupRegistration(reg, kind, ipfs, name) {
+  const detailsFn = kind === 'trustedzone' ? 'trustedZoneImageDetails' : 'imageDetails';
+  const versionsFn = kind === 'trustedzone' ? 'trustedZoneImageVersions' : 'imageVersions';
+  if (ipfs) {
+    try { return decodeDetails(await reg[detailsFn](ipfs), ipfs); }
+    catch (e) { return { found: false, error: e.message }; }
+  }
+  if (name) {
+    let latest = null;
+    for (let i = 0; i < 64; i += 1) {
+      let v;
+      try { v = await reg[versionsFn](name, i); } catch (e) { break; }
+      if (!v) break;
+      latest = v;
+    }
+    if (latest) {
+      try { return decodeDetails(await reg[detailsFn](latest), name); }
+      catch (e) { return { found: false, error: e.message }; }
+    }
+    return { found: false, note: `no registered version for name '${name}' -- the Image Registry is keyed by image IPFS hash; pass --ipfs <hash>` };
+  }
+  return { found: false, note: 'no --ipfs or --name to look up' };
+}
+
+async function sectionNetwork(prov, name, net) {
+  const out = {
+    network: name, type: net.type, chain_id: net.chainId, rpc: net.rpc,
+    protocol_contract: net.protocol || '(n/a)',
+    image_registry: net.imageRegistry || '(n/a)',
+    esr_contract: net.esr || '(not deployed)',
+  };
+  try {
+    out.latest_block = await prov.getBlockNumber();
+    out.connected = true;
+  } catch (e) {
+    out.connected = false; out.error = e.message;
+  }
+  return out;
+}
+
+async function sectionRegistration(prov, net, kind, ipfs, name) {
+  if (!net.imageRegistry) return { note: 'no image registry on this network' };
+  const reg = new ethers.Contract(net.imageRegistry, IMAGE_REGISTRY_ABI, prov);
+  return lookupRegistration(reg, kind, ipfs, name);
+}
+
+async function sectionEsr(prov, net, enclaveWallet, eventsN) {
+  if (!net.esr) return { note: 'ESR is not deployed on this network' };
+  const esr = new ethers.Contract(net.esr, ESR_ABI, prov);
+  const out = { esr_contract: net.esr };
+  try { out.total_registry_entries = (await esr.entryCount()).toNumber(); } catch (e) { /* ignore */ }
+  if (enclaveWallet) {
+    try {
+      const latest = await prov.getBlockNumber();
+      const from = Math.max(0, latest - 500000);
+      const flt = esr.filters.StateCommitted(ethers.utils.getAddress(enclaveWallet));
+      let logs = await esr.queryFilter(flt, from, 'latest');
+      logs = logs.slice(-eventsN);
+      out.recent_commits = logs.map((l) => ({
+        key_hash: l.args.key,
+        version: l.args.version.toNumber(),
+        cid: l.args.cid,
+        seq: l.args.seq.toNumber(),
+        // PUBLIC per-key nonce (advances by 1 on every commit).
+        nonce: l.args.nonce.toNumber(),
+        block: l.blockNumber,
+      }));
+    } catch (e) {
+      out.recent_commits_error = e.message;
+    }
+  } else {
+    out.recent_commits_note = 'pass --enclave <ESR wallet> to list this enclave\'s state commits';
+  }
+  return out;
+}
+
+async function esrQuery(prov, name, net, args) {
+  const esrAddr = args.contract || net.esr;
+  const sub = args.esrCmd || 'address';
+  if (sub === 'address') return { network: name, esr_contract: esrAddr || '(not deployed)', rpc: net.rpc };
+  if (!esrAddr) throw new Error(`ESR is not deployed on ${name}.`);
+  const c = new ethers.Contract(esrAddr, ESR_ABI, prov);
+  if (sub === 'count') return { network: name, entry_count: (await c.entryCount()).toNumber() };
+  if (sub === 'version') {
+    const v = (await c.getVersion(ethers.utils.getAddress(args.enclave), keyHash(args.key))).toNumber();
+    return { enclave: args.enclave, key: args.key, version: v };
+  }
+  if (sub === 'nonce') {
+    const n = (await c.getNonce(ethers.utils.getAddress(args.enclave), keyHash(args.key))).toNumber();
+    return {
+      enclave: args.enclave, key: args.key, nonce: n,
+      note: 'per-key nonce, PUBLIC data (free eth_call); advances by 1 on '
+        + 'every commit, 0 = key never committed. For exactly-once, pass '
+        + 'EXACTLY nonce + 1 to commit(); an omitted nonce is auto-assigned '
+        + 'the next value by the registry',
+    };
+  }
+  if (sub === 'state') {
+    const enclave = ethers.utils.getAddress(args.enclave);
+    const kh = keyHash(args.key);
+    const [cid, version, updated] = await c.getState(enclave, kh);
+    const exists = await c.exists(enclave, kh);
+    return {
+      network: name, enclave: args.enclave, key: args.key, key_hash: kh,
+      exists, version: version.toNumber(),
+      // PUBLIC per-key nonce; 0 = key never committed.
+      nonce: (await c.getNonce(enclave, kh)).toNumber(),
+      cid: cid || null, cid_valid: looksLikeCID(cid),
+      updated_at: updated.toNumber(),
+      note: 'cid points at ENCRYPTED state; only the enclave can decrypt it',
+    };
+  }
+  if (sub === 'list') {
+    const start = parseInt(args.start || 0, 10);
+    const limit = parseInt(args.limit || 50, 10);
+    const [encs, keys, cids, versions, updated, total] = await c.getEntriesFrom(start, limit);
+    const entries = encs.map((e, i) => ({
+      enclave: e, key_hash: keys[i], cid: cids[i] || null,
+      version: versions[i].toNumber(), updated_at: updated[i].toNumber(),
+    }));
+    return { network: name, total: total.toNumber(), start, returned: entries.length, entries };
+  }
+  throw new Error(`unknown esr subcommand: ${sub}`);
+}
+
+// ---- arg parsing (tiny, dependency-free) -----------------------------------
+
+function parseArgs(argv) {
+  const a = { _: [], json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const t = argv[i];
+    if (t === '--json') a.json = true;
+    else if (t.startsWith('--')) { a[t.slice(2)] = argv[i + 1]; i += 1; }
+    else a._.push(t);
+  }
+  return a;
+}
+
+function emit(obj, asJson) {
+  if (asJson) { console.log(JSON.stringify(obj, null, 2)); return; }
+  for (const [k, v] of Object.entries(obj)) {
+    if (Array.isArray(v)) { console.log(`${k}:`); v.forEach((it) => console.log('  ' + JSON.stringify(it))); }
+    else console.log(`${k}: ${v}`);
+  }
+}
+
+function printFull(info) {
+  const n = info.network;
+  console.log('NETWORK');
+  console.log(`  ${n.network} (${n.type}, chain ${n.chain_id})   block ${n.latest_block || '?'}   ${n.connected ? 'connected' : 'NOT CONNECTED'}`);
+  console.log(`  rpc:            ${n.rpc}`);
+  console.log(`  protocol:       ${n.protocol_contract}`);
+  console.log(`  image registry: ${n.image_registry}`);
+  console.log(`  esr:            ${n.esr_contract}`);
+  for (const [label, key] of [['TRUSTEDZONE', 'trustedzone'], ['SECURELOCK', 'securelock']]) {
+    const r = info[key] || {};
+    console.log(label);
+    if (r.published || r.validated || r.image_ipfs_hash) {
+      console.log(`  published:    ${r.published ? 'yes' : 'no'}   validated: ${r.validated ? 'yes' : 'no'}`);
+      console.log(`  image hash:   ${r.image_ipfs_hash}`);
+      console.log(`  version:      ${r.image_version}`);
+      console.log(`  reward addr:  ${r.reward_address}`);
+      console.log(`  attestation:  ${r.attestation_session ? 'MRENCLAVE session present' : 'none'}`);
+    } else {
+      console.log(`  not found     (${r.error || r.note || 'not registered'})`);
+    }
+  }
+  const e = info.esr || {};
+  console.log('ESR');
+  if (e.note) { console.log(`  ${e.note}`); return; }
+  console.log(`  registry:     ${e.esr_contract}`);
+  if ('total_registry_entries' in e) console.log(`  total keys:   ${e.total_registry_entries} (all enclaves)`);
+  if (e.recent_commits) {
+    console.log(`  recent state commits for this enclave: ${e.recent_commits.length}`);
+    e.recent_commits.forEach((c) => console.log(`    v${c.version}  seq ${c.seq}  nonce ${c.nonce}  ${c.key_hash}  ${c.cid}  (block ${c.block})`));
+  } else if (e.recent_commits_note) console.log(`  ${e.recent_commits_note}`);
+  else if (e.recent_commits_error) console.log(`  (could not read commits: ${e.recent_commits_error})`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const section = args._[0];               // network | trustedzone | securelock | esr | undefined
+  const { name: netName, net } = resolveNetwork(args.network);
+  const prov = provider(net.rpc);
+
+  const ipfs = args.ipfs || process.env.IPFS_HASH || null;
+  const projName = args.name || process.env.PROJECT_NAME || null;
+
+  if (section === 'esr') {
+    args.esrCmd = args._[1];
+    const obj = await esrQuery(prov, netName, net, args);
+    emit(obj, args.json);
+    return;
+  }
+  if (section === 'network') { emit(await sectionNetwork(prov, netName, net), args.json); return; }
+  if (section === 'trustedzone') { emit(await sectionRegistration(prov, net, 'trustedzone', ipfs, projName), args.json); return; }
+  if (section === 'securelock') { emit(await sectionRegistration(prov, net, 'securelock', ipfs, projName), args.json); return; }
+
+  const info = {
+    project: { name: projName || '(unknown)', dapp_type: process.env.SERVICE_TYPE || process.env.DAPP_TYPE, version: process.env.VERSION },
+    network: await sectionNetwork(prov, netName, net),
+    trustedzone: await sectionRegistration(prov, net, 'trustedzone', ipfs, projName),
+    securelock: await sectionRegistration(prov, net, 'securelock', ipfs, projName),
+    esr: await sectionEsr(prov, net, args.enclave || null, parseInt(args.events || 10, 10)),
+  };
+  if (args.json) { console.log(JSON.stringify(info, null, 2)); return; }
+  const pr = info.project;
+  console.log(`PROJECT  ${pr.name}${pr.dapp_type ? '   type ' + pr.dapp_type : ''}${pr.version != null ? '   version ' + pr.version : ''}`);
+  printFull(info);
+}
+
+main().catch((e) => { console.error(`ecld-info: ${e.message}`); process.exit(1); });

package/nodenithy/build/securelock/.ecld-test-stage/ecld_state.js

@@ -462,11 +462,15 @@ class StateRegistry {
    */
   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 EXACTLY the last accepted nonce for the key + 1
-    // (see getNonce; the sequence is 1, 2, 3, ... with no gaps and no
-    // reuse). Anything else throws StateNonceError and the state is NOT
-    // changed.
+    // also be { attempts, nonce }. The per-key nonce sequence advances by
+    // exactly 1 on EVERY commit (1, 2, 3, ... -- no gaps, no reuse; see
+    // getNonce).
+    //   - Omitted: the SDK takes the next value in sequence automatically.
+    //     Always succeeds (subject to permissions/versioning) but carries NO
+    //     exactly-once guarantee -- a resubmitted task picks a fresh number.
+    //   - Explicit: must be EXACTLY the last accepted nonce + 1, pinned by
+    //     the CLIENT before submitting. Anything else throws StateNonceError
+    //     (task code 36) and the state is NOT changed.
     const { attempts = 3, nonce = null } =
       typeof opts === 'number' ? { attempts: opts } : (opts || {});
     const transform = async (acl, data) => {
@@ -499,26 +503,40 @@ class StateRegistry {
       // nonce (chain merged with this task's own accepted commits), so a
       // duplicate fails in-enclave with task code 36 instead of as a failed
       // relay. The contract re-enforces the same rule on-chain either way.
+      let finalNonce;
       if (nonce != null) {
-        const n = Math.trunc(nonce);
+        finalNonce = Math.trunc(nonce);
+        if (finalNonce === 0) {
+          throw new StateNonceError(
+            `nonce=0 is reserved for 'not set' (the registry then assigns the ` +
+              `next value itself) -- omit the nonce on commit('${key}', ...) ` +
+              'instead of passing 0. Pinned nonces start at 1: use getNonce() + 1.'
+          );
+        }
         // eslint-disable-next-line no-await-in-loop
         const storedNonce = await this.getNonce(key);
-        if (n !== storedNonce + 1) {
+        if (finalNonce !== storedNonce + 1) {
           throw new StateNonceError(
-            `nonce ${n} is out of sequence for state key '${key}' (last accepted: ` +
+            `nonce ${finalNonce} is out of sequence for state key '${key}' (last accepted: ` +
               `${storedNonce}, expected: ${storedNonce + 1}); commit suppressed, ` +
               'state unchanged'
           );
         }
+      } else {
+        // No explicit nonce: the CONTRACT assigns the next value in sequence
+        // itself (wire nonce 0 = "omitted"); this predicted value feeds the
+        // blob's reporting copy and the task memo. The sequence advances on
+        // EVERY commit; only an EXPLICIT nonce carries the exactly-once
+        // guarantee (an omitted one is auto-assigned a fresh number, so it
+        // cannot deduplicate -- by design).
+        // eslint-disable-next-line no-await-in-loop
+        finalNonce = (await this.getNonce(key)) + 1;
       }
       // eslint-disable-next-line no-await-in-loop
       const [nextAcl, newData] = await transform(acl, data, currentVersion);
-      // The blob carries a REPORTING COPY of what the registry will store for
-      // this key after this commit: the supplied nonce, or the preserved
-      // current value for a nonce-less commit. Chain stays primary; reads
+      // The blob carries a REPORTING COPY of the nonce the registry will
+      // store for this key after this commit. Chain stays primary; reads
       // verify the two match.
-      // eslint-disable-next-line no-await-in-loop
-      const finalNonce = nonce != null ? Math.trunc(nonce) : ((await this.getNonce(key)) || null);
       // Bind the authoring caller into the blob (hence the CID/signature) for
       // owned state.
       const stored = wrapStored(nextAcl, newData, nextAcl ? _taskCaller : null, finalNonce);
@@ -533,7 +551,8 @@ class StateRegistry {
       await this._publish(key, blob, cid);
 
       try {
-        // On-chain, 0 means "no guard: preserve the stored nonce".
+        // Wire value: the pinned nonce, or 0 = "omitted" -- the contract
+        // then assigns the next value atomically on-chain.
         // eslint-disable-next-line no-await-in-loop
         await this._sendCommit(keyHash(key), cid, currentVersion,
           nextAcl ? normAddr(nextAcl.owner) : null,
@@ -541,7 +560,7 @@ class StateRegistry {
         // Record the POST-commit values (the DATA -- the ACL never leaves in
         // results): this is what the chain shows once the relay lands.
         ledgerRecord(key, currentVersion + 1, cid, newData);
-        if (nonce != null) _taskNonces[key] = Math.trunc(nonce);
+        _taskNonces[key] = finalNonce;
         return [nextAcl, newData];
       } catch (e) {
         const msg = String(e && e.message ? e.message : e);

package/nodenithy/build/securelock/.ecld-test-stage/esr_local.js

@@ -128,9 +128,10 @@ class MemContract {
   }
 
   // ---- the on-chain commitFor, applied locally ----
-  // Idempotency nonces are enforced strictly sequentially per (enclave, key),
-  // exactly like the contract: nonce != 0 must be EXACTLY the stored value + 1
-  // (no gaps, no reuse) or NonceOutOfOrder is thrown; nonce == 0 preserves it.
+  // The per-key nonce advances by EXACTLY 1 on every commit, like the
+  // contract: nonce == 0 ("omitted") gets the next value assigned by the
+  // registry itself; a non-zero nonce is a client-pinned guard and must be
+  // EXACTLY the stored value + 1 (no gaps, no reuse) or NonceOutOfOrder.
   applyCommit(enclave, keyHash, cid, expectedVersion, nonce = 0) {
     const k = key(enclave, keyHash);
     const entry = this._entries[k] || {};
@@ -140,7 +141,9 @@ class MemContract {
     }
     let storedNonce = Number(entry.nonce || 0);
     const n = Number(nonce || 0);
-    if (n !== 0) {
+    if (n === 0) {
+      storedNonce += 1;
+    } else {
       if (n !== storedNonce + 1) {
         throw new Error(`NonceOutOfOrder: stored ${storedNonce}, given ${n}`);
       }

package/nodenithy/build/securelock/.ecld-test-stage/nonce_ladder.js

@@ -52,10 +52,10 @@ async function main() {
   if (!threw) throw new Error('gap accepted');
   console.log('3. nonce=2 (+1) accepted, gap nonce=10 rejected ok');
 
-  // 4. nonce-less commit preserves the stored nonce
+  // 4. nonce-less commit AUTO-takes the next in sequence (2 -> 3)
   await r.commit('counter', (s) => ({ ...s, note: 'free' }));
-  if ((await r.getNonce('counter')) !== 2) throw new Error('step4');
-  console.log('4. nonce-less commit preserves stored nonce ok');
+  if ((await r.getNonce('counter')) !== 3) throw new Error('step4');
+  console.log('4. nonce-less commit auto-advanced the sequence to 3 ok');
 
   // 5. stale (reused) nonce rejected; the exact next one still works
   threw = false;
@@ -66,9 +66,17 @@ async function main() {
     threw = true;
   }
   if (!threw) throw new Error('stale accepted');
-  await r.commit('counter', (s) => ({ ...s, step: 3 }), { nonce: 3 });
-  if ((await r.getNonce('counter')) !== 3) throw new Error('step5');
-  console.log('5. stale nonce=1 rejected, next nonce=3 accepted ok');
+  threw = false;
+  try {
+    await r.commit('counter', (s) => s, { nonce: 0 });
+  } catch (e) {
+    if (!/reserved/.test(String(e.message))) throw e;
+    threw = true;
+  }
+  if (!threw) throw new Error('explicit 0 accepted');
+  await r.commit('counter', (s) => ({ ...s, step: 4 }), { nonce: 4 });
+  if ((await r.getNonce('counter')) !== 4) throw new Error('step5');
+  console.log('5. stale nonce=1 rejected, explicit nonce=0 refused, next nonce=4 accepted ok');
 
   // 6. contract-side (registry) enforcement, bypassing the SDK pre-check
   const mc = new MemContract(null);
@@ -94,8 +102,8 @@ async function main() {
   esrLocal.install(ecld2, { caller: A, filePrefix: 'st' });
   const r2 = new ecld2.StateRegistry();
   const n2 = await r2.getNonce('counter');
-  if (n2 !== 3) throw new Error('step7 got ' + n2);
-  console.log('7. chain-first getNonce()==3 after reload (public read, no memo) ok');
+  if (n2 !== 4) throw new Error('step7 got ' + n2);
+  console.log('7. chain-first getNonce()==4 after reload (public read, no memo) ok');
 
   // 8. public: nonce read needs no ACL -- content read stays denied for B
   delete require.cache[require.resolve(path.join(__dirname, 'ecld_state.js'))];

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

@@ -462,11 +462,15 @@ class StateRegistry {
    */
   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 EXACTLY the last accepted nonce for the key + 1
-    // (see getNonce; the sequence is 1, 2, 3, ... with no gaps and no
-    // reuse). Anything else throws StateNonceError and the state is NOT
-    // changed.
+    // also be { attempts, nonce }. The per-key nonce sequence advances by
+    // exactly 1 on EVERY commit (1, 2, 3, ... -- no gaps, no reuse; see
+    // getNonce).
+    //   - Omitted: the SDK takes the next value in sequence automatically.
+    //     Always succeeds (subject to permissions/versioning) but carries NO
+    //     exactly-once guarantee -- a resubmitted task picks a fresh number.
+    //   - Explicit: must be EXACTLY the last accepted nonce + 1, pinned by
+    //     the CLIENT before submitting. Anything else throws StateNonceError
+    //     (task code 36) and the state is NOT changed.
     const { attempts = 3, nonce = null } =
       typeof opts === 'number' ? { attempts: opts } : (opts || {});
     const transform = async (acl, data) => {
@@ -499,26 +503,40 @@ class StateRegistry {
       // nonce (chain merged with this task's own accepted commits), so a
       // duplicate fails in-enclave with task code 36 instead of as a failed
       // relay. The contract re-enforces the same rule on-chain either way.
+      let finalNonce;
       if (nonce != null) {
-        const n = Math.trunc(nonce);
+        finalNonce = Math.trunc(nonce);
+        if (finalNonce === 0) {
+          throw new StateNonceError(
+            `nonce=0 is reserved for 'not set' (the registry then assigns the ` +
+              `next value itself) -- omit the nonce on commit('${key}', ...) ` +
+              'instead of passing 0. Pinned nonces start at 1: use getNonce() + 1.'
+          );
+        }
         // eslint-disable-next-line no-await-in-loop
         const storedNonce = await this.getNonce(key);
-        if (n !== storedNonce + 1) {
+        if (finalNonce !== storedNonce + 1) {
           throw new StateNonceError(
-            `nonce ${n} is out of sequence for state key '${key}' (last accepted: ` +
+            `nonce ${finalNonce} is out of sequence for state key '${key}' (last accepted: ` +
               `${storedNonce}, expected: ${storedNonce + 1}); commit suppressed, ` +
               'state unchanged'
           );
         }
+      } else {
+        // No explicit nonce: the CONTRACT assigns the next value in sequence
+        // itself (wire nonce 0 = "omitted"); this predicted value feeds the
+        // blob's reporting copy and the task memo. The sequence advances on
+        // EVERY commit; only an EXPLICIT nonce carries the exactly-once
+        // guarantee (an omitted one is auto-assigned a fresh number, so it
+        // cannot deduplicate -- by design).
+        // eslint-disable-next-line no-await-in-loop
+        finalNonce = (await this.getNonce(key)) + 1;
       }
       // eslint-disable-next-line no-await-in-loop
       const [nextAcl, newData] = await transform(acl, data, currentVersion);
-      // The blob carries a REPORTING COPY of what the registry will store for
-      // this key after this commit: the supplied nonce, or the preserved
-      // current value for a nonce-less commit. Chain stays primary; reads
+      // The blob carries a REPORTING COPY of the nonce the registry will
+      // store for this key after this commit. Chain stays primary; reads
       // verify the two match.
-      // eslint-disable-next-line no-await-in-loop
-      const finalNonce = nonce != null ? Math.trunc(nonce) : ((await this.getNonce(key)) || null);
       // Bind the authoring caller into the blob (hence the CID/signature) for
       // owned state.
       const stored = wrapStored(nextAcl, newData, nextAcl ? _taskCaller : null, finalNonce);
@@ -533,7 +551,8 @@ class StateRegistry {
       await this._publish(key, blob, cid);
 
       try {
-        // On-chain, 0 means "no guard: preserve the stored nonce".
+        // Wire value: the pinned nonce, or 0 = "omitted" -- the contract
+        // then assigns the next value atomically on-chain.
         // eslint-disable-next-line no-await-in-loop
         await this._sendCommit(keyHash(key), cid, currentVersion,
           nextAcl ? normAddr(nextAcl.owner) : null,
@@ -541,7 +560,7 @@ class StateRegistry {
         // Record the POST-commit values (the DATA -- the ACL never leaves in
         // results): this is what the chain shows once the relay lands.
         ledgerRecord(key, currentVersion + 1, cid, newData);
-        if (nonce != null) _taskNonces[key] = Math.trunc(nonce);
+        _taskNonces[key] = finalNonce;
         return [nextAcl, newData];
       } catch (e) {
         const msg = String(e && e.message ? e.message : e);

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

@@ -128,9 +128,10 @@ class MemContract {
   }
 
   // ---- the on-chain commitFor, applied locally ----
-  // Idempotency nonces are enforced strictly sequentially per (enclave, key),
-  // exactly like the contract: nonce != 0 must be EXACTLY the stored value + 1
-  // (no gaps, no reuse) or NonceOutOfOrder is thrown; nonce == 0 preserves it.
+  // The per-key nonce advances by EXACTLY 1 on every commit, like the
+  // contract: nonce == 0 ("omitted") gets the next value assigned by the
+  // registry itself; a non-zero nonce is a client-pinned guard and must be
+  // EXACTLY the stored value + 1 (no gaps, no reuse) or NonceOutOfOrder.
   applyCommit(enclave, keyHash, cid, expectedVersion, nonce = 0) {
     const k = key(enclave, keyHash);
     const entry = this._entries[k] || {};
@@ -140,7 +141,9 @@ class MemContract {
     }
     let storedNonce = Number(entry.nonce || 0);
     const n = Number(nonce || 0);
-    if (n !== 0) {
+    if (n === 0) {
+      storedNonce += 1;
+    } else {
       if (n !== storedNonce + 1) {
         throw new Error(`NonceOutOfOrder: stored ${storedNonce}, given ${n}`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethernity-cloud/sdk-js",
-  "version": "1.5.15",
+  "version": "1.5.16",
   "description": "A package to run ethernity cloud build scripts",
   "scripts": {
     "ecld-build": "cross-env node ./node_modules/@ethernity-cloud/sdk-js/build.js",