@crisp-e3/sdk 0.5.12 → 0.7.0

package/README.md

@@ -149,10 +149,10 @@ const address = await getAddressFromSignature(signature, messageHash)
 #### State Utilities
 
 ```typescript
-import { getPreviousCiphertext, getIsSlotEmpty } from '@crisp-e3/sdk'
+import { getPreviousCiphertext } from '@crisp-e3/sdk'
 
 const previousCiphertext = await getPreviousCiphertext(serverUrl, e3Id, slotAddress)
-const isEmpty = await getIsSlotEmpty(serverUrl, e3Id, slotAddress)
+// Returns undefined when the slot is empty (404)
 ```
 
 ## API
@@ -170,10 +170,8 @@ const isEmpty = await getIsSlotEmpty(serverUrl, e3Id, slotAddress)
 - `getRoundDetails(serverUrl: string, e3Id: number): Promise<RoundDetails>` - Get round details
 - `getRoundTokenDetails(serverUrl: string, e3Id: number): Promise<TokenDetails>` - Get token details
   for a round
-- `getPreviousCiphertext(serverUrl: string, e3Id: number, address: string): Promise<Uint8Array>` -
-  Get previous ciphertext for a slot
-- `getIsSlotEmpty(serverUrl: string, e3Id: number, address: string): Promise<boolean>` - Check if a
-  slot is empty
+- `getPreviousCiphertext(serverUrl: string, e3Id: number, address: string): Promise<Uint8Array | undefined>` -
+  Get previous ciphertext for a slot (undefined when slot is empty)
 
 ### Token Functions
 

package/dist/index.d.ts

@@ -82,7 +82,7 @@ type MerkleProof = {
 /**
  * Type representing a vote
  */
-type Vote = bigint[];
+type Vote = number[];
 type ProofData = {
     publicInputs: string[];
     proof: Uint8Array;
@@ -146,21 +146,15 @@ declare const getRoundDetails: (serverUrl: string, e3Id: number) => Promise<Roun
  */
 declare const getRoundTokenDetails: (serverUrl: string, e3Id: number) => Promise<TokenDetails>;
 /**
- * Get the previous ciphertext for a slot from the CRISP server
+ * Get the previous ciphertext for a slot from the CRISP server.
+ * Returns undefined when the slot is empty (404).
+ *
  * @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
+ * @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>;
-/**
- * Check if a slot is empty for a given E3 ID and slot address
- * @param serverUrl - The base URL of the CRISP server
- * @param e3Id - The e3Id of the round
- * @param address - The address of the slot
- * @returns Whether the slot is empty or not
- */
-declare const getIsSlotEmpty: (serverUrl: string, e3Id: number, address: string) => Promise<boolean>;
+declare const getPreviousCiphertext: (serverUrl: string, e3Id: number, address: string) => Promise<Uint8Array | undefined>;
 
 declare const MERKLE_TREE_MAX_DEPTH = 20;
 /**
@@ -197,33 +191,51 @@ declare const getAddressFromSignature: (signature: `0x${string}`, messageHash?:
  * @param numChoices Number of choices.
  * @returns Maximum value per choice.
  */
-declare const getMaxVoteValue: (numChoices: number) => bigint;
+declare const getMaxVoteValue: (numChoices: number) => number;
 /**
  * Get a zero vote with the given number of choices.
  * @param numChoices Number of choices.
  * @returns A zero vote with the given number of choices.
  */
-declare const getZeroVote: (numChoices: number) => bigint[];
+declare const getZeroVote: (numChoices: number) => number[];
 
 /**
- * Decode an encoded tally into vote counts for n choices.
- * @param tallyBytes The encoded tally as a hex string.
- * @param numChoices Number of choices.
- * @returns Array of vote counts per choice.
+ * Vote encoding and BFV encryption for the CRISP voting protocol.
+ *
+ * Encodes vote choices (numbers per option) into polynomial coefficient arrays
+ * suitable for BFV homomorphic encryption. Each choice is represented as a
+ * segment of binary digits, padded to fit the polynomial degree. Supports
+ * encoding, encryption, decryption, and tally decoding.
  */
-declare const decodeTally: (tallyBytes: string, numChoices: number) => Vote;
+
 /**
- * Encrypt the vote using the public key.
- * @param vote - The vote to encrypt.
- * @param publicKey - The public key to use for encryption.
- * @returns The encrypted vote as a Uint8Array.
+ * Encrypts an encoded vote using BFV homomorphic encryption.
+ *
+ * @param vote - Vote choices to encrypt
+ * @param publicKey - BFV public key
+ * @returns Encrypted ciphertext
  */
 declare const encryptVote: (vote: Vote, publicKey: Uint8Array) => Uint8Array;
 /**
- * Generate a random public key.
- * @returns The generated public key as a Uint8Array.
+ * Decodes raw tally bytes (or hex string) into vote values per choice.
+ * Expects the same segment layout as used in encodeVote.
+ *
+ * @param tallyBytes - Hex string or array of decoded numbers from tally/decryption
+ * @param numChoices - Number of vote options
+ * @returns Vote array with one value per choice
+ */
+declare const decodeTally: (tallyBytes: string | number[], numChoices: number) => Vote;
+/**
+ * Generates a BFV keypair for vote encryption and decryption.
+ *
+ * @returns Object with secretKey and publicKey as Uint8Arrays
  */
-declare const generatePublicKey: () => Uint8Array;
+declare const generateBFVKeys: () => {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+
+declare const destroyBBApi: () => void;
 /**
  * Validate a vote.
  * @param vote - The vote to validate.
@@ -278,10 +290,15 @@ declare class CrispSDK {
     generateMaskVoteProof(maskProofInputs: MaskVoteProofRequest): Promise<ProofData>;
     /**
      * Generate a proof for a vote.
+     *
+     * 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.
+     *
      * @param voteProofInputs - The inputs required to generate the vote proof.
      * @returns A promise that resolves to the generated proof data.
      */
     generateVoteProof(voteProofInputs: VoteProofRequest): Promise<ProofData>;
 }
 
-export { CreditMode, CrispSDK, MERKLE_TREE_MAX_DEPTH, type MaskVoteProofInputs, type RoundDetails, type RoundDetailsResponse, SIGNATURE_MESSAGE, SIGNATURE_MESSAGE_HASH, type TokenDetails, type Vote, type VoteProofInputs, decodeTally, encodeSolidityProof, encryptVote, generateMaskVoteProof, generateMerkleProof, generateMerkleTree, generatePublicKey, generateVoteProof, getAddressFromSignature, getBalanceAt, getIsSlotEmpty, getMaxVoteValue, getPreviousCiphertext, getRoundDetails, getRoundTokenDetails, getTotalSupplyAt, getTreeData, getZeroVote, hashLeaf, validateVote, verifyProof };
+export { CreditMode, CrispSDK, MERKLE_TREE_MAX_DEPTH, type MaskVoteProofInputs, type ProofData, type RoundDetails, type RoundDetailsResponse, SIGNATURE_MESSAGE, SIGNATURE_MESSAGE_HASH, type TokenDetails, type Vote, type VoteProofInputs, decodeTally, destroyBBApi, encodeSolidityProof, encryptVote, generateBFVKeys, generateMaskVoteProof, generateMerkleProof, generateMerkleTree, generateVoteProof, getAddressFromSignature, getBalanceAt, getMaxVoteValue, getPreviousCiphertext, getRoundDetails, getRoundTokenDetails, getTotalSupplyAt, getTreeData, getZeroVote, hashLeaf, validateVote, verifyProof };