@vocdoni/davinci-sdk 0.0.1 → 0.0.2

package/dist/index.umd.js

@@ -401,29 +401,34 @@
     }
 
     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,
@@ -442,6 +447,12 @@
       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,
@@ -553,6 +564,141 @@
           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 {
@@ -731,43 +877,50 @@
       }
       // ─── 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();
       }
     }
 
@@ -851,10 +1004,114 @@
         };
       }
       /**
-       * 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);
@@ -877,35 +1134,15 @@
           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
         };
       }
       /**
@@ -983,6 +1220,312 @@
         }));
         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 {
@@ -1172,11 +1715,61 @@
        * @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
@@ -1186,15 +1779,18 @@
        * @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
@@ -1383,31 +1979,36 @@
       }
       // ─── 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();
       }
     }
 
@@ -1634,9 +2235,13 @@
         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);
@@ -1644,9 +2249,13 @@
         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);
@@ -1668,9 +2277,13 @@
         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,
@@ -1701,8 +2314,11 @@
        * 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
@@ -1731,12 +2347,95 @@
         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
@@ -1746,6 +2445,7 @@
        * 
        * @param config - Simplified process configuration
        * @returns Promise resolving to the process creation result
+       * @throws Error if signer does not have a provider
        * 
        * @example
        * ```typescript
@@ -1798,12 +2498,15 @@
         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)
@@ -1845,6 +2548,8 @@
       /**
        * 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
@@ -1865,6 +2570,8 @@
       /**
        * 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
@@ -1883,9 +2590,59 @@
         }
         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
@@ -1899,15 +2656,14 @@
        * // 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
        * );
@@ -1921,6 +2677,266 @@
         }
         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)
@@ -1995,6 +3011,18 @@
       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;