@crisp-e3/sdk 0.5.3 → 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

@@ -98,8 +98,7 @@ type MaskVoteProofInputs = {
     balance: bigint;
     slotAddress: string;
     merkleLeaves: string[] | bigint[];
-    isFirstVote: boolean;
-    previousCiphertext: Uint8Array;
+    previousCiphertext?: Uint8Array;
 };
 type MaskVoteProofRequest = {
     e3Id: number;
@@ -108,8 +107,7 @@ type MaskVoteProofRequest = {
     slotAddress: string;
     merkleLeaves: string[] | bigint[];
 };
-type VoteProofRequest = {
-    e3Id: number;
+type VoteProofInputs = {
     merkleLeaves: string[] | bigint[];
     publicKey: Uint8Array;
     balance: bigint;
@@ -117,8 +115,10 @@ type VoteProofRequest = {
     signature: `0x${string}`;
     messageHash: `0x${string}`;
     slotAddress: string;
+    previousCiphertext?: Uint8Array;
 };
-type VoteProofInputs = {
+type VoteProofRequest = {
+    e3Id: number;
     merkleLeaves: string[] | bigint[];
     publicKey: Uint8Array;
     balance: bigint;
@@ -126,8 +126,6 @@ type VoteProofInputs = {
     signature: `0x${string}`;
     messageHash: `0x${string}`;
     slotAddress: string;
-    isFirstVote: boolean;
-    previousCiphertext: Uint8Array;
 };
 
 /**
@@ -239,21 +237,23 @@ declare const verifyProof: (proof: ProofData) => Promise<boolean>;
 declare const encodeSolidityProof: (proof: ProofData) => Hex;
 
 /**
- * A class representing the Crisp SDK.
+ * 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.
+     * 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
+     * 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>;
     /**