@vocdoni/davinci-sdk 0.0.7 → 0.1.0

package/README.md

@@ -20,7 +20,7 @@ yarn add @vocdoni/davinci-sdk
 ### Basic Usage
 
 ```typescript
-import { DavinciSDK, PlainCensus, WeightedCensus } from '@vocdoni/davinci-sdk';
+import { DavinciSDK, OffchainCensus } from '@vocdoni/davinci-sdk';
 import { Wallet } from 'ethers';
 
 // Initialize the SDK
@@ -34,7 +34,7 @@ const sdk = new DavinciSDK({
 await sdk.init();
 
 // 1. Create a census with eligible voters
-const census = new PlainCensus(); // or WeightedCensus for custom voting power
+const census = new OffchainCensus(); // Supports both plain and weighted voting
 census.add([
   '0x1234567890123456789012345678901234567890',
   '0x2345678901234567890123456789012345678901',
@@ -152,14 +152,16 @@ The SDK provides simple-to-use census classes that make voter management easy. C
 
 ### Census Types
 
-#### PlainCensus - Equal Voting Power
+#### OffchainCensus - Static Merkle Tree Census
 
-Everyone gets the same voting weight (weight = 1).
+A flexible census that supports both plain addresses (equal voting power) and weighted participants.
+
+**Plain addresses (everyone gets weight = 1):**
 
 ```typescript
-import { PlainCensus } from '@vocdoni/davinci-sdk';
+import { OffchainCensus } from '@vocdoni/davinci-sdk';
 
-const census = new PlainCensus();
+const census = new OffchainCensus();
 census.add([
   '0x1234567890123456789012345678901234567890',
   '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
@@ -168,19 +170,19 @@ census.add([
 
 // Use directly in process creation - SDK auto-publishes!
 const process = await sdk.createProcess({
-  census: census, // ✨ Auto-published!
+  census: census, // ✨ Auto-published! maxVoters auto-calculated!
   // ... rest of config
 });
 ```
 
-#### WeightedCensus - Custom Voting Power
+**Weighted participants (custom voting power):**
 
-Assign different voting weights to participants. Supports flexible weight types: **string**, **number**, or **bigint**.
+Supports flexible weight types: **string**, **number**, or **bigint**.
 
 ```typescript
-import { WeightedCensus } from '@vocdoni/davinci-sdk';
+import { OffchainCensus } from '@vocdoni/davinci-sdk';
 
-const census = new WeightedCensus();
+const census = new OffchainCensus();
 
 census.add([
   { key: '0x123...', weight: "1" },    // string
@@ -188,7 +190,27 @@ census.add([
   { key: '0x789...', weight: 100n },   // bigint
 ]);
 
-// Auto-published when creating process
+// Auto-published when creating process, maxVoters auto-set to participant count
+const process = await sdk.createProcess({
+  census: census,
+  // ... rest of config
+});
+```
+
+#### OffchainDynamicCensus - Updatable Merkle Tree Census
+
+Similar to OffchainCensus but allows census updates after process creation.
+
+```typescript
+import { OffchainDynamicCensus } from '@vocdoni/davinci-sdk';
+
+const census = new OffchainDynamicCensus();
+census.add([
+  { key: '0x123...', weight: 10 },
+  { key: '0x456...', weight: 20 }
+]);
+
+// Auto-published and updatable
 const process = await sdk.createProcess({
   census: census,
   // ... rest of config
@@ -204,12 +226,12 @@ 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
+  "https://csp-server.com"  // CSP URL
 );
 
 const process = await sdk.createProcess({
   census: census,
+  maxVoters: 1000, // Required for CSP census
   // ... rest of config
 });
 ```
@@ -219,17 +241,17 @@ const process = await sdk.createProcess({
 For censuses already published to the network.
 
 ```typescript
-import { PublishedCensus, CensusType } from '@vocdoni/davinci-sdk';
+import { PublishedCensus, CensusOrigin } from '@vocdoni/davinci-sdk';
 
 const census = new PublishedCensus(
-  CensusType.WEIGHTED,
+  CensusOrigin.OffchainStatic,
   "0xroot...",
-  "ipfs://uri...",
-  100 // size
+  "ipfs://uri..."
 );
 
 const process = await sdk.createProcess({
   census: census,
+  maxVoters: 100, // Required for pre-published census
   // ... rest of config
 });
 ```
@@ -239,7 +261,7 @@ const process = await sdk.createProcess({
 The SDK automatically publishes unpublished censuses when creating a process:
 
 ```typescript
-const census = new PlainCensus();
+const census = new OffchainCensus();
 census.add(['0x123...', '0x456...']);
 
 console.log(census.isPublished); // false
@@ -257,10 +279,10 @@ console.log(census.censusURI);    // Published URI
 
 ### Flexible Weight Types
 
-WeightedCensus accepts weights as strings, numbers, or bigints for maximum flexibility:
+OffchainCensus accepts weights as strings, numbers, or bigints for maximum flexibility:
 
 ```typescript
-const census = new WeightedCensus();
+const census = new OffchainCensus();
 
 // String weights (recommended for very large numbers)
 census.add({ key: '0x123...', weight: "999999999999" });
@@ -282,7 +304,7 @@ census.add([
 ### Census Operations
 
 ```typescript
-const census = new WeightedCensus();
+const census = new OffchainCensus();
 
 // Add single participant
 census.add({ key: '0x123...', weight: 5 });
@@ -310,7 +332,6 @@ const participants = census.participants;
 if (census.isPublished) {
   console.log('Root:', census.censusRoot);
   console.log('URI:', census.censusURI);
-  console.log('Size:', census.size);
 }
 ```
 
@@ -323,9 +344,9 @@ const process = await sdk.createProcess({
   census: {
     type: CensusOrigin.OffchainStatic,
     root: "0xabc...",
-    size: 100,
     uri: "ipfs://..."
   },
+  maxVoters: 100, // Required for manual census config
   // ... rest of config
 });
 ```
@@ -408,7 +429,6 @@ const processResult = await sdk.createProcess({
   census: {
     type: CensusOrigin.OffchainStatic,
     root: "0x...",
-    size: 1000,
     uri: "ipfs://..."
   },
   
@@ -431,8 +451,8 @@ const processResult = await sdk.createProcess({
     minValueSum: "0"
   },
   
-  // Maximum voters (optional, defaults to census size)
-  maxVoters: 500, // Limit the process to 500 voters
+  // Maximum voters (required for manual census config)
+  maxVoters: 500,
   
   // Questions
   questions: [{
@@ -664,9 +684,9 @@ async function completeVotingExample() {
     census: {
       type: CensusOrigin.OffchainStatic,
       root: publishResult.root,
-      size: censusSize,
       uri: publishResult.uri
     },
+    maxVoters: censusSize,
     timing: {
       startDate: new Date(Date.now() + 60000), // Start in 1 minute
       duration: 3600 // 1 hour

package/dist/index.d.ts

@@ -117,7 +117,7 @@ declare enum CensusOrigin {
     /** Credential Service Provider (CSP) census using EdDSA BLS12-377 */
     CSP = 4
 }
-interface CensusParticipant$1 {
+interface CensusParticipant {
     key: string;
     weight?: string;
 }
@@ -275,8 +275,8 @@ declare class VocdoniCensusService extends BaseService {
      */
     getCensusUri(relativePath: string): string;
     createCensus(): Promise<string>;
-    addParticipants(censusId: string, participants: CensusParticipant$1[]): Promise<void>;
-    getParticipants(censusId: string): Promise<CensusParticipant$1[]>;
+    addParticipants(censusId: string, participants: CensusParticipant[]): Promise<void>;
+    getParticipants(censusId: string): Promise<CensusParticipant[]>;
     getCensusRoot(censusId: string): Promise<string>;
     getCensusSizeById(censusId: string): Promise<number>;
     getCensusSizeByRoot(censusRoot: string): Promise<number>;
@@ -289,21 +289,6 @@ declare class VocdoniCensusService extends BaseService {
     getHealth(): Promise<HealthResponse>;
 }
 
-/**
- * Census type enumeration
- */
-declare enum CensusType {
-    PLAIN = "plain",
-    WEIGHTED = "weighted",
-    CSP = "csp"
-}
-/**
- * Re-export CensusParticipant from types for convenience
- * Extended to make weight required (base type has optional weight)
- */
-interface CensusParticipant extends CensusParticipant$1 {
-    weight: string;
-}
 /**
  * Abstract base class for all census types
  */
@@ -311,84 +296,48 @@ declare abstract class Census {
     protected _censusId: string | null;
     protected _censusRoot: string | null;
     protected _censusURI: string | null;
-    protected _type: CensusType;
     protected _censusOrigin: CensusOrigin;
-    protected _size: number | null;
-    constructor(type: CensusType, censusOrigin?: CensusOrigin);
+    constructor(censusOrigin: CensusOrigin);
     get censusId(): string | null;
     get censusRoot(): string | null;
     get censusURI(): string | null;
-    get type(): CensusType;
-    get size(): number | null;
     get isPublished(): boolean;
     /**
      * Get the census origin (OffchainStatic, OffchainDynamic, Onchain, or CSP)
      */
     get censusOrigin(): CensusOrigin;
-}
-
-/**
- * Plain census where all participants have equal voting power (weight=1)
- * Simpler API - just add addresses without specifying weights
- */
-declare class PlainCensus extends Census {
-    private _participants;
-    /**
-     * Creates a new PlainCensus
-     * @param censusOrigin - The census origin (defaults to OffchainStatic for backward compatibility)
-     */
-    constructor(censusOrigin?: CensusOrigin);
     /**
-     * Add participant(s) with automatic weight=1
-     * @param addresses - Single address or array of addresses
+     * Check if this census requires publishing via the Census API
+     * Merkle censuses (OffchainStatic, OffchainDynamic) need to be published
+     * Onchain and CSP censuses are ready immediately upon construction
      */
-    add(addresses: string | string[]): void;
-    /**
-     * Remove participant by address
-     */
-    remove(address: string): void;
-    /**
-     * Get all participants as CensusParticipant array (for API)
-     * All participants have weight="1"
-     */
-    get participants(): CensusParticipant[];
-    /**
-     * Get addresses only
-     */
-    get addresses(): string[];
-    private validateAddress;
-    /**
-     * Internal method called after publishing
-     * @internal
-     */
-    _setPublishedData(root: string, uri: string, size: number, censusId?: string): void;
+    get requiresPublishing(): boolean;
 }
 
 /**
- * Participant with flexible weight type for WeightedCensus
+ * Participant with flexible weight type for MerkleCensus
  * Weight can be string, number, or bigint - will be normalized to string internally
  */
-interface WeightedParticipant {
+interface Participant {
     key: string;
     weight: string | number | bigint;
 }
 /**
- * Weighted census where participants can have different voting power
- * Requires specifying weight for each participant
+ * Abstract base class for Merkle Tree censuses
+ * Supports both plain addresses (weight=1) and weighted participants
  */
-declare class WeightedCensus extends Census {
+declare abstract class MerkleCensus extends Census {
     private _participants;
+    constructor(censusOrigin: CensusOrigin);
     /**
-     * Creates a new WeightedCensus
-     * @param censusOrigin - The census origin (defaults to OffchainStatic for backward compatibility)
-     */
-    constructor(censusOrigin?: CensusOrigin);
-    /**
-     * Add participant(s) with custom weights
-     * Weight can be provided as string, number, or bigint - will be converted to string internally
-     * @param participant - Single participant or array of participants with custom weights
+     * Add participant(s) - supports both plain addresses and weighted participants
+     * @param data - Can be:
+     *   - string: single address (weight=1)
+     *   - string[]: array of addresses (weight=1 for all)
+     *   - {key: string, weight: string|number|bigint}: single weighted participant
+     *   - Array of weighted participants
      */
-    add(participant: WeightedParticipant | WeightedParticipant[]): void;
+    add(data: string | string[] | Participant | Participant[]): void;
     /**
      * Remove participant by address
      */
@@ -405,16 +354,58 @@ declare class WeightedCensus extends Census {
      * Get weight for specific address
      */
     getWeight(address: string): string | undefined;
+    /**
+     * Internal method to add a plain address with a given weight
+     */
+    private addAddress;
+    /**
+     * Internal method to add a weighted participant
+     */
+    private addParticipant;
     /**
      * Normalizes weight from string, number, or bigint to string
      */
     private normalizeWeight;
-    private validateParticipant;
+    /**
+     * Validates Ethereum address format
+     */
+    private validateAddress;
     /**
      * Internal method called after publishing
      * @internal
      */
-    _setPublishedData(root: string, uri: string, size: number, censusId?: string): void;
+    _setPublishedData(root: string, uri: string, censusId?: string): void;
+}
+
+/**
+ * Offchain static Merkle Tree census (most common)
+ * Supports both plain addresses (weight=1) and weighted participants
+ */
+declare class OffchainCensus extends MerkleCensus {
+    constructor();
+}
+
+/**
+ * Offchain dynamic Merkle Tree census
+ * Supports both plain addresses (weight=1) and weighted participants
+ */
+declare class OffchainDynamicCensus extends MerkleCensus {
+    constructor();
+}
+
+/**
+ * Onchain census that references a smart contract
+ * Does not require publishing as it references an existing on-chain contract
+ */
+declare class OnchainCensus extends Census {
+    private _contractAddress;
+    /**
+     * Creates an OnchainCensus
+     * @param contractAddress - The address of the smart contract (e.g., ERC20, ERC721)
+     * @param uri - Optional URI with census information
+     */
+    constructor(contractAddress: string, uri?: string);
+    get contractAddress(): string;
 }
 
 /**
@@ -424,25 +415,23 @@ declare class WeightedCensus extends Census {
 declare class CspCensus extends Census {
     private _publicKey;
     private _cspURI;
-    constructor(publicKey: string, cspURI: string, size: number);
+    constructor(publicKey: string, cspURI: string);
     get publicKey(): string;
     get cspURI(): string;
 }
 
 /**
  * Published census - represents a census that has already been published
- * Use this when you have the census root, URI, and size from a previous publication
+ * Use this when you have the census root and URI from a previous publication
  */
 declare class PublishedCensus extends Census {
     /**
      * Creates a PublishedCensus from existing census data
-     * @param type - The census type (PLAIN, WEIGHTED, or CSP)
+     * @param censusOrigin - The census origin (OffchainStatic, OffchainDynamic, Onchain, or CSP)
      * @param root - The census root
      * @param uri - The census URI
-     * @param size - The census size (number of participants)
-     * @param censusOrigin - The census origin (optional - defaults based on type if not provided)
      */
-    constructor(type: CensusType, root: string, uri: string, size: number, censusOrigin?: CensusOrigin);
+    constructor(censusOrigin: CensusOrigin, root: string, uri: string);
 }
 
 /**
@@ -452,19 +441,18 @@ declare class CensusOrchestrator {
     private censusService;
     constructor(censusService: VocdoniCensusService);
     /**
-     * Publishes a PlainCensus or WeightedCensus
+     * Publishes a MerkleCensus (OffchainCensus, OffchainDynamicCensus, or OnchainCensus)
      * Creates a working census, adds participants, and publishes it
      */
-    publish(census: PlainCensus | WeightedCensus): Promise<void>;
+    publish(census: MerkleCensus): Promise<void>;
     /**
      * Gets census data for process creation
-     * Throws if census is not published
+     * Throws if census is not ready (published for Merkle/CSP, or constructed for Onchain)
      */
     getCensusData(census: Census): {
         type: CensusOrigin;
         root: string;
         uri: string;
-        size: number;
     };
 }
 
@@ -1276,8 +1264,10 @@ interface BaseProcessConfig {
         endDate?: Date | string | number;
     };
     /**
-     * Maximum number of voters allowed for this process (optional, defaults to census size)
-     * This parameter limits how many votes can be cast in the process.
+     * Maximum number of voters allowed for this process
+     * Optional only if census is a published MerkleCensus (OffchainCensus/OffchainDynamicCensus)
+     * - defaults to participant count from the census
+     * Required in all other cases (OnchainCensus, CspCensus, manual config, unpublished census)
      */
     maxVoters?: number;
 }
@@ -2713,5 +2703,5 @@ declare class DavinciSDK {
     private ensureProvider;
 }
 
-export { BaseService, Census, CensusNotUpdatable, CensusOrchestrator, CensusOrigin, CensusType, CircomProof, ContractServiceError, CspCensus, DavinciCrypto, DavinciSDK, ElectionMetadataTemplate, ElectionResultsTypeNames, OrganizationAdministratorError, OrganizationCreateError, OrganizationDeleteError, OrganizationRegistryService, OrganizationUpdateError, PlainCensus, ProcessCensusError, ProcessCreateError, ProcessDurationError, ProcessOrchestrationService, ProcessRegistryService, ProcessResultError, ProcessStateTransitionError, ProcessStatus, ProcessStatusError, PublishedCensus, SmartContractService, TxStatus, VocdoniApiService, VocdoniCensusService, VocdoniSequencerService, VoteOrchestrationService, VoteStatus, WeightedCensus, assertCSPCensusProof, assertMerkleCensusProof, createProcessSignatureMessage, getElectionMetadataTemplate, isCSPCensusProof, isMerkleCensusProof, signProcessCreation, validateProcessId };
-export type { AbstainProperties, AnyJson, ApiError, ApprovalProperties, BallotMode, BaseCensusProof, BaseProcess, BudgetProperties, CSPCensusProof, CSPCensusProofProvider, CSPSignOutput, CensusData, CensusParticipant$1 as CensusParticipant, CensusProof, CensusProviders, CensusSizeResponse, Choice, ChoiceProperties, CircomProofOptions, CreateProcessRequest, CreateProcessResponse, CustomMeta, DavinciCryptoCiphertext, DavinciCryptoInputs, DavinciCryptoOptions, DavinciCryptoOutput, DavinciSDKConfig, ElectionMetadata, ElectionResultsType, EncryptionKey, EntityCallback, GetProcessResponse, Groth16Proof, HealthResponse, IChoice, IQuestion, InfoResponse, JsonArray, JsonMap, ListProcessesResponse, MerkleCensusProof, MerkleCensusProofProvider, MultiLanguage, OrganizationAdministratorAddedCallback, OrganizationAdministratorRemovedCallback, OrganizationCreatedCallback, OrganizationInfo, OrganizationUpdatedCallback, ParticipantInfoResponse, ProcessCensusUpdatedCallback, ProcessConfig, ProcessConfigWithMetadata, ProcessConfigWithMetadataUri, ProcessCreatedCallback, ProcessCreationResult, ProcessDurationChangedCallback, ProcessInfo, ProcessMaxVotersChangedCallback, ProcessQuestion, ProcessResultsSetCallback, ProcessStateTransitionedCallback, ProcessStatusChangedCallback, ProofInputs, ProtocolVersion, PublishCensusResponse, QuadraticProperties, Question, SequencerStats, Snapshot, SnapshotsQueryParams, SnapshotsResponse, TxStatusEvent, VocdoniApiServiceConfig, VoteBallot, VoteCiphertext, VoteConfig, VoteOrchestrationConfig, VoteProof, VoteRequest, VoteResult, VoteStatusInfo, VoteStatusResponse, WeightedParticipant, WorkerStats, WorkersResponse };
+export { BaseService, Census, CensusNotUpdatable, CensusOrchestrator, CensusOrigin, CircomProof, ContractServiceError, CspCensus, DavinciCrypto, DavinciSDK, ElectionMetadataTemplate, ElectionResultsTypeNames, MerkleCensus, OffchainCensus, OffchainDynamicCensus, OnchainCensus, OrganizationAdministratorError, OrganizationCreateError, OrganizationDeleteError, OrganizationRegistryService, OrganizationUpdateError, ProcessCensusError, ProcessCreateError, ProcessDurationError, ProcessOrchestrationService, ProcessRegistryService, ProcessResultError, ProcessStateTransitionError, ProcessStatus, ProcessStatusError, PublishedCensus, SmartContractService, TxStatus, VocdoniApiService, VocdoniCensusService, VocdoniSequencerService, VoteOrchestrationService, VoteStatus, assertCSPCensusProof, assertMerkleCensusProof, createProcessSignatureMessage, getElectionMetadataTemplate, isCSPCensusProof, isMerkleCensusProof, signProcessCreation, validateProcessId };
+export type { AbstainProperties, AnyJson, ApiError, ApprovalProperties, BallotMode, BaseCensusProof, BaseProcess, BudgetProperties, CSPCensusProof, CSPCensusProofProvider, CSPSignOutput, CensusData, CensusParticipant, CensusProof, CensusProviders, CensusSizeResponse, Choice, ChoiceProperties, CircomProofOptions, CreateProcessRequest, CreateProcessResponse, CustomMeta, DavinciCryptoCiphertext, DavinciCryptoInputs, DavinciCryptoOptions, DavinciCryptoOutput, DavinciSDKConfig, ElectionMetadata, ElectionResultsType, EncryptionKey, EntityCallback, GetProcessResponse, Groth16Proof, HealthResponse, IChoice, IQuestion, InfoResponse, JsonArray, JsonMap, ListProcessesResponse, MerkleCensusProof, MerkleCensusProofProvider, MultiLanguage, OrganizationAdministratorAddedCallback, OrganizationAdministratorRemovedCallback, OrganizationCreatedCallback, OrganizationInfo, OrganizationUpdatedCallback, Participant, ParticipantInfoResponse, ProcessCensusUpdatedCallback, ProcessConfig, ProcessConfigWithMetadata, ProcessConfigWithMetadataUri, ProcessCreatedCallback, ProcessCreationResult, ProcessDurationChangedCallback, ProcessInfo, ProcessMaxVotersChangedCallback, ProcessQuestion, ProcessResultsSetCallback, ProcessStateTransitionedCallback, ProcessStatusChangedCallback, ProofInputs, ProtocolVersion, PublishCensusResponse, QuadraticProperties, Question, SequencerStats, Snapshot, SnapshotsQueryParams, SnapshotsResponse, TxStatusEvent, VocdoniApiServiceConfig, VoteBallot, VoteCiphertext, VoteConfig, VoteOrchestrationConfig, VoteProof, VoteRequest, VoteResult, VoteStatusInfo, VoteStatusResponse, WorkerStats, WorkersResponse };