wagmi-extended 2.2.1 → 2.2.3

package/README.md

@@ -22,6 +22,7 @@ Whether you're building a DeFi platform, a governance system, or any blockchain
 - [Non-hook functions setup](#non-hook-functions-setup)
   - [Error handling](#error-handling)
   - [fetchTokenX](#fetchTokenX)
+  - [fetchDeploymentBlockX](#fetchDeploymentBlockX)
 - [Contributing](#contributing)
 - [Donations](#support--donations)
 - [License](#license)
@@ -365,14 +366,58 @@ const tokensData = await Promise.all(tokenAddresses.map((token) =>
 
 > **Note:** : if you did not setup configs (queryClient and wagmi config) you can call by passing client and config as params: `fetchTokenX(token, queryClient, wagmiConfig)`.
 
+### fetchDeploymentBlockX
+
+The `fetchDeploymentBlockX` function finds and caches the earliest block where a contract was deployed  
+(i.e., the first block containing bytecode at a given address).
+
+It uses an **exponential descent** followed by a **binary search**, making it optimal for locating deployment blocks with minimal RPC calls.
+
+- **Exponential descent**: quickly finds a safe lower bound with no code.
+- **Binary search**: efficiently pinpoints the exact deployment block in logarithmic steps.
+
+#### Features
+
+- **React Query caching**: results stored under the key  
+  `["deploymentBlock", chainId, address.toLowerCase(), floor]`.
+- **LocalStorage caching (browser only)**:
+  - On the **first run**, the block is computed and stored in both React Query and `localStorage`.
+  - On **subsequent runs**, the value is read from `localStorage` to fully prevent RPC refetches.
+- **SSR-safe**: all localStorage access is gated by `typeof window !== 'undefined'`.
+- **Opt-out**: pass `{ disableLocalStorage: true }` to bypass read/write of `localStorage`.
+
+#### Example
+
+```ts
+import { fetchDeploymentBlockX } from "wagmi-extended";
+
+async function main() {
+  const deploymentBlock = await fetchDeploymentBlockX(
+    "0xYourContractAddress",
+    0n
+  );
+
+  console.log("Contract was deployed at block:", deploymentBlock.toString());
+}
+
+main();
+```
+
+Performance
+
+Performs O(log N) RPC calls, where N is the distance between the latest block and the deployment block.
+
+- Much more efficient than linear scanning.
+- Automatically cached by React Query under the key:
+
 ## Contributing
 
 This project is open source and we welcome contributions from the community! If you have ideas, improvements, or bug fixes, please feel free to open pull requests or file issues. Your help makes this project better for everyone.
 
-- **Open Issues & PRs:**  
+- **Open Issues & PRs:**
   You can report bugs or request features by opening an issue on [GitHub Issues](https://github.com/WingsDevelopment/wagmi-extended/issues). Similarly, feel free to open a pull request (PR) with your changes.
 
-- **Star the Project:**  
+- **Star the Project:**
   If you like `wagmi-extended` or find it useful, please consider starring the repository on [GitHub](https://github.com/WingsDevelopment/wagmi-extended). It helps the project gain visibility and motivates further development.
 
 Thank you for your support and contributions!
@@ -381,10 +426,10 @@ Thank you for your support and contributions!
 
 If you enjoy this project and would like to support its ongoing development, please consider donating!
 
-- **Buy Me a Coffee:**  
+- **Buy Me a Coffee:**
   [buymeacoffee.com/srdjanr160N](https://buymeacoffee.com/srdjanr160N)
 
-- **Ethereum Donation Address:**  
+- **Ethereum Donation Address:**
   `0x410A11ed53a9a59094F24D2ae4ACbeF7f84955a1`
 
 Any donation, no matter how small, is greatly appreciated!
@@ -398,3 +443,7 @@ Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 For more information, please refer to <http://unlicense.org/>
+
+```
+
+```

package/dist/fetch-functions/common/fetchDeploymentBlockX.d.ts

@@ -8,13 +8,21 @@ export declare const deploymentBlockKey: (chainId: number | undefined, address:
  *
  * Use with `queryClient.fetchQuery(...)`.
  *
- * @param address     - Contract address to probe.
- * @param floor       - Optional lower bound (inclusive) to speed up search. Defaults to `0n`.
- * @param wagmiConfig - Wagmi `Config` (optional; resolved via `ensureClientAndConfig` if omitted).
+ * @param address            - Contract address to probe.
+ * @param floor              - Optional lower bound (inclusive) to speed up search. Defaults to `0n`.
+ * @param wagmiConfig        - Wagmi `Config` (optional; resolved via `ensureClientAndConfig` if omitted).
+ * @param options.disableLocalStorage - If `true`, skip reading/writing localStorage (default `false`).
  *
- * @returns A fully-configured query options object (key + fn + metadata).
+ * Local Storage behavior (SSR-safe):
+ * - If not disabled and a value exists in `localStorage`, the `queryFn` will
+ *   return it immediately without performing RPC calls.
+ * - After an on-chain discovery, the result is written to `localStorage`
+ *   (unless disabled). This pairs nicely with `staleTime: Infinity` to
+ *   avoid future refetches.
  */
-export declare function getDeploymentBlockQueryOptionsX(address: Address, floor?: bigint, wagmiConfig?: Config): {
+export declare function getDeploymentBlockQueryOptionsX(address: Address, floor?: bigint, wagmiConfig?: Config, options?: {
+    disableLocalStorage?: boolean;
+}): {
     readonly staleTime: number;
     readonly meta: {
         readonly queryType: import("../../query-config/index.js").QueryType.MetaDataQuery;
@@ -31,24 +39,36 @@ export declare function getDeploymentBlockQueryOptionsX(address: Address, floor?
  *
  * #### Caching
  * - Query key: `["deploymentBlock", chainId, address.toLowerCase(), floor]`
- * - For long-lived results, we apply `queryConfig.metaDataQuery` (tweak as needed).
+ * - Long-lived results: `queryConfig.metaDataQuery` (e.g., `staleTime: Infinity`)
  *
- * #### Performance
- * - **O(log N)** `eth_getCode` calls, where `N` is the gap between the latest
- *   block and the deployment block—optimal among comparison-based strategies.
+ * #### Local Storage (SSR-safe)
+ * - Before calling `fetchQuery`, we seed the Query Cache from `localStorage`
+ *   (unless `disableLocalStorage` is true). When a cached value is present,
+ *   `fetchQuery` will *not* execute the `queryFn`, fully preventing RPC refetches.
+ * - After on-chain discovery, the result is written back to `localStorage`
+ *   (unless disabled).
  *
  * @example
  * ```ts
- * const block = await fetchDeploymentBlockX("0xContract...", 0n, queryClient, wagmiConfig);
+ * const block = await fetchDeploymentBlockX(
+ *   "0xContract...",
+ *   0n,
+ *   queryClient,
+ *   wagmiConfig,
+ *   { disableLocalStorage: false }
+ * );
  * ```
  *
- * @param address - Contract address to probe.
- * @param floor - Optional lower bound (inclusive) to speed up search. Defaults to `0n`.
- * @param queryClient - Optional TanStack `QueryClient`. If omitted, resolved by `ensureClientAndConfig`.
- * @param wagmiConfig - Optional Wagmi `Config`. If omitted, resolved by `ensureClientAndConfig`.
+ * @param address                   - Contract address to probe.
+ * @param floor                     - Optional lower bound (inclusive). Defaults to `0n`.
+ * @param queryClient               - Optional TanStack `QueryClient`. If omitted, resolved by `ensureClientAndConfig`.
+ * @param wagmiConfig               - Optional Wagmi `Config`. If omitted, resolved by `ensureClientAndConfig`.
+ * @param options.disableLocalStorage - If `true`, skip reading/writing localStorage (default `false`).
  *
  * @returns The earliest block number (bigint) where bytecode exists.
  *
  * @throws If the public client is missing or if no code is present at the latest block.
  */
-export declare function fetchDeploymentBlockX(address: Address, floor?: bigint, queryClient?: QueryClient, wagmiConfig?: Config): Promise<bigint>;
+export declare function fetchDeploymentBlockX(address: Address, floor?: bigint, queryClient?: QueryClient, wagmiConfig?: Config, options?: {
+    disableLocalStorage?: boolean;
+}): Promise<bigint>;

package/dist/index.cjs.js

@@ -857,6 +857,33 @@ async function fetchERC4626DataX(vault, user, spender, queryClient, wagmiConfig)
 
 /** Reusable React Query key helper for deployment block lookups. */
 const deploymentBlockKey = (chainId, address, floor) => ["deploymentBlock", chainId, address?.toLowerCase(), floor];
+/** Internal: SSR-safe localStorage guards */
+const canUseBrowserStorage = typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+/** Internal: build a stable localStorage key */
+const lsKeyForDeploymentBlock = (chainId, address, floor) => `wagmi-extended:deploymentBlock:${chainId}:${address.toLowerCase()}:${floor.toString()}`;
+/** Internal: read bigint from localStorage (SSR safe) */
+function readDeploymentBlockFromLS(chainId, address, floor) {
+    if (!canUseBrowserStorage)
+        return undefined;
+    try {
+        const raw = window.localStorage.getItem(lsKeyForDeploymentBlock(chainId, address, floor));
+        return raw ? BigInt(raw) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Internal: write bigint to localStorage (SSR safe) */
+function writeDeploymentBlockToLS(chainId, address, floor, value) {
+    if (!canUseBrowserStorage)
+        return;
+    try {
+        window.localStorage.setItem(lsKeyForDeploymentBlock(chainId, address, floor), value.toString());
+    }
+    catch {
+        /* ignore quota/security errors */
+    }
+}
 /**
  * Internal helper: checks if there is bytecode at `address` on `blockNumber`.
  */
@@ -920,15 +947,22 @@ async function findDeploymentBlockRpcX(address, wagmiConfig, floor = 0n) {
  *
  * Use with `queryClient.fetchQuery(...)`.
  *
- * @param address     - Contract address to probe.
- * @param floor       - Optional lower bound (inclusive) to speed up search. Defaults to `0n`.
- * @param wagmiConfig - Wagmi `Config` (optional; resolved via `ensureClientAndConfig` if omitted).
+ * @param address            - Contract address to probe.
+ * @param floor              - Optional lower bound (inclusive) to speed up search. Defaults to `0n`.
+ * @param wagmiConfig        - Wagmi `Config` (optional; resolved via `ensureClientAndConfig` if omitted).
+ * @param options.disableLocalStorage - If `true`, skip reading/writing localStorage (default `false`).
  *
- * @returns A fully-configured query options object (key + fn + metadata).
+ * Local Storage behavior (SSR-safe):
+ * - If not disabled and a value exists in `localStorage`, the `queryFn` will
+ *   return it immediately without performing RPC calls.
+ * - After an on-chain discovery, the result is written to `localStorage`
+ *   (unless disabled). This pairs nicely with `staleTime: Infinity` to
+ *   avoid future refetches.
  */
-function getDeploymentBlockQueryOptionsX(address, floor = 0n, wagmiConfig) {
+function getDeploymentBlockQueryOptionsX(address, floor = 0n, wagmiConfig, options) {
     if (!address)
         throw new Error("Address is required");
+    const disableLocalStorage = options?.disableLocalStorage ?? false;
     // Resolve config (caller may pass undefined; we'll normalize later in fetcher too)
     // We only need chainId for the key; if wagmiConfig is missing here,
     // we allow it since fetcher re-resolves. But key stability benefits from chainId.
@@ -939,9 +973,25 @@ function getDeploymentBlockQueryOptionsX(address, floor = 0n, wagmiConfig) {
         queryFn: async () => {
             if (!wagmiConfig)
                 throw new Error("wagmiConfig is required at execution time");
-            return findDeploymentBlockRpcX(address, wagmiConfig, floor);
+            const c = actions.getPublicClient(wagmiConfig);
+            const cid = c?.chain?.id;
+            if (!cid)
+                throw new Error("Client chain ID is missing");
+            // Try localStorage first (no refetches if we already know it)
+            if (!disableLocalStorage) {
+                const fromLS = readDeploymentBlockFromLS(cid, address, floor);
+                if (fromLS !== undefined)
+                    return fromLS;
+            }
+            // Otherwise do the discovery via RPC
+            const discovered = await findDeploymentBlockRpcX(address, wagmiConfig, floor);
+            // Persist to localStorage for subsequent sessions
+            if (!disableLocalStorage) {
+                writeDeploymentBlockToLS(cid, address, floor, discovered);
+            }
+            return discovered;
         },
-        ...queryConfig.metaDataQuery,
+        ...queryConfig.metaDataQuery, // typically sets staleTime: Infinity, gcTime, etc.
     };
 }
 /**
@@ -953,39 +1003,59 @@ function getDeploymentBlockQueryOptionsX(address, floor = 0n, wagmiConfig) {
  *
  * #### Caching
  * - Query key: `["deploymentBlock", chainId, address.toLowerCase(), floor]`
- * - For long-lived results, we apply `queryConfig.metaDataQuery` (tweak as needed).
+ * - Long-lived results: `queryConfig.metaDataQuery` (e.g., `staleTime: Infinity`)
  *
- * #### Performance
- * - **O(log N)** `eth_getCode` calls, where `N` is the gap between the latest
- *   block and the deployment block—optimal among comparison-based strategies.
+ * #### Local Storage (SSR-safe)
+ * - Before calling `fetchQuery`, we seed the Query Cache from `localStorage`
+ *   (unless `disableLocalStorage` is true). When a cached value is present,
+ *   `fetchQuery` will *not* execute the `queryFn`, fully preventing RPC refetches.
+ * - After on-chain discovery, the result is written back to `localStorage`
+ *   (unless disabled).
  *
  * @example
  * ```ts
- * const block = await fetchDeploymentBlockX("0xContract...", 0n, queryClient, wagmiConfig);
+ * const block = await fetchDeploymentBlockX(
+ *   "0xContract...",
+ *   0n,
+ *   queryClient,
+ *   wagmiConfig,
+ *   { disableLocalStorage: false }
+ * );
  * ```
  *
- * @param address - Contract address to probe.
- * @param floor - Optional lower bound (inclusive) to speed up search. Defaults to `0n`.
- * @param queryClient - Optional TanStack `QueryClient`. If omitted, resolved by `ensureClientAndConfig`.
- * @param wagmiConfig - Optional Wagmi `Config`. If omitted, resolved by `ensureClientAndConfig`.
+ * @param address                   - Contract address to probe.
+ * @param floor                     - Optional lower bound (inclusive). Defaults to `0n`.
+ * @param queryClient               - Optional TanStack `QueryClient`. If omitted, resolved by `ensureClientAndConfig`.
+ * @param wagmiConfig               - Optional Wagmi `Config`. If omitted, resolved by `ensureClientAndConfig`.
+ * @param options.disableLocalStorage - If `true`, skip reading/writing localStorage (default `false`).
  *
  * @returns The earliest block number (bigint) where bytecode exists.
  *
  * @throws If the public client is missing or if no code is present at the latest block.
  */
-async function fetchDeploymentBlockX(address, floor = 0n, queryClient, wagmiConfig) {
+async function fetchDeploymentBlockX(address, floor = 0n, queryClient, wagmiConfig, options) {
     if (!address)
         throw new Error("Address is required");
     ({ queryClient, wagmiConfig } = ensureClientAndConfig(queryClient, wagmiConfig));
-    // Resolve chainId for a stable cache key
     const client = actions.getPublicClient(wagmiConfig);
     const chainId = client?.chain?.id;
     if (!chainId)
         throw new Error("Client chain ID is missing");
+    const key = deploymentBlockKey(chainId, address, floor);
+    const disableLocalStorage = options?.disableLocalStorage ?? false;
+    // Seed cache from localStorage so fetchQuery returns immediately w/o running queryFn
+    if (!disableLocalStorage) {
+        const fromLS = readDeploymentBlockFromLS(chainId, address, floor);
+        if (fromLS !== undefined) {
+            queryClient.setQueryData(key, fromLS);
+        }
+    }
     return queryClient.fetchQuery({
-        ...getDeploymentBlockQueryOptionsX(address, floor, wagmiConfig),
+        ...getDeploymentBlockQueryOptionsX(address, floor, wagmiConfig, {
+            disableLocalStorage,
+        }),
         // Ensure the final key includes a concrete chainId
-        queryKey: deploymentBlockKey(chainId, address, floor),
+        queryKey: key,
         // Reinstate metadata (in case your ensure/util merges)
         ...queryConfig.metaDataQuery,
     });