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

package/dist/controllers/schemas.cjs

@@ -0,0 +1,608 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var schemas_exports = {};
+__export(schemas_exports, {
+  SchemaController: () => SchemaController
+});
+module.exports = __toCommonJS(schemas_exports);
+var import_addresses = require("../config/addresses");
+var import_abi = require("../generated/abi");
+var import_multicall = require("../utils/multicall");
+var import_schemaValidation = require("../utils/schemaValidation");
+var import_registry = require("../utils/blockchain/registry");
+var import_subgraph = require("../generated/subgraph");
+var import_graphql = require("graphql");
+var import_urlResolver = require("../utils/urlResolver");
+class SchemaController {
+  constructor(context) {
+    this.context = context;
+  }
+  /**
+   * Creates a new schema with automatic validation and IPFS upload.
+   *
+   * @remarks
+   * This is the primary method for creating schemas on the Vana network. It handles
+   * the complete workflow including schema validation, IPFS upload, and blockchain
+   * registration. The schema definition is stored unencrypted on IPFS to enable
+   * public access and reusability.
+   *
+   * The method automatically:
+   * - Validates the schema definition against the Vana metaschema
+   * - Uploads the definition to IPFS to generate a permanent URL
+   * - Registers the schema on the blockchain with the generated URL
+   *
+   * @param params - Schema creation parameters including name, dialect, and definition
+   * @returns Promise resolving to creation results with schema ID and transaction hash
+   * @throws {SchemaValidationError} When the schema definition is invalid
+   * @throws {Error} When IPFS upload or blockchain registration fails
+   * @example
+   * ```typescript
+   * // Create a JSON schema for user profiles
+   * const result = await vana.schemas.create({
+   *   name: "User Profile",
+   *   dialect: "json",
+   *   schema: {
+   *     type: "object",
+   *     properties: {
+   *       name: { type: "string" },
+   *       age: { type: "number", minimum: 0 }
+   *     },
+   *     required: ["name"]
+   *   }
+   * });
+   *
+   * console.log(`Schema created with ID: ${result.schemaId}`);
+   * ```
+   */
+  async create(params) {
+    const { name, dialect, schema } = params;
+    try {
+      let schemaDefinition;
+      if (typeof schema === "string") {
+        try {
+          schemaDefinition = JSON.parse(schema);
+        } catch {
+          throw new import_schemaValidation.SchemaValidationError(
+            "Invalid JSON in schema definition",
+            []
+          );
+        }
+      } else {
+        schemaDefinition = schema;
+      }
+      const dataSchema = {
+        name,
+        version: "1.0.0",
+        dialect,
+        schema: schemaDefinition
+      };
+      (0, import_schemaValidation.validateDataSchemaAgainstMetaSchema)(dataSchema);
+      if (!this.context.storageManager) {
+        if (this.context.validateStorageRequired) {
+          this.context.validateStorageRequired();
+          throw new Error("Storage validation failed");
+        } else {
+          throw new Error(
+            "Storage manager not configured. Please provide storage providers in VanaConfig."
+          );
+        }
+      }
+      const schemaBlob = new Blob([JSON.stringify(dataSchema)], {
+        type: "application/json"
+      });
+      const uploadResult = await this.context.storageManager.upload(
+        schemaBlob,
+        `${name.replace(/[^a-zA-Z0-9]/g, "_")}.json`,
+        "ipfs"
+        // Use IPFS for public schema storage
+      );
+      const chainId = this.context.walletClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = (0, import_addresses.getContractAddress)(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = (0, import_abi.getAbi)("DataRefinerRegistry");
+      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const from = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address: dataRefinerRegistryAddress,
+        abi: dataRefinerRegistryAbi,
+        functionName: "addSchema",
+        args: [name, dialect, uploadResult.url],
+        account,
+        chain: this.context.walletClient.chain ?? null
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      const txResult = tx({
+        hash,
+        from,
+        contract: "DataRefinerRegistry",
+        fn: "addSchema"
+      });
+      if (!this.context.waitForTransactionEvents) {
+        throw new Error("waitForTransactionEvents not configured");
+      }
+      const result = await this.context.waitForTransactionEvents(txResult);
+      const event = result.expectedEvents.SchemaAdded;
+      if (!event) {
+        throw new Error("SchemaAdded event not found in transaction");
+      }
+      return {
+        schemaId: event.schemaId,
+        definitionUrl: uploadResult.url,
+        transactionHash: hash
+      };
+    } catch (error) {
+      if (error instanceof import_schemaValidation.SchemaValidationError) {
+        throw error;
+      }
+      throw new Error(
+        `Schema creation failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Retrieves a complete schema by its ID with definition fetched and flattened.
+   *
+   * @param schemaId - The ID of the schema to retrieve
+   * @param options - Optional parameters
+   * @param options.subgraphUrl - Custom subgraph URL to use instead of default
+   * @returns Promise resolving to the complete schema object with all fields populated
+   * @throws {Error} When the schema is not found, definition cannot be fetched, or chain is unavailable
+   * @example
+   * ```typescript
+   * const schema = await vana.schemas.get(1);
+   * console.log(`Schema: ${schema.name} (${schema.dialect})`);
+   * console.log(`Version: ${schema.version}`);
+   * console.log(`Description: ${schema.description}`);
+   * console.log('Schema:', schema.schema);
+   *
+   * // Use directly with validator (schema has all required fields)
+   * validator.validateDataAgainstSchema(data, schema);
+   * ```
+   */
+  async get(schemaId, options = {}) {
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
+    let metadata;
+    if (subgraphUrl) {
+      try {
+        metadata = await this._getSchemaViaSubgraph({ schemaId, subgraphUrl });
+      } catch (error) {
+        console.debug("Subgraph query failed, falling back to RPC:", error);
+        try {
+          metadata = await (0, import_registry.fetchSchemaFromChain)(this.context, schemaId);
+        } catch (rpcError) {
+          throw new Error(
+            `Failed to get schema: ${rpcError instanceof Error ? rpcError.message : "Unknown error"}`
+          );
+        }
+      }
+    } else {
+      try {
+        metadata = await (0, import_registry.fetchSchemaFromChain)(this.context, schemaId);
+      } catch (error) {
+        throw new Error(
+          `Failed to get schema: ${error instanceof Error ? error.message : "Unknown error"}`
+        );
+      }
+    }
+    const definition = await (0, import_urlResolver.fetchFromUrl)(
+      metadata.definitionUrl,
+      this.context.downloadRelayer
+    );
+    if (!definition || typeof definition !== "object") {
+      throw new Error(
+        `Invalid schema definition format for schema ${schemaId}`
+      );
+    }
+    (0, import_schemaValidation.validateDataSchemaAgainstMetaSchema)(definition);
+    const dataSchema = definition;
+    if (dataSchema.name !== metadata.name) {
+      console.warn(
+        `Schema name mismatch for ID ${schemaId}: on-chain="${metadata.name}" off-chain="${dataSchema.name}" (using on-chain value)`
+      );
+    }
+    if (dataSchema.dialect !== metadata.dialect) {
+      console.warn(
+        `Schema dialect mismatch for ID ${schemaId}: on-chain="${metadata.dialect}" off-chain="${dataSchema.dialect}" (using on-chain value)`
+      );
+    }
+    return {
+      ...metadata,
+      version: dataSchema.version,
+      description: dataSchema.description,
+      schema: dataSchema.schema
+    };
+  }
+  /**
+   * Gets the total number of schemas registered on the network.
+   *
+   * @param options - Optional parameters
+   * @param options.subgraphUrl - Custom subgraph URL to use instead of default
+   * @returns Promise resolving to the total schema count
+   * @throws {Error} When the count cannot be retrieved
+   * @example
+   * ```typescript
+   * const count = await vana.schemas.count();
+   * console.log(`Total schemas: ${count}`);
+   *
+   * // With custom subgraph
+   * const count = await vana.schemas.count({
+   *   subgraphUrl: 'https://custom-subgraph.com/graphql'
+   * });
+   * ```
+   */
+  async count(options = {}) {
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
+    if (subgraphUrl) {
+      try {
+        return await this._countSchemasViaSubgraph({ subgraphUrl });
+      } catch (error) {
+        console.debug("Subgraph query failed, falling back to RPC:", error);
+      }
+    }
+    try {
+      return await (0, import_registry.fetchSchemaCountFromChain)(this.context);
+    } catch (error) {
+      throw new Error(
+        `Failed to get schemas count: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Lists all schemas with pagination.
+   *
+   * @param options - Optional parameters for listing schemas
+   * @param options.limit - Maximum number of schemas to return
+   * @param options.offset - Number of schemas to skip
+   * @param options.subgraphUrl - Custom subgraph URL to use instead of default
+   * @param options.includeDefinitions - Whether to fetch and include schema definitions (default: false for performance)
+   * @returns Promise resolving to an array of schemas
+   * @example
+   * ```typescript
+   * // Get all schemas (without definitions for performance)
+   * const schemas = await vana.schemas.list();
+   *
+   * // Get schemas with definitions
+   * const schemas = await vana.schemas.list({ includeDefinitions: true });
+   *
+   * // Get schemas with pagination
+   * const schemas = await vana.schemas.list({ limit: 10, offset: 0 });
+   * ```
+   */
+  async list(options = {}) {
+    const { limit = 100, offset = 0, includeDefinitions = false } = options;
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
+    if (subgraphUrl) {
+      try {
+        return await this._listSchemasViaSubgraph({
+          limit,
+          offset,
+          subgraphUrl
+        });
+      } catch (error) {
+        console.debug("Subgraph query failed, falling back to RPC:", error);
+      }
+    }
+    try {
+      const totalCount = await this.count();
+      const start = offset;
+      const end = Math.min(start + limit, totalCount);
+      if (end <= start) {
+        return [];
+      }
+      const chainId = this.context.walletClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = (0, import_addresses.getContractAddress)(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = (0, import_abi.getAbi)("DataRefinerRegistry");
+      const schemaCalls = [];
+      for (let i = start; i < end; i++) {
+        schemaCalls.push({
+          address: dataRefinerRegistryAddress,
+          abi: dataRefinerRegistryAbi,
+          functionName: "schemas",
+          args: [BigInt(i + 1)]
+          // Schema IDs are 1-based
+        });
+      }
+      const schemaResults = await (0, import_multicall.gasAwareMulticall)(this.context.publicClient, {
+        contracts: schemaCalls,
+        allowFailure: true
+      });
+      const schemas = [];
+      schemaResults.forEach((result, index) => {
+        if (result.status === "success" && result.result) {
+          const schemaId = start + index + 1;
+          const schemaData = result.result;
+          if (schemaData.name && schemaData.dialect && schemaData.definitionUrl) {
+            schemas.push({
+              id: schemaId,
+              name: schemaData.name,
+              dialect: schemaData.dialect,
+              definitionUrl: schemaData.definitionUrl
+            });
+          } else {
+            console.warn(`Incomplete schema data for ID ${schemaId}`);
+          }
+        } else {
+          console.warn(`Failed to retrieve schema ${start + index + 1}`);
+        }
+      });
+      if (includeDefinitions) {
+        await this._fetchDefinitionsForSchemas(schemas);
+      }
+      return schemas;
+    } catch (error) {
+      throw new Error(
+        `Failed to list schemas: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Adds a schema using the legacy method (low-level API).
+   *
+   * @deprecated Use create() instead for the high-level API with automatic IPFS upload
+   * @param params - Schema parameters including pre-generated definition URL
+   * @returns Promise resolving to the add schema result
+   */
+  async addSchema(params) {
+    try {
+      const chainId = this.context.walletClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = (0, import_addresses.getContractAddress)(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = (0, import_abi.getAbi)("DataRefinerRegistry");
+      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const from = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address: dataRefinerRegistryAddress,
+        abi: dataRefinerRegistryAbi,
+        functionName: "addSchema",
+        args: [params.name, params.dialect, params.definitionUrl],
+        account,
+        chain: this.context.walletClient.chain ?? null
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      const txResult = tx({
+        hash,
+        from,
+        contract: "DataRefinerRegistry",
+        fn: "addSchema"
+      });
+      if (!this.context.waitForTransactionEvents) {
+        throw new Error("waitForTransactionEvents not configured");
+      }
+      const result = await this.context.waitForTransactionEvents(txResult);
+      const event = result.expectedEvents.SchemaAdded;
+      if (!event) {
+        throw new Error("SchemaAdded event not found in transaction");
+      }
+      const receipt = await this.context.publicClient.getTransactionReceipt({
+        hash
+      });
+      return {
+        transactionHash: hash,
+        blockNumber: receipt.blockNumber,
+        gasUsed: receipt.gasUsed,
+        schemaId: event.schemaId,
+        name: event.name,
+        dialect: event.dialect,
+        definitionUrl: event.definitionUrl
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to add schema: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Internal method: Query schema via subgraph
+   *
+   * @param params - Query parameters
+   * @param params.schemaId - The ID of the schema to retrieve
+   * @param params.subgraphUrl - The subgraph URL to query
+   * @returns Promise resolving to the schema object
+   * @private
+   */
+  async _getSchemaViaSubgraph(params) {
+    const { schemaId, subgraphUrl } = params;
+    const response = await fetch(subgraphUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: (0, import_graphql.print)(import_subgraph.GetSchemaDocument),
+        variables: { id: schemaId.toString() }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Subgraph request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    const result = await response.json();
+    if (result.errors) {
+      throw new Error(
+        `Subgraph query errors: ${result.errors.map((e) => e.message).join(", ")}`
+      );
+    }
+    if (!result.data?.schema) {
+      throw new Error(`Schema ${schemaId} not found in subgraph`);
+    }
+    const subgraphSchema = result.data.schema;
+    return {
+      id: parseInt(subgraphSchema.id),
+      name: subgraphSchema.name,
+      dialect: subgraphSchema.dialect,
+      definitionUrl: subgraphSchema.definitionUrl
+    };
+  }
+  /**
+   * Internal method: List schemas via subgraph
+   *
+   * @param params - Query parameters
+   * @param params.limit - Maximum number of schemas to return
+   * @param params.offset - Number of schemas to skip
+   * @param params.subgraphUrl - The subgraph URL to query
+   * @returns Promise resolving to an array of schemas
+   * @private
+   */
+  async _listSchemasViaSubgraph(params) {
+    const { limit, offset, subgraphUrl } = params;
+    const response = await fetch(subgraphUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: (0, import_graphql.print)(import_subgraph.ListSchemasDocument),
+        variables: { first: limit, skip: offset }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Subgraph request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    const result = await response.json();
+    if (result.errors) {
+      throw new Error(
+        `Subgraph query errors: ${result.errors.map((e) => e.message).join(", ")}`
+      );
+    }
+    if (!result.data?.schemas) {
+      return [];
+    }
+    const schemas = result.data.schemas.map((schema) => ({
+      id: parseInt(schema.id),
+      name: schema.name,
+      dialect: schema.dialect,
+      definitionUrl: schema.definitionUrl
+    }));
+    const { includeDefinitions } = params;
+    if (includeDefinitions) {
+      await this._fetchDefinitionsForSchemas(schemas);
+    }
+    return schemas;
+  }
+  /**
+   * Internal method: Count schemas via subgraph
+   *
+   * @param params - Query parameters
+   * @param params.subgraphUrl - The subgraph URL to query
+   * @returns Promise resolving to the total schema count
+   * @private
+   */
+  async _countSchemasViaSubgraph(params) {
+    const { subgraphUrl } = params;
+    const response = await fetch(subgraphUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: (0, import_graphql.print)(import_subgraph.CountSchemasDocument),
+        variables: {}
+      })
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Subgraph request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    const result = await response.json();
+    if (result.errors) {
+      throw new Error(
+        `Subgraph query errors: ${result.errors.map((e) => e.message).join(", ")}`
+      );
+    }
+    return result.data?.schemas?.length ?? 0;
+  }
+  /**
+   * Gets the user's wallet address.
+   *
+   * @private
+   * @returns Promise resolving to the user's address
+   */
+  async getUserAddress() {
+    if (!this.context.walletClient.account) {
+      throw new Error("No wallet account connected");
+    }
+    if (typeof this.context.walletClient.account === "string") {
+      return this.context.walletClient.account;
+    }
+    if (typeof this.context.walletClient.account === "object" && this.context.walletClient.account.address) {
+      return this.context.walletClient.account.address;
+    }
+    throw new Error("Unable to determine wallet address");
+  }
+  /**
+   * Fetches and attaches definitions to an array of schemas.
+   *
+   * @param schemas - Array of schemas to fetch definitions for
+   * @private
+   */
+  async _fetchDefinitionsForSchemas(schemas) {
+    await Promise.all(
+      schemas.map(async (schema) => {
+        if (!schema.definitionUrl) return;
+        try {
+          const definition = await (0, import_urlResolver.fetchFromUrl)(
+            schema.definitionUrl,
+            this.context.downloadRelayer
+          );
+          if (definition && typeof definition === "object") {
+            (0, import_schemaValidation.validateDataSchemaAgainstMetaSchema)(definition);
+            const dataSchema = definition;
+            schema.version = dataSchema.version;
+            schema.description = dataSchema.description;
+            schema.schema = dataSchema.schema;
+          }
+        } catch (error) {
+          console.error(
+            `Failed to fetch/validate definition for schema ${schema.id}:`,
+            error instanceof import_urlResolver.UrlResolutionError || error instanceof import_schemaValidation.SchemaValidationError ? error.message : error
+          );
+        }
+      })
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SchemaController
+});
+//# sourceMappingURL=schemas.cjs.map