@opendatalabs/vana-sdk 0.1.0-alpha.9b6ddbc → 0.1.0-alpha.9bbda27

package/dist/controllers/dataset.cjs

@@ -0,0 +1,357 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var dataset_exports = {};
+__export(dataset_exports, {
+  DatasetController: () => DatasetController
+});
+module.exports = __toCommonJS(dataset_exports);
+var import_viem = require("viem");
+var import_base = require("./base");
+var import_addresses = require("../generated/addresses");
+var import_abi = require("../generated/abi");
+var import_transactionHelpers = require("../utils/transactionHelpers");
+var import_errors = require("../errors");
+var import_multicall = require("../utils/multicall");
+class DatasetController extends import_base.BaseController {
+  /**
+   * Create a new dataset on the Vana network.
+   *
+   * @remarks
+   * Creates a dataset with the caller as the owner. The dataset will
+   * use the specified schema for file validation. Files can be added
+   * through the contribute workflow and must be accepted by the owner.
+   *
+   * @param schemaId - Schema ID defining file structure and validation
+   * @param options - Optional transaction parameters (gas, nonce, etc.)
+   * @returns Transaction result with DatasetCreated event
+   * @throws {ReadOnlyError} When no wallet is configured
+   * @throws {BlockchainError} When dataset creation fails
+   *
+   * @example
+   * ```typescript
+   * const tx = await vana.dataset.createDataset(42);
+   * const events = await vana.waitForTransactionEvents(tx);
+   * console.log(`Dataset ${events.datasetId} created`);
+   * ```
+   */
+  async createDataset(schemaId, options) {
+    this.assertWallet();
+    try {
+      const chainId = await this.context.publicClient.getChainId();
+      const address = (0, import_addresses.getContractAddress)(chainId, "DatasetRegistry");
+      const abi = (0, import_abi.getAbi)("DatasetRegistry");
+      const account = this.context.walletClient.account ?? this.context.userAddress;
+      if (!account) {
+        throw new Error("No account found");
+      }
+      const accountAddress = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address,
+        abi,
+        functionName: "createDataset",
+        args: [accountAddress, BigInt(schemaId)],
+        account,
+        chain: this.context.walletClient.chain,
+        ...this.spreadTransactionOptions(options)
+      });
+      return (0, import_transactionHelpers.tx)({
+        hash,
+        from: accountAddress,
+        contract: "DatasetRegistry",
+        fn: "createDataset"
+      });
+    } catch (error) {
+      throw new import_errors.BlockchainError(
+        `Failed to create dataset: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+  /**
+   * Accept a pending file into the dataset.
+   *
+   * @remarks
+   * Validates and accepts a contributor's file submission. Only the
+   * dataset owner can accept files. Once accepted, the file becomes
+   * part of the dataset and can be used in operations.
+   *
+   * @param datasetId - Dataset ID to accept the file into
+   * @param fileId - File ID to accept from pending queue
+   * @param options - Optional transaction parameters
+   * @returns Transaction result with FileAccepted event
+   * @throws {ReadOnlyError} When no wallet is configured
+   * @throws {BlockchainError} When file acceptance fails
+   *
+   * @example
+   * ```typescript
+   * const tx = await vana.dataset.acceptFile(1, 42);
+   * await vana.publicClient.waitForTransactionReceipt({ hash: tx.hash });
+   * console.log(`File ${fileId} accepted into dataset ${datasetId}`);
+   * ```
+   */
+  async acceptFile(datasetId, fileId, options) {
+    this.assertWallet();
+    try {
+      const chainId = await this.context.publicClient.getChainId();
+      const address = (0, import_addresses.getContractAddress)(chainId, "DatasetRegistry");
+      const abi = (0, import_abi.getAbi)("DatasetRegistry");
+      const account = this.context.walletClient.account ?? this.context.userAddress;
+      if (!account) {
+        throw new Error("No account found");
+      }
+      const accountAddress = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address,
+        abi,
+        functionName: "acceptFile",
+        args: [BigInt(datasetId), BigInt(fileId)],
+        account,
+        chain: this.context.walletClient.chain,
+        ...this.spreadTransactionOptions(options)
+      });
+      return (0, import_transactionHelpers.tx)({
+        hash,
+        from: accountAddress,
+        contract: "DatasetRegistry",
+        fn: "acceptFile"
+      });
+    } catch (error) {
+      throw new import_errors.BlockchainError(
+        `Failed to accept file: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+  /**
+   * Reject a pending file submission.
+   *
+   * @remarks
+   * Removes a file from the pending queue without accepting it.
+   * Only the dataset owner can reject files. The file remains in
+   * the DataRegistry but is not part of this dataset.
+   *
+   * @param datasetId - Dataset ID to reject the file from
+   * @param fileId - File ID to reject from pending queue
+   * @param options - Optional transaction parameters
+   * @returns Transaction result with FileRejected event
+   * @throws {ReadOnlyError} When no wallet is configured
+   * @throws {BlockchainError} When file rejection fails
+   *
+   * @example
+   * ```typescript
+   * const tx = await vana.dataset.rejectFile(1, 42);
+   * await vana.publicClient.waitForTransactionReceipt({ hash: tx.hash });
+   * ```
+   */
+  async rejectFile(datasetId, fileId, options) {
+    this.assertWallet();
+    try {
+      const chainId = await this.context.publicClient.getChainId();
+      const address = (0, import_addresses.getContractAddress)(chainId, "DatasetRegistry");
+      const abi = (0, import_abi.getAbi)("DatasetRegistry");
+      const account = this.context.walletClient.account ?? this.context.userAddress;
+      if (!account) {
+        throw new Error("No account found");
+      }
+      const accountAddress = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address,
+        abi,
+        functionName: "rejectFile",
+        args: [BigInt(datasetId), BigInt(fileId)],
+        account,
+        chain: this.context.walletClient.chain,
+        ...this.spreadTransactionOptions(options)
+      });
+      return (0, import_transactionHelpers.tx)({
+        hash,
+        from: accountAddress,
+        contract: "DatasetRegistry",
+        fn: "rejectFile"
+      });
+    } catch (error) {
+      throw new import_errors.BlockchainError(
+        `Failed to reject file: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+  /**
+   * Get dataset details including file lists.
+   *
+   * @remarks
+   * Retrieves complete dataset state including owner, pending files,
+   * accepted files, schema, and creation time. This is a read-only
+   * operation that doesn't require a wallet.
+   *
+   * @param datasetId - Dataset ID to query
+   * @returns Dataset object with all details
+   * @throws {BlockchainError} When dataset query fails
+   *
+   * @example
+   * ```typescript
+   * const dataset = await vana.dataset.getDataset(1);
+   * console.log(`Owner: ${dataset.owner}`);
+   * console.log(`Pending: ${dataset.pendingFileIds.length}`);
+   * console.log(`Accepted: ${dataset.fileIds.length}`);
+   * ```
+   */
+  async getDataset(datasetId) {
+    try {
+      const chainId = await this.context.publicClient.getChainId();
+      const address = (0, import_addresses.getContractAddress)(chainId, "DatasetRegistry");
+      const abi = (0, import_abi.getAbi)("DatasetRegistry");
+      const contract = (0, import_viem.getContract)({
+        address,
+        abi,
+        client: this.context.publicClient
+      });
+      const data = await contract.read.getDataset([BigInt(datasetId)]);
+      return {
+        owner: data.owner,
+        pendingFileIds: data.pendingFileIds.map(Number),
+        fileIds: data.fileIds.map(Number),
+        schemaId: Number(data.schemaId),
+        createdAt: Number(data.createdAt)
+      };
+    } catch (error) {
+      throw new import_errors.BlockchainError(
+        `Failed to get dataset: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+  /**
+   * Get all datasets owned by a specific address.
+   *
+   * @remarks
+   * Queries all datasets created by the specified owner. Uses the subgraph
+   * when available for efficient querying, with fallback to RPC via event
+   * logs and multicall for guaranteed real-time accuracy.
+   *
+   * This method will be optimized when datasets are added to the subgraph.
+   * Until then, it efficiently queries the chain using event logs to find
+   * dataset IDs, then uses multicall to batch-read dataset details.
+   *
+   * @param params - Query parameters
+   * @param params.owner - Owner address to query datasets for
+   * @param params.subgraphUrl - Optional custom subgraph URL
+   * @param options - Optional consistency and pagination settings
+   * @returns Array of datasets with their IDs
+   * @throws {BlockchainError} When dataset query fails
+   *
+   * @example
+   * ```typescript
+   * // Get all datasets for an address
+   * const datasets = await vana.dataset.getUserDatasets({
+   *   owner: "0x123..."
+   * });
+   *
+   * // With pagination
+   * const page1 = await vana.dataset.getUserDatasets(
+   *   { owner: "0x123..." },
+   *   { limit: 10, offset: 0 }
+   * );
+   *
+   * // Require recent data from chain
+   * const recent = await vana.dataset.getUserDatasets(
+   *   { owner: "0x123..." },
+   *   { source: "chain" }
+   * );
+   * ```
+   */
+  async getUserDatasets(params, options) {
+    const { owner } = params;
+    const dataSource = "chain";
+    if (dataSource === "chain") {
+      try {
+        const chainId = await this.context.publicClient.getChainId();
+        const contractAddress = (0, import_addresses.getContractAddress)(chainId, "DatasetRegistry");
+        const abi = (0, import_abi.getAbi)("DatasetRegistry");
+        const BATCH_SIZE = 100;
+        const MAX_DATASET_ID = 1e5;
+        let currentId = 1;
+        const userDatasets = [];
+        let reachedEnd = false;
+        while (currentId <= MAX_DATASET_ID && !reachedEnd) {
+          const batchEnd = Math.min(currentId + BATCH_SIZE, MAX_DATASET_ID + 1);
+          const calls = [];
+          for (let id = currentId; id < batchEnd; id++) {
+            calls.push({
+              address: contractAddress,
+              abi,
+              functionName: "getDataset",
+              args: [BigInt(id)]
+            });
+          }
+          const results = await (0, import_multicall.gasAwareMulticall)(
+            this.context.publicClient,
+            {
+              contracts: calls,
+              allowFailure: true
+            },
+            {
+              allowFailure: true
+            }
+          );
+          for (let i = 0; i < results.length; i++) {
+            const result = results[i];
+            const datasetId = currentId + i;
+            if (result.status === "failure" || !result.result) {
+              reachedEnd = true;
+              break;
+            }
+            const data = result.result;
+            const datasetOwner = data.owner;
+            if (!datasetOwner || datasetOwner === "0x0000000000000000000000000000000000000000") {
+              reachedEnd = true;
+              break;
+            }
+            if (datasetOwner.toLowerCase() === owner.toLowerCase()) {
+              userDatasets.push({
+                id: datasetId,
+                owner: datasetOwner,
+                pendingFileIds: data.pendingFileIds.map(Number),
+                fileIds: data.fileIds.map(Number),
+                schemaId: Number(data.schemaId),
+                createdAt: Number(data.createdAt)
+              });
+            }
+          }
+          currentId = batchEnd;
+        }
+        const limit = options?.fetchAll ? userDatasets.length : options?.limit ?? 100;
+        const offset = options?.offset ?? 0;
+        userDatasets.sort((a, b) => b.createdAt - a.createdAt);
+        return userDatasets.slice(offset, offset + limit);
+      } catch (error) {
+        throw new import_errors.BlockchainError(
+          `Failed to get user datasets: ${error instanceof Error ? error.message : String(error)}`,
+          error
+        );
+      }
+    }
+    throw new Error("Subgraph dataset queries not yet implemented");
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DatasetController
+});
+//# sourceMappingURL=dataset.cjs.map

package/dist/controllers/dataset.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/dataset.ts"],"sourcesContent":["/**\n * Controller for managing datasets and contributor workflows.\n *\n * @remarks\n * Handles dataset creation, file acceptance/rejection, and querying\n * through the DatasetRegistry contract. Implements the Contributor\n * Workflow where files are submitted as pending and must be accepted\n * by the dataset owner.\n *\n * @category Controllers\n */\n\nimport { getContract, type Address } from \"viem\";\nimport { BaseController } from \"./base\";\nimport type {\n  TransactionOptions,\n  TransactionResult,\n} from \"../types/operations\";\nimport type { Dataset } from \"../types/dataset\";\nimport type { ConsistencyOptions, PaginationOptions } from \"../types/options\";\nimport { getContractAddress } from \"../generated/addresses\";\nimport { getAbi } from \"../generated/abi\";\nimport { tx } from \"../utils/transactionHelpers\";\nimport { BlockchainError } from \"../errors\";\nimport { gasAwareMulticall } from \"../utils/multicall\";\n\n/**\n * Dataset management controller implementing the Contributor Workflow.\n *\n * @remarks\n * Separates dataset management from raw file operations (DataController).\n * Handles the logical grouping of files and owner approval workflow.\n *\n * Key responsibilities:\n * - Creating new datasets with schema validation\n * - Managing pending file approval queue\n * - Accepting/rejecting contributor files\n * - Querying dataset state and file lists\n *\n * @example\n * ```typescript\n * // Create a dataset\n * const result = await vana.dataset.createDataset(schemaId);\n * const datasetId = await vana.waitForTransactionEvents(result);\n *\n * // Get pending files\n * const dataset = await vana.dataset.getDataset(datasetId);\n * console.log(`${dataset.pendingFileIds.length} files awaiting approval`);\n *\n * // Accept a file\n * await vana.dataset.acceptFile(datasetId, fileId);\n * ```\n */\nexport class DatasetController extends BaseController {\n  /**\n   * Create a new dataset on the Vana network.\n   *\n   * @remarks\n   * Creates a dataset with the caller as the owner. The dataset will\n   * use the specified schema for file validation. Files can be added\n   * through the contribute workflow and must be accepted by the owner.\n   *\n   * @param schemaId - Schema ID defining file structure and validation\n   * @param options - Optional transaction parameters (gas, nonce, etc.)\n   * @returns Transaction result with DatasetCreated event\n   * @throws {ReadOnlyError} When no wallet is configured\n   * @throws {BlockchainError} When dataset creation fails\n   *\n   * @example\n   * ```typescript\n   * const tx = await vana.dataset.createDataset(42);\n   * const events = await vana.waitForTransactionEvents(tx);\n   * console.log(`Dataset ${events.datasetId} created`);\n   * ```\n   */\n  async createDataset(\n    schemaId: number,\n    options?: TransactionOptions,\n  ): Promise<TransactionResult<\"DatasetRegistry\", \"createDataset\">> {\n    this.assertWallet();\n\n    try {\n      const chainId = await this.context.publicClient.getChainId();\n      const address = getContractAddress(chainId, \"DatasetRegistry\");\n      const abi = getAbi(\"DatasetRegistry\");\n      const account =\n        this.context.walletClient.account ?? this.context.userAddress;\n\n      if (!account) {\n        throw new Error(\"No account found\");\n      }\n\n      const accountAddress =\n        typeof account === \"string\" ? account : account.address;\n\n      const hash = await this.context.walletClient.writeContract({\n        address,\n        abi,\n        functionName: \"createDataset\",\n        args: [accountAddress, BigInt(schemaId)],\n        account,\n        chain: this.context.walletClient.chain,\n        ...this.spreadTransactionOptions(options),\n      });\n\n      return tx({\n        hash,\n        from: accountAddress,\n        contract: \"DatasetRegistry\",\n        fn: \"createDataset\",\n      });\n    } catch (error) {\n      throw new BlockchainError(\n        `Failed to create dataset: ${error instanceof Error ? error.message : String(error)}`,\n        error as Error,\n      );\n    }\n  }\n\n  /**\n   * Accept a pending file into the dataset.\n   *\n   * @remarks\n   * Validates and accepts a contributor's file submission. Only the\n   * dataset owner can accept files. Once accepted, the file becomes\n   * part of the dataset and can be used in operations.\n   *\n   * @param datasetId - Dataset ID to accept the file into\n   * @param fileId - File ID to accept from pending queue\n   * @param options - Optional transaction parameters\n   * @returns Transaction result with FileAccepted event\n   * @throws {ReadOnlyError} When no wallet is configured\n   * @throws {BlockchainError} When file acceptance fails\n   *\n   * @example\n   * ```typescript\n   * const tx = await vana.dataset.acceptFile(1, 42);\n   * await vana.publicClient.waitForTransactionReceipt({ hash: tx.hash });\n   * console.log(`File ${fileId} accepted into dataset ${datasetId}`);\n   * ```\n   */\n  async acceptFile(\n    datasetId: number,\n    fileId: number,\n    options?: TransactionOptions,\n  ): Promise<TransactionResult<\"DatasetRegistry\", \"acceptFile\">> {\n    this.assertWallet();\n\n    try {\n      const chainId = await this.context.publicClient.getChainId();\n      const address = getContractAddress(chainId, \"DatasetRegistry\");\n      const abi = getAbi(\"DatasetRegistry\");\n      const account =\n        this.context.walletClient.account ?? this.context.userAddress;\n\n      if (!account) {\n        throw new Error(\"No account found\");\n      }\n\n      const accountAddress =\n        typeof account === \"string\" ? account : account.address;\n\n      const hash = await this.context.walletClient.writeContract({\n        address,\n        abi,\n        functionName: \"acceptFile\",\n        args: [BigInt(datasetId), BigInt(fileId)],\n        account,\n        chain: this.context.walletClient.chain,\n        ...this.spreadTransactionOptions(options),\n      });\n\n      return tx({\n        hash,\n        from: accountAddress,\n        contract: \"DatasetRegistry\",\n        fn: \"acceptFile\",\n      });\n    } catch (error) {\n      throw new BlockchainError(\n        `Failed to accept file: ${error instanceof Error ? error.message : String(error)}`,\n        error as Error,\n      );\n    }\n  }\n\n  /**\n   * Reject a pending file submission.\n   *\n   * @remarks\n   * Removes a file from the pending queue without accepting it.\n   * Only the dataset owner can reject files. The file remains in\n   * the DataRegistry but is not part of this dataset.\n   *\n   * @param datasetId - Dataset ID to reject the file from\n   * @param fileId - File ID to reject from pending queue\n   * @param options - Optional transaction parameters\n   * @returns Transaction result with FileRejected event\n   * @throws {ReadOnlyError} When no wallet is configured\n   * @throws {BlockchainError} When file rejection fails\n   *\n   * @example\n   * ```typescript\n   * const tx = await vana.dataset.rejectFile(1, 42);\n   * await vana.publicClient.waitForTransactionReceipt({ hash: tx.hash });\n   * ```\n   */\n  async rejectFile(\n    datasetId: number,\n    fileId: number,\n    options?: TransactionOptions,\n  ): Promise<TransactionResult<\"DatasetRegistry\", \"rejectFile\">> {\n    this.assertWallet();\n\n    try {\n      const chainId = await this.context.publicClient.getChainId();\n      const address = getContractAddress(chainId, \"DatasetRegistry\");\n      const abi = getAbi(\"DatasetRegistry\");\n      const account =\n        this.context.walletClient.account ?? this.context.userAddress;\n\n      if (!account) {\n        throw new Error(\"No account found\");\n      }\n\n      const accountAddress =\n        typeof account === \"string\" ? account : account.address;\n\n      const hash = await this.context.walletClient.writeContract({\n        address,\n        abi,\n        functionName: \"rejectFile\",\n        args: [BigInt(datasetId), BigInt(fileId)],\n        account,\n        chain: this.context.walletClient.chain,\n        ...this.spreadTransactionOptions(options),\n      });\n\n      return tx({\n        hash,\n        from: accountAddress,\n        contract: \"DatasetRegistry\",\n        fn: \"rejectFile\",\n      });\n    } catch (error) {\n      throw new BlockchainError(\n        `Failed to reject file: ${error instanceof Error ? error.message : String(error)}`,\n        error as Error,\n      );\n    }\n  }\n\n  /**\n   * Get dataset details including file lists.\n   *\n   * @remarks\n   * Retrieves complete dataset state including owner, pending files,\n   * accepted files, schema, and creation time. This is a read-only\n   * operation that doesn't require a wallet.\n   *\n   * @param datasetId - Dataset ID to query\n   * @returns Dataset object with all details\n   * @throws {BlockchainError} When dataset query fails\n   *\n   * @example\n   * ```typescript\n   * const dataset = await vana.dataset.getDataset(1);\n   * console.log(`Owner: ${dataset.owner}`);\n   * console.log(`Pending: ${dataset.pendingFileIds.length}`);\n   * console.log(`Accepted: ${dataset.fileIds.length}`);\n   * ```\n   */\n  async getDataset(datasetId: number): Promise<Dataset> {\n    try {\n      const chainId = await this.context.publicClient.getChainId();\n      const address = getContractAddress(chainId, \"DatasetRegistry\");\n      const abi = getAbi(\"DatasetRegistry\");\n\n      const contract = getContract({\n        address,\n        abi,\n        client: this.context.publicClient,\n      });\n\n      const data = (await contract.read.getDataset([BigInt(datasetId)])) as any;\n\n      // Map contract struct to SDK type\n      return {\n        owner: data.owner as `0x${string}`,\n        pendingFileIds: data.pendingFileIds.map(Number),\n        fileIds: data.fileIds.map(Number),\n        schemaId: Number(data.schemaId),\n        createdAt: Number(data.createdAt),\n      };\n    } catch (error) {\n      throw new BlockchainError(\n        `Failed to get dataset: ${error instanceof Error ? error.message : String(error)}`,\n        error as Error,\n      );\n    }\n  }\n\n  /**\n   * Get all datasets owned by a specific address.\n   *\n   * @remarks\n   * Queries all datasets created by the specified owner. Uses the subgraph\n   * when available for efficient querying, with fallback to RPC via event\n   * logs and multicall for guaranteed real-time accuracy.\n   *\n   * This method will be optimized when datasets are added to the subgraph.\n   * Until then, it efficiently queries the chain using event logs to find\n   * dataset IDs, then uses multicall to batch-read dataset details.\n   *\n   * @param params - Query parameters\n   * @param params.owner - Owner address to query datasets for\n   * @param params.subgraphUrl - Optional custom subgraph URL\n   * @param options - Optional consistency and pagination settings\n   * @returns Array of datasets with their IDs\n   * @throws {BlockchainError} When dataset query fails\n   *\n   * @example\n   * ```typescript\n   * // Get all datasets for an address\n   * const datasets = await vana.dataset.getUserDatasets({\n   *   owner: \"0x123...\"\n   * });\n   *\n   * // With pagination\n   * const page1 = await vana.dataset.getUserDatasets(\n   *   { owner: \"0x123...\" },\n   *   { limit: 10, offset: 0 }\n   * );\n   *\n   * // Require recent data from chain\n   * const recent = await vana.dataset.getUserDatasets(\n   *   { owner: \"0x123...\" },\n   *   { source: \"chain\" }\n   * );\n   * ```\n   */\n  async getUserDatasets(\n    params: {\n      owner: Address;\n      subgraphUrl?: string;\n    },\n    options?: ConsistencyOptions & PaginationOptions,\n  ): Promise<Array<Dataset & { id: number }>> {\n    const { owner } = params;\n\n    // Note: Subgraph doesn't have dataset entities yet, so we always use chain\n    // This will be optimized when datasets are added to the subgraph schema\n    const dataSource = \"chain\";\n\n    // For now, we only support chain queries\n    // Future: Add subgraph query path when datasets are in the subgraph\n    if (dataSource === \"chain\") {\n      try {\n        const chainId = await this.context.publicClient.getChainId();\n        const contractAddress = getContractAddress(chainId, \"DatasetRegistry\");\n        const abi = getAbi(\"DatasetRegistry\");\n\n        // Strategy: Batch-read datasets with multicall, starting from ID 1\n        // Dataset IDs are sequential, so we stop as soon as we hit a non-existent dataset\n        // This avoids eth_getLogs which has range limits\n\n        const BATCH_SIZE = 100; // Read 100 datasets at a time\n        const MAX_DATASET_ID = 100000; // Safety limit to prevent infinite loops\n\n        let currentId = 1;\n        const userDatasets: Array<Dataset & { id: number }> = [];\n        let reachedEnd = false;\n\n        while (currentId <= MAX_DATASET_ID && !reachedEnd) {\n          // Build batch of calls\n          const batchEnd = Math.min(currentId + BATCH_SIZE, MAX_DATASET_ID + 1);\n          const calls = [];\n          for (let id = currentId; id < batchEnd; id++) {\n            calls.push({\n              address: contractAddress,\n              abi,\n              functionName: \"getDataset\",\n              args: [BigInt(id)],\n            });\n          }\n\n          // Batch-read datasets using multicall\n          const results = await gasAwareMulticall(\n            this.context.publicClient,\n            {\n              contracts: calls,\n              allowFailure: true,\n            },\n            {\n              allowFailure: true,\n            },\n          );\n\n          // Process results and filter by owner\n          for (let i = 0; i < results.length; i++) {\n            const result = results[i];\n            const datasetId = currentId + i;\n\n            // If we hit a non-existent dataset (failed call or zero owner), we've reached the end\n            if (result.status === \"failure\" || !result.result) {\n              reachedEnd = true;\n              break;\n            }\n\n            const data = result.result as any;\n            const datasetOwner = data.owner as `0x${string}`;\n\n            // Check for zero address (non-existent dataset)\n            if (\n              !datasetOwner ||\n              datasetOwner === \"0x0000000000000000000000000000000000000000\"\n            ) {\n              reachedEnd = true;\n              break;\n            }\n\n            // If this dataset is owned by the user, add it\n            if (datasetOwner.toLowerCase() === owner.toLowerCase()) {\n              userDatasets.push({\n                id: datasetId,\n                owner: datasetOwner,\n                pendingFileIds: data.pendingFileIds.map(Number),\n                fileIds: data.fileIds.map(Number),\n                schemaId: Number(data.schemaId),\n                createdAt: Number(data.createdAt),\n              });\n            }\n          }\n\n          currentId = batchEnd;\n        }\n\n        // Apply pagination to results\n        const limit = options?.fetchAll\n          ? userDatasets.length\n          : (options?.limit ?? 100);\n        const offset = options?.offset ?? 0;\n\n        // Sort by creation time descending (most recent first)\n        userDatasets.sort((a, b) => b.createdAt - a.createdAt);\n\n        return userDatasets.slice(offset, offset + limit);\n      } catch (error) {\n        throw new BlockchainError(\n          `Failed to get user datasets: ${error instanceof Error ? error.message : String(error)}`,\n          error as Error,\n        );\n      }\n    }\n\n    // Future: When subgraph has dataset entities, implement this path\n    // For now, this code path is unreachable but prepared for future enhancement\n    throw new Error(\"Subgraph dataset queries not yet implemented\");\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/controllers/dataset.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Controller for managing datasets and contributor workflows.
+ *
+ * @remarks
+ * Handles dataset creation, file acceptance/rejection, and querying
+ * through the DatasetRegistry contract. Implements the Contributor
+ * Workflow where files are submitted as pending and must be accepted
+ * by the dataset owner.
+ *
+ * @category Controllers
+ */
+import { type Address } from "viem";
+import { BaseController } from "./base";
+import type { TransactionOptions, TransactionResult } from "../types/operations";
+import type { Dataset } from "../types/dataset";
+import type { ConsistencyOptions, PaginationOptions } from "../types/options";
+/**
+ * Dataset management controller implementing the Contributor Workflow.
+ *
+ * @remarks
+ * Separates dataset management from raw file operations (DataController).
+ * Handles the logical grouping of files and owner approval workflow.
+ *
+ * Key responsibilities:
+ * - Creating new datasets with schema validation
+ * - Managing pending file approval queue
+ * - Accepting/rejecting contributor files
+ * - Querying dataset state and file lists
+ *
+ * @example
+ * ```typescript
+ * // Create a dataset
+ * const result = await vana.dataset.createDataset(schemaId);
+ * const datasetId = await vana.waitForTransactionEvents(result);
+ *
+ * // Get pending files
+ * const dataset = await vana.dataset.getDataset(datasetId);
+ * console.log(`${dataset.pendingFileIds.length} files awaiting approval`);
+ *
+ * // Accept a file
+ * await vana.dataset.acceptFile(datasetId, fileId);
+ * ```
+ */
+export declare class DatasetController extends BaseController {
+    /**
+     * Create a new dataset on the Vana network.
+     *
+     * @remarks
+     * Creates a dataset with the caller as the owner. The dataset will
+     * use the specified schema for file validation. Files can be added
+     * through the contribute workflow and must be accepted by the owner.
+     *
+     * @param schemaId - Schema ID defining file structure and validation
+     * @param options - Optional transaction parameters (gas, nonce, etc.)
+     * @returns Transaction result with DatasetCreated event
+     * @throws {ReadOnlyError} When no wallet is configured
+     * @throws {BlockchainError} When dataset creation fails
+     *
+     * @example
+     * ```typescript
+     * const tx = await vana.dataset.createDataset(42);
+     * const events = await vana.waitForTransactionEvents(tx);
+     * console.log(`Dataset ${events.datasetId} created`);
+     * ```
+     */
+    createDataset(schemaId: number, options?: TransactionOptions): Promise<TransactionResult<"DatasetRegistry", "createDataset">>;
+    /**
+     * Accept a pending file into the dataset.
+     *
+     * @remarks
+     * Validates and accepts a contributor's file submission. Only the
+     * dataset owner can accept files. Once accepted, the file becomes
+     * part of the dataset and can be used in operations.
+     *
+     * @param datasetId - Dataset ID to accept the file into
+     * @param fileId - File ID to accept from pending queue
+     * @param options - Optional transaction parameters
+     * @returns Transaction result with FileAccepted event
+     * @throws {ReadOnlyError} When no wallet is configured
+     * @throws {BlockchainError} When file acceptance fails
+     *
+     * @example
+     * ```typescript
+     * const tx = await vana.dataset.acceptFile(1, 42);
+     * await vana.publicClient.waitForTransactionReceipt({ hash: tx.hash });
+     * console.log(`File ${fileId} accepted into dataset ${datasetId}`);
+     * ```
+     */
+    acceptFile(datasetId: number, fileId: number, options?: TransactionOptions): Promise<TransactionResult<"DatasetRegistry", "acceptFile">>;
+    /**
+     * Reject a pending file submission.
+     *
+     * @remarks
+     * Removes a file from the pending queue without accepting it.
+     * Only the dataset owner can reject files. The file remains in
+     * the DataRegistry but is not part of this dataset.
+     *
+     * @param datasetId - Dataset ID to reject the file from
+     * @param fileId - File ID to reject from pending queue
+     * @param options - Optional transaction parameters
+     * @returns Transaction result with FileRejected event
+     * @throws {ReadOnlyError} When no wallet is configured
+     * @throws {BlockchainError} When file rejection fails
+     *
+     * @example
+     * ```typescript
+     * const tx = await vana.dataset.rejectFile(1, 42);
+     * await vana.publicClient.waitForTransactionReceipt({ hash: tx.hash });
+     * ```
+     */
+    rejectFile(datasetId: number, fileId: number, options?: TransactionOptions): Promise<TransactionResult<"DatasetRegistry", "rejectFile">>;
+    /**
+     * Get dataset details including file lists.
+     *
+     * @remarks
+     * Retrieves complete dataset state including owner, pending files,
+     * accepted files, schema, and creation time. This is a read-only
+     * operation that doesn't require a wallet.
+     *
+     * @param datasetId - Dataset ID to query
+     * @returns Dataset object with all details
+     * @throws {BlockchainError} When dataset query fails
+     *
+     * @example
+     * ```typescript
+     * const dataset = await vana.dataset.getDataset(1);
+     * console.log(`Owner: ${dataset.owner}`);
+     * console.log(`Pending: ${dataset.pendingFileIds.length}`);
+     * console.log(`Accepted: ${dataset.fileIds.length}`);
+     * ```
+     */
+    getDataset(datasetId: number): Promise<Dataset>;
+    /**
+     * Get all datasets owned by a specific address.
+     *
+     * @remarks
+     * Queries all datasets created by the specified owner. Uses the subgraph
+     * when available for efficient querying, with fallback to RPC via event
+     * logs and multicall for guaranteed real-time accuracy.
+     *
+     * This method will be optimized when datasets are added to the subgraph.
+     * Until then, it efficiently queries the chain using event logs to find
+     * dataset IDs, then uses multicall to batch-read dataset details.
+     *
+     * @param params - Query parameters
+     * @param params.owner - Owner address to query datasets for
+     * @param params.subgraphUrl - Optional custom subgraph URL
+     * @param options - Optional consistency and pagination settings
+     * @returns Array of datasets with their IDs
+     * @throws {BlockchainError} When dataset query fails
+     *
+     * @example
+     * ```typescript
+     * // Get all datasets for an address
+     * const datasets = await vana.dataset.getUserDatasets({
+     *   owner: "0x123..."
+     * });
+     *
+     * // With pagination
+     * const page1 = await vana.dataset.getUserDatasets(
+     *   { owner: "0x123..." },
+     *   { limit: 10, offset: 0 }
+     * );
+     *
+     * // Require recent data from chain
+     * const recent = await vana.dataset.getUserDatasets(
+     *   { owner: "0x123..." },
+     *   { source: "chain" }
+     * );
+     * ```
+     */
+    getUserDatasets(params: {
+        owner: Address;
+        subgraphUrl?: string;
+    }, options?: ConsistencyOptions & PaginationOptions): Promise<Array<Dataset & {
+        id: number;
+    }>>;
+}