@vocdoni/davinci-sdk 0.0.1

package/dist/contracts.d.ts

@@ -0,0 +1,512 @@
+import { ContractTransactionResponse, 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.
+ */
+declare enum TxStatus {
+    /** Transaction has been submitted and is waiting to be mined */
+    Pending = "pending",
+    /** Transaction has been successfully mined and executed */
+    Completed = "completed",
+    /** Transaction was mined but reverted during execution */
+    Reverted = "reverted",
+    /** Transaction failed before or during submission */
+    Failed = "failed"
+}
+/**
+ * Union type representing the different events that can occur during a transaction's lifecycle.
+ * Each event includes relevant data based on the transaction status.
+ *
+ * @template T - The type of the successful response data
+ */
+type TxStatusEvent<T = any> = {
+    status: TxStatus.Pending;
+    hash: string;
+} | {
+    status: TxStatus.Completed;
+    response: T;
+} | {
+    status: TxStatus.Reverted;
+    reason?: string;
+} | {
+    status: TxStatus.Failed;
+    error: Error;
+};
+/**
+ * Abstract base class providing common functionality for smart contract interactions.
+ * Implements transaction handling, status monitoring, and event normalization.
+ */
+declare abstract class SmartContractService {
+    /**
+     * Sends a transaction and yields status events during its lifecycle.
+     * This method handles the complete transaction flow from submission to completion,
+     * including error handling and status updates.
+     *
+     * @template T - The type of the successful response data
+     * @param txPromise - Promise resolving to the transaction response
+     * @param responseHandler - Function to process the successful transaction result
+     * @returns AsyncGenerator yielding transaction status events
+     *
+     * @example
+     * ```typescript
+     * const txStream = await this.sendTx(
+     *   contract.someMethod(),
+     *   async () => await contract.getUpdatedValue()
+     * );
+     *
+     * for await (const event of txStream) {
+     *   switch (event.status) {
+     *     case TxStatus.Pending:
+     *       console.log(`Transaction pending: ${event.hash}`);
+     *       break;
+     *     case TxStatus.Completed:
+     *       console.log(`Transaction completed:`, event.response);
+     *       break;
+     *   }
+     * }
+     * ```
+     */
+    protected sendTx<T>(txPromise: Promise<ContractTransactionResponse>, responseHandler: () => Promise<T>): AsyncGenerator<TxStatusEvent<T>, void, unknown>;
+    /**
+     * Executes a transaction stream and returns the result or throws an error.
+     * This is a convenience method that processes a transaction stream and either
+     * returns the successful result or throws an appropriate error.
+     *
+     * @template T - The type of the successful response data
+     * @param stream - AsyncGenerator of transaction status events
+     * @returns Promise resolving to the successful response data
+     * @throws Error if the transaction fails or reverts
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await SmartContractService.executeTx(
+     *     contract.someMethod()
+     *   );
+     *   console.log('Transaction successful:', result);
+     * } catch (error) {
+     *   console.error('Transaction failed:', error);
+     * }
+     * ```
+     */
+    static executeTx<T>(stream: AsyncGenerator<TxStatusEvent<T>>): Promise<T>;
+    /**
+     * Normalizes event listener arguments between different ethers.js versions.
+     * This helper method ensures consistent event argument handling regardless of
+     * whether the event payload follows ethers v5 or v6 format.
+     *
+     * @template Args - Tuple type representing the expected event arguments
+     * @param callback - The event callback function to normalize
+     * @returns Normalized event listener function
+     *
+     * @example
+     * ```typescript
+     * contract.on('Transfer', this.normalizeListener((from: string, to: string, amount: BigInt) => {
+     *   console.log(`Transfer from ${from} to ${to}: ${amount}`);
+     * }));
+     * ```
+     */
+    protected normalizeListener<Args extends any[]>(callback: (...args: Args) => void): (...listenerArgs: any[]) => void;
+}
+
+/**
+ * @fileoverview Standardized error classes for contract services
+ *
+ * This module provides a consistent error hierarchy for all contract service operations.
+ * All errors extend from ContractServiceError and include operation context for better debugging.
+ */
+/**
+ * Abstract base class for all contract service errors.
+ * Provides consistent error structure with operation context.
+ */
+declare abstract class ContractServiceError extends Error {
+    readonly operation: string;
+    /**
+     * Creates a new ContractServiceError instance.
+     *
+     * @param message - The error message describing what went wrong
+     * @param operation - The operation that was being performed when the error occurred
+     */
+    constructor(message: string, operation: string);
+}
+/**
+ * Error thrown when organization creation fails.
+ */
+declare class OrganizationCreateError extends ContractServiceError {
+}
+/**
+ * Error thrown when organization update fails.
+ */
+declare class OrganizationUpdateError extends ContractServiceError {
+}
+/**
+ * Error thrown when organization deletion fails.
+ */
+declare class OrganizationDeleteError extends ContractServiceError {
+}
+/**
+ * Error thrown when administrator operations fail.
+ */
+declare class OrganizationAdministratorError extends ContractServiceError {
+}
+/**
+ * Error thrown when process creation fails.
+ */
+declare class ProcessCreateError extends ContractServiceError {
+}
+/**
+ * Error thrown when process status change fails.
+ */
+declare class ProcessStatusError extends ContractServiceError {
+}
+/**
+ * Error thrown when process census update fails.
+ */
+declare class ProcessCensusError extends ContractServiceError {
+}
+/**
+ * Error thrown when process duration change fails.
+ */
+declare class ProcessDurationError extends ContractServiceError {
+}
+/**
+ * Error thrown when state transition submission fails.
+ */
+declare class ProcessStateTransitionError extends ContractServiceError {
+}
+/**
+ * Error thrown when process result setting fails.
+ */
+declare class ProcessResultError extends ContractServiceError {
+}
+
+/**
+ * @fileoverview Standardized types and interfaces for contract services
+ *
+ * This module provides consistent type definitions for callbacks, interfaces,
+ * and common data structures used across contract services.
+ */
+/**
+ * Generic callback type for contract events.
+ * @template T - Tuple type representing the event arguments
+ */
+type EntityCallback<T extends any[]> = (...args: T) => void;
+/**
+ * Callback for when an organization is created.
+ * @param id - The organization ID
+ */
+type OrganizationCreatedCallback = EntityCallback<[string]>;
+/**
+ * Callback for when an organization is updated.
+ * @param id - The organization ID
+ * @param updater - Address of the account that updated the organization
+ */
+type OrganizationUpdatedCallback = EntityCallback<[string, string]>;
+/**
+ * Callback for when an administrator is added to an organization.
+ * @param id - The organization ID
+ * @param administrator - Address of the administrator that was added
+ */
+type OrganizationAdministratorAddedCallback = EntityCallback<[string, string]>;
+/**
+ * Callback for when an administrator is removed from an organization.
+ * @param id - The organization ID
+ * @param administrator - Address of the administrator that was removed
+ * @param remover - Address of the account that removed the administrator
+ */
+type OrganizationAdministratorRemovedCallback = EntityCallback<[string, string, string]>;
+/**
+ * Callback for when a process is created.
+ * @param processID - The process ID
+ * @param creator - Address of the account that created the process
+ */
+type ProcessCreatedCallback = EntityCallback<[string, string]>;
+/**
+ * Callback for when a process status changes.
+ * @param processID - The process ID
+ * @param oldStatus - The previous status
+ * @param newStatus - The new status
+ */
+type ProcessStatusChangedCallback = EntityCallback<[string, bigint, bigint]>;
+/**
+ * Callback for when a process census is updated.
+ * @param processID - The process ID
+ * @param root - The new census root
+ * @param uri - The new census URI
+ * @param maxVotes - The maximum number of votes
+ */
+type ProcessCensusUpdatedCallback = EntityCallback<[string, string, string, bigint]>;
+/**
+ * Callback for when a process duration changes.
+ * @param processID - The process ID
+ * @param duration - The new duration
+ */
+type ProcessDurationChangedCallback = EntityCallback<[string, bigint]>;
+/**
+ * Callback for when a process state root is updated.
+ * @param processID - The process ID
+ * @param sender - Address of the account that updated the state root
+ * @param newStateRoot - The new state root
+ */
+type ProcessStateRootUpdatedCallback = EntityCallback<[string, string, bigint]>;
+/**
+ * Callback for when process results are set.
+ * @param processID - The process ID
+ * @param sender - Address of the account that set the results
+ * @param result - The results array
+ */
+type ProcessResultsSetCallback = EntityCallback<[string, string, bigint[]]>;
+
+interface OrganizationInfo {
+    name: string;
+    metadataURI: string;
+}
+declare class OrganizationRegistryService extends SmartContractService {
+    private contract;
+    constructor(contractAddress: string, runner: ContractRunner);
+    getOrganization(id: string): Promise<OrganizationInfo>;
+    existsOrganization(id: string): Promise<boolean>;
+    isAdministrator(id: string, address: string): Promise<boolean>;
+    getOrganizationCount(): Promise<number>;
+    createOrganization(name: string, metadataURI: string, administrators: string[]): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    updateOrganization(id: string, name: string, metadataURI: string): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    addAdministrator(id: string, administrator: string): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    removeAdministrator(id: string, administrator: string): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    deleteOrganization(id: string): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    onOrganizationCreated(cb: OrganizationCreatedCallback): void;
+    onOrganizationUpdated(cb: OrganizationUpdatedCallback): void;
+    onAdministratorAdded(cb: OrganizationAdministratorAddedCallback): void;
+    onAdministratorRemoved(cb: OrganizationAdministratorRemovedCallback): void;
+    removeAllListeners(): void;
+}
+
+/**
+ * Census origin types
+ */
+declare enum CensusOrigin {
+    /** Indicates that the census is derived from a Merkle Tree structure */
+    CensusOriginMerkleTree = 1,
+    /** Indicates that the census is provided by a Credential Service Provider (CSP) */
+    CensusOriginCSP = 2
+}
+
+interface BallotMode {
+    numFields: number;
+    maxValue: string;
+    minValue: string;
+    uniqueValues: boolean;
+    costFromWeight: boolean;
+    costExponent: number;
+    maxValueSum: string;
+    minValueSum: string;
+}
+interface Census {
+    censusOrigin: CensusOrigin;
+    maxVotes: string;
+    censusRoot: string;
+    censusURI: string;
+}
+interface EncryptionKey {
+    x: string;
+    y: string;
+}
+
+interface ProofInputs {
+    fields: string[];
+    num_fields: string;
+    unique_values: string;
+    max_value: string;
+    min_value: string;
+    max_value_sum: string;
+    min_value_sum: string;
+    cost_exponent: string;
+    cost_from_weight: string;
+    address: string;
+    weight: string;
+    process_id: string;
+    vote_id: string;
+    encryption_pubkey: [string, string];
+    k: string;
+    cipherfields: string[];
+    inputs_hash: string;
+}
+
+interface DavinciCryptoCiphertext {
+    c1: [string, string];
+    c2: [string, string];
+}
+interface DavinciCryptoOutput {
+    processId: string;
+    address: string;
+    ballot: {
+        curveType: string;
+        ciphertexts: DavinciCryptoCiphertext[];
+    };
+    ballotInputsHash: string;
+    voteId: string;
+    circomInputs: ProofInputs;
+}
+interface CSPSignOutput {
+    censusOrigin: CensusOrigin;
+    root: string;
+    address: string;
+    processId: string;
+    publicKey: string;
+    signature: string;
+}
+interface RawResult<T = any> {
+    error?: string;
+    data?: T;
+}
+interface GoDavinciCryptoWasm {
+    proofInputs(inputJson: string): RawResult<DavinciCryptoOutput>;
+    cspSign(censusOrigin: number, privKey: string, processId: string, address: string): RawResult<CSPSignOutput>;
+    cspVerify(cspProof: string): RawResult<boolean>;
+    cspCensusRoot(censusOrigin: number, privKey: string): RawResult<{
+        root: string;
+    }>;
+}
+declare global {
+    var Go: new () => {
+        importObject: Record<string, any>;
+        run(instance: WebAssembly.Instance): Promise<void>;
+    };
+    var DavinciCrypto: GoDavinciCryptoWasm;
+}
+
+declare enum ProcessStatus {
+    READY = 0,
+    ENDED = 1,
+    CANCELED = 2,
+    PAUSED = 3,
+    RESULTS = 4
+}
+declare class ProcessRegistryService extends SmartContractService {
+    private contract;
+    constructor(contractAddress: string, runner: ContractRunner);
+    getProcess(processID: string): Promise<_vocdoni_davinci_contracts_dist_src_ProcessRegistry.IProcessRegistry.ProcessStructOutput>;
+    getProcessCount(): Promise<number>;
+    getChainID(): Promise<string>;
+    getNextProcessId(organizationId: string): Promise<string>;
+    getProcessEndTime(processID: string): Promise<bigint>;
+    getRVerifierVKeyHash(): Promise<string>;
+    getSTVerifierVKeyHash(): Promise<string>;
+    getMaxCensusOrigin(): Promise<bigint>;
+    getMaxStatus(): Promise<bigint>;
+    getProcessNonce(address: string): Promise<bigint>;
+    getProcessDirect(processID: string): Promise<[bigint, string, _vocdoni_davinci_contracts_dist_src_ProcessRegistry.IProcessRegistry.EncryptionKeyStructOutput, bigint, bigint, bigint, bigint, bigint, bigint, bigint, string, _vocdoni_davinci_contracts_dist_src_ProcessRegistry.IProcessRegistry.BallotModeStructOutput, _vocdoni_davinci_contracts_dist_src_ProcessRegistry.IProcessRegistry.CensusStructOutput] & {
+        status: bigint;
+        organizationId: string;
+        encryptionKey: _vocdoni_davinci_contracts_dist_src_ProcessRegistry.IProcessRegistry.EncryptionKeyStructOutput;
+        latestStateRoot: bigint;
+        startTime: bigint;
+        duration: bigint;
+        voteCount: bigint;
+        voteOverwriteCount: bigint;
+        creationBlock: bigint;
+        batchNumber: bigint;
+        metadataURI: string;
+        ballotMode: _vocdoni_davinci_contracts_dist_src_ProcessRegistry.IProcessRegistry.BallotModeStructOutput;
+        census: _vocdoni_davinci_contracts_dist_src_ProcessRegistry.IProcessRegistry.CensusStructOutput;
+    }>;
+    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<{
+        success: boolean;
+    }>, void, unknown>;
+    setProcessStatus(processID: string, newStatus: ProcessStatus): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    setProcessCensus(processID: string, census: Census): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    setProcessDuration(processID: string, duration: number): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    /**
+     * Matches the on-chain `submitStateTransition(processId, proof, input)`
+     */
+    submitStateTransition(processID: string, proof: string, input: string): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    /**
+     * Sets the results for a voting process.
+     *
+     * @param processID - The ID of the process to set results for
+     * @param proof - Zero-knowledge proof validating the results
+     * @param input - Input data for the proof verification
+     * @returns A transaction stream that resolves to success status
+     */
+    setProcessResults(processID: string, proof: string, input: string): AsyncGenerator<TxStatusEvent<{
+        success: boolean;
+    }>, void, unknown>;
+    onProcessCreated(cb: ProcessCreatedCallback): void;
+    onProcessStatusChanged(cb: ProcessStatusChangedCallback): void;
+    onCensusUpdated(cb: ProcessCensusUpdatedCallback): void;
+    onProcessDurationChanged(cb: ProcessDurationChangedCallback): void;
+    onStateRootUpdated(cb: ProcessStateRootUpdatedCallback): void;
+    onProcessResultsSet(cb: ProcessResultsSetCallback): void;
+    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 };