@crisp-e3/sdk 0.3.0-test → 0.4.0

package/README.md

@@ -1,18 +1,79 @@
 # CRISP SDK
 
-This package is CRISP's TypeScript SDK for interacting with CRISP and the CRISP server.
+TypeScript SDK for interacting with CRISP (Cryptographically Secure and Private voting protocol) and
+the CRISP server.
 
 ## Installation
 
 ```bash
-npm install @enclave/crisp-sdk
+npm install @crisp-e3/sdk
 ```
 
-## Release
+## Features
 
-The SDK is published on npmjs and does not follow the same versioning as the main Enclave packages.
-To release a new version, run the following command:
+- **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
 
-```bash
-pnpm release
+## Usage
+
+### Get Round Details
+
+```typescript
+import { getRoundDetails } from '@crisp-e3/sdk'
+
+const roundDetails = await getRoundDetails(serverUrl, e3Id)
+```
+
+### Get Token Balance
+
+```typescript
+import { getBalanceAt } from '@crisp-e3/sdk'
+
+const balance = await getBalanceAt(voterAddress, tokenAddress, snapshotBlock, chainId)
+```
+
+### Generate Vote Proof
+
+```typescript
+import { generateVoteProof } from '@crisp-e3/sdk'
+
+const proof = await generateVoteProof({
+  vote: { yes: 100n, no: 0n },
+  publicKey: publicKeyBytes,
+  signature: '0x...',
+  balance: 1000n,
+  merkleLeaves: [...],
+})
+```
+
+### Generate Mask Vote Proof
+
+```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)
+```
+
+## API
+
+- **State**: `getRoundDetails`, `getRoundTokenDetails`
+- **Token**: `getBalanceAt`, `getTotalSupplyAt`, `getTreeData`
+- **Vote**: `generateVoteProof`, `generateMaskVoteProof`, `verifyProof`, `decodeTally`
+- **Utils**: `generateMerkleProof`, `generateMerkleTree`, `hashLeaf`, `getAddressFromSignature`

package/dist/index.d.ts

@@ -27,9 +27,9 @@ declare const getBalanceAt: (voterAddress: string, tokenAddress: string, snapsho
 declare const getTotalSupplyAt: (tokenAddress: string, snapshotBlock: number, chainId: number) => Promise<bigint>;
 
 /**
- * Interface representing the details of a specific round returned by the CRISP server
+ * Type representing the details of a specific round returned by the CRISP server
  */
-interface IRoundDetailsResponse {
+type RoundDetailsResponse = {
     id: string;
     chain_id: string;
     enclave_address: string;
@@ -43,11 +43,11 @@ interface IRoundDetailsResponse {
     emojis: [string, string];
     token_address: string;
     balance_threshold: string;
-}
+};
 /**
- * Interface representing the details of a specific round in a more convenient format
+ * Type representing the details of a specific round in a more convenient format
  */
-interface IRoundDetails {
+type RoundDetails = {
     e3Id: bigint;
     chainId: bigint;
     enclaveAddress: string;
@@ -61,39 +61,29 @@ interface IRoundDetails {
     emojis: [string, string];
     tokenAddress: string;
     balanceThreshold: bigint;
-}
+};
 /**
- * Interface representing the token details required for participation in a round
+ * Type representing the token details required for participation in a round
  */
-interface ITokenDetails {
+type TokenDetails = {
     tokenAddress: string;
     threshold: bigint;
     snapshotBlock: bigint;
-}
+};
 /**
- * Interface representing a Merkle proof
+ * Type representing a Merkle proof
  */
-interface IMerkleProof {
+type MerkleProof = {
     leaf: bigint;
     index: number;
     proof: LeanIMTMerkleProof<bigint>;
     length: number;
     indices: number[];
-}
-/**
- * Enum representing the voting modes
- */
-declare enum VotingMode {
-    /**
-     *  Governance voting requires to spend all credits on one option
-        they cannot be split
-     */
-    GOVERNANCE = "GOVERNANCE"
-}
+};
 /**
- * Interface representing a vote with power for 'yes' and 'no'
+ * Type representing a vote with power for 'yes' and 'no'
  */
-interface IVote {
+type Vote = {
     /**
      * The voting power for 'yes' votes
      */
@@ -102,144 +92,45 @@ interface IVote {
      * The voting power for 'no' votes
      */
     no: bigint;
-}
-/**
- * Interface representing a vector with coefficients
- */
-interface Polynomial {
-    coefficients: string[];
-}
-/**
- * Interface representing cryptographic parameters
- */
-interface GrecoCryptographicParams {
-    q_mod_t: string;
-    qis: string[];
-    k0is: string[];
-}
-/**
- * Interface representing Greco bounds
- */
-interface GrecoBoundParams {
-    e_bound: string;
-    u_bound: string;
-    k1_low_bound: string;
-    k1_up_bound: string;
-    p1_bounds: string[];
-    p2_bounds: string[];
-    pk_bounds: string[];
-    r1_low_bounds: string[];
-    r1_up_bounds: string[];
-    r2_bounds: string[];
-}
-/**
- * Interface representing Greco parameters
- */
-interface GrecoParams {
-    crypto: GrecoCryptographicParams;
-    bounds: GrecoBoundParams;
-}
-/**
- * The inputs required for the CRISP circuit
- */
-interface CRISPCircuitInputs {
-    prev_ct0is: Polynomial[];
-    prev_ct1is: Polynomial[];
-    sum_ct0is: Polynomial[];
-    sum_ct1is: Polynomial[];
-    sum_r0is: Polynomial[];
-    sum_r1is: Polynomial[];
-    params: GrecoParams;
-    ct0is: Polynomial[];
-    ct1is: Polynomial[];
-    pk0is: Polynomial[];
-    pk1is: Polynomial[];
-    r1is: Polynomial[];
-    r2is: Polynomial[];
-    p1is: Polynomial[];
-    p2is: Polynomial[];
-    u: Polynomial;
-    e0: Polynomial;
-    e1: Polynomial;
-    e0is: Polynomial[];
-    k1: Polynomial;
-    public_key_x: string[];
-    public_key_y: string[];
-    signature: string[];
-    hashed_message: string[];
-    merkle_root: string;
-    merkle_proof_length: string;
-    merkle_proof_indices: string[];
-    merkle_proof_siblings: string[];
-    slot_address: string;
-    balance: string;
-    is_first_vote: boolean;
-}
-/**
- * Interface representing the inputs for Noir signature verification
- */
-interface NoirSignatureInputs {
-    /**
-     * X coordinate of the public key
-     */
-    pub_key_x: Uint8Array;
-    /**
-     * Y coordinate of the public key
-     */
-    pub_key_y: Uint8Array;
-    /**
-     * The signature to verify
-     */
-    signature: Uint8Array;
-    /**
-     * The hashed message that was signed
-     */
-    hashed_message: Uint8Array;
-}
-/**
- * Parameters for encryptVoteAndGenerateCRISPInputs function
- */
-interface EncryptVoteAndGenerateCRISPInputsParams {
-    encodedVote: string[];
+};
+type MaskVoteProofInputs = {
+    previousCiphertext?: Uint8Array;
+    merkleLeaves: string[] | bigint[];
     publicKey: Uint8Array;
-    previousCiphertext: Uint8Array;
-    signature: `0x${string}`;
-    message: string;
-    merkleData: IMerkleProof;
     balance: bigint;
     slotAddress: string;
-    isFirstVote: boolean;
-}
+};
+type VoteProofInputs = {
+    merkleLeaves: string[] | bigint[];
+    publicKey: Uint8Array;
+    balance: bigint;
+    vote: Vote;
+    signature: `0x${string}`;
+};
 
 /**
  * Get the details of a specific round
  */
-declare const getRoundDetails: (serverUrl: string, e3Id: number) => Promise<IRoundDetails>;
+declare const getRoundDetails: (serverUrl: string, e3Id: number) => Promise<RoundDetails>;
 /**
  * Get the token address, balance threshold and snapshot block for a specific round
  * @param serverUrl - The base URL of the CRISP server
  * @param e3Id - The e3Id of the round
  * @returns The token address, balance threshold and snapshot block
  */
-declare const getRoundTokenDetails: (serverUrl: string, e3Id: number) => Promise<ITokenDetails>;
+declare const getRoundTokenDetails: (serverUrl: string, e3Id: number) => Promise<TokenDetails>;
 
-declare const CRISP_SERVER_TOKEN_TREE_ENDPOINT = "state/token-holders";
-declare const CRISP_SERVER_STATE_LITE_ENDPOINT = "state/lite";
 declare const MERKLE_TREE_MAX_DEPTH = 20;
-/**
- * Half the minimum degree needed to support the maxium vote value
- * If you change MAXIMUM_VOTE_VALUE, make sure to update this value too.
- */
-declare const HALF_LARGEST_MINIMUM_DEGREE = 28;
 /**
  * This is the maximum value for a vote (Yes or No). This is 2^28 - 1
  * The minimum degree that BFV should use is 56 (to accommodate both Yes and No votes)
  */
 declare const MAXIMUM_VOTE_VALUE: bigint;
 /**
- * Mock message for masking signature
+ * 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
  */
-declare const MESSAGE = "Vote for round 0";
+declare const SIGNATURE_MESSAGE = "CRISP: Sign this message to prove ownership of your Ethereum account";
 
 /**
  * Hash a leaf node for the Merkle tree
@@ -247,7 +138,7 @@ declare const MESSAGE = "Vote for round 0";
  * @param balance The voter's balance
  * @returns The hashed leaf as a bigint
  */
-declare const hashLeaf: (address: string, balance: string) => bigint;
+declare const hashLeaf: (address: string, balance: bigint) => bigint;
 /**
  * Generate a new LeanIMT with the leaves provided
  * @param leaves The leaves of the Merkle tree
@@ -256,91 +147,23 @@ declare const hashLeaf: (address: string, balance: string) => bigint;
 declare const generateMerkleTree: (leaves: bigint[]) => LeanIMT;
 /**
  * Generate a Merkle proof for a given address to prove inclusion in the voters' list
- * @param threshold The minimum balance required to be eligible
  * @param balance The voter's balance
  * @param address The voter's address
  * @param leaves The leaves of the Merkle tree
  */
-declare const generateMerkleProof: (threshold: bigint, balance: bigint, address: string, leaves: bigint[]) => IMerkleProof;
-/**
- * Convert a number to its binary representation
- * @param number The number to convert to binary
- * @returns The binary representation of the number as a string
- */
-declare const toBinary: (number: bigint) => string;
+declare const generateMerkleProof: (balance: bigint, address: string, leaves: bigint[] | string[]) => MerkleProof;
+declare const getAddressFromSignature: (signature: `0x${string}`) => Promise<string>;
 
 /**
- * This utility function calculates the first valid index for vote options
- * based on the total voting power and degree.
- * @dev This is needed to calculate the decoded plaintext
- * @dev Also, we will need to check in the circuit that anything within these indices is
- * either 0 or 1.
- * @param totalVotingPower The maximum vote amount (if a single voter had all of the power)
- * @param degree The degree of the polynomial
- */
-declare const calculateValidIndicesForPlaintext: (totalVotingPower: bigint, degree: number) => {
-    yesIndex: number;
-    noIndex: number;
-};
-/**
- * Encode a vote based on the voting mode
- * @param vote The vote to encode
- * @param votingMode The voting mode to use for encoding
- * @param votingPower The voting power of the voter
- * @param bfvParams The BFV parameters to use for encoding
- * @returns The encoded vote as a string
- */
-declare const encodeVote: (vote: IVote, votingMode: VotingMode, votingPower: bigint) => string[];
-/**
- * Given an encoded tally, decode it into its decimal representation
- * @param tally The encoded tally to decode
- * @param votingMode The voting mode
- */
-declare const decodeTally: (tally: string[], votingMode: VotingMode) => IVote;
-/**
- * Validate whether a vote is valid for a given voting mode
- * @param votingMode The voting mode to validate against
- * @param vote The vote to validate
- * @param votingPower The voting power of the voter
- */
-declare const validateVote: (votingMode: VotingMode, vote: IVote, votingPower: bigint) => void;
-declare const encryptVote: (encodedVote: string[], publicKey: Uint8Array) => Promise<Uint8Array>;
-declare const generatePublicKey: () => Promise<Uint8Array>;
-/**
- * This is a wrapper around enclave-e3/sdk encryption functions as CRISP circuit will require some more
- * input values which generic Greco do not need.
- * @param encodedVote The encoded vote as string array
- * @param publicKey The public key to use for encryption
- * @param previousCiphertext The previous ciphertext to use for addition operation
- * @param bfvParams The BFV parameters to use for encryption
- * @param merkleData The merkle proof data
- * @param message The message that was signed
- * @param signature The signature of the message
- * @param balance The voter's balance
- * @param slotAddress The voter's slot address
- * @param isFirstVote Whether this is the first vote for this slot
- * @returns The CRISP circuit inputs
- */
-declare const encryptVoteAndGenerateCRISPInputs: ({ encodedVote, publicKey, previousCiphertext, merkleData, message, signature, balance, slotAddress, isFirstVote, }: EncryptVoteAndGenerateCRISPInputsParams) => Promise<CRISPCircuitInputs>;
-/**
- * A function to generate the data required to mask a vote
- * @param voter The voter's address
- * @param publicKey The voter's public key
- * @param previousCiphertext The previous ciphertext
- * @param merkleRoot The merkle root of the census tree
- * @param slotAddress The voter's slot address
- * @param isFirstVote Whether this is the first vote for this slot
- * @returns The CRISP circuit inputs for a mask vote
+ * Decode an encoded tally into its decimal representation.
+ * @param tally The encoded tally to decode.
+ * @returns The decoded tally as an IVote.
  */
-declare const generateMaskVote: (publicKey: Uint8Array, previousCiphertext: Uint8Array, merkleRoot: bigint, slotAddress: string, isFirstVote: boolean) => Promise<CRISPCircuitInputs>;
-declare const generateProof: (crispInputs: CRISPCircuitInputs) => Promise<ProofData>;
-declare const generateProofWithReturnValue: (crispInputs: CRISPCircuitInputs) => Promise<{
-    returnValue: unknown;
-    proof: ProofData;
-}>;
-declare const getCircuitOutputValue: (crispInputs: CRISPCircuitInputs) => Promise<{
-    returnValue: unknown;
-}>;
+declare const decodeTally: (tally: string[]) => Vote;
+declare const encryptVote: (vote: Vote, publicKey: Uint8Array) => Uint8Array;
+declare const generatePublicKey: () => Uint8Array;
+declare const generateVoteProof: (voteProofInputs: VoteProofInputs) => Promise<ProofData>;
+declare const generateMaskVoteProof: (maskVoteProofInputs: MaskVoteProofInputs) => Promise<ProofData>;
 declare const verifyProof: (proof: ProofData) => Promise<boolean>;
 /**
  * Encode the proof data into a format that can be used by the CRISP program in Solidity
@@ -350,12 +173,4 @@ declare const verifyProof: (proof: ProofData) => Promise<boolean>;
  */
 declare const encodeSolidityProof: (proof: ProofData) => Hex;
 
-/**
- * Given a message and its signed version, extract the signature components
- * @param message The original message
- * @param signedMessage The signed message (signature)
- * @returns The extracted signature components
- */
-declare const extractSignature: (message: string, signedMessage: `0x${string}`) => Promise<NoirSignatureInputs>;
-
-export { type CRISPCircuitInputs, CRISP_SERVER_STATE_LITE_ENDPOINT, CRISP_SERVER_TOKEN_TREE_ENDPOINT, HALF_LARGEST_MINIMUM_DEGREE, type IMerkleProof, type IRoundDetails, type IRoundDetailsResponse, type ITokenDetails, type IVote, MAXIMUM_VOTE_VALUE, MERKLE_TREE_MAX_DEPTH, MESSAGE, type NoirSignatureInputs, VotingMode, calculateValidIndicesForPlaintext, decodeTally, encodeSolidityProof, encodeVote, encryptVote, encryptVoteAndGenerateCRISPInputs, extractSignature, generateMaskVote, generateMerkleProof, generateMerkleTree, generateProof, generateProofWithReturnValue, generatePublicKey, getBalanceAt, getCircuitOutputValue, getRoundDetails, getRoundTokenDetails, getTotalSupplyAt, getTreeData, hashLeaf, toBinary, validateVote, verifyProof };
+export { MAXIMUM_VOTE_VALUE, MERKLE_TREE_MAX_DEPTH, type MaskVoteProofInputs, type RoundDetails, type RoundDetailsResponse, SIGNATURE_MESSAGE, type TokenDetails, type Vote, type VoteProofInputs, decodeTally, encodeSolidityProof, encryptVote, generateMaskVoteProof, generateMerkleProof, generateMerkleTree, generatePublicKey, generateVoteProof, getAddressFromSignature, getBalanceAt, getRoundDetails, getRoundTokenDetails, getTotalSupplyAt, getTreeData, hashLeaf, verifyProof };