@vocdoni/davinci-sdk 0.0.1 → 0.0.2

package/README.md

@@ -195,7 +195,7 @@ await sdk.init();
 
 ### Process Management
 
-#### Creating a Process
+#### Creating a Process (Simple)
 
 ```typescript
 const processResult = await sdk.createProcess({
@@ -244,6 +244,51 @@ const processResult = await sdk.createProcess({
 console.log('Process created:', processResult.processId);
 ```
 
+#### Creating a Process with Real-Time Status (Stream)
+
+For applications that need to show real-time transaction progress to users, use `createProcessStream()`:
+
+```typescript
+import { TxStatus } from '@vocdoni/davinci-sdk';
+
+const stream = sdk.createProcessStream({
+  title: "Election Title",
+  // ... same configuration as above
+});
+
+// Monitor transaction status in real-time
+for await (const event of stream) {
+  switch (event.status) {
+    case TxStatus.Pending:
+      console.log("📝 Transaction submitted:", event.hash);
+      // Update UI to show pending state
+      break;
+      
+    case TxStatus.Completed:
+      console.log("✅ Process created:", event.response.processId);
+      console.log("   Transaction:", 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;
+  }
+}
+```
+
+**When to use each method:**
+
+- Use `createProcess()` for simple scripts and when you don't need transaction progress updates
+- Use `createProcessStream()` for UI applications where users need real-time feedback during transaction processing
+
+
 #### Retrieving Process Information
 
 ```typescript

package/dist/contracts.d.ts

@@ -1,4 +1,4 @@
-import { ContractTransactionResponse, ContractRunner } from 'ethers';
+import { ContractTransactionResponse, BaseContract, ContractEventName, EventFilter, ContractRunner } from 'ethers';
 import * as _vocdoni_davinci_contracts_dist_src_ProcessRegistry from '@vocdoni/davinci-contracts/dist/src/ProcessRegistry';
 
 /**
@@ -83,9 +83,14 @@ type TxStatusEvent<T = any> = {
 };
 /**
  * Abstract base class providing common functionality for smart contract interactions.
- * Implements transaction handling, status monitoring, and event normalization.
+ * Implements transaction handling, status monitoring, event normalization, and
+ * event listener management with automatic fallback for RPCs that don't support eth_newFilter.
  */
 declare abstract class SmartContractService {
+    /** Active polling intervals for event listeners using fallback mode */
+    private pollingIntervals;
+    /** Default polling interval in milliseconds for event listener fallback */
+    protected eventPollingInterval: number;
     /**
      * Sends a transaction and yields status events during its lifecycle.
      * This method handles the complete transaction flow from submission to completion,
@@ -156,6 +161,56 @@ declare abstract class SmartContractService {
      * ```
      */
     protected normalizeListener<Args extends any[]>(callback: (...args: Args) => void): (...listenerArgs: any[]) => void;
+    /**
+     * 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}`);
+     *   }
+     * );
+     * ```
+     */
+    protected setupEventListener<Args extends any[]>(contract: BaseContract, eventFilter: ContractEventName | EventFilter, callback: (...args: Args) => void): Promise<void>;
+    /**
+     * 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
+     */
+    private isUnsupportedMethodError;
+    /**
+     * 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
+     */
+    private setupPollingListener;
+    /**
+     * Clears all active polling intervals.
+     * Should be called when removing all listeners or cleaning up the service.
+     */
+    protected clearPollingIntervals(): void;
+    /**
+     * Sets the polling interval for event listeners using the fallback mechanism.
+     *
+     * @param intervalMs - Polling interval in milliseconds
+     */
+    setEventPollingInterval(intervalMs: number): void;
 }
 
 /**