@vocdoni/davinci-sdk 0.0.1 → 0.0.2

package/dist/index.js

@@ -402,29 +402,34 @@ function resolveUrls(options = {}) {
 }
 
 var processRegistry = {
-	sepolia: "0x40939Ec9FD872eb79A1723B559572dfD71a05d11",
+	sepolia: "0x50CA6A350f3A9C7B8a82eE7a4D5F0f21C54D68e3",
 	uzh: "0x69B16f67Bd2fB18bD720379E9C1Ef5EaD3872d67",
-	mainnet: "0x0"
+	mainnet: "0x0",
+	celo: "0xDda6c75d32c375946C8ae9be41B2F3539dB1118A"
 };
 var organizationRegistry = {
-	sepolia: "0xe7136ED5a7b0e995A8fe35d8B1B815E4160cB491",
+	sepolia: "0xF30678f579Fd89b86295503dC179d5d3aed47a98",
 	uzh: "0xf7BCE4546805547bE526Ca864d6722Ed193E51Aa",
-	mainnet: "0x0"
+	mainnet: "0x0",
+	celo: "0xE17D701EA8f34022F97fC2Ec68c73D42bF99D0BD"
 };
 var stateTransitionVerifierGroth16 = {
-	sepolia: "0xb7A142D24b9220eCBC4f7fcB89Ee952a6C7E332a",
+	sepolia: "0x96EcBbD6aB5fDC063E0fC426F2700290DeeAFE4E",
 	uzh: "0x5e4673CD378F05cc3Ae25804539c91E711548741",
-	mainnet: "0x0"
+	mainnet: "0x0",
+	celo: "0x2DaF913D423128258b2F378E320F9D9D3Be5eCf5"
 };
 var resultsVerifierGroth16 = {
-	sepolia: "0x1188cEbB56ecc90e2bAe5c914274C81Fe1a22e67",
+	sepolia: "0x3ab37C40f7d0649f7a15BA3230f14AB29B51eDCC",
 	uzh: "0x00c7F87731346F592197E49A90Ad6EC236Ad9985",
-	mainnet: "0x0"
+	mainnet: "0x0",
+	celo: "0x808276962217AD1ED3af7D51bFc791903CAd9389"
 };
 var sequencerRegistry = {
 	sepolia: "0x0",
 	uzh: "0x0",
-	mainnet: "0x0"
+	mainnet: "0x0",
+	celo: "0x0"
 };
 var addressesJson = {
 	processRegistry: processRegistry,
@@ -443,6 +448,12 @@ var TxStatus = /* @__PURE__ */ ((TxStatus2) => {
   return TxStatus2;
 })(TxStatus || {});
 class SmartContractService {
+  constructor() {
+    /** Active polling intervals for event listeners using fallback mode */
+    this.pollingIntervals = [];
+    /** Default polling interval in milliseconds for event listener fallback */
+    this.eventPollingInterval = 5e3;
+  }
   /**
    * Sends a transaction and yields status events during its lifecycle.
    * This method handles the complete transaction flow from submission to completion,
@@ -554,6 +565,141 @@ class SmartContractService {
       callback(...args);
     };
   }
+  /**
+   * Sets up an event listener with automatic fallback for RPCs that don't support eth_newFilter.
+   * First attempts to use contract.on() which relies on eth_newFilter. If the RPC doesn't support
+   * this method (error code -32601), automatically falls back to polling with queryFilter.
+   * 
+   * @template Args - Tuple type representing the event arguments
+   * @param contract - The contract instance to listen to
+   * @param eventFilter - The event filter to listen for
+   * @param callback - The callback function to invoke when the event occurs
+   * 
+   * @example
+   * ```typescript
+   * this.setupEventListener(
+   *   this.contract,
+   *   this.contract.filters.Transfer(),
+   *   (from: string, to: string, amount: bigint) => {
+   *     console.log(`Transfer: ${from} -> ${to}: ${amount}`);
+   *   }
+   * );
+   * ```
+   */
+  async setupEventListener(contract, eventFilter, callback) {
+    const normalizedCallback = this.normalizeListener(callback);
+    const provider = contract.runner?.provider;
+    if (!provider) {
+      console.warn("No provider available for event listeners");
+      return;
+    }
+    try {
+      const testFilter = {
+        address: await contract.getAddress(),
+        topics: []
+      };
+      if ("send" in provider && typeof provider.send === "function") {
+        try {
+          await provider.send("eth_newFilter", [testFilter]);
+          contract.on(eventFilter, normalizedCallback);
+          return;
+        } catch (error) {
+          if (this.isUnsupportedMethodError(error)) {
+            console.warn(
+              "RPC does not support eth_newFilter, falling back to polling for events. This may result in delayed event notifications."
+            );
+            this.setupPollingListener(contract, eventFilter, callback);
+            return;
+          }
+        }
+      }
+      const errorHandler = (error) => {
+        if (this.isUnsupportedMethodError(error)) {
+          contract.off(eventFilter, normalizedCallback);
+          contract.off("error", errorHandler);
+          console.warn(
+            "RPC does not support eth_newFilter, falling back to polling for events. This may result in delayed event notifications."
+          );
+          this.setupPollingListener(contract, eventFilter, callback);
+        }
+      };
+      contract.once("error", errorHandler);
+      contract.on(eventFilter, normalizedCallback);
+    } catch (error) {
+      console.warn("Error setting up event listener, falling back to polling:", error.message);
+      this.setupPollingListener(contract, eventFilter, callback);
+    }
+  }
+  /**
+   * Checks if an error indicates that the RPC method is unsupported (eth_newFilter).
+   * 
+   * @param error - The error to check
+   * @returns true if the error indicates unsupported method
+   */
+  isUnsupportedMethodError(error) {
+    return error?.code === -32601 || error?.error?.code === -32601 || error?.data?.code === -32601 || typeof error?.message === "string" && error.message.includes("unsupported method");
+  }
+  /**
+   * Sets up a polling-based event listener as fallback when eth_newFilter is not supported.
+   * Periodically queries for new events and invokes the callback for each new event found.
+   * 
+   * @template Args - Tuple type representing the event arguments
+   * @param contract - The contract instance to poll
+   * @param eventFilter - The event filter to poll for
+   * @param callback - The callback function to invoke for each event
+   */
+  setupPollingListener(contract, eventFilter, callback) {
+    let lastProcessedBlock = 0;
+    const poll = async () => {
+      try {
+        const provider = contract.runner?.provider;
+        if (!provider) {
+          console.warn("No provider available for polling events");
+          return;
+        }
+        const currentBlock = await provider.getBlockNumber();
+        if (lastProcessedBlock === 0) {
+          lastProcessedBlock = currentBlock - 1;
+        }
+        if (currentBlock > lastProcessedBlock) {
+          const events = await contract.queryFilter(
+            eventFilter,
+            lastProcessedBlock + 1,
+            currentBlock
+          );
+          for (const event of events) {
+            if ("args" in event && event.args) {
+              callback(...event.args);
+            }
+          }
+          lastProcessedBlock = currentBlock;
+        }
+      } catch (error) {
+        console.error("Error polling for events:", error);
+      }
+    };
+    const intervalId = setInterval(poll, this.eventPollingInterval);
+    this.pollingIntervals.push(intervalId);
+    poll();
+  }
+  /**
+   * Clears all active polling intervals.
+   * Should be called when removing all listeners or cleaning up the service.
+   */
+  clearPollingIntervals() {
+    for (const intervalId of this.pollingIntervals) {
+      clearInterval(intervalId);
+    }
+    this.pollingIntervals = [];
+  }
+  /**
+   * Sets the polling interval for event listeners using the fallback mechanism.
+   * 
+   * @param intervalMs - Polling interval in milliseconds
+   */
+  setEventPollingInterval(intervalMs) {
+    this.eventPollingInterval = intervalMs;
+  }
 }
 
 class ContractServiceError extends Error {
@@ -732,43 +878,50 @@ class ProcessRegistryService extends SmartContractService {
   }
   // ─── EVENT LISTENERS ───────────────────────────────────────────────────────
   onProcessCreated(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.ProcessCreated(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up ProcessCreated listener:", err));
   }
   onProcessStatusChanged(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.ProcessStatusChanged(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up ProcessStatusChanged listener:", err));
   }
   onCensusUpdated(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.CensusUpdated(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up CensusUpdated listener:", err));
   }
   onProcessDurationChanged(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.ProcessDurationChanged(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up ProcessDurationChanged listener:", err));
   }
   onStateRootUpdated(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.ProcessStateRootUpdated(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up StateRootUpdated listener:", err));
   }
   onProcessResultsSet(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.ProcessResultsSet(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up ProcessResultsSet listener:", err));
   }
   removeAllListeners() {
     this.contract.removeAllListeners();
+    this.clearPollingIntervals();
   }
 }
 
@@ -852,10 +1005,114 @@ class ProcessOrchestrationService {
     };
   }
   /**
-   * Creates a complete voting process with minimal configuration
-   * This method handles all the complex orchestration internally
+   * Creates a complete voting process and returns an async generator that yields transaction status events.
+   * This method allows you to monitor the transaction progress in real-time.
+   * 
+   * @param config - Process configuration
+   * @returns AsyncGenerator yielding transaction status events with ProcessCreationResult
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.createProcessStream({
+   *   title: "My Election",
+   *   description: "A simple election",
+   *   census: { ... },
+   *   ballot: { ... },
+   *   timing: { ... },
+   *   questions: [ ... ]
+   * });
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case "pending":
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case "completed":
+   *       console.log("Process created:", event.response.processId);
+   *       console.log("Transaction hash:", event.response.transactionHash);
+   *       break;
+   *     case "failed":
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case "reverted":
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *createProcessStream(config) {
+    const data = await this.prepareProcessCreation(config);
+    const encryptionKey = {
+      x: data.sequencerResult.encryptionPubKey[0],
+      y: data.sequencerResult.encryptionPubKey[1]
+    };
+    const txStream = this.processRegistry.newProcess(
+      ProcessStatus.READY,
+      data.startTime,
+      data.duration,
+      data.ballotMode,
+      data.census,
+      data.metadataUri,
+      encryptionKey,
+      BigInt(data.sequencerResult.stateRoot)
+    );
+    let transactionHash = "unknown";
+    for await (const event of txStream) {
+      if (event.status === TxStatus.Pending) {
+        transactionHash = event.hash;
+        yield { status: TxStatus.Pending, hash: event.hash };
+      } else if (event.status === TxStatus.Completed) {
+        yield {
+          status: TxStatus.Completed,
+          response: {
+            processId: data.processId,
+            transactionHash
+          }
+        };
+        break;
+      } else if (event.status === TxStatus.Failed) {
+        yield { status: TxStatus.Failed, error: event.error };
+        break;
+      } else if (event.status === TxStatus.Reverted) {
+        yield { status: TxStatus.Reverted, reason: event.reason };
+        break;
+      }
+    }
+  }
+  /**
+   * Creates a complete voting process with minimal configuration.
+   * This is the ultra-easy method for end users that handles all the complex orchestration internally.
+   * 
+   * For real-time transaction status updates, use createProcessStream() instead.
+   * 
+   * The method automatically:
+   * - Gets encryption keys and initial state root from the sequencer
+   * - Handles process creation signatures
+   * - Coordinates between sequencer API and on-chain contract calls
+   * - Creates and pushes metadata
+   * - Submits the on-chain transaction
+   * 
+   * @param config - Simplified process configuration
+   * @returns Promise resolving to the process creation result
    */
   async createProcess(config) {
+    for await (const event of this.createProcessStream(config)) {
+      if (event.status === "completed") {
+        return event.response;
+      } else if (event.status === "failed") {
+        throw event.error;
+      } else if (event.status === "reverted") {
+        throw new Error(`Transaction reverted: ${event.reason || "unknown reason"}`);
+      }
+    }
+    throw new Error("Process creation stream ended unexpectedly");
+  }
+  /**
+   * Prepares all data needed for process creation
+   * @private
+   */
+  async prepareProcessCreation(config) {
     const { startTime, duration } = this.calculateTiming(config.timing);
     const signerAddress = await this.signer.getAddress();
     const processId = await this.processRegistry.getNextProcessId(signerAddress);
@@ -878,35 +1135,15 @@ class ProcessOrchestrationService {
       censusRoot,
       censusURI: config.census.uri
     };
-    const encryptionKey = {
-      x: sequencerResult.encryptionPubKey[0],
-      y: sequencerResult.encryptionPubKey[1]
-    };
-    const txStream = this.processRegistry.newProcess(
-      ProcessStatus.READY,
+    return {
+      processId,
       startTime,
       duration,
+      censusRoot,
       ballotMode,
-      census,
       metadataUri,
-      encryptionKey,
-      BigInt(sequencerResult.stateRoot)
-    );
-    let transactionHash = "unknown";
-    for await (const event of txStream) {
-      if (event.status === "pending") {
-        transactionHash = event.hash;
-      } else if (event.status === "completed") {
-        break;
-      } else if (event.status === "failed") {
-        throw event.error;
-      } else if (event.status === "reverted") {
-        throw new Error(`Transaction reverted: ${event.reason || "unknown reason"}`);
-      }
-    }
-    return {
-      processId,
-      transactionHash
+      sequencerResult,
+      census
     };
   }
   /**
@@ -984,6 +1221,312 @@ class ProcessOrchestrationService {
     }));
     return metadata;
   }
+  /**
+   * Ends a voting process by setting its status to ENDED.
+   * Returns an async generator that yields transaction status events.
+   * 
+   * @param processId - The process ID to end
+   * @returns AsyncGenerator yielding transaction status events
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.endProcessStream("0x1234567890abcdef...");
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case "pending":
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case "completed":
+   *       console.log("Process ended successfully");
+   *       break;
+   *     case "failed":
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case "reverted":
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *endProcessStream(processId) {
+    const txStream = this.processRegistry.setProcessStatus(processId, ProcessStatus.ENDED);
+    for await (const event of txStream) {
+      if (event.status === TxStatus.Pending) {
+        yield { status: TxStatus.Pending, hash: event.hash };
+      } else if (event.status === TxStatus.Completed) {
+        yield {
+          status: TxStatus.Completed,
+          response: { success: true }
+        };
+        break;
+      } else if (event.status === TxStatus.Failed) {
+        yield { status: TxStatus.Failed, error: event.error };
+        break;
+      } else if (event.status === TxStatus.Reverted) {
+        yield { status: TxStatus.Reverted, reason: event.reason };
+        break;
+      }
+    }
+  }
+  /**
+   * Ends a voting process by setting its status to ENDED.
+   * This is a simplified method that waits for transaction completion.
+   * 
+   * For real-time transaction status updates, use endProcessStream() instead.
+   * 
+   * @param processId - The process ID to end
+   * @returns Promise resolving when the process is ended
+   * 
+   * @example
+   * ```typescript
+   * await sdk.endProcess("0x1234567890abcdef...");
+   * console.log("Process ended successfully");
+   * ```
+   */
+  async endProcess(processId) {
+    for await (const event of this.endProcessStream(processId)) {
+      if (event.status === "completed") {
+        return;
+      } else if (event.status === "failed") {
+        throw event.error;
+      } else if (event.status === "reverted") {
+        throw new Error(`Transaction reverted: ${event.reason || "unknown reason"}`);
+      }
+    }
+    throw new Error("End process stream ended unexpectedly");
+  }
+  /**
+   * Pauses a voting process by setting its status to PAUSED.
+   * Returns an async generator that yields transaction status events.
+   * 
+   * @param processId - The process ID to pause
+   * @returns AsyncGenerator yielding transaction status events
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.pauseProcessStream("0x1234567890abcdef...");
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case "pending":
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case "completed":
+   *       console.log("Process paused successfully");
+   *       break;
+   *     case "failed":
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case "reverted":
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *pauseProcessStream(processId) {
+    const txStream = this.processRegistry.setProcessStatus(processId, ProcessStatus.PAUSED);
+    for await (const event of txStream) {
+      if (event.status === TxStatus.Pending) {
+        yield { status: TxStatus.Pending, hash: event.hash };
+      } else if (event.status === TxStatus.Completed) {
+        yield {
+          status: TxStatus.Completed,
+          response: { success: true }
+        };
+        break;
+      } else if (event.status === TxStatus.Failed) {
+        yield { status: TxStatus.Failed, error: event.error };
+        break;
+      } else if (event.status === TxStatus.Reverted) {
+        yield { status: TxStatus.Reverted, reason: event.reason };
+        break;
+      }
+    }
+  }
+  /**
+   * Pauses a voting process by setting its status to PAUSED.
+   * This is a simplified method that waits for transaction completion.
+   * 
+   * For real-time transaction status updates, use pauseProcessStream() instead.
+   * 
+   * @param processId - The process ID to pause
+   * @returns Promise resolving when the process is paused
+   * 
+   * @example
+   * ```typescript
+   * await sdk.pauseProcess("0x1234567890abcdef...");
+   * console.log("Process paused successfully");
+   * ```
+   */
+  async pauseProcess(processId) {
+    for await (const event of this.pauseProcessStream(processId)) {
+      if (event.status === "completed") {
+        return;
+      } else if (event.status === "failed") {
+        throw event.error;
+      } else if (event.status === "reverted") {
+        throw new Error(`Transaction reverted: ${event.reason || "unknown reason"}`);
+      }
+    }
+    throw new Error("Pause process stream ended unexpectedly");
+  }
+  /**
+   * Cancels a voting process by setting its status to CANCELED.
+   * Returns an async generator that yields transaction status events.
+   * 
+   * @param processId - The process ID to cancel
+   * @returns AsyncGenerator yielding transaction status events
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.cancelProcessStream("0x1234567890abcdef...");
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case "pending":
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case "completed":
+   *       console.log("Process canceled successfully");
+   *       break;
+   *     case "failed":
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case "reverted":
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *cancelProcessStream(processId) {
+    const txStream = this.processRegistry.setProcessStatus(processId, ProcessStatus.CANCELED);
+    for await (const event of txStream) {
+      if (event.status === TxStatus.Pending) {
+        yield { status: TxStatus.Pending, hash: event.hash };
+      } else if (event.status === TxStatus.Completed) {
+        yield {
+          status: TxStatus.Completed,
+          response: { success: true }
+        };
+        break;
+      } else if (event.status === TxStatus.Failed) {
+        yield { status: TxStatus.Failed, error: event.error };
+        break;
+      } else if (event.status === TxStatus.Reverted) {
+        yield { status: TxStatus.Reverted, reason: event.reason };
+        break;
+      }
+    }
+  }
+  /**
+   * Cancels a voting process by setting its status to CANCELED.
+   * This is a simplified method that waits for transaction completion.
+   * 
+   * For real-time transaction status updates, use cancelProcessStream() instead.
+   * 
+   * @param processId - The process ID to cancel
+   * @returns Promise resolving when the process is canceled
+   * 
+   * @example
+   * ```typescript
+   * await sdk.cancelProcess("0x1234567890abcdef...");
+   * console.log("Process canceled successfully");
+   * ```
+   */
+  async cancelProcess(processId) {
+    for await (const event of this.cancelProcessStream(processId)) {
+      if (event.status === "completed") {
+        return;
+      } else if (event.status === "failed") {
+        throw event.error;
+      } else if (event.status === "reverted") {
+        throw new Error(`Transaction reverted: ${event.reason || "unknown reason"}`);
+      }
+    }
+    throw new Error("Cancel process stream ended unexpectedly");
+  }
+  /**
+   * Resumes a voting process by setting its status to READY.
+   * This is typically used to resume a paused process.
+   * Returns an async generator that yields transaction status events.
+   * 
+   * @param processId - The process ID to resume
+   * @returns AsyncGenerator yielding transaction status events
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.resumeProcessStream("0x1234567890abcdef...");
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case "pending":
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case "completed":
+   *       console.log("Process resumed successfully");
+   *       break;
+   *     case "failed":
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case "reverted":
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *resumeProcessStream(processId) {
+    const txStream = this.processRegistry.setProcessStatus(processId, ProcessStatus.READY);
+    for await (const event of txStream) {
+      if (event.status === TxStatus.Pending) {
+        yield { status: TxStatus.Pending, hash: event.hash };
+      } else if (event.status === TxStatus.Completed) {
+        yield {
+          status: TxStatus.Completed,
+          response: { success: true }
+        };
+        break;
+      } else if (event.status === TxStatus.Failed) {
+        yield { status: TxStatus.Failed, error: event.error };
+        break;
+      } else if (event.status === TxStatus.Reverted) {
+        yield { status: TxStatus.Reverted, reason: event.reason };
+        break;
+      }
+    }
+  }
+  /**
+   * Resumes a voting process by setting its status to READY.
+   * This is typically used to resume a paused process.
+   * This is a simplified method that waits for transaction completion.
+   * 
+   * For real-time transaction status updates, use resumeProcessStream() instead.
+   * 
+   * @param processId - The process ID to resume
+   * @returns Promise resolving when the process is resumed
+   * 
+   * @example
+   * ```typescript
+   * await sdk.resumeProcess("0x1234567890abcdef...");
+   * console.log("Process resumed successfully");
+   * ```
+   */
+  async resumeProcess(processId) {
+    for await (const event of this.resumeProcessStream(processId)) {
+      if (event.status === "completed") {
+        return;
+      } else if (event.status === "failed") {
+        throw event.error;
+      } else if (event.status === "reverted") {
+        throw new Error(`Transaction reverted: ${event.reason || "unknown reason"}`);
+      }
+    }
+    throw new Error("Resume process stream ended unexpectedly");
+  }
 }
 
 class CircomProof {
@@ -1173,11 +1716,61 @@ class VoteOrchestrationService {
    * @param address - The voter's address
    * @returns Promise resolving to boolean indicating if the address has voted
    */
-  async hasAddressVoted(processId, address) {
-    return this.apiService.sequencer.hasAddressVoted(processId, address);
+  async hasAddressVoted(processId, address) {
+    return this.apiService.sequencer.hasAddressVoted(processId, address);
+  }
+  /**
+   * Watch vote status changes in real-time using an async generator.
+   * Yields each status change as it happens, allowing for reactive UI updates.
+   * 
+   * @param processId - The process ID
+   * @param voteId - The vote ID
+   * @param options - Optional configuration
+   * @returns AsyncGenerator yielding vote status updates
+   * 
+   * @example
+   * ```typescript
+   * const vote = await sdk.submitVote({ processId, choices: [1] });
+   * 
+   * for await (const statusInfo of sdk.watchVoteStatus(vote.processId, vote.voteId)) {
+   *   console.log(`Vote status: ${statusInfo.status}`);
+   *   
+   *   switch (statusInfo.status) {
+   *     case VoteStatus.Pending:
+   *       console.log("⏳ Processing...");
+   *       break;
+   *     case VoteStatus.Verified:
+   *       console.log("✓ Verified");
+   *       break;
+   *     case VoteStatus.Settled:
+   *       console.log("✅ Settled");
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *watchVoteStatus(processId, voteId, options) {
+    const targetStatus = options?.targetStatus ?? VoteStatus.Settled;
+    const timeoutMs = options?.timeoutMs ?? 3e5;
+    const pollIntervalMs = options?.pollIntervalMs ?? 5e3;
+    const startTime = Date.now();
+    let previousStatus = null;
+    while (Date.now() - startTime < timeoutMs) {
+      const statusInfo = await this.getVoteStatus(processId, voteId);
+      if (statusInfo.status !== previousStatus) {
+        previousStatus = statusInfo.status;
+        yield statusInfo;
+        if (statusInfo.status === targetStatus || statusInfo.status === VoteStatus.Error) {
+          return;
+        }
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error(`Vote did not reach status ${targetStatus} within ${timeoutMs}ms`);
   }
   /**
-   * Wait for a vote to reach a specific status
+   * Wait for a vote to reach a specific status.
+   * This is a simpler alternative to watchVoteStatus() that returns only the final status.
    * 
    * @param processId - The process ID
    * @param voteId - The vote ID
@@ -1187,15 +1780,18 @@ class VoteOrchestrationService {
    * @returns Promise resolving to final vote status
    */
   async waitForVoteStatus(processId, voteId, targetStatus = VoteStatus.Settled, timeoutMs = 3e5, pollIntervalMs = 5e3) {
-    const startTime = Date.now();
-    while (Date.now() - startTime < timeoutMs) {
-      const statusInfo = await this.getVoteStatus(processId, voteId);
-      if (statusInfo.status === targetStatus || statusInfo.status === VoteStatus.Error) {
-        return statusInfo;
-      }
-      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    let finalStatus = null;
+    for await (const statusInfo of this.watchVoteStatus(processId, voteId, {
+      targetStatus,
+      timeoutMs,
+      pollIntervalMs
+    })) {
+      finalStatus = statusInfo;
     }
-    throw new Error(`Vote did not reach status ${targetStatus} within ${timeoutMs}ms`);
+    if (!finalStatus) {
+      throw new Error(`Vote did not reach status ${targetStatus} within ${timeoutMs}ms`);
+    }
+    return finalStatus;
   }
   /**
    * Get census proof based on census origin type
@@ -1384,31 +1980,36 @@ class OrganizationRegistryService extends SmartContractService {
   }
   // ─── EVENT LISTENERS ───────────────────────────────────────────────────────
   onOrganizationCreated(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.OrganizationCreated(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up OrganizationCreated listener:", err));
   }
   onOrganizationUpdated(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.OrganizationUpdated(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up OrganizationUpdated listener:", err));
   }
   onAdministratorAdded(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.AdministratorAdded(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up AdministratorAdded listener:", err));
   }
   onAdministratorRemoved(cb) {
-    this.contract.on(
+    this.setupEventListener(
+      this.contract,
       this.contract.filters.AdministratorRemoved(),
-      this.normalizeListener(cb)
-    );
+      cb
+    ).catch((err) => console.error("Error setting up AdministratorRemoved listener:", err));
   }
   removeAllListeners() {
     this.contract.removeAllListeners();
+    this.clearPollingIntervals();
   }
 }
 
@@ -1635,9 +2236,13 @@ class DavinciSDK {
     return this.apiService;
   }
   /**
-   * Get the process registry service for process management
+   * Get the process registry service for process management.
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @throws Error if signer does not have a provider
    */
   get processes() {
+    this.ensureProvider();
     if (!this._processRegistry) {
       const processRegistryAddress = this.resolveContractAddress("processRegistry");
       this._processRegistry = new ProcessRegistryService(processRegistryAddress, this.config.signer);
@@ -1645,9 +2250,13 @@ class DavinciSDK {
     return this._processRegistry;
   }
   /**
-   * Get the organization registry service for organization management
+   * Get the organization registry service for organization management.
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @throws Error if signer does not have a provider
    */
   get organizations() {
+    this.ensureProvider();
     if (!this._organizationRegistry) {
       const organizationRegistryAddress = this.resolveContractAddress("organizationRegistry");
       this._organizationRegistry = new OrganizationRegistryService(organizationRegistryAddress, this.config.signer);
@@ -1669,9 +2278,13 @@ class DavinciSDK {
     return this.davinciCrypto;
   }
   /**
-   * Get the process orchestration service for simplified process creation
+   * Get the process orchestration service for simplified process creation.
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @throws Error if signer does not have a provider
    */
   get processOrchestrator() {
+    this.ensureProvider();
     if (!this._processOrchestrator) {
       this._processOrchestrator = new ProcessOrchestrationService(
         this.processes,
@@ -1702,8 +2315,11 @@ class DavinciSDK {
    * This method fetches raw contract data and transforms it into a user-friendly format
    * that matches the ProcessConfig interface used for creation, plus additional runtime data.
    * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
    * @param processId - The process ID to fetch
    * @returns Promise resolving to user-friendly process information
+   * @throws Error if signer does not have a provider
    * 
    * @example
    * ```typescript
@@ -1732,12 +2348,95 @@ class DavinciSDK {
     if (!this.initialized) {
       throw new Error("SDK must be initialized before getting processes. Call sdk.init() first.");
     }
+    this.ensureProvider();
     return this.processOrchestrator.getProcess(processId);
   }
+  /**
+   * Creates a complete voting process and returns an async generator that yields transaction status events.
+   * This method allows you to monitor the transaction progress in real-time, including pending, completed,
+   * failed, and reverted states.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param config - Simplified process configuration
+   * @returns AsyncGenerator yielding transaction status events
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.createProcessStream({
+   *   title: "My Election",
+   *   description: "A simple election",
+   *   census: {
+   *     type: CensusOrigin.CensusOriginMerkleTree,
+   *     root: "0x1234...",
+   *     size: 100,
+   *     uri: "ipfs://..."
+   *   },
+   *   ballot: {
+   *     numFields: 2,
+   *     maxValue: "3",
+   *     minValue: "0",
+   *     uniqueValues: false,
+   *     costFromWeight: false,
+   *     costExponent: 10000,
+   *     maxValueSum: "6",
+   *     minValueSum: "0"
+   *   },
+   *   timing: {
+   *     startDate: new Date("2024-12-01T10:00:00Z"),
+   *     duration: 3600 * 24
+   *   },
+   *   questions: [
+   *     {
+   *       title: "What is your favorite color?",
+   *       choices: [
+   *         { title: "Red", value: 0 },
+   *         { title: "Blue", value: 1 }
+   *       ]
+   *     }
+   *   ]
+   * });
+   * 
+   * // Monitor transaction progress
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case TxStatus.Pending:
+   *       console.log("Transaction pending:", event.hash);
+   *       // Update UI to show pending state
+   *       break;
+   *     case TxStatus.Completed:
+   *       console.log("Process created:", event.response.processId);
+   *       console.log("Transaction hash:", event.response.transactionHash);
+   *       // Update UI to show success
+   *       break;
+   *     case TxStatus.Failed:
+   *       console.error("Transaction failed:", event.error);
+   *       // Update UI to show error
+   *       break;
+   *     case TxStatus.Reverted:
+   *       console.error("Transaction reverted:", event.reason);
+   *       // Update UI to show revert reason
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  createProcessStream(config) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before creating processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.createProcessStream(config);
+  }
   /**
    * Creates a complete voting process with minimal configuration.
    * This is the ultra-easy method for end users that handles all the complex orchestration internally.
    * 
+   * For real-time transaction status updates, use createProcessStream() instead.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
    * The method automatically:
    * - Gets encryption keys and initial state root from the sequencer
    * - Handles process creation signatures
@@ -1747,6 +2446,7 @@ class DavinciSDK {
    * 
    * @param config - Simplified process configuration
    * @returns Promise resolving to the process creation result
+   * @throws Error if signer does not have a provider
    * 
    * @example
    * ```typescript
@@ -1799,12 +2499,15 @@ class DavinciSDK {
     if (!this.initialized) {
       throw new Error("SDK must be initialized before creating processes. Call sdk.init() first.");
     }
+    this.ensureProvider();
     return this.processOrchestrator.createProcess(config);
   }
   /**
    * Submit a vote with simplified configuration.
    * This is the ultra-easy method for end users that handles all the complex voting workflow internally.
    * 
+   * Does NOT require a provider - can be used with a bare Wallet for signing only.
+   * 
    * The method automatically:
    * - Fetches process information and validates voting is allowed
    * - Gets census proof (Merkle tree based)
@@ -1846,6 +2549,8 @@ class DavinciSDK {
   /**
    * Get the status of a submitted vote.
    * 
+   * Does NOT require a provider - uses API calls only.
+   * 
    * @param processId - The process ID
    * @param voteId - The vote ID returned from submitVote()
    * @returns Promise resolving to vote status information
@@ -1866,6 +2571,8 @@ class DavinciSDK {
   /**
    * Check if an address has voted in a process.
    * 
+   * Does NOT require a provider - uses API calls only.
+   * 
    * @param processId - The process ID
    * @param address - The voter's address
    * @returns Promise resolving to boolean indicating if the address has voted
@@ -1884,9 +2591,59 @@ class DavinciSDK {
     }
     return this.voteOrchestrator.hasAddressVoted(processId, address);
   }
+  /**
+   * Watch vote status changes in real-time using an async generator.
+   * This method yields each status change as it happens, perfect for showing 
+   * progress indicators in UI applications.
+   * 
+   * Does NOT require a provider - uses API calls only.
+   * 
+   * @param processId - The process ID
+   * @param voteId - The vote ID
+   * @param options - Optional configuration
+   * @returns AsyncGenerator yielding vote status updates
+   * 
+   * @example
+   * ```typescript
+   * // Submit vote
+   * const voteResult = await sdk.submitVote({
+   *   processId: "0x1234567890abcdef...",
+   *   choices: [1]
+   * });
+   * 
+   * // Watch status changes in real-time
+   * for await (const statusInfo of sdk.watchVoteStatus(voteResult.processId, voteResult.voteId)) {
+   *   console.log(`Vote status: ${statusInfo.status}`);
+   *   
+   *   switch (statusInfo.status) {
+   *     case VoteStatus.Pending:
+   *       console.log("⏳ Processing...");
+   *       break;
+   *     case VoteStatus.Verified:
+   *       console.log("✓ Vote verified");
+   *       break;
+   *     case VoteStatus.Aggregated:
+   *       console.log("📊 Vote aggregated");
+   *       break;
+   *     case VoteStatus.Settled:
+   *       console.log("✅ Vote settled");
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  watchVoteStatus(processId, voteId, options) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before watching vote status. Call sdk.init() first.");
+    }
+    return this.voteOrchestrator.watchVoteStatus(processId, voteId, options);
+  }
   /**
    * Wait for a vote to reach a specific status.
-   * Useful for waiting for vote confirmation and processing.
+   * This is a simpler alternative to watchVoteStatus() that returns only the final status.
+   * Useful for waiting for vote confirmation and processing without needing to handle each intermediate status.
+   * 
+   * Does NOT require a provider - uses API calls only.
    * 
    * @param processId - The process ID
    * @param voteId - The vote ID
@@ -1900,15 +2657,14 @@ class DavinciSDK {
    * // Submit vote and wait for it to be settled
    * const voteResult = await sdk.submitVote({
    *   processId: "0x1234567890abcdef...",
-   *   choices: [1],
-   *   voterKey: "0x..."
+   *   choices: [1]
    * });
    * 
    * // Wait for the vote to be fully processed
    * const finalStatus = await sdk.waitForVoteStatus(
    *   voteResult.processId,
    *   voteResult.voteId,
-   *   "settled", // Wait until vote is settled
+   *   VoteStatus.Settled, // Wait until vote is settled
    *   300000,    // 5 minute timeout
    *   5000       // Check every 5 seconds
    * );
@@ -1922,6 +2678,266 @@ class DavinciSDK {
     }
     return this.voteOrchestrator.waitForVoteStatus(processId, voteId, targetStatus, timeoutMs, pollIntervalMs);
   }
+  /**
+   * Ends a voting process by setting its status to ENDED and returns an async generator 
+   * that yields transaction status events. This method allows you to monitor the 
+   * transaction progress in real-time.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param processId - The process ID to end
+   * @returns AsyncGenerator yielding transaction status events
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.endProcessStream("0x1234567890abcdef...");
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case TxStatus.Pending:
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case TxStatus.Completed:
+   *       console.log("Process ended successfully");
+   *       break;
+   *     case TxStatus.Failed:
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case TxStatus.Reverted:
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  endProcessStream(processId) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before ending processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.endProcessStream(processId);
+  }
+  /**
+   * Ends a voting process by setting its status to ENDED.
+   * This is the simplified method that waits for transaction completion.
+   * 
+   * For real-time transaction status updates, use endProcessStream() instead.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param processId - The process ID to end
+   * @returns Promise resolving when the process is ended
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * await sdk.endProcess("0x1234567890abcdef...");
+   * console.log("Process ended successfully");
+   * ```
+   */
+  async endProcess(processId) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before ending processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.endProcess(processId);
+  }
+  /**
+   * Pauses a voting process by setting its status to PAUSED and returns an async generator 
+   * that yields transaction status events. This method allows you to monitor the 
+   * transaction progress in real-time.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param processId - The process ID to pause
+   * @returns AsyncGenerator yielding transaction status events
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.pauseProcessStream("0x1234567890abcdef...");
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case TxStatus.Pending:
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case TxStatus.Completed:
+   *       console.log("Process paused successfully");
+   *       break;
+   *     case TxStatus.Failed:
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case TxStatus.Reverted:
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  pauseProcessStream(processId) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before pausing processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.pauseProcessStream(processId);
+  }
+  /**
+   * Pauses a voting process by setting its status to PAUSED.
+   * This is the simplified method that waits for transaction completion.
+   * 
+   * For real-time transaction status updates, use pauseProcessStream() instead.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param processId - The process ID to pause
+   * @returns Promise resolving when the process is paused
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * await sdk.pauseProcess("0x1234567890abcdef...");
+   * console.log("Process paused successfully");
+   * ```
+   */
+  async pauseProcess(processId) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before pausing processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.pauseProcess(processId);
+  }
+  /**
+   * Cancels a voting process by setting its status to CANCELED and returns an async generator 
+   * that yields transaction status events. This method allows you to monitor the 
+   * transaction progress in real-time.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param processId - The process ID to cancel
+   * @returns AsyncGenerator yielding transaction status events
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.cancelProcessStream("0x1234567890abcdef...");
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case TxStatus.Pending:
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case TxStatus.Completed:
+   *       console.log("Process canceled successfully");
+   *       break;
+   *     case TxStatus.Failed:
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case TxStatus.Reverted:
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  cancelProcessStream(processId) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before canceling processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.cancelProcessStream(processId);
+  }
+  /**
+   * Cancels a voting process by setting its status to CANCELED.
+   * This is the simplified method that waits for transaction completion.
+   * 
+   * For real-time transaction status updates, use cancelProcessStream() instead.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param processId - The process ID to cancel
+   * @returns Promise resolving when the process is canceled
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * await sdk.cancelProcess("0x1234567890abcdef...");
+   * console.log("Process canceled successfully");
+   * ```
+   */
+  async cancelProcess(processId) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before canceling processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.cancelProcess(processId);
+  }
+  /**
+   * Resumes a voting process by setting its status to READY and returns an async generator 
+   * that yields transaction status events. This is typically used to resume a paused process.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param processId - The process ID to resume
+   * @returns AsyncGenerator yielding transaction status events
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * const stream = sdk.resumeProcessStream("0x1234567890abcdef...");
+   * 
+   * for await (const event of stream) {
+   *   switch (event.status) {
+   *     case TxStatus.Pending:
+   *       console.log("Transaction pending:", event.hash);
+   *       break;
+   *     case TxStatus.Completed:
+   *       console.log("Process resumed successfully");
+   *       break;
+   *     case TxStatus.Failed:
+   *       console.error("Transaction failed:", event.error);
+   *       break;
+   *     case TxStatus.Reverted:
+   *       console.error("Transaction reverted:", event.reason);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  resumeProcessStream(processId) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before resuming processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.resumeProcessStream(processId);
+  }
+  /**
+   * Resumes a voting process by setting its status to READY.
+   * This is typically used to resume a paused process.
+   * This is the simplified method that waits for transaction completion.
+   * 
+   * For real-time transaction status updates, use resumeProcessStream() instead.
+   * 
+   * Requires a signer with a provider for blockchain interactions.
+   * 
+   * @param processId - The process ID to resume
+   * @returns Promise resolving when the process is resumed
+   * @throws Error if signer does not have a provider
+   * 
+   * @example
+   * ```typescript
+   * await sdk.resumeProcess("0x1234567890abcdef...");
+   * console.log("Process resumed successfully");
+   * ```
+   */
+  async resumeProcess(processId) {
+    if (!this.initialized) {
+      throw new Error("SDK must be initialized before resuming processes. Call sdk.init() first.");
+    }
+    this.ensureProvider();
+    return this.processOrchestrator.resumeProcess(processId);
+  }
   /**
    * Resolve contract address based on configuration priority:
    * 1. If useSequencerAddresses is true: addresses from sequencer (highest priority)
@@ -1996,6 +3012,18 @@ class DavinciSDK {
   isInitialized() {
     return this.initialized;
   }
+  /**
+   * Ensures that the signer has a provider for blockchain operations.
+   * @throws Error if the signer does not have a provider
+   * @private
+   */
+  ensureProvider() {
+    if (!this.config.signer.provider) {
+      throw new Error(
+        "Provider required for blockchain operations (process/organization management). The signer must be connected to a provider. Use wallet.connect(provider) or a browser signer like MetaMask. Note: Voting operations do not require a provider."
+      );
+    }
+  }
 }
 
 exports.BaseService = BaseService;