@maci-protocol/core 0.0.0-ci.185b643

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,64 @@
+import { IncrementalQuinTree } from "@maci-protocol/crypto";
+import { PubKey, type Keypair } from "@maci-protocol/domainobjs";
+import type { IJsonMaciState, IMaciState, TreeDepths } from "./utils/types";
+import { Poll } from "./Poll";
+/**
+ * A representation of the MACI contract.
+ */
+export declare class MaciState implements IMaciState {
+    polls: Map<bigint, Poll>;
+    pubKeys: PubKey[];
+    stateTreeDepth: number;
+    stateTree?: IncrementalQuinTree;
+    numSignUps: 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 pubKey - The public key of the user.
+     * @returns The index of the newly signed-up user in the state tree.
+     */
+    signUp(pubKey: PubKey): 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.
+     * @returns The index of the newly deployed poll.
+     */
+    deployPoll(pollEndTimestamp: bigint, treeDepths: TreeDepths, messageBatchSize: number, coordinatorKeypair: Keypair, voteOptions: bigint): 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,MAAM,EAAE,KAAK,OAAO,EAAU,MAAM,2BAA2B,CAAC;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAa,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEvF,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B;;GAEG;AACH,qBAAa,SAAU,YAAW,UAAU;IAE1C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAA2B;IAGnD,OAAO,EAAE,MAAM,EAAE,CAAM;IAGvB,cAAc,EAAE,MAAM,CAAC;IAGvB,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhC,UAAU,SAAK;IAGf,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;OAGG;gBACS,cAAc,EAAE,MAAM;IAUlC;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAO9B;;;;;;;;OAQG;IACH,UAAU,CACR,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,MAAM,EACxB,kBAAkB,EAAE,OAAO,EAC3B,WAAW,EAAE,MAAM,GAClB,MAAM;IAiBT;;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,127 @@
+"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.pubKeys = [];
+        this.numSignUps = 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.pubKeys = this.pubKeys.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.pubKeys.length === m.pubKeys.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.pubKeys.length; i += 1) {
+                if (!this.pubKeys[i].equals(m.pubKeys[i])) {
+                    return false;
+                }
+            }
+            return true;
+        };
+        this.stateTreeDepth = stateTreeDepth;
+        // we put a blank state leaf to prevent a DoS attack
+        this.pubKeys.push(domainobjs_1.padKey);
+        // we need to increase the number of signups by one given
+        // that we already added the blank leaf
+        this.numSignUps += 1;
+    }
+    /**
+     * Sign up a user with the given public key.
+     * @param pubKey - The public key of the user.
+     * @returns The index of the newly signed-up user in the state tree.
+     */
+    signUp(pubKey) {
+        this.numSignUps += 1;
+        this.stateTree?.insert(pubKey.hash());
+        return this.pubKeys.push(pubKey.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.
+     * @returns The index of the newly deployed poll.
+     */
+    deployPoll(pollEndTimestamp, treeDepths, messageBatchSize, coordinatorKeypair, voteOptions) {
+        const poll = new Poll_1.Poll(pollEndTimestamp, coordinatorKeypair, treeDepths, {
+            messageBatchSize,
+            tallyBatchSize: constants_1.STATE_TREE_ARITY ** treeDepths.intStateTreeDepth,
+        }, this, voteOptions);
+        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()),
+            pubKeys: this.pubKeys.map((pubKey) => pubKey.toJSON()),
+            pollBeingProcessed: Boolean(this.pollBeingProcessed),
+            currentPollBeingProcessed: this.currentPollBeingProcessed ? this.currentPollBeingProcessed.toString() : "",
+            numSignUps: this.numSignUps,
+        };
+    }
+    /**
+     * 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.pubKeys = json.pubKeys.map((pubKey) => domainobjs_1.PubKey.fromJSON(pubKey));
+        maciState.pollBeingProcessed = json.pollBeingProcessed;
+        maciState.currentPollBeingProcessed = BigInt(json.currentPollBeingProcessed);
+        maciState.numSignUps = json.numSignUps;
+        // 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,219 @@
+import { IncrementalQuinTree } from "@maci-protocol/crypto";
+import { PCommand, Keypair, Ballot, PubKey, Message, StateLeaf } from "@maci-protocol/domainobjs";
+import { LeanIMT } from "@zk-kit/lean-imt";
+import type { TreeDepths, BatchSizes, IPoll, IJsonPoll, IProcessMessagesOutput, ITallyCircuitInputs, IProcessMessagesCircuitInputs, IPollJoiningCircuitInputs, IJoiningCircuitArgs } from "./index";
+import type { MaciState } from "./MaciState";
+import type { IJoinedCircuitArgs, IPollJoinedCircuitInputs } from "./utils/types";
+/**
+ * A representation of the Poll contract.
+ */
+export declare class Poll implements IPoll {
+    coordinatorKeypair: Keypair;
+    treeDepths: TreeDepths;
+    batchSizes: BatchSizes;
+    voteOptions: bigint;
+    maxVoteOptions: number;
+    actualStateTreeDepth: number;
+    pollEndTimestamp: bigint;
+    ballots: Ballot[];
+    ballotTree?: IncrementalQuinTree;
+    messages: Message[];
+    commands: PCommand[];
+    encPubKeys: PubKey[];
+    stateCopied: boolean;
+    pubKeys: PubKey[];
+    stateTree?: LeanIMT;
+    numBatchesProcessed: number;
+    currentMessageBatchIndex: number;
+    maciStateRef: MaciState;
+    pollId: bigint;
+    sbSalts: Record<number | string, bigint>;
+    resultRootSalts: Record<number | string, bigint>;
+    preVOSpentVoiceCreditsRootSalts: Record<number | string, bigint>;
+    spentVoiceCreditSubtotalSalts: Record<number | string, bigint>;
+    tallyResult: bigint[];
+    perVOSpentVoiceCredits: bigint[];
+    numBatchesTallied: number;
+    totalSpentVoiceCredits: bigint;
+    emptyBallot: Ballot;
+    emptyBallotHash?: bigint;
+    chainHash: bigint;
+    batchHashes: bigint[];
+    pollStateLeaves: StateLeaf[];
+    pollStateTree?: IncrementalQuinTree;
+    pollNullifiers: Map<bigint, boolean>;
+    private numSignups;
+    /**
+     * 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: TreeDepths, batchSizes: BatchSizes, maciStateRef: MaciState, voteOptions: bigint);
+    /**
+     * 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 pubKey - The poll public key.
+     * @param newVoiceCreditBalance - New voice credit balance of the user.
+     * @returns The index of added state leaf
+     */
+    joinPoll: (nullifier: bigint, pubKey: PubKey, 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 numSignups set as
+     * the number of signups in the MaciState. For message processing, you should set numSignups as
+     * the number of users who joined the poll.
+     */
+    updatePoll: (numSignups: bigint) => void;
+    /**
+     * Process one message.
+     * @param message - The message to process.
+     * @param encPubKey - 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, encPubKey: PubKey, qv?: boolean) => IProcessMessagesOutput;
+    /**
+     * 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 encPubKey - The public key used to encrypt the message
+     */
+    publishMessage: (message: Message, encPubKey: PubKey) => void;
+    /**
+     * Updates message chain hash
+     * @param messageHash hash of message with encPubKey
+     */
+    updateChainHash: (messageHash: bigint) => void;
+    /**
+     * Create circuit input for pollJoining
+     * @param args Poll joining circuit inputs
+     * @returns stringified circuit inputs
+     */
+    joiningCircuitInputs: ({ maciPrivKey, stateLeafIndex, pollPubKey, }: IJoiningCircuitArgs) => IPollJoiningCircuitInputs;
+    /**
+     * Create circuit input for pollJoined
+     * @param args Poll joined circuit inputs
+     * @returns stringified circuit inputs
+     */
+    joinedCircuitInputs: ({ maciPrivKey, 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, qv?: boolean, 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 genProcessMessagesCircuitInputsPartial;
+    /**
+     * 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;
+    tallyVotesNonQv: () => 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 numBallotsToCount - The number of ballots to count for the calculation.
+     * @param useQuadraticVoting - Whether to use quadratic voting or not. Default is true.
+     * @returns Returns the hash of the total spent voice credits and a salt, computed as Poseidon([totalCredits, _salt]).
+     */
+    private genSpentVoiceCreditSubtotalCommitment;
+    /**
+     * 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 numBallotsToCount - The number of ballots to count for the calculation.
+     * @param useQuadraticVoting - Whether to use quadratic voting or not. Default is true.
+     * @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 genPerVOSpentVoiceCreditsCommitment;
+    /**
+     * 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 p - The Poll object to compare.
+     * @returns True if the two Poll objects are equal, false otherwise.
+     */
+    equals: (p: 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 numSignups - the number of signups
+     */
+    setNumSignups: (numSignups: bigint) => void;
+    /**
+     * Get the number of signups
+     * @returns The number of signups
+     */
+    getNumSignups: () => 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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"}