@vocdoni/davinci-sdk 0.0.1 → 0.0.3

package/README.md

@@ -1,7 +1,7 @@
 # Vocdoni DaVinci SDK
 
 [![npm version](https://badge.fury.io/js/%40vocdoni%2Fdavinci-sdk.svg)](https://badge.fury.io/js/%40vocdoni%2Fdavinci-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](#)
 
@@ -20,44 +20,32 @@ yarn add @vocdoni/davinci-sdk
 ### Basic Usage
 
 ```typescript
-import { DavinciSDK, CensusOrigin } from '@vocdoni/davinci-sdk';
+import { DavinciSDK, PlainCensus, WeightedCensus } from '@vocdoni/davinci-sdk';
 import { Wallet } from 'ethers';
 
 // Initialize the SDK
 const wallet = new Wallet('your-private-key');
 const sdk = new DavinciSDK({
   signer: wallet,
-  environment: 'dev' // or 'stg', 'prod'
+  sequencerUrl: 'https://sequencer-dev.davinci.vote',
+  censusUrl: 'https://c3-dev.davinci.vote'
 });
 
 await sdk.init();
 
 // 1. Create a census with eligible voters
-const censusId = await sdk.api.census.createCensus();
-
-// Add participants to the census
-const participants = [
-  { key: "0x1234567890123456789012345678901234567890", weight: "1" },
-  { key: "0x2345678901234567890123456789012345678901", weight: "1" },
-  { key: "0x3456789012345678901234567890123456789012", weight: "2" } // Higher weight
-];
-
-await sdk.api.census.addParticipants(censusId, participants);
-
-// Publish the census to get the root
-const publishResult = await sdk.api.census.publishCensus(censusId);
-const censusSize = await sdk.api.census.getCensusSize(publishResult.root);
+const census = new PlainCensus(); // or WeightedCensus for custom voting power
+census.add([
+  '0x1234567890123456789012345678901234567890',
+  '0x2345678901234567890123456789012345678901',
+  '0x3456789012345678901234567890123456789012'
+]);
 
 // 2. Create a voting process
 const process = await sdk.createProcess({
   title: "Community Decision",
   description: "Vote on our next community initiative",
-  census: {
-    type: CensusOrigin.CensusOriginMerkleTree,
-    root: publishResult.root,
-    size: censusSize,
-    uri: publishResult.uri
-  },
+  census: census,
   timing: {
     startDate: new Date("2024-12-01T10:00:00Z"),
     duration: 86400 // 24 hours in seconds
@@ -76,7 +64,8 @@ const process = await sdk.createProcess({
 const voterWallet = new Wallet('voter-private-key'); // Must be one of the census participants
 const voterSdk = new DavinciSDK({
   signer: voterWallet,
-  environment: 'dev'
+  sequencerUrl: 'https://sequencer-dev.davinci.vote'
+  // No censusUrl needed for voting-only operations
 });
 await voterSdk.init();
 
@@ -157,6 +146,190 @@ pnpm add @vocdoni/davinci-sdk ethers
 - **Process**: Container for all voting parameters and metadata
 - **Proof**: Cryptographic evidence that a vote is valid
 
+## 📋 Census Management
+
+The SDK provides simple-to-use census classes that make voter management easy. Census objects are **automatically published** when creating a process - no manual steps required!
+
+### Census Types
+
+#### PlainCensus - Equal Voting Power
+
+Everyone gets the same voting weight (weight = 1).
+
+```typescript
+import { PlainCensus } from '@vocdoni/davinci-sdk';
+
+const census = new PlainCensus();
+census.add([
+  '0x1234567890123456789012345678901234567890',
+  '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+  '0x9876543210987654321098765432109876543210'
+]);
+
+// Use directly in process creation - SDK auto-publishes!
+const process = await sdk.createProcess({
+  census: census, // ✨ Auto-published!
+  // ... rest of config
+});
+```
+
+#### WeightedCensus - Custom Voting Power
+
+Assign different voting weights to participants. Supports flexible weight types: **string**, **number**, or **bigint**.
+
+```typescript
+import { WeightedCensus } from '@vocdoni/davinci-sdk';
+
+const census = new WeightedCensus();
+
+census.add([
+  { key: '0x123...', weight: "1" },    // string
+  { key: '0x456...', weight: 5 },      // number
+  { key: '0x789...', weight: 100n },   // bigint
+]);
+
+// Auto-published when creating process
+const process = await sdk.createProcess({
+  census: census,
+  // ... rest of config
+});
+```
+
+#### CspCensus - Certificate Service Provider
+
+For external authentication systems.
+
+```typescript
+import { CspCensus } from '@vocdoni/davinci-sdk';
+
+const census = new CspCensus(
+  "0x1234567890abcdef", // Root hash (public key)
+  "https://csp-server.com", // CSP URL
+  1000 // Expected number of voters
+);
+
+const process = await sdk.createProcess({
+  census: census,
+  // ... rest of config
+});
+```
+
+#### PublishedCensus - Use Pre-Published Census
+
+For censuses already published to the network.
+
+```typescript
+import { PublishedCensus, CensusType } from '@vocdoni/davinci-sdk';
+
+const census = new PublishedCensus(
+  CensusType.WEIGHTED,
+  "0xroot...",
+  "ipfs://uri...",
+  100 // size
+);
+
+const process = await sdk.createProcess({
+  census: census,
+  // ... rest of config
+});
+```
+
+### Auto-Publishing Feature
+
+The SDK automatically publishes unpublished censuses when creating a process:
+
+```typescript
+const census = new PlainCensus();
+census.add(['0x123...', '0x456...']);
+
+console.log(census.isPublished); // false
+
+// SDK automatically publishes during process creation
+const process = await sdk.createProcess({
+  census: census,
+  // ... config
+});
+
+console.log(census.isPublished); // true ✅
+console.log(census.censusRoot);   // Published root hash
+console.log(census.censusURI);    // Published URI
+```
+
+### Flexible Weight Types
+
+WeightedCensus accepts weights as strings, numbers, or bigints for maximum flexibility:
+
+```typescript
+const census = new WeightedCensus();
+
+// String weights (recommended for very large numbers)
+census.add({ key: '0x123...', weight: "999999999999" });
+
+// Number weights (easy to use, good for reasonable values)
+census.add({ key: '0x456...', weight: 100 });
+
+// BigInt weights (for JavaScript bigint support)
+census.add({ key: '0x789...', weight: 1000000n });
+
+// Mix them all!
+census.add([
+  { key: '0xaaa...', weight: "1" },
+  { key: '0xbbb...', weight: 5 },
+  { key: '0xccc...', weight: 10n }
+]);
+```
+
+### Census Operations
+
+```typescript
+const census = new WeightedCensus();
+
+// Add single participant
+census.add({ key: '0x123...', weight: 5 });
+
+// Add multiple participants
+census.add([
+  { key: '0x456...', weight: 10 },
+  { key: '0x789...', weight: 15 }
+]);
+
+// Remove participant
+census.remove('0x123...');
+
+// Get participant weight
+const weight = census.getWeight('0x456...'); // Returns: "10"
+
+// Get all addresses
+const addresses = census.addresses; // ['0x456...', '0x789...']
+
+// Get all participants with weights
+const participants = census.participants;
+// [{ key: '0x456...', weight: '10' }, { key: '0x789...', weight: '15' }]
+
+// Check if published
+if (census.isPublished) {
+  console.log('Root:', census.censusRoot);
+  console.log('URI:', census.censusURI);
+  console.log('Size:', census.size);
+}
+```
+
+### Manual Census Configuration (Advanced)
+
+For advanced use cases, you can still provide census data manually:
+
+```typescript
+const process = await sdk.createProcess({
+  census: {
+    type: CensusOrigin.CensusOriginMerkleTree,
+    root: "0xabc...",
+    size: 100,
+    uri: "ipfs://..."
+  },
+  // ... rest of config
+});
+```
+
 ## 📖 API Reference
 
 ### SDK Initialization
@@ -166,36 +339,65 @@ pnpm add @vocdoni/davinci-sdk ethers
 ```typescript
 interface DavinciSDKConfig {
   signer: Signer;                    // Ethereum signer (required)
-  environment?: 'dev' | 'stg' | 'prod'; // Environment (default: 'prod')
-  sequencerUrl?: string;             // Custom sequencer URL
-  censusUrl?: string;                // Custom census API URL
-  chain?: 'sepolia' | 'mainnet';    // Blockchain network
-  contractAddresses?: {              // Custom contract addresses
+  sequencerUrl: string;              // Sequencer API URL (required)
+  censusUrl?: string;                // Census API URL (optional, only needed for census creation)
+  addresses?: {                      // Custom contract addresses (optional)
     processRegistry?: string;
     organizationRegistry?: string;
-    // ... other contracts
+    stateTransitionVerifier?: string;
+    resultsVerifier?: string;
+    sequencerRegistry?: string;
   };
-  useSequencerAddresses?: boolean;   // Use addresses from sequencer
+  censusProviders?: CensusProviders; // Custom census proof providers (optional)
+  verifyCircuitFiles?: boolean;      // Verify downloaded circuit files (default: true)
+  verifyProof?: boolean;             // Verify generated proof before submission (default: true)
 }
 ```
 
+**Key Points:**
+
+- **`sequencerUrl`** (required): The Vocdoni sequencer API endpoint
+  - Dev: `https://sequencer-dev.davinci.vote`
+  - Staging: `https://sequencer1.davinci.vote`
+  - Production: (check latest docs)
+
+- **`censusUrl`** (optional): Only required if you're creating censuses from scratch. Not needed for voting-only operations.
+
+- **Contract Addresses**: If not provided, the SDK automatically fetches them from the sequencer's `/info` endpoint during initialization. This is the recommended approach.
+
 #### Basic Initialization
 
 ```typescript
 import { DavinciSDK } from '@vocdoni/davinci-sdk';
 import { Wallet } from 'ethers';
 
+// Development environment
 const sdk = new DavinciSDK({
   signer: new Wallet('your-private-key'),
-  environment: 'dev'
+  sequencerUrl: 'https://sequencer-dev.davinci.vote',
+  censusUrl: 'https://c3-dev.davinci.vote'
 });
 
 await sdk.init();
 ```
 
+**Automatic Contract Address Fetching:**
+
+The SDK automatically fetches contract addresses from the sequencer during `init()`:
+
+```typescript
+const sdk = new DavinciSDK({
+  signer: wallet,
+  sequencerUrl: 'https://sequencer-dev.davinci.vote'
+  // Contract addresses will be fetched automatically from sequencer
+});
+
+await sdk.init(); // Fetches and stores contract addresses
+```
+
 ### Process Management
 
-#### Creating a Process
+#### Creating a Process (Simple)
 
 ```typescript
 const processResult = await sdk.createProcess({
@@ -244,6 +446,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
@@ -315,7 +562,8 @@ async function completeVotingExample() {
   const organizerWallet = new Wallet('organizer-private-key');
   const sdk = new DavinciSDK({
     signer: organizerWallet,
-    environment: 'dev'
+    sequencerUrl: 'https://sequencer-dev.davinci.vote',
+    censusUrl: 'https://c3-dev.davinci.vote'
   });
   await sdk.init();
 
@@ -370,7 +618,8 @@ async function completeVotingExample() {
   const voterWallet = voters[0]; // Use first voter from census
   const voterSdk = new DavinciSDK({
     signer: voterWallet,
-    environment: 'dev'
+    sequencerUrl: 'https://sequencer-dev.davinci.vote'
+    // No censusUrl needed for voting-only operations
   });
   await voterSdk.init();
 
@@ -414,7 +663,7 @@ async function browserVotingExample() {
   // Initialize SDK
   const sdk = new DavinciSDK({
     signer,
-    environment: 'prod'
+    sequencerUrl: 'https://sequencer.davinci.vote' // Production URL
   });
   await sdk.init();
 
@@ -438,10 +687,9 @@ async function browserVotingExample() {
 ```typescript
 const sdk = new DavinciSDK({
   signer: wallet,
-  chain: 'sepolia',
   sequencerUrl: 'https://your-custom-sequencer.com',
   censusUrl: 'https://your-custom-census.com',
-  contractAddresses: {
+  addresses: {
     processRegistry: '0x...',
     organizationRegistry: '0x...',
     stateTransitionVerifier: '0x...',
@@ -450,14 +698,18 @@ const sdk = new DavinciSDK({
 });
 ```
 
-### Using Sequencer-Provided Addresses
+### Automatic Contract Address Fetching (Default Behavior)
+
+By default, the SDK automatically fetches contract addresses from the sequencer's `/info` endpoint:
 
 ```typescript
 const sdk = new DavinciSDK({
   signer: wallet,
-  environment: 'dev',
-  useSequencerAddresses: true // Fetch contract addresses from sequencer
+  sequencerUrl: 'https://sequencer-dev.davinci.vote'
+  // Contract addresses fetched automatically during init()
 });
+
+await sdk.init(); // Fetches addresses from sequencer
 ```
 
 ### Custom Vote Randomness
@@ -466,7 +718,7 @@ const sdk = new DavinciSDK({
 const vote = await sdk.submitVote({
   processId: "0x...",
   choices: [1],
-  randomness: "your-custom-randomness-hex" // For deterministic testing
+  randomness: "your-custom-randomness-hex"
 });
 ```
 
@@ -600,7 +852,9 @@ yarn format
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.
+
+The AGPL-3.0 is a copyleft license that requires anyone who distributes your code or a derivative work to make the source available under the same terms. If your application is a web service, users interacting with it remotely must also be able to access the source code.
 
 ## 🆘 Support
 

package/dist/contracts.d.ts

@@ -1,53 +1,6 @@
-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';
 
-/**
- * Interface defining the structure of deployed contract addresses across different networks.
- * Each contract has addresses for both Sepolia testnet and Ethereum mainnet.
- */
-interface DeployedAddresses {
-    /** Process Registry contract addresses */
-    processRegistry: {
-        /** Sepolia testnet address */
-        sepolia: string;
-        /** Ethereum mainnet address */
-        mainnet: string;
-    };
-    /** Organization Registry contract addresses */
-    organizationRegistry: {
-        /** Sepolia testnet address */
-        sepolia: string;
-        /** Ethereum mainnet address */
-        mainnet: string;
-    };
-    /** State Transition Verifier contract addresses */
-    stateTransitionVerifierGroth16: {
-        /** Sepolia testnet address */
-        sepolia: string;
-        /** Ethereum mainnet address */
-        mainnet: string;
-    };
-    /** Results Verifier contract addresses */
-    resultsVerifierGroth16: {
-        /** Sepolia testnet address */
-        sepolia: string;
-        /** Ethereum mainnet address */
-        mainnet: string;
-    };
-    /** Sequencer Registry contract addresses */
-    sequencerRegistry: {
-        /** Sepolia testnet address */
-        sepolia: string;
-        /** Ethereum mainnet address */
-        mainnet: string;
-    };
-}
-/**
- * Deployed contract addresses imported from @vocdoni/davinci-contracts package.
- * These addresses are used to interact with the Vocdoni voting protocol contracts
- * on different networks.
- */
-declare const deployedAddresses: DeployedAddresses;
 /**
  * Enum representing the possible states of a transaction during its lifecycle.
  * Used to track and report transaction status in the event stream.
@@ -83,9 +36,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 +114,59 @@ 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 or filter operations are not working.
+     * This includes:
+     * - Method not found (-32601): RPC doesn't support eth_newFilter
+     * - Filter not found (-32000): RPC doesn't properly maintain filters
+     *
+     * @param error - The error to check
+     * @returns true if the error indicates unsupported or broken filter functionality
+     */
+    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;
 }
 
 /**
@@ -359,7 +370,7 @@ interface BallotMode {
     maxValueSum: string;
     minValueSum: string;
 }
-interface Census {
+interface CensusData {
     censusOrigin: CensusOrigin;
     maxVotes: string;
     censusRoot: string;
@@ -470,13 +481,13 @@ declare class ProcessRegistryService extends SmartContractService {
     }>;
     getRVerifier(): Promise<string>;
     getSTVerifier(): Promise<string>;
-    newProcess(status: ProcessStatus, startTime: number, duration: number, ballotMode: BallotMode, census: Census, metadata: string, encryptionKey: EncryptionKey, initStateRoot: bigint): AsyncGenerator<TxStatusEvent<{
+    newProcess(status: ProcessStatus, startTime: number, duration: number, ballotMode: BallotMode, census: CensusData, metadata: string, encryptionKey: EncryptionKey, initStateRoot: bigint): AsyncGenerator<TxStatusEvent<{
         success: boolean;
     }>, void, unknown>;
     setProcessStatus(processID: string, newStatus: ProcessStatus): AsyncGenerator<TxStatusEvent<{
         success: boolean;
     }>, void, unknown>;
-    setProcessCensus(processID: string, census: Census): AsyncGenerator<TxStatusEvent<{
+    setProcessCensus(processID: string, census: CensusData): AsyncGenerator<TxStatusEvent<{
         success: boolean;
     }>, void, unknown>;
     setProcessDuration(processID: string, duration: number): AsyncGenerator<TxStatusEvent<{
@@ -508,5 +519,5 @@ declare class ProcessRegistryService extends SmartContractService {
     removeAllListeners(): void;
 }
 
-export { ContractServiceError, OrganizationAdministratorError, OrganizationCreateError, OrganizationDeleteError, OrganizationRegistryService, OrganizationUpdateError, ProcessCensusError, ProcessCreateError, ProcessDurationError, ProcessRegistryService, ProcessResultError, ProcessStateTransitionError, ProcessStatus, ProcessStatusError, SmartContractService, TxStatus, deployedAddresses };
-export type { DeployedAddresses, EntityCallback, OrganizationAdministratorAddedCallback, OrganizationAdministratorRemovedCallback, OrganizationCreatedCallback, OrganizationInfo, OrganizationUpdatedCallback, ProcessCensusUpdatedCallback, ProcessCreatedCallback, ProcessDurationChangedCallback, ProcessResultsSetCallback, ProcessStateRootUpdatedCallback, ProcessStatusChangedCallback, TxStatusEvent };
+export { ContractServiceError, OrganizationAdministratorError, OrganizationCreateError, OrganizationDeleteError, OrganizationRegistryService, OrganizationUpdateError, ProcessCensusError, ProcessCreateError, ProcessDurationError, ProcessRegistryService, ProcessResultError, ProcessStateTransitionError, ProcessStatus, ProcessStatusError, SmartContractService, TxStatus };
+export type { EntityCallback, OrganizationAdministratorAddedCallback, OrganizationAdministratorRemovedCallback, OrganizationCreatedCallback, OrganizationInfo, OrganizationUpdatedCallback, ProcessCensusUpdatedCallback, ProcessCreatedCallback, ProcessDurationChangedCallback, ProcessResultsSetCallback, ProcessStateRootUpdatedCallback, ProcessStatusChangedCallback, TxStatusEvent };