@net-protocol/storage 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,54 @@
 # @net-protocol/storage
 
-Net Storage SDK for key-value storage on the Net protocol. Supports regular storage, chunked storage, and XML storage patterns.
+**Status: Alpha** - Usable but may have breaking changes over time. Suitable for early adopters and testing.
+
+Net Storage SDK for permanent onchain key-value storage built on Net Protocol.
+
+## What is Net Storage?
+
+Net Storage provides permanent, versioned key-value storage on the blockchain. Every write creates a new version, preserving complete history. Unlike traditional databases, Storage data is:
+
+- **Immutable**: Once stored, data cannot be modified
+- **Versioned**: Complete history of all changes preserved
+- **Transparent**: All data is publicly verifiable
+- **Decentralized**: No central servers or databases
+
+## Storage Types
+
+Net Storage supports three storage patterns for different file sizes:
+
+### Regular Storage
+
+**Best for**: Small data (< 20KB)  
+**How it works**: Stores data directly as Net messages  
+**Use cases**: User settings, configuration, small metadata
+
+### Chunked Storage
+
+**Best for**: Medium files (20KB-80KB)  
+**How it works**: Compresses data (gzip) and splits into 20KB chunks  
+**Use cases**: Images, documents, medium-sized data
+
+### XML Storage
+
+**Best for**: Large files (multi-MB)  
+**How it works**: Splits large files into 80KB pieces, stores each using ChunkedStorage, maintains references as XML metadata  
+**Use cases**: Videos, large images, datasets, any large file
+
+## What can you do with this package?
+
+- **Store data permanently**: Write key-value pairs that persist forever on the blockchain
+- **Access version history**: Read any historical version of stored data
+- **Store files of any size**: From small settings to multi-MB files
+- **Build storage apps**: Create applications that need permanent, verifiable data storage
+
+This package provides both React hooks (for UI) and client classes (for non-React code).
+
+## Learn More
+
+- [Net Storage Documentation](https://docs.netprotocol.app/docs/apps/storage/01-overview) - Complete storage documentation
+- [Storage Developer Guide](https://docs.netprotocol.app/docs/apps/storage/03-developer-guide) - Technical implementation details
+- [Net Protocol Documentation](https://docs.netprotocol.app) - Core protocol documentation
 
 ## Installation
 
@@ -23,7 +71,11 @@ yarn add @net-protocol/storage
 ### React Hooks
 
 ```typescript
-import { useStorage, useXmlStorage, useStorageFromRouter } from "@net-protocol/storage";
+import {
+  useStorage,
+  useXmlStorage,
+  useStorageFromRouter,
+} from "@net-protocol/storage";
 
 // Basic storage read
 function MyComponent() {
@@ -35,7 +87,7 @@ function MyComponent() {
 
   if (isLoading) return <div>Loading...</div>;
   if (error) return <div>Error: {error.message}</div>;
-  
+
   const [text, data] = data || [];
   return <div>{text}</div>;
 }
@@ -102,7 +154,11 @@ function XmlWithFormats() {
   });
 
   // Return as object format (default)
-  const { data: objectData, filename, isXml } = useXmlStorage({
+  const {
+    data: objectData,
+    filename,
+    isXml,
+  } = useXmlStorage({
     chainId: 8453,
     key: "my-xml-key",
     operatorAddress: "0x...",
@@ -180,7 +236,7 @@ const chunks = chunkDataForStorage("large data string");
 const assembled = assembleChunks(chunks);
 
 // Parse XML references
-const references = parseNetReferences("<net k=\"hash\" v=\"0.0.1\" />");
+const references = parseNetReferences('<net k="hash" v="0.0.1" />');
 
 // Process data for XML storage
 const result = processDataForStorage(data, operatorAddress);
@@ -229,4 +285,3 @@ Hierarchical storage using XML references. Supports recursive resolution and ope
 ## License
 
 MIT
-

package/dist/index.d.mts

@@ -3,9 +3,12 @@ import { Abi, PublicClient } from 'viem';
 import { WriteTransactionConfig } from '@net-protocol/core';
 
 /**
- * Storage data tuple: [text, data]
+ * Storage data object: { text, value }
  */
-type StorageData = [string, string];
+type StorageData = {
+    text: string;
+    value: string;
+};
 /**
  * Bulk storage key for batch operations
  */
@@ -73,7 +76,6 @@ type UseXmlStorageOptions = {
     index?: number;
     keyFormat?: "raw" | "bytes32";
     useRouter?: boolean;
-    returnFormat?: "object" | "tuple";
     outputFormat?: "hex" | "string";
 };
 /**
@@ -96,8 +98,11 @@ declare function useStorageForOperator({ chainId, operatorAddress, }: UseStorage
     isLoading: boolean;
     error: undefined;
 };
-declare function useStorageForOperatorAndKey({ chainId, key, operatorAddress, keyFormat, }: UseStorageOptions): {
-    data: StorageData | undefined;
+declare function useStorageForOperatorAndKey({ chainId, key, operatorAddress, keyFormat, outputFormat, }: UseStorageOptions): {
+    data: {
+        text: string;
+        value: string;
+    } | undefined;
     isLoading: boolean;
     error: Error | undefined;
 };
@@ -130,15 +135,9 @@ declare function useStorageTotalWrites({ chainId, key, operatorAddress, enabled,
     error: viem.ReadContractErrorType | null | undefined;
 };
 
-declare function useXmlStorage({ chainId, key, operatorAddress, skipXmlParsing, enabled, content, index, keyFormat, useRouter, returnFormat, outputFormat, }: UseXmlStorageOptions): {
-    data: StorageData | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-    filename?: undefined;
-    isXml?: undefined;
-} | {
-    data: string | undefined;
-    filename: string;
+declare function useXmlStorage({ chainId, key, operatorAddress, skipXmlParsing, enabled, content, index, keyFormat, useRouter, outputFormat, }: UseXmlStorageOptions): {
+    text: string;
+    value: string;
     isLoading: boolean;
     error: Error | undefined;
     isXml: boolean;

package/dist/index.d.ts

@@ -3,9 +3,12 @@ import { Abi, PublicClient } from 'viem';
 import { WriteTransactionConfig } from '@net-protocol/core';
 
 /**
- * Storage data tuple: [text, data]
+ * Storage data object: { text, value }
  */
-type StorageData = [string, string];
+type StorageData = {
+    text: string;
+    value: string;
+};
 /**
  * Bulk storage key for batch operations
  */
@@ -73,7 +76,6 @@ type UseXmlStorageOptions = {
     index?: number;
     keyFormat?: "raw" | "bytes32";
     useRouter?: boolean;
-    returnFormat?: "object" | "tuple";
     outputFormat?: "hex" | "string";
 };
 /**
@@ -96,8 +98,11 @@ declare function useStorageForOperator({ chainId, operatorAddress, }: UseStorage
     isLoading: boolean;
     error: undefined;
 };
-declare function useStorageForOperatorAndKey({ chainId, key, operatorAddress, keyFormat, }: UseStorageOptions): {
-    data: StorageData | undefined;
+declare function useStorageForOperatorAndKey({ chainId, key, operatorAddress, keyFormat, outputFormat, }: UseStorageOptions): {
+    data: {
+        text: string;
+        value: string;
+    } | undefined;
     isLoading: boolean;
     error: Error | undefined;
 };
@@ -130,15 +135,9 @@ declare function useStorageTotalWrites({ chainId, key, operatorAddress, enabled,
     error: viem.ReadContractErrorType | null | undefined;
 };
 
-declare function useXmlStorage({ chainId, key, operatorAddress, skipXmlParsing, enabled, content, index, keyFormat, useRouter, returnFormat, outputFormat, }: UseXmlStorageOptions): {
-    data: StorageData | undefined;
-    isLoading: boolean;
-    error: Error | undefined;
-    filename?: undefined;
-    isXml?: undefined;
-} | {
-    data: string | undefined;
-    filename: string;
+declare function useXmlStorage({ chainId, key, operatorAddress, skipXmlParsing, enabled, content, index, keyFormat, useRouter, outputFormat, }: UseXmlStorageOptions): {
+    text: string;
+    value: string;
     isLoading: boolean;
     error: Error | undefined;
     isXml: boolean;

package/dist/index.js

@@ -747,10 +747,10 @@ function useStorage({
   const outputAsString = outputFormat === "string";
   const storageKeyBytes = key ? getStorageKeyBytes(key, keyFormat) : void 0;
   const formatData = (text, dataHex) => {
-    if (outputAsString) {
-      return [text, viem.hexToString(dataHex)];
-    }
-    return [text, dataHex];
+    return {
+      text,
+      value: outputAsString ? viem.hexToString(dataHex) : dataHex
+    };
   };
   const [routerData, setRouterData] = react.useState();
   const [routerChunkLoading, setRouterChunkLoading] = react.useState(false);
@@ -772,6 +772,10 @@ function useStorage({
       }
       const [isChunkedStorage, text, data] = routerHook.data;
       if (!isChunkedStorage) {
+        if (!data || typeof data !== "string") {
+          setRouterData(void 0);
+          return;
+        }
         const formatted = formatData(text, data);
         setRouterData(formatted);
         return;
@@ -804,10 +808,10 @@ function useStorage({
           setRouterData(void 0);
         } else {
           if (outputAsString) {
-            setRouterData([text, assembledString]);
+            setRouterData({ text, value: assembledString });
           } else {
             const hexData = viem.stringToHex(assembledString);
-            setRouterData([text, hexData]);
+            setRouterData({ text, value: hexData });
           }
         }
       } catch (error) {
@@ -894,6 +898,11 @@ function useStorage({
           args: [storageKeyBytes2, operatorAddress, index]
         });
         const [text, data] = result;
+        if (!data || typeof data !== "string") {
+          setHistoricalData(void 0);
+          setHistoricalLoading(false);
+          return;
+        }
         setHistoricalData(formatData(text, data));
       } catch (error) {
         console.error(
@@ -906,7 +915,15 @@ function useStorage({
       }
     }
     fetchHistoricalVersion();
-  }, [chainId, key, operatorAddress, index, enabled, isLatestVersion, outputAsString]);
+  }, [
+    chainId,
+    key,
+    operatorAddress,
+    index,
+    enabled,
+    isLatestVersion,
+    outputAsString
+  ]);
   if (!isLatestVersion) {
     return {
       data: historicalData,
@@ -921,7 +938,14 @@ function useStorage({
       error: routerHook.error || routerChunkError
     };
   }
-  const formattedDirectData = latestData ? formatData(latestData[0], latestData[1]) : void 0;
+  const formattedDirectData = latestData ? (() => {
+    const result = latestData;
+    const [text, valueHex] = result;
+    if (!valueHex || typeof valueHex !== "string") {
+      return void 0;
+    }
+    return formatData(text, valueHex);
+  })() : void 0;
   return {
     data: formattedDirectData,
     isLoading: latestLoading,
@@ -963,9 +987,11 @@ function useStorageForOperatorAndKey({
   chainId,
   key,
   operatorAddress,
-  keyFormat
+  keyFormat,
+  outputFormat = "hex"
 }) {
   const storageKeyBytes = key ? getStorageKeyBytes(key, keyFormat) : void 0;
+  const outputAsString = outputFormat === "string";
   const readContractArgs = {
     abi: STORAGE_CONTRACT.abi,
     address: STORAGE_CONTRACT.address,
@@ -978,7 +1004,13 @@ function useStorageForOperatorAndKey({
   };
   const { data, isLoading, error } = wagmi.useReadContract(readContractArgs);
   return {
-    data,
+    data: data ? (() => {
+      const [text, valueHex] = data;
+      return {
+        text,
+        value: outputAsString ? viem.hexToString(valueHex) : valueHex
+      };
+    })() : void 0,
     isLoading,
     error
   };
@@ -1188,11 +1220,9 @@ function useXmlStorage({
   index,
   keyFormat,
   useRouter,
-  returnFormat = "object",
   outputFormat = "hex"
 }) {
   const isPreviewMode = !!content;
-  const returnAsTuple = returnFormat === "tuple";
   const outputAsString = outputFormat === "string";
   const {
     data: metadata,
@@ -1215,8 +1245,8 @@ function useXmlStorage({
   const metadataString = react.useMemo(() => {
     if (skipXmlParsing) return "";
     if (isPreviewMode) return content || "";
-    if (!metadata?.[1]) return "";
-    return metadata[1];
+    if (!metadata?.value) return "";
+    return metadata.value;
   }, [skipXmlParsing, isPreviewMode, content, metadata]);
   react.useMemo(() => {
     if (!metadataString) return [];
@@ -1267,78 +1297,22 @@ function useXmlStorage({
     if (skipXmlParsing || !metadataString) return false;
     return containsXmlReferences(metadataString);
   }, [metadataString, skipXmlParsing]);
-  if (returnAsTuple) {
-    if (skipXmlParsing) {
-      if (isPreviewMode) {
-        const contentValue = content || "";
-        return {
-          data: contentValue ? outputAsString ? [metadata?.[0] || "", contentValue] : [
-            metadata?.[0] || "",
-            viem.stringToHex(contentValue)
-          ] : void 0,
-          isLoading: metadataLoading,
-          error: metadataError
-        };
-      } else {
-        const dataValue = metadata?.[1];
-        return {
-          data: dataValue ? outputAsString ? [metadata?.[0] || "", dataValue] : [
-            metadata?.[0] || "",
-            viem.stringToHex(dataValue)
-          ] : void 0,
-          isLoading: metadataLoading,
-          error: metadataError
-        };
-      }
-    }
-    if (isXml) {
-      if (!assembledData) {
-        return {
-          data: void 0,
-          isLoading: metadataLoading || chunksLoading,
-          error: metadataError || chunksError
-        };
-      }
-      const hexData = viem.stringToHex(assembledData);
-      return {
-        data: outputAsString ? [metadata?.[0] || "", assembledData] : [metadata?.[0] || "", hexData],
-        isLoading: metadataLoading || chunksLoading,
-        error: metadataError || chunksError
-      };
-    } else {
-      if (!metadata) {
-        return {
-          data: void 0,
-          isLoading: metadataLoading,
-          error: metadataError
-        };
-      }
-      const dataValue = metadata[1];
-      const returnValue = dataValue ? outputAsString ? [metadata[0], dataValue] : [
-        metadata[0],
-        viem.stringToHex(dataValue)
-      ] : void 0;
-      return {
-        data: returnValue,
-        isLoading: metadataLoading,
-        error: metadataError
-      };
-    }
-  }
+  const formatValue = (value) => {
+    if (!value) return "";
+    return outputAsString ? value : viem.stringToHex(value);
+  };
   if (skipXmlParsing) {
     return {
-      data: isPreviewMode ? content || "" : metadata?.[1] || "",
-      // metadata[1] is already a plain string
-      filename: metadata?.[0] || "",
+      text: metadata?.text || "",
+      value: isPreviewMode ? content || "" : formatValue(metadata?.value),
       isLoading: metadataLoading,
       error: metadataError,
       isXml: false
     };
   }
   return {
-    data: isXml ? assembledData : isPreviewMode ? content || "" : metadata?.[1] || "",
-    // metadata[1] is already a plain string
-    filename: metadata?.[0] || "",
+    text: metadata?.text || "",
+    value: isXml ? formatValue(assembledData) : isPreviewMode ? content || "" : formatValue(metadata?.value),
     isLoading: metadataLoading || isXml && chunksLoading,
     error: metadataError || chunksError,
     isXml
@@ -1375,16 +1349,13 @@ function useStorageFromRouter({
       }
       const [isChunkedStorage, text, data] = routerResult;
       if (!isChunkedStorage) {
-        setAssembledData([text, data]);
+        setAssembledData({ text, value: data });
         return;
       }
       setIsChunkLoading(true);
       setChunkError(void 0);
       try {
-        const [chunkCount] = viem.decodeAbiParameters(
-          [{ type: "uint8" }],
-          data
-        );
+        const [chunkCount] = viem.decodeAbiParameters([{ type: "uint8" }], data);
         if (chunkCount === 0) {
           setAssembledData(void 0);
           return;
@@ -1400,7 +1371,7 @@ function useStorageFromRouter({
           setAssembledData(void 0);
         } else {
           const hexData = viem.stringToHex(assembledString);
-          setAssembledData([text, hexData]);
+          setAssembledData({ text, value: hexData });
         }
       } catch (error) {
         setChunkError(error);
@@ -1624,7 +1595,8 @@ var StorageClient = class {
     });
     try {
       const result = await actions.readContract(this.client, config);
-      return result;
+      const [text, value] = result;
+      return { text, value };
     } catch {
       return null;
     }
@@ -1642,7 +1614,8 @@ var StorageClient = class {
     });
     try {
       const result = await actions.readContract(this.client, config);
-      return result;
+      const [text, value] = result;
+      return { text, value };
     } catch {
       return null;
     }
@@ -1829,7 +1802,8 @@ var StorageClient = class {
         functionName: "getForOperatorAndKey",
         args: [params.operator, storageKeyBytes]
       });
-      return result;
+      const [text, value] = result;
+      return { text, value };
     } catch {
       return null;
     }
@@ -1869,8 +1843,9 @@ var StorageClient = class {
         if (!result) {
           throw new Error("StoredDataNotFound");
         }
-        [text, data] = result;
-        data = viem.hexToString(data);
+        const resultObj = result;
+        text = resultObj.text;
+        data = viem.hexToString(resultObj.value);
       }
     } else {
       const result = await this.getViaRouter({
@@ -1940,7 +1915,9 @@ var StorageClient = class {
       throw new Error("Chunks array cannot be empty");
     }
     if (params.chunks && params.chunks.length > 255) {
-      throw new Error(`Too many chunks: ${params.chunks.length} exceeds maximum of 255`);
+      throw new Error(
+        `Too many chunks: ${params.chunks.length} exceeds maximum of 255`
+      );
     }
   }
   /**
@@ -1952,7 +1929,9 @@ var StorageClient = class {
     const transactionConfigs = [];
     for (const xmlChunk of params.xmlChunks) {
       const chunks = chunkDataForStorage(xmlChunk);
-      const chunkedHash = core.keccak256HashString(xmlChunk + params.operatorAddress);
+      const chunkedHash = core.keccak256HashString(
+        xmlChunk + params.operatorAddress
+      );
       chunkedStorageHashes.push(chunkedHash);
       const config = this.prepareChunkedPut({
         key: chunkedHash,
@@ -1977,7 +1956,10 @@ var StorageClient = class {
    */
   preparePut(params) {
     this.validateStorageParams({ key: params.key });
-    const keyBytes32 = getStorageKeyBytes(params.key, params.keyFormat);
+    const keyBytes32 = getStorageKeyBytes(
+      params.key,
+      params.keyFormat
+    );
     const valueHex = core.normalizeDataOrEmpty(params.value);
     return {
       to: STORAGE_CONTRACT.address,
@@ -1991,7 +1973,10 @@ var StorageClient = class {
    */
   prepareChunkedPut(params) {
     this.validateStorageParams({ key: params.key, chunks: params.chunks });
-    const keyBytes32 = getStorageKeyBytes(params.key, params.keyFormat);
+    const keyBytes32 = getStorageKeyBytes(
+      params.key,
+      params.keyFormat
+    );
     for (const chunk of params.chunks) {
       if (!chunk.startsWith("0x")) {
         throw new Error(`Invalid chunk format: ${chunk} must be a hex string`);
@@ -2013,7 +1998,10 @@ var StorageClient = class {
     }
     const bulkEntries = params.entries.map((entry) => {
       this.validateStorageParams({ key: entry.key });
-      const keyBytes32 = getStorageKeyBytes(entry.key, params.keyFormat);
+      const keyBytes32 = getStorageKeyBytes(
+        entry.key,
+        params.keyFormat
+      );
       const valueHex = core.normalizeDataOrEmpty(entry.value);
       return {
         key: keyBytes32,
@@ -2053,7 +2041,10 @@ var StorageClient = class {
         keyFormat: params.keyFormat
       });
       return {
-        transactionConfigs: [metadataConfig, ...chunkedResult.transactionConfigs],
+        transactionConfigs: [
+          metadataConfig,
+          ...chunkedResult.transactionConfigs
+        ],
         topLevelHash: result.topLevelHash,
         metadata: chunkedResult.xmlMetadata
       };