@crisp-e3/sdk 0.16.0 → 0.18.0-insecure.0

package/dist/circuits-BWegRaZy.d.ts

@@ -0,0 +1,49 @@
+import { CompiledCircuit } from '@noir-lang/noir_js';
+
+/** BFV parameter sets the circuits can be compiled against. */
+type CircuitPreset = 'insecure-512' | 'secure-8192';
+/**
+ * The circuits whose ABI is shaped by the BFV degree, and which therefore exist once per preset.
+ *
+ * The aggregation circuits — `crisp_fold`, `crisp_onchain_fold` and `user_data_encryption` — are
+ * deliberately absent. Their parameters are proof and verification-key shaped (410/115 fields), not
+ * polynomial shaped, so one compiled artifact serves both presets; the fold circuits assert
+ * `chain_key_hash` against the insecure *or* the secure constant for exactly that reason. They ship
+ * in the main entry point, which is why `verifyProof` works without a preset loaded.
+ */
+type CircuitBundle = {
+    readonly preset: CircuitPreset;
+    readonly crisp: CompiledCircuit;
+    readonly crispOnchain: CompiledCircuit;
+    readonly userDataEncryptionCt0: CompiledCircuit;
+    readonly userDataEncryptionCt1: CompiledCircuit;
+};
+/**
+ * Install the preset-bound circuits used by `generateProof`.
+ *
+ * The bundle is not bundled into the main entry point, because the secure-8192 artifacts are more
+ * than an order of magnitude larger than the insecure-512 ones and no consumer needs both. Load the
+ * one you want from its subpath and register it once at start-up:
+ *
+ * ```ts
+ * import { setCircuits } from '@crisp-e3/sdk'
+ * import { loadCircuits } from '@crisp-e3/sdk/insecure-512'
+ *
+ * setCircuits(await loadCircuits())
+ * ```
+ */
+declare const setCircuits: (bundle: CircuitBundle) => void;
+/** The registered bundle, or `null` when none has been installed yet. */
+declare const getRegisteredCircuits: () => CircuitBundle | null;
+/** The preset currently installed, or `null` when none has been installed yet. */
+declare const registeredPreset: () => CircuitPreset | null;
+/**
+ * The registered bundle, throwing a directed error when nothing has been installed.
+ *
+ * Proving cannot fall back to a default preset: a ballot proved against the wrong parameters fails
+ * on chain rather than locally, so guessing here would move the failure somewhere much harder to
+ * read.
+ */
+declare const requireCircuits: () => CircuitBundle;
+
+export { type CircuitBundle as C, type CircuitPreset as a, requireCircuits as b, getRegisteredCircuits as g, registeredPreset as r, setCircuits as s };

package/dist/index.d.ts

@@ -1,12 +1,14 @@
+export { C as CircuitBundle, a as CircuitPreset, g as getRegisteredCircuits, r as registeredPreset, b as requireCircuits, s as setCircuits } from './circuits-BWegRaZy.js';
 import { LeanIMTMerkleProof, LeanIMT } from '@zk-kit/lean-imt';
 import { Hex } from 'viem';
+import '@noir-lang/noir_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[]>;
+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
@@ -94,54 +96,125 @@ type ProofData = {
     publicInputs: string[];
     proof: Uint8Array;
     encryptedVote: Uint8Array;
+    /**
+     * The tree index of the entry this input extends, plus one; zero when it extends nothing.
+     *
+     * `CRISPProgram` reads the parent's commitment from this and hands it to the circuit as
+     * `prev_ct_commitment`, and the Secure Process walks each slot's chain by it. Offset by one so
+     * that zero means "no parent", which is what index 0 would otherwise be ambiguous with.
+     */
+    parentIndexPlusOne: number;
 };
-type MaskVoteProofInputs = {
-    publicKey: Uint8Array;
-    balance: bigint;
-    slotAddress: string;
-    merkleLeaves: string[] | bigint[];
-    previousCiphertext?: Uint8Array;
-    numOptions: number;
+/**
+ * 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';
+/**
+ * The two halves of a slot head, which only mean anything together.
+ *
+ * Modelled as a pair rather than two optional fields: a ciphertext without its index would be
+ * proven against one entry and published against another, and the mismatch only surfaces as a
+ * rejected proof.
+ */
+type SlotHeadInputs = {
+    /**
+     * The ciphertext currently in the slot: the end of its chain of usable entries, not simply
+     * the newest one published. An entry whose bytes do not reproduce its commitment is never
+     * selected by the Secure Process and is never a valid parent, so building on it would have
+     * this input dropped from the tally.
+     */
+    previousCiphertext: Uint8Array;
+    /** The tree index of `previousCiphertext`, which this input names as its parent. */
+    previousIndex: number;
+} | {
+    previousCiphertext?: undefined;
+    previousIndex?: undefined;
 };
-type MaskVoteProofRequest = {
-    e3Id: number;
+type PrepareBallotInputsBase = {
     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;
+} & SlotHeadInputs;
+/**
+ * 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;
+    /**
+     * The ciphertext to publish, which is the ballot itself for a vote or a re-vote, and the slot's
+     * ciphertext plus the zero ballot for a mask over an occupied slot.
+     */
+    encryptedVote: Uint8Array;
+    /**
+     * The commitment to `encryptedVote`: what the circuit returns, what the E3 program stores, and
+     * what `CRISPProgram.ballotDigest` takes as its `ciphertextCommitment` argument.
+     *
+     * Since the digest is itself a circuit input, a caller has to know this value before proving,
+     * which is why the wasm exports it rather than leaving it to be read off the finished proof.
+     */
+    ctCommitment: `0x${string}`;
+    /** The value {@link ProofData.parentIndexPlusOne} carries through to `encodeSolidityProof`. */
+    parentIndexPlusOne: number;
+    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 the slot head from the server, so callers pass neither part of it.
+ */
+type PrepareBallotRequest = {
+    e3Id: bigint;
+} & DistributiveOmit<PrepareBallotInputs, 'previousCiphertext' | 'previousIndex'>;
+/**
+ * The end of a slot's chain of usable entries: what a new input extends.
+ *
+ * Not simply the newest entry published to the slot. An entry whose bytes do not reproduce its
+ * commitment is never selected by the Secure Process and is never a valid parent, so the server
+ * resolves the chain and answers with the entry that actually holds the slot.
+ */
+type SlotHead = {
+    ciphertext: Uint8Array;
+    /** The tree index of that entry. */
+    index: number;
 };
 /**
  * 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 +250,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 +271,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 +280,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 +311,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 +331,23 @@ 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 voting power a slot may spend in a `CensusMode.ONCHAIN` round, in ballot units.
+ *
+ * Read from the CRISP program rather than derived here. The contract scales raw token power by a
+ * per-round divisor before handing it to the circuit as public input 4, and it is the same
+ * contract that verifies the proof — so recomputing the value client-side would mean re-deriving
+ * the round's snapshot, its divisor and the rounding, and any drift surfaces only as an opaque
+ * verifier failure.
+ *
+ * @param programAddress - The CRISP program address
+ * @param e3Id - The e3Id of the round
+ * @param slot - The slot address the ballot is written to
+ * @param chainId - The chain the program is deployed on
+ * @returns The spendable voting power in ballot units, or 0 for a round that is not ONCHAIN
+ */
+declare const getOnchainVotingPower: (programAddress: string, e3Id: bigint, slot: string, chainId: number) => Promise<bigint>;
 /**
  * Get the previous ciphertext for a slot from the CRISP server.
  * Returns undefined when the slot is empty (404).
@@ -266,9 +355,10 @@ declare const getOnChainRoundData: (programAddress: string, e3Id: number, chainI
  * @param serverUrl - The base URL of the CRISP server
  * @param e3Id - The e3Id of the round
  * @param address - The address of the slot
- * @returns The previous ciphertext for the slot, or undefined if the slot is empty
+ * @returns The end of the slot's chain of usable entries and its tree index, or undefined when the
+ *          slot holds nothing usable. The index is what a new input names as its parent.
  */
-declare const getPreviousCiphertext: (serverUrl: string, e3Id: number, address: string) => Promise<Uint8Array | undefined>;
+declare const getPreviousCiphertext: (serverUrl: string, e3Id: bigint, address: string) => Promise<SlotHead | undefined>;
 
 /**
  * Get the current (most recent) round, optionally filtered by requester addresses.
@@ -284,14 +374,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 +403,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 +425,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 +433,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 +557,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,30 +585,55 @@ 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 generateVoteProof: (voteProofInputs: VoteProofInputs) => Promise<ProofData>;
+declare const prepareBallot: (inputs: PrepareBallotInputs) => Promise<PreparedBallot>;
 /**
- * Generate a proof for a vote masking operation.
- * @param maskVoteProofInputs The mask vote proof inputs.
- * @returns
+ * 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 finishBallotProof: (prepared: PreparedBallot, digest: `0x${string}`, signature: `0x${string}`) => Promise<ProofData>;
+/**
+ * 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.
  * @param proof The proof data.
  * @returns The encoded proof data as a hex string.
  */
-declare const encodeSolidityProof: ({ publicInputs, proof, encryptedVote }: ProofData) => Hex;
+declare const encodeSolidityProof: ({ publicInputs, proof, encryptedVote, parentIndexPlusOne }: ProofData) => Hex;
 
 /**
  * A class representing the CRISP SDK.
@@ -515,22 +650,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 +688,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 +713,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 +731,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 +748,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
+     * @returns The slot head and its tree index, or undefined if the slot holds nothing usable
      */
-    getPreviousCiphertext(e3Id: number, address: string): Promise<Uint8Array | undefined>;
+    getPreviousCiphertext(e3Id: bigint, address: string): Promise<SlotHead | 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 SlotHead, 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, getOnchainVotingPower, getPreviousCiphertext, getRoundCiphertext, getRoundDetails, getRoundPublicKey, getRoundResult, getRoundStateLite, getRoundTokenDetails, getScaledBalance, getTokenHolderHashes, getTotalSupplyAt, getTreeData, getVoteStatus, getZeroVote, hashLeaf, prepareBallot, prepareCircuitInputs, requestNewRound, splitDigest, validateVote, verifyProof };