@effectstream/midnight-contracts 0.103.0 → 0.103.2

package/README.md

@@ -123,6 +123,21 @@ The circuit list is enumerated automatically from the contract's compiled `keys/
 - `deployMidnightContractPhased(...)`: the phased deploy routine `deployMidnightContract` delegates to when `phasedVerifierKeys` is set. Exported for advanced callers that already have built providers and a wallet.
 - `DeployConfig`, `NetworkUrls`: input types.
 
+Wallet and dust helpers, exported from the package root:
+
+- `buildWalletFacade(...)`: builds the wallet facade the deploy and batcher paths run on.
+- `registerNightForDust(...)`, `getInitialDustState(...)`: register NIGHT to generate dust and read the starting state.
+- `waitForDustFunds(wallet, opts)` / `waitForDustFundsWithRetry(...)`: block until a wallet has spendable dust — the step that makes a freshly funded wallet usable.
+- `saveDustState(...)` / `loadDustState(...)`: persist and restore dust state across restarts, avoiding a re-sync.
+- `resolveFacadeDustBalance(...)`: current dust balance for a facade.
+
+Other subpaths:
+
+- `@effectstream/midnight-contracts/wallet-info` - wallet inspection plus the dust-state persistence helpers above, and `resolveWalletSyncTimeoutMs()`.
+- `@effectstream/midnight-contracts/midnight-env` - `midnightNetworkConfig` (the resolved `{ id, indexer, indexerWS, node, proofServer }` endpoints, env-overridable), `MidnightNetworkConfig`, and `isExternalProofServerConfigured`.
+- `@effectstream/midnight-contracts/ledger-from-tx-state` - `midnightLedgerFromTxStateHex(...)` and the `MidnightLedgerFn` / `MidnightContractStateDeserializer` types, for decoding contract ledger state from a serialized transaction state.
+- `@effectstream/midnight-contracts/types` - shared types.
+
 ## Examples
 
 End-to-end usage in templates:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/midnight-contracts",
-  "version": "0.103.0",
+  "version": "0.103.2",
   "license": "(MIT OR Apache-2.0)",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -21,7 +21,7 @@
     "./types": "./src/types.ts"
   },
   "dependencies": {
-    "@effectstream/utils": "0.103.0",
+    "@effectstream/utils": "0.103.2",
     "@scure/bip39": "^2.0.1",
     "dotenv": "^16.4.7",
     "rxjs": "^7.8.2",

package/src/dust-state.ts

@@ -0,0 +1,73 @@
+// Dust-state persistence — the ONLY disk I/O behind the `./wallet-info`
+// subpath, split into its own module so it stays out of browser bundles.
+//
+// `get-wallet-info.ts` is reachable from browsers (MidnightLocal.connectFromSeed
+// imports it to build the wallet facade), and previously carried these
+// functions along with their `node:fs` import. Bundlers shim `node:fs` to an
+// empty/null module, which once crashed the whole entry at import time and,
+// after that was patched, still shipped dead fs/path polyfills to the client.
+// Here the functions are reached only via a lazy `await import()` inside
+// `waitForDustFundsWithRetry` — a node-side flow — so `node:fs`/`node:path`
+// never enter the browser's static graph at all.
+import * as path from "node:path";
+import * as fs from "node:fs";
+
+const log = console;
+
+/**
+ * Build the dust state file path from network + seed.
+ * Uses first 16 hex chars of the seed as a stable identifier — the seed
+ * deterministically maps to a dust address, so this is a unique key per wallet
+ * that is available before building the facade.
+ */
+export function getDustStatePath(baseDir: string, networkId: string, seed: string): string {
+  const seedKey = seed.slice(0, 16);
+  return path.join(baseDir, `${networkId}-${seedKey}.json`);
+}
+
+function isUndeployedNetwork(networkId: string): boolean {
+  return networkId.toLowerCase() === "undeployed";
+}
+
+/**
+ * Save serialized dust wallet state to disk.
+ * No-ops for "undeployed" networks (chain resets make cached state invalid).
+ * @param seed - Wallet seed hex string (used to derive stable file path)
+ */
+export function saveDustState(
+  baseDir: string,
+  networkId: string,
+  seed: string,
+  serializedState: string,
+): string | null {
+  if (isUndeployedNetwork(networkId)) return null;
+  const filePath = getDustStatePath(baseDir, networkId, seed);
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, serializedState, "utf-8");
+    log.info(`Dust state saved to ${filePath}`);
+    return filePath;
+  } catch (e) {
+    log.warn(`Failed to save dust state to ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  }
+}
+
+/**
+ * Load previously saved dust wallet state from disk.
+ * Always returns null for "undeployed" networks.
+ * @param seed - Wallet seed hex string (used to derive stable file path)
+ */
+export function loadDustState(
+  baseDir: string,
+  networkId: string,
+  seed: string,
+): string | null {
+  if (isUndeployedNetwork(networkId)) return null;
+  const filePath = getDustStatePath(baseDir, networkId, seed);
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}

package/src/get-wallet-info.ts

@@ -38,77 +38,24 @@ import {
   TransactionHistoryStorage,
 } from "@midnightntwrk/wallet-sdk-abstractions";
 import { MidnightBech32m } from "@midnightntwrk/wallet-sdk-address-format";
-import * as path from "node:path";
-import { mkdirSync, writeFileSync, readFileSync } from "node:fs";
+// No node:fs / node:path here — this module is reachable from BROWSER bundles
+// (MidnightLocal.connectFromSeed imports `./wallet-info` to build the wallet
+// facade), and browser bundlers shim those to empty/null modules. All disk I/O
+// (dust-state persistence) lives in dust-state.ts, loaded lazily inside
+// waitForDustFundsWithRetry so it never enters the browser's static graph.
 import { CONSTANTS } from "./constants.ts";
 import type { NetworkUrls, WalletResult } from "./types.ts";
 import { midnightNetworkConfig } from "./midnight-env.ts";
 import { getEnv, args as getArgs, exit, isNotFoundError } from "@effectstream/utils/runtime";
 
 // ============================================================================
-// Dust State Persistence
+// Dust State Persistence — moved to dust-state.ts (node-only; disk I/O).
+// Re-exported from mod.ts for node consumers; NOT re-exported here, since a
+// static re-export would pull node:fs right back into the browser graph.
 // ============================================================================
 
 const DEFAULT_DUST_STATE_DIR = "dust-state";
 
-/**
- * Build the dust state file path from network + seed.
- * Uses first 16 hex chars of the seed as a stable identifier — the seed
- * deterministically maps to a dust address, so this is a unique key per wallet
- * that is available before building the facade.
- */
-function getDustStatePath(baseDir: string, networkId: string, seed: string): string {
-  const seedKey = seed.slice(0, 16);
-  return path.join(baseDir, `${networkId}-${seedKey}.json`);
-}
-
-function isUndeployedNetwork(networkId: string): boolean {
-  return networkId.toLowerCase() === "undeployed";
-}
-
-/**
- * Save serialized dust wallet state to disk.
- * No-ops for "undeployed" networks (chain resets make cached state invalid).
- * @param seed - Wallet seed hex string (used to derive stable file path)
- */
-export function saveDustState(
-  baseDir: string,
-  networkId: string,
-  seed: string,
-  serializedState: string,
-): string | null {
-  if (isUndeployedNetwork(networkId)) return null;
-  const filePath = getDustStatePath(baseDir, networkId, seed);
-  try {
-    mkdirSync(path.dirname(filePath), { recursive: true });
-    writeFileSync(filePath, serializedState, "utf-8");
-    log.info(`Dust state saved to ${filePath}`);
-    return filePath;
-  } catch (e) {
-    log.warn(`Failed to save dust state to ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
-    return null;
-  }
-}
-
-/**
- * Load previously saved dust wallet state from disk.
- * Always returns null for "undeployed" networks.
- * @param seed - Wallet seed hex string (used to derive stable file path)
- */
-export function loadDustState(
-  baseDir: string,
-  networkId: string,
-  seed: string,
-): string | null {
-  if (isUndeployedNetwork(networkId)) return null;
-  const filePath = getDustStatePath(baseDir, networkId, seed);
-  try {
-    return readFileSync(filePath, "utf-8");
-  } catch {
-    return null;
-  }
-}
-
 // ============================================================================
 // Key Derivation
 // ============================================================================
@@ -554,6 +501,11 @@ export async function waitForDustFundsWithRetry(
 
   const networkIdStr = String(networkId);
 
+  // Lazy import keeps node:fs out of the browser's static graph — this retry
+  // flow is node-side (long-running dust sync with disk caching), while the
+  // module as a whole is bundled for browsers via `./wallet-info`.
+  const { loadDustState, saveDustState, getDustStatePath } = await import("./dust-state.ts");
+
   // Pre-load cached state from disk before building any wallet.
   // Uses seed-based path so we don't need the dust address yet.
   const cachedState: string | null = loadDustState(dustStateDir, networkIdStr, seed);

package/src/mod.ts

@@ -18,9 +18,12 @@ export {
     getInitialDustState,
     waitForDustFunds,
     waitForDustFundsWithRetry,
-    saveDustState,
-    loadDustState,
 } from "./get-wallet-info.ts";
+// Disk-backed dust persistence lives in its own node-only module so the
+// browser-reachable ./wallet-info subpath carries no node:fs. This barrel is
+// node-only anyway (deploy.ts imports node:fs/promises), so a static
+// re-export here is fine and keeps the public API unchanged.
+export { saveDustState, loadDustState } from "./dust-state.ts";
 export type {
     WalletSyncMode,
     DustSyncWithRetryOptions,