@maci-protocol/core 0.0.0-ci.01622be

package/README.md

@@ -0,0 +1,107 @@
+# `maci-core`
+
+[![NPM Package][core-npm-badge]][core-npm-link]
+[![Actions Status][core-actions-badge]][core-actions-link]
+
+This submodule assists with handling key business logic functions and
+processes.
+
+## Overview
+
+One may conceive of MACI as a state machine with 1) data and 2) functions which
+transform said data. This makes it easier to reason about the system, write
+tests, and implement functionality. It also allows us to implement the smart
+contracts in discrete components which are easy to test.
+
+To this end, this submodule exposes a `MaciState` class and a `Poll` class.
+Developers should instantiate objects from these classes to test MACI. For
+instance, [`MACI.test.ts`](https://github.com/privacy-scaling-explorations/maci/blob/dev/packages/contracts/tests/MACI.test.ts) creates a
+`MaciState` object and every time it interacts with the MACI smart contract, it
+mirrors said interaction on the `MaciState` and `Poll`. As such, the developer
+can then use their helper functions like `maciState.signUp()`,
+`poll.publishMessage`, `poll.processMessages()`, and `poll.tallyVotes()` to
+step through the various stages of the MACI flow.
+
+## `MaciState`
+
+### Key functions
+
+#### **`signUp`**
+
+Accepts a user's public key and creates a new state leaf and ballot leaf.
+
+In testing, whenever a test suite submits a `signUp()` transaction, it should
+call `maciState.signUp()` as well, so that the off-chain representation of MACI
+is kept up to date.
+
+In production, `genMaciStateFromContract()` in
+[`genMaciState.ts`](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/ts/genMaciState.ts) uses this function when it
+scans a MACI contract's event log for signups, so as to bring its `MaciState`
+instance up to date.
+
+#### **`deployPoll`**
+
+Creates a new `Poll`. This should be done whenever the MACI contract's
+`deployPoll()` function is called.
+
+### Helper functions
+
+#### **`copy`**
+
+A function that deep-copies an object.
+
+### Key data structures
+
+#### **`stateTree`**
+
+`stateTree` is a quinary Merkle tree, chosen over a binary tree due to the gas and circuit constraints associated with the Poseidon hash function ([details here][ethresearch-link]). Each leaf in this tree represents a participant's public key, their voice credit balance and the block timestamp at which they signed up. The tree features a configurable depth and an arity of five, with insertions starting at index 1. The zeroth leaf is reserved as a security measure against denial-of-service attacks.
+
+## **`Poll`**
+
+A `Poll` is an off-chain representation of a Poll. In testing, `Poll` instances
+should mirror their on-chain counterparts.
+
+### Key functions
+
+#### **`publishMessage`**
+
+Publishes a message by updating the message tree and message accumulation
+queue.
+
+#### **`processMessages`**
+
+Processes a batch of messages and returns the inputs to the `processMessages`
+circuit which can be used to prove correct execution.
+
+#### **`tallyVotes`**
+
+Tallies a batch of votes and returns the inputs to the `tallyVotes`
+circuit which can be used to prove correct execution.
+
+### Helper functions
+
+#### **`copy`**
+
+Deep-copies and returns this object.
+
+### Key data structures
+
+#### **`messageTree`**
+
+`messageTree` is also a quinary Merkle tree. Each message in this tree represents an encrypted command, such as a user casting a vote in a poll or changing their public key.
+
+## Testing
+
+For more details about testing please refer to the [tests documentation](https://maci.pse.dev/docs/testing).
+
+[core-npm-badge]: https://img.shields.io/npm/v/maci-core.svg
+[core-npm-link]: https://www.npmjs.com/package/maci-core
+[core-actions-badge]: https://github.com/privacy-scaling-explorations/maci/actions/workflows/core-build.yml/badge.svg
+[core-actions-link]: https://github.com/privacy-scaling-explorations/maci/actions?query=workflow%3Acore
+[ethresearch-link]: https://ethresear.ch/t/gas-and-circuit-constraint-benchmarks-of-binary-and-quinary-incremental-merkle-trees-using-the-poseidon-hash-function/7446
+
+## Directory Structure
+
+- `ts/`: The home for our core classes, `MaciState` and `Poll`
+- `ts/utls/`: Contains supporting utilities
+- `ts/__tests__/`: A dedicated test suite directory

package/build/ts/MaciState.d.ts

@@ -0,0 +1,66 @@
+import { IncrementalQuinTree } from "@maci-protocol/crypto";
+import { PublicKey, type Keypair } from "@maci-protocol/domainobjs";
+import type { IJsonMaciState, IMaciState, ITreeDepths } from "./utils/types";
+import { Poll } from "./Poll";
+import { EMode } from "./utils/constants";
+/**
+ * A representation of the MACI contract.
+ */
+export declare class MaciState implements IMaciState {
+    polls: Map<bigint, Poll>;
+    publicKeys: PublicKey[];
+    stateTreeDepth: number;
+    stateTree?: IncrementalQuinTree;
+    totalSignups: number;
+    pollBeingProcessed?: boolean;
+    currentPollBeingProcessed?: bigint;
+    /**
+     * Constructs a new MaciState object.
+     * @param stateTreeDepth - The depth of the state tree.
+     */
+    constructor(stateTreeDepth: number);
+    /**
+     * Sign up a user with the given public key.
+     * @param publicKey - The public key of the user.
+     * @returns The index of the newly signed-up user in the state tree.
+     */
+    signUp(publicKey: PublicKey): number;
+    /**
+     * Deploy a new poll with the given parameters.
+     * @param pollEndTimestamp - The Unix timestamp at which the poll ends.
+     * @param treeDepths - The depths of the tree.
+     * @param messageBatchSize - The batch size for processing messages.
+     * @param coordinatorKeypair - The keypair of the MACI round coordinator.
+     * @param voteOptions - The number of vote options for this poll.
+     * @param mode - The voting mode
+     * @returns The index of the newly deployed poll.
+     */
+    deployPoll(pollEndTimestamp: bigint, treeDepths: ITreeDepths, messageBatchSize: number, coordinatorKeypair: Keypair, voteOptions: bigint, mode: EMode): bigint;
+    /**
+     * Deploy a null poll.
+     */
+    deployNullPoll(): void;
+    /**
+     * Create a deep copy of the MaciState object.
+     * @returns A new instance of the MaciState object with the same properties.
+     */
+    copy: () => MaciState;
+    /**
+     * Check if the MaciState object is equal to another MaciState object.
+     * @param m - The MaciState object to compare.
+     * @returns True if the two MaciState objects are equal, false otherwise.
+     */
+    equals: (m: MaciState) => boolean;
+    /**
+     * Serialize the MaciState object to a JSON object.
+     * @returns A JSON object representing the MaciState object.
+     */
+    toJSON(): IJsonMaciState;
+    /**
+     * Create a new MaciState object from a JSON object.
+     * @param json - The JSON object representing the MaciState object.
+     * @returns A new instance of the MaciState object with the properties from the JSON object.
+     */
+    static fromJSON(json: IJsonMaciState): MaciState;
+}
+//# sourceMappingURL=MaciState.d.ts.map

package/build/ts/MaciState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaciState.d.ts","sourceRoot":"","sources":["../../ts/MaciState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,KAAK,OAAO,EAAU,MAAM,2BAA2B,CAAC;AAE5E,OAAO,KAAK,EAAE,cAAc,EAAa,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAExF,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAoB,MAAM,mBAAmB,CAAC;AAE5D;;GAEG;AACH,qBAAa,SAAU,YAAW,UAAU;IAE1C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAA2B;IAGnD,UAAU,EAAE,SAAS,EAAE,CAAM;IAG7B,cAAc,EAAE,MAAM,CAAC;IAGvB,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhC,YAAY,SAAK;IAGjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;OAGG;gBACS,cAAc,EAAE,MAAM;IAUlC;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM;IAOpC;;;;;;;;;OASG;IACH,UAAU,CACR,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,WAAW,EACvB,gBAAgB,EAAE,MAAM,EACxB,kBAAkB,EAAE,OAAO,EAC3B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,KAAK,GACV,MAAM;IAkBT;;OAEG;IACH,cAAc,IAAI,IAAI;IAItB;;;OAGG;IACH,IAAI,QAAO,SAAS,CAQlB;IAEF;;;;OAIG;IACH,MAAM,GAAI,GAAG,SAAS,KAAG,OAAO,CAsB9B;IAEF;;;OAGG;IACH,MAAM,IAAI,cAAc;IAWxB;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS;CAgBjD"}

package/build/ts/MaciState.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaciState = void 0;
+const domainobjs_1 = require("@maci-protocol/domainobjs");
+const Poll_1 = require("./Poll");
+const constants_1 = require("./utils/constants");
+/**
+ * A representation of the MACI contract.
+ */
+class MaciState {
+    /**
+     * Constructs a new MaciState object.
+     * @param stateTreeDepth - The depth of the state tree.
+     */
+    constructor(stateTreeDepth) {
+        // a MaciState can hold multiple polls
+        this.polls = new Map();
+        // the public keys of the users
+        this.publicKeys = [];
+        this.totalSignups = 0;
+        /**
+         * Create a deep copy of the MaciState object.
+         * @returns A new instance of the MaciState object with the same properties.
+         */
+        this.copy = () => {
+            const copied = new MaciState(this.stateTreeDepth);
+            copied.publicKeys = this.publicKeys.map((x) => x.copy());
+            copied.polls = new Map(Array.from(this.polls, ([key, value]) => [key, value.copy()]));
+            return copied;
+        };
+        /**
+         * Check if the MaciState object is equal to another MaciState object.
+         * @param m - The MaciState object to compare.
+         * @returns True if the two MaciState objects are equal, false otherwise.
+         */
+        this.equals = (m) => {
+            const result = this.stateTreeDepth === m.stateTreeDepth &&
+                this.polls.size === m.polls.size &&
+                this.publicKeys.length === m.publicKeys.length;
+            if (!result) {
+                return false;
+            }
+            for (let i = 0; i < this.polls.size; i += 1) {
+                if (!this.polls.get(BigInt(i))?.equals(m.polls.get(BigInt(i)))) {
+                    return false;
+                }
+            }
+            for (let i = 0; i < this.publicKeys.length; i += 1) {
+                if (!this.publicKeys[i].equals(m.publicKeys[i])) {
+                    return false;
+                }
+            }
+            return true;
+        };
+        this.stateTreeDepth = stateTreeDepth;
+        // we put a blank state leaf to prevent a DoS attack
+        this.publicKeys.push(domainobjs_1.padKey);
+        // we need to increase the number of signups by one given
+        // that we already added the blank leaf
+        this.totalSignups += 1;
+    }
+    /**
+     * Sign up a user with the given public key.
+     * @param publicKey - The public key of the user.
+     * @returns The index of the newly signed-up user in the state tree.
+     */
+    signUp(publicKey) {
+        this.totalSignups += 1;
+        this.stateTree?.insert(publicKey.hash());
+        return this.publicKeys.push(publicKey.copy()) - 1;
+    }
+    /**
+     * Deploy a new poll with the given parameters.
+     * @param pollEndTimestamp - The Unix timestamp at which the poll ends.
+     * @param treeDepths - The depths of the tree.
+     * @param messageBatchSize - The batch size for processing messages.
+     * @param coordinatorKeypair - The keypair of the MACI round coordinator.
+     * @param voteOptions - The number of vote options for this poll.
+     * @param mode - The voting mode
+     * @returns The index of the newly deployed poll.
+     */
+    deployPoll(pollEndTimestamp, treeDepths, messageBatchSize, coordinatorKeypair, voteOptions, mode) {
+        const poll = new Poll_1.Poll(pollEndTimestamp, coordinatorKeypair, treeDepths, {
+            messageBatchSize,
+            tallyBatchSize: constants_1.STATE_TREE_ARITY ** treeDepths.tallyProcessingStateTreeDepth,
+        }, this, voteOptions, mode);
+        this.polls.set(BigInt(this.polls.size), poll);
+        return BigInt(this.polls.size - 1);
+    }
+    /**
+     * Deploy a null poll.
+     */
+    deployNullPoll() {
+        this.polls.set(BigInt(this.polls.size), null);
+    }
+    /**
+     * Serialize the MaciState object to a JSON object.
+     * @returns A JSON object representing the MaciState object.
+     */
+    toJSON() {
+        return {
+            stateTreeDepth: this.stateTreeDepth,
+            polls: Array.from(this.polls.values()).map((poll) => poll.toJSON()),
+            publicKeys: this.publicKeys.map((publicKey) => publicKey.toJSON()),
+            pollBeingProcessed: Boolean(this.pollBeingProcessed),
+            currentPollBeingProcessed: this.currentPollBeingProcessed ? this.currentPollBeingProcessed.toString() : "",
+            totalSignups: this.totalSignups,
+        };
+    }
+    /**
+     * Create a new MaciState object from a JSON object.
+     * @param json - The JSON object representing the MaciState object.
+     * @returns A new instance of the MaciState object with the properties from the JSON object.
+     */
+    static fromJSON(json) {
+        const maciState = new MaciState(json.stateTreeDepth);
+        // assign the json values to the new instance
+        maciState.publicKeys = json.publicKeys.map((publicKey) => domainobjs_1.PublicKey.fromJSON(publicKey));
+        maciState.pollBeingProcessed = json.pollBeingProcessed;
+        maciState.currentPollBeingProcessed = BigInt(json.currentPollBeingProcessed);
+        maciState.totalSignups = json.totalSignups;
+        // re-generate the polls and set the maci state reference
+        maciState.polls = new Map(json.polls.map((jsonPoll, index) => [BigInt(index), Poll_1.Poll.fromJSON(jsonPoll, maciState)]));
+        return maciState;
+    }
+}
+exports.MaciState = MaciState;
+//# sourceMappingURL=MaciState.js.map

package/build/ts/MaciState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaciState.js","sourceRoot":"","sources":["../../ts/MaciState.ts"],"names":[],"mappings":"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"}

package/build/ts/Poll.d.ts

@@ -0,0 +1,228 @@
+import { IncrementalQuinTree } from "@maci-protocol/crypto";
+import { VoteCommand, Keypair, Ballot, PublicKey, Message, StateLeaf } from "@maci-protocol/domainobjs";
+import { LeanIMT } from "@zk-kit/lean-imt";
+import type { ITreeDepths, IBatchSizes, IPoll, IJsonPoll, IProcessMessagesOutput, ITallyCircuitInputs, IProcessMessagesCircuitInputs, IPollJoiningCircuitInputs, IJoiningCircuitArgs } from "./index";
+import type { MaciState } from "./MaciState";
+import type { IGetVoiceCreditsLeft, IJoinedCircuitArgs, IPollJoinedCircuitInputs } from "./utils/types";
+import { EMode } from "./utils/constants";
+/**
+ * A representation of the Poll contract.
+ */
+export declare class Poll implements IPoll {
+    coordinatorKeypair: Keypair;
+    treeDepths: ITreeDepths;
+    batchSizes: IBatchSizes;
+    voteOptions: bigint;
+    maxVoteOptions: number;
+    actualStateTreeDepth: number;
+    pollEndTimestamp: bigint;
+    ballots: Ballot[];
+    ballotTree?: IncrementalQuinTree;
+    messages: Message[];
+    commands: VoteCommand[];
+    encryptionPublicKeys: PublicKey[];
+    stateCopied: boolean;
+    publicKeys: PublicKey[];
+    stateTree?: LeanIMT;
+    numBatchesProcessed: number;
+    currentMessageBatchIndex: number;
+    maciStateRef: MaciState;
+    pollId: bigint;
+    sbSalts: Record<number | string, bigint>;
+    resultRootSalts: Record<number | string, bigint>;
+    perVoteOptionSpentVoiceCreditsRootSalts: Record<number | string, bigint>;
+    spentVoiceCreditSubtotalSalts: Record<number | string, bigint>;
+    tallyResult: bigint[];
+    perVoteOptionSpentVoiceCredits: bigint[];
+    numBatchesTallied: number;
+    totalSpentVoiceCredits: bigint;
+    emptyBallot: Ballot;
+    emptyBallotHash?: bigint;
+    chainHash: bigint;
+    batchHashes: bigint[];
+    pollStateLeaves: StateLeaf[];
+    pollStateTree?: IncrementalQuinTree;
+    pollNullifiers: Map<bigint, boolean>;
+    private mode;
+    private totalSignups;
+    /**
+     * Constructs a new Poll object.
+     * @param pollEndTimestamp - The Unix timestamp at which the poll ends.
+     * @param coordinatorKeypair - The keypair of the coordinator.
+     * @param treeDepths - The depths of the trees used in the poll.
+     * @param batchSizes - The sizes of the batches used in the poll.
+     * @param maciStateRef - The reference to the MACI state.
+     * @param pollId - The poll id
+     */
+    constructor(pollEndTimestamp: bigint, coordinatorKeypair: Keypair, treeDepths: ITreeDepths, batchSizes: IBatchSizes, maciStateRef: MaciState, voteOptions: bigint, mode: EMode);
+    /**
+     * Check if user has already joined the poll by checking if the nullifier is registered
+     */
+    hasJoined: (nullifier: bigint) => boolean;
+    /**
+     * Join the anonymous user to the Poll (to the tree)
+     * @param nullifier - Hashed private key used as nullifier
+     * @param publicKey - The poll public key.
+     * @param newVoiceCreditBalance - New voice credit balance of the user.
+     * @returns The index of added state leaf
+     */
+    joinPoll: (nullifier: bigint, publicKey: PublicKey, newVoiceCreditBalance: bigint) => number;
+    /**
+     * Update a Poll with data from MaciState.
+     * This is the step where we copy the state from the MaciState instance,
+     * and set the number of signups we have so far.
+     * @note It should be called to generate the state for poll joining with totalSignups set as
+     * the number of signups in the MaciState. For message processing, you should set totalSignups as
+     * the number of users who joined the poll.
+     */
+    updatePoll: (totalSignups: bigint) => void;
+    /**
+     * Process one message.
+     * @param message - The message to process.
+     * @param encryptionPublicKey - The public key associated with the encryption private key.
+     * @returns A number of variables which will be used in the zk-SNARK circuit.
+     */
+    processMessage: (message: Message, encryptionPublicKey: PublicKey) => IProcessMessagesOutput;
+    /**
+     * Get voice credits left for the voting command.
+     *
+     * @param args - arguments for getting voice credits
+     * @returns voice credits left
+     */
+    getVoiceCreditsLeft({ stateLeaf, originalVoteWeight, newVoteWeight, mode }: IGetVoiceCreditsLeft): bigint;
+    /**
+     * Inserts a Message and the corresponding public key used to generate the
+     * ECDH shared key which was used to encrypt said message.
+     * @param message - The message to insert
+     * @param encryptionPublicKey - The public key used to encrypt the message
+     */
+    publishMessage: (message: Message, encryptionPublicKey: PublicKey) => void;
+    /**
+     * Updates message chain hash
+     * @param messageHash hash of message with encryptionPublicKey
+     */
+    updateChainHash: (messageHash: bigint) => void;
+    /**
+     * Create circuit input for pollJoining
+     * @param args Poll joining circuit inputs
+     * @returns stringified circuit inputs
+     */
+    joiningCircuitInputs: ({ maciPrivateKey, stateLeafIndex, pollPublicKey, }: IJoiningCircuitArgs) => IPollJoiningCircuitInputs;
+    /**
+     * Create circuit input for pollJoined
+     * @param args Poll joined circuit inputs
+     * @returns stringified circuit inputs
+     */
+    joinedCircuitInputs: ({ maciPrivateKey, stateLeafIndex, voiceCreditsBalance, }: IJoinedCircuitArgs) => IPollJoinedCircuitInputs;
+    /**
+     * Pad last unclosed batch
+     */
+    padLastBatch: () => void;
+    /**
+     * This method checks if there are any unprocessed messages in the Poll instance.
+     * @returns Returns true if the number of processed batches is
+     * less than the total number of batches, false otherwise.
+     */
+    hasUnprocessedMessages: () => boolean;
+    /**
+     * Process _batchSize messages starting from the saved index. This
+     * function will process messages even if the number of messages is not an
+     * exact multiple of _batchSize. e.g. if there are 10 messages, index is
+     * 8, and _batchSize is 4, this function will only process the last two
+     * messages in this.messages, and finally update the zeroth state leaf.
+     * Note that this function will only process as many state leaves as there
+     * are ballots to prevent accidental inclusion of a new user after this
+     * poll has concluded.
+     * @param pollId The ID of the poll associated with the messages to
+     *        process
+     * @param quiet - Whether to log errors or not
+     * @returns stringified circuit inputs
+     */
+    processMessages: (pollId: bigint, quiet?: boolean) => IProcessMessagesCircuitInputs;
+    /**
+     * Generates partial circuit inputs for processing a batch of messages
+     * @param index - The index of the partial batch.
+     * @returns stringified partial circuit inputs
+     */
+    private generateProcessMessagesCircuitInputsPartial;
+    /**
+     * Process all messages. This function does not update the ballots or state
+     * leaves; rather, it copies and then updates them. This makes it possible
+     * to test the result of multiple processMessage() invocations.
+     * @returns The state leaves and ballots of the poll
+     */
+    processAllMessages: () => {
+        stateLeaves: StateLeaf[];
+        ballots: Ballot[];
+    };
+    /**
+     * Checks whether there are any untallied ballots.
+     * @returns Whether there are any untallied ballots
+     */
+    hasUntalliedBallots: () => boolean;
+    /**
+     * This method tallies a ballots and updates the tally results.
+     *
+     * @returns the circuit inputs for the TallyVotes circuit.
+     */
+    tallyVotes: () => ITallyCircuitInputs;
+    /**
+     * This method generates a commitment to the total spent voice credits.
+     *
+     * This is the hash of the total spent voice credits and a salt, computed as Poseidon([totalCredits, _salt]).
+     * @param salt - The salt used in the hash function.
+     * @param ballotsToCount - The number of ballots to count for the calculation.
+     * @param mode - Voting mode, default QV.
+     * @returns Returns the hash of the total spent voice credits and a salt, computed as Poseidon([totalCredits, _salt]).
+     */
+    private generateSpentVoiceCreditSubtotalCommitment;
+    /**
+     * This method generates a commitment to the spent voice credits per vote option.
+     *
+     * This is the hash of the Merkle root of the spent voice credits per vote option and a salt, computed as Poseidon([root, _salt]).
+     * @param salt - The salt used in the hash function.
+     * @param ballotsToCount - The number of ballots to count for the calculation.
+     * @param mode - Voting mode, default is QV.
+     * @returns Returns the hash of the Merkle root of the spent voice credits per vote option and a salt, computed as Poseidon([root, _salt]).
+     */
+    private generatePerVoteOptionSpentVoiceCreditsCommitment;
+    /**
+     * Create a deep copy of the Poll object.
+     * @returns A new instance of the Poll object with the same properties.
+     */
+    copy: () => Poll;
+    /**
+     * Check if the Poll object is equal to another Poll object.
+     * @param poll - The Poll object to compare.
+     * @returns True if the two Poll objects are equal, false otherwise.
+     */
+    equals: (poll: Poll) => boolean;
+    /**
+     * Serialize the Poll object to a JSON object
+     * @returns a JSON object
+     */
+    toJSON(): IJsonPoll;
+    /**
+     * Deserialize a json object into a Poll instance
+     * @param json the json object to deserialize
+     * @param maciState the reference to the MaciState Class
+     * @returns a new Poll instance
+     */
+    static fromJSON(json: IJsonPoll, maciState: MaciState): Poll;
+    /**
+     * Set the coordinator's keypair
+     * @param serializedPrivateKey - the serialized private key
+     */
+    setCoordinatorKeypair: (serializedPrivateKey: string) => void;
+    /**
+     * Set the number of signups to match the ones from the contract
+     * @param totalSignups - the number of signups
+     */
+    setTotalSignups: (totalSignups: bigint) => void;
+    /**
+     * Get the number of signups
+     * @returns The number of signups
+     */
+    gettotalSignups: () => bigint;
+}
+//# sourceMappingURL=Poll.d.ts.map

package/build/ts/Poll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Poll.d.ts","sourceRoot":"","sources":["../../ts/Poll.ts"],"names":[],"mappings":"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"}