refactor: simplify crisp sdk api

[cedoor]

Follow-up of #1109

Summary by CodeRabbit

• New Features

  • Added a CrispSDK class offering higher-level methods to simplify server interactions and vote-proof generation.

• Documentation

  • Expanded API reference with usage examples, function signatures, and sections for state, token, vote, proof, and utility operations.

• Bug Fixes

  • Simplified proof generation inputs and first-vote detection to rely on presence of prior ciphertext rather than extra flags.

• Chores

  • Package versions bumped to 0.5.4 across examples.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
crisp	Ready	Preview, Comment	Dec 22, 2025 11:23am

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
enclave-docs	Skipped		Dec 22, 2025 11:23am

[coderabbitai]

Walkthrough

Removes explicit serverUrl from two client worker SDK calls and removes isFirstVote/encryptVote defaults from the CRISP SDK. Types now make previousCiphertext optional and first-vote detection uses previousCiphertext presence. README expanded with a CrispSDK class and comprehensive API surface.

Changes

Cohort / File(s)	Summary
Client worker examples/CRISP/client/libs/crispSDKWorker.js	Removed serverUrl property from generateMaskVoteProof and generateVoteProof call arguments.
SDK core & vote flow examples/CRISP/packages/crisp-sdk/src/sdk.ts, .../src/vote.ts	Dropped encryptVote/ZERO_VOTE defaulting and removed isFirstVote input; determine first vote by absence of previousCiphertext; pass previousCiphertext only when present; adjusted circuit-input construction accordingly.
Types examples/CRISP/packages/crisp-sdk/src/types.ts	Made previousCiphertext optional on relevant inputs, removed isFirstVote from mask inputs, added VoteProofInputs and VoteProofRequest shapes, removed Signature type.
SDK README / API examples/CRISP/packages/crisp-sdk/README.md	Replaced usage section with expanded CrispSDK class docs and a full high-/low-level API surface, constants, utilities, and type signatures.
Tests examples/CRISP/packages/crisp-sdk/tests/vote.test.ts, examples/CRISP/packages/crisp-contracts/tests/crisp.contracts.test.ts	Refactored sdk instantiation into test setup; introduced mock factories for getPreviousCiphertext/isSlotEmpty responses; removed encryptVote usage and isFirstVote/previousCiphertext fields from test inputs; updated fetch mocks.
Package versions examples/CRISP/client/package.json, examples/CRISP/packages/*/package.json	Bumped package versions from 0.5.3 → 0.5.4 and updated @crisp-e3/sdk dependency in client to 0.5.4.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Pay attention to vote flow changes in vote.ts (first-vote detection, input construction).
• Verify all call sites handle optional previousCiphertext (types and tests).
• Confirm README signatures match actual exported API and that client worker call sites align with SDK expectations.

Possibly related PRs

• feat: get previous ciphertext from server [skip-line-limit] #1109 — modifies the same worker call site (crispSDKWorker.js) around proof-generation parameters.
• chore: set target web/nodejs for crisp zk-inputs #1006 — touches vote.ts initialization and proof generation logic; overlaps on vote-proof changes.
• feat: mask vote utilities #924 — overlapping changes to CRISP SDK vote and types handling (previousCiphertext/isFirstVote adjustments).

Suggested reviewers

• ctrlc03

Poem

🐰 In burrows of code I nibble and play,
A flag folded up, a ciphertext says "stay".
No more default whispers to guess who goes first,
The absence now answers — quiet, not terse.
Hooray for small hops and proofs unrehearsed! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately reflects the main refactoring work: removing isFirstVote flags and making previousCiphertext optional, which simplifies the SDK API surface across multiple files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor/crisp-sdk-1

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b8972e0 and 006c545.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (4)

• examples/CRISP/client/package.json
• examples/CRISP/packages/crisp-contracts/package.json
• examples/CRISP/packages/crisp-sdk/package.json
• examples/CRISP/packages/crisp-zk-inputs/package.json

✅ Files skipped from review due to trivial changes (3)

• examples/CRISP/packages/crisp-zk-inputs/package.json
• examples/CRISP/packages/crisp-sdk/package.json
• examples/CRISP/packages/crisp-contracts/package.json

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: ctrlc03
Repo: gnosisguild/enclave PR: 963
File: examples/CRISP/client/package.json:25-25
Timestamp: 2025-11-05T14:12:57.814Z
Learning: In the Enclave/CRISP codebase, `enclave-e3/sdk` and `crisp-e3/sdk` are different packages: `enclave-e3/sdk` is the general Enclave SDK, while `crisp-e3/sdk` is the CRISP-specific SDK. The CRISP client (`examples/CRISP/client`) intentionally depends on `enclave-e3/sdk`, not `crisp-e3/sdk`.

Learnt from: ctrlc03
Repo: gnosisguild/enclave PR: 1109
File: examples/CRISP/server/src/server/routes/state.rs:33-37
Timestamp: 2025-12-19T11:35:43.204Z
Learning: In the CRISP voting system (examples/CRISP), ciphertext data and slot states are public and stored on-chain in the CRISPProgram smart contract. The server endpoints `/previous-ciphertext` and `/is-slot-empty` expose public blockchain data that can already be accessed by anyone through the contract's external view functions (getSlotIndex, isSlotEmptyByAddress) or by reading contract state directly. Authentication is not needed for these endpoints since they only expose data that is already publicly available on the blockchain.

📚 Learning: 2025-11-05T14:12:57.814Z

Learnt from: ctrlc03
Repo: gnosisguild/enclave PR: 963
File: examples/CRISP/client/package.json:25-25
Timestamp: 2025-11-05T14:12:57.814Z
Learning: In the Enclave/CRISP codebase, `enclave-e3/sdk` and `crisp-e3/sdk` are different packages: `enclave-e3/sdk` is the general Enclave SDK, while `crisp-e3/sdk` is the CRISP-specific SDK. The CRISP client (`examples/CRISP/client`) intentionally depends on `enclave-e3/sdk`, not `crisp-e3/sdk`.

Applied to files:

• examples/CRISP/client/package.json

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)

• GitHub Check: build_enclave_cli
• GitHub Check: build_sdk
• GitHub Check: build_e3_support_dev
• GitHub Check: build_crisp_sdk
• GitHub Check: rust_unit
• GitHub Check: integration_prebuild
• GitHub Check: rust_integration
• GitHub Check: test_net
• GitHub Check: build_ciphernode_image

🔇 Additional comments (1)

examples/CRISP/client/package.json (1)

21-21: Verify package availability and client code compatibility.

The version bump from 0.5.3 to 0.5.4 aligns with the PR objectives. However, ensure that:

1. The new version is published and available on npm
2. The client code is compatible with the SDK API changes mentioned in the summary (removed serverUrl parameter, optional previousCiphertext, etc.)

The client correctly depends on @crisp-e3/sdk (the CRISP-specific SDK) and imports it in examples/CRISP/client/libs/crispSDKWorker.js for proof generation. The version 0.5.4 is available in the monorepo workspace. Verify that the API changes do not break the generateVoteProof and generateMaskVoteProof method calls, and that encodeSolidityProof continues to work as expected.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ctrlc03]

LGTM