@opendatalabs/vana-sdk 0.1.0-alpha.eebb656 → 0.1.0-alpha.ef15099

package/dist/core.d.ts

@@ -1,11 +1,17 @@
 import type { VanaConfig, VanaConfigWithStorage, RuntimeConfig, StorageRequiredMarker } from "./types";
+import type { UnifiedRelayerResponse } from "./types/relayer";
 import { PermissionsController } from "./controllers/permissions";
+import { RuntimePermissionsController } from "./controllers/runtimePermissions";
+import { AccessSettlementController } from "./controllers/accessSettlement";
 import { DataController } from "./controllers/data";
 import { SchemaController } from "./controllers/schemas";
 import { ServerController } from "./controllers/server";
 import { ProtocolController } from "./controllers/protocol";
-import type { Address, Hash, TransactionReceipt } from "viem";
+import { OperationsController } from "./controllers/operations";
+import type { PublicClient, Address, Hash, TransactionReceipt } from "viem";
 import type { Operation, PollingOptions, TransactionResult, TransactionWaitOptions } from "./types/operations";
+import type { IOperationStore, IRelayerStateStore } from "./types/operationStore";
+import type { IAtomicStore } from "./types/atomicStore";
 import type { Contract, Fn, TypedTransactionResult } from "./generated/event-types";
 import type { VanaPlatformAdapter } from "./platform/interface";
 /**
@@ -96,24 +102,33 @@ export declare class VanaCoreFactory {
 export declare class VanaCore {
     /** Manages gasless data access permissions and trusted server registry. */
     readonly permissions: PermissionsController;
+    /** Manages runtime permissions for dataset monetization via Vana Runtime. */
+    readonly runtimePermissions: RuntimePermissionsController;
+    /** Manages payment settlement for runtime operations. */
+    readonly accessSettlement: AccessSettlementController;
     /** Handles user data file operations. */
     readonly data: DataController;
     /** Manages data schemas and refiners. */
     readonly schemas: SchemaController;
+    /** Manages asynchronous operation recovery and status checking. */
+    readonly operations: OperationsController;
     /** Provides personal server setup and trusted server interactions. */
     readonly server: ServerController;
     /** Offers low-level access to Vana protocol smart contracts. */
     readonly protocol: ProtocolController;
     /** Handles environment-specific operations like encryption and file systems. */
     protected platform: VanaPlatformAdapter;
-    private readonly relayerCallbacks?;
+    private readonly relayerConfig?;
+    private readonly relayerCallback?;
     private readonly downloadRelayer?;
     private readonly storageManager?;
     private readonly hasRequiredStorage;
     private readonly ipfsGateways?;
-    private readonly defaultPersonalServerUrl?;
-    private readonly publicClient;
-    private readonly walletClient;
+    readonly publicClient: PublicClient;
+    private readonly walletClient?;
+    private readonly _staticUserAddress?;
+    protected readonly operationStore?: IOperationStore | IRelayerStateStore;
+    protected readonly atomicStore?: IAtomicStore;
     /**
      * Initializes a new VanaCore client instance with the provided configuration.
      *
@@ -211,16 +226,17 @@ export declare class VanaCore {
      */
     get chainName(): string;
     /**
-     * Retrieves the user's wallet address from the connected client.
+     * The user's wallet address.
+     * In wallet mode, this always returns the current wallet account address.
+     * In read-only mode, this returns the static address provided during initialization.
      *
-     * @returns A Promise that resolves to the user's Ethereum address
      * @example
      * ```typescript
-     * const address = await vana.getUserAddress();
+     * const address = vana.userAddress;
      * console.log(`User address: ${address}`); // e.g., "User address: 0x742d35..."
      * ```
      */
-    getUserAddress(): Promise<Address>;
+    get userAddress(): Address;
     /**
      * Retrieves comprehensive runtime configuration information.
      *
@@ -377,7 +393,7 @@ export declare class VanaCore {
      * });
      * ```
      */
-    waitForOperation<T = unknown>(opOrId: Operation<T> | string, options?: PollingOptions): Promise<Operation<T>>;
+    waitForOperation(opOrId: Operation | string, options?: PollingOptions): Promise<Operation>;
     /**
      * Waits for a transaction to be confirmed and returns the receipt.
      *
@@ -437,4 +453,47 @@ export declare class VanaCore {
      * @see For understanding transaction flows, visit https://docs.vana.org/docs/transactions
      */
     waitForTransactionEvents<C extends Contract, F extends Fn<C>>(transaction: TransactionResult<C, F>, options?: TransactionWaitOptions): Promise<TypedTransactionResult<C, F>>;
+    /**
+     * Enhances a unified relayer response with client-side behavior.
+     *
+     * @remarks
+     * This method wraps a relayer response in an enhanced object that provides
+     * a fluent `.wait()` method for handling asynchronous operations. The enhanced
+     * response intelligently handles both submitted transactions (via hash) and
+     * pending operations (via operationId).
+     *
+     * @param response - The unified relayer response to enhance
+     * @returns EnhancedTransactionResponse if the response can be enhanced, null otherwise
+     *
+     * @example
+     * ```typescript
+     * // Enhance a relayer response for fluent waiting
+     * const response = await handleRelayerOperation(vana, request);
+     * const enhanced = vana.enhanceRelayerResponse(response);
+     * if (enhanced) {
+     *   const result = await enhanced.wait();
+     *   if (result.expectedEvents?.FileAdded) {
+     *     console.log('File ID:', result.expectedEvents.FileAdded.fileId);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With status updates for pending operations
+     * const enhanced = vana.enhanceRelayerResponse(response);
+     * if (enhanced) {
+     *   const result = await enhanced.wait({
+     *     onStatusUpdate: (status) => {
+     *       console.log('Operation status:', status.type);
+     *     },
+     *     timeout: 60000 // 1 minute timeout
+     *   });
+     * }
+     * ```
+     *
+     * @category Relayer
+     * @since 0.2.0
+     */
+    enhanceRelayerResponse(response: UnifiedRelayerResponse): Promise<any>;
 }

package/dist/core.js

@@ -1,19 +1,25 @@
 import {
   isWalletConfig,
   isChainConfig,
+  isReadOnlyConfig,
+  isAddressOnlyConfig,
   isVanaChainId,
   hasStorageConfig
 } from "./types";
 import { InvalidConfigurationError } from "./errors";
 import { PermissionsController } from "./controllers/permissions";
+import { RuntimePermissionsController } from "./controllers/runtimePermissions";
+import { AccessSettlementController } from "./controllers/accessSettlement";
 import { DataController } from "./controllers/data";
 import { SchemaController } from "./controllers/schemas";
 import { ServerController } from "./controllers/server";
 import { ProtocolController } from "./controllers/protocol";
+import { OperationsController } from "./controllers/operations";
 import { StorageManager } from "./storage";
 import { createWalletClient, createPublicClient, http } from "viem";
+import { extractAddress } from "./utils/wallet";
 import { chains } from "./config/chains";
-import { getChainConfig } from "./chains";
+import { getChainConfig, vanaMainnet } from "./chains";
 import {
   encryptBlobWithSignedKey,
   decryptBlobWithSignedKey
@@ -62,24 +68,34 @@ class VanaCoreFactory {
 class VanaCore {
   /** Manages gasless data access permissions and trusted server registry. */
   permissions;
+  /** Manages runtime permissions for dataset monetization via Vana Runtime. */
+  runtimePermissions;
+  /** Manages payment settlement for runtime operations. */
+  accessSettlement;
   /** Handles user data file operations. */
   data;
   /** Manages data schemas and refiners. */
   schemas;
+  /** Manages asynchronous operation recovery and status checking. */
+  operations;
   /** Provides personal server setup and trusted server interactions. */
   server;
   /** Offers low-level access to Vana protocol smart contracts. */
   protocol;
   /** Handles environment-specific operations like encryption and file systems. */
   platform;
-  relayerCallbacks;
+  relayerConfig;
+  relayerCallback;
   downloadRelayer;
   storageManager;
   hasRequiredStorage;
   ipfsGateways;
-  defaultPersonalServerUrl;
   publicClient;
   walletClient;
+  _staticUserAddress;
+  // For read-only mode
+  operationStore;
+  atomicStore;
   /**
    * Initializes a new VanaCore client instance with the provided configuration.
    *
@@ -104,10 +120,33 @@ class VanaCore {
   constructor(platform, config) {
     this.platform = platform;
     this.validateConfig(config);
-    this.relayerCallbacks = config.relayerCallbacks;
+    this.operationStore = config?.operationStore;
+    this.relayerConfig = config.relayer;
+    if (config.relayer) {
+      if (typeof config.relayer !== "string" && typeof config.relayer !== "function") {
+        throw new InvalidConfigurationError(
+          "Relayer must be either a URL string or a callback function"
+        );
+      }
+      if (typeof config.relayer === "string") {
+        const url = config.relayer;
+        this.relayerCallback = async (request) => {
+          const response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(request)
+          });
+          if (!response.ok) {
+            throw new Error(`Relayer request failed: ${response.statusText}`);
+          }
+          return response.json();
+        };
+      } else {
+        this.relayerCallback = config.relayer;
+      }
+    }
     this.downloadRelayer = config.downloadRelayer;
     this.ipfsGateways = config.ipfsGateways;
-    this.defaultPersonalServerUrl = config.defaultPersonalServerUrl;
     this.hasRequiredStorage = hasStorageConfig(config);
     if (config.storage?.providers) {
       this.storageManager = new StorageManager();
@@ -121,8 +160,34 @@ class VanaCore {
       }
     }
     let walletClient;
+    let publicClient;
+    let staticUserAddress;
+    let chainToUse;
     if (isWalletConfig(config)) {
       walletClient = config.walletClient;
+      chainToUse = walletClient.chain ?? vanaMainnet;
+      staticUserAddress = void 0;
+      if ("publicClient" in config && config.publicClient) {
+        publicClient = config.publicClient;
+      } else {
+        publicClient = createPublicClient({
+          chain: chainToUse,
+          transport: http()
+        });
+      }
+    } else if (isReadOnlyConfig(config)) {
+      walletClient = void 0;
+      publicClient = config.publicClient;
+      staticUserAddress = config.address;
+      chainToUse = config.publicClient.chain ?? vanaMainnet;
+    } else if (isAddressOnlyConfig(config)) {
+      walletClient = void 0;
+      staticUserAddress = config.address;
+      chainToUse = config.chain ?? vanaMainnet;
+      publicClient = createPublicClient({
+        chain: chainToUse,
+        transport: http()
+      });
     } else if (isChainConfig(config)) {
       if (!config.account) {
         throw new InvalidConfigurationError(
@@ -135,30 +200,38 @@ class VanaCore {
           `Unsupported chain ID: ${config.chainId}`
         );
       }
+      chainToUse = chain;
       walletClient = createWalletClient({
         chain,
         transport: http(config.rpcUrl ?? chain.rpcUrls.default.http[0]),
         account: config.account
       });
+      staticUserAddress = void 0;
+      publicClient = createPublicClient({
+        chain,
+        transport: http()
+      });
     } else {
       throw new InvalidConfigurationError(
-        "Invalid configuration: must be either WalletConfig or ChainConfig"
+        "Invalid configuration: must provide either walletClient, publicClient + address, or address alone"
       );
     }
-    const publicClient = createPublicClient({
-      chain: walletClient.chain,
-      transport: http()
-    });
     this.publicClient = publicClient;
     this.walletClient = walletClient;
-    const chainConfig = getChainConfig(walletClient.chain.id);
+    this._staticUserAddress = staticUserAddress;
+    const chainConfig = getChainConfig(chainToUse.id);
     const subgraphUrl = config.subgraphUrl ?? chainConfig?.subgraphUrl;
+    const personalServerUrl = config.defaultPersonalServerUrl ?? chainConfig?.personalServerUrl;
+    const self = this;
     const sharedContext = {
       walletClient,
       publicClient,
+      get userAddress() {
+        return self.userAddress;
+      },
       applicationClient: walletClient,
       // Using same wallet for now
-      relayerCallbacks: this.relayerCallbacks,
+      relayer: this.relayerCallback,
       downloadRelayer: this.downloadRelayer,
       storageManager: this.storageManager,
       subgraphUrl,
@@ -167,13 +240,17 @@ class VanaCore {
       validateStorageRequired: this.validateStorageRequired.bind(this),
       hasStorage: this.hasStorage.bind(this),
       ipfsGateways: this.ipfsGateways,
-      defaultPersonalServerUrl: this.defaultPersonalServerUrl,
+      defaultPersonalServerUrl: personalServerUrl,
       waitForTransactionEvents: this.waitForTransactionEvents.bind(this),
-      waitForOperation: this.waitForOperation.bind(this)
+      waitForOperation: this.waitForOperation.bind(this),
+      operationStore: this.operationStore
     };
     this.permissions = new PermissionsController(sharedContext);
+    this.runtimePermissions = new RuntimePermissionsController(sharedContext);
+    this.accessSettlement = new AccessSettlementController(sharedContext);
     this.data = new DataController(sharedContext);
     this.schemas = new SchemaController(sharedContext);
+    this.operations = new OperationsController(sharedContext);
     this.server = new ServerController(sharedContext);
     this.protocol = new ProtocolController(sharedContext);
   }
@@ -193,7 +270,7 @@ class VanaCore {
   validateStorageRequired() {
     if (!this.hasRequiredStorage) {
       throw new InvalidConfigurationError(
-        "Storage configuration is required for this operation. Please configure storage providers in VanaConfig.storage, provide a relayerCallbacks.storeGrantFile implementation, or pass pre-stored URLs to avoid this dependency. \n\nFor better type safety, consider using VanaCoreFactory.createWithStorage() with VanaConfigWithStorage to catch this error at compile time."
+        "Storage configuration is required for this operation. Please configure storage providers in VanaConfig.storage, provide a relayer configuration, or pass pre-stored URLs to avoid this dependency. \n\nFor better type safety, consider using VanaCoreFactory.createWithStorage() with VanaConfigWithStorage to catch this error at compile time."
       );
     }
   }
@@ -242,13 +319,6 @@ class VanaCore {
     if (!config) {
       throw new InvalidConfigurationError("Configuration object is required");
     }
-    if (config.relayerCallbacks !== void 0) {
-      if (typeof config.relayerCallbacks !== "object") {
-        throw new InvalidConfigurationError(
-          "relayerCallbacks must be an object"
-        );
-      }
-    }
     if (config.storage?.providers) {
       if (typeof config.storage.providers !== "object") {
         throw new InvalidConfigurationError(
@@ -315,9 +385,26 @@ class VanaCore {
           );
         }
       }
+    } else if (isReadOnlyConfig(config)) {
+      if (!config.publicClient) {
+        throw new InvalidConfigurationError(
+          "publicClient is required for read-only configuration"
+        );
+      }
+      if (!config.address) {
+        throw new InvalidConfigurationError(
+          "address is required for read-only configuration"
+        );
+      }
+    } else if (isAddressOnlyConfig(config)) {
+      if (!config.address) {
+        throw new InvalidConfigurationError(
+          "address is required for address-only configuration"
+        );
+      }
     } else {
       throw new InvalidConfigurationError(
-        "Configuration must be either WalletConfig or ChainConfig"
+        "Invalid configuration: must provide either walletClient, publicClient + address, or address alone"
       );
     }
   }
@@ -348,27 +435,24 @@ class VanaCore {
     return this.protocol.getChainName();
   }
   /**
-   * Retrieves the user's wallet address from the connected client.
+   * The user's wallet address.
+   * In wallet mode, this always returns the current wallet account address.
+   * In read-only mode, this returns the static address provided during initialization.
    *
-   * @returns A Promise that resolves to the user's Ethereum address
    * @example
    * ```typescript
-   * const address = await vana.getUserAddress();
+   * const address = vana.userAddress;
    * console.log(`User address: ${address}`); // e.g., "User address: 0x742d35..."
    * ```
    */
-  async getUserAddress() {
-    if (!this.walletClient.account) {
-      throw new Error("No wallet account connected");
-    }
-    const { account } = this.walletClient;
-    if (typeof account === "string") {
-      return account;
+  get userAddress() {
+    if (this.walletClient?.account) {
+      return extractAddress(this.walletClient.account);
     }
-    if (typeof account === "object" && account.address) {
-      return account.address;
+    if (this._staticUserAddress) {
+      return this._staticUserAddress;
     }
-    throw new Error("Unable to determine wallet address");
+    throw new Error("No user address available");
   }
   /**
    * Retrieves comprehensive runtime configuration information.
@@ -385,7 +469,7 @@ class VanaCore {
     return {
       chainId: this.chainId,
       chainName: this.chainName,
-      relayerCallbacks: this.relayerCallbacks,
+      relayerConfig: this.relayerConfig,
       storageProviders: this.storageManager?.getStorageProviders() ?? [],
       defaultStorageProvider: this.storageManager?.getDefaultStorageProvider()
     };
@@ -622,6 +706,52 @@ class VanaCore {
     const result = parseTransaction(transaction, receipt);
     return result;
   }
+  /**
+   * Enhances a unified relayer response with client-side behavior.
+   *
+   * @remarks
+   * This method wraps a relayer response in an enhanced object that provides
+   * a fluent `.wait()` method for handling asynchronous operations. The enhanced
+   * response intelligently handles both submitted transactions (via hash) and
+   * pending operations (via operationId).
+   *
+   * @param response - The unified relayer response to enhance
+   * @returns EnhancedTransactionResponse if the response can be enhanced, null otherwise
+   *
+   * @example
+   * ```typescript
+   * // Enhance a relayer response for fluent waiting
+   * const response = await handleRelayerOperation(vana, request);
+   * const enhanced = vana.enhanceRelayerResponse(response);
+   * if (enhanced) {
+   *   const result = await enhanced.wait();
+   *   if (result.expectedEvents?.FileAdded) {
+   *     console.log('File ID:', result.expectedEvents.FileAdded.fileId);
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // With status updates for pending operations
+   * const enhanced = vana.enhanceRelayerResponse(response);
+   * if (enhanced) {
+   *   const result = await enhanced.wait({
+   *     onStatusUpdate: (status) => {
+   *       console.log('Operation status:', status.type);
+   *     },
+   *     timeout: 60000 // 1 minute timeout
+   *   });
+   * }
+   * ```
+   *
+   * @category Relayer
+   * @since 0.2.0
+   */
+  async enhanceRelayerResponse(response) {
+    const { enhanceResponse } = await import("./client/enhancedResponse");
+    return enhanceResponse(response, this);
+  }
 }
 export {
   VanaCore,