@crisp-e3/sdk 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { Hex } from 'viem';
  * @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[]>;
+declare const getTreeData: (serverUrl: string, e3Id: bigint) => Promise<bigint[]>;
 /**
  * Get the token balance at a specific block for a given address
  * @param voterAddress - The address of the voter
@@ -95,53 +95,71 @@ type ProofData = {
     proof: Uint8Array;
     encryptedVote: Uint8Array;
 };
-type MaskVoteProofInputs = {
-    publicKey: Uint8Array;
-    balance: bigint;
-    slotAddress: string;
-    merkleLeaves: string[] | bigint[];
+/**
+ * Which circuit a ballot is built for.
+ *
+ * `merkle` proves membership of a census tree, and matches `CensusMode.TOKEN` and
+ * `CensusMode.BY_REQUESTER`. `onchain` takes voting power as a public input that the contract
+ * reads from the token, and matches `CensusMode.ONCHAIN`.
+ */
+type CensusVariant = 'merkle' | 'onchain';
+type PrepareBallotInputsBase = {
     previousCiphertext?: Uint8Array;
-    numOptions: number;
-};
-type MaskVoteProofRequest = {
-    e3Id: number;
     publicKey: Uint8Array;
-    balance: bigint;
     slotAddress: string;
-    merkleLeaves: string[] | bigint[];
+    isMaskVote: boolean;
     numOptions: number;
-};
-type VoteProofInputs = {
-    merkleLeaves: string[] | bigint[];
-    publicKey: Uint8Array;
-    balance: bigint;
     vote: Vote;
-    signature: `0x${string}`;
-    messageHash: `0x${string}`;
-    slotAddress: string;
-    previousCiphertext?: Uint8Array;
 };
-type VoteProofRequest = {
-    e3Id: number;
-    merkleLeaves: string[] | bigint[];
-    publicKey: Uint8Array;
+/**
+ * Everything needed to encrypt a ballot, before the voter has signed anything.
+ */
+type PrepareBallotInputs = (PrepareBallotInputsBase & {
+    censusMode: 'merkle';
     balance: bigint;
-    vote: Vote;
-    signature: `0x${string}`;
-    messageHash: `0x${string}`;
-    slotAddress: string;
+    merkleLeaves: string[] | bigint[];
+}) | (PrepareBallotInputsBase & {
+    censusMode: 'onchain';
+    votingPower: bigint;
+});
+/**
+ * A ballot that is encrypted but not yet signed.
+ *
+ * `ctCommitment` is the value to pass to `CRISPProgram.ballotDigest`. Reading the digest from the
+ * contract rather than rebuilding the EIP-712 struct here keeps one implementation of the domain.
+ */
+type PreparedBallot = {
+    circuitInputs: any;
+    encryptedVote: Uint8Array;
+    ctCommitment: `0x${string}`;
+    censusMode: CensusVariant;
 };
+/**
+ * `Omit` that maps over each member of a union instead of collapsing it.
+ *
+ * A plain `Omit` on a discriminated union merges the members and loses the discriminant, which
+ * would let a caller pass `censusMode: 'onchain'` with no `votingPower`.
+ */
+type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
+/**
+ * A {@link PrepareBallotInputs} plus the round it belongs to.
+ *
+ * The SDK resolves `previousCiphertext` from the server, so callers do not pass it.
+ */
+type PrepareBallotRequest = {
+    e3Id: bigint;
+} & DistributiveOmit<PrepareBallotInputs, 'previousCiphertext'>;
 /**
  * Type representing the current round returned by the CRISP server (`rounds/current`)
  */
 type CurrentRoundResponse = {
-    id: number;
+    id: string;
 };
 /**
  * Type representing the lite state of a round returned by the CRISP server (`state/lite`)
  */
 type E3StateLiteResponse = {
-    id: number;
+    id: string;
     chain_id: number;
     interfold_address: string;
     status: string;
@@ -177,7 +195,7 @@ type NewRoundRequest = {
  * Type representing a request to broadcast an encrypted vote (`voting/broadcast`)
  */
 type BroadcastVoteRequest = {
-    e3Id: number;
+    e3Id: bigint;
     encodedProof: string;
     address: string;
 };
@@ -198,7 +216,7 @@ type BroadcastVoteResponse = {
  * Type representing the vote status of an address in a round (`voting/status`)
  */
 type VoteStatusResponse = {
-    round_id: number;
+    round_id: string;
     address: string;
     has_voted: boolean;
     round_status: string | null;
@@ -207,7 +225,7 @@ type VoteStatusResponse = {
  * Type representing the result of a round (`state/result` and `state/all`)
  */
 type WebResultResponse = {
-    round_id: number;
+    round_id: string;
     tally: string[];
     option_1_emoji: string;
     option_2_emoji: string;
@@ -238,14 +256,14 @@ declare enum CreditMode {
  * @param e3Id - The e3Id of the round
  * @returns The round details
  */
-declare const getRoundDetails: (serverUrl: string, e3Id: number) => Promise<RoundDetails>;
+declare const getRoundDetails: (serverUrl: string, e3Id: bigint) => Promise<RoundDetails>;
 /**
  * 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<TokenDetails>;
+declare const getRoundTokenDetails: (serverUrl: string, e3Id: bigint) => Promise<TokenDetails>;
 /**
  * Get the round data stored in the CRISPProgram contract, such as the merkle root
  * of the census and the merkle root of the encrypted votes published so far.
@@ -258,7 +276,7 @@ declare const getRoundTokenDetails: (serverUrl: string, e3Id: number) => Promise
  * @param chainId - The chain ID of the network the program is deployed on
  * @returns The on chain round data
  */
-declare const getOnChainRoundData: (programAddress: string, e3Id: number, chainId: number) => Promise<OnChainRoundData>;
+declare const getOnChainRoundData: (programAddress: string, e3Id: bigint, chainId: number) => Promise<OnChainRoundData>;
 /**
  * Get the previous ciphertext for a slot from the CRISP server.
  * Returns undefined when the slot is empty (404).
@@ -268,7 +286,7 @@ declare const getOnChainRoundData: (programAddress: string, e3Id: number, chainI
  * @param address - The address of the slot
  * @returns The previous ciphertext for the slot, or undefined if the slot is empty
  */
-declare const getPreviousCiphertext: (serverUrl: string, e3Id: number, address: string) => Promise<Uint8Array | undefined>;
+declare const getPreviousCiphertext: (serverUrl: string, e3Id: bigint, address: string) => Promise<Uint8Array | undefined>;
 
 /**
  * Get the current (most recent) round, optionally filtered by requester addresses.
@@ -284,14 +302,14 @@ declare const getCurrentRound: (serverUrl: string, requesters?: string[]) => Pro
  * @param e3Id - The e3Id of the round
  * @returns The committee public key bytes
  */
-declare const getRoundPublicKey: (serverUrl: string, e3Id: number) => Promise<Uint8Array>;
+declare const getRoundPublicKey: (serverUrl: string, e3Id: bigint) => Promise<Uint8Array>;
 /**
  * Get the ciphertext output for a given round.
  * @param serverUrl - The base URL of the CRISP server
  * @param e3Id - The e3Id of the round
  * @returns The ciphertext output bytes
  */
-declare const getRoundCiphertext: (serverUrl: string, e3Id: number) => Promise<Uint8Array>;
+declare const getRoundCiphertext: (serverUrl: string, e3Id: bigint) => Promise<Uint8Array>;
 /**
  * Request a new E3 round. Requires the server's cron API key.
  * @param serverUrl - The base URL of the CRISP server
@@ -313,14 +331,14 @@ declare const broadcastVote: (serverUrl: string, request: BroadcastVoteRequest)
  * @param address - The voter address
  * @returns The vote status for the address
  */
-declare const getVoteStatus: (serverUrl: string, e3Id: number, address: string) => Promise<VoteStatusResponse>;
+declare const getVoteStatus: (serverUrl: string, e3Id: bigint, address: string) => Promise<VoteStatusResponse>;
 /**
  * Get the result for a given round.
  * @param serverUrl - The base URL of the CRISP server
  * @param e3Id - The e3Id of the round
  * @returns The round result (tally, emojis, total votes, end time and requester)
  */
-declare const getRoundResult: (serverUrl: string, e3Id: number) => Promise<WebResultResponse>;
+declare const getRoundResult: (serverUrl: string, e3Id: bigint) => Promise<WebResultResponse>;
 /**
  * Get the results for all rounds, optionally filtered by requester addresses.
  * @param serverUrl - The base URL of the CRISP server
@@ -335,7 +353,7 @@ declare const getAllRoundResults: (serverUrl: string, requesters?: string[]) =>
  * @param e3Id - The e3Id of the round
  * @returns The lite round state
  */
-declare const getRoundStateLite: (serverUrl: string, e3Id: number) => Promise<E3StateLiteResponse>;
+declare const getRoundStateLite: (serverUrl: string, e3Id: bigint) => Promise<E3StateLiteResponse>;
 /**
  * Get the token holder hashes (hash(address, balance)) for a given round.
  * These are the Merkle tree leaves used for eligibility proofs.
@@ -343,14 +361,14 @@ declare const getRoundStateLite: (serverUrl: string, e3Id: number) => Promise<E3
  * @param e3Id - The e3Id of the round
  * @returns The list of token holder hashes
  */
-declare const getTokenHolderHashes: (serverUrl: string, e3Id: number) => Promise<string[]>;
+declare const getTokenHolderHashes: (serverUrl: string, e3Id: bigint) => Promise<string[]>;
 /**
  * Get the eligible addresses and their balances for a given round.
  * @param serverUrl - The base URL of the CRISP server
  * @param e3Id - The e3Id of the round
  * @returns The list of eligible token holders
  */
-declare const getEligibleAddresses: (serverUrl: string, e3Id: number) => Promise<TokenHolder[]>;
+declare const getEligibleAddresses: (serverUrl: string, e3Id: bigint) => Promise<TokenHolder[]>;
 
 declare const MERKLE_TREE_MAX_DEPTH = 20;
 declare const MAX_MSG_NON_ZERO_COEFFS = 100;
@@ -467,7 +485,27 @@ declare const generateBFVKeys: () => {
     publicKey: Uint8Array;
 };
 
+/**
+ * Split a 32-byte digest into the two 16-byte halves the circuit takes as public inputs.
+ *
+ * A Keccak digest is 256 bits and a field element holds fewer than 254, so it cannot cross the
+ * circuit boundary in one piece. `crisp_lib::ecdsa::digest_from_halves` rebuilds the 32 bytes and
+ * range-checks each half, and `CRISPProgram.publishInput` splits the same way.
+ *
+ * @param digest The 32-byte ballot digest.
+ * @returns The high and low halves as hex field elements.
+ */
+declare const splitDigest: (digest: `0x${string}`) => {
+    digestHi: `0x${string}`;
+    digestLo: `0x${string}`;
+};
+
 declare const destroyBBApi: () => void;
+/**
+ * Encrypt a ballot and build every circuit input that does not depend on the signature.
+ * Runs in a worker when available to avoid blocking the main thread.
+ */
+declare const prepareCircuitInputs: (inputs: PrepareBallotInputs) => Promise<PreparedBallot>;
 /**
  * Validate a vote.
  * @param vote - The vote to validate.
@@ -475,23 +513,48 @@ declare const destroyBBApi: () => void;
  */
 declare const validateVote: (vote: Vote, balance: bigint) => void;
 /**
- * Generate a vote proof for the CRISP circuit given the vote proof inputs.
- * @param voteProofInputs - The vote proof inputs.
- * @returns The vote proof.
+ * Phase one: encrypt a ballot, before the voter signs anything.
+ *
+ * A ballot must be encrypted before it can be signed, because the digest binds the ciphertext.
+ * Take `ctCommitment` from the result, read the digest from `CRISPProgram.ballotDigest`, have the
+ * voter sign it, then call {@link finishBallotProof}.
+ *
+ * @param inputs - The ballot to encrypt.
+ * @returns The prepared ballot.
+ */
+declare const prepareBallot: (inputs: PrepareBallotInputs) => Promise<PreparedBallot>;
+/**
+ * Phase two: prove a prepared ballot, given the signature over its digest.
+ *
+ * Get the digest from `CRISPProgram.ballotDigest(e3Id, slot, prepared.ctCommitment)` and have the
+ * voter sign it. Reading it from the contract rather than rebuilding the EIP-712 struct here means
+ * there is only one implementation of the domain to keep correct.
+ *
+ * @param prepared The output of `prepareBallot`.
+ * @param digest The ballot digest.
+ * @param signature The voter signature over that digest.
+ * @returns The proof.
  */
-declare const generateVoteProof: (voteProofInputs: VoteProofInputs) => Promise<ProofData>;
+declare const finishBallotProof: (prepared: PreparedBallot, digest: `0x${string}`, signature: `0x${string}`) => Promise<ProofData>;
 /**
- * Generate a proof for a vote masking operation.
- * @param maskVoteProofInputs The mask vote proof inputs.
- * @returns
+ * Phase two for a mask.
+ *
+ * A mask carries the same digest as a real vote, because `CRISPProgram.publishInput` computes it
+ * for every input regardless of branch. Only the signature is a placeholder, and the circuit does
+ * not check it on the mask branch. Passing a real digest here is what keeps a mask and a vote
+ * indistinguishable in the published public inputs.
+ *
+ * @param prepared The output of `prepareBallot` with `isMaskVote: true`.
+ * @param digest The ballot digest, from the same contract call a real vote would use.
+ * @returns The proof.
  */
-declare const generateMaskVoteProof: (maskVoteProofInputs: MaskVoteProofInputs) => Promise<ProofData>;
+declare const finishMaskProof: (prepared: PreparedBallot, digest: `0x${string}`) => Promise<ProofData>;
 /**
  * Locally verify a Noir proof.
  * @param proof - The proof to verify.
  * @returns True if the proof is valid, false otherwise.
  */
-declare const verifyProof: (proof: ProofData) => Promise<boolean>;
+declare const verifyProof: (proof: ProofData, censusMode?: CensusVariant) => Promise<boolean>;
 /**
  * Encode the proof data into a format that can be used by the CRISP program in Solidity
  * to validate the proof.
@@ -515,22 +578,33 @@ declare class CrispSDK {
      */
     constructor(serverUrl: string);
     /**
-     * Generate a proof for a vote masking.
-     * @param maskProofInputs - The inputs required to generate the mask vote proof.
-     * @returns A promise that resolves to the generated proof data.
+     * Phase one: encrypt a ballot, before the voter signs anything.
+     *
+     * A ballot has to be encrypted before it can be signed, because the digest binds the ciphertext.
+     * Take `ctCommitment` from the result, read the digest from
+     * `CRISPProgram.ballotDigest(e3Id, slot, ctCommitment)`, have the voter sign it, then call
+     * {@link finishBallot}.
+     *
+     * Masks and real votes take the same path. This method calls the same server API
+     * (previous-ciphertext) for both, so the server cannot infer the ballot type from the request
+     * pattern, and the encryption is identical either way.
+     *
+     * @param request - The ballot to encrypt.
+     * @returns A promise that resolves to the prepared ballot.
      */
-    generateMaskVoteProof(maskProofInputs: MaskVoteProofRequest): Promise<ProofData>;
+    prepareBallot(request: PrepareBallotRequest): Promise<PreparedBallot>;
     /**
-     * Generate a proof for a vote.
+     * Phase two: prove a prepared ballot.
      *
-     * Note: The previous ciphertext is not used in the proof computation. This method still calls
-     * the same server API (previous-ciphertext) as {@link generateMaskVoteProof} to prevent the
-     * server from inferring the vote type (mask vs normal) from the client's API usage pattern.
+     * A mask passes no signature and gets the placeholder. It still carries the same digest as a
+     * real vote, because the contract computes the digest for every input.
      *
-     * @param voteProofInputs - The inputs required to generate the vote proof.
+     * @param prepared - The output of {@link prepareBallot}.
+     * @param digest - The digest read from `CRISPProgram.ballotDigest`.
+     * @param signature - The voter signature, omitted for a mask.
      * @returns A promise that resolves to the generated proof data.
      */
-    generateVoteProof(voteProofInputs: VoteProofRequest): Promise<ProofData>;
+    finishBallot(prepared: PreparedBallot, digest: `0x${string}`, signature?: `0x${string}`): Promise<ProofData>;
     /**
      * Get the current (most recent) round, optionally filtered by requester addresses.
      * @param requesters - Optional list of requester addresses to filter by
@@ -542,13 +616,13 @@ declare class CrispSDK {
      * @param e3Id - The e3Id of the round
      * @returns The committee public key bytes
      */
-    getRoundPublicKey(e3Id: number): Promise<Uint8Array>;
+    getRoundPublicKey(e3Id: bigint): Promise<Uint8Array>;
     /**
      * Get the ciphertext output for a given round.
      * @param e3Id - The e3Id of the round
      * @returns The ciphertext output bytes
      */
-    getRoundCiphertext(e3Id: number): Promise<Uint8Array>;
+    getRoundCiphertext(e3Id: bigint): Promise<Uint8Array>;
     /**
      * Request a new E3 round. Requires the server's cron API key.
      * @param request - The new round request (cron API key, token address and balance threshold)
@@ -567,13 +641,13 @@ declare class CrispSDK {
      * @param address - The voter address
      * @returns The vote status for the address
      */
-    getVoteStatus(e3Id: number, address: string): Promise<VoteStatusResponse>;
+    getVoteStatus(e3Id: bigint, address: string): Promise<VoteStatusResponse>;
     /**
      * Get the result for a given round.
      * @param e3Id - The e3Id of the round
      * @returns The round result (tally, emojis, total votes, end time and requester)
      */
-    getRoundResult(e3Id: number): Promise<WebResultResponse>;
+    getRoundResult(e3Id: bigint): Promise<WebResultResponse>;
     /**
      * Get the results for all rounds, optionally filtered by requester addresses.
      * @param requesters - Optional list of requester addresses to filter by
@@ -585,13 +659,13 @@ declare class CrispSDK {
      * @param e3Id - The e3Id of the round
      * @returns The lite round state
      */
-    getRoundStateLite(e3Id: number): Promise<E3StateLiteResponse>;
+    getRoundStateLite(e3Id: bigint): Promise<E3StateLiteResponse>;
     /**
      * Get the details of a specific round in a camelCase convenience format.
      * @param e3Id - The e3Id of the round
      * @returns The round details
      */
-    getRoundDetails(e3Id: number): Promise<RoundDetails>;
+    getRoundDetails(e3Id: bigint): Promise<RoundDetails>;
     /**
      * Get the round data stored in the CRISPProgram contract, read directly from the chain.
      *
@@ -602,33 +676,33 @@ declare class CrispSDK {
      * @param chainId - The chain ID of the network the program is deployed on
      * @returns The on chain round data
      */
-    getOnChainRoundData(programAddress: string, e3Id: number, chainId?: number): Promise<OnChainRoundData>;
+    getOnChainRoundData(programAddress: string, e3Id: bigint, chainId?: number): Promise<OnChainRoundData>;
     /**
      * Get the token address, balance threshold and snapshot block for a specific round.
      * @param e3Id - The e3Id of the round
      * @returns The token details
      */
-    getRoundTokenDetails(e3Id: number): Promise<TokenDetails>;
+    getRoundTokenDetails(e3Id: bigint): Promise<TokenDetails>;
     /**
      * Get the token holder hashes (hash(address, balance)) for a given round.
      * These are the Merkle tree leaves used for eligibility proofs.
      * @param e3Id - The e3Id of the round
      * @returns The list of token holder hashes
      */
-    getTokenHolderHashes(e3Id: number): Promise<string[]>;
+    getTokenHolderHashes(e3Id: bigint): Promise<string[]>;
     /**
      * Get the eligible addresses and their balances for a given round.
      * @param e3Id - The e3Id of the round
      * @returns The list of eligible token holders
      */
-    getEligibleAddresses(e3Id: number): Promise<TokenHolder[]>;
+    getEligibleAddresses(e3Id: bigint): Promise<TokenHolder[]>;
     /**
      * Get the previous ciphertext input for a slot address in a given round.
      * @param e3Id - The e3Id of the round
      * @param address - The address of the slot
      * @returns The previous ciphertext, or undefined if the slot is empty
      */
-    getPreviousCiphertext(e3Id: number, address: string): Promise<Uint8Array | undefined>;
+    getPreviousCiphertext(e3Id: bigint, address: string): Promise<Uint8Array | undefined>;
 }
 
-export { type BroadcastVoteRequest, type BroadcastVoteResponse, CreditMode, CrispSDK, type CurrentRoundResponse, type E3StateLiteResponse, type JsonResponse, MAX_MSG_NON_ZERO_COEFFS, MAX_VOTE_OPTIONS, MERKLE_TREE_MAX_DEPTH, type MaskVoteProofInputs, type NewRoundRequest, type OnChainRoundData, type ProofData, type RoundDetails, SIGNATURE_MESSAGE, SIGNATURE_MESSAGE_HASH, type TallyResult, type TokenDetails, type TokenHolder, type Vote, type VoteProofInputs, type VoteResponseStatus, type VoteStatusResponse, type WebResultResponse, broadcastVote, decodeTally, decryptVote, destroyBBApi, encodeSolidityProof, encodeVote, encryptVote, generateBFVKeys, generateMaskVoteProof, generateMerkleProof, generateMerkleTree, generateVoteProof, getAddressFromSignature, getAllRoundResults, getBalanceAt, getCurrentRound, getEligibleAddresses, getMaxVoteValue, getOnChainRoundData, getPreviousCiphertext, getRoundCiphertext, getRoundDetails, getRoundPublicKey, getRoundResult, getRoundStateLite, getRoundTokenDetails, getScaledBalance, getTokenHolderHashes, getTotalSupplyAt, getTreeData, getVoteStatus, getZeroVote, hashLeaf, requestNewRound, validateVote, verifyProof };
+export { type BroadcastVoteRequest, type BroadcastVoteResponse, type CensusVariant, CreditMode, CrispSDK, type CurrentRoundResponse, type E3StateLiteResponse, type JsonResponse, MAX_MSG_NON_ZERO_COEFFS, MAX_VOTE_OPTIONS, MERKLE_TREE_MAX_DEPTH, type NewRoundRequest, type OnChainRoundData, type PrepareBallotInputs, type PrepareBallotRequest, type PreparedBallot, type ProofData, type RoundDetails, SIGNATURE_MESSAGE, SIGNATURE_MESSAGE_HASH, type TallyResult, type TokenDetails, type TokenHolder, type Vote, type VoteResponseStatus, type VoteStatusResponse, type WebResultResponse, broadcastVote, decodeTally, decryptVote, destroyBBApi, encodeSolidityProof, encodeVote, encryptVote, finishBallotProof, finishMaskProof, generateBFVKeys, generateMerkleProof, generateMerkleTree, getAddressFromSignature, getAllRoundResults, getBalanceAt, getCurrentRound, getEligibleAddresses, getMaxVoteValue, getOnChainRoundData, getPreviousCiphertext, getRoundCiphertext, getRoundDetails, getRoundPublicKey, getRoundResult, getRoundStateLite, getRoundTokenDetails, getScaledBalance, getTokenHolderHashes, getTotalSupplyAt, getTreeData, getVoteStatus, getZeroVote, hashLeaf, prepareBallot, prepareCircuitInputs, requestNewRound, splitDigest, validateVote, verifyProof };