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

package/dist/controllers/protocol.cjs

@@ -0,0 +1,179 @@
+"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");
+class ProtocolController {
+  constructor(context) {
+    this.context = context;
+    this.contractFactory = new import_contractController.ContractFactory(context.walletClient);
+  }
+  contractFactory;
+  /**
+   * 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;
+      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 ?? 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) {
+    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;
+    if (!chainId) {
+      throw new Error("Chain ID not available from wallet 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;
+    if (!chainName) {
+      throw new Error("Chain name not available from wallet 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 \"./permissions\";\nimport type { GetContractReturnType } from \"viem\";\n\n/**\n * Provides direct, low-level access to all Vana protocol smart contracts.\n *\n * @remarks\n * This controller serves as the designated \"escape hatch\" for advanced developers who need\n * to interact directly with the underlying blockchain contracts. It provides access to\n * contract addresses, ABIs, and factory methods for creating typed contract instances.\n * Most developers should use the higher-level DataController and PermissionsController\n * instead of this advanced API.\n *\n * **Contract Selection:**\n * The controller automatically handles chain detection and provides only contracts that\n * are deployed on the current network. All contract instances are fully typed for\n * enhanced developer experience and type safety.\n *\n * **Method Selection:**\n * - `getContract()` retrieves contract address and ABI for manual interaction\n * - `createContract()` returns fully typed contract instance with read/write methods\n * - `getAvailableContracts()` lists all contracts deployed on current chain\n * - `isContractAvailable()` checks if specific contract exists on current chain\n * - `getChainId()` and `getChainName()` provide current network information\n *\n * **Usage Guidelines:**\n * Use this controller when high-level controllers don't provide needed functionality.\n * Most developers should use `vana.data.*` for files and `vana.permissions.*` for access control.\n *\n * **Type Safety:**\n * Use `as const` assertion with contract names for full TypeScript type inference.\n * Contract instances provide complete typing for all methods, parameters, and return values.\n *\n * @example\n * ```typescript\n * // Get contract info for direct interaction\n * const registry = vana.protocol.getContract(\"DataRegistry\" as const);\n *\n * // Access contract address and ABI with full typing\n * console.log(registry.address); // Contract address on current chain\n * console.log(registry.abi);     // Fully typed contract ABI\n *\n * // Create a typed contract instance\n * const contract = vana.protocol.createContract(\"DataRegistry\" as const);\n * const fileCount = await contract.read.filesCount();\n * ```\n * @category Advanced\n * @see {@link https://docs.vana.com/developer/protocol/contracts | Vana Protocol Contracts} for contract specifications\n */\nexport class ProtocolController {\n  private readonly contractFactory: ContractFactory;\n\n  constructor(private readonly context: ControllerContext) {\n    this.contractFactory = new ContractFactory(context.walletClient);\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 = this.context.walletClient.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 = this.context.walletClient.chain?.id ?? 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    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 = this.context.walletClient.chain?.id;\n    if (!chainId) {\n      throw new Error(\"Chain ID not available from wallet 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 = this.context.walletClient.chain?.name;\n    if (!chainName) {\n      throw new Error(\"Chain name not available from wallet client\");\n    }\n    return chainName;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,oBAAsC;AACtC,gCAIO;AAkDA,MAAM,mBAAmB;AAAA,EAG9B,YAA6B,SAA4B;AAA5B;AAC3B,SAAK,kBAAkB,IAAI,0CAAgB,QAAQ,YAAY;AAAA,EACjE;AAAA,EAJiB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA4BjB,YACE,cAC+B;AAC/B,QAAI;AACF,YAAM,UAAU,KAAK,QAAQ,aAAa,OAAO;AAEjD,UAAI,CAAC,SAAS;AACZ,cAAM,IAAI,oCAAsB,cAAc,CAAC;AAAA,MACjD;AAEA,iBAAO,2CAAgB,cAAc,OAAsB;AAAA,IAC7D,SAAS,OAAO;AACd,UAAI,iBAAiB,qCAAuB;AAC1C,cAAM;AAAA,MACR;AACA,UAAI,iBAAiB,OAAO;AAC1B,YAAI,MAAM,QAAQ,SAAS,4BAA4B,GAAG;AACxD,cAAI,UAAU;AACd,cAAI;AACF,sBAAU,KAAK,QAAQ,aAAa,OAAO,MAAM;AAAA,UACnD,QAAQ;AAEN,sBAAU;AAAA,UACZ;AACA,gBAAM,IAAI,oCAAsB,cAAc,OAAO;AAAA,QACvD;AACA,cAAM;AAAA,MACR;AACA,YAAM,IAAI,MAAM,0BAA0B,YAAY,iBAAiB;AAAA,IACzE;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA0BA,eACE,cACwC;AACxC,QAAI;AACF,iBAAO,iDAAsB,cAAc,KAAK,QAAQ,YAAY;AAAA,IACtE,SAAS,OAAO;AACd,UAAI,iBAAiB,OAAO;AAC1B,YAAI,MAAM,QAAQ,SAAS,4BAA4B,GAAG;AACxD,gBAAM,UAAU,KAAK,QAAQ,aAAa,OAAO,MAAM;AACvD,gBAAM,IAAI,oCAAsB,cAAc,OAAO;AAAA,QACvD;AACA,cAAM;AAAA,MACR;AACA,YAAM,IAAI;AAAA,QACR,6BAA6B,YAAY;AAAA,MAC3C;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,wBAAwC;AACtC,WAAO,KAAK,gBAAgB,sBAAsB;AAAA,EACpD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,oBAAoB,cAAqC;AACvD,UAAM,qBAAqB,KAAK,sBAAsB;AACtD,WAAO,mBAAmB,SAAS,YAAY;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,qBAAsC;AACpC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,aAAqB;AACnB,UAAM,UAAU,KAAK,QAAQ,aAAa,OAAO;AACjD,QAAI,CAAC,SAAS;AACZ,YAAM,IAAI,MAAM,2CAA2C;AAAA,IAC7D;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,eAAuB;AACrB,UAAM,YAAY,KAAK,QAAQ,aAAa,OAAO;AACnD,QAAI,CAAC,WAAW;AACd,YAAM,IAAI,MAAM,6CAA6C;AAAA,IAC/D;AACA,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/controllers/protocol.d.ts

@@ -0,0 +1,139 @@
+import type { ContractInfo } from "../types/index";
+import type { VanaContract, ContractAbis } from "../generated/abi";
+import { ContractFactory } from "../contracts/contractController";
+import type { ControllerContext } from "./permissions";
+import type { GetContractReturnType } from "viem";
+/**
+ * Provides direct, low-level access to all Vana protocol smart contracts.
+ *
+ * @remarks
+ * This controller serves as the designated "escape hatch" for advanced developers who need
+ * to interact directly with the underlying blockchain contracts. It provides access to
+ * contract addresses, ABIs, and factory methods for creating typed contract instances.
+ * Most developers should use the higher-level DataController and PermissionsController
+ * instead of this advanced API.
+ *
+ * **Contract Selection:**
+ * The controller automatically handles chain detection and provides only contracts that
+ * are deployed on the current network. All contract instances are fully typed for
+ * enhanced developer experience and type safety.
+ *
+ * **Method Selection:**
+ * - `getContract()` retrieves contract address and ABI for manual interaction
+ * - `createContract()` returns fully typed contract instance with read/write methods
+ * - `getAvailableContracts()` lists all contracts deployed on current chain
+ * - `isContractAvailable()` checks if specific contract exists on current chain
+ * - `getChainId()` and `getChainName()` provide current network information
+ *
+ * **Usage Guidelines:**
+ * Use this controller when high-level controllers don't provide needed functionality.
+ * Most developers should use `vana.data.*` for files and `vana.permissions.*` for access control.
+ *
+ * **Type Safety:**
+ * Use `as const` assertion with contract names for full TypeScript type inference.
+ * Contract instances provide complete typing for all methods, parameters, and return values.
+ *
+ * @example
+ * ```typescript
+ * // Get contract info for direct interaction
+ * const registry = vana.protocol.getContract("DataRegistry" as const);
+ *
+ * // Access contract address and ABI with full typing
+ * console.log(registry.address); // Contract address on current chain
+ * console.log(registry.abi);     // Fully typed contract ABI
+ *
+ * // Create a typed contract instance
+ * const contract = vana.protocol.createContract("DataRegistry" as const);
+ * const fileCount = await contract.read.filesCount();
+ * ```
+ * @category Advanced
+ * @see {@link https://docs.vana.com/developer/protocol/contracts | Vana Protocol Contracts} for contract specifications
+ */
+export declare class ProtocolController {
+    private readonly context;
+    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,159 @@
+import { ContractNotFoundError } from "../errors";
+import {
+  getContractController,
+  getContractInfo,
+  ContractFactory
+} from "../contracts/contractController";
+class ProtocolController {
+  constructor(context) {
+    this.context = context;
+    this.contractFactory = new ContractFactory(context.walletClient);
+  }
+  contractFactory;
+  /**
+   * 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;
+      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 ?? 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) {
+    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;
+    if (!chainId) {
+      throw new Error("Chain ID not available from wallet 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;
+    if (!chainName) {
+      throw new Error("Chain name not available from wallet 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 \"./permissions\";\nimport type { GetContractReturnType } from \"viem\";\n\n/**\n * Provides direct, low-level access to all Vana protocol smart contracts.\n *\n * @remarks\n * This controller serves as the designated \"escape hatch\" for advanced developers who need\n * to interact directly with the underlying blockchain contracts. It provides access to\n * contract addresses, ABIs, and factory methods for creating typed contract instances.\n * Most developers should use the higher-level DataController and PermissionsController\n * instead of this advanced API.\n *\n * **Contract Selection:**\n * The controller automatically handles chain detection and provides only contracts that\n * are deployed on the current network. All contract instances are fully typed for\n * enhanced developer experience and type safety.\n *\n * **Method Selection:**\n * - `getContract()` retrieves contract address and ABI for manual interaction\n * - `createContract()` returns fully typed contract instance with read/write methods\n * - `getAvailableContracts()` lists all contracts deployed on current chain\n * - `isContractAvailable()` checks if specific contract exists on current chain\n * - `getChainId()` and `getChainName()` provide current network information\n *\n * **Usage Guidelines:**\n * Use this controller when high-level controllers don't provide needed functionality.\n * Most developers should use `vana.data.*` for files and `vana.permissions.*` for access control.\n *\n * **Type Safety:**\n * Use `as const` assertion with contract names for full TypeScript type inference.\n * Contract instances provide complete typing for all methods, parameters, and return values.\n *\n * @example\n * ```typescript\n * // Get contract info for direct interaction\n * const registry = vana.protocol.getContract(\"DataRegistry\" as const);\n *\n * // Access contract address and ABI with full typing\n * console.log(registry.address); // Contract address on current chain\n * console.log(registry.abi);     // Fully typed contract ABI\n *\n * // Create a typed contract instance\n * const contract = vana.protocol.createContract(\"DataRegistry\" as const);\n * const fileCount = await contract.read.filesCount();\n * ```\n * @category Advanced\n * @see {@link https://docs.vana.com/developer/protocol/contracts | Vana Protocol Contracts} for contract specifications\n */\nexport class ProtocolController {\n  private readonly contractFactory: ContractFactory;\n\n  constructor(private readonly context: ControllerContext) {\n    this.contractFactory = new ContractFactory(context.walletClient);\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 = this.context.walletClient.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 = this.context.walletClient.chain?.id ?? 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    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 = this.context.walletClient.chain?.id;\n    if (!chainId) {\n      throw new Error(\"Chain ID not available from wallet 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 = this.context.walletClient.chain?.name;\n    if (!chainName) {\n      throw new Error(\"Chain name not available from wallet client\");\n    }\n    return chainName;\n  }\n}\n"],"mappings":"AAEA,SAAS,6BAA6B;AACtC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAkDA,MAAM,mBAAmB;AAAA,EAG9B,YAA6B,SAA4B;AAA5B;AAC3B,SAAK,kBAAkB,IAAI,gBAAgB,QAAQ,YAAY;AAAA,EACjE;AAAA,EAJiB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA4BjB,YACE,cAC+B;AAC/B,QAAI;AACF,YAAM,UAAU,KAAK,QAAQ,aAAa,OAAO;AAEjD,UAAI,CAAC,SAAS;AACZ,cAAM,IAAI,sBAAsB,cAAc,CAAC;AAAA,MACjD;AAEA,aAAO,gBAAgB,cAAc,OAAsB;AAAA,IAC7D,SAAS,OAAO;AACd,UAAI,iBAAiB,uBAAuB;AAC1C,cAAM;AAAA,MACR;AACA,UAAI,iBAAiB,OAAO;AAC1B,YAAI,MAAM,QAAQ,SAAS,4BAA4B,GAAG;AACxD,cAAI,UAAU;AACd,cAAI;AACF,sBAAU,KAAK,QAAQ,aAAa,OAAO,MAAM;AAAA,UACnD,QAAQ;AAEN,sBAAU;AAAA,UACZ;AACA,gBAAM,IAAI,sBAAsB,cAAc,OAAO;AAAA,QACvD;AACA,cAAM;AAAA,MACR;AACA,YAAM,IAAI,MAAM,0BAA0B,YAAY,iBAAiB;AAAA,IACzE;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA0BA,eACE,cACwC;AACxC,QAAI;AACF,aAAO,sBAAsB,cAAc,KAAK,QAAQ,YAAY;AAAA,IACtE,SAAS,OAAO;AACd,UAAI,iBAAiB,OAAO;AAC1B,YAAI,MAAM,QAAQ,SAAS,4BAA4B,GAAG;AACxD,gBAAM,UAAU,KAAK,QAAQ,aAAa,OAAO,MAAM;AACvD,gBAAM,IAAI,sBAAsB,cAAc,OAAO;AAAA,QACvD;AACA,cAAM;AAAA,MACR;AACA,YAAM,IAAI;AAAA,QACR,6BAA6B,YAAY;AAAA,MAC3C;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,wBAAwC;AACtC,WAAO,KAAK,gBAAgB,sBAAsB;AAAA,EACpD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,oBAAoB,cAAqC;AACvD,UAAM,qBAAqB,KAAK,sBAAsB;AACtD,WAAO,mBAAmB,SAAS,YAAY;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,qBAAsC;AACpC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,aAAqB;AACnB,UAAM,UAAU,KAAK,QAAQ,aAAa,OAAO;AACjD,QAAI,CAAC,SAAS;AACZ,YAAM,IAAI,MAAM,2CAA2C;AAAA,IAC7D;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,eAAuB;AACrB,UAAM,YAAY,KAAK,QAAQ,aAAa,OAAO;AACnD,QAAI,CAAC,WAAW;AACd,YAAM,IAAI,MAAM,6CAA6C;AAAA,IAC/D;AACA,WAAO;AAAA,EACT;AACF;","names":[]}