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

package/dist/controllers/schemas.d.ts

@@ -1,30 +1,7 @@
-import { CompleteSchema, Schema, AddSchemaParams, AddSchemaResult } from '../types/data.js';
-import { C as ControllerContext } from '../permissions-eo8YeLGf.js';
-import 'viem';
-import '../types/operations.js';
-import '../generated/server/server-exports.js';
-import '../generated/server/server.js';
-import '../types/config.js';
-import '../types/chains.js';
-import '../types/storage.js';
-import '../types/permissions.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 '../platform/interface.js';
-
+import type { Schema, CompleteSchema, AddSchemaParams } from "../types/index";
+import type { SchemaAddedResult } from "../types/transactionResults";
+import type { ControllerContext } from "./permissions";
+import { BaseController } from "./base";
 /**
  * Parameters for creating a new schema with automatic IPFS upload.
  *
@@ -33,7 +10,7 @@ import '../platform/interface.js';
  * automatically uploads the schema definition to IPFS and registers it on-chain.
  * @category Schema Management
  */
-interface CreateSchemaParams {
+export interface CreateSchemaParams {
     /** The name of the schema */
     name: string;
     /** The dialect of the schema (e.g., 'json' or 'sqlite') */
@@ -48,99 +25,105 @@ interface CreateSchemaParams {
  * Returned by the `schemas.create()` method after successful upload and registration.
  * @category Schema Management
  */
-interface CreateSchemaResult {
+export interface CreateSchemaResult {
     /** The schema ID assigned by the contract */
-    schemaId: number;
+    schemaId: bigint;
     /** The IPFS URL where the schema definition is stored */
     definitionUrl: string;
     /** The transaction hash of the schema registration */
     transactionHash: string;
 }
 /**
- * Manages data schemas and refiners on the Vana network.
+ * Manages data schemas for validation and structure definition on Vana.
  *
  * @remarks
- * This controller handles the complete lifecycle of data schemas including creation,
- * validation, IPFS upload, and blockchain registration. It provides methods for managing
- * both schemas (data structure definitions) and refiners (data processing definitions).
+ * Handles schema lifecycle from creation through registration. Schemas define
+ * data structure and validation rules, ensuring consistency across the network.
+ * Stored unencrypted on IPFS for public reusability.
  *
- * **Schema Storage:**
- * Schemas are stored unencrypted on IPFS for public access and reusability across the network.
- * Schema definitions use JSON Schema format for data validation and structure definition.
+ * **Architecture:**
+ * Schemas use dual storage: definitions on IPFS (public), metadata on blockchain.
+ * Supports JSON Schema and SQLite dialects for flexible data modeling.
  *
  * **Method Selection:**
- * - `create()` validates, uploads to IPFS, and registers new schemas on blockchain
- * - `get()` retrieves existing schema metadata by ID from blockchain contracts
- * - `count()` returns total number of registered schemas for pagination
- * - `list()` provides paginated access to all schemas with optional filtering
- * - `addSchema()` provides lower-level schema registration with pre-uploaded URLs
+ * - `create()` - Validate, upload to IPFS, register on blockchain
+ * - `get()` - Retrieve schema with definition by ID
+ * - `list()` - Paginated schema browsing with metadata
+ * - `count()` - Total schemas for pagination
+ * - `addSchema()` - Low-level registration with pre-uploaded URL
  *
  * **Storage Requirements:**
- * Methods requiring storage configuration: `create()`
- * Methods working without storage: `get()`, `count()`, `list()`, `addSchema()`
+ * - Methods requiring storage: `create()`
+ * - Methods without storage: `get()`, `list()`, `count()`, `addSchema()`
  *
  * @example
  * ```typescript
- * // Create a new schema with automatic IPFS upload
+ * // Create schema with validation rules
  * const result = await vana.schemas.create({
  *   name: "User Profile",
  *   dialect: "json",
  *   schema: {
  *     type: "object",
  *     properties: {
- *       name: { type: "string" },
- *       age: { type: "number" }
+ *       name: { type: "string", minLength: 1 },
+ *       age: { type: "number", minimum: 0, maximum: 150 }
  *     },
  *     required: ["name"]
  *   }
  * });
+ * console.log(`Schema ${result.schemaId} created`);
  *
- * // Get an existing schema
- * const schema = await vana.schemas.get(1);
+ * // Retrieve for validation
+ * const schema = await vana.schemas.get(result.schemaId);
+ * console.log(`Schema: ${schema.name} (${schema.dialect})`);
  *
- * // List all schemas
- * const count = await vana.schemas.count();
+ * // Browse available schemas
+ * const schemas = await vana.schemas.list({ limit: 10 });
+ * schemas.forEach(s => console.log(`${s.id}: ${s.name}`));
  * ```
+ *
  * @category Schema Management
+ * @see For conceptual overview, visit {@link https://docs.vana.org/docs/schemas}
  */
-declare class SchemaController {
-    private readonly context;
+export declare class SchemaController extends BaseController {
     constructor(context: ControllerContext);
     /**
-     * Creates a new schema with automatic validation and IPFS upload.
+     * Creates a schema with 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.
+     * 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
      *
-     * 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
+     * @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.
      *
-     * @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" },
+     *       name: { type: "string", minLength: 1 },
      *       age: { type: "number", minimum: 0 }
      *     },
      *     required: ["name"]
      *   }
      * });
-     *
-     * console.log(`Schema created with ID: ${result.schemaId}`);
+     * console.log(`Schema ${result.schemaId} at ${result.definitionUrl}`);
      * ```
      */
     create(params: CreateSchemaParams): Promise<CreateSchemaResult>;
@@ -214,6 +197,8 @@ declare class SchemaController {
         offset?: number;
         subgraphUrl?: string;
         includeDefinitions?: boolean;
+        minBlock?: number;
+        waitForSync?: number;
     }): Promise<Schema[]>;
     /**
      * Adds a schema using the legacy method (low-level API).
@@ -222,7 +207,7 @@ declare class SchemaController {
      * @param params - Schema parameters including pre-generated definition URL
      * @returns Promise resolving to the add schema result
      */
-    addSchema(params: AddSchemaParams): Promise<AddSchemaResult>;
+    addSchema(params: AddSchemaParams): Promise<SchemaAddedResult>;
     /**
      * Internal method: Query schema via subgraph
      *
@@ -259,7 +244,6 @@ declare class SchemaController {
      * @private
      * @returns Promise resolving to the user's address
      */
-    private getUserAddress;
     /**
      * Fetches and attaches definitions to an array of schemas.
      *
@@ -268,5 +252,3 @@ declare class SchemaController {
      */
     private _fetchDefinitionsForSchemas;
 }
-
-export { type CreateSchemaParams, type CreateSchemaResult, SchemaController };

package/dist/controllers/schemas.js

@@ -1,3 +1,4 @@
+import { BaseController } from "./base";
 import { getContractAddress } from "../config/addresses";
 import { getAbi } from "../generated/abi";
 import { gasAwareMulticall } from "../utils/multicall";
@@ -16,48 +17,51 @@ import {
 } from "../generated/subgraph";
 import { print } from "graphql";
 import { fetchFromUrl, UrlResolutionError } from "../utils/urlResolver";
-class SchemaController {
+class SchemaController extends BaseController {
   constructor(context) {
-    this.context = context;
+    super(context);
   }
   /**
-   * Creates a new schema with automatic validation and IPFS upload.
+   * Creates a schema with 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.
+   * Primary method for schema creation. Validates definition,
+   * uploads to IPFS (unencrypted for reusability), and registers
+   * on blockchain. Schema becomes immediately available network-wide.
    *
-   * 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 - 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.
    *
-   * @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" },
+   *       name: { type: "string", minLength: 1 },
    *       age: { type: "number", minimum: 0 }
    *     },
    *     required: ["name"]
    *   }
    * });
-   *
-   * console.log(`Schema created with ID: ${result.schemaId}`);
+   * console.log(`Schema ${result.schemaId} at ${result.definitionUrl}`);
    * ```
    */
   async create(params) {
+    this.assertWallet();
     const { name, dialect, schema } = params;
     try {
       let schemaDefinition;
@@ -95,11 +99,9 @@ class SchemaController {
       });
       const uploadResult = await this.context.storageManager.upload(
         schemaBlob,
-        `${name.replace(/[^a-zA-Z0-9]/g, "_")}.json`,
-        "ipfs"
-        // Use IPFS for public schema storage
+        `${name.replace(/[^a-zA-Z0-9]/g, "_")}.json`
       );
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -108,27 +110,35 @@ class SchemaController {
         "DataRefinerRegistry"
       );
       const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const userAddress = await this.getUserAddress();
-      const txHash = await this.context.walletClient.writeContract({
+      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: this.context.walletClient.account || userAddress,
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient.chain ?? null
       });
-      const receipt = await this.context.publicClient.waitForTransactionReceipt(
-        {
-          hash: txHash,
-          confirmations: 1
-        }
-      );
-      const { parseSchemaAddedEvent } = await import("../utils/eventParsing");
-      const eventData = parseSchemaAddedEvent(receipt);
+      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: Number(eventData.schemaId),
+        schemaId: event.schemaId,
         definitionUrl: uploadResult.url,
-        transactionHash: txHash
+        transactionHash: hash
       };
     } catch (error) {
       if (error instanceof SchemaValidationError) {
@@ -160,7 +170,7 @@ class SchemaController {
    * ```
    */
   async get(schemaId, options = {}) {
-    const subgraphUrl = options.subgraphUrl || this.context.subgraphUrl;
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
     let metadata;
     if (subgraphUrl) {
       try {
@@ -196,13 +206,13 @@ class SchemaController {
     validateDataSchemaAgainstMetaSchema(definition);
     const dataSchema = definition;
     if (dataSchema.name !== metadata.name) {
-      throw new Error(
-        `Schema name mismatch: on-chain="${metadata.name}" off-chain="${dataSchema.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) {
-      throw new Error(
-        `Schema dialect mismatch: on-chain="${metadata.dialect}" off-chain="${dataSchema.dialect}"`
+      console.warn(
+        `Schema dialect mismatch for ID ${schemaId}: on-chain="${metadata.dialect}" off-chain="${dataSchema.dialect}" (using on-chain value)`
       );
     }
     return {
@@ -231,7 +241,7 @@ class SchemaController {
    * ```
    */
   async count(options = {}) {
-    const subgraphUrl = options.subgraphUrl || this.context.subgraphUrl;
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
     if (subgraphUrl) {
       try {
         return await this._countSchemasViaSubgraph({ subgraphUrl });
@@ -269,8 +279,18 @@ class SchemaController {
    * ```
    */
   async list(options = {}) {
-    const { limit = 100, offset = 0, includeDefinitions = false } = options;
-    const subgraphUrl = options.subgraphUrl || this.context.subgraphUrl;
+    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({
@@ -289,7 +309,7 @@ class SchemaController {
       if (end <= start) {
         return [];
       }
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -349,8 +369,9 @@ class SchemaController {
    * @returns Promise resolving to the add schema result
    */
   async addSchema(params) {
+    this.assertWallet();
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -359,26 +380,42 @@ class SchemaController {
         "DataRefinerRegistry"
       );
       const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const userAddress = await this.getUserAddress();
-      const txHash = await this.context.walletClient.writeContract({
+      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: this.context.walletClient.account || userAddress,
-        chain: this.context.walletClient.chain || null
+        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
       });
-      const receipt = await this.context.publicClient.waitForTransactionReceipt(
-        {
-          hash: txHash,
-          confirmations: 1
-        }
-      );
-      const { parseSchemaAddedEvent } = await import("../utils/eventParsing");
-      const eventData = parseSchemaAddedEvent(receipt);
       return {
-        schemaId: Number(eventData.schemaId),
-        transactionHash: txHash
+        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(
@@ -467,7 +504,7 @@ class SchemaController {
       dialect: schema.dialect,
       definitionUrl: schema.definitionUrl
     }));
-    const includeDefinitions = params.includeDefinitions;
+    const { includeDefinitions } = params;
     if (includeDefinitions) {
       await this._fetchDefinitionsForSchemas(schemas);
     }
@@ -502,7 +539,7 @@ class SchemaController {
         `Subgraph query errors: ${result.errors.map((e) => e.message).join(", ")}`
       );
     }
-    return result.data?.schemas?.length || 0;
+    return result.data?.schemas?.length ?? 0;
   }
   /**
    * Gets the user's wallet address.
@@ -510,18 +547,6 @@ class SchemaController {
    * @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.
    *