@kynesyslabs/demosdk 2.8.10 → 2.8.11

package/build/storage/StorageProgram.d.ts

@@ -1,31 +1,40 @@
-import type { StorageProgramPayload, StorageProgramAccessControl } from "../types/blockchain/TransactionSubtypes/StorageProgramTransaction";
+import type { StorageProgramPayload, StorageProgramACL, StorageACLMode, StorageEncoding, StorageLocation, StorageGroupPermissions, StorageProgramAccessControl } from "../types/blockchain/TransactionSubtypes/StorageProgramTransaction";
 /**
- * Storage Program class for creating and managing key-value storage on Demos Network
+ * StorageProgram - Unified storage solution for Demos Network
+ *
+ * Supports both JSON (structured) and Binary (raw) data storage
+ * with robust access control and size-based pricing.
  *
  * Features:
  * - Deterministic address derivation (stor-{sha256})
- * - Key-value storage with 128KB limit
- * - Access control (private, public, restricted, deployer-only)
- * - Nested data structures (max 64 levels)
+ * - Dual encoding: JSON key-value or raw binary
+ * - Robust ACL: owner, allowed, blacklisted, public, groups
+ * - Size limit: 1MB for both encodings
+ * - Pricing: 1 DEM per 10KB
+ * - Permanent storage, owner/ACL-deletable only
+ * - IPFS-ready (stubs for future hybrid storage)
  *
  * @example
  * ```typescript
  * import { StorageProgram } from '@kynesyslabs/demosdk'
  *
- * // Derive storage address
- * const address = StorageProgram.deriveStorageAddress(
- *   'myDeployerAddress',
- *   'myAppConfig',
- *   'randomSalt123'
+ * // Create JSON storage program
+ * const jsonPayload = StorageProgram.createStorageProgram(
+ *   'demos1abc...',
+ *   'myConfig',
+ *   { apiKey: 'secret', settings: { theme: 'dark' } },
+ *   'json',
+ *   { mode: 'public' }
  * )
  *
- * // Create storage program
- * const payload = StorageProgram.createStorageProgram(
- *   'myDeployerAddress',
- *   'myAppConfig',
- *   { apiKey: 'secret', endpoint: 'https://api.example.com' },
- *   'public',
- *   'randomSalt123'
+ * // Create Binary storage program
+ * const binaryPayload = StorageProgram.createStorageProgram(
+ *   'demos1abc...',
+ *   'myImage',
+ *   Buffer.from(imageData).toString('base64'),
+ *   'binary',
+ *   { mode: 'restricted', allowed: ['demos1user1...'] },
+ *   { metadata: { filename: 'avatar.png', mimeType: 'image/png' } }
  * )
  * ```
  */
@@ -33,7 +42,7 @@ export declare class StorageProgram {
     /**
      * Derive a deterministic storage program address
      *
-     * @param deployerAddress - Address of the program deployer
+     * @param deployerAddress - Address of the program deployer (will be owner)
      * @param programName - Name of the storage program
      * @param salt - Optional random salt for uniqueness (default: empty string)
      * @returns Storage address in format: stor-{first 40 chars of sha256}
@@ -52,43 +61,75 @@ export declare class StorageProgram {
     /**
      * Create a new Storage Program
      *
-     * @param deployerAddress - Address creating the storage program (will be the deployer)
-     * @param programName - Name of the storage program
-     * @param initialData - Initial key-value data to store
-     * @param accessControl - Access control mode (default: 'private')
-     * @param salt - Optional random salt for address derivation
-     * @param allowedAddresses - List of allowed addresses (for 'restricted' mode)
+     * @param deployerAddress - Address creating the storage program (becomes owner)
+     * @param programName - Unique name for the program
+     * @param data - Initial data (JSON object or base64 binary string)
+     * @param encoding - "json" or "binary" (default: "json")
+     * @param acl - Access control configuration (default: owner-only)
+     * @param options - Additional options (salt, metadata, storageLocation)
      * @returns StorageProgramPayload for transaction creation
      *
      * @example
      * ```typescript
+     * // JSON storage with public read access
+     * const payload = StorageProgram.createStorageProgram(
+     *   'demos1abc...',
+     *   'appConfig',
+     *   { version: '1.0', features: ['auth', 'storage'] },
+     *   'json',
+     *   { mode: 'public' }
+     * )
+     *
+     * // Binary storage with group access
      * const payload = StorageProgram.createStorageProgram(
      *   'demos1abc...',
-     *   'userPreferences',
-     *   { theme: 'dark', language: 'en' },
-     *   'private'
+     *   'teamDocument',
+     *   base64EncodedPdf,
+     *   'binary',
+     *   {
+     *     mode: 'restricted',
+     *     groups: {
+     *       editors: { members: ['demos1a...', 'demos1b...'], permissions: ['read', 'write'] },
+     *       viewers: { members: ['demos1c...'], permissions: ['read'] }
+     *     }
+     *   },
+     *   { metadata: { filename: 'report.pdf', mimeType: 'application/pdf' } }
      * )
      * ```
      */
-    static createStorageProgram(deployerAddress: string, programName: string, initialData: Record<string, any>, accessControl?: StorageProgramAccessControl, salt?: string, allowedAddresses?: string[]): StorageProgramPayload;
+    static createStorageProgram(deployerAddress: string, programName: string, data: Record<string, any> | string, encoding?: StorageEncoding, acl?: Partial<StorageProgramACL>, options?: {
+        salt?: string;
+        metadata?: Record<string, unknown>;
+        storageLocation?: StorageLocation;
+    }): StorageProgramPayload;
     /**
-     * Write or update key-value data in a Storage Program
+     * Write/update data in a Storage Program
      *
      * @param storageAddress - The storage program address (stor-{hash})
-     * @param data - Key-value data to write/update
+     * @param data - Data to write (JSON object or base64 binary string)
+     * @param encoding - "json" or "binary" (default: "json")
      * @returns StorageProgramPayload for transaction creation
      *
      * @example
      * ```typescript
+     * // Update JSON data
+     * const payload = StorageProgram.writeStorage(
+     *   'stor-7a8b9c...',
+     *   { newKey: 'value', existingKey: 'updatedValue' },
+     *   'json'
+     * )
+     *
+     * // Update binary data
      * const payload = StorageProgram.writeStorage(
      *   'stor-7a8b9c...',
-     *   { newKey: 'value', existingKey: 'updatedValue' }
+     *   newBase64Content,
+     *   'binary'
      * )
      * ```
      */
-    static writeStorage(storageAddress: string, data: Record<string, any>): StorageProgramPayload;
+    static writeStorage(storageAddress: string, data: Record<string, any> | string, encoding?: StorageEncoding): StorageProgramPayload;
     /**
-     * Read data from a Storage Program (query operation, not a transaction)
+     * Read data from a Storage Program (creates payload for RPC)
      *
      * Note: This creates a payload for validation purposes.
      * Actual reads should use RPC endpoints like GET /storage-program/:address
@@ -107,32 +148,45 @@ export declare class StorageProgram {
      */
     static readStorage(storageAddress: string): StorageProgramPayload;
     /**
-     * Update access control settings for a Storage Program (deployer only)
+     * Update access control settings for a Storage Program (owner only)
      *
      * @param storageAddress - The storage program address
-     * @param accessControl - New access control mode
-     * @param allowedAddresses - Updated list of allowed addresses (for 'restricted' mode)
+     * @param acl - New access control configuration
      * @returns StorageProgramPayload for transaction creation
      *
      * @example
      * ```typescript
-     * // Change from private to public
+     * // Change to public access
      * const payload = StorageProgram.updateAccessControl(
      *   'stor-7a8b9c...',
-     *   'public'
+     *   { mode: 'public' }
      * )
      *
-     * // Set restricted access with allowlist
+     * // Add users to blacklist
      * const payload = StorageProgram.updateAccessControl(
      *   'stor-7a8b9c...',
-     *   'restricted',
-     *   ['demos1user1...', 'demos1user2...']
+     *   {
+     *     mode: 'public',
+     *     blacklisted: ['demos1bad...', 'demos1spam...']
+     *   }
+     * )
+     *
+     * // Set up group-based access
+     * const payload = StorageProgram.updateAccessControl(
+     *   'stor-7a8b9c...',
+     *   {
+     *     mode: 'restricted',
+     *     groups: {
+     *       admins: { members: ['demos1admin...'], permissions: ['read', 'write', 'delete'] },
+     *       users: { members: ['demos1user1...', 'demos1user2...'], permissions: ['read'] }
+     *     }
+     *   }
      * )
      * ```
      */
-    static updateAccessControl(storageAddress: string, accessControl: StorageProgramAccessControl, allowedAddresses?: string[]): StorageProgramPayload;
+    static updateAccessControl(storageAddress: string, acl: Partial<StorageProgramACL>): StorageProgramPayload;
     /**
-     * Delete an entire Storage Program (deployer only)
+     * Delete a Storage Program (owner/ACL-permissioned only)
      *
      * WARNING: This operation is irreversible and will delete all stored data.
      *
@@ -146,35 +200,66 @@ export declare class StorageProgram {
      */
     static deleteStorageProgram(storageAddress: string): StorageProgramPayload;
     /**
-     * Validate storage size against 128KB limit
+     * Validate data size against 1MB limit
      *
-     * @param data - The data object to validate
-     * @returns true if size is within limit, false otherwise
+     * @param data - Data to validate (JSON object or base64 string)
+     * @param encoding - Encoding type ("json" or "binary")
+     * @returns true if size is within 1MB limit, false otherwise
      *
      * @example
      * ```typescript
-     * const data = { key: 'value', nested: { data: 'here' } }
-     * if (StorageProgram.validateSize(data)) {
+     * // Validate JSON data
+     * if (StorageProgram.validateSize({ key: 'value' }, 'json')) {
+     *   // Safe to store
+     * }
+     *
+     * // Validate binary data
+     * if (StorageProgram.validateSize(base64String, 'binary')) {
      *   // Safe to store
      * }
      * ```
      */
-    static validateSize(data: Record<string, any>): boolean;
+    static validateSize(data: Record<string, any> | string, encoding?: StorageEncoding): boolean;
     /**
-     * Get the size of data in bytes
+     * Get data size in bytes
      *
-     * @param data - The data object to measure
+     * @param data - Data to measure (JSON object or base64 string)
+     * @param encoding - Encoding type ("json" or "binary")
      * @returns Size in bytes
      *
      * @example
      * ```typescript
-     * const size = StorageProgram.getDataSize({ key: 'value' })
+     * const size = StorageProgram.getDataSize({ key: 'value' }, 'json')
      * console.log(`Data size: ${size} bytes`)
      * ```
      */
-    static getDataSize(data: Record<string, any>): number;
+    static getDataSize(data: Record<string, any> | string, encoding?: StorageEncoding): number;
     /**
-     * Validate nesting depth (max 64 levels)
+     * Calculate storage fee based on data size
+     *
+     * Pricing: 1 DEM per 10KB (minimum 1 DEM)
+     *
+     * @param data - Data to calculate fee for (JSON object or base64 string)
+     * @param encoding - Encoding type ("json" or "binary")
+     * @returns Fee in DEM (bigint)
+     *
+     * @example
+     * ```typescript
+     * const fee = StorageProgram.calculateStorageFee({ key: 'value' }, 'json')
+     * console.log(`Storage fee: ${fee} DEM`)
+     *
+     * // Examples:
+     * // 5KB -> 1 DEM
+     * // 15KB -> 2 DEM
+     * // 100KB -> 10 DEM
+     * // 1MB -> 103 DEM
+     * ```
+     */
+    static calculateStorageFee(data: Record<string, any> | string, encoding?: StorageEncoding): bigint;
+    /**
+     * Validate JSON nesting depth (max 64 levels)
+     *
+     * Only applicable for JSON encoding.
      *
      * @param data - The data object to validate
      * @param maxDepth - Maximum allowed nesting depth (default: 64)
@@ -189,4 +274,109 @@ export declare class StorageProgram {
      * ```
      */
     static validateNestingDepth(data: any, maxDepth?: number): boolean;
+    /**
+     * Check if an address has permission for an operation
+     *
+     * ACL Resolution Priority:
+     * 1. Owner -> FULL ACCESS (always)
+     * 2. Blacklisted -> DENIED (even if in allowed/groups)
+     * 3. Allowed -> permissions granted
+     * 4. Groups -> check group permissions
+     * 5. Mode fallback: owner/restricted -> DENIED, public -> READ only
+     *
+     * @param acl - Access control configuration
+     * @param ownerAddress - Owner address of the storage program
+     * @param requestingAddress - Address requesting permission
+     * @param permission - Permission type to check
+     * @returns true if permission is granted
+     *
+     * @example
+     * ```typescript
+     * const acl = { mode: 'public', blacklisted: ['demos1spam...'] }
+     * const canRead = StorageProgram.checkPermission(acl, owner, user, 'read')
+     * ```
+     */
+    static checkPermission(acl: StorageProgramACL, ownerAddress: string, requestingAddress: string, permission: "read" | "write" | "delete"): boolean;
+    /**
+     * Create a public ACL (anyone can read, owner writes)
+     *
+     * @returns StorageProgramACL configured for public read access
+     *
+     * @example
+     * ```typescript
+     * const acl = StorageProgram.publicACL()
+     * // { mode: 'public' }
+     * ```
+     */
+    static publicACL(): StorageProgramACL;
+    /**
+     * Create a private/owner-only ACL
+     *
+     * @returns StorageProgramACL configured for owner-only access
+     *
+     * @example
+     * ```typescript
+     * const acl = StorageProgram.privateACL()
+     * // { mode: 'owner' }
+     * ```
+     */
+    static privateACL(): StorageProgramACL;
+    /**
+     * Create a restricted ACL with allowed addresses
+     *
+     * @param allowed - List of addresses allowed to access
+     * @returns StorageProgramACL configured for restricted access
+     *
+     * @example
+     * ```typescript
+     * const acl = StorageProgram.restrictedACL(['demos1a...', 'demos1b...'])
+     * // { mode: 'restricted', allowed: ['demos1a...', 'demos1b...'] }
+     * ```
+     */
+    static restrictedACL(allowed: string[]): StorageProgramACL;
+    /**
+     * Create a group-based ACL
+     *
+     * @param groups - Named groups with members and permissions
+     * @returns StorageProgramACL configured for group-based access
+     *
+     * @example
+     * ```typescript
+     * const acl = StorageProgram.groupACL({
+     *   admins: { members: ['demos1admin...'], permissions: ['read', 'write', 'delete'] },
+     *   editors: { members: ['demos1ed1...', 'demos1ed2...'], permissions: ['read', 'write'] },
+     *   viewers: { members: ['demos1view...'], permissions: ['read'] }
+     * })
+     * ```
+     */
+    static groupACL(groups: Record<string, StorageGroupPermissions>): StorageProgramACL;
+    /**
+     * Create an ACL with a blacklist
+     *
+     * @param mode - Base mode ('public' or 'restricted')
+     * @param blacklisted - Addresses to block
+     * @param allowed - Optional allowed addresses (for restricted mode)
+     * @returns StorageProgramACL with blacklist configured
+     *
+     * @example
+     * ```typescript
+     * // Public but block spam addresses
+     * const acl = StorageProgram.blacklistACL('public', ['demos1spam...'])
+     * ```
+     */
+    static blacklistACL(mode: StorageACLMode, blacklisted: string[], allowed?: string[]): StorageProgramACL;
+    /**
+     * @deprecated Use createStorageProgram with acl parameter instead.
+     * Kept for backward compatibility.
+     *
+     * Create a new Storage Program with legacy access control
+     */
+    static createStorageProgramLegacy(deployerAddress: string, programName: string, initialData: Record<string, any>, accessControl?: StorageProgramAccessControl, salt?: string, allowedAddresses?: string[]): StorageProgramPayload;
+    /**
+     * @deprecated Use updateAccessControl with acl parameter instead.
+     * Kept for backward compatibility.
+     *
+     * Update access control with legacy mode
+     */
+    static updateAccessControlLegacy(storageAddress: string, accessControl: StorageProgramAccessControl, allowedAddresses?: string[]): StorageProgramPayload;
 }

package/build/storage/StorageProgram.js

@@ -2,42 +2,55 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageProgram = void 0;
 const crypto_1 = require("crypto");
-// REVIEW: Storage Program class for key-value storage with access control
+const StorageProgramTransaction_1 = require("../types/blockchain/TransactionSubtypes/StorageProgramTransaction");
+// REVIEW: Unified Storage Program class for both JSON and Binary storage with robust ACL
 /**
- * Storage Program class for creating and managing key-value storage on Demos Network
+ * StorageProgram - Unified storage solution for Demos Network
+ *
+ * Supports both JSON (structured) and Binary (raw) data storage
+ * with robust access control and size-based pricing.
  *
  * Features:
  * - Deterministic address derivation (stor-{sha256})
- * - Key-value storage with 128KB limit
- * - Access control (private, public, restricted, deployer-only)
- * - Nested data structures (max 64 levels)
+ * - Dual encoding: JSON key-value or raw binary
+ * - Robust ACL: owner, allowed, blacklisted, public, groups
+ * - Size limit: 1MB for both encodings
+ * - Pricing: 1 DEM per 10KB
+ * - Permanent storage, owner/ACL-deletable only
+ * - IPFS-ready (stubs for future hybrid storage)
  *
  * @example
  * ```typescript
  * import { StorageProgram } from '@kynesyslabs/demosdk'
  *
- * // Derive storage address
- * const address = StorageProgram.deriveStorageAddress(
- *   'myDeployerAddress',
- *   'myAppConfig',
- *   'randomSalt123'
+ * // Create JSON storage program
+ * const jsonPayload = StorageProgram.createStorageProgram(
+ *   'demos1abc...',
+ *   'myConfig',
+ *   { apiKey: 'secret', settings: { theme: 'dark' } },
+ *   'json',
+ *   { mode: 'public' }
  * )
  *
- * // Create storage program
- * const payload = StorageProgram.createStorageProgram(
- *   'myDeployerAddress',
- *   'myAppConfig',
- *   { apiKey: 'secret', endpoint: 'https://api.example.com' },
- *   'public',
- *   'randomSalt123'
+ * // Create Binary storage program
+ * const binaryPayload = StorageProgram.createStorageProgram(
+ *   'demos1abc...',
+ *   'myImage',
+ *   Buffer.from(imageData).toString('base64'),
+ *   'binary',
+ *   { mode: 'restricted', allowed: ['demos1user1...'] },
+ *   { metadata: { filename: 'avatar.png', mimeType: 'image/png' } }
  * )
  * ```
  */
 class StorageProgram {
+    // ========================================================================
+    // Address Derivation
+    // ========================================================================
     /**
      * Derive a deterministic storage program address
      *
-     * @param deployerAddress - Address of the program deployer
+     * @param deployerAddress - Address of the program deployer (will be owner)
      * @param programName - Name of the storage program
      * @param salt - Optional random salt for uniqueness (default: empty string)
      * @returns Storage address in format: stor-{first 40 chars of sha256}
@@ -60,64 +73,103 @@ class StorageProgram {
         const addressHash = hash.substring(0, 40);
         return `stor-${addressHash}`;
     }
+    // ========================================================================
+    // Program Operations
+    // ========================================================================
     /**
      * Create a new Storage Program
      *
-     * @param deployerAddress - Address creating the storage program (will be the deployer)
-     * @param programName - Name of the storage program
-     * @param initialData - Initial key-value data to store
-     * @param accessControl - Access control mode (default: 'private')
-     * @param salt - Optional random salt for address derivation
-     * @param allowedAddresses - List of allowed addresses (for 'restricted' mode)
+     * @param deployerAddress - Address creating the storage program (becomes owner)
+     * @param programName - Unique name for the program
+     * @param data - Initial data (JSON object or base64 binary string)
+     * @param encoding - "json" or "binary" (default: "json")
+     * @param acl - Access control configuration (default: owner-only)
+     * @param options - Additional options (salt, metadata, storageLocation)
      * @returns StorageProgramPayload for transaction creation
      *
      * @example
      * ```typescript
+     * // JSON storage with public read access
      * const payload = StorageProgram.createStorageProgram(
      *   'demos1abc...',
-     *   'userPreferences',
-     *   { theme: 'dark', language: 'en' },
-     *   'private'
+     *   'appConfig',
+     *   { version: '1.0', features: ['auth', 'storage'] },
+     *   'json',
+     *   { mode: 'public' }
+     * )
+     *
+     * // Binary storage with group access
+     * const payload = StorageProgram.createStorageProgram(
+     *   'demos1abc...',
+     *   'teamDocument',
+     *   base64EncodedPdf,
+     *   'binary',
+     *   {
+     *     mode: 'restricted',
+     *     groups: {
+     *       editors: { members: ['demos1a...', 'demos1b...'], permissions: ['read', 'write'] },
+     *       viewers: { members: ['demos1c...'], permissions: ['read'] }
+     *     }
+     *   },
+     *   { metadata: { filename: 'report.pdf', mimeType: 'application/pdf' } }
      * )
      * ```
      */
-    static createStorageProgram(deployerAddress, programName, initialData, accessControl = "private", salt, allowedAddresses) {
-        // Derive storage address
-        const storageAddress = this.deriveStorageAddress(deployerAddress, programName, salt || "");
+    static createStorageProgram(deployerAddress, programName, data, encoding = "json", acl, options) {
+        const storageAddress = this.deriveStorageAddress(deployerAddress, programName, options?.salt || "");
+        const fullACL = {
+            mode: acl?.mode || "owner",
+            allowed: acl?.allowed,
+            blacklisted: acl?.blacklisted,
+            groups: acl?.groups,
+        };
         return {
             operation: "CREATE_STORAGE_PROGRAM",
             storageAddress,
             programName,
-            data: initialData,
-            accessControl,
-            allowedAddresses,
-            salt,
+            encoding,
+            data,
+            acl: fullACL,
+            salt: options?.salt,
+            metadata: options?.metadata,
+            storageLocation: options?.storageLocation || "onchain",
         };
     }
     /**
-     * Write or update key-value data in a Storage Program
+     * Write/update data in a Storage Program
      *
      * @param storageAddress - The storage program address (stor-{hash})
-     * @param data - Key-value data to write/update
+     * @param data - Data to write (JSON object or base64 binary string)
+     * @param encoding - "json" or "binary" (default: "json")
      * @returns StorageProgramPayload for transaction creation
      *
      * @example
      * ```typescript
+     * // Update JSON data
+     * const payload = StorageProgram.writeStorage(
+     *   'stor-7a8b9c...',
+     *   { newKey: 'value', existingKey: 'updatedValue' },
+     *   'json'
+     * )
+     *
+     * // Update binary data
      * const payload = StorageProgram.writeStorage(
      *   'stor-7a8b9c...',
-     *   { newKey: 'value', existingKey: 'updatedValue' }
+     *   newBase64Content,
+     *   'binary'
      * )
      * ```
      */
-    static writeStorage(storageAddress, data) {
+    static writeStorage(storageAddress, data, encoding = "json") {
         return {
             operation: "WRITE_STORAGE",
             storageAddress,
             data,
+            encoding,
         };
     }
     /**
-     * Read data from a Storage Program (query operation, not a transaction)
+     * Read data from a Storage Program (creates payload for RPC)
      *
      * Note: This creates a payload for validation purposes.
      * Actual reads should use RPC endpoints like GET /storage-program/:address
@@ -141,39 +193,51 @@ class StorageProgram {
         };
     }
     /**
-     * Update access control settings for a Storage Program (deployer only)
+     * Update access control settings for a Storage Program (owner only)
      *
      * @param storageAddress - The storage program address
-     * @param accessControl - New access control mode
-     * @param allowedAddresses - Updated list of allowed addresses (for 'restricted' mode)
+     * @param acl - New access control configuration
      * @returns StorageProgramPayload for transaction creation
      *
      * @example
      * ```typescript
-     * // Change from private to public
+     * // Change to public access
+     * const payload = StorageProgram.updateAccessControl(
+     *   'stor-7a8b9c...',
+     *   { mode: 'public' }
+     * )
+     *
+     * // Add users to blacklist
      * const payload = StorageProgram.updateAccessControl(
      *   'stor-7a8b9c...',
-     *   'public'
+     *   {
+     *     mode: 'public',
+     *     blacklisted: ['demos1bad...', 'demos1spam...']
+     *   }
      * )
      *
-     * // Set restricted access with allowlist
+     * // Set up group-based access
      * const payload = StorageProgram.updateAccessControl(
      *   'stor-7a8b9c...',
-     *   'restricted',
-     *   ['demos1user1...', 'demos1user2...']
+     *   {
+     *     mode: 'restricted',
+     *     groups: {
+     *       admins: { members: ['demos1admin...'], permissions: ['read', 'write', 'delete'] },
+     *       users: { members: ['demos1user1...', 'demos1user2...'], permissions: ['read'] }
+     *     }
+     *   }
      * )
      * ```
      */
-    static updateAccessControl(storageAddress, accessControl, allowedAddresses) {
+    static updateAccessControl(storageAddress, acl) {
         return {
             operation: "UPDATE_ACCESS_CONTROL",
             storageAddress,
-            accessControl,
-            allowedAddresses,
+            acl: acl,
         };
     }
     /**
-     * Delete an entire Storage Program (deployer only)
+     * Delete a Storage Program (owner/ACL-permissioned only)
      *
      * WARNING: This operation is irreversible and will delete all stored data.
      *
@@ -191,44 +255,91 @@ class StorageProgram {
             storageAddress,
         };
     }
+    // ========================================================================
+    // Validation Helpers
+    // ========================================================================
     /**
-     * Validate storage size against 128KB limit
+     * Validate data size against 1MB limit
      *
-     * @param data - The data object to validate
-     * @returns true if size is within limit, false otherwise
+     * @param data - Data to validate (JSON object or base64 string)
+     * @param encoding - Encoding type ("json" or "binary")
+     * @returns true if size is within 1MB limit, false otherwise
      *
      * @example
      * ```typescript
-     * const data = { key: 'value', nested: { data: 'here' } }
-     * if (StorageProgram.validateSize(data)) {
+     * // Validate JSON data
+     * if (StorageProgram.validateSize({ key: 'value' }, 'json')) {
+     *   // Safe to store
+     * }
+     *
+     * // Validate binary data
+     * if (StorageProgram.validateSize(base64String, 'binary')) {
      *   // Safe to store
      * }
      * ```
      */
-    static validateSize(data) {
-        const jsonString = JSON.stringify(data);
-        const sizeInBytes = new TextEncoder().encode(jsonString).length;
-        const maxSizeInBytes = 128 * 1024; // 128KB
-        return sizeInBytes <= maxSizeInBytes;
+    static validateSize(data, encoding = "json") {
+        const sizeBytes = this.getDataSize(data, encoding);
+        return sizeBytes <= StorageProgramTransaction_1.STORAGE_PROGRAM_CONSTANTS.MAX_SIZE_BYTES;
     }
     /**
-     * Get the size of data in bytes
+     * Get data size in bytes
      *
-     * @param data - The data object to measure
+     * @param data - Data to measure (JSON object or base64 string)
+     * @param encoding - Encoding type ("json" or "binary")
      * @returns Size in bytes
      *
      * @example
      * ```typescript
-     * const size = StorageProgram.getDataSize({ key: 'value' })
+     * const size = StorageProgram.getDataSize({ key: 'value' }, 'json')
      * console.log(`Data size: ${size} bytes`)
      * ```
      */
-    static getDataSize(data) {
-        const jsonString = JSON.stringify(data);
-        return new TextEncoder().encode(jsonString).length;
+    static getDataSize(data, encoding = "json") {
+        if (encoding === "binary") {
+            // Binary data is base64 encoded, decode to get actual size
+            // Base64 encoding: every 4 chars = 3 bytes
+            const base64String = data;
+            // Remove padding and calculate
+            const padding = (base64String.match(/=/g) || []).length;
+            return Math.floor((base64String.length * 3) / 4) - padding;
+        }
+        else {
+            // JSON data - measure serialized size
+            const jsonString = JSON.stringify(data);
+            return new TextEncoder().encode(jsonString).length;
+        }
+    }
+    /**
+     * Calculate storage fee based on data size
+     *
+     * Pricing: 1 DEM per 10KB (minimum 1 DEM)
+     *
+     * @param data - Data to calculate fee for (JSON object or base64 string)
+     * @param encoding - Encoding type ("json" or "binary")
+     * @returns Fee in DEM (bigint)
+     *
+     * @example
+     * ```typescript
+     * const fee = StorageProgram.calculateStorageFee({ key: 'value' }, 'json')
+     * console.log(`Storage fee: ${fee} DEM`)
+     *
+     * // Examples:
+     * // 5KB -> 1 DEM
+     * // 15KB -> 2 DEM
+     * // 100KB -> 10 DEM
+     * // 1MB -> 103 DEM
+     * ```
+     */
+    static calculateStorageFee(data, encoding = "json") {
+        const sizeBytes = this.getDataSize(data, encoding);
+        const chunks = Math.ceil(sizeBytes / StorageProgramTransaction_1.STORAGE_PROGRAM_CONSTANTS.PRICING_CHUNK_BYTES);
+        return BigInt(Math.max(1, chunks)) * StorageProgramTransaction_1.STORAGE_PROGRAM_CONSTANTS.FEE_PER_CHUNK;
     }
     /**
-     * Validate nesting depth (max 64 levels)
+     * Validate JSON nesting depth (max 64 levels)
+     *
+     * Only applicable for JSON encoding.
      *
      * @param data - The data object to validate
      * @param maxDepth - Maximum allowed nesting depth (default: 64)
@@ -242,7 +353,7 @@ class StorageProgram {
      * }
      * ```
      */
-    static validateNestingDepth(data, maxDepth = 64) {
+    static validateNestingDepth(data, maxDepth = StorageProgramTransaction_1.STORAGE_PROGRAM_CONSTANTS.MAX_JSON_NESTING_DEPTH) {
         const getDepth = (obj, currentDepth = 1) => {
             if (typeof obj !== "object" || obj === null) {
                 return currentDepth;
@@ -252,6 +363,173 @@ class StorageProgram {
         };
         return getDepth(data) <= maxDepth;
     }
+    // ========================================================================
+    // ACL Helpers
+    // ========================================================================
+    /**
+     * Check if an address has permission for an operation
+     *
+     * ACL Resolution Priority:
+     * 1. Owner -> FULL ACCESS (always)
+     * 2. Blacklisted -> DENIED (even if in allowed/groups)
+     * 3. Allowed -> permissions granted
+     * 4. Groups -> check group permissions
+     * 5. Mode fallback: owner/restricted -> DENIED, public -> READ only
+     *
+     * @param acl - Access control configuration
+     * @param ownerAddress - Owner address of the storage program
+     * @param requestingAddress - Address requesting permission
+     * @param permission - Permission type to check
+     * @returns true if permission is granted
+     *
+     * @example
+     * ```typescript
+     * const acl = { mode: 'public', blacklisted: ['demos1spam...'] }
+     * const canRead = StorageProgram.checkPermission(acl, owner, user, 'read')
+     * ```
+     */
+    static checkPermission(acl, ownerAddress, requestingAddress, permission) {
+        // 1. Owner always has full access
+        if (requestingAddress === ownerAddress)
+            return true;
+        // 2. Blacklisted addresses are always denied
+        if (acl.blacklisted?.includes(requestingAddress))
+            return false;
+        // 3. Check allowed list (grants all permissions)
+        if (acl.allowed?.includes(requestingAddress))
+            return true;
+        // 4. Check groups
+        if (acl.groups) {
+            for (const group of Object.values(acl.groups)) {
+                if (group.members.includes(requestingAddress) && group.permissions.includes(permission)) {
+                    return true;
+                }
+            }
+        }
+        // 5. Fall back to mode
+        switch (acl.mode) {
+            case "public":
+                return permission === "read"; // Public allows read only
+            case "owner":
+            case "restricted":
+            default:
+                return false;
+        }
+    }
+    /**
+     * Create a public ACL (anyone can read, owner writes)
+     *
+     * @returns StorageProgramACL configured for public read access
+     *
+     * @example
+     * ```typescript
+     * const acl = StorageProgram.publicACL()
+     * // { mode: 'public' }
+     * ```
+     */
+    static publicACL() {
+        return { mode: "public" };
+    }
+    /**
+     * Create a private/owner-only ACL
+     *
+     * @returns StorageProgramACL configured for owner-only access
+     *
+     * @example
+     * ```typescript
+     * const acl = StorageProgram.privateACL()
+     * // { mode: 'owner' }
+     * ```
+     */
+    static privateACL() {
+        return { mode: "owner" };
+    }
+    /**
+     * Create a restricted ACL with allowed addresses
+     *
+     * @param allowed - List of addresses allowed to access
+     * @returns StorageProgramACL configured for restricted access
+     *
+     * @example
+     * ```typescript
+     * const acl = StorageProgram.restrictedACL(['demos1a...', 'demos1b...'])
+     * // { mode: 'restricted', allowed: ['demos1a...', 'demos1b...'] }
+     * ```
+     */
+    static restrictedACL(allowed) {
+        return { mode: "restricted", allowed };
+    }
+    /**
+     * Create a group-based ACL
+     *
+     * @param groups - Named groups with members and permissions
+     * @returns StorageProgramACL configured for group-based access
+     *
+     * @example
+     * ```typescript
+     * const acl = StorageProgram.groupACL({
+     *   admins: { members: ['demos1admin...'], permissions: ['read', 'write', 'delete'] },
+     *   editors: { members: ['demos1ed1...', 'demos1ed2...'], permissions: ['read', 'write'] },
+     *   viewers: { members: ['demos1view...'], permissions: ['read'] }
+     * })
+     * ```
+     */
+    static groupACL(groups) {
+        return { mode: "restricted", groups };
+    }
+    /**
+     * Create an ACL with a blacklist
+     *
+     * @param mode - Base mode ('public' or 'restricted')
+     * @param blacklisted - Addresses to block
+     * @param allowed - Optional allowed addresses (for restricted mode)
+     * @returns StorageProgramACL with blacklist configured
+     *
+     * @example
+     * ```typescript
+     * // Public but block spam addresses
+     * const acl = StorageProgram.blacklistACL('public', ['demos1spam...'])
+     * ```
+     */
+    static blacklistACL(mode, blacklisted, allowed) {
+        return { mode, blacklisted, allowed };
+    }
+    // ========================================================================
+    // Legacy Compatibility Methods
+    // ========================================================================
+    /**
+     * @deprecated Use createStorageProgram with acl parameter instead.
+     * Kept for backward compatibility.
+     *
+     * Create a new Storage Program with legacy access control
+     */
+    static createStorageProgramLegacy(deployerAddress, programName, initialData, accessControl = "private", salt, allowedAddresses) {
+        const storageAddress = this.deriveStorageAddress(deployerAddress, programName, salt || "");
+        return {
+            operation: "CREATE_STORAGE_PROGRAM",
+            storageAddress,
+            programName,
+            data: initialData,
+            encoding: "json",
+            accessControl,
+            allowedAddresses,
+            salt,
+        };
+    }
+    /**
+     * @deprecated Use updateAccessControl with acl parameter instead.
+     * Kept for backward compatibility.
+     *
+     * Update access control with legacy mode
+     */
+    static updateAccessControlLegacy(storageAddress, accessControl, allowedAddresses) {
+        return {
+            operation: "UPDATE_ACCESS_CONTROL",
+            storageAddress,
+            accessControl,
+            allowedAddresses,
+        };
+    }
 }
 exports.StorageProgram = StorageProgram;
 //# sourceMappingURL=StorageProgram.js.map

package/build/storage/StorageProgram.js.map

@@ -1 +1 @@
-{"version":3,"file":"StorageProgram.js","sourceRoot":"","sources":["../../../src/storage/StorageProgram.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"StorageProgram.js","sourceRoot":"","sources":["../../../src/storage/StorageProgram.ts"],"names":[],"mappings":"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"}

package/build/storage/index.d.ts

@@ -1,2 +1,3 @@
 export { StorageProgram } from "./StorageProgram";
-export type { StorageProgramPayload, StorageProgramAccessControl, StorageProgramOperation, StorageProgramTransactionContent, StorageProgramTransaction, } from "../types/blockchain/TransactionSubtypes/StorageProgramTransaction";
+export type { StorageProgramOperation, StorageEncoding, StorageLocation, StorageACLMode, StorageGroupPermissions, StorageProgramACL, StorageProgramPayload, StorageProgramTransactionContent, StorageProgramTransaction, StorageProgramAccessControl, } from "../types/blockchain/TransactionSubtypes/StorageProgramTransaction";
+export { STORAGE_PROGRAM_CONSTANTS, isStorageProgramPayload, isValidEncoding, isValidStorageLocation, } from "../types/blockchain/TransactionSubtypes/StorageProgramTransaction";

package/build/storage/index.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StorageProgram = void 0;
+exports.isValidStorageLocation = exports.isValidEncoding = exports.isStorageProgramPayload = exports.STORAGE_PROGRAM_CONSTANTS = exports.StorageProgram = void 0;
 var StorageProgram_1 = require("./StorageProgram");
 Object.defineProperty(exports, "StorageProgram", { enumerable: true, get: function () { return StorageProgram_1.StorageProgram; } });
+var StorageProgramTransaction_1 = require("../types/blockchain/TransactionSubtypes/StorageProgramTransaction");
+Object.defineProperty(exports, "STORAGE_PROGRAM_CONSTANTS", { enumerable: true, get: function () { return StorageProgramTransaction_1.STORAGE_PROGRAM_CONSTANTS; } });
+Object.defineProperty(exports, "isStorageProgramPayload", { enumerable: true, get: function () { return StorageProgramTransaction_1.isStorageProgramPayload; } });
+Object.defineProperty(exports, "isValidEncoding", { enumerable: true, get: function () { return StorageProgramTransaction_1.isValidEncoding; } });
+Object.defineProperty(exports, "isValidStorageLocation", { enumerable: true, get: function () { return StorageProgramTransaction_1.isValidStorageLocation; } });
 //# sourceMappingURL=index.js.map

package/build/storage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAAxC,gHAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAAxC,gHAAA,cAAc,OAAA;AAiBvB,+GAK0E;AAJtE,sIAAA,yBAAyB,OAAA;AACzB,oIAAA,uBAAuB,OAAA;AACvB,4HAAA,eAAe,OAAA;AACf,mIAAA,sBAAsB,OAAA"}

package/build/types/blockchain/TransactionSubtypes/StorageProgramTransaction.d.ts

@@ -1,33 +1,87 @@
 import { Transaction, TransactionContent } from "../Transaction";
+/**
+ * Storage Program constants for validation and pricing
+ */
+export declare const STORAGE_PROGRAM_CONSTANTS: {
+    /** Maximum storage size in bytes (1MB) */
+    readonly MAX_SIZE_BYTES: 1048576;
+    /** Size chunk for pricing in bytes (10KB) */
+    readonly PRICING_CHUNK_BYTES: 10240;
+    /** Fee per chunk in DEM */
+    readonly FEE_PER_CHUNK: 1n;
+    /** Maximum nesting depth for JSON encoding */
+    readonly MAX_JSON_NESTING_DEPTH: 64;
+};
 /**
  * Storage Program operations
  *
  * - CREATE_STORAGE_PROGRAM: Initialize a new storage program with access control
- * - WRITE_STORAGE: Write/update key-value pairs in the storage
+ * - WRITE_STORAGE: Write/update data in the storage
  * - READ_STORAGE: Query operation (not a transaction, used for validation)
- * - UPDATE_ACCESS_CONTROL: Modify access control settings (deployer only)
- * - DELETE_STORAGE_PROGRAM: Remove the entire storage program (deployer only)
+ * - UPDATE_ACCESS_CONTROL: Modify access control settings (owner only)
+ * - DELETE_STORAGE_PROGRAM: Remove the entire storage program (owner/ACL permissioned)
  */
 export type StorageProgramOperation = "CREATE_STORAGE_PROGRAM" | "WRITE_STORAGE" | "READ_STORAGE" | "UPDATE_ACCESS_CONTROL" | "DELETE_STORAGE_PROGRAM";
 /**
- * Access control modes for Storage Programs
+ * Storage encoding format
+ * - json: Structured key-value data (Record<string, any>)
+ * - binary: Raw binary data (base64 encoded string)
+ */
+export type StorageEncoding = "json" | "binary";
+/**
+ * Storage location type
+ * - onchain: Stored directly in PostgreSQL (current implementation)
+ * - ipfs: Stored on IPFS with CID reference (future - not yet implemented)
+ */
+export type StorageLocation = "onchain" | "ipfs";
+/**
+ * Access control mode determining default behavior
+ * - owner: Only owner can read and write (most restrictive)
+ * - public: Anyone can read, only owner can write
+ * - restricted: Only addresses in allowed/groups can access
+ */
+export type StorageACLMode = "owner" | "public" | "restricted";
+/**
+ * Group permissions for access control
+ */
+export interface StorageGroupPermissions {
+    /** Member addresses in this group */
+    members: string[];
+    /** Permissions granted to group members */
+    permissions: ("read" | "write" | "delete")[];
+}
+/**
+ * Robust Access Control for Storage Programs
+ * Applies to both JSON and Binary encodings
  *
- * - private: Only deployer can read and write
- * - public: Anyone can read, only deployer can write
- * - restricted: Only addresses in allowedAddresses can read/write
- * - deployer-only: Only deployer has all permissions (same as private but explicit)
+ * ACL Resolution Priority:
+ * 1. Owner -> FULL ACCESS (always)
+ * 2. Blacklisted -> DENIED (even if in allowed/groups)
+ * 3. Allowed -> permissions granted
+ * 4. Groups -> check group permissions
+ * 5. Mode fallback:
+ *    - "owner" -> DENIED
+ *    - "public" -> READ only
+ *    - "restricted" -> DENIED
+ */
+export interface StorageProgramACL {
+    /** Access mode determining default behavior */
+    mode: StorageACLMode;
+    /** Addresses explicitly allowed to read/write */
+    allowed?: string[];
+    /** Addresses explicitly blocked (takes precedence over allowed/groups) */
+    blacklisted?: string[];
+    /** Named groups with member addresses and permissions */
+    groups?: Record<string, StorageGroupPermissions>;
+}
+/**
+ * @deprecated Use StorageProgramACL instead. Kept for backward compatibility.
  */
 export type StorageProgramAccessControl = "private" | "public" | "restricted" | "deployer-only";
 /**
  * Storage Program payload for transaction data
  *
- * @property operation - The storage operation to perform
- * @property storageAddress - The storage program address (stor-{hash})
- * @property programName - Name of the storage program (required for CREATE)
- * @property data - Key-value data to write (required for CREATE and WRITE)
- * @property accessControl - Access control mode (optional for CREATE, required for UPDATE_ACCESS_CONTROL)
- * @property allowedAddresses - List of allowed addresses for 'restricted' mode
- * @property salt - Random salt for address derivation (optional for CREATE)
+ * Unified payload supporting both JSON and Binary encodings with robust ACL.
  */
 export interface StorageProgramPayload {
     /** The storage operation to perform */
@@ -36,14 +90,45 @@ export interface StorageProgramPayload {
     storageAddress: string;
     /** Name of the storage program (required for CREATE_STORAGE_PROGRAM) */
     programName?: string;
-    /** Key-value data to write (for CREATE_STORAGE_PROGRAM and WRITE_STORAGE) */
-    data?: Record<string, any>;
-    /** Access control mode */
+    /**
+     * Encoding format for the data
+     * - json: data field contains Record<string, any>
+     * - binary: data field contains base64 string
+     * @default "json"
+     */
+    encoding?: StorageEncoding;
+    /**
+     * Data to store
+     * - For json encoding: Record<string, any> (max 64 nesting levels)
+     * - For binary encoding: base64 encoded string
+     * Max size: 1MB for both
+     */
+    data?: Record<string, any> | string;
+    /**
+     * Robust access control configuration (new)
+     * Supports owner, allowed, blacklisted, public, and groups
+     */
+    acl?: StorageProgramACL;
+    /**
+     * @deprecated Use acl instead. Kept for backward compatibility.
+     * Simple access control mode
+     */
     accessControl?: StorageProgramAccessControl;
-    /** Allowed addresses for 'restricted' access control */
+    /**
+     * @deprecated Use acl.allowed instead. Kept for backward compatibility.
+     * Allowed addresses for 'restricted' access control
+     */
     allowedAddresses?: string[];
     /** Random salt for deterministic address derivation (optional) */
     salt?: string;
+    /** Optional metadata (filename, mimeType, description, etc.) */
+    metadata?: Record<string, unknown>;
+    /**
+     * Storage location preference
+     * @default "onchain"
+     * Note: "ipfs" is not yet implemented, will fall back to "onchain"
+     */
+    storageLocation?: StorageLocation;
 }
 /**
  * Transaction content type for Storage Program operations.
@@ -55,16 +140,30 @@ export type StorageProgramTransactionContent = Omit<TransactionContent, "type" |
 };
 /**
  * Complete Storage Program transaction interface.
- * Used for structured key-value storage on the blockchain with access control.
+ * Used for unified storage on the blockchain with access control.
  *
  * Storage Programs support:
- * - Key-value storage (max 128KB per program)
- * - Access control (private, public, restricted, deployer-only)
- * - Deterministic address derivation
- * - Nested data structures (max 64 levels)
+ * - Dual encoding: JSON (structured) or Binary (raw)
+ * - Max size: 1MB for both encodings
+ * - Pricing: 1 DEM per 10KB
+ * - Robust ACL: owner, allowed, blacklisted, public, groups
+ * - Permanent storage, owner/ACL-deletable only
+ * - IPFS-ready (stubs for future hybrid storage)
  *
- * @see STORAGE_PROGRAMS_SPEC.md for complete specification
+ * @see feature_storage_programs_plan.md for complete specification
  */
 export interface StorageProgramTransaction extends Omit<Transaction, "content"> {
     content: StorageProgramTransactionContent;
 }
+/**
+ * Check if a payload is a StorageProgram payload
+ */
+export declare function isStorageProgramPayload(payload: unknown): payload is StorageProgramPayload;
+/**
+ * Check if encoding is valid
+ */
+export declare function isValidEncoding(encoding: unknown): encoding is StorageEncoding;
+/**
+ * Check if storage location is valid
+ */
+export declare function isValidStorageLocation(location: unknown): location is StorageLocation;

package/build/types/blockchain/TransactionSubtypes/StorageProgramTransaction.js

@@ -1,3 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORAGE_PROGRAM_CONSTANTS = void 0;
+exports.isStorageProgramPayload = isStorageProgramPayload;
+exports.isValidEncoding = isValidEncoding;
+exports.isValidStorageLocation = isValidStorageLocation;
+// REVIEW: Unified Storage Program transaction types for both JSON and Binary storage
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Storage Program constants for validation and pricing
+ */
+exports.STORAGE_PROGRAM_CONSTANTS = {
+    /** Maximum storage size in bytes (1MB) */
+    MAX_SIZE_BYTES: 1048576,
+    /** Size chunk for pricing in bytes (10KB) */
+    PRICING_CHUNK_BYTES: 10240,
+    /** Fee per chunk in DEM */
+    FEE_PER_CHUNK: 1n,
+    /** Maximum nesting depth for JSON encoding */
+    MAX_JSON_NESTING_DEPTH: 64,
+};
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Check if a payload is a StorageProgram payload
+ */
+function isStorageProgramPayload(payload) {
+    if (!payload || typeof payload !== "object")
+        return false;
+    const p = payload;
+    return (typeof p.operation === "string" &&
+        typeof p.storageAddress === "string" &&
+        ["CREATE_STORAGE_PROGRAM", "WRITE_STORAGE", "READ_STORAGE", "UPDATE_ACCESS_CONTROL", "DELETE_STORAGE_PROGRAM"].includes(p.operation));
+}
+/**
+ * Check if encoding is valid
+ */
+function isValidEncoding(encoding) {
+    return encoding === "json" || encoding === "binary";
+}
+/**
+ * Check if storage location is valid
+ */
+function isValidStorageLocation(location) {
+    return location === "onchain" || location === "ipfs";
+}
 //# sourceMappingURL=StorageProgramTransaction.js.map

package/build/types/blockchain/TransactionSubtypes/StorageProgramTransaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"StorageProgramTransaction.js","sourceRoot":"","sources":["../../../../../src/types/blockchain/TransactionSubtypes/StorageProgramTransaction.ts"],"names":[],"mappings":""}
+{"version":3,"file":"StorageProgramTransaction.js","sourceRoot":"","sources":["../../../../../src/types/blockchain/TransactionSubtypes/StorageProgramTransaction.ts"],"names":[],"mappings":";;;AAoOA,0DAQC;AAKD,0CAEC;AAKD,wDAEC;AAxPD,qFAAqF;AAErF,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;GAEG;AACU,QAAA,yBAAyB,GAAG;IACrC,0CAA0C;IAC1C,cAAc,EAAE,OAAO;IAEvB,6CAA6C;IAC7C,mBAAmB,EAAE,KAAK;IAE1B,2BAA2B;IAC3B,aAAa,EAAE,EAAE;IAEjB,8CAA8C;IAC9C,sBAAsB,EAAE,EAAE;CACpB,CAAA;AAsMV,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,SAAgB,uBAAuB,CAAC,OAAgB;IACpD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACzD,MAAM,CAAC,GAAG,OAAkC,CAAA;IAC5C,OAAO,CACH,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ;QACpC,CAAC,wBAAwB,EAAE,eAAe,EAAE,cAAc,EAAE,uBAAuB,EAAE,wBAAwB,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAmB,CAAC,CACjJ,CAAA;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,QAAiB;IAC7C,OAAO,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,QAAQ,CAAA;AACvD,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB,CAAC,QAAiB;IACpD,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,MAAM,CAAA;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kynesyslabs/demosdk",
-    "version": "2.8.10",
+    "version": "2.8.11",
     "description": "Demosdk is a JavaScript/TypeScript SDK that provides a unified interface for interacting with Demos network",
     "main": "build/index.js",
     "types": "build/index.d.ts",