@net-protocol/storage 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,523 @@
+import * as viem from 'viem';
+import { Abi, PublicClient } from 'viem';
+import { WriteTransactionConfig } from '@net-protocol/core';
+
+/**
+ * Storage data tuple: [text, data]
+ */
+type StorageData = [string, string];
+/**
+ * Bulk storage key for batch operations
+ */
+type BulkStorageKey = {
+    key: string;
+    operator: string;
+    keyFormat?: "raw" | "bytes32";
+};
+/**
+ * Bulk storage result
+ */
+type BulkStorageResult = {
+    text: string;
+    value: string;
+};
+/**
+ * Options for useStorage hook
+ */
+type UseStorageOptions = {
+    chainId: number;
+    key?: string;
+    operatorAddress?: string;
+    enabled?: boolean;
+    index?: number;
+    keyFormat?: "raw" | "bytes32";
+    useRouter?: boolean;
+    outputFormat?: "hex" | "string";
+};
+/**
+ * Options for StorageClient
+ */
+type StorageClientOptions = {
+    chainId: number;
+    overrides?: {
+        rpcUrls: string[];
+    };
+};
+/**
+ * XML reference structure
+ */
+interface XmlReference$1 {
+    hash: string;
+    version: string;
+    index?: number;
+    operator?: string;
+    source?: string;
+}
+/**
+ * Chunked storage metadata
+ */
+type ChunkedMetadata = {
+    chunkCount: number;
+    originalText: string;
+};
+/**
+ * Options for useXmlStorage hook
+ */
+type UseXmlStorageOptions = {
+    chainId: number;
+    key?: string;
+    operatorAddress: string;
+    skipXmlParsing?: boolean;
+    enabled?: boolean;
+    content?: string;
+    index?: number;
+    keyFormat?: "raw" | "bytes32";
+    useRouter?: boolean;
+    returnFormat?: "object" | "tuple";
+    outputFormat?: "hex" | "string";
+};
+/**
+ * Options for useStorageFromRouter hook
+ */
+type UseStorageFromRouterOptions = {
+    chainId: number;
+    storageKey: `0x${string}`;
+    operatorAddress: string;
+    enabled?: boolean;
+};
+
+declare function useStorage({ chainId, key, operatorAddress, enabled, index, keyFormat, useRouter, outputFormat, }: UseStorageOptions): {
+    data: StorageData | undefined;
+    isLoading: boolean;
+    error: Error | undefined;
+};
+declare function useStorageForOperator({ chainId, operatorAddress, }: UseStorageOptions): {
+    data: any[][];
+    isLoading: boolean;
+    error: undefined;
+};
+declare function useStorageForOperatorAndKey({ chainId, key, operatorAddress, keyFormat, }: UseStorageOptions): {
+    data: StorageData | undefined;
+    isLoading: boolean;
+    error: Error | undefined;
+};
+declare function useBulkStorage({ chainId, keys, safe, keyFormat, }: {
+    chainId: number;
+    keys: BulkStorageKey[];
+    safe?: boolean;
+    keyFormat?: "raw" | "bytes32";
+}): {
+    data: {
+        text: string;
+        value: string;
+    }[] | undefined;
+    isLoading: boolean;
+    error: Error | undefined;
+};
+/**
+ * Get total number of versions (writes) for a storage key
+ * Tries both chunked storage and regular storage
+ */
+declare function useStorageTotalWrites({ chainId, key, operatorAddress, enabled, keyFormat, }: {
+    chainId: number;
+    key?: string;
+    operatorAddress?: string;
+    enabled?: boolean;
+    keyFormat?: "raw" | "bytes32";
+}): {
+    data: number | undefined;
+    isLoading: boolean;
+    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;
+    isLoading: boolean;
+    error: Error | undefined;
+    isXml: boolean;
+};
+
+/**
+ * Generic hook to fetch storage content from StorageRouter
+ * Handles both regular storage and chunked storage seamlessly
+ * Works for any storage key (not just canvases)
+ */
+declare function useStorageFromRouter({ chainId, storageKey, operatorAddress, enabled, }: UseStorageFromRouterOptions): {
+    data: StorageData | undefined;
+    isLoading: boolean;
+    error: Error | undefined;
+};
+
+/**
+ * StorageClient - Client for interacting with Net protocol storage
+ *
+ * **Pattern for client methods:**
+ * - Client methods never require `chainId` in their parameters
+ * - All methods use `this.chainId` internally (set during construction)
+ * - Config builders receive `chainId` as a separate required parameter
+ * - This ensures consistency: the client's `chainId` is the single source of truth
+ */
+declare class StorageClient {
+    private client;
+    private chainId;
+    constructor(params: StorageClientOptions);
+    /**
+     * Get storage value for a key and operator (latest version)
+     */
+    get(params: {
+        key: string;
+        operator: string;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<StorageData | null>;
+    /**
+     * Get storage value at a specific historical index
+     */
+    getValueAtIndex(params: {
+        key: string;
+        operator: string;
+        index: number;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<StorageData | null>;
+    /**
+     * Get total number of writes (versions) for a key-operator pair
+     * Tries ChunkedStorageReader first, then Storage
+     */
+    getTotalWrites(params: {
+        key: string;
+        operator: string;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<number>;
+    /**
+     * Bulk get storage values
+     */
+    bulkGet(params: {
+        keys: BulkStorageKey[];
+        safe?: boolean;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<BulkStorageResult[]>;
+    /**
+     * Get storage value via StorageRouter (latest version)
+     * Returns data with storage type indication
+     */
+    getViaRouter(params: {
+        key: string;
+        operator: string;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<{
+        isChunkedStorage: boolean;
+        text: string;
+        data: string;
+    } | null>;
+    /**
+     * Get chunked storage metadata
+     */
+    getChunkedMetadata(params: {
+        key: string;
+        operator: string;
+        index?: number;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<{
+        chunkCount: number;
+        originalText: string;
+    } | null>;
+    /**
+     * Get chunked storage chunks
+     */
+    getChunked(params: {
+        key: string;
+        operator: string;
+        start: number;
+        end: number;
+        index?: number;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<string[]>;
+    /**
+     * Get chunked storage at a specific historical index
+     */
+    getChunkedAtIndex(params: {
+        key: string;
+        operator: string;
+        start: number;
+        end: number;
+        index: number;
+    }): Promise<string[]>;
+    /**
+     * Get all storage keys for an operator using Net contract
+     */
+    getForOperator(params: {
+        operator: string;
+    }): Promise<Array<[string, string, number, string]>>;
+    /**
+     * Get storage value for operator and key
+     */
+    getForOperatorAndKey(params: {
+        operator: string;
+        key: string;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<StorageData | null>;
+    /**
+     * Read storage data with XML resolution
+     */
+    readStorageData(params: {
+        key: string;
+        operator: string;
+        index?: number;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<{
+        text: string;
+        data: string;
+        isXml: boolean;
+    }>;
+    /**
+     * Read chunked storage data with decompression
+     */
+    readChunkedStorage(params: {
+        key: string;
+        operator: string;
+        index?: number;
+        keyFormat?: "raw" | "bytes32";
+    }): Promise<{
+        text: string;
+        data: string;
+    }>;
+    /**
+     * Validate storage parameters
+     */
+    private validateStorageParams;
+    /**
+     * Prepare transaction configs for storing XML chunks in ChunkedStorage backend.
+     * Each XML chunk is compressed and chunked into 20KB ChunkedStorage chunks.
+     */
+    private prepareXmlChunksForChunkedStorage;
+    /**
+     * Prepare transaction config for storing a single value in Storage contract.
+     */
+    preparePut(params: {
+        key: string | `0x${string}`;
+        text: string;
+        value: string | `0x${string}`;
+        keyFormat?: "raw" | "bytes32";
+    }): WriteTransactionConfig;
+    /**
+     * Prepare transaction config for storing data in ChunkedStorage contract.
+     */
+    prepareChunkedPut(params: {
+        key: string | `0x${string}`;
+        text: string;
+        chunks: string[];
+        keyFormat?: "raw" | "bytes32";
+    }): WriteTransactionConfig;
+    /**
+     * Prepare transaction config for bulk storage operations using Storage.bulkPut.
+     */
+    prepareBulkPut(params: {
+        entries: Array<{
+            key: string | `0x${string}`;
+            text: string;
+            value: string | `0x${string}`;
+        }>;
+        keyFormat?: "raw" | "bytes32";
+    }): WriteTransactionConfig;
+    /**
+     * Prepare transaction configs for XML storage (multiple transactions - metadata + chunks).
+     */
+    prepareXmlStorage(params: {
+        data: string;
+        operatorAddress: `0x${string}`;
+        storageKey?: string | `0x${string}`;
+        filename?: string;
+        useChunkedStorageBackend?: boolean;
+        keyFormat?: "raw" | "bytes32";
+    }): {
+        transactionConfigs: WriteTransactionConfig[];
+        topLevelHash: string;
+        metadata: string;
+    };
+}
+
+/**
+ * Format storage key for display, decoding hex to readable text when possible
+ * Returns both the display text and whether it was successfully decoded
+ */
+declare function formatStorageKeyForDisplay(storageKey: string): {
+    displayText: string;
+    isDecoded: boolean;
+};
+/**
+ * Get storage key as bytes32 format
+ * Supports direct hex bytes32 input or converts string to bytes32
+ * For strings longer than 32 bytes, hashes them
+ *
+ * @param input - The storage key (raw string or bytes32 hex)
+ * @param keyFormat - Optional format override: "raw" to always convert, "bytes32" to use as-is, undefined for auto-detect
+ */
+declare function getStorageKeyBytes(input: string, keyFormat?: "raw" | "bytes32"): string;
+/**
+ * Encodes a storage key for use in URL paths.
+ *
+ * This ensures special characters (including trailing spaces) are preserved
+ * when storage keys are used in URLs.
+ *
+ * @param key - The storage key string (already decoded, from data or URL params)
+ * @returns URL-encoded storage key safe for use in path segments
+ *
+ * @example
+ * encodeStorageKeyForUrl('declaration of independence ')
+ * // Returns: 'declaration%20of%20independence%20'
+ */
+declare function encodeStorageKeyForUrl(key: string): string;
+/**
+ * Generate a <net ... /> embed tag for storage
+ * @param params - Object containing storage embed parameters
+ * @param params.storageKeyBytes - The storage key as bytes32 (hex string)
+ * @param params.operatorAddress - The operator address
+ * @param params.isRegularStorage - If true, includes s="d" for direct Storage.sol reads. If false/undefined, omits s attribute (defaults to ChunkedStorage)
+ * @param params.versionIndex - Optional version index. If provided, includes i="versionIndex" attribute to reference specific historical version
+ * @returns The embed tag string
+ */
+declare function generateStorageEmbedTag(params: {
+    storageKeyBytes: string;
+    operatorAddress: string;
+    isRegularStorage?: boolean;
+    versionIndex?: number;
+}): string;
+
+/**
+ * Chunks data for storage in ChunkedStorage contract
+ * First compresses the data using gzip, then chunks the compressed data
+ * @param data - The string data to chunk
+ * @returns Array of hex-encoded byte chunks of compressed data
+ */
+declare function chunkDataForStorage(data: string): string[];
+/**
+ * Determines if XML storage should be suggested for the given data
+ * @param data - The string data to check
+ * @returns True if XML storage should be suggested
+ */
+declare function shouldSuggestXmlStorage(data: string): boolean;
+/**
+ * Gets the estimated number of chunks for given data
+ * @param data - The string data
+ * @returns Number of chunks that would be created
+ */
+declare function getChunkCount(data: string): number;
+/**
+ * Assemble chunks into a single string and decompress
+ * Pure function - can be used in both client and server code
+ * @param chunks - Array of hex-encoded chunk strings
+ * @returns Decompressed string or undefined if decompression fails
+ */
+declare function assembleChunks(chunks: string[]): string | undefined;
+
+/**
+ * XML reference type for chunk metadata
+ */
+interface XmlReference {
+    hash: string;
+    version: string;
+    index?: number;
+    operator?: string;
+    source?: string;
+}
+/**
+ * Parse XML metadata to extract chunk references
+ * Format: <net k="hashValue" v="0.0.1" o="0xoperator" s="d" />
+ */
+declare function parseNetReferences(metadata: string): XmlReference[];
+/**
+ * Check if a string contains XML references
+ */
+declare function containsXmlReferences(data: string): boolean;
+/**
+ * Detect storage type based on content
+ */
+declare function detectStorageType(metadata: string): "xml" | "regular";
+/**
+ * Resolve operator address for a reference with fallback to default
+ */
+declare function resolveOperator(reference: XmlReference, defaultOperator: string): string;
+/**
+ * Generate unique key for a reference to detect circular dependencies
+ */
+declare function getReferenceKey(reference: XmlReference, defaultOperator: string): string;
+
+/**
+ * Split data into chunks of specified size
+ */
+declare function chunkData(data: string, chunkSize?: number): string[];
+/**
+ * Generate XML metadata string from chunk hashes
+ * Format: <net k="hash1" v="0.0.1" i="0" o="0xoperator" /><net k="hash2" v="0.0.1" i="0" o="0xoperator" />
+ */
+declare function generateXmlMetadata(chunkHashes: string[], historicalIndex: number, operatorAddress: string): string;
+/**
+ * Generate XML metadata string from chunk hashes with source support
+ * Format: <net k="hash1" v="0.0.1" i="0" o="0xoperator" s="d" /><net k="hash2" v="0.0.1" i="0" o="0xoperator" />
+ */
+declare function generateXmlMetadataWithSource(chunkHashes: string[], historicalIndex: number, operatorAddress: string, source?: string): string;
+/**
+ * Validate data size against constraints
+ */
+declare function validateDataSize(chunks: string[]): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Compute top-level hash from chunk hashes
+ */
+declare function computeTopLevelHash(chunkHashes: string[]): string;
+/**
+ * Complete chunking and hash generation process
+ */
+declare function processDataForStorage(data: string, operatorAddress: string, storageKey?: string): {
+    chunks: string[];
+    chunkHashes: string[];
+    xmlMetadata: string;
+    topLevelHash: string;
+    valid: boolean;
+    error?: string;
+};
+
+declare const STORAGE_CONTRACT: {
+    abi: Abi;
+    address: `0x${string}`;
+};
+declare const CHUNKED_STORAGE_CONTRACT: {
+    abi: Abi;
+    address: `0x${string}`;
+};
+declare const CHUNKED_STORAGE_READER_CONTRACT: {
+    abi: Abi;
+    address: `0x${string}`;
+};
+declare const STORAGE_ROUTER_CONTRACT: {
+    abi: Abi;
+    address: `0x${string}`;
+};
+declare const SAFE_STORAGE_READER_CONTRACT: {
+    abi: Abi;
+    address: `0x${string}`;
+};
+
+/**
+ * Maximum depth for recursive XML resolution
+ */
+declare const MAX_XML_DEPTH = 3;
+/**
+ * Number of XML references to fetch concurrently per batch
+ */
+declare const CONCURRENT_XML_FETCHES = 3;
+/**
+ * Recursively resolve XML references up to specified depth
+ * Handles circular reference detection and parallel fetching per layer
+ */
+declare function resolveXmlRecursive(content: string, defaultOperator: string, client: PublicClient, maxDepth: number, visited?: Set<string>, inheritedOperator?: string): Promise<string>;
+
+export { type BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, type ChunkedMetadata, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, type StorageClientOptions, type StorageData, type UseStorageOptions, type UseXmlStorageOptions, type XmlReference$1 as XmlReference, assembleChunks, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectStorageType, encodeStorageKeyForUrl, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, parseNetReferences, processDataForStorage, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, useBulkStorage, useStorage, useStorageForOperator, useStorageForOperatorAndKey, useStorageFromRouter, useStorageTotalWrites, useXmlStorage, validateDataSize };