@pyratzlabs/react-fhevm-utils 3.5.7 → 3.6.0

package/dist/client/context/FhevmProvider.d.ts

@@ -1,16 +1,18 @@
 import React, { ReactNode } from "react";
+import { FhevmInstance, FhevmInstanceConfig, FhevmStatus } from "../../lib/fhevmManager";
 import { Network } from "../../types/fhevmConfig";
-import { FhevmInstance, FhevmInstanceConfig } from "@zama-fhe/relayer-sdk/bundle";
 interface ProviderProps {
     children: ReactNode;
     network?: Network;
     config?: Partial<FhevmInstanceConfig>;
+    enabled?: boolean;
 }
 interface ContextProps {
     instance?: FhevmInstance;
+    status: FhevmStatus;
     config?: Partial<FhevmInstanceConfig>;
 }
 export declare const FhevmContext: React.Context<ContextProps>;
-declare const FhevmProvider: ({ children, network, config, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
+declare const FhevmProvider: ({ children, network, config, enabled, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
 export declare const useFhevmContext: () => ContextProps;
 export default FhevmProvider;

package/dist/client/context/FhevmProvider.js

@@ -8,27 +8,32 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useState, } from "react";
-import { getOrCreateFhevmInstance } from "../../lib/fhevm";
+import { createContext, useContext, useEffect, useSyncExternalStore, } from "react";
+import { fhevmManager, } from "../../lib/fhevmManager";
 export const FhevmContext = createContext({
     instance: undefined,
+    status: "uninitialized",
     config: undefined,
 });
-const FhevmProvider = ({ children, network = "sepolia", config, }) => {
-    const [instance, setInstance] = useState();
+const FhevmProvider = ({ children, network = "sepolia", config, enabled = true, }) => {
+    const status = useSyncExternalStore(fhevmManager.subscribe, fhevmManager.getStatus, fhevmManager.getStatus);
     useEffect(() => {
-        const initFhevm = (config, network) => __awaiter(void 0, void 0, void 0, function* () {
+        if (!enabled)
+            return;
+        const initFhevm = () => __awaiter(void 0, void 0, void 0, function* () {
             try {
-                const instance = yield getOrCreateFhevmInstance(network, config);
-                setInstance(instance);
+                yield fhevmManager.load();
+                yield fhevmManager.initSDK();
+                yield fhevmManager.createInstance({ network, customConfig: config });
             }
             catch (error) {
                 throw new Error(`Failed to initialize FHEVM: ${error}. With config: ${JSON.stringify(config)}`);
             }
         });
-        initFhevm(config, network);
-    }, [config, network]);
-    return (_jsx(FhevmContext.Provider, { value: { instance, config }, children: children }));
+        initFhevm();
+    }, [config, network, enabled]);
+    const instance = status === "ready" ? fhevmManager.getInstance() : undefined;
+    return (_jsx(FhevmContext.Provider, { value: { instance, status, config }, children: children }));
 };
 export const useFhevmContext = () => useContext(FhevmContext);
 export default FhevmProvider;

package/dist/client/hooks/useFhevmInstance.d.ts

@@ -1,3 +1,4 @@
 export declare const useFhevmInstance: () => {
     instance: import("@zama-fhe/relayer-sdk/web").FhevmInstance | undefined;
+    status: import("../../lib/fhevmManager").FhevmStatus;
 };

package/dist/client/hooks/useFhevmInstance.js

@@ -1,5 +1,5 @@
 import { useFhevmContext } from "../context/FhevmProvider";
 export const useFhevmInstance = () => {
-    const { instance } = useFhevmContext();
-    return { instance };
+    const { instance, status } = useFhevmContext();
+    return { instance, status };
 };

package/dist/lib/fhevmManager.d.ts

@@ -0,0 +1,68 @@
+import type { FhevmInstanceConfig, FhevmInstance } from "@zama-fhe/relayer-sdk/bundle";
+import { Network } from "../types/fhevmConfig";
+export type { FhevmInstance, FhevmInstanceConfig };
+export type FhevmStatus = "uninitialized" | "creating" | "ready" | "error" | "not-supported";
+export type RelayerSDK = {
+    initSDK: (options?: {
+        tfheParams?: unknown;
+        kmsParams?: unknown;
+        thread?: number;
+    }) => Promise<boolean>;
+    createInstance: (config: FhevmInstanceConfig) => Promise<FhevmInstance>;
+    SepoliaConfig: FhevmInstanceConfig;
+    MainnetConfig: FhevmInstanceConfig;
+};
+export type CreateInstanceOptions = {
+    network?: Network;
+    customConfig?: Partial<FhevmInstanceConfig>;
+};
+declare class FhevmManager {
+    private sdk;
+    private instance;
+    private loadPromise;
+    private instancePromise;
+    private _status;
+    private listeners;
+    private currentNetwork;
+    get status(): FhevmStatus;
+    get isLoaded(): boolean;
+    /**
+     * Subscribe to status changes. Returns an unsubscribe function.
+     * Compatible with React's useSyncExternalStore.
+     */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Get current status. For useSyncExternalStore.
+     */
+    getStatus: () => FhevmStatus;
+    /**
+     * Set status and notify listeners.
+     * External callers should only use 'uninitialized' or 'not-supported'.
+     * Setting 'uninitialized' also clears the instance.
+     */
+    setStatus: (status: FhevmStatus) => void;
+    private isBrowser;
+    private isValidSDK;
+    private getNetworkConfig;
+    /**
+     * Loads the relayer SDK script into the page.
+     * Safe to call multiple times - subsequent calls return the same promise.
+     */
+    load: () => Promise<void>;
+    /**
+     * Initializes the SDK after loading.
+     * Must be called after load() completes.
+     */
+    initSDK: () => Promise<boolean>;
+    /**
+     * Creates and initializes the FHEVM instance.
+     * Safe to call multiple times - returns existing promise if already creating.
+     */
+    createInstance: (options?: CreateInstanceOptions) => Promise<void>;
+    /**
+     * Gets the ready FHEVM instance.
+     * @throws Error if instance is not ready
+     */
+    getInstance: () => FhevmInstance;
+}
+export declare const fhevmManager: FhevmManager;

package/dist/lib/fhevmManager.js

@@ -0,0 +1,231 @@
+"use client";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { mainnet, sepolia } from "viem/chains";
+import { ZAMA_RELAYER_CDN_URL } from "../config";
+// ============================================================================
+// FhevmManager Class
+// ============================================================================
+class FhevmManager {
+    constructor() {
+        this._status = "uninitialized";
+        this.listeners = new Set();
+        this.currentNetwork = "sepolia";
+        // ==========================================================================
+        // Subscription (for React's useSyncExternalStore)
+        // ==========================================================================
+        /**
+         * Subscribe to status changes. Returns an unsubscribe function.
+         * Compatible with React's useSyncExternalStore.
+         */
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => this.listeners.delete(listener);
+        };
+        /**
+         * Get current status. For useSyncExternalStore.
+         */
+        this.getStatus = () => {
+            return this._status;
+        };
+        /**
+         * Set status and notify listeners.
+         * External callers should only use 'uninitialized' or 'not-supported'.
+         * Setting 'uninitialized' also clears the instance.
+         */
+        this.setStatus = (status) => {
+            if (status === "uninitialized") {
+                this.instance = undefined;
+                this.instancePromise = undefined;
+            }
+            if (this._status !== status) {
+                this._status = status;
+                this.listeners.forEach((listener) => listener());
+            }
+        };
+        // ==========================================================================
+        // Public Methods
+        // ==========================================================================
+        /**
+         * Loads the relayer SDK script into the page.
+         * Safe to call multiple times - subsequent calls return the same promise.
+         */
+        this.load = () => __awaiter(this, void 0, void 0, function* () {
+            if (!this.isBrowser()) {
+                throw new Error("Relayer SDK can only be used in the browser");
+            }
+            // Already loaded
+            if (this.isLoaded) {
+                return;
+            }
+            // Return existing promise if already loading
+            if (this.loadPromise) {
+                return this.loadPromise;
+            }
+            // Check if SDK is already on window (loaded by another source)
+            const windowWithSDK = window;
+            if (this.isValidSDK(windowWithSDK.relayerSDK)) {
+                this.sdk = windowWithSDK.relayerSDK;
+                return;
+            }
+            // Check if script tag already exists
+            const existingScript = document.querySelector(`script[src="${ZAMA_RELAYER_CDN_URL}"]`);
+            if (existingScript) {
+                // Wait for it to load and populate window
+                this.loadPromise = new Promise((resolve, reject) => {
+                    const checkInterval = setInterval(() => {
+                        if (this.isValidSDK(windowWithSDK.relayerSDK)) {
+                            clearInterval(checkInterval);
+                            this.sdk = windowWithSDK.relayerSDK;
+                            resolve();
+                        }
+                    }, 50);
+                    // Timeout after 10 seconds
+                    setTimeout(() => {
+                        clearInterval(checkInterval);
+                        this.loadPromise = undefined;
+                        reject(new Error("Timeout waiting for existing Relayer SDK script to load"));
+                    }, 10000);
+                });
+                return this.loadPromise;
+            }
+            // Load the script
+            this.loadPromise = new Promise((resolve, reject) => {
+                const script = document.createElement("script");
+                script.src = ZAMA_RELAYER_CDN_URL;
+                script.type = "text/javascript";
+                script.async = true;
+                script.onload = () => {
+                    const windowWithSDK = window;
+                    if (this.isValidSDK(windowWithSDK.relayerSDK)) {
+                        this.sdk = windowWithSDK.relayerSDK;
+                        resolve();
+                    }
+                    else {
+                        this.loadPromise = undefined;
+                        reject(new Error("Relayer SDK script loaded but SDK is invalid"));
+                    }
+                };
+                script.onerror = () => {
+                    this.loadPromise = undefined;
+                    reject(new Error(`Failed to load Relayer SDK from ${ZAMA_RELAYER_CDN_URL}`));
+                };
+                document.head.appendChild(script);
+            });
+            return this.loadPromise;
+        });
+        /**
+         * Initializes the SDK after loading.
+         * Must be called after load() completes.
+         */
+        this.initSDK = () => __awaiter(this, void 0, void 0, function* () {
+            if (!this.sdk) {
+                throw new Error("SDK not loaded. Call load() first.");
+            }
+            return this.sdk.initSDK();
+        });
+        /**
+         * Creates and initializes the FHEVM instance.
+         * Safe to call multiple times - returns existing promise if already creating.
+         */
+        this.createInstance = (...args_1) => __awaiter(this, [...args_1], void 0, function* (options = {}) {
+            var _a;
+            const network = (_a = options.network) !== null && _a !== void 0 ? _a : "sepolia";
+            // Return early if already created for same network
+            if (this.instancePromise && network === this.currentNetwork) {
+                yield this.instancePromise;
+                return;
+            }
+            if (!this.sdk) {
+                throw new Error("SDK not loaded. Call load() and initSDK() first.");
+            }
+            this.currentNetwork = network;
+            const baseConfig = this.getNetworkConfig(network);
+            try {
+                this.setStatus("creating");
+                const config = Object.assign(Object.assign({}, baseConfig), options.customConfig);
+                this.instancePromise = this.sdk.createInstance(config);
+                this.instance = yield this.instancePromise;
+                this.setStatus("ready");
+            }
+            catch (error) {
+                console.error("FHEVM instance creation failed:", error);
+                this.setStatus("error");
+                this.instancePromise = undefined;
+                throw error;
+            }
+        });
+        /**
+         * Gets the ready FHEVM instance.
+         * @throws Error if instance is not ready
+         */
+        this.getInstance = () => {
+            if (!this.instance) {
+                throw new Error("FHEVM instance not created. Call createInstance() first or wait for initialization.");
+            }
+            if (this._status === "creating") {
+                throw new Error("FHEVM instance is still being created. Please wait for initialization.");
+            }
+            if (this._status === "error") {
+                throw new Error("FHEVM instance creation failed. Check previous errors or reinitialize.");
+            }
+            if (this._status === "not-supported") {
+                throw new Error(`FHEVM is not supported on the current network. Please switch to a supported network.`);
+            }
+            if (this._status !== "ready") {
+                throw new Error(`FHEVM instance is not ready. Current status: ${this._status}`);
+            }
+            return this.instance;
+        };
+    }
+    // ==========================================================================
+    // Getters
+    // ==========================================================================
+    get status() {
+        return this._status;
+    }
+    get isLoaded() {
+        return this.sdk !== undefined && this.isValidSDK(this.sdk);
+    }
+    // ==========================================================================
+    // Private Helpers
+    // ==========================================================================
+    isBrowser() {
+        return typeof window === "object";
+    }
+    isValidSDK(sdk) {
+        if (!sdk || typeof sdk !== "object")
+            return false;
+        const relayerSDK = sdk;
+        return (typeof relayerSDK.initSDK === "function" &&
+            typeof relayerSDK.createInstance === "function" &&
+            typeof relayerSDK.SepoliaConfig === "object" &&
+            typeof relayerSDK.MainnetConfig === "object");
+    }
+    getNetworkConfig(network) {
+        if (!this.sdk) {
+            throw new Error("SDK not loaded. Call load() first.");
+        }
+        const configByChainId = {
+            [sepolia.id]: this.sdk.SepoliaConfig,
+            [mainnet.id]: this.sdk.MainnetConfig,
+        };
+        const chainId = network === "mainnet" ? mainnet.id : sepolia.id;
+        const config = configByChainId[chainId];
+        if (!config) {
+            throw new Error(`No relayer SDK config found for network: ${network}`);
+        }
+        return config;
+    }
+}
+// ============================================================================
+// Singleton Export
+// ============================================================================
+export const fhevmManager = new FhevmManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyratzlabs/react-fhevm-utils",
-  "version": "3.5.7",
+  "version": "3.6.0",
   "description": "React hooks and utilities for Fhevmjs",
   "main": "dist/index.js",
   "files": [