@hsuite/smart-engines-sdk 3.4.1 → 3.6.0

package/dist/nestjs/index.js

@@ -230,7 +230,7 @@ var CreateAccountRequestSchema = zod.z.object({
    * Smart node security mode for the account key structure.
    * - 'partial': threshold(2, [appOwnerKey, tssKeyList]) — co-control
    * - 'full': TSS KeyList only — full validator network control
-   * Default: 'full' (Arc 5 §7.5.2: 'none' removed).
+   * @defaultValue 'full'
    */
   securityMode: zod.z.enum(["partial", "full"]).default("full"),
   /**
@@ -1100,6 +1100,187 @@ var ClusterDiscoveryClient = class {
   }
 };
 
+// src/http/index.ts
+var SdkHttpError = class extends Error {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "SdkHttpError";
+  }
+  statusCode;
+  details;
+};
+function createHttpClient(config) {
+  const timeout = config.timeout ?? 3e4;
+  function getHeaders(contentType) {
+    const headers = {};
+    if (contentType) {
+      headers["Content-Type"] = contentType;
+    }
+    if (config.authToken) {
+      headers["Authorization"] = `Bearer ${config.authToken}`;
+    }
+    if (config.apiKey) {
+      headers["X-API-Key"] = config.apiKey;
+    }
+    return headers;
+  }
+  function setAuthToken(token) {
+    config.authToken = token;
+  }
+  function getAuthToken() {
+    return config.authToken;
+  }
+  async function request(method, path, body) {
+    const url = `${config.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const init = {
+        method,
+        headers: getHeaders("application/json"),
+        signal: controller.signal
+      };
+      if (body !== void 0) {
+        init.body = JSON.stringify(body);
+      }
+      const response = await fetch(url, init);
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new SdkHttpError(
+          errorData.message || `API error: ${response.status} ${response.statusText}`,
+          response.status,
+          errorData
+        );
+      }
+      const text = await response.text();
+      if (!text) return void 0;
+      return JSON.parse(text);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof SdkHttpError) throw error;
+      const err = error;
+      if (err.name === "AbortError") {
+        throw new SdkHttpError("Request timeout", 408);
+      }
+      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
+    }
+  }
+  async function getText(path) {
+    const url = `${config.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: getHeaders(),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errBody = await response.json().catch(() => ({}));
+        throw new SdkHttpError(
+          errBody.message || `API error: ${response.status} ${response.statusText}`,
+          response.status,
+          errBody
+        );
+      }
+      return await response.text();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof SdkHttpError) throw error;
+      const err = error;
+      if (err.name === "AbortError") {
+        throw new SdkHttpError("Request timeout", 408);
+      }
+      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
+    }
+  }
+  async function upload(path, file, filename, metadata, fieldName = "file") {
+    const url = `${config.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout * 2);
+    try {
+      const formData = new FormData();
+      const blob = file instanceof Blob ? file : new Blob([new Uint8Array(file)]);
+      formData.append(fieldName, blob, filename);
+      if (metadata) {
+        for (const [key, value] of Object.entries(metadata)) {
+          formData.append(key, value);
+        }
+      }
+      const headers = {};
+      if (config.authToken) {
+        headers["Authorization"] = `Bearer ${config.authToken}`;
+      }
+      if (config.apiKey) {
+        headers["X-API-Key"] = config.apiKey;
+      }
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: formData,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new SdkHttpError(
+          errorData.message || `Upload error: ${response.status} ${response.statusText}`,
+          response.status,
+          errorData
+        );
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof SdkHttpError) throw error;
+      const err = error;
+      if (err.name === "AbortError") {
+        throw new SdkHttpError("Upload timeout", 408);
+      }
+      throw new SdkHttpError(`Upload error: ${err.message}`, 0, error);
+    }
+  }
+  let reauthInFlight = null;
+  async function withAuthRetry(path, op) {
+    try {
+      return await op();
+    } catch (error) {
+      const refreshable = !!config.onUnauthorized && !path.startsWith("/api/auth/") && error instanceof SdkHttpError && error.statusCode === 401;
+      if (!refreshable) throw error;
+      if (!reauthInFlight) {
+        reauthInFlight = Promise.resolve(config.onUnauthorized()).finally(() => {
+          reauthInFlight = null;
+        });
+      }
+      try {
+        await reauthInFlight;
+      } catch {
+        throw error;
+      }
+      return await op();
+    }
+  }
+  const client = {
+    post: (path, body) => withAuthRetry(path, () => request("POST", path, body)),
+    get: (path) => withAuthRetry(path, () => request("GET", path)),
+    put: (path, body) => withAuthRetry(path, () => request("PUT", path, body)),
+    patch: (path, body) => withAuthRetry(path, () => request("PATCH", path, body)),
+    delete: (path) => withAuthRetry(path, () => request("DELETE", path)),
+    getText: (path) => withAuthRetry(path, () => getText(path)),
+    upload: ((path, file, filename, metadata, fieldName) => withAuthRetry(path, () => upload(path, file, filename, metadata, fieldName))),
+    setAuthToken,
+    getAuthToken
+  };
+  return client;
+}
+function encodePathParam(param) {
+  return encodeURIComponent(param).replace(/%2F/gi, "");
+}
+
 // src/discovery/discovery-client.ts
 var DiscoveryClient = class {
   constructor(http) {
@@ -1133,7 +1314,7 @@ var DiscoveryClient = class {
    * try/catch.
    */
   async getClusterByNode(nodeId) {
-    return this.http.get(`/discovery/clusters/${encodeURIComponent(nodeId)}`);
+    return this.http.get(`/discovery/clusters/${encodePathParam(nodeId)}`);
   }
 };
 var PlatformImagesClient = class {
@@ -1163,7 +1344,7 @@ var PlatformImagesClient = class {
    * authorized?" queries.
    */
   async get(imageName) {
-    return this.http.get(`/discovery/platform-images/${encodeURIComponent(imageName)}`);
+    return this.http.get(`/discovery/platform-images/${encodePathParam(imageName)}`);
   }
   /**
    * `GET /api/v3/discovery/platform-images/:imageName/:version` —
@@ -1172,7 +1353,7 @@ var PlatformImagesClient = class {
    */
   async getVersion(imageName, version) {
     return this.http.get(
-      `/discovery/platform-images/${encodeURIComponent(imageName)}/${encodeURIComponent(version)}`
+      `/discovery/platform-images/${encodePathParam(imageName)}/${encodePathParam(version)}`
     );
   }
   /**
@@ -1186,13 +1367,63 @@ var PlatformImagesClient = class {
    */
   async verify(imageName, version, digest) {
     return this.http.get(
-      `/discovery/platform-images/${encodeURIComponent(imageName)}/${encodeURIComponent(
+      `/discovery/platform-images/${encodePathParam(imageName)}/${encodePathParam(
         version
       )}/verify?digest=${encodeURIComponent(digest)}`
     );
   }
 };
 
+// src/network-presets.ts
+var KNOWN_NETWORKS = {
+  testnet: {
+    bootstrap: ["https://gateway.testnet.hsuite.network"]
+  },
+  mainnet: {
+    // Mainnet entrypoint reserved. The SDK still resolves the name so
+    // upgrade-by-flipping-NETWORK works; the bootstrap URL is the
+    // pre-allocated DNS we own. If mainnet isn't deployed yet, the discovery
+    // fetch will fail at runtime with the same "no seed reachable" error
+    // any unreachable URL produces — the caller learns the network is not
+    // live, rather than getting a baffling "unknown network" TypeScript
+    // error at compile time.
+    bootstrap: ["https://gateway.hsuite.network"]
+  }
+};
+function resolveNetwork(name) {
+  const preset = KNOWN_NETWORKS[name];
+  if (!preset) {
+    throw new Error(
+      `Unknown network: "${name}". Known networks: ${Object.keys(KNOWN_NETWORKS).join(", ")}`
+    );
+  }
+  return preset;
+}
+
+// src/discovery/resolve-cluster.ts
+async function resolveClusterEndpoint(config) {
+  const allowInsecure = config.allowInsecure ?? false;
+  const bootstrap = config.bootstrap ? [...config.bootstrap] : config.network ? [...resolveNetwork(config.network).bootstrap] : [];
+  if (bootstrap.length === 0) {
+    return { ok: false, reason: "no-seeds" };
+  }
+  const discovery = new ClusterDiscoveryClient({
+    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) {
+    return { ok: false, reason: "no-clusters" };
+  }
+  return { ok: true, cluster };
+}
+
 // src/auth/validator-auth.ts
 var SUPPORTED_AUTH_CHAINS = [
   "hedera",
@@ -1201,6 +1432,10 @@ var SUPPORTED_AUTH_CHAINS = [
   "stellar",
   "solana"
 ];
+function toBytes(value) {
+  if (value instanceof Uint8Array) return value;
+  return value.toBytes();
+}
 function validateValidatorUrl(url, allowInsecure = false) {
   try {
     const parsed = new URL(url);
@@ -1400,30 +1635,42 @@ var ValidatorAuthClient = class {
     }
   }
   /**
-   * Sign challenge with Hedera private key
+   * Sign challenge with Hedera private key.
+   *
+   * Structurally typed against the surface of `@hashgraph/sdk`'s
+   * `PrivateKey`. We don't `import` the SDK directly — pulling it into
+   * the smart-engine SDK's runtime would bloat browser bundles and bring
+   * peer-dep churn — but any object with a compatible `sign(...)` method
+   * works.
    *
    * @param challenge - Challenge string from validator
-   * @param privateKey - Hedera PrivateKey instance from @hashgraph/sdk
+   * @param privateKey - Hedera PrivateKey instance (or compatible signer)
    * @returns Hex-encoded signature
    */
   signChallengeHedera(challenge, privateKey) {
-    const messageBytes = Buffer.from(challenge, "utf-8");
+    const messageBytes = new Uint8Array(Buffer.from(challenge, "utf-8"));
     const signature = privateKey.sign(messageBytes);
-    return Buffer.from(signature).toString("hex");
+    return Buffer.from(toBytes(signature)).toString("hex");
   }
   /**
-   * Sign challenge with XRPL wallet
+   * Sign challenge with XRPL wallet.
+   *
+   * Structurally typed against the surface of xrpl's `Wallet` — see the
+   * comment on {@link HederaSigner} for the "no direct import" rationale.
+   * Accepts both the `{ signedTransaction }` envelope and the bare-string
+   * return shapes that xrpl signer libraries expose.
    *
    * @param challenge - Challenge string from validator
-   * @param wallet - XRPL Wallet instance from xrpl library
+   * @param wallet - XRPL Wallet instance (or compatible signer)
    * @returns Hex-encoded signature
    */
   signChallengeXRPL(challenge, wallet) {
     const signature = wallet.sign(challenge);
-    if (typeof signature === "string" && /^[0-9A-Fa-f]+$/.test(signature)) {
-      return signature;
+    if (typeof signature === "string") {
+      if (/^[0-9A-Fa-f]+$/.test(signature)) return signature;
+      return Buffer.from(signature).toString("hex");
     }
-    return Buffer.from(signature).toString("hex");
+    return signature.signedTransaction;
   }
   /**
    * Complete authentication flow in one call
@@ -1460,189 +1707,6 @@ var ValidatorAuthError = class extends Error {
   details;
 };
 
-// src/http/index.ts
-var SdkHttpError = class extends Error {
-  constructor(message, statusCode, details) {
-    super(message);
-    this.statusCode = statusCode;
-    this.details = details;
-    this.name = "SdkHttpError";
-  }
-  statusCode;
-  details;
-};
-function createHttpClient(config) {
-  const timeout = config.timeout ?? 3e4;
-  function getHeaders(contentType) {
-    const headers = {};
-    if (contentType) {
-      headers["Content-Type"] = contentType;
-    }
-    if (config.authToken) {
-      headers["Authorization"] = `Bearer ${config.authToken}`;
-    }
-    if (config.apiKey) {
-      headers["X-API-Key"] = config.apiKey;
-    }
-    return headers;
-  }
-  function setAuthToken(token) {
-    config.authToken = token;
-  }
-  async function request(method, path, body) {
-    const url = `${config.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-    try {
-      const init = {
-        method,
-        headers: getHeaders("application/json"),
-        signal: controller.signal
-      };
-      if (body !== void 0) {
-        init.body = JSON.stringify(body);
-      }
-      const response = await fetch(url, init);
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        throw new SdkHttpError(
-          errorData.message || `API error: ${response.status} ${response.statusText}`,
-          response.status,
-          errorData
-        );
-      }
-      const text = await response.text();
-      if (!text) return void 0;
-      return JSON.parse(text);
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof SdkHttpError) throw error;
-      const err = error;
-      if (err.name === "AbortError") {
-        throw new SdkHttpError("Request timeout", 408);
-      }
-      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
-    }
-  }
-  async function getText(path) {
-    const url = `${config.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-    try {
-      const response = await fetch(url, {
-        method: "GET",
-        headers: getHeaders(),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errBody = await response.json().catch(() => ({}));
-        throw new SdkHttpError(
-          errBody.message || `API error: ${response.status} ${response.statusText}`,
-          response.status,
-          errBody
-        );
-      }
-      return await response.text();
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof SdkHttpError) throw error;
-      const err = error;
-      if (err.name === "AbortError") {
-        throw new SdkHttpError("Request timeout", 408);
-      }
-      throw new SdkHttpError(`Network error: ${err.message}`, 0, error);
-    }
-  }
-  async function upload(path, file, filename, metadata, fieldName = "file") {
-    const url = `${config.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout * 2);
-    try {
-      const formData = new FormData();
-      const blob = file instanceof Blob ? file : new Blob([new Uint8Array(file)]);
-      formData.append(fieldName, blob, filename);
-      if (metadata) {
-        for (const [key, value] of Object.entries(metadata)) {
-          formData.append(key, value);
-        }
-      }
-      const headers = {};
-      if (config.authToken) {
-        headers["Authorization"] = `Bearer ${config.authToken}`;
-      }
-      if (config.apiKey) {
-        headers["X-API-Key"] = config.apiKey;
-      }
-      const response = await fetch(url, {
-        method: "POST",
-        headers,
-        body: formData,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        throw new SdkHttpError(
-          errorData.message || `Upload error: ${response.status} ${response.statusText}`,
-          response.status,
-          errorData
-        );
-      }
-      return response.json();
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof SdkHttpError) throw error;
-      const err = error;
-      if (err.name === "AbortError") {
-        throw new SdkHttpError("Upload timeout", 408);
-      }
-      throw new SdkHttpError(`Upload error: ${err.message}`, 0, error);
-    }
-  }
-  const client = {
-    post: (path, body) => request("POST", path, body),
-    get: (path) => request("GET", path),
-    put: (path, body) => request("PUT", path, body),
-    patch: (path, body) => request("PATCH", path, body),
-    delete: (path) => request("DELETE", path),
-    getText,
-    upload: ((path, file, filename, metadata, fieldName) => upload(path, file, filename, metadata, fieldName)),
-    setAuthToken
-  };
-  return client;
-}
-function encodePathParam(param) {
-  return encodeURIComponent(param).replace(/%2F/gi, "");
-}
-
-// src/network-presets.ts
-var KNOWN_NETWORKS = {
-  testnet: {
-    bootstrap: ["https://gateway.testnet.hsuite.network"]
-  },
-  mainnet: {
-    // Mainnet entrypoint reserved. The SDK still resolves the name so
-    // upgrade-by-flipping-NETWORK works; the bootstrap URL is the
-    // pre-allocated DNS we own. If mainnet isn't deployed yet, the discovery
-    // fetch will fail at runtime with the same "no seed reachable" error
-    // any unreachable URL produces — the caller learns the network is not
-    // live, rather than getting a baffling "unknown network" TypeScript
-    // error at compile time.
-    bootstrap: ["https://gateway.hsuite.network"]
-  }
-};
-function resolveNetwork(name) {
-  const preset = KNOWN_NETWORKS[name];
-  if (!preset) {
-    throw new Error(
-      `Unknown network: "${name}". Known networks: ${Object.keys(KNOWN_NETWORKS).join(", ")}`
-    );
-  }
-  return preset;
-}
-
 // src/subscription/index.ts
 var SubscriptionClient = class {
   constructor(http) {
@@ -1660,13 +1724,13 @@ var SubscriptionClient = class {
    * Get subscription status by app ID
    */
   async getStatus(appId) {
-    return this.http.get(`/subscription/status/${encodeURIComponent(appId)}`);
+    return this.http.get(`/subscription/status/${encodePathParam(appId)}`);
   }
   /**
    * Mint subscription NFT after deposit is confirmed
    */
   async mintNft(appId) {
-    return this.http.post(`/subscription/mint/${encodeURIComponent(appId)}`, {});
+    return this.http.post(`/subscription/mint/${encodePathParam(appId)}`, {});
   }
   /**
    * Renew subscription by extending period
@@ -1735,13 +1799,13 @@ var SubscriptionClient = class {
    * List subscriptions by status
    */
   async listByStatus(status) {
-    return this.http.get(`/subscription/list/status/${encodeURIComponent(status)}`);
+    return this.http.get(`/subscription/list/status/${encodePathParam(status)}`);
   }
   /**
    * Get subscription balance
    */
   async getBalance(appId) {
-    return this.http.get(`/subscription/balance/${encodeURIComponent(appId)}`);
+    return this.http.get(`/subscription/balance/${encodePathParam(appId)}`);
   }
   // ─── Tier-Change Endpoints ────────────────────────────────────────────────
   /**
@@ -1773,19 +1837,19 @@ var SubscriptionClient = class {
    */
   async getActiveFor(walletAddress) {
     return this.http.get(
-      `/subscription/active-for/${encodeURIComponent(walletAddress)}`
+      `/subscription/active-for/${encodePathParam(walletAddress)}`
     );
   }
   /** Today's consumption breakdown by category for an app. Owner-only. */
   async getUsage(appId) {
-    return this.http.get(`/subscription/usage/${encodeURIComponent(appId)}`);
+    return this.http.get(`/subscription/usage/${encodePathParam(appId)}`);
   }
   /**
    * Current usage with overage info: usage percent, grace status,
    * upgrade suggestion, projected days until limit. Owner-only.
    */
   async getUsageStatus(appId) {
-    return this.http.get(`/subscription/usage/status/${encodeURIComponent(appId)}`);
+    return this.http.get(`/subscription/usage/status/${encodePathParam(appId)}`);
   }
   /**
    * Subscription balance deduction history. Pagination + ISO-8601 range
@@ -1799,7 +1863,7 @@ var SubscriptionClient = class {
     if (options?.to) params.append("to", options.to);
     const qs = params.toString();
     return this.http.get(
-      `/subscription/billing/${encodeURIComponent(appId)}${qs ? `?${qs}` : ""}`
+      `/subscription/billing/${encodePathParam(appId)}${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -1819,6 +1883,40 @@ var SubscriptionClient = class {
   }
 };
 
+// src/faucet/index.ts
+var FaucetClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Request a signing challenge for a recipient address. The returned
+   * `message` must be signed by the key controlling `recipientAddress`.
+   */
+  async requestChallenge(chain, recipientAddress) {
+    return this.http.post("/faucet/hsuite/challenge", { chain, recipientAddress });
+  }
+  /**
+   * Submit a signed challenge to dispense HST. The result is a discriminated
+   * union on `status` — branch on `'dispensed' | 'trustline_required' |
+   * 'rate_limited'`. On `'trustline_required'`, set the returned trust line on
+   * the recipient and re-dispense with a fresh challenge.
+   */
+  async dispense(req) {
+    return this.http.post("/faucet/hsuite", req);
+  }
+  /**
+   * Get today's dispense status for a recipient (e.g. amount already
+   * dispensed today).
+   */
+  async getStatus(chain, recipientAddress) {
+    const params = new URLSearchParams();
+    params.append("chain", chain);
+    params.append("recipientAddress", recipientAddress);
+    return this.http.get(`/faucet/hsuite/status?${params.toString()}`);
+  }
+};
+
 // src/tss/index.ts
 var TSSClient = class {
   constructor(http) {
@@ -1826,80 +1924,105 @@ var TSSClient = class {
   }
   http;
   /**
-   * Create a multi-sig entity with TSS
+   * Create a multi-sig entity via a synchronous DKG ceremony.
+   *
+   * @param options Entity-creation parameters (chain, threshold, participants).
+   * @returns The created entity's identity (ids + group public keys).
    */
   async createEntity(options) {
     return this.http.post("/tss/entity/create", options);
   }
   /**
-   * Reshare keys when cluster membership changes.
-   * Redistributes secret shares WITHOUT changing public keys.
+   * Reshare keys when cluster membership changes. Redistributes secret shares
+   * WITHOUT changing public keys.
+   *
+   * @param request The new membership / threshold to reshare to.
+   * @returns The reshare outcome.
    */
   async reshareCluster(request) {
     return this.http.post("/tss/cluster/reshare", request);
   }
   /**
-   * Get entity details by ID
+   * Get entity details by id.
+   *
+   * @param entityId The entity id to look up.
+   * @returns The entity's details.
    */
   async getEntity(entityId) {
-    return this.http.get(`/tss/entity/${encodeURIComponent(entityId)}`);
+    return this.http.get(`/tss/entity/${encodePathParam(entityId)}`);
   }
   /**
    * Sign a transaction using MPC.
    *
    * Routes to `POST /api/v3/tss/hedera/sign-mpc`. Only `'hedera'` is wired
-   * server-side today (see
-   * `apps/smart-validator/src/tss/tss.controller.ts:279`); other chain
-   * signing paths run via their own controllers (XRPL multisig, Polkadot
-   * MPC) and are not exposed through this sub-client. The `chain` field is
-   * carried into the request body so the validator can log + route, but
-   * any non-`'hedera'` value will 404.
+   * server-side; other chain signing paths run via their own controllers (XRPL
+   * multisig, Polkadot MPC) and are not exposed through this sub-client. The
+   * `chain` field is carried into the request body so the validator can log +
+   * route, but any non-`'hedera'` value will 404.
+   *
+   * @param request The MPC signing request; `chain` is forced to `'hedera'`.
+   * @returns The MPC signing result.
    */
   async signMPC(request) {
     const chain = "hedera";
     return this.http.post(`/tss/${chain}/sign-mpc`, { ...request, chain });
   }
   /**
-   * Get known validators and their public keys
+   * Get known validators and their public keys.
+   *
+   * @returns The validator list with public keys.
    */
   async getValidators() {
     return this.http.get("/tss/validators");
   }
   /**
-   * Force announcement of this node's public key
+   * Force announcement of this node's public key.
+   *
+   * @returns Whether the announcement was accepted, plus a status message.
    */
   async announceKey() {
     return this.http.post("/tss/announce", {});
   }
   /**
-   * Get TSS statistics
+   * Get TSS statistics.
+   *
+   * @returns Aggregate TSS statistics.
    */
   async getStats() {
     return this.http.get("/tss/stats");
   }
   /**
-   * List all TSS entities
+   * List all TSS entities.
+   *
+   * @returns The full entity list.
    */
   async listEntities() {
     return this.http.get("/tss/entities");
   }
   /**
-   * TSS health check
+   * TSS health check.
+   *
+   * @returns The TSS subsystem health report.
    */
   async getHealth() {
     return this.http.get("/tss/health");
   }
   /**
-   * List DKG ceremonies and their statistics
+   * List DKG ceremonies and their statistics.
+   *
+   * @returns The ceremony list.
    */
   async listCeremonies() {
     return this.http.get("/tss/multisig/ceremonies");
   }
   /**
-   * Get multi-sig transaction status by transaction ID
+   * Get multi-sig transaction status by transaction id.
+   *
+   * @param txId The multi-sig transaction id.
+   * @returns The current status of that transaction.
    */
   async getMultiSigStatus(txId) {
-    return this.http.get(`/tss/multisig/transactions/${encodeURIComponent(txId)}`);
+    return this.http.get(`/tss/multisig/transactions/${encodePathParam(txId)}`);
   }
   /**
    * Async-job variant of {@link createEntity}.
@@ -1907,6 +2030,9 @@ var TSSClient = class {
    * Server returns 202 + `{ jobId, statusUrl, status: 'pending' }` immediately;
    * the DKG ceremony runs in the background. Poll {@link getJob} until the
    * status reaches `'success'` or `'failed'`.
+   *
+   * @param options Entity-creation parameters.
+   * @returns A job descriptor (`jobId`, `statusUrl`, initial status).
    */
   async createEntityAsync(options) {
     return this.http.post("/tss/entity/create/async", options);
@@ -1914,6 +2040,9 @@ var TSSClient = class {
   /**
    * Async-job variant of {@link reshareCluster}. Returns 202 + a polling
    * descriptor; resharing runs in the background.
+   *
+   * @param request The new membership / threshold to reshare to.
+   * @returns A job descriptor to poll via {@link getJob}.
    */
   async reshareClusterAsync(request) {
     return this.http.post("/tss/cluster/reshare/async", request);
@@ -1921,9 +2050,12 @@ var TSSClient = class {
   /**
    * Poll the status of an async TSS-ceremony job kicked off via
    * {@link createEntityAsync} or {@link reshareClusterAsync}.
+   *
+   * @param jobId The job id returned by the async kickoff call.
+   * @returns The job's current status (and result once terminal).
    */
   async getJob(jobId) {
-    return this.http.get(`/tss/jobs/${encodeURIComponent(jobId)}`);
+    return this.http.get(`/tss/jobs/${encodePathParam(jobId)}`);
   }
   /**
    * Sign a hex payload as smart-app entity `appId` via the cluster's TSS
@@ -1933,9 +2065,13 @@ var TSSClient = class {
    * Payload constraints (enforced server-side):
    *   - even-length lowercase hex
    *   - ≥32 bytes, ≤8KB
+   *
+   * @param appId The smart-app entity id to sign as.
+   * @param request The hex payload to sign.
+   * @returns The aggregate signature over the payload.
    */
   async signForApp(appId, request) {
-    return this.http.post(`/tss/entity/${encodeURIComponent(appId)}/sign`, request);
+    return this.http.post(`/tss/entity/${encodePathParam(appId)}/sign`, request);
   }
 };
 
@@ -1960,31 +2096,31 @@ var IPFSClient = class {
    * Pin content by CID to ensure it persists
    */
   async pin(cid) {
-    return this.http.post(`/ipfs/pin/${encodeURIComponent(cid)}`, {});
+    return this.http.post(`/ipfs/pin/${encodePathParam(cid)}`, {});
   }
   /**
    * Unpin content by CID
    */
   async unpin(cid) {
-    return this.http.delete(`/ipfs/unpin/${encodeURIComponent(cid)}`);
+    return this.http.delete(`/ipfs/unpin/${encodePathParam(cid)}`);
   }
   /**
    * Get a file by CID
    */
   async getFile(cid) {
-    return this.http.get(`/ipfs/file/${encodeURIComponent(cid)}`);
+    return this.http.get(`/ipfs/file/${encodePathParam(cid)}`);
   }
   /**
    * Get raw content by CID
    */
   async getContent(cid) {
-    return this.http.get(`/ipfs/${encodeURIComponent(cid)}`);
+    return this.http.get(`/ipfs/${encodePathParam(cid)}`);
   }
   /**
    * Get file metadata by CID
    */
   async getMetadata(cid) {
-    return this.http.get(`/ipfs/metadata/${encodeURIComponent(cid)}`);
+    return this.http.get(`/ipfs/metadata/${encodePathParam(cid)}`);
   }
   /**
    * List all pinned content
@@ -2042,7 +2178,7 @@ var HederaTssClient = class {
 var HederaTransactionsClient = class {
   constructor(http, tssHttp) {
     this.http = http;
-    this.tss = new HederaTssClient(tssHttp ?? http);
+    this.tss = new HederaTssClient(tssHttp);
   }
   http;
   /**
@@ -2053,10 +2189,10 @@ var HederaTransactionsClient = class {
    *   - `client.hedera.tss.createTopic(...)` makes the cluster sign+submit in one call.
    *
    * `tssHttp` is the validator's `/api/v3`-rooted HTTP client (different from
-   * the `/api/transactions` one this class uses for prepare paths). When the
-   * legacy single-arg constructor is used (no tssHttp passed), `tss` falls
-   * back to the same `http` instance for backwards compatibility — callers
-   * outside `SmartEngineClient` rarely use the TSS surface.
+   * the `/api/transactions` one this class uses for prepare paths). Both
+   * clients are required — the previous single-arg fallback to `http` was
+   * unreachable through `SmartEngineClient` (the only call site always
+   * passes both).
    */
   tss;
   /** Prepare an HCS topic creation transaction. */
@@ -2237,7 +2373,7 @@ var SnapshotsClient = class {
    */
   async generate(tokenId, options) {
     return this.http.post(
-      `/snapshots/generate/${encodeURIComponent(tokenId)}`,
+      `/snapshots/generate/${encodePathParam(tokenId)}`,
       options || {}
     );
   }
@@ -2245,7 +2381,7 @@ var SnapshotsClient = class {
    * Get snapshot details by ID
    */
   async get(snapshotId) {
-    return this.http.get(`/snapshots/${encodeURIComponent(snapshotId)}`);
+    return this.http.get(`/snapshots/${encodePathParam(snapshotId)}`);
   }
   /**
    * List snapshots for a token
@@ -2256,7 +2392,7 @@ var SnapshotsClient = class {
     if (pagination?.limit !== void 0) params.set("limit", String(pagination.limit));
     const qs = params.toString();
     return this.http.get(
-      `/snapshots/token/${encodeURIComponent(tokenId)}${qs ? `?${qs}` : ""}`
+      `/snapshots/token/${encodePathParam(tokenId)}${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -2268,7 +2404,7 @@ var SnapshotsClient = class {
   async download(snapshotId, format) {
     const params = format ? `?format=${encodeURIComponent(format)}` : "";
     return this.http.get(
-      `/snapshots/${encodeURIComponent(snapshotId)}/download${params}`
+      `/snapshots/${encodePathParam(snapshotId)}/download${params}`
     );
   }
 };
@@ -2451,20 +2587,20 @@ var SettlementClient = class {
    * Get the current status of a settlement by ID.
    */
   async getStatus(settlementId) {
-    return this.http.get(`/settlement/${encodeURIComponent(settlementId)}/status`);
+    return this.http.get(`/settlement/${encodePathParam(settlementId)}/status`);
   }
   /**
    * Confirm that XRP has landed on the destination address.
    * Advances the settlement to the next processing step.
    */
   async confirmXrpLanded(settlementId) {
-    return this.http.post(`/settlement/${encodeURIComponent(settlementId)}/confirm-xrp`, {});
+    return this.http.post(`/settlement/${encodePathParam(settlementId)}/confirm-xrp`, {});
   }
   /**
    * Get settlement history for a given entity.
    */
   async getHistory(entityId) {
-    return this.http.get(`/settlement/history/${encodeURIComponent(entityId)}`);
+    return this.http.get(`/settlement/history/${encodePathParam(entityId)}`);
   }
 };
 
@@ -2507,39 +2643,39 @@ var DaoDashboardClient = class {
   /** Aggregated dashboard counters for a user's governance home screen. */
   async getStats(userAddress) {
     return this.http.get(
-      `/dao/dashboard/stats/${encodeURIComponent(userAddress)}`
+      `/dao/dashboard/stats/${encodePathParam(userAddress)}`
     );
   }
   /** Active proposals across every DAO the user belongs to, with vote state. */
   async getActiveProposals(userAddress) {
     return this.http.get(
-      `/dao/dashboard/active-proposals/${encodeURIComponent(userAddress)}`
+      `/dao/dashboard/active-proposals/${encodePathParam(userAddress)}`
     );
   }
   /** Paginated vote history across DAOs. */
   async getVoteHistory(userAddress, opts = {}) {
     const qs = buildQuery({ limit: opts.limit, offset: opts.offset });
     return this.http.get(
-      `/dao/dashboard/vote-history/${encodeURIComponent(userAddress)}${qs}`
+      `/dao/dashboard/vote-history/${encodePathParam(userAddress)}${qs}`
     );
   }
   /** Activity feed (proposal-created/vote-cast/etc.) across user's DAOs. */
   async getActivity(userAddress, opts = {}) {
     const qs = buildQuery({ limit: opts.limit, daoId: opts.daoId });
     return this.http.get(
-      `/dao/dashboard/activity/${encodeURIComponent(userAddress)}${qs}`
+      `/dao/dashboard/activity/${encodePathParam(userAddress)}${qs}`
     );
   }
   /** Items the user must act on (sign prepared messages, claim NFTs, …). */
   async getPendingActions(userAddress) {
     return this.http.get(
-      `/dao/dashboard/pending-actions/${encodeURIComponent(userAddress)}`
+      `/dao/dashboard/pending-actions/${encodePathParam(userAddress)}`
     );
   }
   /** Governance impact metrics — weight delivered, success rate, streak. */
   async getImpact(userAddress) {
     return this.http.get(
-      `/dao/dashboard/impact/${encodeURIComponent(userAddress)}`
+      `/dao/dashboard/impact/${encodePathParam(userAddress)}`
     );
   }
 };
@@ -2555,13 +2691,13 @@ function buildQuery2(params) {
   return qs ? `?${qs}` : "";
 }
 function encodeDaoId(daoId) {
-  return encodeURIComponent(daoId);
+  return encodePathParam(daoId);
 }
 function encodeProposalId(proposalId) {
-  return encodeURIComponent(proposalId);
+  return encodePathParam(proposalId);
 }
 function encodeAddress(address) {
-  return encodeURIComponent(address);
+  return encodePathParam(address);
 }
 var DaoClient = class {
   constructor(http) {
@@ -2767,7 +2903,7 @@ var AgentsClient = class {
   }
   /** Get agent details */
   async get(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}`);
+    return this.http.get(`/api/agents/${encodePathParam(agentId)}`);
   }
   /** List all agents */
   async list() {
@@ -2779,33 +2915,33 @@ var AgentsClient = class {
    * the caller is expected to sign and submit the prepared bytes.
    */
   async fund(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/fund`, request);
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/fund`, request);
   }
   /**
    * Execute a trade (agent-wallet OR owner). Returns a
    * `PreparedTransactionResponse` wrapped in a `success: true` envelope.
    */
   async trade(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/trade`, request);
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/trade`, request);
   }
   /**
    * Withdraw from agent treasury (owner-only). Returns a
    * `PreparedTransactionResponse` wrapped in a `success: true` envelope.
    */
   async withdraw(agentId, request) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/withdraw`, request);
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/withdraw`, request);
   }
   /** Pause an agent */
   async pause(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/pause`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/pause`, {});
   }
   /** Resume a paused agent */
   async resume(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/resume`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/resume`, {});
   }
   /** Revoke an agent (permanent) */
   async revoke(agentId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/revoke`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/revoke`, {});
   }
   /**
    * Update agent rules.
@@ -2816,23 +2952,23 @@ var AgentsClient = class {
    * the verb mismatch.
    */
   async updateRules(agentId, rules) {
-    return this.http.patch(`/api/agents/${encodeURIComponent(agentId)}/rules`, rules);
+    return this.http.patch(`/api/agents/${encodePathParam(agentId)}/rules`, rules);
   }
   /** Get agent events */
   async getEvents(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}/events`);
+    return this.http.get(`/api/agents/${encodePathParam(agentId)}/events`);
   }
   /** Get agent balances across chains */
   async getBalances(agentId) {
-    return this.http.get(`/api/agents/${encodeURIComponent(agentId)}/balances`);
+    return this.http.get(`/api/agents/${encodePathParam(agentId)}/balances`);
   }
   /** Approve a pending agent operation */
   async approve(agentId, operationId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/approve/${encodeURIComponent(operationId)}`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/approve/${encodePathParam(operationId)}`, {});
   }
   /** Reject a pending agent operation */
   async reject(agentId, operationId) {
-    return this.http.post(`/api/agents/${encodeURIComponent(agentId)}/reject/${encodeURIComponent(operationId)}`, {});
+    return this.http.post(`/api/agents/${encodePathParam(agentId)}/reject/${encodePathParam(operationId)}`, {});
   }
 };
 
@@ -2871,7 +3007,7 @@ var DeploymentClient = class {
    */
   async uploadFrontend(appId, bundle, filename = "bundle.tar.gz") {
     return this.http.upload(
-      `/api/deployment/apps/${encodeURIComponent(appId)}/frontend`,
+      `/api/deployment/apps/${encodePathParam(appId)}/frontend`,
       bundle,
       filename,
       void 0,
@@ -2885,20 +3021,20 @@ var DeploymentClient = class {
    * until `runtime.runtimeState === 'RUNNING'` for the URL to be live.
    */
   async deploy(appId, request) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/deploy`, request);
+    return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/deploy`, request);
   }
   /**
    * Roll back to a previously-deployed image tag (must exist in
    * `runtime.deploymentHistory[]`).
    */
   async rollback(appId, request) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/rollback`, request);
+    return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/rollback`, request);
   }
   /**
    * Live combined lifecycle + runtime status of an app.
    */
   async status(appId) {
-    return this.http.get(`/api/deployment/apps/${encodeURIComponent(appId)}/status`);
+    return this.http.get(`/api/deployment/apps/${encodePathParam(appId)}/status`);
   }
   /**
    * List all deployed apps for the authenticated developer.
@@ -2910,31 +3046,35 @@ var DeploymentClient = class {
    * Get app details.
    */
   async get(appId) {
-    return this.http.get(`/api/deployment/apps/${encodeURIComponent(appId)}`);
+    return this.http.get(`/api/deployment/apps/${encodePathParam(appId)}`);
   }
   /**
-   * Update app configuration. Runtime effect lands in PR-H.
+   * Update app configuration.
+   *
+   * @param appId - The app to update.
+   * @param updates - Partial deploy-request fields to apply.
+   * @returns The updated app info.
    */
   async update(appId, updates) {
-    return this.http.put(`/api/deployment/apps/${encodeURIComponent(appId)}`, updates);
+    return this.http.put(`/api/deployment/apps/${encodePathParam(appId)}`, updates);
   }
   /**
-   * Delete an app. Runtime effect (namespace teardown) lands in PR-H.
+   * Delete an app (runtime effect: namespace teardown).
    */
   async delete(appId) {
-    return this.http.delete(`/api/deployment/apps/${encodeURIComponent(appId)}`);
+    return this.http.delete(`/api/deployment/apps/${encodePathParam(appId)}`);
   }
   /**
-   * Suspend an app. Runtime effect (scale to zero) lands in PR-H.
+   * Suspend an app (runtime effect: scale to zero).
    */
   async suspend(appId) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/suspend`, {});
+    return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/suspend`, {});
   }
   /**
-   * Resume a suspended app. Runtime effect (scale back up) lands in PR-H.
+   * Resume a suspended app (runtime effect: scale back up).
    */
   async resume(appId) {
-    return this.http.post(`/api/deployment/apps/${encodeURIComponent(appId)}/resume`, {});
+    return this.http.post(`/api/deployment/apps/${encodePathParam(appId)}/resume`, {});
   }
   /**
    * Get deployment statistics.
@@ -2961,7 +3101,7 @@ var DeploymentClient = class {
    * CGNAT / cloud metadata destinations (SSRF guard).
    */
   async setWebhook(appId, webhookUrl) {
-    return this.http.put(`/api/deployment/apps/${encodeURIComponent(appId)}/webhook`, {
+    return this.http.put(`/api/deployment/apps/${encodePathParam(appId)}/webhook`, {
       webhookUrl
     });
   }
@@ -2977,10 +3117,10 @@ var DeploymentClient = class {
    * exposition format.
    */
   async getMetrics(appId) {
-    return this.http.getText(`/api/deployment/apps/${encodeURIComponent(appId)}/metrics`);
+    return this.http.getText(`/api/deployment/apps/${encodePathParam(appId)}/metrics`);
   }
   /**
-   * Rotate the smart-app's tenant-secret KEK (ADR-011 Phase 6).
+   * Rotate the smart-app's tenant-secret KEK.
    *
    * Re-encrypts every `runtime.env` envelope at the new KEK version
    * transparently. Previous versions remain valid until explicitly
@@ -2988,12 +3128,12 @@ var DeploymentClient = class {
    */
   async rotateKek(appId) {
     return this.http.post(
-      `/api/deployment/apps/${encodeURIComponent(appId)}/credentials/rotate-kek`,
+      `/api/deployment/apps/${encodePathParam(appId)}/credentials/rotate-kek`,
       {}
     );
   }
   /**
-   * Revoke a tenant-secret KEK version (ADR-011 Phase 6 emergency burn).
+   * Revoke a tenant-secret KEK version (emergency burn).
    *
    * Envelopes at the revoked version become operationally dead —
    * decryption inside the smart-app pod fails. Owner-only and
@@ -3002,7 +3142,7 @@ var DeploymentClient = class {
    */
   async revokeKek(appId, version) {
     return this.http.post(
-      `/api/deployment/apps/${encodeURIComponent(appId)}/credentials/revoke-kek`,
+      `/api/deployment/apps/${encodePathParam(appId)}/credentials/revoke-kek`,
       { version }
     );
   }
@@ -3182,16 +3322,6 @@ var TokensClient = class {
   async getMigrationsForToken(tokenId) {
     return this.http.get(`/tokens/${encodePathParam(tokenId)}/migrations`);
   }
-  /**
-   * Get token details. NOTE: collides with `client.getTokenInfo(...)` —
-   * see the class JSDoc above for the route-order details. Prefer
-   * `client.getTokenInfo(...)` unless you have a reason to call this one.
-   */
-  async getDetails(chain, tokenId) {
-    return this.http.get(
-      `/tokens/${encodePathParam(chain)}/${encodePathParam(tokenId)}`
-    );
-  }
 };
 
 // src/operator/operator-client.ts
@@ -3226,6 +3356,8 @@ var SmartEngineClient = class _SmartEngineClient {
   // ========== Sub-Clients ==========
   /** Application subscription management */
   subscription;
+  /** Testnet HST faucet (challenge -> sign -> dispense) */
+  faucet;
   /** Threshold Signature Scheme — chain-agnostic MPC operations */
   tss;
   /** IPFS decentralized file storage */
@@ -3284,6 +3416,7 @@ var SmartEngineClient = class _SmartEngineClient {
       timeout: config.timeout
     });
     this.subscription = new SubscriptionClient(this.http);
+    this.faucet = new FaucetClient(this.http);
     this.tss = new TSSClient(this.http);
     this.ipfs = new IPFSClient(this.http);
     this.transactions = new TransactionsClient(this.txHttp);
@@ -3339,13 +3472,17 @@ var SmartEngineClient = class _SmartEngineClient {
     });
   }
   /**
-   * Connect to the smart-engines network with auto-discovery and authentication
+   * Connect to the smart-engines network with auto-discovery and authentication.
    *
-   * This method:
-   * 1. Discovers validators via HCS registry topic
-   * 2. Selects a random validator with API endpoint
-   * 3. Authenticates with Web3-style challenge-response
-   * 4. Returns a configured client ready to use
+   * Steps:
+   * 1. Discovers validators via the HCS registry topic.
+   * 2. Selects a random validator with an API endpoint.
+   * 3. Authenticates with Web3-style challenge-response.
+   * 4. Returns a configured client ready to use.
+   *
+   * @param config - Network, registry topic, and auth signer config.
+   * @returns The configured client, the chosen validator, and the auth session.
+   * @throws SmartEngineError 503 if no validator with an API endpoint is found.
    */
   static async connectToNetwork(config) {
     const allowInsecure = config.allowInsecure ?? false;
@@ -3382,18 +3519,22 @@ 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.
+   * Connect to the smart-engines network via the **service-registry**.
+   * 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):
+   * Resolution ladder:
    *   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.
    *
+   * @param config - Seed + auth config. See {@link ClusterConnectionConfig}.
+   * @returns The configured client, the selected cluster, and the auth session.
+   * @throws SmartEngineError 400 if neither `bootstrap` nor `network` is given.
+   * @throws SmartEngineError 503 if no active cluster can be reached.
+   *
    * @example Zero-config (recommended for smart-app callers)
    * ```ts
    * const { client, cluster, session } = await SmartEngineClient.connectToCluster({
@@ -3418,30 +3559,25 @@ var SmartEngineClient = class _SmartEngineClient {
    */
   static async connectToCluster(config) {
     const allowInsecure = config.allowInsecure ?? false;
-    const bootstrap = config.bootstrap ? [...config.bootstrap] : [...resolveNetwork(config.network).bootstrap];
-    if (bootstrap.length === 0) {
-      throw new SmartEngineError(
-        "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
-        400
-      );
-    }
-    const discovery = new ClusterDiscoveryClient({
-      bootstrap,
+    const resolved = await resolveClusterEndpoint({
+      bootstrap: config.bootstrap,
+      network: config.network,
       allowInsecure,
-      trustAnchor: config.trustAnchor ? {
-        network: config.trustAnchor.network,
-        registryTopicId: config.trustAnchor.registryTopicId,
-        mirrorNodeUrl: config.trustAnchor.mirrorNodeUrl,
-        allowInsecure
-      } : void 0
+      trustAnchor: config.trustAnchor
     });
-    const cluster = await discovery.getRandomCluster();
-    if (!cluster) {
+    if (!resolved.ok) {
+      if (resolved.reason === "no-seeds") {
+        throw new SmartEngineError(
+          "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
+          400
+        );
+      }
       throw new SmartEngineError(
         "No active clusters available via bootstrap seeds. Check bootstrap URLs and network reachability.",
         503
       );
     }
+    const cluster = resolved.cluster;
     const gatewayUrl = cluster.endpoints.gatewayUrl;
     validateClientUrl(gatewayUrl, allowInsecure);
     const auth = new ValidatorAuthClient({ security: { allowInsecure } });
@@ -3466,7 +3602,7 @@ var SmartEngineClient = class _SmartEngineClient {
   }
   /** Check if client has an auth token */
   isAuthenticated() {
-    return !!this.http.authToken;
+    return this.http.getAuthToken() !== void 0;
   }
   /**
    * Get HTTP resilience health information
@@ -3527,17 +3663,11 @@ var SmartEngineClient = class _SmartEngineClient {
     return this.http.post("/tokens/mint", validated);
   }
   /**
-   * Get token information.
+   * Get token information for a token on the given chain.
    *
-   * Route `GET /api/v3/tokens/:chain/:tokenId` is registered twice on the
-   * validator: by `ValidatorController` at
-   * `apps/smart-validator/src/validator.controller.ts:497` and by
-   * `TokenMigrationController` at
-   * `apps/smart-validator/src/token-migration/token-migration.controller.ts:173`.
-   * Nest resolves routes in `controllers: [...]` order — `ValidatorController`
-   * is registered first (`apps/smart-validator/src/smart-validator.module.ts:1222`),
-   * so `multiChain.getTokenInfo(chain, tokenId)` wins and the
-   * token-migration handler is unreachable via this path.
+   * @param chain - Chain identifier (e.g. `'hedera'`, `'xrpl'`).
+   * @param tokenId - Chain-native token identifier.
+   * @returns Token metadata and supply information.
    */
   async getTokenInfo(chain, tokenId) {
     return this.http.get(`/tokens/${encodePathParam(chain)}/${encodePathParam(tokenId)}`);
@@ -3697,7 +3827,7 @@ var RoutingClient = class {
   }
   /** Unregister a host. */
   async unregisterHost(hostId) {
-    return this.http.delete(`/routing/hosts/${encodeURIComponent(hostId)}`);
+    return this.http.delete(`/routing/hosts/${encodePathParam(hostId)}`);
   }
   /** Get all registered hosts. */
   async getAllHosts() {
@@ -3709,19 +3839,19 @@ var RoutingClient = class {
   }
   /** Get a specific host by ID. */
   async getHost(hostId) {
-    return this.http.get(`/routing/hosts/${encodeURIComponent(hostId)}`);
+    return this.http.get(`/routing/hosts/${encodePathParam(hostId)}`);
   }
   /** Trigger host re-verification. */
   async verifyHost(hostId) {
-    return this.http.post(`/routing/hosts/${encodeURIComponent(hostId)}/verify`, {});
+    return this.http.post(`/routing/hosts/${encodePathParam(hostId)}/verify`, {});
   }
   /** Set routing configuration for an app. */
   async setRoutingConfig(appId, config) {
-    return this.http.put(`/routing/config/${encodeURIComponent(appId)}`, config);
+    return this.http.put(`/routing/config/${encodePathParam(appId)}`, config);
   }
   /** Get routing configuration for an app. */
   async getRoutingConfig(appId) {
-    return this.http.get(`/routing/config/${encodeURIComponent(appId)}`);
+    return this.http.get(`/routing/config/${encodePathParam(appId)}`);
   }
   /** Proxy a request through the gateway. */
   async proxyRequest(request) {
@@ -3737,7 +3867,7 @@ var RoutingClient = class {
    * field; treat `appId` as the success signal.
    */
   async mapDomainToApp(domain, appId) {
-    return this.http.post(`/routing/domains/${encodeURIComponent(domain)}/map`, { appId });
+    return this.http.post(`/routing/domains/${encodePathParam(domain)}/map`, { appId });
   }
 };
 
@@ -3753,11 +3883,11 @@ var DomainsClient = class {
   }
   /** Check domain availability */
   async checkAvailability(domain) {
-    return this.http.get(`/domains/check/${encodeURIComponent(domain)}`);
+    return this.http.get(`/domains/check/${encodePathParam(domain)}`);
   }
   /** Get domain information */
   async getInfo(domain) {
-    return this.http.get(`/domains/${encodeURIComponent(domain)}`);
+    return this.http.get(`/domains/${encodePathParam(domain)}`);
   }
   /** List domains, optionally filtered by owner */
   async list(owner) {
@@ -3766,51 +3896,50 @@ var DomainsClient = class {
   }
   /**
    * Generate a verification token. Server accepts one of `dns-txt`,
-   * `dns-cname`, `http-file`, `email` (see controller Swagger enum at
-   * `apps/smart-gateway/src/domains/domains.controller.ts:226-234`).
+   * `dns-cname`, `http-file`, `email`.
    */
   async generateVerificationToken(domain, method) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/verification`, { method });
+    return this.http.post(`/domains/${encodePathParam(domain)}/verification`, { method });
   }
   /** Verify domain ownership */
   async verifyOwnership(domain, token) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/verify`, { token });
+    return this.http.post(`/domains/${encodePathParam(domain)}/verify`, { token });
   }
   /** Configure DNS records for a domain */
   async configureDns(domain, records) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/dns`, { records });
+    return this.http.post(`/domains/${encodePathParam(domain)}/dns`, { records });
   }
   /** Enable DNSSEC for a domain */
   async enableDnssec(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/dnssec/enable`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/dnssec/enable`, {});
   }
   /** Disable DNSSEC for a domain */
   async disableDnssec(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/dnssec/disable`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/dnssec/disable`, {});
   }
   /** Renew a domain */
   async renew(domain, years) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/renew`, { years: years ?? 1 });
+    return this.http.post(`/domains/${encodePathParam(domain)}/renew`, { years: years ?? 1 });
   }
   /** Initiate a domain transfer */
   async transfer(domain, request) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/transfer`, request);
+    return this.http.post(`/domains/${encodePathParam(domain)}/transfer`, request);
   }
   /** Approve a pending domain transfer */
   async approveTransfer(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/transfer/approve`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/transfer/approve`, {});
   }
   /** Reject a pending domain transfer */
   async rejectTransfer(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/transfer/reject`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/transfer/reject`, {});
   }
   /** Suspend a domain */
   async suspend(domain, reason) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/suspend`, { reason });
+    return this.http.post(`/domains/${encodePathParam(domain)}/suspend`, { reason });
   }
   /** Unsuspend a domain */
   async unsuspend(domain) {
-    return this.http.post(`/domains/${encodeURIComponent(domain)}/unsuspend`, {});
+    return this.http.post(`/domains/${encodePathParam(domain)}/unsuspend`, {});
   }
 };
 
@@ -3837,7 +3966,7 @@ var DnsClient = class {
   }
   /** Get a specific zone */
   async getZone(zoneName) {
-    return this.http.get(`/dns/zones/${encodeURIComponent(zoneName)}`);
+    return this.http.get(`/dns/zones/${encodePathParam(zoneName)}`);
   }
   /** Create a new DNS zone */
   async createZone(request) {
@@ -3845,38 +3974,38 @@ var DnsClient = class {
   }
   /** Delete a DNS zone */
   async deleteZone(zoneName) {
-    return this.http.delete(`/dns/zones/${encodeURIComponent(zoneName)}`);
+    return this.http.delete(`/dns/zones/${encodePathParam(zoneName)}`);
   }
   /** Add a record to a zone */
   async addRecord(zoneName, record) {
-    return this.http.post(`/dns/zones/${encodeURIComponent(zoneName)}/records`, record);
+    return this.http.post(`/dns/zones/${encodePathParam(zoneName)}/records`, record);
   }
   /** Update a record in a zone */
   async updateRecord(zoneName, recordId, updates) {
     return this.http.put(
-      `/dns/zones/${encodeURIComponent(zoneName)}/records/${encodeURIComponent(recordId)}`,
+      `/dns/zones/${encodePathParam(zoneName)}/records/${encodePathParam(recordId)}`,
       updates
     );
   }
   /** Delete a record from a zone */
   async deleteRecord(zoneName, recordId) {
     return this.http.delete(
-      `/dns/zones/${encodeURIComponent(zoneName)}/records/${encodeURIComponent(recordId)}`
+      `/dns/zones/${encodePathParam(zoneName)}/records/${encodePathParam(recordId)}`
     );
   }
   /** Generate DNSSEC keys for a zone */
   async generateDnssecKeys(zoneName, algorithm) {
-    return this.http.post(`/dns/zones/${encodeURIComponent(zoneName)}/dnssec/keys`, {
+    return this.http.post(`/dns/zones/${encodePathParam(zoneName)}/dnssec/keys`, {
       algorithm
     });
   }
   /** Get DNSSEC keys for a zone */
   async getDnssecKeys(zoneName) {
-    return this.http.get(`/dns/zones/${encodeURIComponent(zoneName)}/dnssec/keys`);
+    return this.http.get(`/dns/zones/${encodePathParam(zoneName)}/dnssec/keys`);
   }
   /** Get DS record for a zone (for registrar configuration) */
   async getDsRecord(zoneName) {
-    return this.http.get(`/dns/zones/${encodeURIComponent(zoneName)}/dnssec/ds`);
+    return this.http.get(`/dns/zones/${encodePathParam(zoneName)}/dnssec/ds`);
   }
   /** Clear DNS cache */
   async clearCache() {
@@ -3891,10 +4020,8 @@ var HealthClient = class {
   }
   http;
   /**
-   * Per-cluster aggregate health probe. Wraps
-   * `GET /api/v3/cluster/health` — see
-   * `apps/smart-gateway/src/health/health.controller.ts:213-263`. Returns
-   * local validator + host + genesis state in a single payload.
+   * Per-cluster aggregate health probe. Wraps `GET /api/v3/cluster/health`.
+   * Returns local validator + host + genesis state in a single payload.
    */
   async getCluster() {
     return this.http.get("/cluster/health");
@@ -3977,7 +4104,7 @@ var DatabaseClient = class {
   async insert(collection, document) {
     const appId = this.getAppId();
     return this.http.post(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(collection)}`,
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(collection)}`,
       document
     );
   }
@@ -3995,7 +4122,7 @@ var DatabaseClient = class {
     if (options?.sort) params.set("sort", options.sort);
     const qs = params.toString();
     return this.http.get(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(collection)}${qs ? `?${qs}` : ""}`
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(collection)}${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -4004,7 +4131,7 @@ var DatabaseClient = class {
   async update(collection, documentId, updates) {
     const appId = this.getAppId();
     return this.http.put(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(collection)}/${encodeURIComponent(documentId)}`,
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(collection)}/${encodePathParam(documentId)}`,
       updates
     );
   }
@@ -4014,7 +4141,7 @@ var DatabaseClient = class {
   async delete(collection, documentId) {
     const appId = this.getAppId();
     return this.http.delete(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(collection)}/${encodeURIComponent(documentId)}`
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(collection)}/${encodePathParam(documentId)}`
     );
   }
   /**
@@ -4026,7 +4153,7 @@ var DatabaseClient = class {
    */
   async listCollections() {
     const appId = this.getAppId();
-    return this.http.get(`/api/db/${encodeURIComponent(appId)}/collections`);
+    return this.http.get(`/api/db/${encodePathParam(appId)}/collections`);
   }
   /**
    * Create a new collection in the database.
@@ -4036,7 +4163,7 @@ var DatabaseClient = class {
    */
   async createCollection(name) {
     const appId = this.getAppId();
-    return this.http.post(`/api/db/${encodeURIComponent(appId)}/collections`, { name });
+    return this.http.post(`/api/db/${encodePathParam(appId)}/collections`, { name });
   }
   /**
    * Drop a collection and all its documents.
@@ -4047,7 +4174,7 @@ var DatabaseClient = class {
   async dropCollection(name) {
     const appId = this.getAppId();
     return this.http.delete(
-      `/api/db/${encodeURIComponent(appId)}/collections/${encodeURIComponent(name)}`
+      `/api/db/${encodePathParam(appId)}/collections/${encodePathParam(name)}`
     );
   }
   // ========== State Proofs ==========
@@ -4056,7 +4183,7 @@ var DatabaseClient = class {
    */
   async getStateRoot() {
     const appId = this.getAppId();
-    return this.http.get(`/api/db/${encodeURIComponent(appId)}/state/root`);
+    return this.http.get(`/api/db/${encodePathParam(appId)}/state/root`);
   }
   /**
    * Get a Merkle proof for a specific document
@@ -4064,7 +4191,7 @@ var DatabaseClient = class {
   async getDocumentProof(documentId) {
     const appId = this.getAppId();
     return this.http.get(
-      `/api/db/${encodeURIComponent(appId)}/${encodeURIComponent(documentId)}/proof`
+      `/api/db/${encodePathParam(appId)}/${encodePathParam(documentId)}/proof`
     );
   }
   /**
@@ -4078,7 +4205,7 @@ var DatabaseClient = class {
     if (options?.limit !== void 0) params.set("limit", String(options.limit));
     const qs = params.toString();
     return this.http.get(
-      `/api/db/${encodeURIComponent(appId)}/state/transitions${qs ? `?${qs}` : ""}`
+      `/api/db/${encodePathParam(appId)}/state/transitions${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -4086,7 +4213,7 @@ var DatabaseClient = class {
    */
   async getDbStats() {
     const appId = this.getAppId();
-    return this.http.get(`/api/db/${encodeURIComponent(appId)}/stats`);
+    return this.http.get(`/api/db/${encodePathParam(appId)}/stats`);
   }
 };
 
@@ -4103,47 +4230,35 @@ var StorageClient = class {
    */
   async upload(file, filename, metadata) {
     const appId = this.getAppId();
-    return this.http.upload(`/api/storage/${encodeURIComponent(appId)}/upload`, file, filename, metadata);
+    return this.http.upload(`/api/storage/${encodePathParam(appId)}/upload`, file, filename, metadata);
   }
   /**
    * Download a file by CID
    */
   async download(cid) {
     const appId = this.getAppId();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/download/${encodeURIComponent(cid)}`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/download/${encodePathParam(cid)}`);
   }
   /**
    * Get file metadata
    */
   async getMetadata(cid) {
     const appId = this.getAppId();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/metadata/${encodeURIComponent(cid)}`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/metadata/${encodePathParam(cid)}`);
   }
   /**
    * Delete a file
    */
   async delete(cid) {
     const appId = this.getAppId();
-    return this.http.delete(`/api/storage/${encodeURIComponent(appId)}/${encodeURIComponent(cid)}`);
+    return this.http.delete(`/api/storage/${encodePathParam(appId)}/${encodePathParam(cid)}`);
   }
   /**
-   * Get file info.
+   * List all files for the app.
    *
-   * @deprecated The smart-host storage controller does not expose a
-   * bare-CID metadata route — every metadata lookup must go through
-   * `getMetadata(cid)` (`/api/storage/:appId/metadata/:cid`) or the
-   * stream body via `download(cid)`. This alias forwards to `download`
-   * for back-compat; remove in the next major SDK release.
-   */
-  async getFile(cid) {
-    return this.download(cid);
-  }
-  /**
-   * List all files for the app
-   *
-   * @param pagination.offset Server reads `offset`; the legacy `skip`
-   *   option was a client-only synonym that the server silently ignored.
-   *   Use `offset` going forward.
+   * @param pagination - Optional `limit` and `offset` (the server reads
+   *   `offset` for pagination).
+   * @returns The file list and total count.
    */
   async listFiles(pagination) {
     const appId = this.getAppId();
@@ -4151,21 +4266,21 @@ var StorageClient = class {
     if (pagination?.limit !== void 0) params.set("limit", String(pagination.limit));
     if (pagination?.offset !== void 0) params.set("offset", String(pagination.offset));
     const qs = params.toString();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/files${qs ? `?${qs}` : ""}`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/files${qs ? `?${qs}` : ""}`);
   }
   /**
    * Get storage usage for the current app
    */
   async getUsage() {
     const appId = this.getAppId();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/usage`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/usage`);
   }
   /**
    * Check if a file exists
    */
   async exists(cid) {
     const appId = this.getAppId();
-    return this.http.get(`/api/storage/${encodeURIComponent(appId)}/exists/${encodeURIComponent(cid)}`);
+    return this.http.get(`/api/storage/${encodePathParam(appId)}/exists/${encodePathParam(cid)}`);
   }
 };
 
@@ -4182,7 +4297,7 @@ var FunctionsClient = class {
    */
   async deploy(request) {
     const appId = this.getAppId();
-    return this.http.post(`/api/functions/${encodeURIComponent(appId)}`, request);
+    return this.http.post(`/api/functions/${encodePathParam(appId)}`, request);
   }
   /**
    * Invoke a function
@@ -4190,7 +4305,7 @@ var FunctionsClient = class {
   async invoke(functionId, payload) {
     const appId = this.getAppId();
     return this.http.post(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}/invoke`,
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}/invoke`,
       payload ?? {}
     );
   }
@@ -4199,7 +4314,7 @@ var FunctionsClient = class {
    */
   async list() {
     const appId = this.getAppId();
-    return this.http.get(`/api/functions/${encodeURIComponent(appId)}`);
+    return this.http.get(`/api/functions/${encodePathParam(appId)}`);
   }
   /**
    * Get function details
@@ -4207,7 +4322,7 @@ var FunctionsClient = class {
   async get(functionId) {
     const appId = this.getAppId();
     return this.http.get(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}`
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}`
     );
   }
   /**
@@ -4216,7 +4331,7 @@ var FunctionsClient = class {
   async update(functionId, updates) {
     const appId = this.getAppId();
     return this.http.put(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}`,
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}`,
       updates
     );
   }
@@ -4226,7 +4341,7 @@ var FunctionsClient = class {
   async delete(functionId) {
     const appId = this.getAppId();
     return this.http.delete(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}`
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}`
     );
   }
   /**
@@ -4240,7 +4355,7 @@ var FunctionsClient = class {
     if (options?.level) params.set("level", options.level);
     const qs = params.toString();
     return this.http.get(
-      `/api/functions/${encodeURIComponent(appId)}/${encodeURIComponent(functionId)}/logs${qs ? `?${qs}` : ""}`
+      `/api/functions/${encodePathParam(appId)}/${encodePathParam(functionId)}/logs${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -4248,7 +4363,7 @@ var FunctionsClient = class {
    */
   async getStats() {
     const appId = this.getAppId();
-    return this.http.get(`/api/functions/${encodeURIComponent(appId)}/stats`);
+    return this.http.get(`/api/functions/${encodePathParam(appId)}/stats`);
   }
 };
 
@@ -4265,28 +4380,28 @@ var MessagingClient = class {
    */
   async createChannel(config) {
     const appId = this.getAppId();
-    return this.http.post(`/api/messaging/${encodeURIComponent(appId)}/channels`, config);
+    return this.http.post(`/api/messaging/${encodePathParam(appId)}/channels`, config);
   }
   /**
    * Delete a channel
    */
   async deleteChannel(channelId) {
     const appId = this.getAppId();
-    return this.http.delete(`/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channelId)}`);
+    return this.http.delete(`/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channelId)}`);
   }
   /**
    * Get a channel by ID
    */
   async getChannel(channelId) {
     const appId = this.getAppId();
-    return this.http.get(`/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channelId)}`);
+    return this.http.get(`/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channelId)}`);
   }
   /**
    * List all channels for the app
    */
   async listChannels() {
     const appId = this.getAppId();
-    return this.http.get(`/api/messaging/${encodeURIComponent(appId)}/channels`);
+    return this.http.get(`/api/messaging/${encodePathParam(appId)}/channels`);
   }
   /**
    * Publish a message to a channel
@@ -4294,7 +4409,7 @@ var MessagingClient = class {
   async publish(channel, message, metadata) {
     const appId = this.getAppId();
     return this.http.post(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/publish`,
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/publish`,
       { data: message, metadata }
     );
   }
@@ -4309,7 +4424,7 @@ var MessagingClient = class {
     if (options?.after) params.set("after", options.after);
     const qs = params.toString();
     return this.http.get(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/history${qs ? `?${qs}` : ""}`
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/history${qs ? `?${qs}` : ""}`
     );
   }
   /**
@@ -4323,7 +4438,7 @@ var MessagingClient = class {
   async setPresence(channel, member) {
     const appId = this.getAppId();
     return this.http.post(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/presence`,
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/presence`,
       member
     );
   }
@@ -4339,7 +4454,7 @@ var MessagingClient = class {
   async removePresence(channel, clientId) {
     const appId = this.getAppId();
     return this.http.delete(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/presence/${encodeURIComponent(clientId)}`
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/presence/${encodePathParam(clientId)}`
     );
   }
   /**
@@ -4348,7 +4463,7 @@ var MessagingClient = class {
   async getPresence(channel) {
     const appId = this.getAppId();
     return this.http.get(
-      `/api/messaging/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/presence`
+      `/api/messaging/${encodePathParam(appId)}/channels/${encodePathParam(channel)}/presence`
     );
   }
   /**
@@ -4356,7 +4471,7 @@ var MessagingClient = class {
    */
   async getStats() {
     const appId = this.getAppId();
-    return this.http.get(`/api/messaging/${encodeURIComponent(appId)}/stats`);
+    return this.http.get(`/api/messaging/${encodePathParam(appId)}/stats`);
   }
 };
 
@@ -4444,7 +4559,7 @@ var RulesClient = class {
   }
   /** Fetch a published rule by its HCS consensus timestamp. */
   async get(consensusTimestamp) {
-    return this.http.get(`/api/rules/${encodeURIComponent(consensusTimestamp)}`);
+    return this.http.get(`/api/rules/${encodePathParam(consensusTimestamp)}`);
   }
   /** List rules owned by the authenticated entity, optionally filtered by type. */
   async listByOwner(filter) {
@@ -4461,13 +4576,13 @@ var RulesClient = class {
   /** Walk the version history of a published rule. */
   async getVersionHistory(consensusTimestamp) {
     return this.http.get(
-      `/api/rules/${encodeURIComponent(consensusTimestamp)}/versions`
+      `/api/rules/${encodePathParam(consensusTimestamp)}/versions`
     );
   }
   /** Deprecate a published rule (owner-only). */
   async deprecate(consensusTimestamp) {
     return this.http.post(
-      `/api/rules/${encodeURIComponent(consensusTimestamp)}/deprecate`,
+      `/api/rules/${encodePathParam(consensusTimestamp)}/deprecate`,
       {}
     );
   }
@@ -4505,7 +4620,7 @@ var EntitiesClient = class {
   }
   /** Fetch an entity by its canonical `entityId`. */
   async get(entityId) {
-    return this.http.get(`/api/entities/${encodeURIComponent(entityId)}`);
+    return this.http.get(`/api/entities/${encodePathParam(entityId)}`);
   }
   /** List entities owned by the authenticated wallet, optionally filtered by type. */
   async listByOwner(filter) {
@@ -4521,10 +4636,16 @@ var BaasClient = class _BaasClient {
   appId;
   timeout;
   allowInsecure;
-  authToken = null;
   http;
   /** Last HTTP error (for getHttpHealth) */
   lastHttpError;
+  /**
+   * Auth options from the last {@link authenticate} call, retained so the
+   * client can transparently re-authenticate when the session token expires
+   * (the http client invokes {@link reauthenticate} on a 401). Undefined until
+   * the first successful authenticate.
+   */
+  authContext;
   // ========== Sub-Clients ==========
   /** Trustless database with state proofs and Merkle verification */
   db;
@@ -4554,7 +4675,11 @@ var BaasClient = class _BaasClient {
     const baseUrlWithPrefix = this.pathPrefix ? this.hostUrl.replace(/\/$/, "") + this.pathPrefix : this.hostUrl;
     this.http = createHttpClient({
       baseUrl: baseUrlWithPrefix,
-      timeout: this.timeout
+      timeout: this.timeout,
+      // Transparent session refresh: on a 401, re-run the challenge-response
+      // with the retained signer and retry once. No-op until authenticate() has
+      // been called (authContext set). Excludes /api/auth/* (see http client).
+      onUnauthorized: () => this.reauthenticate()
     });
     const getAppId = () => this.requireAppId();
     this.db = new DatabaseClient(this.http, getAppId);
@@ -4608,30 +4733,25 @@ var BaasClient = class _BaasClient {
    */
   static async connectToCluster(config) {
     const allowInsecure = config.allowInsecure ?? false;
-    const bootstrap = config.bootstrap ? [...config.bootstrap] : [...resolveNetwork(config.network).bootstrap];
-    if (bootstrap.length === 0) {
-      throw new BaasError(
-        "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
-        400
-      );
-    }
-    const discovery = new ClusterDiscoveryClient({
-      bootstrap,
+    const resolved = await resolveClusterEndpoint({
+      bootstrap: config.bootstrap,
+      network: config.network,
       allowInsecure,
-      trustAnchor: config.trustAnchor ? {
-        network: config.trustAnchor.network,
-        registryTopicId: config.trustAnchor.registryTopicId,
-        mirrorNodeUrl: config.trustAnchor.mirrorNodeUrl,
-        allowInsecure
-      } : void 0
+      trustAnchor: config.trustAnchor
     });
-    const cluster = await discovery.getRandomCluster();
-    if (!cluster) {
+    if (!resolved.ok) {
+      if (resolved.reason === "no-seeds") {
+        throw new BaasError(
+          "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
+          400
+        );
+      }
       throw new BaasError(
         "No active clusters available via bootstrap seeds. Check network reachability or bootstrap URLs.",
         503
       );
     }
+    const cluster = resolved.cluster;
     return new _BaasClient({
       hostUrl: cluster.endpoints.gatewayUrl,
       appId: config.appId,
@@ -4649,7 +4769,7 @@ var BaasClient = class _BaasClient {
   }
   /** Check if the client is authenticated */
   isAuthenticated() {
-    return this.authToken !== null;
+    return this.http.getAuthToken() !== void 0;
   }
   /** Get the current app ID */
   getAppId() {
@@ -4695,93 +4815,80 @@ var BaasClient = class _BaasClient {
    */
   async authenticate(options) {
     const { chain, walletAddress, publicKey, signFn } = options;
-    const challenge = await this.post("/api/auth/challenge", {
-      chain,
-      walletAddress,
+    this.authContext = options;
+    let challenge;
+    try {
+      challenge = await this.http.post("/api/auth/challenge", {
+        chain,
+        walletAddress,
+        appId: this.appId
+      });
+    } catch (err) {
+      throw asBaasError(err);
+    }
+    const signature = await signFn(challenge.message);
+    let result;
+    try {
+      result = await this.http.post("/api/auth/verify", {
+        challengeId: challenge.challengeId,
+        signature,
+        publicKey
+      });
+    } catch (err) {
+      throw asBaasError(err);
+    }
+    this.http.setAuthToken(result.token);
+    return result;
+  }
+  /**
+   * Re-run the challenge-response with the retained signer to mint a fresh
+   * session token. Invoked by the http client's `onUnauthorized` hook when a
+   * request 401s because the token expired — so long-lived clients keep working
+   * without the caller re-implementing refresh. No-op if {@link authenticate}
+   * was never called. The `/api/auth/*` calls below are excluded from the http
+   * client's 401-retry path, so this can never recurse.
+   */
+  async reauthenticate() {
+    const ctx = this.authContext;
+    if (!ctx) return;
+    const challenge = await this.http.post("/api/auth/challenge", {
+      chain: ctx.chain,
+      walletAddress: ctx.walletAddress,
       appId: this.appId
     });
-    const signature = await signFn(challenge.message);
-    const result = await this.post("/api/auth/verify", {
+    const signature = await ctx.signFn(challenge.message);
+    const result = await this.http.post("/api/auth/verify", {
       challengeId: challenge.challengeId,
       signature,
-      publicKey
+      publicKey: ctx.publicKey
     });
-    this.authToken = result.token;
-    this.http.setAuthToken?.(result.token);
-    return result;
+    this.http.setAuthToken(result.token);
   }
   /** Validate the current session */
   async validateSession() {
     this.requireAuth();
-    return this.get("/api/auth/session");
+    try {
+      return await this.http.get("/api/auth/session");
+    } catch (err) {
+      throw asBaasError(err);
+    }
   }
   /** Destroy the current session on server and clear local token */
   async logout() {
-    if (this.authToken) {
+    if (this.http.getAuthToken()) {
       try {
-        await this.post("/api/auth/logout", {});
+        await this.http.post("/api/auth/logout", {});
       } catch {
       }
     }
-    this.authToken = null;
+    this.http.setAuthToken(void 0);
   }
   // ========== HTTP Helpers ==========
   requireAuth() {
-    if (!this.authToken) {
+    if (!this.http.getAuthToken()) {
       throw new BaasError("Authentication required. Call authenticate() first.", 401);
     }
   }
-  getHeaders() {
-    const headers = {
-      "Content-Type": "application/json"
-    };
-    if (this.authToken) {
-      headers["Authorization"] = `Bearer ${this.authToken}`;
-    }
-    return headers;
-  }
-  async post(path, body) {
-    return this.request("POST", path, body);
-  }
-  async get(path) {
-    return this.request("GET", path);
-  }
-  async request(method, path, body) {
-    const url = `${this.hostUrl}${this.pathPrefix}${path}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const options = {
-        method,
-        headers: this.getHeaders(),
-        signal: controller.signal
-      };
-      if (body !== void 0) {
-        options.body = JSON.stringify(body);
-      }
-      const response = await fetch(url, options);
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        throw new BaasError(
-          errorData.message || `API error: ${response.status} ${response.statusText}`,
-          response.status,
-          errorData
-        );
-      }
-      const text = await response.text();
-      if (!text) return void 0;
-      return JSON.parse(text);
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof BaasError) throw error;
-      const err = error;
-      if (err.name === "AbortError") {
-        throw new BaasError("Request timeout", 408);
-      }
-      throw new BaasError(`Network error: ${err.message}`, 0, { originalError: err.message });
-    }
-  }
 };
 var BaasError = class extends Error {
   constructor(message, statusCode, details) {
@@ -4793,6 +4900,17 @@ var BaasError = class extends Error {
   statusCode;
   details;
 };
+function asBaasError(err) {
+  if (err instanceof BaasError) return err;
+  if (err instanceof SdkHttpError) {
+    const details = err.details ?? void 0;
+    return new BaasError(err.message, err.statusCode, details);
+  }
+  const e = err;
+  return new BaasError(`Network error: ${e?.message ?? String(err)}`, 0, {
+    originalError: e?.message ?? String(err)
+  });
+}
 function validateUrl2(url, allowInsecure = false) {
   try {
     const parsed = new URL(url);
@@ -5016,10 +5134,12 @@ exports.SmartEngineService = __decorateClass([
 // src/nestjs/smart-engine.module.ts
 exports.SmartEngineModule = class SmartEngineModule {
   /**
-   * Configure the module with static configuration
+   * Configure the module with static configuration.
    *
-   * @param config - SmartEngine service configuration
-   * @param isGlobal - Whether to make the module global (default: true)
+   * @param config - SmartEngine service configuration.
+   * @param isGlobal - Whether to make the module global. @defaultValue true
+   * @returns A `DynamicModule` exporting {@link SmartEngineService} plus the
+   *   BaaS / rules / entities clients.
    */
   static forRoot(config, isGlobal = true) {
     return {
@@ -5042,11 +5162,15 @@ exports.SmartEngineModule = class SmartEngineModule {
     };
   }
   /**
-   * Configure the module with async configuration
+   * Configure the module with async configuration.
    *
    * Supports factory functions, configuration classes, and existing providers.
    *
-   * @param options - Async configuration options
+   * @param options - Async configuration options.
+   * @returns A `DynamicModule` exporting {@link SmartEngineService} plus the
+   *   BaaS / rules / entities clients.
+   * @throws Error if `options` provides none of `useFactory`, `useClass`, or
+   *   `useExisting`.
    */
   static forRootAsync(options) {
     const asyncProviders = this.createAsyncProviders(options);