@ic-reactor/candid 3.0.7-beta.1 → 3.0.7-beta.2

package/README.md

@@ -86,6 +86,7 @@ await clientManager.initialize()
 const reactor = new CandidReactor({
   canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
   clientManager,
+  name: "my-canister",
 })
 await reactor.initialize() // Fetches IDL from network
 
@@ -93,6 +94,7 @@ await reactor.initialize() // Fetches IDL from network
 const reactor = new CandidReactor({
   canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
   clientManager,
+  name: "my-canister",
   candid: `service : {
     icrc1_name : () -> (text) query;
     icrc1_balance_of : (record { owner : principal }) -> (nat) query;
@@ -117,6 +119,7 @@ You can also register individual methods on-the-fly:
 const reactor = new CandidReactor({
   canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
   clientManager,
+  name: "my-canister",
 })
 
 // Register a method by its Candid signature
@@ -272,8 +275,9 @@ new CandidReactor(config: CandidReactorParameters)
 
 | Parameter       | Type               | Required | Description                                      |
 | --------------- | ------------------ | -------- | ------------------------------------------------ |
-| `canisterId`    | `CanisterId`       | Yes      | The canister ID to interact with                 |
+| `name`          | `string`           | Yes      | Name of the canister/reactor                     |
 | `clientManager` | `ClientManager`    | Yes      | Client manager from `@ic-reactor/core`           |
+| `canisterId`    | `CanisterId`       | No       | The canister ID (optional if using env vars)     |
 | `candid`        | `string`           | No       | Candid service definition (avoids network fetch) |
 | `idlFactory`    | `InterfaceFactory` | No       | IDL factory (if already available)               |
 | `actor`         | `A`                | No       | Existing actor instance                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/candid",
-  "version": "3.0.7-beta.1",
+  "version": "3.0.7-beta.2",
   "description": "IC Reactor Candid Adapter - Fetch and parse Candid definitions from Internet Computer canisters",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "repository": {
@@ -41,7 +42,7 @@
   "author": "Behrad Deylami",
   "license": "MIT",
   "dependencies": {
-    "@ic-reactor/core": "^3.0.7-beta.1"
+    "@ic-reactor/core": "^3.0.7-beta.2"
   },
   "peerDependencies": {
     "@icp-sdk/core": "^5.0.0"

package/src/adapter.ts

@@ -0,0 +1,446 @@
+import type { HttpAgent } from "@icp-sdk/core/agent"
+import type { Principal } from "@icp-sdk/core/principal"
+import type {
+  CandidAdapterParameters,
+  CandidDefinition,
+  CandidClientManager,
+  ReactorParser,
+} from "./types"
+
+import { CanisterStatus } from "@icp-sdk/core/agent"
+import { IDL } from "@icp-sdk/core/candid"
+import { DEFAULT_IC_DIDJS_ID, DEFAULT_LOCAL_DIDJS_ID } from "./constants"
+import { importCandidDefinition } from "./utils"
+import { CanisterId } from "@ic-reactor/core"
+
+/**
+ * CandidAdapter provides functionality to fetch and parse Candid definitions
+ * from Internet Computer canisters.
+ *
+ * It supports multiple methods for retrieving Candid definitions:
+ * 1. From canister metadata (preferred)
+ * 2. From the `__get_candid_interface_tmp_hack` method (fallback)
+ *
+ * It also supports parsing Candid to JavaScript using:
+ * 1. Local WASM parser (@ic-reactor/parser) - faster, no network request
+ * 2. Remote didjs canister - always available fallback
+ *
+ * @example
+ * ```typescript
+ * import { CandidAdapter } from "@ic-reactor/candid"
+ * import { ClientManager } from "@ic-reactor/core"
+ * import { QueryClient } from "@tanstack/query-core"
+ *
+ * const queryClient = new QueryClient()
+ * const clientManager = new ClientManager({ queryClient })
+ * await clientManager.initialize()
+ *
+ * const adapter = new CandidAdapter({ clientManager })
+ *
+ * // Optionally load the local parser for faster processing
+ * await adapter.loadParser()
+ *
+ * // Get the Candid definition for a canister
+ * const { idlFactory } = await adapter.getCandidDefinition("ryjl3-tyaaa-aaaaa-aaaba-cai")
+ * ```
+ */
+export class CandidAdapter {
+  /** The client manager providing agent and identity access. */
+  public clientManager: CandidClientManager
+
+  /** The canister ID of the didjs canister for remote Candid compilation. */
+  public didjsCanisterId: CanisterId
+
+  /** The optional local parser module. */
+  private parserModule?: ReactorParser
+
+  /** Whether parser auto-loading has been attempted. */
+  private parserLoadAttempted = false
+
+  /** Function to unsubscribe from identity updates. */
+  public unsubscribe: () => void = noop
+
+  /**
+   * Creates a new CandidAdapter instance.
+   *
+   * @param params - The adapter parameters.
+   */
+  constructor({ clientManager, didjsCanisterId }: CandidAdapterParameters) {
+    this.clientManager = clientManager
+    this.didjsCanisterId = didjsCanisterId || this.getDefaultDidJsId()
+
+    // Subscribe to identity changes to update didjs canister ID if needed
+    this.unsubscribe = clientManager.subscribe(() => {
+      if (!didjsCanisterId) {
+        this.didjsCanisterId = this.getDefaultDidJsId()
+      }
+    })
+  }
+
+  /**
+   * The HTTP agent from the client manager.
+   */
+  get agent(): HttpAgent {
+    return this.clientManager.agent
+  }
+
+  /**
+   * Whether the local parser is available.
+   */
+  get hasParser(): boolean {
+    return this.parserModule !== undefined
+  }
+
+  /**
+   * Loads the local parser module for converting Candid to JavaScript.
+   * If no module is provided, attempts to dynamically load @ic-reactor/parser.
+   *
+   * @param module - Optional parser module to use.
+   * @throws Error if the parser loading fails.
+   *
+   * @example
+   * ```typescript
+   * // Load the default parser
+   * await adapter.loadParser()
+   *
+   * // Or provide a custom parser
+   * import * as parser from "@ic-reactor/parser"
+   * await adapter.loadParser(parser)
+   * ```
+   */
+  public async loadParser(module?: ReactorParser): Promise<void> {
+    if (module !== undefined) {
+      this.parserModule = module
+      this.parserLoadAttempted = true
+      return
+    }
+
+    if (this.parserLoadAttempted) {
+      return // Already tried loading
+    }
+
+    this.parserLoadAttempted = true
+
+    try {
+      this.parserModule = require("@ic-reactor/parser")
+      if (this.parserModule?.default) {
+        await this.parserModule.default()
+      }
+    } catch (error) {
+      throw new Error(`Error loading parser: ${error}`)
+    }
+  }
+
+  /**
+   * Attempts to load the parser silently (no error if not available).
+   * Useful for optional parser initialization.
+   */
+  private async tryLoadParser(): Promise<void> {
+    if (this.parserModule || this.parserLoadAttempted) {
+      return
+    }
+
+    this.parserLoadAttempted = true
+
+    try {
+      this.parserModule = require("@ic-reactor/parser")
+      if (this.parserModule?.default) {
+        await this.parserModule.default()
+      }
+    } catch {
+      // Silently fail - parser is optional
+      this.parserModule = undefined
+    }
+  }
+
+  /**
+   * Gets the default didjs canister ID based on whether the agent is local or not.
+   */
+  private getDefaultDidJsId(): string {
+    return this.clientManager.isLocal
+      ? DEFAULT_LOCAL_DIDJS_ID
+      : DEFAULT_IC_DIDJS_ID
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // MAIN API - High-level methods for fetching Candid definitions
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Gets the parsed Candid definition for a canister, ready for use with Actor.createActor.
+   * This is the main entry point for fetching a canister's interface.
+   *
+   * @param canisterId - The canister ID to get the Candid definition for.
+   * @returns The parsed Candid definition with idlFactory and optional init.
+   * @throws Error if fetching or parsing fails.
+   *
+   * @example
+   * ```typescript
+   * const { idlFactory } = await adapter.getCandidDefinition("ryjl3-tyaaa-aaaaa-aaaba-cai")
+   * ```
+   */
+  public async getCandidDefinition(
+    canisterId: CanisterId
+  ): Promise<CandidDefinition> {
+    try {
+      const candidSource = await this.fetchCandidSource(canisterId)
+      return await this.parseCandidSource(candidSource)
+    } catch (error) {
+      throw new Error(`Error fetching canister ${canisterId}: ${error}`)
+    }
+  }
+
+  /**
+   * Fetches the raw Candid source string for a canister.
+   * First attempts to get it from metadata, then falls back to the tmp hack method.
+   *
+   * @param canisterId - The canister ID to fetch the Candid source for.
+   * @returns The raw Candid source string (.did file contents).
+   * @throws Error if both methods fail.
+   *
+   * @example
+   * ```typescript
+   * const candidSource = await adapter.fetchCandidSource("ryjl3-tyaaa-aaaaa-aaaba-cai")
+   * console.log(candidSource) // service { greet: (text) -> (text) query; }
+   * ```
+   */
+  public async fetchCandidSource(canisterId: CanisterId): Promise<string> {
+    // First attempt: Try getting Candid from metadata
+    const fromMetadata = await this.fetchFromMetadata(canisterId).catch(
+      () => undefined
+    )
+
+    if (fromMetadata) {
+      return fromMetadata
+    }
+
+    // Second attempt: Try the temporary hack method
+    const fromTmpHack = await this.fetchFromTmpHack(canisterId).catch(
+      () => undefined
+    )
+
+    if (fromTmpHack) {
+      return fromTmpHack
+    }
+
+    throw new Error("Failed to retrieve Candid source by any method.")
+  }
+
+  /**
+   * Parses Candid source string and returns the definition with idlFactory.
+   * First attempts to use the local parser, then falls back to the remote didjs canister.
+   *
+   * @param candidSource - The raw Candid source string.
+   * @returns The parsed Candid definition.
+   * @throws Error if parsing fails.
+   */
+  public async parseCandidSource(
+    candidSource: string
+  ): Promise<CandidDefinition> {
+    // Try to auto-load parser if not already loaded
+    await this.tryLoadParser()
+
+    let compiledJs: string | undefined
+
+    // First attempt: Try local parser (faster, no network)
+    if (this.parserModule) {
+      try {
+        compiledJs = this.compileLocal(candidSource)
+      } catch {
+        // Fall through to remote compilation
+      }
+    }
+
+    // Second attempt: Try remote didjs canister
+    if (!compiledJs) {
+      compiledJs = await this.compileRemote(candidSource)
+    }
+
+    if (!compiledJs) {
+      throw new Error("Failed to compile Candid to JavaScript")
+    }
+
+    return importCandidDefinition(compiledJs)
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // FETCH METHODS - Low-level methods for fetching Candid source
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Fetches Candid source from the canister's metadata.
+   *
+   * @param canisterId - The canister ID to query.
+   * @returns The Candid source string, or undefined if not available.
+   */
+  public async fetchFromMetadata(
+    canisterId: CanisterId
+  ): Promise<string | undefined> {
+    const status = await CanisterStatus.request({
+      agent: this.agent,
+      canisterId: canisterId as Principal,
+      paths: ["candid"],
+    })
+
+    return status.get("candid") as string | undefined
+  }
+
+  /**
+   * Fetches Candid source using the temporary hack method.
+   * This calls the `__get_candid_interface_tmp_hack` query method on the canister.
+   *
+   * @param canisterId - The canister ID to query.
+   * @returns The Candid source string.
+   */
+  public async fetchFromTmpHack(canisterId: CanisterId): Promise<string> {
+    const canisterIdStr =
+      typeof canisterId === "string" ? canisterId : canisterId.toString()
+
+    // Use raw agent.query instead of Actor.createActor
+    const response = await this.agent.query(canisterIdStr, {
+      methodName: "__get_candid_interface_tmp_hack",
+      arg: IDL.encode([], []),
+    })
+
+    if ("reply" in response && response.reply) {
+      const [candidSource] = IDL.decode([IDL.Text], response.reply.arg) as [
+        string,
+      ]
+      return candidSource
+    }
+
+    throw new Error(`Query failed: ${JSON.stringify(response)}`)
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // COMPILE METHODS - Methods for compiling Candid to JavaScript
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Compiles Candid source to JavaScript using the local WASM parser.
+   *
+   * @param candidSource - The Candid source to compile.
+   * @returns The compiled JavaScript code.
+   * @throws Error if the parser is not loaded.
+   */
+  public compileLocal(candidSource: string): string {
+    if (!this.parserModule) {
+      throw new Error("Parser not loaded. Call loadParser() first.")
+    }
+
+    return this.parserModule.didToJs(candidSource)
+  }
+
+  /**
+   * Compiles Candid source to JavaScript using the remote didjs canister.
+   *
+   * @param candidSource - The Candid source to compile.
+   * @param didjsCanisterId - Optional custom didjs canister ID.
+   * @returns The compiled JavaScript code, or undefined if compilation fails.
+   */
+  public async compileRemote(
+    candidSource: string,
+    didjsCanisterId?: string
+  ): Promise<string | undefined> {
+    const canisterId = didjsCanisterId || this.didjsCanisterId
+
+    // Use raw agent.query instead of Actor.createActor
+    const response = await this.agent.query(canisterId, {
+      methodName: "did_to_js",
+      arg: IDL.encode([IDL.Text], [candidSource]),
+    })
+
+    if ("reply" in response && response.reply) {
+      const [result] = IDL.decode([IDL.Opt(IDL.Text)], response.reply.arg) as [
+        [string] | [],
+      ]
+      return result[0]
+    }
+
+    throw new Error(`Query failed: ${JSON.stringify(response)}`)
+  }
+
+  /**
+   * Validates Candid source using the local parser.
+   *
+   * @param candidSource - The Candid source to validate.
+   * @returns True if the source is valid, false otherwise.
+   * @throws Error if the parser is not loaded.
+   */
+  public validateCandid(candidSource: string): boolean {
+    if (!this.parserModule) {
+      throw new Error("Parser not loaded. Call loadParser() first.")
+    }
+
+    return this.parserModule.validateIDL(candidSource)
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // DEPRECATED ALIASES - For backwards compatibility
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * @deprecated Use `loadParser()` instead.
+   */
+  public async initializeParser(module?: ReactorParser): Promise<void> {
+    return this.loadParser(module)
+  }
+
+  /**
+   * @deprecated Use `fetchCandidSource()` instead.
+   */
+  public async fetchCandidDefinition(canisterId: CanisterId): Promise<string> {
+    return this.fetchCandidSource(canisterId)
+  }
+
+  /**
+   * @deprecated Use `fetchFromMetadata()` instead.
+   */
+  public async getFromMetadata(
+    canisterId: CanisterId
+  ): Promise<string | undefined> {
+    return this.fetchFromMetadata(canisterId)
+  }
+
+  /**
+   * @deprecated Use `fetchFromTmpHack()` instead.
+   */
+  public async getFromTmpHack(canisterId: CanisterId): Promise<string> {
+    return this.fetchFromTmpHack(canisterId)
+  }
+
+  /**
+   * @deprecated Use `parseCandidSource()` instead.
+   */
+  public async evaluateCandidDefinition(
+    data: string
+  ): Promise<CandidDefinition> {
+    return this.parseCandidSource(data)
+  }
+
+  /**
+   * @deprecated Use `compileRemote()` instead.
+   */
+  public async fetchDidTojs(
+    candidSource: string,
+    didjsCanisterId?: string
+  ): Promise<string | undefined> {
+    return this.compileRemote(candidSource, didjsCanisterId)
+  }
+
+  /**
+   * @deprecated Use `compileLocal()` instead.
+   */
+  public parseDidToJs(candidSource: string): string {
+    return this.compileLocal(candidSource)
+  }
+
+  /**
+   * @deprecated Use `validateCandid()` instead.
+   */
+  public validateIDL(candidSource: string): boolean {
+    return this.validateCandid(candidSource)
+  }
+}
+
+const noop = () => {}

package/src/constants.ts

@@ -0,0 +1,11 @@
+/**
+ * Default didjs canister ID for the IC mainnet.
+ * This canister is used to compile Candid to JavaScript.
+ */
+export const DEFAULT_IC_DIDJS_ID = "a4gq6-oaaaa-aaaab-qaa4q-cai"
+
+/**
+ * Default didjs canister ID for local development.
+ * This canister is used to compile Candid to JavaScript locally.
+ */
+export const DEFAULT_LOCAL_DIDJS_ID = "bd3sg-teaaa-aaaaa-qaaba-cai"

package/src/display-reactor.ts

@@ -0,0 +1,324 @@
+import type { BaseActor, DisplayReactorParameters } from "@ic-reactor/core"
+import type {
+  CandidDisplayReactorParameters,
+  DynamicMethodOptions,
+} from "./types"
+
+import {
+  DisplayReactor,
+  didToDisplayCodec,
+  didTypeFromArray,
+} from "@ic-reactor/core"
+import { CandidAdapter } from "./adapter"
+import { IDL } from "@icp-sdk/core/candid"
+
+// ============================================================================
+// CandidDisplayReactor
+// ============================================================================
+
+/**
+ * CandidDisplayReactor combines the display transformation capabilities of
+ * DisplayReactor with dynamic Candid parsing from CandidReactor.
+ *
+ * This class provides:
+ * - **Display transformations**: Automatic type conversion between Candid and
+ *   display-friendly types (bigint ↔ string, Principal ↔ string, etc.)
+ * - **Validation**: Optional argument validation with display types
+ * - **Dynamic Candid parsing**: Initialize from Candid source or fetch from network
+ * - **Dynamic method registration**: Register methods at runtime with Candid signatures
+ *
+ * @typeParam A - The actor service type
+ *
+ * @example
+ * ```typescript
+ * import { CandidDisplayReactor } from "@ic-reactor/candid"
+ *
+ * const reactor = new CandidDisplayReactor({
+ *   clientManager,
+ *   canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+ * })
+ *
+ * // Initialize from network (fetches Candid from canister)
+ * await reactor.initialize()
+ *
+ * // Or provide Candid source directly
+ * const reactor2 = new CandidDisplayReactor({
+ *   clientManager,
+ *   canisterId: "...",
+ *   candid: `service : { greet : (text) -> (text) query }`
+ * })
+ * await reactor2.initialize()
+ *
+ * // Call methods with display types (strings instead of bigint/Principal)
+ * const result = await reactor.callMethod({
+ *   functionName: "transfer",
+ *   args: [{ to: "aaaaa-aa", amount: "1000000" }] // strings!
+ * })
+ *
+ * // Add validation
+ * reactor.registerValidator("transfer", ([input]) => {
+ *   if (!input.to) {
+ *     return { success: false, issues: [{ path: ["to"], message: "Required" }] }
+ *   }
+ *   return { success: true }
+ * })
+ * ```
+ */
+export class CandidDisplayReactor<A = BaseActor> extends DisplayReactor<A> {
+  public adapter: CandidAdapter
+  private candidSource?: string
+
+  constructor(config: CandidDisplayReactorParameters<A>) {
+    const superConfig = { ...config }
+
+    if (!superConfig.idlFactory) {
+      superConfig.idlFactory = ({ IDL }) => IDL.Service({})
+    }
+
+    super(superConfig as DisplayReactorParameters<A>)
+
+    this.candidSource = config.candid
+
+    if (config.adapter) {
+      this.adapter = config.adapter
+    } else {
+      this.adapter = new CandidAdapter({
+        clientManager: this.clientManager,
+      })
+    }
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // INITIALIZATION
+  // ══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Initializes the reactor by parsing the provided Candid string or fetching it from the network.
+   * This updates the internal service definition with the actual canister interface.
+   *
+   * After initialization, all DisplayReactor methods work with display type transformations.
+   *
+   * @example
+   * ```typescript
+   * const reactor = new CandidDisplayReactor({
+   *   clientManager,
+   *   canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+   * })
+   *
+   * // Fetches Candid from the canister and initializes
+   * await reactor.initialize()
+   *
+   * // Now you can call methods with display types
+   * const balance = await reactor.callMethod({
+   *   functionName: "icrc1_balance_of",
+   *   args: [{ owner: "aaaaa-aa" }] // Principal as string!
+   * })
+   * ```
+   */
+  public async initialize(): Promise<void> {
+    let idlFactory: IDL.InterfaceFactory
+
+    if (this.candidSource) {
+      const definition = await this.adapter.parseCandidSource(this.candidSource)
+      idlFactory = definition.idlFactory
+    } else {
+      const definition = await this.adapter.getCandidDefinition(this.canisterId)
+      idlFactory = definition.idlFactory
+    }
+
+    this.service = idlFactory({ IDL })
+
+    // Re-initialize codecs after service is updated
+    this.reinitializeCodecs()
+  }
+
+  /**
+   * Re-initialize the display codecs after the service has been updated.
+   * This is called automatically after initialize() or registerMethod().
+   */
+  private reinitializeCodecs(): void {
+    const fields = this.getServiceInterface()?._fields
+    if (!fields) return
+
+    // Access the private codecs map from DisplayReactor
+    const codecs = (this as any).codecs as Map<
+      string,
+      { args: any; result: any }
+    >
+
+    for (const [methodName, funcType] of fields) {
+      // Skip if already exists
+      if (codecs.has(methodName)) continue
+
+      const argsIdlType = didTypeFromArray(funcType.argTypes)
+      const retIdlType = didTypeFromArray(funcType.retTypes)
+
+      codecs.set(methodName, {
+        args: didToDisplayCodec(argsIdlType),
+        result: didToDisplayCodec(retIdlType),
+      })
+    }
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // DYNAMIC METHOD REGISTRATION
+  // ══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Register a dynamic method by its Candid signature.
+   * After registration, all DisplayReactor methods work with display type transformations.
+   *
+   * @example
+   * ```typescript
+   * // Register a method
+   * await reactor.registerMethod({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query"
+   * })
+   *
+   * // Now use with display types!
+   * const balance = await reactor.callMethod({
+   *   functionName: "icrc1_balance_of",
+   *   args: [{ owner: "aaaaa-aa" }] // Principal as string
+   * })
+   * // balance is string (not bigint) due to display transformation
+   * ```
+   */
+  public async registerMethod(options: DynamicMethodOptions): Promise<void> {
+    const { functionName, candid } = options
+
+    // Check if method already registered
+    const existing = this.service._fields.find(
+      ([name]) => name === functionName
+    )
+    if (existing) return
+
+    // Parse the Candid signature
+    const serviceSource = candid.includes("service :")
+      ? candid
+      : `service : { ${functionName} : ${candid}; }`
+
+    const { idlFactory } = await this.adapter.parseCandidSource(serviceSource)
+    const parsedService = idlFactory({ IDL })
+
+    const funcField = parsedService._fields.find(
+      ([name]) => name === functionName
+    )
+    if (!funcField) {
+      throw new Error(
+        `Method "${functionName}" not found in the provided Candid signature`
+      )
+    }
+
+    // Inject into our service
+    this.service._fields.push(funcField)
+
+    // Re-initialize codecs for the new method
+    this.reinitializeCodecs()
+  }
+
+  /**
+   * Register multiple methods at once.
+   *
+   * @example
+   * ```typescript
+   * await reactor.registerMethods([
+   *   { functionName: "icrc1_balance_of", candid: "(record { owner : principal }) -> (nat) query" },
+   *   { functionName: "icrc1_transfer", candid: "(record { to : principal; amount : nat }) -> (variant { Ok : nat; Err : text })" }
+   * ])
+   * ```
+   */
+  public async registerMethods(methods: DynamicMethodOptions[]): Promise<void> {
+    await Promise.all(methods.map((m) => this.registerMethod(m)))
+  }
+
+  /**
+   * Check if a method is registered (either from initialize or registerMethod).
+   */
+  public hasMethod(functionName: string): boolean {
+    return this.service._fields.some(([name]) => name === functionName)
+  }
+
+  /**
+   * Get all registered method names.
+   */
+  public getMethodNames(): string[] {
+    return this.service._fields.map(([name]) => name)
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // DYNAMIC CALL SHORTCUTS
+  // ══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Perform a dynamic update call in one step with display type transformations.
+   * Registers the method if not already registered, then calls it.
+   *
+   * @example
+   * ```typescript
+   * const result = await reactor.callDynamic({
+   *   functionName: "transfer",
+   *   candid: "(record { to : principal; amount : nat }) -> (variant { Ok : nat; Err : text })",
+   *   args: [{ to: "aaaaa-aa", amount: "100" }] // Display types!
+   * })
+   * ```
+   */
+  public async callDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.callMethod({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+
+  /**
+   * Perform a dynamic query call in one step with display type transformations.
+   * Registers the method if not already registered, then calls it.
+   *
+   * @example
+   * ```typescript
+   * const balance = await reactor.queryDynamic({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query",
+   *   args: [{ owner: "aaaaa-aa" }] // Display types!
+   * })
+   * // balance is string (not BigInt)
+   * ```
+   */
+  public async queryDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.callMethod({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+
+  /**
+   * Fetch with dynamic Candid and TanStack Query caching.
+   * Registers the method if not already registered, then fetches with caching.
+   * Results are transformed to display types.
+   *
+   * @example
+   * ```typescript
+   * const balance = await reactor.fetchQueryDynamic({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query",
+   *   args: [{ owner: "aaaaa-aa" }]
+   * })
+   * // Subsequent calls with same args return cached result
+   * ```
+   */
+  public async fetchQueryDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.fetchQuery({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { CandidAdapter } from "./adapter"
+export * from "./types"
+export * from "./constants"
+export * from "./utils"
+export * from "./reactor"
+export * from "./display-reactor"

package/src/reactor.ts

@@ -0,0 +1,199 @@
+import type { BaseActor, ReactorParameters } from "@ic-reactor/core"
+import type { CandidReactorParameters, DynamicMethodOptions } from "./types"
+
+import { Reactor } from "@ic-reactor/core"
+import { CandidAdapter } from "./adapter"
+import { IDL } from "@icp-sdk/core/candid"
+
+export class CandidReactor<A = BaseActor> extends Reactor<A> {
+  public adapter: CandidAdapter
+  private candidSource?: string
+
+  constructor(config: CandidReactorParameters) {
+    const superConfig = { ...config }
+
+    if (!superConfig.idlFactory) {
+      superConfig.idlFactory = ({ IDL }) => IDL.Service({})
+    }
+
+    super(superConfig as ReactorParameters)
+
+    this.candidSource = config.candid
+    if (config.adapter) {
+      this.adapter = config.adapter
+    } else {
+      this.adapter = new CandidAdapter({
+        clientManager: this.clientManager,
+      })
+    }
+  }
+
+  /**
+   * Initializes the reactor by parsing the provided Candid string or fetching it from the network.
+   * This updates the internal service definition with the actual canister interface.
+   *
+   * After initialization, all standard Reactor methods (callMethod, fetchQuery, etc.) work.
+   */
+  public async initialize(): Promise<void> {
+    let idlFactory: IDL.InterfaceFactory
+
+    if (this.candidSource) {
+      const definition = await this.adapter.parseCandidSource(this.candidSource)
+      idlFactory = definition.idlFactory
+    } else {
+      const definition = await this.adapter.getCandidDefinition(this.canisterId)
+      idlFactory = definition.idlFactory
+    }
+
+    this.service = idlFactory({ IDL })
+  }
+
+  /**
+   * Register a dynamic method by its Candid signature.
+   * After registration, all standard Reactor methods work with this method name.
+   *
+   * @example
+   * ```typescript
+   * // Register a method
+   * await reactor.registerMethod({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query"
+   * })
+   *
+   * // Now use standard Reactor methods!
+   * const balance = await reactor.callMethod({
+   *   functionName: "icrc1_balance_of",
+   *   args: [{ owner }]
+   * })
+   *
+   * // Or with caching
+   * const cachedBalance = await reactor.fetchQuery({
+   *   functionName: "icrc1_balance_of",
+   *   args: [{ owner }]
+   * })
+   * ```
+   */
+  public async registerMethod(options: DynamicMethodOptions): Promise<void> {
+    const { functionName, candid } = options
+
+    // Check if method already registered
+    const existing = this.service._fields.find(
+      ([name]) => name === functionName
+    )
+    if (existing) return
+
+    // Parse the Candid signature
+    const serviceSource = candid.includes("service :")
+      ? candid
+      : `service : { ${functionName} : ${candid}; }`
+
+    const { idlFactory } = await this.adapter.parseCandidSource(serviceSource)
+    const parsedService = idlFactory({ IDL })
+
+    const funcField = parsedService._fields.find(
+      ([name]) => name === functionName
+    )
+    if (!funcField) {
+      throw new Error(
+        `Method "${functionName}" not found in the provided Candid signature`
+      )
+    }
+
+    // Inject into our service
+    this.service._fields.push(funcField)
+  }
+
+  /**
+   * Register multiple methods at once.
+   */
+  public async registerMethods(methods: DynamicMethodOptions[]): Promise<void> {
+    await Promise.all(methods.map((m) => this.registerMethod(m)))
+  }
+
+  /**
+   * Check if a method is registered (either from initialize or registerMethod).
+   */
+  public hasMethod(functionName: string): boolean {
+    return this.service._fields.some(([name]) => name === functionName)
+  }
+
+  /**
+   * Get all registered method names.
+   */
+  public getMethodNames(): string[] {
+    return this.service._fields.map(([name]) => name)
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // DYNAMIC CALL SHORTCUTS
+  // ══════════════════════════════════════════════════════════════════════
+
+  /**
+   * Perform a dynamic update call in one step.
+   * Registers the method if not already registered, then calls it.
+   *
+   * @example
+   * ```typescript
+   * const result = await reactor.callDynamic({
+   *   functionName: "transfer",
+   *   candid: "(record { to : principal; amount : nat }) -> (variant { Ok : nat; Err : text })",
+   *   args: [{ to: Principal.fromText("..."), amount: 100n }]
+   * })
+   * ```
+   */
+  public async callDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.callMethod({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+
+  /**
+   * Perform a dynamic query call in one step.
+   * Registers the method if not already registered, then calls it.
+   *
+   * @example
+   * ```typescript
+   * const balance = await reactor.queryDynamic({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query",
+   *   args: [{ owner: Principal.fromText("...") }]
+   * })
+   * ```
+   */
+  public async queryDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.callMethod({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+
+  /**
+   * Fetch with dynamic Candid and TanStack Query caching.
+   * Registers the method if not already registered, then fetches with caching.
+   *
+   * @example
+   * ```typescript
+   * const balance = await reactor.fetchQueryDynamic({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query",
+   *   args: [{ owner }]
+   * })
+   * ```
+   */
+  public async fetchQueryDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.fetchQuery({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+}

package/src/types.ts

@@ -0,0 +1,107 @@
+import type { HttpAgent, Identity } from "@icp-sdk/core/agent"
+import type { IDL } from "@icp-sdk/core/candid"
+import type {
+  BaseActor,
+  CanisterId,
+  DisplayReactorParameters,
+  ReactorParameters,
+} from "@ic-reactor/core"
+import type { CandidAdapter } from "./adapter"
+
+export interface DynamicMethodOptions {
+  /** The method name to register. */
+  functionName: string
+  /**
+   * The Candid signature for the method.
+   * Can be either a method signature like "(text) -> (text) query"
+   * or a full service definition like "service : { greet: (text) -> (text) query }".
+   */
+  candid: string
+}
+
+export interface CandidReactorParameters extends Omit<
+  ReactorParameters,
+  "idlFactory"
+> {
+  /** The canister ID. */
+  canisterId?: CanisterId
+  /** The Candid source code. If not provided, the canister's Candid will be fetched. */
+  candid?: string
+  /** The IDL interface factory. */
+  idlFactory?: (IDL: any) => any
+  /** The Candid adapter. */
+  adapter?: CandidAdapter
+}
+
+// ============================================================================
+// CandidDisplayReactor Parameters
+// ============================================================================
+
+export interface CandidDisplayReactorParameters<A = BaseActor> extends Omit<
+  DisplayReactorParameters<A>,
+  "idlFactory"
+> {
+  /** The canister ID. */
+  canisterId?: CanisterId
+  /** The Candid source code. If not provided, the canister's Candid will be fetched. */
+  candid?: string
+  /** The IDL interface factory. */
+  idlFactory?: (IDL: any) => any
+  /** The Candid adapter. */
+  adapter?: CandidAdapter
+}
+
+/**
+ * Minimal interface for ClientManager that CandidAdapter depends on.
+ * This allows the candid package to work with ClientManager without importing the full core package.
+ */
+export interface CandidClientManager {
+  /** The HTTP agent used for making requests. */
+  agent: HttpAgent
+  /** Whether the agent is connected to a local network. */
+  isLocal: boolean
+  /** Subscribe to identity changes. Returns an unsubscribe function. */
+  subscribe(callback: (identity: Identity) => void): () => void
+}
+
+/**
+ * Parameters for initializing the CandidAdapter.
+ */
+export interface CandidAdapterParameters {
+  /** The client manager that provides agent and identity access. */
+  clientManager: CandidClientManager
+  /** The canister ID of the didjs canister for compiling Candid to JavaScript. */
+  didjsCanisterId?: CanisterId
+}
+
+/**
+ * Represents a parsed Candid definition with IDL factory and initialization.
+ */
+export interface CandidDefinition {
+  /** The IDL interface factory. */
+  idlFactory: IDL.InterfaceFactory
+  /** Optional init function for the canister. */
+  init?: (args: { IDL: typeof IDL }) => IDL.Type<unknown>[]
+}
+
+/**
+ * Interface for the optional parser module (@ic-reactor/parser).
+ */
+export interface ReactorParser {
+  /**
+   * Default function to initialize the WASM module.
+   */
+  default?: () => Promise<void>
+  /**
+   * Converts Candid (DID) source to JavaScript code.
+   * @param candidSource - The Candid source code.
+   * @returns The JavaScript code.
+   */
+  didToJs(candidSource: string): string
+  /**
+   * Validates the Candid (IDL) source.
+   * @param candidSource - The Candid source code.
+   * @returns True if valid, false otherwise.
+   */
+  validateIDL(candidSource: string): boolean
+}

package/src/utils.ts

@@ -0,0 +1,28 @@
+import type { CandidDefinition } from "./types"
+
+/**
+ * Imports and evaluates a Candid definition from JavaScript code.
+ *
+ * @param candidJs - The JavaScript code containing the Candid definition.
+ * @returns A promise that resolves to the CandidDefinition.
+ * @throws Error if the import fails.
+ */
+export async function importCandidDefinition(
+  candidJs: string
+): Promise<CandidDefinition> {
+  try {
+    // Create a data URL with the JavaScript code
+    const dataUri =
+      "data:text/javascript;charset=utf-8," + encodeURIComponent(candidJs)
+
+    // Dynamically import the module
+    const module = await import(/* webpackIgnore: true */ dataUri)
+
+    return {
+      idlFactory: module.idlFactory,
+      init: module.init,
+    }
+  } catch (error) {
+    throw new Error(`Failed to import Candid definition: ${error}`)
+  }
+}