@kynesyslabs/demosdk 2.8.10 → 2.8.13

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;
 }