@vocdoni/davinci-sdk 0.0.1

package/dist/sequencer.d.ts

@@ -0,0 +1,538 @@
+import { Signer, Wallet } from 'ethers';
+import { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+type AnyJson = boolean | number | string | null | JsonArray | JsonMap | any;
+interface JsonMap {
+    [key: string]: AnyJson;
+}
+interface JsonArray extends Array<AnyJson> {
+}
+type CustomMeta = AnyJson | JsonArray | JsonMap;
+type MultiLanguage<T> = {
+    default: T;
+    [lang: string]: T;
+};
+interface IChoice {
+    title: MultiLanguage<string>;
+    value: number;
+    meta?: CustomMeta;
+    results?: string;
+    answer?: number;
+}
+interface IQuestion {
+    title: MultiLanguage<string>;
+    description?: MultiLanguage<string>;
+    numAbstains?: string;
+    meta?: CustomMeta;
+    choices: Array<IChoice>;
+}
+declare enum ElectionResultsTypeNames {
+    SINGLE_CHOICE_MULTIQUESTION = "single-choice-multiquestion",
+    MULTIPLE_CHOICE = "multiple-choice",
+    BUDGET = "budget-based",
+    APPROVAL = "approval",
+    QUADRATIC = "quadratic"
+}
+interface AbstainProperties {
+    canAbstain: boolean;
+    abstainValues: Array<string>;
+}
+interface ChoiceProperties {
+    repeatChoice: boolean;
+    numChoices: {
+        min: number;
+        max: number;
+    };
+}
+interface BudgetProperties {
+    useCensusWeightAsBudget: boolean;
+    maxBudget: number;
+    minStep: number;
+    forceFullBudget: boolean;
+}
+interface ApprovalProperties {
+    rejectValue: number;
+    acceptValue: number;
+}
+interface QuadraticProperties extends BudgetProperties {
+    quadraticCost: number;
+}
+type ElectionResultsType = {
+    name: ElectionResultsTypeNames.SINGLE_CHOICE_MULTIQUESTION;
+    properties: Record<string, never>;
+} | {
+    name: ElectionResultsTypeNames.MULTIPLE_CHOICE;
+    properties: AbstainProperties & ChoiceProperties;
+} | {
+    name: ElectionResultsTypeNames.BUDGET;
+    properties: BudgetProperties;
+} | {
+    name: ElectionResultsTypeNames.APPROVAL;
+    properties: ApprovalProperties;
+} | {
+    name: ElectionResultsTypeNames.QUADRATIC;
+    properties: QuadraticProperties;
+};
+type ProtocolVersion = '1.1' | '1.2';
+interface ElectionMetadata {
+    version: ProtocolVersion;
+    title: MultiLanguage<string>;
+    description: MultiLanguage<string>;
+    media: {
+        header: string;
+        logo: string;
+    };
+    meta?: {
+        [key: string]: any;
+    };
+    questions: Array<IQuestion>;
+    type: ElectionResultsType;
+}
+
+declare class BaseService {
+    protected axios: AxiosInstance;
+    constructor(baseURL: string, config?: AxiosRequestConfig);
+    protected request<T>(config: AxiosRequestConfig): Promise<T>;
+}
+
+/**
+ * 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 BaseCensusProof {
+    /** The Merkle root (hex-prefixed). */
+    root: string;
+    /** The voter's address (hex-prefixed). */
+    address: string;
+    /** The weight as a decimal string. */
+    weight: string;
+    /** Census origin type: CensusOriginMerkleTree for merkle proofs, CensusOriginCSP for csp proofs */
+    censusOrigin: CensusOrigin;
+}
+interface MerkleCensusProof extends BaseCensusProof {
+    censusOrigin: CensusOrigin.CensusOriginMerkleTree;
+    /** The leaf value (hex-prefixed weight). */
+    value: string;
+    /** The serialized sibling path (hex-prefixed). */
+    siblings: string;
+}
+interface CSPCensusProof extends BaseCensusProof {
+    censusOrigin: CensusOrigin.CensusOriginCSP;
+    /** The process id signed with the address (hex-prefixed). */
+    processId: string;
+    /** The public key of the csp (hex-prefixed). */
+    publicKey: string;
+    /** The signature that proves that the voter is in the census (hex-prefixed). */
+    signature: string;
+}
+type CensusProof = MerkleCensusProof | CSPCensusProof;
+
+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 CreateProcessRequest {
+    processId: string;
+    censusRoot: string;
+    ballotMode: BallotMode;
+    signature: string;
+    /**
+     * The censusOrigin specifies the origin type of the census used in the request.
+     * This attribute allows the API to determine how the census data should be processed or verified.
+     */
+    censusOrigin: CensusOrigin;
+}
+interface CreateProcessResponse {
+    processId: string;
+    encryptionPubKey: [string, string];
+    stateRoot: string;
+    ballotMode: BallotMode;
+}
+interface GetProcessResponse {
+    id: string;
+    status: number;
+    organizationId: string;
+    encryptionKey: EncryptionKey;
+    stateRoot: string;
+    result: string[];
+    startTime: number;
+    duration: number;
+    metadataURI: string;
+    ballotMode: BallotMode;
+    census: Census;
+    metadata: {
+        title: Record<string, string>;
+        description: Record<string, string>;
+        media: {
+            header: string;
+            logo: string;
+        };
+        questions: {
+            title: Record<string, string>;
+            description: Record<string, string>;
+            choices: {
+                title: Record<string, string>;
+                value: number;
+                meta: Record<string, string>;
+            }[];
+            meta: Record<string, string>;
+        }[];
+        processType: {
+            name: string;
+            properties: Record<string, string>;
+        };
+    };
+    voteCount: string;
+    voteOverwrittenCount: string;
+    isAcceptingVotes: boolean;
+    sequencerStats: {
+        stateTransitionCount: number;
+        lastStateTransitionDate: string;
+        settledStateTransitionCount: number;
+        aggregatedVotesCount: number;
+        verifiedVotesCount: number;
+        pendingVotesCount: number;
+        currentBatchSize: number;
+        lastBatchSize: number;
+    };
+}
+interface VoteCiphertext {
+    c1: [string, string];
+    c2: [string, string];
+}
+interface VoteBallot {
+    curveType: string;
+    ciphertexts: VoteCiphertext[];
+}
+interface VoteProof {
+    pi_a: [string, string, string];
+    pi_b: [[string, string], [string, string], [string, string]];
+    pi_c: [string, string, string];
+    protocol: string;
+}
+interface VoteRequest {
+    /** The `processId` you obtained when creating the process. */
+    processId: string;
+    /** Your Merkle‐proof that you're in the census. */
+    censusProof: CensusProof;
+    /** Your encrypted ballot. */
+    ballot: VoteBallot;
+    /** The zkSNARK proof that the ballot is well‐formed. */
+    ballotProof: VoteProof;
+    /** Hash of the ballot inputs (decimal string). */
+    ballotInputsHash: string;
+    /** Your Ethereum address (hex-prefixed). */
+    address: string;
+    /** Signature over the raw bytes of the voteId. */
+    signature: string;
+    /** The vote ID (hex-prefixed). */
+    voteId: string;
+}
+interface InfoResponse {
+    circuitUrl: string;
+    circuitHash: string;
+    provingKeyUrl: string;
+    provingKeyHash: string;
+    verificationKeyUrl: string;
+    verificationKeyHash: string;
+    ballotProofWasmHelperUrl: string;
+    ballotProofWasmHelperHash: string;
+    ballotProofWasmHelperExecJsUrl: string;
+    ballotProofWasmHelperExecJsHash: string;
+    contracts: {
+        process: string;
+        organization: string;
+        stateTransitionVerifier: string;
+        resultsVerifier: string;
+    };
+    network: {
+        [key: string]: number;
+    };
+}
+declare enum VoteStatus {
+    Pending = "pending",
+    Verified = "verified",
+    Aggregated = "aggregated",
+    Processed = "processed",
+    Settled = "settled",
+    Error = "error"
+}
+interface VoteStatusResponse {
+    status: VoteStatus;
+}
+interface ListProcessesResponse {
+    processes: string[];
+}
+interface SequencerStats {
+    activeProcesses: number;
+    pendingVotes: number;
+    verifiedVotes: number;
+    aggregatedVotes: number;
+    stateTransitions: number;
+    settledStateTransitions: number;
+    lastStateTransitionDate: string;
+}
+interface WorkerStats {
+    name: string;
+    successCount: number;
+    failedCount: number;
+}
+interface WorkersResponse {
+    workers: WorkerStats[];
+}
+
+/**
+ * Creates the signature message for process creation.
+ * @param processId - The process ID (with or without 0x prefix)
+ * @returns The message string to be signed
+ */
+declare function createProcessSignatureMessage(processId: string): string;
+/**
+ * Signs the process creation message with the provided signer.
+ * @param processId - The process ID (with or without 0x prefix)
+ * @param signer - The signer (Wallet or Signer) to sign with
+ * @returns Promise resolving to the signature string
+ */
+declare function signProcessCreation(processId: string, signer: Signer | Wallet): Promise<string>;
+/**
+ * Validates that a process ID is a valid 64-character hex string (32 bytes).
+ * @param processId - The process ID to validate
+ * @returns True if valid, false otherwise
+ */
+declare function validateProcessId(processId: string): boolean;
+
+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 Groth16Proof {
+    pi_a: [string, string, string];
+    pi_b: [[string, string], [string, string], [string, string]];
+    pi_c: [string, string, string];
+    protocol: string;
+    curve: string;
+}
+interface CircomProofOptions {
+    wasmUrl?: string;
+    zkeyUrl?: string;
+    vkeyUrl?: string;
+    /** Optional SHA-256 hash to verify circuit WASM file integrity */
+    wasmHash?: string;
+    /** Optional SHA-256 hash to verify proving key file integrity */
+    zkeyHash?: string;
+    /** Optional SHA-256 hash to verify verification key file integrity */
+    vkeyHash?: string;
+}
+declare class CircomProof {
+    private readonly wasmUrl?;
+    private readonly zkeyUrl?;
+    private readonly vkeyUrl?;
+    private readonly wasmHash?;
+    private readonly zkeyHash?;
+    private readonly vkeyHash?;
+    private wasmCache;
+    private zkeyCache;
+    private vkeyCache;
+    constructor(opts?: CircomProofOptions);
+    /**
+     * Computes SHA-256 hash of the given data and compares it with the expected hash.
+     * @param data - The data to hash (string or ArrayBuffer or Uint8Array)
+     * @param expectedHash - The expected SHA-256 hash in hexadecimal format
+     * @param filename - The filename for error reporting
+     * @throws Error if the computed hash doesn't match the expected hash
+     */
+    private verifyHash;
+    /**
+     * Generate a zk‐SNARK proof.
+     * If you didn't pass wasmUrl/zkeyUrl in the constructor you must supply them here.
+     */
+    generate(inputs: ProofInputs, urls?: {
+        wasmUrl?: string;
+        zkeyUrl?: string;
+    }): Promise<{
+        proof: Groth16Proof;
+        publicSignals: string[];
+    }>;
+    verify(proof: Groth16Proof, publicSignals: string[], urlOverride?: string): Promise<boolean>;
+}
+
+interface DavinciCryptoInputs {
+    address: string;
+    processID: string;
+    encryptionKey: [string, string];
+    k?: string;
+    weight: string;
+    fieldValues: string[];
+    ballotMode: BallotMode;
+}
+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;
+}
+interface DavinciCryptoOptions {
+    /** URL to wasm_exec.js */
+    wasmExecUrl: string;
+    /** URL to the compiled davinci_crypto.wasm */
+    wasmUrl: string;
+    /** How long (ms) to wait for the Go runtime to attach DavinciCrypto */
+    initTimeoutMs?: number;
+    /** Optional SHA-256 hash to verify wasm_exec.js integrity */
+    wasmExecHash?: string;
+    /** Optional SHA-256 hash to verify davinci_crypto.wasm integrity */
+    wasmHash?: string;
+}
+declare class DavinciCrypto {
+    private go;
+    private initialized;
+    private readonly wasmExecUrl;
+    private readonly wasmUrl;
+    private readonly initTimeoutMs;
+    private readonly wasmExecHash?;
+    private readonly wasmHash?;
+    private static wasmExecCache;
+    private static wasmBinaryCache;
+    constructor(opts: DavinciCryptoOptions);
+    /**
+     * Computes SHA-256 hash of the given data and compares it with the expected hash.
+     * @param data - The data to hash (string or ArrayBuffer)
+     * @param expectedHash - The expected SHA-256 hash in hexadecimal format
+     * @param filename - The filename for error reporting
+     * @throws Error if the computed hash doesn't match the expected hash
+     */
+    private verifyHash;
+    /**
+     * Must be awaited before calling `proofInputs()`.
+     * Safe to call multiple times.
+     */
+    init(): Promise<void>;
+    /**
+     * Convert your inputs into JSON, hand off to Go/WASM, then parse & return.
+     * @throws if called before `await init()`, or if Go returns an error
+     */
+    proofInputs(inputs: DavinciCryptoInputs): Promise<DavinciCryptoOutput>;
+    /**
+     * Generate a CSP (Credential Service Provider) signature for census proof.
+     * @param censusOrigin - The census origin type (e.g., CensusOrigin.CensusOriginCSP)
+     * @param privKey - The private key in hex format
+     * @param processId - The process ID in hex format
+     * @param address - The address in hex format
+     * @returns The CSP proof as a parsed JSON object
+     * @throws if called before `await init()`, or if Go returns an error
+     */
+    cspSign(censusOrigin: CensusOrigin, privKey: string, processId: string, address: string): Promise<CSPSignOutput>;
+    /**
+     * Verify a CSP (Credential Service Provider) proof.
+     * @param censusOrigin - The census origin type (e.g., CensusOrigin.CensusOriginCSP)
+     * @param root - The census root
+     * @param address - The address
+     * @param processId - The process ID
+     * @param publicKey - The public key
+     * @param signature - The signature
+     * @returns The verification result
+     * @throws if called before `await init()`, or if Go returns an error
+     */
+    cspVerify(censusOrigin: CensusOrigin, root: string, address: string, processId: string, publicKey: string, signature: string): Promise<boolean>;
+    /**
+     * Generate a CSP (Credential Service Provider) census root.
+     * @param censusOrigin - The census origin type (e.g., CensusOrigin.CensusOriginCSP)
+     * @param privKey - The private key in hex format
+     * @returns The census root as a hexadecimal string
+     * @throws if called before `await init()`, or if Go returns an error
+     */
+    cspCensusRoot(censusOrigin: CensusOrigin, privKey: string): Promise<string>;
+}
+
+declare class VocdoniSequencerService extends BaseService {
+    constructor(baseURL: string);
+    ping(): Promise<void>;
+    createProcess(body: CreateProcessRequest): Promise<CreateProcessResponse>;
+    getProcess(processId: string): Promise<GetProcessResponse>;
+    listProcesses(): Promise<string[]>;
+    submitVote(vote: VoteRequest): Promise<void>;
+    getVoteStatus(processId: string, voteId: string): Promise<VoteStatusResponse>;
+    hasAddressVoted(processId: string, address: string): Promise<boolean>;
+    getInfo(): Promise<InfoResponse>;
+    pushMetadata(metadata: ElectionMetadata): Promise<string>;
+    getMetadata(hashOrUrl: string): Promise<ElectionMetadata>;
+    getMetadataUrl(hash: string): string;
+    getStats(): Promise<SequencerStats>;
+    getWorkers(): Promise<WorkersResponse>;
+}
+
+export { CircomProof, DavinciCrypto, VocdoniSequencerService, VoteStatus, createProcessSignatureMessage, signProcessCreation, validateProcessId };
+export type { CSPSignOutput, CircomProofOptions, CreateProcessRequest, CreateProcessResponse, DavinciCryptoCiphertext, DavinciCryptoInputs, DavinciCryptoOptions, DavinciCryptoOutput, GetProcessResponse, Groth16Proof, InfoResponse, ListProcessesResponse, ProofInputs, SequencerStats, VoteBallot, VoteCiphertext, VoteProof, VoteRequest, VoteStatusResponse, WorkerStats, WorkersResponse };

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@vocdoni/davinci-sdk",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "yarn clean && rollup -c",
+    "dev": "rollup -c -w",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint-staged": "lint-staged",
+    "test": "yarn test:unit && yarn test:integration",
+    "test:unit": "yarn test:contracts:unit && yarn test:sequencer:unit",
+    "test:integration": "yarn test:contracts:integration && yarn test:sequencer:integration && yarn test:census:integration",
+    "test:contracts": "yarn test:contracts:unit && yarn test:contracts:integration",
+    "test:contracts:unit": "jest 'test/contracts/unit'",
+    "test:contracts:integration": "jest 'test/contracts/integration' --runInBand",
+    "test:sequencer": "yarn test:sequencer:unit && yarn test:sequencer:integration",
+    "test:sequencer:unit": "jest 'test/sequencer/unit'",
+    "test:sequencer:integration": "jest 'test/sequencer/integration' --runInBand",
+    "test:census": "yarn test:census:integration",
+    "test:census:integration": "jest 'test/census/integration' --runInBand"
+  },
+  "description": "A powerful TypeScript SDK for building decentralized voting applications on the Vocdoni DaVinci protocol with homomorphic encryption and zero-knowledge proofs",
+  "keywords": [
+    "vocdoni",
+    "davinci",
+    "voting",
+    "blockchain",
+    "ethereum",
+    "decentralized",
+    "privacy",
+    "homomorphic-encryption",
+    "zero-knowledge",
+    "zk-snarks",
+    "typescript",
+    "sdk",
+    "elections",
+    "governance",
+    "cryptography",
+    "web3"
+  ],
+  "author": {
+    "name": "Vocdoni",
+    "email": "info@vocdoni.io",
+    "url": "https://vocdoni.io"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/vocdoni/davinci-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vocdoni/davinci-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vocdoni/davinci-sdk/issues"
+  },
+  "dependencies": {
+    "@ethereumjs/common": "^4.4.0",
+    "@vocdoni/davinci-contracts": "0.0.18",
+    "axios": "^1.8.4",
+    "ethers": "^6.7.1",
+    "snarkjs": "^0.7.5"
+  },
+  "devDependencies": {
+    "lint-staged": "^15.2.0",
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@types/jest": "^29.5.4",
+    "@types/node": "^20.5.9",
+    "@typescript-eslint/eslint-plugin": "^6.6.0",
+    "@typescript-eslint/parser": "^6.6.0",
+    "dotenv": "^16.4.7",
+    "esbuild": "^0.25.2",
+    "eslint": "^8.48.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.0.3",
+    "rimraf": "^5.0.1",
+    "rollup": "^4.0.0",
+    "rollup-plugin-copy": "^3.5.0",
+    "rollup-plugin-dts": "^6.2.1",
+    "rollup-plugin-esbuild": "^6.2.1",
+    "rollup-plugin-polyfill-node": "^0.13.0",
+    "ts-jest": "^29.3.1",
+    "typescript": "^5.2.2"
+  }
+}