@crisp-e3/sdk 0.5.2 → 0.5.4

package/README.md

@@ -19,23 +19,60 @@ npm install @crisp-e3/sdk
 
 ## Usage
 
-### Get Round Details
+### CrispSDK Class (Recommended)
+
+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: [...],
+})
+```
+
+### Standalone Functions
+
+#### Get Round Details
 
 ```typescript
-import { getRoundDetails } from '@crisp-e3/sdk'
+import { getRoundDetails, getRoundTokenDetails } from '@crisp-e3/sdk'
 
 const roundDetails = await getRoundDetails(serverUrl, e3Id)
+const tokenDetails = await getRoundTokenDetails(serverUrl, e3Id)
 ```
 
-### Get Token Balance
+#### Get Token Balance and Supply
 
 ```typescript
-import { getBalanceAt } from '@crisp-e3/sdk'
+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
+#### Generate Vote Proof (Low-level)
 
 ```typescript
 import { generateVoteProof } from '@crisp-e3/sdk'
@@ -44,12 +81,15 @@ 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
+#### Generate Mask Vote Proof (Low-level)
 
 ```typescript
 import { generateMaskVoteProof } from '@crisp-e3/sdk'
@@ -63,7 +103,7 @@ const maskProof = await generateMaskVoteProof({
 })
 ```
 
-### Verify Proof
+#### Verify Proof
 
 ```typescript
 import { verifyProof } from '@crisp-e3/sdk'
@@ -71,9 +111,112 @@ 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
 
-- **State**: `getRoundDetails`, `getRoundTokenDetails`
-- **Token**: `getBalanceAt`, `getTotalSupplyAt`, `getTreeData`
-- **Vote**: `generateVoteProof`, `generateMaskVoteProof`, `verifyProof`, `decodeTally`
-- **Utils**: `generateMerkleProof`, `generateMerkleTree`, `hashLeaf`, `getAddressFromSignature`
+### CrispSDK Class
+
+- `constructor(serverUrl: string)` - Create a new SDK instance
+- `generateVoteProof(voteProofRequest: VoteProofRequest): Promise<ProofData>` - Generate a vote
+  proof (automatically handles previous ciphertext)
+- `generateMaskVoteProof(maskVoteProofRequest: MaskVoteProofRequest): Promise<ProofData>` - Generate
+  a mask vote proof (automatically handles previous ciphertext)
+
+### State Functions
+
+- `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
+
+### Token Functions
+
+- `getBalanceAt(voterAddress: string, tokenAddress: string, snapshotBlock: number, chainId: number): Promise<bigint>` -
+  Get token balance at a specific block
+- `getTotalSupplyAt(tokenAddress: string, snapshotBlock: number, chainId: number): Promise<bigint>` -
+  Get total supply at a specific block
+- `getTreeData(serverUrl: string, e3Id: number): Promise<bigint[]>` - Get merkle tree leaves from
+  server
+
+### Vote Functions
+
+- `generateVoteProof(voteProofInputs: VoteProofInputs): Promise<ProofData>` - Generate a vote proof
+  (low-level)
+- `generateMaskVoteProof(maskVoteProofInputs: MaskVoteProofInputs): Promise<ProofData>` - Generate a
+  mask vote proof (low-level)
+- `verifyProof(proof: ProofData): Promise<boolean>` - 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
+
+### Utility Functions
+
+- `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<string>` - Extract address from signature
+
+### Constants
+
+- `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
+
+### Types
+
+- `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

package/dist/index.d.ts

@@ -94,11 +94,18 @@ type Vote = {
     no: bigint;
 };
 type MaskVoteProofInputs = {
-    previousCiphertext?: Uint8Array;
+    publicKey: Uint8Array;
+    balance: bigint;
+    slotAddress: string;
     merkleLeaves: string[] | bigint[];
+    previousCiphertext?: Uint8Array;
+};
+type MaskVoteProofRequest = {
+    e3Id: number;
     publicKey: Uint8Array;
     balance: bigint;
     slotAddress: string;
+    merkleLeaves: string[] | bigint[];
 };
 type VoteProofInputs = {
     merkleLeaves: string[] | bigint[];
@@ -106,8 +113,19 @@ type VoteProofInputs = {
     balance: bigint;
     vote: Vote;
     signature: `0x${string}`;
+    messageHash: `0x${string}`;
+    slotAddress: string;
     previousCiphertext?: Uint8Array;
+};
+type VoteProofRequest = {
+    e3Id: number;
+    merkleLeaves: string[] | bigint[];
+    publicKey: Uint8Array;
+    balance: bigint;
+    vote: Vote;
+    signature: `0x${string}`;
     messageHash: `0x${string}`;
+    slotAddress: string;
 };
 
 /**
@@ -121,13 +139,29 @@ declare const getRoundDetails: (serverUrl: string, e3Id: number) => Promise<Roun
  * @returns The token address, balance threshold and snapshot block
  */
 declare const getRoundTokenDetails: (serverUrl: string, e3Id: number) => Promise<TokenDetails>;
+/**
+ * Get the previous ciphertext for a slot from the CRISP server
+ * @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
+ */
+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 MERKLE_TREE_MAX_DEPTH = 20;
 /**
  * This is the maximum value for a vote (Yes or No). This is 2^50 - 1
  * The minimum degree that BFV should use is 100 (to accommodate both Yes and No votes)
  */
-declare const MAXIMUM_VOTE_VALUE: bigint;
+declare const MAXIMUM_VOTE_VALUE: number;
 /**
  * Message used by users to prove ownership of their Ethereum account
  * This message is signed by the user's private key to authenticate their identity
@@ -156,18 +190,43 @@ declare const generateMerkleTree: (leaves: bigint[]) => LeanIMT;
  * @param leaves The leaves of the Merkle tree
  */
 declare const generateMerkleProof: (balance: bigint, address: string, leaves: bigint[] | string[]) => MerkleProof;
-declare const getAddressFromSignature: (signature: `0x${string}`, messageHash: `0x${string}`) => Promise<string>;
+declare const getAddressFromSignature: (signature: `0x${string}`, messageHash?: `0x${string}`) => Promise<string>;
 
 /**
  * Decode an encoded tally into its decimal representation.
- * @param tally The encoded tally to decode.
+ * @param tallyBytes The encoded tally as a hex string (bytes).
  * @returns The decoded tally as an IVote.
  */
-declare const decodeTally: (tally: string[]) => Vote;
+declare const decodeTally: (tallyBytes: string) => 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.
+ */
 declare const encryptVote: (vote: Vote, publicKey: Uint8Array) => Uint8Array;
+/**
+ * Generate a random public key.
+ * @returns The generated public key as a Uint8Array.
+ */
 declare const generatePublicKey: () => Uint8Array;
+/**
+ * Generate a vote proof for the CRISP circuit given the vote proof inputs.
+ * @param voteProofInputs - The vote proof inputs.
+ * @returns The vote proof.
+ */
 declare const generateVoteProof: (voteProofInputs: VoteProofInputs) => Promise<ProofData>;
+/**
+ * Generate a proof for a vote masking operation.
+ * @param maskVoteProofInputs The mask vote proof inputs.
+ * @returns
+ */
 declare const generateMaskVoteProof: (maskVoteProofInputs: MaskVoteProofInputs) => Promise<ProofData>;
+/**
+ * Locally verify a Noir proof.
+ * @param proof - The proof to verify.
+ * @returns True if the proof is valid, false otherwise.
+ */
 declare const verifyProof: (proof: ProofData) => Promise<boolean>;
 /**
  * Encode the proof data into a format that can be used by the CRISP program in Solidity
@@ -177,4 +236,32 @@ declare const verifyProof: (proof: ProofData) => Promise<boolean>;
  */
 declare const encodeSolidityProof: (proof: ProofData) => Hex;
 
-export { MAXIMUM_VOTE_VALUE, 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, getRoundDetails, getRoundTokenDetails, getTotalSupplyAt, getTreeData, hashLeaf, verifyProof };
+/**
+ * A class representing the CRISP SDK.
+ */
+declare class CrispSDK {
+    /**
+     * The server URL for the CRISP SDK.
+     * It's used by methods that communicate directly with the CRISP server.
+     */
+    private serverUrl;
+    /**
+     * Create a new instance.
+     * @param serverUrl
+     */
+    constructor(serverUrl: string);
+    /**
+     * Generate a proof for a vote masking.
+     * @param maskProofInputs - The inputs required to generate the mask vote proof.
+     * @returns A promise that resolves to the generated proof data.
+     */
+    generateMaskVoteProof(maskProofInputs: MaskVoteProofRequest): Promise<ProofData>;
+    /**
+     * Generate a proof for a vote.
+     * @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 { CrispSDK, MAXIMUM_VOTE_VALUE, 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, getPreviousCiphertext, getRoundDetails, getRoundTokenDetails, getTotalSupplyAt, getTreeData, hashLeaf, verifyProof };