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

package/dist/controllers/protocol.cjs

@@ -0,0 +1,183 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var protocol_exports = {};
+__export(protocol_exports, {
+  ProtocolController: () => ProtocolController
+});
+module.exports = __toCommonJS(protocol_exports);
+var import_errors = require("../errors");
+var import_contractController = require("../contracts/contractController");
+var import_base = require("./base");
+class ProtocolController extends import_base.BaseController {
+  contractFactory;
+  constructor(context) {
+    super(context);
+    this.contractFactory = new import_contractController.ContractFactory(
+      context.walletClient ?? context.publicClient
+    );
+  }
+  /**
+   * Retrieves the address and ABI for a specific Vana protocol contract.
+   *
+   * @remarks
+   * This method provides direct access to contract addresses and ABIs for the current
+   * chain. It includes full TypeScript type inference when using const assertions,
+   * enabling type-safe contract interactions. The method only returns contracts that
+   * are actually deployed on the current network.
+   * @param contractName - The name of the Vana contract to retrieve (use const assertion for full typing)
+   * @returns An object containing the contract's address and fully typed ABI
+   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain.
+   *   Verify contract name spelling and check current network with `getChainId()`.
+   * @example
+   * ```typescript
+   * // Get contract info with full type inference
+   * const dataRegistry = vana.protocol.getContract("DataRegistry" as const);
+   *
+   * // Now dataRegistry.abi is fully typed for the DataRegistry contract
+   * console.log(dataRegistry.address); // "0x123..."
+   * console.log(dataRegistry.abi.length); // Full ABI array
+   * ```
+   */
+  getContract(contractName) {
+    try {
+      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new import_errors.ContractNotFoundError(contractName, 0);
+      }
+      return (0, import_contractController.getContractInfo)(contractName, chainId);
+    } catch (error) {
+      if (error instanceof import_errors.ContractNotFoundError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.message.includes("Contract address not found")) {
+          let chainId = 0;
+          try {
+            chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id ?? 0;
+          } catch {
+            chainId = 0;
+          }
+          throw new import_errors.ContractNotFoundError(contractName, chainId);
+        }
+        throw error;
+      }
+      throw new Error(`Failed to get contract ${contractName}: Unknown error`);
+    }
+  }
+  /**
+   * Creates a fully typed contract instance ready for blockchain interaction.
+   *
+   * @remarks
+   * This method creates a contract instance with complete type safety for all contract
+   * methods including read operations, write operations, and event handling. The instance
+   * is pre-configured with the correct address, ABI, and wallet client for immediate use.
+   * All method parameters and return types are fully typed based on the contract ABI.
+   * @param contractName - The name of the Vana contract (use const assertion for full typing)
+   * @returns A fully typed contract instance with read/write methods and event handling
+   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain
+   * @example
+   * ```typescript
+   * // Create typed contract instance
+   * const dataRegistry = vana.protocol.createContract("DataRegistry" as const);
+   *
+   * // Full type safety for all operations
+   * const fileCount = await dataRegistry.read.filesCount(); // Type: bigint
+   * const txHash = await dataRegistry.write.addFile(["ipfs://..."]); // Typed parameters
+   *
+   * // Listen to events with full typing
+   * const logs = await dataRegistry.getEvents.FileAdded();
+   * ```
+   */
+  createContract(contractName) {
+    this.assertWallet();
+    try {
+      return (0, import_contractController.getContractController)(contractName, this.context.walletClient);
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.message.includes("Contract address not found")) {
+          const chainId = this.context.walletClient.chain?.id ?? 0;
+          throw new import_errors.ContractNotFoundError(contractName, chainId);
+        }
+        throw error;
+      }
+      throw new Error(
+        `Failed to create contract ${contractName}: Unknown error`
+      );
+    }
+  }
+  /**
+   * Gets all available contract names that can be used with getContract().
+   * Returns only contracts that are actually deployed on the current chain.
+   *
+   * @returns Array of all available contract names for the current chain
+   */
+  getAvailableContracts() {
+    return this.contractFactory.getAvailableContracts();
+  }
+  /**
+   * Checks if a specific contract is available on the current chain.
+   *
+   * @param contractName - The contract name to check
+   * @returns Whether the contract is deployed on the current chain
+   */
+  isContractAvailable(contractName) {
+    const availableContracts = this.getAvailableContracts();
+    return availableContracts.includes(contractName);
+  }
+  /**
+   * Gets the contract factory instance for advanced usage.
+   * This provides access to additional contract management methods.
+   *
+   * @returns The contract factory instance
+   */
+  getContractFactory() {
+    return this.contractFactory;
+  }
+  /**
+   * Gets the current chain ID from the wallet client.
+   *
+   * @returns The chain ID
+   * @throws {Error} When chain ID is not available from wallet client
+   */
+  getChainId() {
+    const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
+    if (!chainId) {
+      throw new Error("Chain ID not available from client");
+    }
+    return chainId;
+  }
+  /**
+   * Gets the current chain name from the wallet client.
+   *
+   * @returns The chain name
+   * @throws {Error} When chain name is not available from wallet client
+   */
+  getChainName() {
+    const chainName = this.context.walletClient?.chain?.name ?? this.context.publicClient.chain?.name;
+    if (!chainName) {
+      throw new Error("Chain name not available from client");
+    }
+    return chainName;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ProtocolController
+});
+//# sourceMappingURL=protocol.cjs.map

package/dist/controllers/protocol.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/protocol.ts"],"sourcesContent":["import type { ContractInfo, VanaChainId } from \"../types/index\";\nimport type { VanaContract, ContractAbis } from \"../generated/abi\";\nimport { ContractNotFoundError } from \"../errors\";\nimport {\n  getContractController,\n  getContractInfo,\n  ContractFactory,\n} from \"../contracts/contractController\";\nimport type { ControllerContext } from \"../types/controller-context\";\nimport type { GetContractReturnType } from \"viem\";\nimport { BaseController } from \"./base\";\n\n/**\n * Provides low-level access to Vana protocol smart contracts.\n *\n * @remarks\n * Advanced API for direct contract interaction. Most developers should use\n * higher-level controllers (DataController, PermissionsController) instead.\n * This controller serves as an escape hatch when high-level APIs lack needed\n * functionality.\n *\n * **Architecture:**\n * Automatically detects current chain and provides only deployed contracts.\n * Full TypeScript type safety through contract ABIs and const assertions.\n *\n * **Method Selection:**\n * - `getContract()` - Retrieve address and ABI for manual interaction\n * - `createContract()` - Get typed contract instance with read/write methods\n * - `getAvailableContracts()` - List all contracts on current chain\n * - `isContractAvailable()` - Check contract deployment status\n * - `getChainId()`/`getChainName()` - Current network information\n *\n * **When to Use:**\n * - Custom contract interactions not covered by high-level APIs\n * - Direct contract event listening\n * - Advanced protocol operations\n *\n * **Type Safety:**\n * Always use `as const` with contract names for full type inference.\n *\n * @example\n * ```typescript\n * // Get contract info with typed ABI\n * const registry = vana.protocol.getContract(\"DataRegistry\" as const);\n * console.log(`Contract at ${registry.address}`);\n *\n * // Create typed contract instance\n * const contract = vana.protocol.createContract(\"DataRegistry\" as const);\n * const count = await contract.read.filesCount(); // Returns: bigint\n *\n * // Write operations with full typing\n * const hash = await contract.write.addFile([\"ipfs://...\"]);\n * ```\n *\n * @category Advanced\n * @see For contract specifications, visit {@link https://docs.vana.org/docs/protocol-contracts}\n */\nexport class ProtocolController extends BaseController {\n  private readonly contractFactory: ContractFactory;\n\n  constructor(context: ControllerContext) {\n    super(context);\n    this.contractFactory = new ContractFactory(\n      context.walletClient ?? context.publicClient,\n    );\n  }\n\n  /**\n   * Retrieves the address and ABI for a specific Vana protocol contract.\n   *\n   * @remarks\n   * This method provides direct access to contract addresses and ABIs for the current\n   * chain. It includes full TypeScript type inference when using const assertions,\n   * enabling type-safe contract interactions. The method only returns contracts that\n   * are actually deployed on the current network.\n   * @param contractName - The name of the Vana contract to retrieve (use const assertion for full typing)\n   * @returns An object containing the contract's address and fully typed ABI\n   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain.\n   *   Verify contract name spelling and check current network with `getChainId()`.\n   * @example\n   * ```typescript\n   * // Get contract info with full type inference\n   * const dataRegistry = vana.protocol.getContract(\"DataRegistry\" as const);\n   *\n   * // Now dataRegistry.abi is fully typed for the DataRegistry contract\n   * console.log(dataRegistry.address); // \"0x123...\"\n   * console.log(dataRegistry.abi.length); // Full ABI array\n   * ```\n   */\n  getContract<T extends VanaContract>(\n    contractName: T,\n  ): ContractInfo<ContractAbis[T]> {\n    try {\n      const chainId =\n        this.context.walletClient?.chain?.id ??\n        this.context.publicClient.chain?.id;\n\n      if (!chainId) {\n        throw new ContractNotFoundError(contractName, 0);\n      }\n\n      return getContractInfo(contractName, chainId as VanaChainId);\n    } catch (error) {\n      if (error instanceof ContractNotFoundError) {\n        throw error;\n      }\n      if (error instanceof Error) {\n        if (error.message.includes(\"Contract address not found\")) {\n          let chainId = 0;\n          try {\n            chainId =\n              this.context.walletClient?.chain?.id ??\n              this.context.publicClient.chain?.id ??\n              0;\n          } catch {\n            // Use 0 as fallback if chain ID access fails\n            chainId = 0;\n          }\n          throw new ContractNotFoundError(contractName, chainId);\n        }\n        throw error;\n      }\n      throw new Error(`Failed to get contract ${contractName}: Unknown error`);\n    }\n  }\n\n  /**\n   * Creates a fully typed contract instance ready for blockchain interaction.\n   *\n   * @remarks\n   * This method creates a contract instance with complete type safety for all contract\n   * methods including read operations, write operations, and event handling. The instance\n   * is pre-configured with the correct address, ABI, and wallet client for immediate use.\n   * All method parameters and return types are fully typed based on the contract ABI.\n   * @param contractName - The name of the Vana contract (use const assertion for full typing)\n   * @returns A fully typed contract instance with read/write methods and event handling\n   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain\n   * @example\n   * ```typescript\n   * // Create typed contract instance\n   * const dataRegistry = vana.protocol.createContract(\"DataRegistry\" as const);\n   *\n   * // Full type safety for all operations\n   * const fileCount = await dataRegistry.read.filesCount(); // Type: bigint\n   * const txHash = await dataRegistry.write.addFile([\"ipfs://...\"]); // Typed parameters\n   *\n   * // Listen to events with full typing\n   * const logs = await dataRegistry.getEvents.FileAdded();\n   * ```\n   */\n  createContract<T extends VanaContract>(\n    contractName: T,\n  ): GetContractReturnType<ContractAbis[T]> {\n    this.assertWallet();\n    try {\n      return getContractController(contractName, this.context.walletClient);\n    } catch (error) {\n      if (error instanceof Error) {\n        if (error.message.includes(\"Contract address not found\")) {\n          const chainId = this.context.walletClient.chain?.id ?? 0;\n          throw new ContractNotFoundError(contractName, chainId);\n        }\n        throw error;\n      }\n      throw new Error(\n        `Failed to create contract ${contractName}: Unknown error`,\n      );\n    }\n  }\n\n  /**\n   * Gets all available contract names that can be used with getContract().\n   * Returns only contracts that are actually deployed on the current chain.\n   *\n   * @returns Array of all available contract names for the current chain\n   */\n  getAvailableContracts(): VanaContract[] {\n    return this.contractFactory.getAvailableContracts();\n  }\n\n  /**\n   * Checks if a specific contract is available on the current chain.\n   *\n   * @param contractName - The contract name to check\n   * @returns Whether the contract is deployed on the current chain\n   */\n  isContractAvailable(contractName: VanaContract): boolean {\n    const availableContracts = this.getAvailableContracts();\n    return availableContracts.includes(contractName);\n  }\n\n  /**\n   * Gets the contract factory instance for advanced usage.\n   * This provides access to additional contract management methods.\n   *\n   * @returns The contract factory instance\n   */\n  getContractFactory(): ContractFactory {\n    return this.contractFactory;\n  }\n\n  /**\n   * Gets the current chain ID from the wallet client.\n   *\n   * @returns The chain ID\n   * @throws {Error} When chain ID is not available from wallet client\n   */\n  getChainId(): number {\n    const chainId =\n      this.context.walletClient?.chain?.id ??\n      this.context.publicClient.chain?.id;\n    if (!chainId) {\n      throw new Error(\"Chain ID not available from client\");\n    }\n    return chainId;\n  }\n\n  /**\n   * Gets the current chain name from the wallet client.\n   *\n   * @returns The chain name\n   * @throws {Error} When chain name is not available from wallet client\n   */\n  getChainName(): string {\n    const chainName =\n      this.context.walletClient?.chain?.name ??\n      this.context.publicClient.chain?.name;\n    if (!chainName) {\n      throw new Error(\"Chain name not available from client\");\n    }\n    return chainName;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/controllers/protocol.d.ts

@@ -0,0 +1,138 @@
+import type { ContractInfo } from "../types/index";
+import type { VanaContract, ContractAbis } from "../generated/abi";
+import { ContractFactory } from "../contracts/contractController";
+import type { ControllerContext } from "../types/controller-context";
+import type { GetContractReturnType } from "viem";
+import { BaseController } from "./base";
+/**
+ * Provides low-level access to Vana protocol smart contracts.
+ *
+ * @remarks
+ * Advanced API for direct contract interaction. Most developers should use
+ * higher-level controllers (DataController, PermissionsController) instead.
+ * This controller serves as an escape hatch when high-level APIs lack needed
+ * functionality.
+ *
+ * **Architecture:**
+ * Automatically detects current chain and provides only deployed contracts.
+ * Full TypeScript type safety through contract ABIs and const assertions.
+ *
+ * **Method Selection:**
+ * - `getContract()` - Retrieve address and ABI for manual interaction
+ * - `createContract()` - Get typed contract instance with read/write methods
+ * - `getAvailableContracts()` - List all contracts on current chain
+ * - `isContractAvailable()` - Check contract deployment status
+ * - `getChainId()`/`getChainName()` - Current network information
+ *
+ * **When to Use:**
+ * - Custom contract interactions not covered by high-level APIs
+ * - Direct contract event listening
+ * - Advanced protocol operations
+ *
+ * **Type Safety:**
+ * Always use `as const` with contract names for full type inference.
+ *
+ * @example
+ * ```typescript
+ * // Get contract info with typed ABI
+ * const registry = vana.protocol.getContract("DataRegistry" as const);
+ * console.log(`Contract at ${registry.address}`);
+ *
+ * // Create typed contract instance
+ * const contract = vana.protocol.createContract("DataRegistry" as const);
+ * const count = await contract.read.filesCount(); // Returns: bigint
+ *
+ * // Write operations with full typing
+ * const hash = await contract.write.addFile(["ipfs://..."]);
+ * ```
+ *
+ * @category Advanced
+ * @see For contract specifications, visit {@link https://docs.vana.org/docs/protocol-contracts}
+ */
+export declare class ProtocolController extends BaseController {
+    private readonly contractFactory;
+    constructor(context: ControllerContext);
+    /**
+     * Retrieves the address and ABI for a specific Vana protocol contract.
+     *
+     * @remarks
+     * This method provides direct access to contract addresses and ABIs for the current
+     * chain. It includes full TypeScript type inference when using const assertions,
+     * enabling type-safe contract interactions. The method only returns contracts that
+     * are actually deployed on the current network.
+     * @param contractName - The name of the Vana contract to retrieve (use const assertion for full typing)
+     * @returns An object containing the contract's address and fully typed ABI
+     * @throws {ContractNotFoundError} When the contract is not deployed on the current chain.
+     *   Verify contract name spelling and check current network with `getChainId()`.
+     * @example
+     * ```typescript
+     * // Get contract info with full type inference
+     * const dataRegistry = vana.protocol.getContract("DataRegistry" as const);
+     *
+     * // Now dataRegistry.abi is fully typed for the DataRegistry contract
+     * console.log(dataRegistry.address); // "0x123..."
+     * console.log(dataRegistry.abi.length); // Full ABI array
+     * ```
+     */
+    getContract<T extends VanaContract>(contractName: T): ContractInfo<ContractAbis[T]>;
+    /**
+     * Creates a fully typed contract instance ready for blockchain interaction.
+     *
+     * @remarks
+     * This method creates a contract instance with complete type safety for all contract
+     * methods including read operations, write operations, and event handling. The instance
+     * is pre-configured with the correct address, ABI, and wallet client for immediate use.
+     * All method parameters and return types are fully typed based on the contract ABI.
+     * @param contractName - The name of the Vana contract (use const assertion for full typing)
+     * @returns A fully typed contract instance with read/write methods and event handling
+     * @throws {ContractNotFoundError} When the contract is not deployed on the current chain
+     * @example
+     * ```typescript
+     * // Create typed contract instance
+     * const dataRegistry = vana.protocol.createContract("DataRegistry" as const);
+     *
+     * // Full type safety for all operations
+     * const fileCount = await dataRegistry.read.filesCount(); // Type: bigint
+     * const txHash = await dataRegistry.write.addFile(["ipfs://..."]); // Typed parameters
+     *
+     * // Listen to events with full typing
+     * const logs = await dataRegistry.getEvents.FileAdded();
+     * ```
+     */
+    createContract<T extends VanaContract>(contractName: T): GetContractReturnType<ContractAbis[T]>;
+    /**
+     * Gets all available contract names that can be used with getContract().
+     * Returns only contracts that are actually deployed on the current chain.
+     *
+     * @returns Array of all available contract names for the current chain
+     */
+    getAvailableContracts(): VanaContract[];
+    /**
+     * Checks if a specific contract is available on the current chain.
+     *
+     * @param contractName - The contract name to check
+     * @returns Whether the contract is deployed on the current chain
+     */
+    isContractAvailable(contractName: VanaContract): boolean;
+    /**
+     * Gets the contract factory instance for advanced usage.
+     * This provides access to additional contract management methods.
+     *
+     * @returns The contract factory instance
+     */
+    getContractFactory(): ContractFactory;
+    /**
+     * Gets the current chain ID from the wallet client.
+     *
+     * @returns The chain ID
+     * @throws {Error} When chain ID is not available from wallet client
+     */
+    getChainId(): number;
+    /**
+     * Gets the current chain name from the wallet client.
+     *
+     * @returns The chain name
+     * @throws {Error} When chain name is not available from wallet client
+     */
+    getChainName(): string;
+}

package/dist/controllers/protocol.js

@@ -0,0 +1,163 @@
+import { ContractNotFoundError } from "../errors";
+import {
+  getContractController,
+  getContractInfo,
+  ContractFactory
+} from "../contracts/contractController";
+import { BaseController } from "./base";
+class ProtocolController extends BaseController {
+  contractFactory;
+  constructor(context) {
+    super(context);
+    this.contractFactory = new ContractFactory(
+      context.walletClient ?? context.publicClient
+    );
+  }
+  /**
+   * Retrieves the address and ABI for a specific Vana protocol contract.
+   *
+   * @remarks
+   * This method provides direct access to contract addresses and ABIs for the current
+   * chain. It includes full TypeScript type inference when using const assertions,
+   * enabling type-safe contract interactions. The method only returns contracts that
+   * are actually deployed on the current network.
+   * @param contractName - The name of the Vana contract to retrieve (use const assertion for full typing)
+   * @returns An object containing the contract's address and fully typed ABI
+   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain.
+   *   Verify contract name spelling and check current network with `getChainId()`.
+   * @example
+   * ```typescript
+   * // Get contract info with full type inference
+   * const dataRegistry = vana.protocol.getContract("DataRegistry" as const);
+   *
+   * // Now dataRegistry.abi is fully typed for the DataRegistry contract
+   * console.log(dataRegistry.address); // "0x123..."
+   * console.log(dataRegistry.abi.length); // Full ABI array
+   * ```
+   */
+  getContract(contractName) {
+    try {
+      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new ContractNotFoundError(contractName, 0);
+      }
+      return getContractInfo(contractName, chainId);
+    } catch (error) {
+      if (error instanceof ContractNotFoundError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.message.includes("Contract address not found")) {
+          let chainId = 0;
+          try {
+            chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id ?? 0;
+          } catch {
+            chainId = 0;
+          }
+          throw new ContractNotFoundError(contractName, chainId);
+        }
+        throw error;
+      }
+      throw new Error(`Failed to get contract ${contractName}: Unknown error`);
+    }
+  }
+  /**
+   * Creates a fully typed contract instance ready for blockchain interaction.
+   *
+   * @remarks
+   * This method creates a contract instance with complete type safety for all contract
+   * methods including read operations, write operations, and event handling. The instance
+   * is pre-configured with the correct address, ABI, and wallet client for immediate use.
+   * All method parameters and return types are fully typed based on the contract ABI.
+   * @param contractName - The name of the Vana contract (use const assertion for full typing)
+   * @returns A fully typed contract instance with read/write methods and event handling
+   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain
+   * @example
+   * ```typescript
+   * // Create typed contract instance
+   * const dataRegistry = vana.protocol.createContract("DataRegistry" as const);
+   *
+   * // Full type safety for all operations
+   * const fileCount = await dataRegistry.read.filesCount(); // Type: bigint
+   * const txHash = await dataRegistry.write.addFile(["ipfs://..."]); // Typed parameters
+   *
+   * // Listen to events with full typing
+   * const logs = await dataRegistry.getEvents.FileAdded();
+   * ```
+   */
+  createContract(contractName) {
+    this.assertWallet();
+    try {
+      return getContractController(contractName, this.context.walletClient);
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.message.includes("Contract address not found")) {
+          const chainId = this.context.walletClient.chain?.id ?? 0;
+          throw new ContractNotFoundError(contractName, chainId);
+        }
+        throw error;
+      }
+      throw new Error(
+        `Failed to create contract ${contractName}: Unknown error`
+      );
+    }
+  }
+  /**
+   * Gets all available contract names that can be used with getContract().
+   * Returns only contracts that are actually deployed on the current chain.
+   *
+   * @returns Array of all available contract names for the current chain
+   */
+  getAvailableContracts() {
+    return this.contractFactory.getAvailableContracts();
+  }
+  /**
+   * Checks if a specific contract is available on the current chain.
+   *
+   * @param contractName - The contract name to check
+   * @returns Whether the contract is deployed on the current chain
+   */
+  isContractAvailable(contractName) {
+    const availableContracts = this.getAvailableContracts();
+    return availableContracts.includes(contractName);
+  }
+  /**
+   * Gets the contract factory instance for advanced usage.
+   * This provides access to additional contract management methods.
+   *
+   * @returns The contract factory instance
+   */
+  getContractFactory() {
+    return this.contractFactory;
+  }
+  /**
+   * Gets the current chain ID from the wallet client.
+   *
+   * @returns The chain ID
+   * @throws {Error} When chain ID is not available from wallet client
+   */
+  getChainId() {
+    const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
+    if (!chainId) {
+      throw new Error("Chain ID not available from client");
+    }
+    return chainId;
+  }
+  /**
+   * Gets the current chain name from the wallet client.
+   *
+   * @returns The chain name
+   * @throws {Error} When chain name is not available from wallet client
+   */
+  getChainName() {
+    const chainName = this.context.walletClient?.chain?.name ?? this.context.publicClient.chain?.name;
+    if (!chainName) {
+      throw new Error("Chain name not available from client");
+    }
+    return chainName;
+  }
+}
+export {
+  ProtocolController
+};
+//# sourceMappingURL=protocol.js.map

package/dist/controllers/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/protocol.ts"],"sourcesContent":["import type { ContractInfo, VanaChainId } from \"../types/index\";\nimport type { VanaContract, ContractAbis } from \"../generated/abi\";\nimport { ContractNotFoundError } from \"../errors\";\nimport {\n  getContractController,\n  getContractInfo,\n  ContractFactory,\n} from \"../contracts/contractController\";\nimport type { ControllerContext } from \"../types/controller-context\";\nimport type { GetContractReturnType } from \"viem\";\nimport { BaseController } from \"./base\";\n\n/**\n * Provides low-level access to Vana protocol smart contracts.\n *\n * @remarks\n * Advanced API for direct contract interaction. Most developers should use\n * higher-level controllers (DataController, PermissionsController) instead.\n * This controller serves as an escape hatch when high-level APIs lack needed\n * functionality.\n *\n * **Architecture:**\n * Automatically detects current chain and provides only deployed contracts.\n * Full TypeScript type safety through contract ABIs and const assertions.\n *\n * **Method Selection:**\n * - `getContract()` - Retrieve address and ABI for manual interaction\n * - `createContract()` - Get typed contract instance with read/write methods\n * - `getAvailableContracts()` - List all contracts on current chain\n * - `isContractAvailable()` - Check contract deployment status\n * - `getChainId()`/`getChainName()` - Current network information\n *\n * **When to Use:**\n * - Custom contract interactions not covered by high-level APIs\n * - Direct contract event listening\n * - Advanced protocol operations\n *\n * **Type Safety:**\n * Always use `as const` with contract names for full type inference.\n *\n * @example\n * ```typescript\n * // Get contract info with typed ABI\n * const registry = vana.protocol.getContract(\"DataRegistry\" as const);\n * console.log(`Contract at ${registry.address}`);\n *\n * // Create typed contract instance\n * const contract = vana.protocol.createContract(\"DataRegistry\" as const);\n * const count = await contract.read.filesCount(); // Returns: bigint\n *\n * // Write operations with full typing\n * const hash = await contract.write.addFile([\"ipfs://...\"]);\n * ```\n *\n * @category Advanced\n * @see For contract specifications, visit {@link https://docs.vana.org/docs/protocol-contracts}\n */\nexport class ProtocolController extends BaseController {\n  private readonly contractFactory: ContractFactory;\n\n  constructor(context: ControllerContext) {\n    super(context);\n    this.contractFactory = new ContractFactory(\n      context.walletClient ?? context.publicClient,\n    );\n  }\n\n  /**\n   * Retrieves the address and ABI for a specific Vana protocol contract.\n   *\n   * @remarks\n   * This method provides direct access to contract addresses and ABIs for the current\n   * chain. It includes full TypeScript type inference when using const assertions,\n   * enabling type-safe contract interactions. The method only returns contracts that\n   * are actually deployed on the current network.\n   * @param contractName - The name of the Vana contract to retrieve (use const assertion for full typing)\n   * @returns An object containing the contract's address and fully typed ABI\n   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain.\n   *   Verify contract name spelling and check current network with `getChainId()`.\n   * @example\n   * ```typescript\n   * // Get contract info with full type inference\n   * const dataRegistry = vana.protocol.getContract(\"DataRegistry\" as const);\n   *\n   * // Now dataRegistry.abi is fully typed for the DataRegistry contract\n   * console.log(dataRegistry.address); // \"0x123...\"\n   * console.log(dataRegistry.abi.length); // Full ABI array\n   * ```\n   */\n  getContract<T extends VanaContract>(\n    contractName: T,\n  ): ContractInfo<ContractAbis[T]> {\n    try {\n      const chainId =\n        this.context.walletClient?.chain?.id ??\n        this.context.publicClient.chain?.id;\n\n      if (!chainId) {\n        throw new ContractNotFoundError(contractName, 0);\n      }\n\n      return getContractInfo(contractName, chainId as VanaChainId);\n    } catch (error) {\n      if (error instanceof ContractNotFoundError) {\n        throw error;\n      }\n      if (error instanceof Error) {\n        if (error.message.includes(\"Contract address not found\")) {\n          let chainId = 0;\n          try {\n            chainId =\n              this.context.walletClient?.chain?.id ??\n              this.context.publicClient.chain?.id ??\n              0;\n          } catch {\n            // Use 0 as fallback if chain ID access fails\n            chainId = 0;\n          }\n          throw new ContractNotFoundError(contractName, chainId);\n        }\n        throw error;\n      }\n      throw new Error(`Failed to get contract ${contractName}: Unknown error`);\n    }\n  }\n\n  /**\n   * Creates a fully typed contract instance ready for blockchain interaction.\n   *\n   * @remarks\n   * This method creates a contract instance with complete type safety for all contract\n   * methods including read operations, write operations, and event handling. The instance\n   * is pre-configured with the correct address, ABI, and wallet client for immediate use.\n   * All method parameters and return types are fully typed based on the contract ABI.\n   * @param contractName - The name of the Vana contract (use const assertion for full typing)\n   * @returns A fully typed contract instance with read/write methods and event handling\n   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain\n   * @example\n   * ```typescript\n   * // Create typed contract instance\n   * const dataRegistry = vana.protocol.createContract(\"DataRegistry\" as const);\n   *\n   * // Full type safety for all operations\n   * const fileCount = await dataRegistry.read.filesCount(); // Type: bigint\n   * const txHash = await dataRegistry.write.addFile([\"ipfs://...\"]); // Typed parameters\n   *\n   * // Listen to events with full typing\n   * const logs = await dataRegistry.getEvents.FileAdded();\n   * ```\n   */\n  createContract<T extends VanaContract>(\n    contractName: T,\n  ): GetContractReturnType<ContractAbis[T]> {\n    this.assertWallet();\n    try {\n      return getContractController(contractName, this.context.walletClient);\n    } catch (error) {\n      if (error instanceof Error) {\n        if (error.message.includes(\"Contract address not found\")) {\n          const chainId = this.context.walletClient.chain?.id ?? 0;\n          throw new ContractNotFoundError(contractName, chainId);\n        }\n        throw error;\n      }\n      throw new Error(\n        `Failed to create contract ${contractName}: Unknown error`,\n      );\n    }\n  }\n\n  /**\n   * Gets all available contract names that can be used with getContract().\n   * Returns only contracts that are actually deployed on the current chain.\n   *\n   * @returns Array of all available contract names for the current chain\n   */\n  getAvailableContracts(): VanaContract[] {\n    return this.contractFactory.getAvailableContracts();\n  }\n\n  /**\n   * Checks if a specific contract is available on the current chain.\n   *\n   * @param contractName - The contract name to check\n   * @returns Whether the contract is deployed on the current chain\n   */\n  isContractAvailable(contractName: VanaContract): boolean {\n    const availableContracts = this.getAvailableContracts();\n    return availableContracts.includes(contractName);\n  }\n\n  /**\n   * Gets the contract factory instance for advanced usage.\n   * This provides access to additional contract management methods.\n   *\n   * @returns The contract factory instance\n   */\n  getContractFactory(): ContractFactory {\n    return this.contractFactory;\n  }\n\n  /**\n   * Gets the current chain ID from the wallet client.\n   *\n   * @returns The chain ID\n   * @throws {Error} When chain ID is not available from wallet client\n   */\n  getChainId(): number {\n    const chainId =\n      this.context.walletClient?.chain?.id ??\n      this.context.publicClient.chain?.id;\n    if (!chainId) {\n      throw new Error(\"Chain ID not available from client\");\n    }\n    return chainId;\n  }\n\n  /**\n   * Gets the current chain name from the wallet client.\n   *\n   * @returns The chain name\n   * @throws {Error} When chain name is not available from wallet client\n   */\n  getChainName(): string {\n    const chainName =\n      this.context.walletClient?.chain?.name ??\n      this.context.publicClient.chain?.name;\n    if (!chainName) {\n      throw new Error(\"Chain name not available from client\");\n    }\n    return chainName;\n  }\n}\n"],"mappings":"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","names":[]}