CRISP SDK

TypeScript SDK for interacting with CRISP (Coercion-Resistant Impartial Selection Protocol) and the
CRISP server.

Installation

``bash
npm install @crisp-e3/sdk
`

Features

- Round Management: Fetch round details, token requirements, and voting parameters
- Token Operations: Query token balances and total supply at specific blocks
- Merkle Tree Utilities: Generate proofs for voter inclusion in the eligibility tree
- Vote Proof Generation: Create zero-knowledge proofs for votes and mask votes
- Proof Verification: Verify generated proofs using Noir circuits

Usage

$3

The CrispSDK class provides a convenient interface that automatically handles server communication
for fetching previous ciphertexts and checking slot status.

`typescript
import { CrispSDK } from '@crisp-e3/sdk'

const sdk = new CrispSDK(serverUrl)

// Generate a vote proof (automatically fetches previous ciphertext if needed)
const voteProof = await sdk.generateVoteProof({
e3Id: 1,
vote: { yes: 100n, no: 0n },
publicKey: publicKeyBytes,
signature: '0x...',
messageHash: '0x...',
balance: 1000n,
slotAddress: '0x...',
merkleLeaves: [...],
})

// Generate a mask vote proof (automatically fetches previous ciphertext if needed)
const maskProof = await sdk.generateMaskVoteProof({
e3Id: 1,
balance: 1000n,
slotAddress: '0x...',
publicKey: publicKeyBytes,
merkleLeaves: [...],
})
`

$3

#### Get Round Details

`typescript
import { getRoundDetails, getRoundTokenDetails } from '@crisp-e3/sdk'

const roundDetails = await getRoundDetails(serverUrl, e3Id)
const tokenDetails = await getRoundTokenDetails(serverUrl, e3Id)
`

#### Get Token Balance and Supply

`typescript
import { getBalanceAt, getTotalSupplyAt, getTreeData } from '@crisp-e3/sdk'

const balance = await getBalanceAt(voterAddress, tokenAddress, snapshotBlock, chainId)
const totalSupply = await getTotalSupplyAt(tokenAddress, snapshotBlock, chainId)
const merkleLeaves = await getTreeData(serverUrl, e3Id)
`

#### Generate Vote Proof (Low-level)

`typescript
import { generateVoteProof } from '@crisp-e3/sdk'

const proof = await generateVoteProof({
vote: { yes: 100n, no: 0n },
publicKey: publicKeyBytes,
signature: '0x...',
messageHash: '0x...',
balance: 1000n,
slotAddress: '0x...',
merkleLeaves: [...],
previousCiphertext: previousCiphertextBytes, // optional
})
`

#### Generate Mask Vote Proof (Low-level)

`typescript
import { generateMaskVoteProof } from '@crisp-e3/sdk'

const maskProof = await generateMaskVoteProof({
balance: 1000n,
slotAddress: '0x...',
publicKey: publicKeyBytes,
merkleLeaves: [...],
previousCiphertext: previousCiphertextBytes, // optional
})
`

#### Verify Proof

`typescript
import { verifyProof } from '@crisp-e3/sdk'

const isValid = await verifyProof(proof)
`

#### Decode Tally

`typescript
import { decodeTally } from '@crisp-e3/sdk'

const tally = decodeTally(tallyBytes)
// Returns: { yes: bigint, no: bigint }
`

#### Cryptographic Utilities

`typescript
import { generatePublicKey, encryptVote, encodeSolidityProof } from '@crisp-e3/sdk'

const publicKey = generatePublicKey()
const encryptedVote = encryptVote(vote, publicKey)
const encodedProof = encodeSolidityProof(proof)
`

#### Merkle Tree Utilities

`typescript
import {
generateMerkleProof,
generateMerkleTree,
hashLeaf,
getAddressFromSignature,
} from '@crisp-e3/sdk'

const leaf = hashLeaf(address, balance)
const tree = generateMerkleTree(leaves)
const proof = generateMerkleProof(balance, address, merkleLeaves)
const address = await getAddressFromSignature(signature, messageHash)
`

#### State Utilities

`typescript
import { getPreviousCiphertext, getIsSlotEmpty } from '@crisp-e3/sdk'

const previousCiphertext = await getPreviousCiphertext(serverUrl, e3Id, slotAddress)
const isEmpty = await getIsSlotEmpty(serverUrl, e3Id, slotAddress)
`

API

$3

- constructor(serverUrl: string) - Create a new SDK instance
- generateVoteProof(voteProofRequest: VoteProofRequest): Promise - Generate a vote
proof (automatically handles previous ciphertext)
- generateMaskVoteProof(maskVoteProofRequest: MaskVoteProofRequest): Promise - Generate
a mask vote proof (automatically handles previous ciphertext)

$3

- getRoundDetails(serverUrl: string, e3Id: number): Promise - Get round details
- getRoundTokenDetails(serverUrl: string, e3Id: number): Promise - Get token details
for a round
- getPreviousCiphertext(serverUrl: string, e3Id: number, address: string): Promise -
Get previous ciphertext for a slot
- getIsSlotEmpty(serverUrl: string, e3Id: number, address: string): Promise - Check if a
slot is empty

$3

- getBalanceAt(voterAddress: string, tokenAddress: string, snapshotBlock: number, chainId: number): Promise -
Get token balance at a specific block
- getTotalSupplyAt(tokenAddress: string, snapshotBlock: number, chainId: number): Promise -
Get total supply at a specific block
- getTreeData(serverUrl: string, e3Id: number): Promise - Get merkle tree leaves from
server

$3

- generateVoteProof(voteProofInputs: VoteProofInputs): Promise - Generate a vote proof
(low-level)
- generateMaskVoteProof(maskVoteProofInputs: MaskVoteProofInputs): Promise - Generate a
mask vote proof (low-level)
- verifyProof(proof: ProofData): Promise - Verify a proof locally
- decodeTally(tallyBytes: string): Vote - Decode an encoded tally
- generatePublicKey(): Uint8Array - Generate a random public key
- encryptVote(vote: Vote, publicKey: Uint8Array): Uint8Array - Encrypt a vote
- encodeSolidityProof(proof: ProofData): Hex - Encode proof for Solidity contract

$3

- generateMerkleProof(balance: bigint, address: string, leaves: bigint[] | string[]): MerkleProof -
Generate merkle proof
- generateMerkleTree(leaves: bigint[]): LeanIMT - Generate merkle tree
- hashLeaf(address: string, balance: bigint): bigint - Hash a leaf node
- getAddressFromSignature(signature: \0x${string}\, messageHash?: \0x${string}\):
Promise - Extract address from signature

$3

- MERKLE_TREE_MAX_DEPTH - Maximum depth of the merkle tree
- SIGNATURE_MESSAGE - Message used for signature verification
- MAXIMUM_VOTE_VALUE - Maximum allowed vote value
- SIGNATURE_MESSAGE_HASH - Hash of the signature message

$3

- RoundDetails - Round details type
- RoundDetailsResponse - Server response type for round details
- TokenDetails - Token details type
- Vote - Vote type with yes and no bigint fields
- MaskVoteProofInputs - Inputs for mask vote proof generation
- VoteProofInputs` - Inputs for vote proof generation