@vocdoni/davinci-sdk 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -113,7 +113,7 @@ declare enum CensusOrigin {
     /** Indicates that the census is provided by a Credential Service Provider (CSP) */
     CensusOriginCSP = 2
 }
-interface CensusParticipant {
+interface CensusParticipant$1 {
     key: string;
     weight?: string;
 }
@@ -269,8 +269,8 @@ declare class VocdoniCensusService extends BaseService {
      */
     getCensusUri(censusRoot: string): string;
     createCensus(): Promise<string>;
-    addParticipants(censusId: string, participants: CensusParticipant[]): Promise<void>;
-    getParticipants(censusId: string): Promise<CensusParticipant[]>;
+    addParticipants(censusId: string, participants: CensusParticipant$1[]): Promise<void>;
+    getParticipants(censusId: string): Promise<CensusParticipant$1[]>;
     getCensusRoot(censusId: string): Promise<string>;
     getCensusSizeById(censusId: string): Promise<number>;
     getCensusSizeByRoot(censusRoot: string): Promise<number>;
@@ -283,6 +283,168 @@ 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
+ */
+declare abstract class Census {
+    protected _censusId: string | null;
+    protected _censusRoot: string | null;
+    protected _censusURI: string | null;
+    protected _type: CensusType;
+    protected _size: number | null;
+    constructor(type: CensusType);
+    get censusId(): string | null;
+    get censusRoot(): string | null;
+    get censusURI(): string | null;
+    get type(): CensusType;
+    get size(): number | null;
+    get isPublished(): boolean;
+    /**
+     * Convert CensusType to CensusOrigin enum for API compatibility
+     */
+    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;
+    constructor();
+    /**
+     * Add participant(s) with automatic weight=1
+     * @param addresses - Single address or array of addresses
+     */
+    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;
+}
+
+/**
+ * Participant with flexible weight type for WeightedCensus
+ * Weight can be string, number, or bigint - will be normalized to string internally
+ */
+interface WeightedParticipant {
+    key: string;
+    weight: string | number | bigint;
+}
+/**
+ * Weighted census where participants can have different voting power
+ * Requires specifying weight for each participant
+ */
+declare class WeightedCensus extends Census {
+    private _participants;
+    constructor();
+    /**
+     * 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: WeightedParticipant | WeightedParticipant[]): void;
+    /**
+     * Remove participant by address
+     */
+    remove(address: string): void;
+    /**
+     * Get all participants as CensusParticipant array
+     */
+    get participants(): CensusParticipant[];
+    /**
+     * Get participant addresses
+     */
+    get addresses(): string[];
+    /**
+     * Get weight for specific address
+     */
+    getWeight(address: string): string | undefined;
+    /**
+     * Normalizes weight from string, number, or bigint to string
+     */
+    private normalizeWeight;
+    private validateParticipant;
+    /**
+     * Internal method called after publishing
+     * @internal
+     */
+    _setPublishedData(root: string, uri: string, size: number, censusId?: string): void;
+}
+
+/**
+ * CSP (Certificate Service Provider) census
+ * Uses a public key and CSP server URI instead of a participant list
+ */
+declare class CspCensus extends Census {
+    private _publicKey;
+    private _cspURI;
+    constructor(publicKey: string, cspURI: string, size: number);
+    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
+ */
+declare class PublishedCensus extends Census {
+    constructor(type: CensusType, root: string, uri: string, size: number);
+}
+
+/**
+ * Orchestrates census creation and publishing
+ */
+declare class CensusOrchestrator {
+    private censusService;
+    constructor(censusService: VocdoniCensusService);
+    /**
+     * Publishes a PlainCensus or WeightedCensus
+     * Creates a working census, adds participants, and publishes it
+     */
+    publish(census: PlainCensus | WeightedCensus): Promise<void>;
+    /**
+     * Gets census data for process creation
+     * Throws if census is not published
+     */
+    getCensusData(census: Census): {
+        type: CensusOrigin;
+        root: string;
+        uri: string;
+        size: number;
+    };
+}
+
 interface BallotMode {
     numFields: number;
     maxValue: string;
@@ -293,7 +455,7 @@ interface BallotMode {
     maxValueSum: string;
     minValueSum: string;
 }
-interface Census {
+interface CensusData {
     censusOrigin: CensusOrigin;
     maxVotes: string;
     censusRoot: string;
@@ -332,7 +494,7 @@ interface GetProcessResponse {
     duration: number;
     metadataURI: string;
     ballotMode: BallotMode;
-    census: Census;
+    census: CensusData;
     metadata: {
         title: Record<string, string>;
         description: Record<string, string>;
@@ -481,118 +643,6 @@ declare class VocdoniApiService {
     constructor(config: VocdoniApiServiceConfig);
 }
 
-/**
- * Supported environment types
- */
-type Environment = 'dev' | 'stg' | 'prod';
-/**
- * URL configuration for each service
- */
-interface ServiceUrls {
-    /** Sequencer API URL */
-    sequencer: string;
-    /** Census API URL */
-    census: string;
-}
-/**
- * Chain configuration for each environment
- */
-interface ChainConfig {
-    /** Chain name/ID */
-    chain: 'sepolia' | 'mainnet';
-}
-/**
- * Environment-based URL configuration
- */
-interface EnvironmentConfig {
-    dev: ServiceUrls & ChainConfig;
-    stg: ServiceUrls & ChainConfig;
-    prod: ServiceUrls & ChainConfig;
-}
-/**
- * Configuration options for environment setup
- */
-interface EnvironmentOptions {
-    /** Environment to use (defaults to 'prod') */
-    environment?: Environment;
-    /** Custom URLs to override defaults */
-    customUrls?: Partial<ServiceUrls>;
-    /** Custom chain to override default */
-    customChain?: ChainConfig['chain'];
-}
-
-/**
- * Default URL and chain configuration for all environments
- */
-declare const DEFAULT_ENVIRONMENT_URLS: EnvironmentConfig;
-/**
- * Get URLs and chain configuration for a specific environment
- */
-declare function getEnvironmentConfig(environment: Environment): ServiceUrls & ChainConfig;
-/**
- * Get only URLs for a specific environment
- */
-declare function getEnvironmentUrls(environment: Environment): ServiceUrls;
-/**
- * Get chain configuration for a specific environment
- */
-declare function getEnvironmentChain(environment: Environment): ChainConfig['chain'];
-/**
- * Resolve URLs and chain based on environment and custom overrides
- */
-declare function resolveConfiguration(options?: EnvironmentOptions): ServiceUrls & ChainConfig;
-/**
- * Resolve only URLs based on environment and custom overrides
- */
-declare function resolveUrls(options?: EnvironmentOptions): ServiceUrls;
-
-/**
- * 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.
@@ -729,10 +779,13 @@ declare abstract class SmartContractService {
      */
     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).
+     * 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 method
+     * @returns true if the error indicates unsupported or broken filter functionality
      */
     private isUnsupportedMethodError;
     /**
@@ -872,13 +925,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<{
@@ -1171,7 +1224,22 @@ interface BaseProcess {
 /**
  * Configuration for creating a process
  */
-interface ProcessConfig extends BaseProcess {
+interface ProcessConfig extends Omit<BaseProcess, 'census'> {
+    /**
+     * Census - either a Census object (PlainCensus, WeightedCensus, CspCensus, PublishedCensus)
+     * or manual configuration. If a Census object is provided and not published, it will be
+     * automatically published.
+     */
+    census: Census | {
+        /** Census type - MerkleTree or CSP */
+        type: CensusOrigin;
+        /** Census root */
+        root: string;
+        /** Census size */
+        size: number;
+        /** Census URI */
+        uri: string;
+    };
     /** Process timing - use either duration-based or date-based configuration */
     timing: {
         /** Start date/time (Date object, ISO string, or Unix timestamp, default: now + 60 seconds) */
@@ -1229,7 +1297,13 @@ declare class ProcessOrchestrationService {
     private organizationRegistry;
     private getCrypto;
     private signer;
+    private censusOrchestrator;
     constructor(processRegistry: ProcessRegistryService, apiService: VocdoniApiService, organizationRegistry: OrganizationRegistryService, getCrypto: () => Promise<DavinciCrypto>, signer: Signer);
+    /**
+     * Handles census - auto-publishes if needed and returns census config
+     * @private
+     */
+    private handleCensus;
     /**
      * Gets user-friendly process information by transforming raw contract data
      * @param processId - The process ID to fetch
@@ -1541,6 +1615,15 @@ interface VoteStatusInfo {
     /** The process ID */
     processId: string;
 }
+/**
+ * Configuration options for VoteOrchestrationService
+ */
+interface VoteOrchestrationConfig {
+    /** Whether to verify downloaded circuit files match expected hashes (default: true) */
+    verifyCircuitFiles?: boolean;
+    /** Whether to verify the generated proof is valid before submission (default: true) */
+    verifyProof?: boolean;
+}
 /**
  * Service that orchestrates the complete voting workflow
  * Handles all the complex cryptographic operations and API calls internally
@@ -1550,7 +1633,9 @@ declare class VoteOrchestrationService {
     private getCrypto;
     private signer;
     private censusProviders;
-    constructor(apiService: VocdoniApiService, getCrypto: () => Promise<DavinciCrypto>, signer: Signer, censusProviders?: CensusProviders);
+    private readonly verifyCircuitFiles;
+    private readonly verifyProof;
+    constructor(apiService: VocdoniApiService, getCrypto: () => Promise<DavinciCrypto>, signer: Signer, censusProviders?: CensusProviders, config?: VoteOrchestrationConfig);
     /**
      * Submit a vote with simplified configuration
      * This method handles all the complex orchestration internally:
@@ -1754,43 +1839,42 @@ interface DavinciSDKConfig {
      * - For process/organization operations: Must be connected to a provider
      */
     signer: Signer;
-    /** Environment to use (dev, stg, prod) - used to set default URLs and chain if not explicitly provided */
-    environment?: Environment;
-    /** Sequencer API URL for Vocdoni services (optional, defaults based on environment) */
-    sequencerUrl?: string;
-    /** Census API URL for census management (optional, defaults based on environment) */
+    /** Sequencer API URL for Vocdoni services (required) */
+    sequencerUrl: string;
+    /** Census API URL for census management (optional, only needed when creating censuses from scratch) */
     censusUrl?: string;
-    /** Chain name (optional, defaults based on environment) */
-    chain?: 'sepolia' | 'mainnet';
-    /** Custom contract addresses (optional, uses defaults if not provided) */
-    contractAddresses?: {
+    /** Custom contract addresses (optional, fetched from sequencer if not provided) */
+    addresses?: {
         processRegistry?: string;
         organizationRegistry?: string;
         stateTransitionVerifier?: string;
         resultsVerifier?: string;
         sequencerRegistry?: string;
     };
-    /** Whether to force using contract addresses from sequencer info (optional, defaults to false) */
-    useSequencerAddresses?: boolean;
     /** Custom census proof providers (optional) */
     censusProviders?: CensusProviders;
+    /** Whether to verify downloaded circuit files match expected hashes (optional, defaults to true) */
+    verifyCircuitFiles?: boolean;
+    /** Whether to verify the generated proof is valid before submission (optional, defaults to true) */
+    verifyProof?: boolean;
 }
 /**
- * Internal configuration interface (without environment)
+ * Internal configuration interface
  */
 interface InternalDavinciSDKConfig {
     signer: Signer;
     sequencerUrl: string;
-    censusUrl: string;
-    chain: 'sepolia' | 'mainnet';
-    contractAddresses: {
+    censusUrl?: string;
+    customAddresses: {
         processRegistry?: string;
         organizationRegistry?: string;
         stateTransitionVerifier?: string;
         resultsVerifier?: string;
         sequencerRegistry?: string;
     };
-    useSequencerAddresses: boolean;
+    fetchAddressesFromSequencer: boolean;
+    verifyCircuitFiles: boolean;
+    verifyProof: boolean;
 }
 /**
  * Simplified SDK class that encapsulates all Vocdoni DaVinci functionality
@@ -2023,6 +2107,7 @@ declare class DavinciSDK {
      * 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.
+     * IMPORTANT: Requires censusUrl to be configured in the SDK for fetching census proofs (unless using custom census providers).
      *
      * The method automatically:
      * - Fetches process information and validates voting is allowed
@@ -2032,6 +2117,7 @@ declare class DavinciSDK {
      *
      * @param config - Simplified vote configuration
      * @returns Promise resolving to vote submission result
+     * @throws Error if censusUrl is not configured (unless using custom census providers)
      *
      * @example
      * ```typescript
@@ -2395,20 +2481,15 @@ declare class DavinciSDK {
     resumeProcess(processId: string): Promise<void>;
     /**
      * Resolve contract address based on configuration priority:
-     * 1. If useSequencerAddresses is true: addresses from sequencer (highest priority)
-     * 2. Custom addresses from config (if provided by user)
-     * 3. Default deployed addresses from npm package
+     * 1. Custom addresses from user config (if provided)
+     * 2. Addresses from sequencer (fetched during init if no custom addresses provided)
      */
     private resolveContractAddress;
     /**
-     * Get default contract address from deployed addresses
-     */
-    private getDefaultContractAddress;
-    /**
-     * Update contract addresses from sequencer info if useSequencerAddresses is enabled
-     * Sequencer addresses have priority over user-provided addresses
+     * Fetch contract addresses from sequencer info
+     * This is called during init() if custom addresses are not provided
      */
-    private updateContractAddressesFromSequencer;
+    private fetchContractAddressesFromSequencer;
     /**
      * Get the current configuration
      */
@@ -2425,5 +2506,5 @@ declare class DavinciSDK {
     private ensureProvider;
 }
 
-export { BaseService, CensusOrigin, CircomProof, ContractServiceError, DEFAULT_ENVIRONMENT_URLS, DavinciCrypto, DavinciSDK, ElectionMetadataTemplate, ElectionResultsTypeNames, OrganizationAdministratorError, OrganizationCreateError, OrganizationDeleteError, OrganizationRegistryService, OrganizationUpdateError, ProcessCensusError, ProcessCreateError, ProcessDurationError, ProcessOrchestrationService, ProcessRegistryService, ProcessResultError, ProcessStateTransitionError, ProcessStatus, ProcessStatusError, SmartContractService, TxStatus, VocdoniApiService, VocdoniCensusService, VocdoniSequencerService, VoteOrchestrationService, VoteStatus, assertCSPCensusProof, assertMerkleCensusProof, createProcessSignatureMessage, deployedAddresses, getElectionMetadataTemplate, getEnvironmentChain, getEnvironmentConfig, getEnvironmentUrls, isCSPCensusProof, isMerkleCensusProof, resolveConfiguration, resolveUrls, signProcessCreation, validateProcessId };
-export type { AbstainProperties, AnyJson, ApiError, ApprovalProperties, BallotMode, BaseCensusProof, BaseProcess, BudgetProperties, CSPCensusProof, CSPCensusProofProvider, CSPSignOutput, Census, CensusParticipant, CensusProof, CensusProviders, CensusSizeResponse, ChainConfig, Choice, ChoiceProperties, CircomProofOptions, CreateProcessRequest, CreateProcessResponse, CustomMeta, DavinciCryptoCiphertext, DavinciCryptoInputs, DavinciCryptoOptions, DavinciCryptoOutput, DavinciSDKConfig, DeployedAddresses, ElectionMetadata, ElectionResultsType, EncryptionKey, EntityCallback, Environment, EnvironmentConfig, EnvironmentOptions, GetProcessResponse, Groth16Proof, HealthResponse, IChoice, IQuestion, InfoResponse, JsonArray, JsonMap, ListProcessesResponse, MerkleCensusProof, MerkleCensusProofProvider, MultiLanguage, OrganizationAdministratorAddedCallback, OrganizationAdministratorRemovedCallback, OrganizationCreatedCallback, OrganizationInfo, OrganizationUpdatedCallback, ProcessCensusUpdatedCallback, ProcessConfig, ProcessCreatedCallback, ProcessCreationResult, ProcessDurationChangedCallback, ProcessInfo, ProcessResultsSetCallback, ProcessStateRootUpdatedCallback, ProcessStatusChangedCallback, ProofInputs, ProtocolVersion, PublishCensusResponse, QuadraticProperties, Question, SequencerStats, ServiceUrls, Snapshot, SnapshotsQueryParams, SnapshotsResponse, TxStatusEvent, VocdoniApiServiceConfig, VoteBallot, VoteCiphertext, VoteConfig, VoteProof, VoteRequest, VoteResult, VoteStatusInfo, VoteStatusResponse, WorkerStats, WorkersResponse };
+export { BaseService, Census, 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, ProcessCensusUpdatedCallback, ProcessConfig, ProcessCreatedCallback, ProcessCreationResult, ProcessDurationChangedCallback, ProcessInfo, ProcessResultsSetCallback, ProcessStateRootUpdatedCallback, ProcessStatusChangedCallback, ProofInputs, ProtocolVersion, PublishCensusResponse, QuadraticProperties, Question, SequencerStats, Snapshot, SnapshotsQueryParams, SnapshotsResponse, TxStatusEvent, VocdoniApiServiceConfig, VoteBallot, VoteCiphertext, VoteConfig, VoteOrchestrationConfig, VoteProof, VoteRequest, VoteResult, VoteStatusInfo, VoteStatusResponse, WeightedParticipant, WorkerStats, WorkersResponse };