@crisp-e3/zk-inputs 0.17.0 → 0.18.0

package/README.md

@@ -7,17 +7,25 @@ witness data needed for Noir-based vote-validity proofs without duplicating the
 ## What it generates
 
 The WASM module wraps a `ZKInputsGenerator` class that performs BFV encryption and produces the
-witness data needed for CRISP's Noir circuits. Two main proof types are supported:
+witness data needed for CRISP's Noir circuits.
 
-- **Vote proof** (`generateInputs`) — encrypts a vote under the committee's threshold BFV public key
-  and produces a witness proving the vote is correctly encrypted and that the voter is eligible
-  (e.g. holds the required token balance, verified via a Merkle membership proof).
+`generateInputs` is the only entry point, and it covers all three operations: a first vote, a
+re-vote, and a masker contribution under the
+[vote masking](https://blog.theinterfold.com/vote-masking-receipt-freeness-secret-ballots/) scheme
+that provides receipt-freeness.
 
-- **Vote update / mask proof** (`generateInputsForUpdate`) — same structure, but used for revotes or
-  masker contributions under the
-  [vote masking](https://blog.theinterfold.com/vote-masking-receipt-freeness-secret-ballots/) scheme
-  that provides receipt-freeness. Unlike the first-vote path, this preserves the real
-  `prev_ct_commitment` (rather than zeroing it) to chain updates together.
+```typescript
+generateInputs(previousCiphertext, publicKey, vote, keepPrevious)
+```
+
+- `previousCiphertext` is the ciphertext currently in the slot, or `undefined` when it is empty.
+- `keepPrevious` is set only for a mask over an occupied slot. It makes the ballot add to that
+  ciphertext; everything else replaces it.
+
+One function rather than one per operation, deliberately: the encryption, the witness, and the
+published ciphertext have the same shape in every case, so nothing about a submission says which
+operation it was. Splitting the paths would make the three tellable apart, which is the attack
+masking exists to prevent.
 
 The generator also exposes `encryptVote` / `decryptVote` for standalone BFV operations and
 `generateKeys` for key generation.
@@ -38,17 +46,23 @@ The `init` subpackage handles both environments transparently.
 
 ```ts
 // Bad — the raw default loader doesn't work in Node.js contexts
-import init, { generateVoteInputs } from '@crisp-e3/zk-inputs'
+import init, { ZKInputsGenerator } from '@crisp-e3/zk-inputs'
 ```
 
 ### ✅ Use the universal subpackage loader
 
 ```ts
 import init from '@crisp-e3/zk-inputs/init'
-import { generateVoteInputs } from '@crisp-e3/zk-inputs'
+import { ZKInputsGenerator } from '@crisp-e3/zk-inputs'
 
 await init()
-const inputs = generateVoteInputs(/* ... */)
+const generator = ZKInputsGenerator.withDefaults()
+const { encryptedVote, inputs } = generator.generateInputs(
+  previousCiphertext,
+  publicKey,
+  vote,
+  keepPrevious,
+)
 ```
 
 Call `init()` once before using any other imports from `@crisp-e3/zk-inputs`. In browser

package/dist/index.d.ts

@@ -7,6 +7,14 @@
 export class ZKInputsGenerator {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Computes the SAFE commitment of serialized ciphertext bytes.
+     *
+     * The witness already carries this value for the ciphertext a ballot publishes. Kept for
+     * callers that hold bytes they did not generate, such as a slot ciphertext read back from the
+     * server.
+     */
+    computeCtCommitment(ciphertext: Uint8Array): Uint8Array;
     /**
      * Decrypt a vote from JavaScript.
      */
@@ -16,13 +24,20 @@ export class ZKInputsGenerator {
      */
     encryptVote(public_key: Uint8Array, vote: BigInt64Array): Uint8Array;
     /**
-     * Generate CRISP ZK inputs from JavaScript.
-     */
-    generateInputs(prev_ciphertext: Uint8Array, public_key: Uint8Array, vote: BigInt64Array): any;
-    /**
-     * Generate CRISP ZK inputs for a vote update (either from voter or as a masker) from JavaScript.
+     * Generate the CRISP ZK inputs for one ballot from JavaScript.
+     *
+     * One entry point for a first vote, a re-vote, and a mask. Pass the ciphertext currently in
+     * the slot, or `undefined` when the slot is empty, and set `keepPrevious` only for a mask over
+     * an occupied slot. Everything else is identical between the three, which is what keeps them
+     * indistinguishable once published.
+     *
+     * # Arguments
+     * - `previous_ciphertext`: The ciphertext in the slot, or `undefined` when it is empty
+     * - `public_key`: Public key bytes for encryption
+     * - `vote`: Vote value as a vector of coefficients
+     * - `keep_previous`: Whether the ballot adds to the slot rather than replacing it
      */
-    generateInputsForUpdate(prev_ciphertext: Uint8Array, public_key: Uint8Array, vote: BigInt64Array): any;
+    generateInputs(previous_ciphertext: Uint8Array | null | undefined, public_key: Uint8Array, vote: BigInt64Array, keep_previous: boolean): any;
     /**
      * Generate a public/secret key pair from JavaScript.
      */
@@ -55,10 +70,10 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_zkinputsgenerator_free: (a: number, b: number) => void;
+    readonly zkinputsgenerator_computeCtCommitment: (a: number, b: number, c: number) => [number, number, number, number];
     readonly zkinputsgenerator_decryptVote: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly zkinputsgenerator_encryptVote: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
-    readonly zkinputsgenerator_generateInputs: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
-    readonly zkinputsgenerator_generateInputsForUpdate: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
+    readonly zkinputsgenerator_generateInputs: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number];
     readonly zkinputsgenerator_generateKeys: (a: number) => [number, number, number];
     readonly zkinputsgenerator_getBFVParams: (a: number) => [number, number, number];
     readonly zkinputsgenerator_new: (a: number, b: bigint, c: number, d: number) => [number, number, number];

package/dist/index.js

@@ -20,6 +20,26 @@ export class ZKInputsGenerator {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_zkinputsgenerator_free(ptr, 0);
     }
+    /**
+     * Computes the SAFE commitment of serialized ciphertext bytes.
+     *
+     * The witness already carries this value for the ciphertext a ballot publishes. Kept for
+     * callers that hold bytes they did not generate, such as a slot ciphertext read back from the
+     * server.
+     * @param {Uint8Array} ciphertext
+     * @returns {Uint8Array}
+     */
+    computeCtCommitment(ciphertext) {
+        const ptr0 = passArray8ToWasm0(ciphertext, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.zkinputsgenerator_computeCtCommitment(this.__wbg_ptr, ptr0, len0);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v2;
+    }
     /**
      * Decrypt a vote from JavaScript.
      * @param {Uint8Array} secret_key
@@ -59,40 +79,32 @@ export class ZKInputsGenerator {
         return v3;
     }
     /**
-     * Generate CRISP ZK inputs from JavaScript.
-     * @param {Uint8Array} prev_ciphertext
-     * @param {Uint8Array} public_key
-     * @param {BigInt64Array} vote
-     * @returns {any}
-     */
-    generateInputs(prev_ciphertext, public_key, vote) {
-        const ptr0 = passArray8ToWasm0(prev_ciphertext, wasm.__wbindgen_malloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ptr1 = passArray8ToWasm0(public_key, wasm.__wbindgen_malloc);
-        const len1 = WASM_VECTOR_LEN;
-        const ptr2 = passArray64ToWasm0(vote, wasm.__wbindgen_malloc);
-        const len2 = WASM_VECTOR_LEN;
-        const ret = wasm.zkinputsgenerator_generateInputs(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
-        if (ret[2]) {
-            throw takeFromExternrefTable0(ret[1]);
-        }
-        return takeFromExternrefTable0(ret[0]);
-    }
-    /**
-     * Generate CRISP ZK inputs for a vote update (either from voter or as a masker) from JavaScript.
-     * @param {Uint8Array} prev_ciphertext
+     * Generate the CRISP ZK inputs for one ballot from JavaScript.
+     *
+     * One entry point for a first vote, a re-vote, and a mask. Pass the ciphertext currently in
+     * the slot, or `undefined` when the slot is empty, and set `keepPrevious` only for a mask over
+     * an occupied slot. Everything else is identical between the three, which is what keeps them
+     * indistinguishable once published.
+     *
+     * # Arguments
+     * - `previous_ciphertext`: The ciphertext in the slot, or `undefined` when it is empty
+     * - `public_key`: Public key bytes for encryption
+     * - `vote`: Vote value as a vector of coefficients
+     * - `keep_previous`: Whether the ballot adds to the slot rather than replacing it
+     * @param {Uint8Array | null | undefined} previous_ciphertext
      * @param {Uint8Array} public_key
      * @param {BigInt64Array} vote
+     * @param {boolean} keep_previous
      * @returns {any}
      */
-    generateInputsForUpdate(prev_ciphertext, public_key, vote) {
-        const ptr0 = passArray8ToWasm0(prev_ciphertext, wasm.__wbindgen_malloc);
-        const len0 = WASM_VECTOR_LEN;
+    generateInputs(previous_ciphertext, public_key, vote, keep_previous) {
+        var ptr0 = isLikeNone(previous_ciphertext) ? 0 : passArray8ToWasm0(previous_ciphertext, wasm.__wbindgen_malloc);
+        var len0 = WASM_VECTOR_LEN;
         const ptr1 = passArray8ToWasm0(public_key, wasm.__wbindgen_malloc);
         const len1 = WASM_VECTOR_LEN;
         const ptr2 = passArray64ToWasm0(vote, wasm.__wbindgen_malloc);
         const len2 = WASM_VECTOR_LEN;
-        const ret = wasm.zkinputsgenerator_generateInputsForUpdate(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
+        const ret = wasm.zkinputsgenerator_generateInputs(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2, keep_previous);
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
@@ -291,6 +303,10 @@ function handleError(f, args) {
     }
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 function passArray64ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 8, 8) >>> 0;
     getBigUint64ArrayMemory0().set(arg, ptr / 8);