@crisp-e3/sdk 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -25,26 +25,9 @@ declare const getBalanceAt: (voterAddress: string, tokenAddress: string, snapsho
  */
 declare const getTotalSupplyAt: (tokenAddress: string, snapshotBlock: number, chainId: number) => Promise<bigint>;
 
-/**
- * Type representing the details of a specific round returned by the CRISP server
- */
-type RoundDetailsResponse = {
-    id: string;
-    chain_id: string;
-    interfold_address: string;
-    status: string;
-    vote_count: string;
-    start_time: string;
-    duration: string;
-    expiration: string;
-    start_block: string;
-    committee_public_key: string[];
-    emojis: [string, string];
-    token_address: string;
-    balance_threshold: string;
-};
 /**
  * Type representing the details of a specific round in a more convenient format
+ * (camelCase view of the server's `state/lite` response)
  */
 type RoundDetails = {
     e3Id: bigint;
@@ -53,13 +36,27 @@ type RoundDetails = {
     status: string;
     voteCount: bigint;
     startTime: bigint;
-    duration: bigint;
-    expiration: bigint;
+    endTime: bigint;
     startBlock: bigint;
-    committeePublicKey: string[];
+    committeePublicKey: Uint8Array;
     emojis: [string, string];
     tokenAddress: string;
     balanceThreshold: bigint;
+    numOptions: bigint;
+    requester: string;
+    creditMode: CreditMode;
+    credits?: bigint;
+};
+/**
+ * Type representing the round data stored in the CRISPProgram contract
+ */
+type OnChainRoundData = {
+    merkleRoot: bigint;
+    paramsHash: `0x${string}`;
+    numOptions: bigint;
+    creditMode: CreditMode;
+    inputRoot: bigint;
+    numberOfVotes: bigint;
 };
 /**
  * Type representing the token details required for participation in a round
@@ -124,6 +121,96 @@ type VoteProofRequest = {
     messageHash: `0x${string}`;
     slotAddress: string;
 };
+/**
+ * Type representing the current round returned by the CRISP server (`rounds/current`)
+ */
+type CurrentRoundResponse = {
+    id: number;
+};
+/**
+ * Type representing the lite state of a round returned by the CRISP server (`state/lite`)
+ */
+type E3StateLiteResponse = {
+    id: number;
+    chain_id: number;
+    interfold_address: string;
+    status: string;
+    vote_count: number;
+    start_time: number;
+    end_time: number;
+    start_block: number;
+    committee_public_key: number[];
+    emojis: [string, string];
+    token_address: string;
+    balance_threshold: string;
+    num_options: string;
+    requester: string;
+    credit_mode: CreditMode;
+    credits: string | null;
+};
+/**
+ * Type representing a generic message response from the CRISP server
+ */
+type JsonResponse = {
+    response: string;
+};
+/**
+ * Type representing a request to start a new E3 round (`rounds/request`)
+ */
+type NewRoundRequest = {
+    cronApiKey: string;
+    tokenAddress: string;
+    balanceThreshold: string;
+};
+/**
+ * Type representing a request to broadcast an encrypted vote (`voting/broadcast`)
+ */
+type BroadcastVoteRequest = {
+    e3Id: number;
+    encodedProof: string;
+    address: string;
+};
+/**
+ * The status of a vote broadcast returned by the CRISP server
+ */
+type VoteResponseStatus = 'success' | 'user_already_voted' | 'failed_broadcast';
+/**
+ * Type representing the response to a vote broadcast (`voting/broadcast`)
+ */
+type BroadcastVoteResponse = {
+    status: VoteResponseStatus;
+    tx_hash: string | null;
+    message: string | null;
+    is_vote_update?: boolean;
+};
+/**
+ * Type representing the vote status of an address in a round (`voting/status`)
+ */
+type VoteStatusResponse = {
+    round_id: number;
+    address: string;
+    has_voted: boolean;
+    round_status: string | null;
+};
+/**
+ * Type representing the result of a round (`state/result` and `state/all`)
+ */
+type WebResultResponse = {
+    round_id: number;
+    tally: string[];
+    option_1_emoji: string;
+    option_2_emoji: string;
+    total_votes: number;
+    end_time: number;
+    requester: string;
+};
+/**
+ * Type representing a token holder with their address and balance (`state/eligible-addresses`)
+ */
+type TokenHolder = {
+    address: string;
+    balance: string;
+};
 /**
  * Enum representing the credit mode for a round, which can be either constant or custom.
  * In constant mode, all voters receive the same amount of credits, while in custom mode,
@@ -135,7 +222,10 @@ declare enum CreditMode {
 }
 
 /**
- * Get the details of a specific round
+ * Get the details of a specific round in a camelCase convenience format
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @returns The round details
  */
 declare const getRoundDetails: (serverUrl: string, e3Id: number) => Promise<RoundDetails>;
 /**
@@ -145,6 +235,19 @@ 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 round data stored in the CRISPProgram contract, such as the merkle root
+ * of the census and the merkle root of the encrypted votes published so far.
+ *
+ * Unlike {@link getRoundDetails}, this reads directly from the chain and so does not
+ * depend on the CRISP server.
+ *
+ * @param programAddress - The address of the CRISPProgram contract
+ * @param e3Id - The e3Id of the round
+ * @param chainId - The chain ID of the network the program is deployed on
+ * @returns The on chain round data
+ */
+declare const getOnChainRoundData: (programAddress: string, e3Id: number, chainId: number) => Promise<OnChainRoundData>;
 /**
  * Get the previous ciphertext for a slot from the CRISP server.
  * Returns undefined when the slot is empty (404).
@@ -156,6 +259,88 @@ declare const getRoundTokenDetails: (serverUrl: string, e3Id: number) => Promise
  */
 declare const getPreviousCiphertext: (serverUrl: string, e3Id: number, address: string) => Promise<Uint8Array | undefined>;
 
+/**
+ * Get the current (most recent) round, optionally filtered by requester addresses.
+ * Returns undefined when no current round exists (404).
+ * @param serverUrl - The base URL of the CRISP server
+ * @param requesters - Optional list of requester addresses to filter by (only the first is used by the server)
+ * @returns The current round id, or undefined if none exists
+ */
+declare const getCurrentRound: (serverUrl: string, requesters?: string[]) => Promise<CurrentRoundResponse | undefined>;
+/**
+ * Get the committee public key for a given round.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @returns The committee public key bytes
+ */
+declare const getRoundPublicKey: (serverUrl: string, e3Id: number) => Promise<Uint8Array>;
+/**
+ * Get the ciphertext output for a given round.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @returns The ciphertext output bytes
+ */
+declare const getRoundCiphertext: (serverUrl: string, e3Id: number) => Promise<Uint8Array>;
+/**
+ * Request a new E3 round. Requires the server's cron API key.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param request - The new round request (cron API key, token address and balance threshold)
+ * @returns The server confirmation message
+ */
+declare const requestNewRound: (serverUrl: string, request: NewRoundRequest) => Promise<JsonResponse>;
+/**
+ * Broadcast an encrypted vote through the CRISP server, which relays it on-chain.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param request - The vote request (round id, hex encoded proof and voter address)
+ * @returns The broadcast result, including the transaction hash on success
+ */
+declare const broadcastVote: (serverUrl: string, request: BroadcastVoteRequest) => Promise<BroadcastVoteResponse>;
+/**
+ * Get the vote status for an address in a specific round.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @param address - The voter address
+ * @returns The vote status for the address
+ */
+declare const getVoteStatus: (serverUrl: string, e3Id: number, address: string) => Promise<VoteStatusResponse>;
+/**
+ * Get the result for a given round.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @returns The round result (tally, emojis, total votes, end time and requester)
+ */
+declare const getRoundResult: (serverUrl: string, e3Id: number) => Promise<WebResultResponse>;
+/**
+ * Get the results for all rounds, optionally filtered by requester addresses.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param requesters - Optional list of requester addresses to filter by
+ * @returns The results for all matching rounds
+ */
+declare const getAllRoundResults: (serverUrl: string, requesters?: string[]) => Promise<WebResultResponse[]>;
+/**
+ * Get the lite state for a given round, as returned by the server (snake_case fields).
+ * See `getRoundDetails` in `state.ts` for a camelCase convenience wrapper over this endpoint.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @returns The lite round state
+ */
+declare const getRoundStateLite: (serverUrl: string, e3Id: number) => Promise<E3StateLiteResponse>;
+/**
+ * Get the token holder hashes (hash(address, balance)) for a given round.
+ * These are the Merkle tree leaves used for eligibility proofs.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @returns The list of token holder hashes
+ */
+declare const getTokenHolderHashes: (serverUrl: string, e3Id: number) => Promise<string[]>;
+/**
+ * Get the eligible addresses and their balances for a given round.
+ * @param serverUrl - The base URL of the CRISP server
+ * @param e3Id - The e3Id of the round
+ * @returns The list of eligible token holders
+ */
+declare const getEligibleAddresses: (serverUrl: string, e3Id: number) => Promise<TokenHolder[]>;
+
 declare const MERKLE_TREE_MAX_DEPTH = 20;
 declare const MAX_MSG_NON_ZERO_COEFFS = 100;
 declare const MAX_VOTE_OPTIONS = 10;
@@ -309,6 +494,104 @@ declare class CrispSDK {
      * @returns A promise that resolves to the generated proof data.
      */
     generateVoteProof(voteProofInputs: VoteProofRequest): Promise<ProofData>;
+    /**
+     * Get the current (most recent) round, optionally filtered by requester addresses.
+     * @param requesters - Optional list of requester addresses to filter by
+     * @returns The current round id, or undefined if no round exists
+     */
+    getCurrentRound(requesters?: string[]): Promise<CurrentRoundResponse | undefined>;
+    /**
+     * Get the committee public key for a given round.
+     * @param e3Id - The e3Id of the round
+     * @returns The committee public key bytes
+     */
+    getRoundPublicKey(e3Id: number): Promise<Uint8Array>;
+    /**
+     * Get the ciphertext output for a given round.
+     * @param e3Id - The e3Id of the round
+     * @returns The ciphertext output bytes
+     */
+    getRoundCiphertext(e3Id: number): Promise<Uint8Array>;
+    /**
+     * Request a new E3 round. Requires the server's cron API key.
+     * @param request - The new round request (cron API key, token address and balance threshold)
+     * @returns The server confirmation message
+     */
+    requestNewRound(request: NewRoundRequest): Promise<JsonResponse>;
+    /**
+     * Broadcast an encrypted vote through the CRISP server, which relays it on-chain.
+     * @param request - The vote request (round id, hex encoded proof and voter address)
+     * @returns The broadcast result, including the transaction hash on success
+     */
+    broadcastVote(request: BroadcastVoteRequest): Promise<BroadcastVoteResponse>;
+    /**
+     * Get the vote status for an address in a specific round.
+     * @param e3Id - The e3Id of the round
+     * @param address - The voter address
+     * @returns The vote status for the address
+     */
+    getVoteStatus(e3Id: number, address: string): Promise<VoteStatusResponse>;
+    /**
+     * Get the result for a given round.
+     * @param e3Id - The e3Id of the round
+     * @returns The round result (tally, emojis, total votes, end time and requester)
+     */
+    getRoundResult(e3Id: number): Promise<WebResultResponse>;
+    /**
+     * Get the results for all rounds, optionally filtered by requester addresses.
+     * @param requesters - Optional list of requester addresses to filter by
+     * @returns The results for all matching rounds
+     */
+    getAllRoundResults(requesters?: string[]): Promise<WebResultResponse[]>;
+    /**
+     * Get the lite state for a given round, as returned by the server (snake_case fields).
+     * @param e3Id - The e3Id of the round
+     * @returns The lite round state
+     */
+    getRoundStateLite(e3Id: number): Promise<E3StateLiteResponse>;
+    /**
+     * Get the details of a specific round in a camelCase convenience format.
+     * @param e3Id - The e3Id of the round
+     * @returns The round details
+     */
+    getRoundDetails(e3Id: number): Promise<RoundDetails>;
+    /**
+     * Get the round data stored in the CRISPProgram contract, read directly from the chain.
+     *
+     * When the chain id is omitted it is looked up on the CRISP server.
+     *
+     * @param programAddress - The address of the CRISPProgram contract
+     * @param e3Id - The e3Id of the round
+     * @param chainId - The chain ID of the network the program is deployed on
+     * @returns The on chain round data
+     */
+    getOnChainRoundData(programAddress: string, e3Id: number, chainId?: number): Promise<OnChainRoundData>;
+    /**
+     * Get the token address, balance threshold and snapshot block for a specific round.
+     * @param e3Id - The e3Id of the round
+     * @returns The token details
+     */
+    getRoundTokenDetails(e3Id: number): Promise<TokenDetails>;
+    /**
+     * Get the token holder hashes (hash(address, balance)) for a given round.
+     * These are the Merkle tree leaves used for eligibility proofs.
+     * @param e3Id - The e3Id of the round
+     * @returns The list of token holder hashes
+     */
+    getTokenHolderHashes(e3Id: number): Promise<string[]>;
+    /**
+     * Get the eligible addresses and their balances for a given round.
+     * @param e3Id - The e3Id of the round
+     * @returns The list of eligible token holders
+     */
+    getEligibleAddresses(e3Id: number): Promise<TokenHolder[]>;
+    /**
+     * Get the previous ciphertext input for a slot address in a given round.
+     * @param e3Id - The e3Id of the round
+     * @param address - The address of the slot
+     * @returns The previous ciphertext, or undefined if the slot is empty
+     */
+    getPreviousCiphertext(e3Id: number, address: string): Promise<Uint8Array | undefined>;
 }
 
-export { CreditMode, CrispSDK, MAX_MSG_NON_ZERO_COEFFS, MAX_VOTE_OPTIONS, MERKLE_TREE_MAX_DEPTH, type MaskVoteProofInputs, type ProofData, type RoundDetails, type RoundDetailsResponse, SIGNATURE_MESSAGE, SIGNATURE_MESSAGE_HASH, type TokenDetails, type Vote, type VoteProofInputs, decodeTally, destroyBBApi, encodeSolidityProof, encryptVote, generateBFVKeys, generateMaskVoteProof, generateMerkleProof, generateMerkleTree, generateVoteProof, getAddressFromSignature, getBalanceAt, getMaxVoteValue, getPreviousCiphertext, getRoundDetails, getRoundTokenDetails, getScaledBalance, getTotalSupplyAt, getTreeData, getZeroVote, hashLeaf, validateVote, verifyProof };
+export { type BroadcastVoteRequest, type BroadcastVoteResponse, CreditMode, CrispSDK, type CurrentRoundResponse, type E3StateLiteResponse, type JsonResponse, MAX_MSG_NON_ZERO_COEFFS, MAX_VOTE_OPTIONS, MERKLE_TREE_MAX_DEPTH, type MaskVoteProofInputs, type NewRoundRequest, type OnChainRoundData, type ProofData, type RoundDetails, SIGNATURE_MESSAGE, SIGNATURE_MESSAGE_HASH, type TokenDetails, type TokenHolder, type Vote, type VoteProofInputs, type VoteResponseStatus, type VoteStatusResponse, type WebResultResponse, broadcastVote, decodeTally, destroyBBApi, encodeSolidityProof, encryptVote, generateBFVKeys, generateMaskVoteProof, generateMerkleProof, generateMerkleTree, generateVoteProof, getAddressFromSignature, getAllRoundResults, getBalanceAt, getCurrentRound, getEligibleAddresses, getMaxVoteValue, getOnChainRoundData, getPreviousCiphertext, getRoundCiphertext, getRoundDetails, getRoundPublicKey, getRoundResult, getRoundStateLite, getRoundTokenDetails, getScaledBalance, getTokenHolderHashes, getTotalSupplyAt, getTreeData, getVoteStatus, getZeroVote, hashLeaf, requestNewRound, validateVote, verifyProof };