@hsuite/smart-engines-sdk 3.0.3 → 3.1.0

package/dist/nestjs/index.js

@@ -1022,6 +1022,185 @@ function normalizeRegistryEntry(raw) {
   return null;
 }
 
+// src/discovery/cluster-discovery.ts
+var ClusterDiscoveryClient = class {
+  bootstrap;
+  cacheTtlMs;
+  fetchTimeoutMs;
+  allowInsecure;
+  trustAnchorClient;
+  cache = null;
+  constructor(config) {
+    if (!config.bootstrap || config.bootstrap.length === 0) {
+      throw new Error("ClusterDiscoveryClient: bootstrap must list at least one seed URL");
+    }
+    if (!config.allowInsecure) {
+      for (const seed of config.bootstrap) {
+        if (!seed.startsWith("https://")) {
+          throw new Error(
+            `ClusterDiscoveryClient: bootstrap seed "${seed}" is not HTTPS. Set allowInsecure=true for local development only.`
+          );
+        }
+      }
+    }
+    this.bootstrap = config.bootstrap;
+    this.cacheTtlMs = config.cacheTtlMs ?? 6e4;
+    this.fetchTimeoutMs = config.fetchTimeoutMs ?? 5e3;
+    this.allowInsecure = config.allowInsecure ?? false;
+    this.trustAnchorClient = config.trustAnchor ? new ValidatorDiscoveryClient(config.trustAnchor) : null;
+  }
+  /**
+   * Fetch the active-cluster set, with caching.
+   *
+   * Tries each bootstrap seed in order until one returns HTTP 200 with a
+   * parseable cluster list. If all seeds fail, throws — callers can
+   * handle by falling back to a previously-cached value if they want,
+   * or by initializing with multiple seeds.
+   */
+  async getClusters(forceRefresh = false) {
+    if (!forceRefresh && this.cache && this.isCacheValid()) {
+      return this.cache.clusters;
+    }
+    const fetched = await this.fetchFromFirstAvailableSeed();
+    const verified = this.trustAnchorClient ? await this.verifyAgainstTrustAnchor(fetched) : fetched;
+    this.cache = { clusters: verified, lastUpdated: Date.now() };
+    return verified;
+  }
+  /**
+   * Random pick over the active-cluster set. Returns `null` when no
+   * cluster passes verification (empty registry / all-rejected anchor).
+   *
+   * Uses `crypto.getRandomValues` when available (browsers, Deno, modern
+   * Node) for cryptographic-strength randomness; `Math.random` is a
+   * fallback for older runtimes where `globalThis.crypto` is undefined.
+   * Discovery isn't cryptographically sensitive — load distribution is
+   * the goal here.
+   */
+  async getRandomCluster(forceRefresh = false) {
+    const clusters = await this.getClusters(forceRefresh);
+    if (clusters.length === 0) return null;
+    return clusters[this.pickRandomIndex(clusters.length)];
+  }
+  /**
+   * Convenience wrapper returning just the gateway URL of a random
+   * active cluster. The single most-used SDK entry point — most
+   * downstream callers want `new SmartEngineClient({ baseUrl: ... })`
+   * and don't care about the rest of the metadata.
+   */
+  async getRandomGatewayUrl(forceRefresh = false) {
+    const cluster = await this.getRandomCluster(forceRefresh);
+    return cluster?.endpoints.gatewayUrl ?? null;
+  }
+  /** Per-clusterId lookup, useful for "stick the SDK to cluster X" flows. */
+  async getClusterById(clusterId, forceRefresh = false) {
+    const clusters = await this.getClusters(forceRefresh);
+    return clusters.find((c) => c.clusterId === clusterId) ?? null;
+  }
+  clearCache() {
+    this.cache = null;
+  }
+  isCacheValid() {
+    if (!this.cache) return false;
+    return Date.now() - this.cache.lastUpdated < this.cacheTtlMs;
+  }
+  async fetchFromFirstAvailableSeed() {
+    const errors = [];
+    for (const seed of this.bootstrap) {
+      try {
+        return await this.fetchClustersFromSeed(seed);
+      } catch (err) {
+        errors.push(`${seed}: ${err.message}`);
+      }
+    }
+    throw new Error(
+      `ClusterDiscoveryClient: no bootstrap seed reachable. Attempts:
+  ${errors.join("\n  ")}`
+    );
+  }
+  async fetchClustersFromSeed(seed) {
+    const url = `${seed.replace(/\/$/, "")}/api/v3/discovery/clusters`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.fetchTimeoutMs);
+    try {
+      const res = await fetch(url, { signal: ctrl.signal });
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      const body = await res.json();
+      if (!Array.isArray(body.clusters)) {
+        throw new Error("response missing clusters[]");
+      }
+      return body.clusters.map((c) => this.normalizeClusterEntry(c)).filter((c) => c !== null);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  normalizeClusterEntry(raw) {
+    if (typeof raw.clusterId !== "string" || !raw.clusterId) return null;
+    if (!raw.endpoints || typeof raw.endpoints !== "object") return null;
+    const ep = raw.endpoints;
+    if (typeof ep.gatewayUrl !== "string" || !ep.gatewayUrl) return null;
+    if (!this.allowInsecure && !ep.gatewayUrl.startsWith("https://")) {
+      return null;
+    }
+    const nodeIds = Array.isArray(raw.nodeIds) ? raw.nodeIds.filter((n) => typeof n === "string") : [];
+    return {
+      clusterId: raw.clusterId,
+      endpoints: {
+        clusterId: raw.clusterId,
+        gatewayUrl: ep.gatewayUrl,
+        harborUrl: typeof ep.harborUrl === "string" ? ep.harborUrl : void 0,
+        natsUrl: typeof ep.natsUrl === "string" ? ep.natsUrl : void 0,
+        publicIp: typeof ep.publicIp === "string" ? ep.publicIp : void 0,
+        region: typeof ep.region === "string" ? ep.region : void 0
+      },
+      nodeIds
+    };
+  }
+  /**
+   * Cross-check the HTTP-fetched cluster set against the HCS validator
+   * registry. Clusters whose nodeIds are not on-chain are dropped.
+   *
+   * Two failure modes are deliberately silent here:
+   *   - the HCS read itself throws → original list is returned
+   *     un-verified. Trust-anchor is advisory; a network partition
+   *     between SDK and Hedera mirror shouldn't strand the SDK.
+   *   - the HCS read returns empty (mirror node lag, wrong topicId)
+   *     → original list is returned. Better to keep working off
+   *     possibly-stale-but-real data than reject every cluster.
+   *
+   * Both behaviors are why this is called "trust *anchor*", not
+   * "trust gate". Crypto-strong gating is a follow-up.
+   */
+  async verifyAgainstTrustAnchor(clusters) {
+    if (!this.trustAnchorClient || clusters.length === 0) return clusters;
+    let onChainNodeIds;
+    try {
+      const validators = await this.trustAnchorClient.getValidators();
+      if (validators.length === 0) return clusters;
+      onChainNodeIds = new Set(validators.map((v) => v.nodeId));
+    } catch {
+      return clusters;
+    }
+    return clusters.filter((c) => {
+      if (c.nodeIds.length === 0) {
+        return false;
+      }
+      return c.nodeIds.some((id) => onChainNodeIds.has(id));
+    });
+  }
+  pickRandomIndex(n) {
+    if (n <= 1) return 0;
+    const g = globalThis.crypto;
+    if (g?.getRandomValues) {
+      const buf = new Uint32Array(1);
+      g.getRandomValues(buf);
+      return buf[0] % n;
+    }
+    return Math.floor(Math.random() * n);
+  }
+};
+
 // src/auth/validator-auth.ts
 var SUPPORTED_AUTH_CHAINS = [
   "hedera",
@@ -1832,6 +2011,167 @@ var SnapshotsClient = class {
   }
 };
 
+// src/historical-balance/historical-balance-client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var ENDPOINT_PATH = "/api/v3/historical-balance/query";
+var HistoricalBalanceClientError = class extends Error {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "HistoricalBalanceClientError";
+  }
+  statusCode;
+  details;
+};
+var HistoricalBalanceClient = class _HistoricalBalanceClient {
+  // Standalone-mode fields (set when the client builds its own fetch).
+  baseUrl;
+  authToken;
+  apiKey;
+  timeoutMs;
+  fetchImpl;
+  // Sub-client-mode field (set when wired via SmartEngineClient).
+  http;
+  constructor(config) {
+    if ("http" in config) {
+      this.http = config.http;
+      this.timeoutMs = DEFAULT_TIMEOUT_MS;
+      return;
+    }
+    if (!config.baseUrl) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient: baseUrl is required for standalone construction",
+        400
+      );
+    }
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.authToken = config.authToken;
+    this.apiKey = config.apiKey;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = config.fetchImpl;
+  }
+  /**
+   * Factory used by `SmartEngineClient` to wire this sub-client onto the
+   * parent's shared `HttpClient` (which already carries auth + baseUrl + a
+   * `/api/v3` prefix). Routes through `/historical-balance/query` since the
+   * parent's HttpClient is rooted at `/api/v3`.
+   */
+  static fromHttp(http) {
+    return new _HistoricalBalanceClient({ http });
+  }
+  /**
+   * Query a point-in-time balance.
+   *
+   * The validator returns the on-chain bigint as a base-10 decimal string.
+   * Callers needing arithmetic precision should wrap the result:
+   *
+   * ```ts
+   * const { balance } = await client.historicalBalance.getBalance({ ... });
+   * const value = BigInt(balance);
+   * ```
+   */
+  async getBalance(params) {
+    this.validateParams(params);
+    if (this.http) {
+      return this.http.post("/historical-balance/query", params);
+    }
+    return this.standaloneFetch(params);
+  }
+  validateParams(params) {
+    if (!params || typeof params !== "object") {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient.getBalance: params object is required",
+        400
+      );
+    }
+    const { chain, entityId, account, atTimestamp } = params;
+    if (chain !== "hedera" && chain !== "xrpl" && chain !== "polkadot") {
+      throw new HistoricalBalanceClientError(
+        `HistoricalBalanceClient.getBalance: unsupported chain "${String(chain)}" (expected hedera | xrpl | polkadot)`,
+        400
+      );
+    }
+    if (typeof entityId !== "string" || entityId.length === 0) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient.getBalance: entityId must be a non-empty string",
+        400
+      );
+    }
+    if (typeof account !== "string" || account.length === 0) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient.getBalance: account must be a non-empty string",
+        400
+      );
+    }
+    if (typeof atTimestamp !== "number" || !Number.isInteger(atTimestamp) || atTimestamp <= 0) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient.getBalance: atTimestamp must be a positive integer (unix seconds)",
+        400
+      );
+    }
+  }
+  async standaloneFetch(params) {
+    const url = `${this.baseUrl}${ENDPOINT_PATH}`;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (this.authToken) headers.Authorization = `Bearer ${this.authToken}`;
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    const fetchFn = this.fetchImpl ?? (typeof fetch !== "undefined" ? fetch : void 0);
+    if (!fetchFn) {
+      throw new HistoricalBalanceClientError(
+        "HistoricalBalanceClient: no fetch implementation available (provide fetchImpl)",
+        500
+      );
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await fetchFn(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(params),
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      const message = err instanceof Error ? err.message : String(err);
+      throw new HistoricalBalanceClientError(
+        `HistoricalBalanceClient: transport error: ${message}`,
+        0,
+        err
+      );
+    }
+    clearTimeout(timer);
+    let body;
+    const text = await response.text();
+    if (text.length > 0) {
+      try {
+        body = JSON.parse(text);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new HistoricalBalanceClientError(
+          `HistoricalBalanceClient: non-JSON response (status=${response.status}): ${message}`,
+          response.status,
+          { raw: text }
+        );
+      }
+    }
+    if (!response.ok) {
+      const detail = body && typeof body === "object" && "message" in body ? String(body.message) : `HTTP ${response.status}`;
+      throw new HistoricalBalanceClientError(
+        `HistoricalBalanceClient: ${detail}`,
+        response.status,
+        body
+      );
+    }
+    return body;
+  }
+};
+
 // src/settlement/index.ts
 var SettlementClient = class {
   constructor(http) {
@@ -1866,6 +2206,53 @@ var SettlementClient = class {
   }
 };
 
+// src/governance/governance-client.ts
+var GovernanceClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Dry-run a governance proposal/vote/etc. against `GovernanceMolecule.validate(...)`.
+   *
+   * Returns whatever `ValidationResult` the molecule produced. A `false`
+   * `isValid` is **not** an error — it is a successful "this proposal is
+   * invalid" outcome and is surfaced via the normal return value.
+   *
+   * HTTP errors (400 malformed body, 500 unexpected) bubble up as
+   * `SdkHttpError` via the shared `HttpClient` layer.
+   */
+  async simulate(params) {
+    return this.http.post("/governance/simulate", params);
+  }
+};
+
+// src/personhood/personhood-client.ts
+var PersonhoodClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Verify a personhood proof for `candidate`.
+   *
+   * Returns the issued cert on accept, `null` on clean rejection. All
+   * other failure modes (validation, transport, 5xx) propagate as
+   * `SdkHttpError`.
+   */
+  async verify(params) {
+    const result = await this.http.post(
+      "/personhood/verify",
+      {
+        candidate: params.candidate,
+        proof: params.proof
+      }
+    );
+    if (result === void 0) return null;
+    return result;
+  }
+};
+
 // src/client.ts
 var SmartEngineClient = class _SmartEngineClient {
   baseUrl;
@@ -1886,8 +2273,14 @@ var SmartEngineClient = class _SmartEngineClient {
   transactions;
   /** Token holder snapshot generation and retrieval */
   snapshots;
+  /** Historical balance archive reads (chain-native bigint, returned as decimal string) */
+  historicalBalance;
   /** Cross-chain settlement operations */
   settlement;
+  /** Governance proposal dry-run (simulate-only) */
+  governance;
+  /** Personhood verification (HPP one-human-one-member) */
+  personhood;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
     this.baseUrl = validateClientUrl(config.baseUrl, this.allowInsecure);
@@ -1908,7 +2301,10 @@ var SmartEngineClient = class _SmartEngineClient {
     this.ipfs = new IPFSClient(this.http);
     this.transactions = new TransactionsClient(this.txHttp);
     this.snapshots = new SnapshotsClient(this.http);
+    this.historicalBalance = HistoricalBalanceClient.fromHttp(this.http);
     this.settlement = new SettlementClient(this.http);
+    this.governance = new GovernanceClient(this.http);
+    this.personhood = new PersonhoodClient(this.http);
   }
   /**
    * Connect to the smart-engines network with auto-discovery and authentication
@@ -1953,6 +2349,67 @@ var SmartEngineClient = class _SmartEngineClient {
     });
     return { client, validator, session };
   }
+  /**
+   * Connect to the smart-engines network via the **service-registry**
+   * (PR-1 of the cluster-discovery arc). Preferred over
+   * {@link connectToNetwork} once the validator pods in the target network
+   * have published their cluster endpoints — the SDK auto-balances across
+   * the active cluster set and rides permissionless cluster join/leave
+   * without code edits.
+   *
+   * Fallback ladder (per `docs/ops/HANDOFF-service-registry-distribution-layer.md` §6):
+   *   1. HTTP fetch `/api/v3/discovery/clusters` from each bootstrap seed.
+   *   2. (Optional) HCS trust-anchor membership cross-check.
+   *   3. Random-pick over the verified set.
+   *
+   * @example
+   * ```ts
+   * const { client, cluster, session } = await SmartEngineClient.connectToCluster({
+   *   bootstrap: ['https://sn1.testnet.hsuite.network', 'https://sn2.testnet.hsuite.network'],
+   *   chain: 'xrpl',
+   *   address: '...',
+   *   publicKey: '...',
+   *   signFn: async (challenge) => sign(challenge),
+   * });
+   * ```
+   */
+  static async connectToCluster(config) {
+    const allowInsecure = config.allowInsecure ?? false;
+    const discovery = new ClusterDiscoveryClient({
+      bootstrap: config.bootstrap,
+      allowInsecure,
+      trustAnchor: config.trustAnchor ? {
+        network: config.trustAnchor.network,
+        registryTopicId: config.trustAnchor.registryTopicId,
+        mirrorNodeUrl: config.trustAnchor.mirrorNodeUrl,
+        allowInsecure
+      } : void 0
+    });
+    const cluster = await discovery.getRandomCluster();
+    if (!cluster) {
+      throw new SmartEngineError2(
+        "No active clusters available via bootstrap seeds. Check bootstrap URLs and network reachability.",
+        503
+      );
+    }
+    const gatewayUrl = cluster.endpoints.gatewayUrl;
+    validateClientUrl(gatewayUrl, allowInsecure);
+    const auth = new ValidatorAuthClient({ security: { allowInsecure } });
+    const session = await auth.authenticateWithSigner(
+      gatewayUrl,
+      config.chain,
+      config.address,
+      config.publicKey,
+      config.signFn,
+      config.metadata
+    );
+    const client = new _SmartEngineClient({
+      baseUrl: gatewayUrl,
+      authToken: session.token,
+      allowInsecure
+    });
+    return { client, cluster, session };
+  }
   /** Get the current validator URL */
   getBaseUrl() {
     return this.baseUrl;