@crisp-e3/sdk 0.17.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,5 +1,7 @@
+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
@@ -94,6 +96,14 @@ 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;
 };
 /**
  * Which circuit a ballot is built for.
@@ -103,14 +113,34 @@ type ProofData = {
  * 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 PrepareBallotInputsBase = {
-    previousCiphertext?: Uint8Array;
     publicKey: Uint8Array;
     slotAddress: string;
     isMaskVote: boolean;
     numOptions: number;
     vote: Vote;
-};
+} & SlotHeadInputs;
 /**
  * Everything needed to encrypt a ballot, before the voter has signed anything.
  */
@@ -130,8 +160,21 @@ type PrepareBallotInputs = (PrepareBallotInputsBase & {
  */
 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;
 };
 /**
@@ -144,11 +187,23 @@ type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K>
 /**
  * A {@link PrepareBallotInputs} plus the round it belongs to.
  *
- * The SDK resolves `previousCiphertext` from the server, so callers do not pass it.
+ * The SDK resolves the slot head from the server, so callers pass neither part of it.
  */
 type PrepareBallotRequest = {
     e3Id: bigint;
-} & DistributiveOmit<PrepareBallotInputs, 'previousCiphertext'>;
+} & 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`)
  */
@@ -277,6 +332,22 @@ declare const getRoundTokenDetails: (serverUrl: string, e3Id: bigint) => Promise
  * @returns The on chain round data
  */
 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).
@@ -284,9 +355,10 @@ declare const getOnChainRoundData: (programAddress: string, e3Id: bigint, 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: bigint, 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.
@@ -561,7 +633,7 @@ declare const verifyProof: (proof: ProofData, censusMode?: CensusVariant) => Pro
  * @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.
@@ -700,9 +772,9 @@ declare class CrispSDK {
      * 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: bigint, address: string): Promise<Uint8Array | undefined>;
+    getPreviousCiphertext(e3Id: bigint, address: string): Promise<SlotHead | undefined>;
 }
 
-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 };
+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 };