@crisp-e3/sdk 0.0.1-test → 0.0.2-test

package/dist/index.d.ts

@@ -0,0 +1,365 @@
+import { LeanIMTMerkleProof, LeanIMT } from '@zk-kit/lean-imt';
+import { ProofData } from '@aztec/bb.js';
+
+/**
+ * Get the merkle tree data from the CRISP server
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ */
+declare const getTreeData: (serverUrl: string, e3Id: number) => Promise<bigint[]>;
+/**
+ * Get the token balance at a specific block for a given address
+ * @param voterAddress - The address of the voter
+ * @param tokenAddress - The address of the token contract
+ * @param snapshotBlock - The block number at which to get the balance
+ * @param chainId - The chain ID of the network
+ * @returns The token balance as a bigint
+ */
+declare const getBalanceAt: (voterAddress: string, tokenAddress: string, snapshotBlock: number, chainId: number) => Promise<bigint>;
+/**
+ * Get the total supply of a ERC20Votes Token at a specific block
+ * @param tokenAddress The token address to query
+ * @param snapshotBlock The block number at which to get the total supply
+ * @param chainId The chain ID of the network
+ * @returns The total supply as a bigint
+ */
+declare const getTotalSupplyAt: (tokenAddress: string, snapshotBlock: number, chainId: number) => Promise<bigint>;
+
+/**
+ * Interface representing the details of a specific round returned by the CRISP server
+ */
+interface IRoundDetailsResponse {
+    id: string;
+    chain_id: string;
+    enclave_address: string;
+    status: string;
+    vote_count: string;
+    start_time: string;
+    duration: string;
+    expiration: string;
+    start_block: string;
+    committee_public_key: string[];
+    emojis: [string, string];
+    token_address: string;
+    balance_threshold: string;
+}
+/**
+ * Interface representing the details of a specific round in a more convenient format
+ */
+interface IRoundDetails {
+    e3Id: bigint;
+    chainId: bigint;
+    enclaveAddress: string;
+    status: string;
+    voteCount: bigint;
+    startTime: bigint;
+    duration: bigint;
+    expiration: bigint;
+    startBlock: bigint;
+    committeePublicKey: string[];
+    emojis: [string, string];
+    tokenAddress: string;
+    balanceThreshold: bigint;
+}
+/**
+ * Interface representing the token details required for participation in a round
+ */
+interface ITokenDetails {
+    tokenAddress: string;
+    threshold: bigint;
+    snapshotBlock: bigint;
+}
+/**
+ * Interface representing a Merkle proof
+ */
+interface IMerkleProof {
+    leaf: bigint;
+    index: number;
+    proof: LeanIMTMerkleProof<bigint>;
+    length: number;
+    indices: number[];
+}
+/**
+ * Enum representing the voting modes
+ */
+declare enum VotingMode {
+    /**
+     *  Governance voting requires to spend all credits on one option
+        they cannot be split
+     */
+    GOVERNANCE = "GOVERNANCE"
+}
+/**
+ * Interface representing a vote with power for 'yes' and 'no'
+ */
+interface IVote {
+    /**
+     * The voting power for 'yes' votes
+     */
+    yes: bigint;
+    /**
+     * The voting power for 'no' votes
+     */
+    no: bigint;
+}
+/**
+ * Interface representing a vector with coefficients
+ */
+interface Polynomial {
+    coefficients: string[];
+}
+/**
+ * Interface representing cryptographic parameters
+ */
+interface GrecoCryptographicParams {
+    q_mod_t: string;
+    qis: string[];
+    k0is: string[];
+}
+/**
+ * Interface representing Greco bounds
+ */
+interface GrecoBoundParams {
+    e_bound: string;
+    u_bound: string;
+    k1_low_bound: string;
+    k1_up_bound: string;
+    p1_bounds: string[];
+    p2_bounds: string[];
+    pk_bounds: string[];
+    r1_low_bounds: string[];
+    r1_up_bounds: string[];
+    r2_bounds: string[];
+}
+/**
+ * Interface representing Greco parameters
+ */
+interface GrecoParams {
+    crypto: GrecoCryptographicParams;
+    bounds: GrecoBoundParams;
+}
+/**
+ * The inputs required for the CRISP circuit
+ */
+interface CRISPCircuitInputs {
+    prev_ct0is: Polynomial[];
+    prev_ct1is: Polynomial[];
+    sum_ct0is: Polynomial[];
+    sum_ct1is: Polynomial[];
+    sum_r0is: Polynomial[];
+    sum_r1is: Polynomial[];
+    params: GrecoParams;
+    ct0is: Polynomial[];
+    ct1is: Polynomial[];
+    pk0is: Polynomial[];
+    pk1is: Polynomial[];
+    r1is: Polynomial[];
+    r2is: Polynomial[];
+    p1is: Polynomial[];
+    p2is: Polynomial[];
+    u: Polynomial;
+    e0: Polynomial;
+    e1: Polynomial;
+    k1: Polynomial;
+    public_key_x: string[];
+    public_key_y: string[];
+    signature: string[];
+    hashed_message: string[];
+    merkle_root: string;
+    merkle_proof_length: string;
+    merkle_proof_indices: string[];
+    merkle_proof_siblings: string[];
+    slot_address: string;
+    balance: string;
+    is_first_vote: boolean;
+}
+/**
+ * Interface representing the BFV parameters
+ */
+interface BFVParams {
+    degree: number;
+    plaintextModulus: bigint;
+    moduli: BigInt64Array;
+}
+/**
+ * Interface representing the inputs for Noir signature verification
+ */
+interface NoirSignatureInputs {
+    /**
+     * X coordinate of the public key
+     */
+    pub_key_x: Uint8Array;
+    /**
+     * Y coordinate of the public key
+     */
+    pub_key_y: Uint8Array;
+    /**
+     * The signature to verify
+     */
+    signature: Uint8Array;
+    /**
+     * The hashed message that was signed
+     */
+    hashed_message: Uint8Array;
+}
+/**
+ * Parameters for encryptVoteAndGenerateCRISPInputs function
+ */
+interface EncryptVoteAndGenerateCRISPInputsParams {
+    encodedVote: string[];
+    publicKey: Uint8Array;
+    previousCiphertext: Uint8Array;
+    signature: `0x${string}`;
+    message: string;
+    merkleData: IMerkleProof;
+    balance: bigint;
+    bfvParams?: BFVParams;
+    slotAddress: string;
+    isFirstVote: boolean;
+}
+
+/**
+ * Get the details of a specific round
+ */
+declare const getRoundDetails: (serverUrl: string, e3Id: number) => Promise<IRoundDetails>;
+/**
+ * Get the token address, balance threshold and snapshot block for a specific round
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @returns The token address, balance threshold and snapshot block
+ */
+declare const getRoundTokenDetails: (serverUrl: string, e3Id: number) => Promise<ITokenDetails>;
+
+declare const CRISP_SERVER_TOKEN_TREE_ENDPOINT = "state/token-holders";
+declare const CRISP_SERVER_STATE_LITE_ENDPOINT = "state/lite";
+/**
+ * Half the minimum degree needed to support the maxium vote value
+ * If you change MAXIMUM_VOTE_VALUE, make sure to update this value too.
+ */
+declare const HALF_LARGEST_MINIMUM_DEGREE = 28;
+/**
+ * This is the maximum value for a vote (Yes or No). This is 2^28 - 1
+ * The minimum degree that BFV should use is 56 (to accommodate both Yes and No votes)
+ */
+declare const MAXIMUM_VOTE_VALUE: bigint;
+/**
+ * Default BFV parameters for the CRISP ZK inputs generator.
+ * These are the parameters used for the default testing purposes only.
+ */
+declare const DEFAULT_BFV_PARAMS: BFVParams;
+/**
+ * Mock message for masking signature
+ */
+declare const MESSAGE = "Vote for round 0";
+
+/**
+ * Hash a leaf node for the Merkle tree
+ * @param address The voter's address
+ * @param balance The voter's balance
+ * @returns The hashed leaf as a bigint
+ */
+declare const hashLeaf: (address: string, balance: string) => bigint;
+/**
+ * Generate a new LeanIMT with the leaves provided
+ * @param leaves The leaves of the Merkle tree
+ * @returns the generated Merkle tree
+ */
+declare const generateMerkleTree: (leaves: bigint[]) => LeanIMT;
+/**
+ * Generate a Merkle proof for a given address to prove inclusion in the voters' list
+ * @param threshold The minimum balance required to be eligible
+ * @param balance The voter's balance
+ * @param address The voter's address
+ * @param leaves The leaves of the Merkle tree
+ * @param maxDepth The maximum depth of the Merkle tree
+ */
+declare const generateMerkleProof: (threshold: bigint, balance: bigint, address: string, leaves: bigint[], maxDepth: number) => IMerkleProof;
+/**
+ * Convert a number to its binary representation
+ * @param number The number to convert to binary
+ * @returns The binary representation of the number as a string
+ */
+declare const toBinary: (number: bigint) => string;
+
+/**
+ * This utility function calculates the first valid index for vote options
+ * based on the total voting power and degree.
+ * @dev This is needed to calculate the decoded plaintext
+ * @dev Also, we will need to check in the circuit that anything within these indices is
+ * either 0 or 1.
+ * @param totalVotingPower The maximum vote amount (if a single voter had all of the power)
+ * @param degree The degree of the polynomial
+ */
+declare const calculateValidIndicesForPlaintext: (totalVotingPower: bigint, degree: number) => {
+    yesIndex: number;
+    noIndex: number;
+};
+/**
+ * Encode a vote based on the voting mode
+ * @param vote The vote to encode
+ * @param votingMode The voting mode to use for encoding
+ * @param votingPower The voting power of the voter
+ * @param bfvParams The BFV parameters to use for encoding
+ * @returns The encoded vote as a string
+ */
+declare const encodeVote: (vote: IVote, votingMode: VotingMode, votingPower: bigint, bfvParams?: BFVParams) => string[];
+/**
+ * Given an encoded tally, decode it into its decimal representation
+ * @param tally The encoded tally to decode
+ * @param votingMode The voting mode
+ */
+declare const decodeTally: (tally: string[], votingMode: VotingMode) => IVote;
+/**
+ * Validate whether a vote is valid for a given voting mode
+ * @param votingMode The voting mode to validate against
+ * @param vote The vote to validate
+ * @param votingPower The voting power of the voter
+ */
+declare const validateVote: (votingMode: VotingMode, vote: IVote, votingPower: bigint) => void;
+/**
+ * This is a wrapper around enclave-e3/sdk encryption functions as CRISP circuit will require some more
+ * input values which generic Greco do not need.
+ * @param encodedVote The encoded vote as string array
+ * @param publicKey The public key to use for encryption
+ * @param previousCiphertext The previous ciphertext to use for addition operation
+ * @param bfvParams The BFV parameters to use for encryption
+ * @param merkleData The merkle proof data
+ * @param message The message that was signed
+ * @param signature The signature of the message
+ * @param balance The voter's balance
+ * @param slotAddress The voter's slot address
+ * @param isFirstVote Whether this is the first vote for this slot
+ * @returns The CRISP circuit inputs
+ */
+declare const encryptVoteAndGenerateCRISPInputs: ({ encodedVote, publicKey, previousCiphertext, bfvParams, merkleData, message, signature, balance, slotAddress, isFirstVote, }: EncryptVoteAndGenerateCRISPInputsParams) => Promise<CRISPCircuitInputs>;
+/**
+ * A function to generate the data required to mask a vote
+ * @param voter The voter's address
+ * @param publicKey The voter's public key
+ * @param previousCiphertext The previous ciphertext
+ * @param bfvParams The BFV parameters
+ * @param merkleRoot The merkle root of the census tree
+ * @param slotAddress The voter's slot address
+ * @param isFirstVote Whether this is the first vote for this slot
+ * @returns The CRISP circuit inputs for a mask vote
+ */
+declare const generateMaskVote: (publicKey: Uint8Array, previousCiphertext: Uint8Array, bfvParams: BFVParams | undefined, merkleRoot: bigint, slotAddress: string, isFirstVote: boolean) => Promise<CRISPCircuitInputs>;
+declare const generateProof: (crispInputs: CRISPCircuitInputs) => Promise<ProofData>;
+declare const generateProofWithReturnValue: (crispInputs: CRISPCircuitInputs) => Promise<{
+    returnValue: unknown;
+    proof: ProofData;
+}>;
+declare const getCircuitOutputValue: (crispInputs: CRISPCircuitInputs) => Promise<{
+    returnValue: unknown;
+}>;
+declare const verifyProof: (proof: ProofData) => Promise<boolean>;
+
+/**
+ * Given a message and its signed version, extract the signature components
+ * @param message The original message
+ * @param signedMessage The signed message (signature)
+ * @returns The extracted signature components
+ */
+declare const extractSignature: (message: string, signedMessage: `0x${string}`) => Promise<NoirSignatureInputs>;
+
+export { type CRISPCircuitInputs, CRISP_SERVER_STATE_LITE_ENDPOINT, CRISP_SERVER_TOKEN_TREE_ENDPOINT, DEFAULT_BFV_PARAMS, HALF_LARGEST_MINIMUM_DEGREE, type IMerkleProof, type IRoundDetails, type IRoundDetailsResponse, type ITokenDetails, type IVote, MAXIMUM_VOTE_VALUE, MESSAGE, type NoirSignatureInputs, VotingMode, calculateValidIndicesForPlaintext, decodeTally, encodeVote, encryptVoteAndGenerateCRISPInputs, extractSignature, generateMaskVote, generateMerkleProof, generateMerkleTree, generateProof, generateProofWithReturnValue, getBalanceAt, getCircuitOutputValue, getRoundDetails, getRoundTokenDetails, getTotalSupplyAt, getTreeData, hashLeaf, toBinary, validateVote, verifyProof };