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

package/dist/controllers/runtimePermissions.d.ts

@@ -0,0 +1,152 @@
+import { BaseController } from "./base";
+import type { RuntimePermissionParams, RuntimePermission, RuntimeGrantFile, RuntimePermissionResult } from "../types/runtimePermissions";
+/**
+ * Controller for VanaRuntimePermissions contract
+ *
+ * @remarks
+ * Manages permissions for data access via Vana Runtime. Allows dataset owners
+ * to create monetized access permissions for data consumers to execute operations
+ * on their datasets within TEE environments.
+ *
+ * Follows the same pattern as PermissionsController but for runtime-specific permissions.
+ *
+ * @category Controllers
+ * @example
+ * ```typescript
+ * // Create a permission for a data consumer
+ * const result = await sdk.runtimePermissions.createPermission({
+ *   datasetId: 123n,
+ *   grantee: "0x...",
+ *   task: "vanaorg/vana-task-demo:latest",
+ *   operation: "aggregate_keywords",
+ *   pricing: { price_per_file_vana: 0.1 }
+ * });
+ *
+ * console.log(`Permission created with ID: ${result.permissionId}`);
+ * console.log(`Grant stored at: ${result.grantUrl}`);
+ * ```
+ */
+export declare class RuntimePermissionsController extends BaseController {
+    /**
+     * Create a new runtime permission grant
+     *
+     * @remarks
+     * This method:
+     * 1. Creates a grant file with pricing and operation details
+     * 2. Uploads the grant to IPFS (via relayer if available)
+     * 3. Calls VanaRuntimePermissions.createPermission() on-chain
+     * 4. Waits for transaction confirmation
+     * 5. Returns the permission ID and grant URL
+     *
+     * @param params - Permission parameters including dataset, grantee, pricing
+     * @returns Permission ID, transaction hash, and grant URL
+     * @throws {BlockchainError} When permission creation fails
+     * @throws {NetworkError} When IPFS upload fails
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.runtimePermissions.createPermission({
+     *   datasetId: 123n,
+     *   grantee: "0x742d35Cc...",
+     *   task: "vanaorg/vana-task-demo:latest",
+     *   operation: "aggregate_keywords",
+     *   pricing: {
+     *     price_per_file_vana: 0.1,
+     *     minimum_price_vana: 0.01,
+     *     maximum_price_vana: 100
+     *   },
+     *   parameters: {
+     *     maxFiles: 1000
+     *   },
+     * });
+     * ```
+     */
+    createPermission(params: RuntimePermissionParams): Promise<RuntimePermissionResult>;
+    /**
+     * Get permission by ID
+     *
+     * @remarks
+     * Fetches permission details from the VanaRuntimePermissions contract.
+     * The returned permission contains an IPFS hash in the grant field,
+     * which can be resolved using fetchGrant().
+     *
+     * @param permissionId - Permission identifier
+     * @returns Permission details including dataset, grantee, and grant hash
+     *
+     * @example
+     * ```typescript
+     * const permission = await sdk.runtimePermissions.getPermission(1024n);
+     * console.log(`Dataset: ${permission.datasetId}`);
+     * console.log(`Grant: ${permission.grant}`); // IPFS hash
+     *
+     * // Resolve full grant details
+     * const grantFile = await sdk.runtimePermissions.fetchGrant(permission);
+     * console.log(`Price: ${grantFile.pricing.price_per_file_vana} VANA`);
+     * ```
+     */
+    getPermission(permissionId: bigint): Promise<RuntimePermission>;
+    /**
+     * Check if permission is active (not expired)
+     *
+     * @remarks
+     * Returns true if the current block number is between startBlock and endBlock.
+     *
+     * @param permissionId - Permission identifier
+     * @returns Whether permission is currently active
+     *
+     * @example
+     * ```typescript
+     * const isActive = await sdk.runtimePermissions.isPermissionActive(1024n);
+     * if (isActive) {
+     *   console.log("Permission is valid");
+     * } else {
+     *   console.log("Permission has expired");
+     * }
+     * ```
+     */
+    isPermissionActive(permissionId: bigint): Promise<boolean>;
+    /**
+     * Get all permissions for a dataset
+     *
+     * @remarks
+     * Returns an array of permissions that have been granted for the specified dataset.
+     * Useful for dataset owners to view all active permissions.
+     *
+     * @param datasetId - Dataset identifier
+     * @returns Array of runtime permissions
+     *
+     * @example
+     * ```typescript
+     * const permissions = await sdk.runtimePermissions.getDatasetPermissions(123n);
+     * console.log(`Found ${permissions.length} permissions`);
+     *
+     * // Access each permission directly
+     * for (const permission of permissions) {
+     *   console.log(`Permission ${permission.id}: ${permission.grant}`);
+     * }
+     * ```
+     */
+    getDatasetPermissions(datasetId: bigint): Promise<RuntimePermission[]>;
+    /**
+     * Fetch and parse grant file from IPFS
+     *
+     * @remarks
+     * Resolves the IPFS hash stored in permission.grant and returns the
+     * full grant file with pricing and operation details.
+     *
+     * @param permission - Permission with grant URL/hash
+     * @returns Parsed grant file with pricing and parameters
+     * @throws {NetworkError} When IPFS fetch fails
+     *
+     * @example
+     * ```typescript
+     * const permission = await sdk.runtimePermissions.getPermission(1024n);
+     * const grant = await sdk.runtimePermissions.fetchGrant(permission);
+     *
+     * console.log(`Task: ${grant.task}`);
+     * console.log(`Operation: ${grant.operation}`);
+     * console.log(`Price: ${grant.pricing.price_per_file_vana} VANA per file`);
+     * ```
+     */
+    fetchGrant(permission: RuntimePermission): Promise<RuntimeGrantFile>;
+}

package/dist/controllers/runtimePermissions.js

@@ -0,0 +1,251 @@
+import { getContract } from "viem";
+import { BaseController } from "./base";
+import {
+  createRuntimeGrantFile,
+  retrieveRuntimeGrantFile
+} from "../utils/runtimeGrantFiles";
+import { BlockchainError, NetworkError } from "../errors";
+import { getContractAddress } from "../generated/addresses";
+import { getAbi } from "../generated/abi";
+class RuntimePermissionsController extends BaseController {
+  /**
+   * Create a new runtime permission grant
+   *
+   * @remarks
+   * This method:
+   * 1. Creates a grant file with pricing and operation details
+   * 2. Uploads the grant to IPFS (via relayer if available)
+   * 3. Calls VanaRuntimePermissions.createPermission() on-chain
+   * 4. Waits for transaction confirmation
+   * 5. Returns the permission ID and grant URL
+   *
+   * @param params - Permission parameters including dataset, grantee, pricing
+   * @returns Permission ID, transaction hash, and grant URL
+   * @throws {BlockchainError} When permission creation fails
+   * @throws {NetworkError} When IPFS upload fails
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.runtimePermissions.createPermission({
+   *   datasetId: 123n,
+   *   grantee: "0x742d35Cc...",
+   *   task: "vanaorg/vana-task-demo:latest",
+   *   operation: "aggregate_keywords",
+   *   pricing: {
+   *     price_per_file_vana: 0.1,
+   *     minimum_price_vana: 0.01,
+   *     maximum_price_vana: 100
+   *   },
+   *   parameters: {
+   *     maxFiles: 1000
+   *   },
+   * });
+   * ```
+   */
+  async createPermission(params) {
+    this.assertWallet();
+    try {
+      const grantFile = createRuntimeGrantFile(params);
+      let grantUrl = params.grantUrl;
+      if (!grantUrl) {
+        if (!this.context.relayer) {
+          throw new NetworkError(
+            "No relayer configured and no grantUrl provided. Configure relayer or provide grantUrl parameter."
+          );
+        }
+        const request = {
+          type: "direct",
+          operation: "storeGrantFile",
+          params: grantFile
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new NetworkError(
+            `Failed to store grant file: ${response.error}`
+          );
+        }
+        if (response.type === "direct" && typeof response.result === "object" && response.result !== null && "url" in response.result && typeof response.result.url === "string") {
+          grantUrl = response.result.url;
+        } else {
+          throw new NetworkError("Upload succeeded but no URL was returned");
+        }
+      }
+      const chainId = await this.context.publicClient.getChainId();
+      const contractAddress = getContractAddress(
+        chainId,
+        "VanaRuntimePermissions"
+      );
+      const abi = getAbi("VanaRuntimePermissions");
+      const granteeId = BigInt(params.grantee);
+      const startBlock = await this.context.publicClient.getBlockNumber();
+      const endBlock = 2n ** 256n - 1n;
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const hash = await this.context.walletClient.writeContract({
+        address: contractAddress,
+        abi,
+        functionName: "createPermission",
+        args: [params.datasetId, granteeId, grantUrl, startBlock, endBlock],
+        account,
+        chain: this.context.walletClient?.chain ?? null
+      });
+      await this.context.publicClient.waitForTransactionReceipt({
+        hash
+      });
+      const permissionId = 0n;
+      return {
+        permissionId,
+        hash,
+        grantUrl
+      };
+    } catch (error) {
+      if (error instanceof NetworkError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw new BlockchainError(
+          `Failed to create runtime permission: ${error.message}`,
+          error
+        );
+      }
+      throw new BlockchainError(
+        "Failed to create runtime permission with unknown error"
+      );
+    }
+  }
+  /**
+   * Get permission by ID
+   *
+   * @remarks
+   * Fetches permission details from the VanaRuntimePermissions contract.
+   * The returned permission contains an IPFS hash in the grant field,
+   * which can be resolved using fetchGrant().
+   *
+   * @param permissionId - Permission identifier
+   * @returns Permission details including dataset, grantee, and grant hash
+   *
+   * @example
+   * ```typescript
+   * const permission = await sdk.runtimePermissions.getPermission(1024n);
+   * console.log(`Dataset: ${permission.datasetId}`);
+   * console.log(`Grant: ${permission.grant}`); // IPFS hash
+   *
+   * // Resolve full grant details
+   * const grantFile = await sdk.runtimePermissions.fetchGrant(permission);
+   * console.log(`Price: ${grantFile.pricing.price_per_file_vana} VANA`);
+   * ```
+   */
+  async getPermission(permissionId) {
+    const chainId = await this.context.publicClient.getChainId();
+    const contractAddress = getContractAddress(
+      chainId,
+      "VanaRuntimePermissions"
+    );
+    const abi = getAbi("VanaRuntimePermissions");
+    const contract = getContract({
+      address: contractAddress,
+      abi,
+      client: this.context.publicClient
+    });
+    return await contract.read.getPermission([
+      permissionId
+    ]);
+  }
+  /**
+   * Check if permission is active (not expired)
+   *
+   * @remarks
+   * Returns true if the current block number is between startBlock and endBlock.
+   *
+   * @param permissionId - Permission identifier
+   * @returns Whether permission is currently active
+   *
+   * @example
+   * ```typescript
+   * const isActive = await sdk.runtimePermissions.isPermissionActive(1024n);
+   * if (isActive) {
+   *   console.log("Permission is valid");
+   * } else {
+   *   console.log("Permission has expired");
+   * }
+   * ```
+   */
+  async isPermissionActive(permissionId) {
+    const chainId = await this.context.publicClient.getChainId();
+    const contractAddress = getContractAddress(
+      chainId,
+      "VanaRuntimePermissions"
+    );
+    const abi = getAbi("VanaRuntimePermissions");
+    const contract = getContract({
+      address: contractAddress,
+      abi,
+      client: this.context.publicClient
+    });
+    return await contract.read.isPermissionActive([permissionId]);
+  }
+  /**
+   * Get all permissions for a dataset
+   *
+   * @remarks
+   * Returns an array of permissions that have been granted for the specified dataset.
+   * Useful for dataset owners to view all active permissions.
+   *
+   * @param datasetId - Dataset identifier
+   * @returns Array of runtime permissions
+   *
+   * @example
+   * ```typescript
+   * const permissions = await sdk.runtimePermissions.getDatasetPermissions(123n);
+   * console.log(`Found ${permissions.length} permissions`);
+   *
+   * // Access each permission directly
+   * for (const permission of permissions) {
+   *   console.log(`Permission ${permission.id}: ${permission.grant}`);
+   * }
+   * ```
+   */
+  async getDatasetPermissions(datasetId) {
+    const chainId = await this.context.publicClient.getChainId();
+    const contractAddress = getContractAddress(
+      chainId,
+      "VanaRuntimePermissions"
+    );
+    const abi = getAbi("VanaRuntimePermissions");
+    const contract = getContract({
+      address: contractAddress,
+      abi,
+      client: this.context.publicClient
+    });
+    return await contract.read.getDatasetPermissions([
+      datasetId
+    ]);
+  }
+  /**
+   * Fetch and parse grant file from IPFS
+   *
+   * @remarks
+   * Resolves the IPFS hash stored in permission.grant and returns the
+   * full grant file with pricing and operation details.
+   *
+   * @param permission - Permission with grant URL/hash
+   * @returns Parsed grant file with pricing and parameters
+   * @throws {NetworkError} When IPFS fetch fails
+   *
+   * @example
+   * ```typescript
+   * const permission = await sdk.runtimePermissions.getPermission(1024n);
+   * const grant = await sdk.runtimePermissions.fetchGrant(permission);
+   *
+   * console.log(`Task: ${grant.task}`);
+   * console.log(`Operation: ${grant.operation}`);
+   * console.log(`Price: ${grant.pricing.price_per_file_vana} VANA per file`);
+   * ```
+   */
+  async fetchGrant(permission) {
+    return await retrieveRuntimeGrantFile(permission.grant);
+  }
+}
+export {
+  RuntimePermissionsController
+};
+//# sourceMappingURL=runtimePermissions.js.map

package/dist/controllers/runtimePermissions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/runtimePermissions.ts"],"sourcesContent":["import { getContract } from \"viem\";\nimport { BaseController } from \"./base\";\nimport type {\n  RuntimePermissionParams,\n  RuntimePermission,\n  RuntimeGrantFile,\n  RuntimePermissionResult,\n} from \"../types/runtimePermissions\";\nimport type { UnifiedRelayerRequest } from \"../types/relayer\";\nimport {\n  createRuntimeGrantFile,\n  retrieveRuntimeGrantFile,\n} from \"../utils/runtimeGrantFiles\";\nimport { BlockchainError, NetworkError } from \"../errors\";\nimport { getContractAddress } from \"../generated/addresses\";\nimport { getAbi } from \"../generated/abi\";\n\n/**\n * Controller for VanaRuntimePermissions contract\n *\n * @remarks\n * Manages permissions for data access via Vana Runtime. Allows dataset owners\n * to create monetized access permissions for data consumers to execute operations\n * on their datasets within TEE environments.\n *\n * Follows the same pattern as PermissionsController but for runtime-specific permissions.\n *\n * @category Controllers\n * @example\n * ```typescript\n * // Create a permission for a data consumer\n * const result = await sdk.runtimePermissions.createPermission({\n *   datasetId: 123n,\n *   grantee: \"0x...\",\n *   task: \"vanaorg/vana-task-demo:latest\",\n *   operation: \"aggregate_keywords\",\n *   pricing: { price_per_file_vana: 0.1 }\n * });\n *\n * console.log(`Permission created with ID: ${result.permissionId}`);\n * console.log(`Grant stored at: ${result.grantUrl}`);\n * ```\n */\nexport class RuntimePermissionsController extends BaseController {\n  /**\n   * Create a new runtime permission grant\n   *\n   * @remarks\n   * This method:\n   * 1. Creates a grant file with pricing and operation details\n   * 2. Uploads the grant to IPFS (via relayer if available)\n   * 3. Calls VanaRuntimePermissions.createPermission() on-chain\n   * 4. Waits for transaction confirmation\n   * 5. Returns the permission ID and grant URL\n   *\n   * @param params - Permission parameters including dataset, grantee, pricing\n   * @returns Permission ID, transaction hash, and grant URL\n   * @throws {BlockchainError} When permission creation fails\n   * @throws {NetworkError} When IPFS upload fails\n   *\n   * @example\n   * ```typescript\n   * const result = await sdk.runtimePermissions.createPermission({\n   *   datasetId: 123n,\n   *   grantee: \"0x742d35Cc...\",\n   *   task: \"vanaorg/vana-task-demo:latest\",\n   *   operation: \"aggregate_keywords\",\n   *   pricing: {\n   *     price_per_file_vana: 0.1,\n   *     minimum_price_vana: 0.01,\n   *     maximum_price_vana: 100\n   *   },\n   *   parameters: {\n   *     maxFiles: 1000\n   *   },\n   * });\n   * ```\n   */\n  async createPermission(\n    params: RuntimePermissionParams,\n  ): Promise<RuntimePermissionResult> {\n    this.assertWallet();\n\n    try {\n      // 1. Create grant file\n      const grantFile = createRuntimeGrantFile(params);\n\n      // 2. Upload to IPFS (via relayer if available, or use provided URL)\n      let grantUrl = params.grantUrl;\n      if (!grantUrl) {\n        if (!this.context.relayer) {\n          throw new NetworkError(\n            \"No relayer configured and no grantUrl provided. \" +\n              \"Configure relayer or provide grantUrl parameter.\",\n          );\n        }\n\n        // Store via relayer\n        const request: UnifiedRelayerRequest = {\n          type: \"direct\",\n          operation: \"storeGrantFile\",\n          params: grantFile,\n        };\n        const response = await this.context.relayer(request);\n        if (response.type === \"error\") {\n          throw new NetworkError(\n            `Failed to store grant file: ${response.error}`,\n          );\n        }\n        if (\n          response.type === \"direct\" &&\n          typeof response.result === \"object\" &&\n          response.result !== null &&\n          \"url\" in response.result &&\n          typeof response.result.url === \"string\"\n        ) {\n          grantUrl = response.result.url;\n        } else {\n          throw new NetworkError(\"Upload succeeded but no URL was returned\");\n        }\n      }\n\n      // 3. Get contract address and ABI\n      const chainId = await this.context.publicClient.getChainId();\n      const contractAddress = getContractAddress(\n        chainId,\n        \"VanaRuntimePermissions\",\n      );\n      const abi = getAbi(\"VanaRuntimePermissions\");\n\n      // 4. Convert grantee address to ID\n      // NOTE: For MVP, we use address as ID. In production, this should\n      // query a grantee registry contract or use a proper ID scheme.\n      const granteeId = BigInt(params.grantee);\n\n      // 5. Get current block for startBlock\n      const startBlock = await this.context.publicClient.getBlockNumber();\n\n      // 6. Set endBlock to max uint256 (never expires)\n      // Note: Unlike DataPortabilityPermissions which has no on-chain expiration,\n      // VanaRuntimePermissions contract requires endBlock. We always set it to\n      // max uint256 since we have no way to predict future block numbers from timestamps.\n      const endBlock = 2n ** 256n - 1n;\n\n      // 7. Call contract to create permission\n      const account =\n        this.context.walletClient?.account ?? this.context.userAddress;\n\n      const hash = await this.context.walletClient.writeContract({\n        address: contractAddress,\n        abi,\n        functionName: \"createPermission\",\n        args: [params.datasetId, granteeId, grantUrl, startBlock, endBlock],\n        account,\n        chain: this.context.walletClient?.chain ?? null,\n      });\n\n      // 8. Wait for transaction confirmation\n      await this.context.publicClient.waitForTransactionReceipt({\n        hash,\n      });\n\n      // 9. Parse PermissionCreated event to get permission ID\n      // For MVP, we'll use a placeholder. In production, parse event logs.\n      // TODO: Add proper event parsing from receipt.logs\n      const permissionId = 0n; // Placeholder\n\n      return {\n        permissionId,\n        hash,\n        grantUrl,\n      };\n    } catch (error) {\n      if (error instanceof NetworkError) {\n        throw error;\n      }\n      if (error instanceof Error) {\n        throw new BlockchainError(\n          `Failed to create runtime permission: ${error.message}`,\n          error,\n        );\n      }\n      throw new BlockchainError(\n        \"Failed to create runtime permission with unknown error\",\n      );\n    }\n  }\n\n  /**\n   * Get permission by ID\n   *\n   * @remarks\n   * Fetches permission details from the VanaRuntimePermissions contract.\n   * The returned permission contains an IPFS hash in the grant field,\n   * which can be resolved using fetchGrant().\n   *\n   * @param permissionId - Permission identifier\n   * @returns Permission details including dataset, grantee, and grant hash\n   *\n   * @example\n   * ```typescript\n   * const permission = await sdk.runtimePermissions.getPermission(1024n);\n   * console.log(`Dataset: ${permission.datasetId}`);\n   * console.log(`Grant: ${permission.grant}`); // IPFS hash\n   *\n   * // Resolve full grant details\n   * const grantFile = await sdk.runtimePermissions.fetchGrant(permission);\n   * console.log(`Price: ${grantFile.pricing.price_per_file_vana} VANA`);\n   * ```\n   */\n  async getPermission(permissionId: bigint): Promise<RuntimePermission> {\n    const chainId = await this.context.publicClient.getChainId();\n    const contractAddress = getContractAddress(\n      chainId,\n      \"VanaRuntimePermissions\",\n    );\n    const abi = getAbi(\"VanaRuntimePermissions\");\n\n    const contract = getContract({\n      address: contractAddress,\n      abi,\n      client: this.context.publicClient,\n    });\n\n    return (await contract.read.getPermission([\n      permissionId,\n    ])) as RuntimePermission;\n  }\n\n  /**\n   * Check if permission is active (not expired)\n   *\n   * @remarks\n   * Returns true if the current block number is between startBlock and endBlock.\n   *\n   * @param permissionId - Permission identifier\n   * @returns Whether permission is currently active\n   *\n   * @example\n   * ```typescript\n   * const isActive = await sdk.runtimePermissions.isPermissionActive(1024n);\n   * if (isActive) {\n   *   console.log(\"Permission is valid\");\n   * } else {\n   *   console.log(\"Permission has expired\");\n   * }\n   * ```\n   */\n  async isPermissionActive(permissionId: bigint): Promise<boolean> {\n    const chainId = await this.context.publicClient.getChainId();\n    const contractAddress = getContractAddress(\n      chainId,\n      \"VanaRuntimePermissions\",\n    );\n    const abi = getAbi(\"VanaRuntimePermissions\");\n\n    const contract = getContract({\n      address: contractAddress,\n      abi,\n      client: this.context.publicClient,\n    });\n\n    return (await contract.read.isPermissionActive([permissionId])) as boolean;\n  }\n\n  /**\n   * Get all permissions for a dataset\n   *\n   * @remarks\n   * Returns an array of permissions that have been granted for the specified dataset.\n   * Useful for dataset owners to view all active permissions.\n   *\n   * @param datasetId - Dataset identifier\n   * @returns Array of runtime permissions\n   *\n   * @example\n   * ```typescript\n   * const permissions = await sdk.runtimePermissions.getDatasetPermissions(123n);\n   * console.log(`Found ${permissions.length} permissions`);\n   *\n   * // Access each permission directly\n   * for (const permission of permissions) {\n   *   console.log(`Permission ${permission.id}: ${permission.grant}`);\n   * }\n   * ```\n   */\n  async getDatasetPermissions(datasetId: bigint): Promise<RuntimePermission[]> {\n    const chainId = await this.context.publicClient.getChainId();\n    const contractAddress = getContractAddress(\n      chainId,\n      \"VanaRuntimePermissions\",\n    );\n    const abi = getAbi(\"VanaRuntimePermissions\");\n\n    const contract = getContract({\n      address: contractAddress,\n      abi,\n      client: this.context.publicClient,\n    });\n\n    return (await contract.read.getDatasetPermissions([\n      datasetId,\n    ])) as RuntimePermission[];\n  }\n\n  /**\n   * Fetch and parse grant file from IPFS\n   *\n   * @remarks\n   * Resolves the IPFS hash stored in permission.grant and returns the\n   * full grant file with pricing and operation details.\n   *\n   * @param permission - Permission with grant URL/hash\n   * @returns Parsed grant file with pricing and parameters\n   * @throws {NetworkError} When IPFS fetch fails\n   *\n   * @example\n   * ```typescript\n   * const permission = await sdk.runtimePermissions.getPermission(1024n);\n   * const grant = await sdk.runtimePermissions.fetchGrant(permission);\n   *\n   * console.log(`Task: ${grant.task}`);\n   * console.log(`Operation: ${grant.operation}`);\n   * console.log(`Price: ${grant.pricing.price_per_file_vana} VANA per file`);\n   * ```\n   */\n  async fetchGrant(permission: RuntimePermission): Promise<RuntimeGrantFile> {\n    return await retrieveRuntimeGrantFile(permission.grant);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/controllers/runtimePermissions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/controllers/schemas.cjs

@@ -31,7 +31,8 @@ __export(schemas_exports, {
   SchemaController: () => SchemaController
 });
 module.exports = __toCommonJS(schemas_exports);
-var import_addresses = require("../config/addresses");
+var import_base = require("./base");
+var import_addresses = require("../generated/addresses");
 var import_abi = require("../generated/abi");
 var import_multicall = require("../utils/multicall");
 var import_schemaValidation = require("../utils/schemaValidation");
@@ -39,48 +40,51 @@ 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 {
+class SchemaController extends import_base.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;
@@ -118,11 +122,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");
       }
@@ -131,8 +133,8 @@ class SchemaController {
         "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 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,
@@ -300,8 +302,18 @@ class SchemaController {
    * ```
    */
   async list(options = {}) {
-    const { limit = 100, offset = 0, includeDefinitions = false } = 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({
@@ -320,7 +332,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");
       }
@@ -372,6 +384,75 @@ class SchemaController {
       );
     }
   }
+  /**
+   * 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).
    *
@@ -380,8 +461,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");
       }
@@ -390,8 +472,8 @@ class SchemaController {
         "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 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,
@@ -557,18 +639,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.
    *