@opendatalabs/vana-sdk 0.1.0-alpha.ffe4659 → 2.0.0

package/dist/controllers/schemas.js

@@ -0,0 +1,654 @@
+import { BaseController } from "./base";
+import { getContractAddress } from "../config/addresses";
+import { getAbi } from "../generated/abi";
+import { gasAwareMulticall } from "../utils/multicall";
+import {
+  validateDataSchemaAgainstMetaSchema,
+  SchemaValidationError
+} from "../utils/schemaValidation";
+import {
+  fetchSchemaFromChain,
+  fetchSchemaCountFromChain
+} from "../utils/blockchain/registry";
+import {
+  GetSchemaDocument,
+  ListSchemasDocument,
+  CountSchemasDocument
+} from "../generated/subgraph";
+import { print } from "graphql";
+import { fetchFromUrl, UrlResolutionError } from "../utils/urlResolver";
+class SchemaController extends BaseController {
+  constructor(context) {
+    super(context);
+  }
+  /**
+   * Creates a schema with validation and IPFS upload.
+   *
+   * @remarks
+   * Primary method for schema creation. Validates definition,
+   * uploads to IPFS (unencrypted for reusability), and registers
+   * on blockchain. Schema becomes immediately available network-wide.
+   *
+   * @param params - Creation configuration
+   * @param params.name - Human-readable schema name
+   * @param params.dialect - Schema format (`"json"` or `"sqlite"`)
+   * @param params.schema - Definition object or JSON string
+   *
+   * @returns Schema ID, IPFS URL, and transaction hash
+   *
+   * @throws {SchemaValidationError} Invalid schema definition.
+   *   Verify schema follows JSON Schema or SQLite format.
+   * @throws {Error} Storage not configured.
+   *   Configure storage providers in VanaConfig.
+   * @throws {Error} IPFS upload failed.
+   *   Check network and storage provider status.
+   *
+   * @example
+   * ```typescript
+   * const result = await vana.schemas.create({
+   *   name: "User Profile",
+   *   dialect: "json",
+   *   schema: {
+   *     type: "object",
+   *     properties: {
+   *       name: { type: "string", minLength: 1 },
+   *       age: { type: "number", minimum: 0 }
+   *     },
+   *     required: ["name"]
+   *   }
+   * });
+   * console.log(`Schema ${result.schemaId} at ${result.definitionUrl}`);
+   * ```
+   */
+  async create(params) {
+    this.assertWallet();
+    const { name, dialect, schema } = params;
+    try {
+      let schemaDefinition;
+      if (typeof schema === "string") {
+        try {
+          schemaDefinition = JSON.parse(schema);
+        } catch {
+          throw new SchemaValidationError(
+            "Invalid JSON in schema definition",
+            []
+          );
+        }
+      } else {
+        schemaDefinition = schema;
+      }
+      const dataSchema = {
+        name,
+        version: "1.0.0",
+        dialect,
+        schema: schemaDefinition
+      };
+      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`
+      );
+      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = getContractAddress(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
+      const account = this.context.walletClient.account ?? this.context.userAddress;
+      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 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 fetchSchemaFromChain(this.context, schemaId);
+        } catch (rpcError) {
+          throw new Error(
+            `Failed to get schema: ${rpcError instanceof Error ? rpcError.message : "Unknown error"}`
+          );
+        }
+      }
+    } else {
+      try {
+        metadata = await fetchSchemaFromChain(this.context, schemaId);
+      } catch (error) {
+        throw new Error(
+          `Failed to get schema: ${error instanceof Error ? error.message : "Unknown error"}`
+        );
+      }
+    }
+    const definition = await fetchFromUrl(
+      metadata.definitionUrl,
+      this.context.downloadRelayer
+    );
+    if (!definition || typeof definition !== "object") {
+      throw new Error(
+        `Invalid schema definition format for schema ${schemaId}`
+      );
+    }
+    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 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,
+      minBlock,
+      waitForSync
+    } = options;
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
+    if (subgraphUrl && (minBlock || waitForSync)) {
+      const { checkSubgraphConsistency } = await import("../utils/subgraphConsistency");
+      await checkSubgraphConsistency(subgraphUrl, { minBlock, waitForSync });
+    }
+    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 ?? this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = getContractAddress(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = 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 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"}`
+      );
+    }
+  }
+  /**
+   * Retrieves schema definition content directly from a URL.
+   *
+   * @remarks
+   * Use this method to fetch and format schema definitions from IPFS or HTTP URLs.
+   * Automatically uses the SDK's configured download proxy to bypass CORS restrictions.
+   * Returns formatted JSON string if content is valid JSON, otherwise raw content.
+   *
+   * @param url - The definition URL (typically from schema.definitionUrl)
+   * @returns Promise resolving to the formatted definition content
+   * @throws {Error} When the content cannot be fetched or network errors occur
+   * @example
+   * ```typescript
+   * const schema = await vana.schemas.get(1);
+   * const definition = await vana.schemas.retrieveDefinition(schema.definitionUrl);
+   * console.log(definition); // Pretty-printed JSON
+   * ```
+   */
+  async retrieveDefinition(url) {
+    try {
+      const { universalFetch } = await import("../utils/download");
+      const response = await universalFetch(url, this.context.downloadRelayer);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      const text = await response.text();
+      try {
+        const json = JSON.parse(text);
+        return JSON.stringify(json, null, 2);
+      } catch {
+        return text;
+      }
+    } catch (error) {
+      throw new Error(
+        `Failed to retrieve schema definition: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Retrieves refinement instruction content from a URL.
+   *
+   * @remarks
+   * Use this method to fetch refinement instructions from IPFS or HTTP URLs.
+   * Temporarily housed in SchemaController since refiners use schemas and we don't
+   * have a dedicated RefinerController yet. Uses the SDK's configured download proxy.
+   *
+   * @param url - The instruction URL (typically from refiner.refinementInstructionUrl)
+   * @returns Promise resolving to the formatted instruction content
+   * @throws {Error} When the content cannot be fetched or network errors occur
+   * @example
+   * ```typescript
+   * const instructions = await vana.schemas.retrieveRefinementInstructions(
+   *   refiner.refinementInstructionUrl
+   * );
+   * console.log(instructions);
+   * ```
+   */
+  async retrieveRefinementInstructions(url) {
+    try {
+      return await this.retrieveDefinition(url);
+    } catch (error) {
+      throw new Error(
+        `Failed to retrieve refinement instructions: ${error instanceof Error ? error.message.replace(
+          "Failed to retrieve schema definition: ",
+          ""
+        ) : "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) {
+    this.assertWallet();
+    try {
+      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = getContractAddress(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
+      const account = this.context.walletClient.account ?? this.context.userAddress;
+      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: print(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: print(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: print(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
+   */
+  /**
+   * 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 fetchFromUrl(
+            schema.definitionUrl,
+            this.context.downloadRelayer
+          );
+          if (definition && typeof definition === "object") {
+            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 UrlResolutionError || error instanceof SchemaValidationError ? error.message : error
+          );
+        }
+      })
+    );
+  }
+}
+export {
+  SchemaController
+};
+//# sourceMappingURL=schemas.js.map