@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dba79a3

package/dist/core.d.ts

@@ -1,45 +1,20 @@
-import { Operation, PollingOptions, TransactionResult, TransactionWaitOptions } from './types/operations.js';
-import * as viem from 'viem';
-import { VanaConfigWithStorage, VanaConfig, StorageRequiredMarker, RuntimeConfig } from './types/config.js';
-import { SchemaController } from './controllers/schemas.js';
-import { P as PermissionsController } from './permissions-eo8YeLGf.js';
-import { DataController } from './controllers/data.js';
-import { ServerController } from './controllers/server.js';
-import { ProtocolController } from './controllers/protocol.js';
-import { VanaPlatformAdapter } from './platform/interface.js';
-import './generated/server/server-exports.js';
-import './generated/server/server.js';
-import './types/chains.js';
-import './types/storage.js';
-import './types/permissions.js';
-import './types/data.js';
-import './config/eventMappings.js';
-import './generated/abi/index.js';
-import './generated/abi/DataPortabilityPermissionsImplementation.js';
-import './generated/abi/DataPortabilityServersImplementation.js';
-import './generated/abi/DataPortabilityGranteesImplementation.js';
-import './generated/abi/VanaEpochImplementation.js';
-import './generated/abi/DLPRegistryImplementation.js';
-import './generated/abi/DLPTreasuryImplementation.js';
-import './generated/abi/DLPRewardDeployerTreasuryImplementation.js';
-import './generated/abi/DLPPerformanceImplementation.js';
-import './generated/abi/DLPRewardDeployerImplementation.js';
-import './generated/abi/DLPRootImplementation.js';
-import './generated/abi/DataLiquidityPoolImplementation.js';
-import './generated/abi/DLPRegistryTreasuryImplementation.js';
-import './storage/manager.js';
-import './utils/schemaValidation.js';
-import './types/personal.js';
-import './types/contracts.js';
-import './contracts/contractController.js';
-import 'abitype';
-import './core/client.js';
-import './config/chains.js';
-
+import type { VanaConfig, VanaConfigWithStorage, RuntimeConfig, StorageRequiredMarker } from "./types";
+import { PermissionsController } from "./controllers/permissions";
+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 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";
 /**
  * Factory functions for creating VanaCore instances with proper type safety
  */
-declare class VanaCoreFactory {
+export declare class VanaCoreFactory {
     /**
      * Creates a VanaCore instance that enforces storage requirements at compile time.
      * Use this factory when you know you'll need storage-dependent operations.
@@ -121,27 +96,32 @@ declare class VanaCoreFactory {
  * ```
  * @category Core SDK
  */
-declare class VanaCore {
+export declare class VanaCore {
     /** Manages gasless data access permissions and trusted server registry. */
     readonly permissions: PermissionsController;
     /** 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.
      *
@@ -239,16 +219,17 @@ 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<viem.Address>;
+    get userAddress(): Address;
     /**
      * Retrieves comprehensive runtime configuration information.
      *
@@ -434,33 +415,35 @@ declare class VanaCore {
      * ```
      */
     waitForTransactionReceipt(hashOrObj: TransactionResult | {
-        hash: viem.Hash;
-    } | viem.Hash, options?: TransactionWaitOptions): Promise<viem.TransactionReceipt>;
+        hash: Hash;
+    } | Hash, options?: TransactionWaitOptions): Promise<TransactionReceipt>;
     /**
-     * Waits for transaction confirmation and parses events.
+     * Waits for transaction confirmation and extracts blockchain event data.
      *
      * @remarks
-     * This method waits for a transaction to be confirmed and then
-     * parses the logs to extract typed event data. The specific event
-     * type depends on the transaction operation.
+     * This method leverages the context-carrying POJO architecture. When passed a
+     * `TransactionResult` with an `operation` field, it automatically parses the
+     * correct events from the transaction logs. For legacy compatibility, it accepts
+     * raw hashes but will not parse events without operation context.
+     *
+     * @param transaction - Transaction result with operation context
+     * @param options - Optional confirmation and timeout settings
+     * @returns Parsed event data specific to the transaction's operation type
+     * @throws {NetworkError} When transaction confirmation times out
+     * @throws {BlockchainError} When expected events are not found in the transaction
      *
-     * @param hashOrObj - Either a TransactionResult object or hash string
-     * @param options - Optional wait configuration
-     * @returns The parsed event data from the transaction
      * @example
      * ```typescript
-     * // Wait for permission grant events
-     * const tx = await vana.permissions.grant(params);
-     * const events = await vana.waitForTransactionEvents(tx);
+     * // Recommended: Pass the transaction result for automatic event parsing
+     * const tx = await vana.permissions.submitAddServerFilesAndPermissions(params);
+     * const events = await vana.waitForTransactionEvents<{ permissionId: bigint }>(tx);
      * console.log(`Permission ID: ${events.permissionId}`);
      *
-     * // Using just the hash
-     * const events = await vana.waitForTransactionEvents("0x123...");
+     * // Legacy: Raw hash without event parsing (returns receipt)
+     * const receipt = await vana.waitForTransactionEvents("0x123...");
      * ```
+     *
+     * @see For understanding transaction flows, visit https://docs.vana.org/docs/transactions
      */
-    waitForTransactionEvents<T = unknown>(hashOrObj: TransactionResult | {
-        hash: viem.Hash;
-    } | viem.Hash, options?: TransactionWaitOptions): Promise<T>;
+    waitForTransactionEvents<C extends Contract, F extends Fn<C>>(transaction: TransactionResult<C, F>, options?: TransactionWaitOptions): Promise<TypedTransactionResult<C, F>>;
 }
-
-export { VanaCore, VanaCoreFactory };

package/dist/core.js

@@ -1,24 +1,23 @@
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 import {
   isWalletConfig,
   isChainConfig,
+  isReadOnlyConfig,
+  isAddressOnlyConfig,
   isVanaChainId,
   hasStorageConfig
 } from "./types";
 import { InvalidConfigurationError } from "./errors";
-import {
-  PermissionsController
-} from "./controllers/permissions";
+import { PermissionsController } from "./controllers/permissions";
 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
@@ -65,6 +64,32 @@ class VanaCoreFactory {
   }
 }
 class VanaCore {
+  /** Manages gasless data access permissions and trusted server registry. */
+  permissions;
+  /** 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;
+  relayerConfig;
+  relayerCallback;
+  downloadRelayer;
+  storageManager;
+  hasRequiredStorage;
+  ipfsGateways;
+  publicClient;
+  walletClient;
+  _staticUserAddress;
+  // For read-only mode
+  operationStore;
+  atomicStore;
   /**
    * Initializes a new VanaCore client instance with the provided configuration.
    *
@@ -87,42 +112,41 @@ class VanaCore {
    * ```
    */
   constructor(platform, config) {
-    /** Manages gasless data access permissions and trusted server registry. */
-    __publicField(this, "permissions");
-    /** Handles user data file operations. */
-    __publicField(this, "data");
-    /** Manages data schemas and refiners. */
-    __publicField(this, "schemas");
-    /** Provides personal server setup and trusted server interactions. */
-    __publicField(this, "server");
-    /** Offers low-level access to Vana protocol smart contracts. */
-    __publicField(this, "protocol");
-    /** Handles environment-specific operations like encryption and file systems. */
-    __publicField(this, "platform");
-    __publicField(this, "relayerCallbacks");
-    __publicField(this, "downloadRelayer");
-    __publicField(this, "storageManager");
-    __publicField(this, "hasRequiredStorage");
-    __publicField(this, "ipfsGateways");
-    __publicField(this, "defaultPersonalServerUrl");
-    __publicField(this, "publicClient");
-    __publicField(this, "walletClient");
     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();
       for (const [name, provider] of Object.entries(config.storage.providers)) {
         const isDefault = name === config.storage.defaultProvider;
-        this.storageManager.register(
-          name,
-          provider,
-          isDefault
-        );
+        this.storageManager.register(name, provider, isDefault);
       }
       if (!config.storage.defaultProvider && Object.keys(config.storage.providers).length > 0) {
         const firstProviderName = Object.keys(config.storage.providers)[0];
@@ -130,8 +154,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(
@@ -144,30 +194,38 @@ class VanaCore {
           `Unsupported chain ID: ${config.chainId}`
         );
       }
+      chainToUse = chain;
       walletClient = createWalletClient({
         chain,
-        transport: http(config.rpcUrl || chain.rpcUrls.default.http[0]),
+        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);
-    const subgraphUrl = config.subgraphUrl || chainConfig?.subgraphUrl;
+    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,
@@ -176,13 +234,15 @@ 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.data = new DataController(sharedContext);
     this.schemas = new SchemaController(sharedContext);
+    this.operations = new OperationsController(sharedContext);
     this.server = new ServerController(sharedContext);
     this.protocol = new ProtocolController(sharedContext);
   }
@@ -202,7 +262,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."
       );
     }
   }
@@ -251,13 +311,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(
@@ -295,13 +348,13 @@ class VanaCore {
       }
       if (!isVanaChainId(config.walletClient.chain.id)) {
         throw new InvalidConfigurationError(
-          `Unsupported chain ID: ${config.walletClient.chain.id}. Supported chains: 14800 (Moksha testnet), 1480 (Vana mainnet)`
+          `Unsupported chain ID: ${String(config.walletClient.chain.id)}. Supported chains: 14800 (Moksha testnet), 1480 (Vana mainnet)`
         );
       }
     } else if (isChainConfig(config)) {
       if (!isVanaChainId(config.chainId)) {
         throw new InvalidConfigurationError(
-          `Unsupported chain ID: ${config.chainId}. Supported chains: 14800 (Moksha testnet), 1480 (Vana mainnet)`
+          `Unsupported chain ID: ${String(config.chainId)}. Supported chains: 14800 (Moksha testnet), 1480 (Vana mainnet)`
         );
       }
       if (config.rpcUrl) {
@@ -324,9 +377,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"
       );
     }
   }
@@ -357,27 +427,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");
+  get userAddress() {
+    if (this.walletClient?.account) {
+      return extractAddress(this.walletClient.account);
     }
-    const account = this.walletClient.account;
-    if (typeof account === "string") {
-      return account;
+    if (this._staticUserAddress) {
+      return this._staticUserAddress;
     }
-    if (typeof account === "object" && account.address) {
-      return account.address;
-    }
-    throw new Error("Unable to determine wallet address");
+    throw new Error("No user address available");
   }
   /**
    * Retrieves comprehensive runtime configuration information.
@@ -394,8 +461,8 @@ class VanaCore {
     return {
       chainId: this.chainId,
       chainName: this.chainName,
-      relayerCallbacks: this.relayerCallbacks,
-      storageProviders: this.storageManager?.getStorageProviders() || [],
+      relayerConfig: this.relayerConfig,
+      storageProviders: this.storageManager?.getStorageProviders() ?? [],
       defaultStorageProvider: this.storageManager?.getDefaultStorageProvider()
     };
   }
@@ -595,30 +662,41 @@ class VanaCore {
     });
   }
   /**
-   * Waits for transaction confirmation and parses events.
+   * Waits for transaction confirmation and extracts blockchain event data.
    *
    * @remarks
-   * This method waits for a transaction to be confirmed and then
-   * parses the logs to extract typed event data. The specific event
-   * type depends on the transaction operation.
+   * This method leverages the context-carrying POJO architecture. When passed a
+   * `TransactionResult` with an `operation` field, it automatically parses the
+   * correct events from the transaction logs. For legacy compatibility, it accepts
+   * raw hashes but will not parse events without operation context.
+   *
+   * @param transaction - Transaction result with operation context
+   * @param options - Optional confirmation and timeout settings
+   * @returns Parsed event data specific to the transaction's operation type
+   * @throws {NetworkError} When transaction confirmation times out
+   * @throws {BlockchainError} When expected events are not found in the transaction
    *
-   * @param hashOrObj - Either a TransactionResult object or hash string
-   * @param options - Optional wait configuration
-   * @returns The parsed event data from the transaction
    * @example
    * ```typescript
-   * // Wait for permission grant events
-   * const tx = await vana.permissions.grant(params);
-   * const events = await vana.waitForTransactionEvents(tx);
+   * // Recommended: Pass the transaction result for automatic event parsing
+   * const tx = await vana.permissions.submitAddServerFilesAndPermissions(params);
+   * const events = await vana.waitForTransactionEvents<{ permissionId: bigint }>(tx);
    * console.log(`Permission ID: ${events.permissionId}`);
    *
-   * // Using just the hash
-   * const events = await vana.waitForTransactionEvents("0x123...");
+   * // Legacy: Raw hash without event parsing (returns receipt)
+   * const receipt = await vana.waitForTransactionEvents("0x123...");
    * ```
+   *
+   * @see For understanding transaction flows, visit https://docs.vana.org/docs/transactions
    */
-  async waitForTransactionEvents(hashOrObj, options) {
-    const receipt = await this.waitForTransactionReceipt(hashOrObj, options);
-    return receipt;
+  async waitForTransactionEvents(transaction, options) {
+    const { parseTransaction } = await import("./utils/parseTransactionPojo");
+    const receipt = await this.waitForTransactionReceipt(
+      transaction.hash,
+      options
+    );
+    const result = parseTransaction(transaction, receipt);
+    return result;
   }
 }
 export {