@cloak.ag/sdk 1.0.7 → 1.0.9

package/dist/index.d.cts

@@ -1753,6 +1753,7 @@ interface ShieldPoolPDAs {
     merkleTree: PublicKey;
     commitments: PublicKey;
     rootsRing: PublicKey;
+    /** @deprecated Use getNullifierPDA() for the new per-nullifier PDA design */
     nullifierShard: PublicKey;
     treasury: PublicKey;
 }
@@ -1774,6 +1775,30 @@ interface ShieldPoolPDAs {
  * @param mint - Optional mint address (defaults to 32 zero bytes for native SOL)
  */
 declare function getShieldPoolPDAs(programId?: PublicKey, mint?: PublicKey): ShieldPoolPDAs;
+/**
+ * Derive the nullifier PDA for a specific nullifier hash.
+ *
+ * With the new PDA-per-nullifier design, each nullifier has its own PDA
+ * instead of being stored in a shared shard. The PDA is created when
+ * the nullifier is used during withdrawal.
+ *
+ * Seeds: ["nullifier", nullifier_hash]
+ *
+ * @param nullifier - 32-byte nullifier hash
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @returns [PublicKey, bump] - The nullifier PDA and its bump seed
+ */
+declare function getNullifierPDA(nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+/**
+ * Derive the swap state PDA for a given nullifier.
+ *
+ * Seeds: ["swap_state", nullifier_hash]
+ *
+ * @param nullifier - 32-byte nullifier hash
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @returns [PublicKey, bump] - The swap state PDA and its bump seed
+ */
+declare function getSwapStatePDA(nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
 
 /**
  * On-chain Merkle proof computation
@@ -1838,6 +1863,11 @@ declare function computeProofForLatestDeposit(connection: Connection, merkleTree
  * as it doesn't require a backend prover service.
  */
 
+/**
+ * Default URL for fetching circuit artifacts
+ * These are served from the Cloak web app at https://cloak.ag
+ */
+declare const DEFAULT_CIRCUITS_URL = "https://www.cloak.ag/circuits";
 interface WithdrawRegularInputs {
     root: bigint;
     nullifier: bigint;
@@ -1898,6 +1928,23 @@ declare function generateWithdrawRegularProof(inputs: WithdrawRegularInputs, cir
  * @param circuitsPath - Path or URL to circuits directory. In browser, use URL like '/circuits' or full URL.
  */
 declare function generateWithdrawSwapProof(inputs: WithdrawSwapInputs, circuitsPath: string): Promise<ProofResult>;
+/**
+ * Check if circuits are available at the given path or URL
+ * Supports both local file paths and remote URLs
+ *
+ * Note: For remote URLs, this returns true without checking (snarkjs will handle loading).
+ * For local paths, it checks if the files exist on disk.
+ */
+declare function areCircuitsAvailable(circuitsPath: string): Promise<boolean>;
+/**
+ * Get default circuits path or URL
+ *
+ * Priority:
+ * 1. CIRCUITS_PATH environment variable (if set)
+ * 2. Local file paths (if available)
+ * 3. Default remote URL (https://cloak.ag/circuits)
+ */
+declare function getDefaultCircuitsPath(): Promise<string>;
 /**
  * Expected circuit hashes for verification
  * These are computed from the verification key files to ensure circuits match on-chain vkeys
@@ -2076,4 +2123,4 @@ declare function cleanupStalePendingOperations(maxAgeMs?: number): {
 
 declare const VERSION = "1.0.0";
 
-export { CLOAK_PROGRAM_ID, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, type DepositInstructionParams, type DepositOptions, type DepositResult, type DepositStatus, EXPECTED_CIRCUIT_HASHES, type EncryptedNote, type ErrorCategory, FIXED_FEE_LAMPORTS, type Groth16Proof, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, type Network, type NoteData, type OnchainMerkleProof, type PendingDeposit, type PendingWithdrawal, type ProofResult, RelayService, RootNotFoundError, ShieldPoolErrors, type ShieldPoolPDAs, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, VARIABLE_FEE_RATE, VERSION, type ViewKey, type WalletAdapter, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSubmissionResult, type WithdrawSwapInputs, bigintToBytes32, buildPublicInputsBytes, bytesToHex, calculateFee, calculateRelayFee, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeCommitment, computeMerkleRoot, computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeProofForLatestDeposit, computeProofFromChain, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, deriveSpendKey, deriveViewKey, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptNoteForRecipient, exportKeys, exportNote, exportWalletKeys, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatErrorForLogging, formatSol, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getDistributableAmount, getExplorerUrl, getPendingOperationsSummary, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getViewKey, hasPendingOperations, hexToBigint, hexToBytes, importKeys, importWalletKeys, isDebugEnabled, isRootNotFoundError, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, parseAmount, parseError, parseNote, parseTransactionError, poseidonHash, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToLimbs, randomBytes, readMerkleTreeState, removePendingDeposit, removePendingWithdrawal, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, sdkLogger, sendTransaction, serializeNote, setDebugMode, signTransaction, splitTo2Limbs, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, validateDepositParams, validateNote, validateOutputsSum, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, withTiming };
+export { CLOAK_PROGRAM_ID, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, DEFAULT_CIRCUITS_URL, type DepositInstructionParams, type DepositOptions, type DepositResult, type DepositStatus, EXPECTED_CIRCUIT_HASHES, type EncryptedNote, type ErrorCategory, FIXED_FEE_LAMPORTS, type Groth16Proof, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, type Network, type NoteData, type OnchainMerkleProof, type PendingDeposit, type PendingWithdrawal, type ProofResult, RelayService, RootNotFoundError, ShieldPoolErrors, type ShieldPoolPDAs, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, VARIABLE_FEE_RATE, VERSION, type ViewKey, type WalletAdapter, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSubmissionResult, type WithdrawSwapInputs, areCircuitsAvailable, bigintToBytes32, buildPublicInputsBytes, bytesToHex, calculateFee, calculateRelayFee, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeCommitment, computeMerkleRoot, computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeProofForLatestDeposit, computeProofFromChain, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, deriveSpendKey, deriveViewKey, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptNoteForRecipient, exportKeys, exportNote, exportWalletKeys, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatErrorForLogging, formatSol, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getDefaultCircuitsPath, getDistributableAmount, getExplorerUrl, getNullifierPDA, getPendingOperationsSummary, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, getViewKey, hasPendingOperations, hexToBigint, hexToBytes, importKeys, importWalletKeys, isDebugEnabled, isRootNotFoundError, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, parseAmount, parseError, parseNote, parseTransactionError, poseidonHash, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToLimbs, randomBytes, readMerkleTreeState, removePendingDeposit, removePendingWithdrawal, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, sdkLogger, sendTransaction, serializeNote, setDebugMode, signTransaction, splitTo2Limbs, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, validateDepositParams, validateNote, validateOutputsSum, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, withTiming };

package/dist/index.d.ts

@@ -1753,6 +1753,7 @@ interface ShieldPoolPDAs {
     merkleTree: PublicKey;
     commitments: PublicKey;
     rootsRing: PublicKey;
+    /** @deprecated Use getNullifierPDA() for the new per-nullifier PDA design */
     nullifierShard: PublicKey;
     treasury: PublicKey;
 }
@@ -1774,6 +1775,30 @@ interface ShieldPoolPDAs {
  * @param mint - Optional mint address (defaults to 32 zero bytes for native SOL)
  */
 declare function getShieldPoolPDAs(programId?: PublicKey, mint?: PublicKey): ShieldPoolPDAs;
+/**
+ * Derive the nullifier PDA for a specific nullifier hash.
+ *
+ * With the new PDA-per-nullifier design, each nullifier has its own PDA
+ * instead of being stored in a shared shard. The PDA is created when
+ * the nullifier is used during withdrawal.
+ *
+ * Seeds: ["nullifier", nullifier_hash]
+ *
+ * @param nullifier - 32-byte nullifier hash
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @returns [PublicKey, bump] - The nullifier PDA and its bump seed
+ */
+declare function getNullifierPDA(nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+/**
+ * Derive the swap state PDA for a given nullifier.
+ *
+ * Seeds: ["swap_state", nullifier_hash]
+ *
+ * @param nullifier - 32-byte nullifier hash
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @returns [PublicKey, bump] - The swap state PDA and its bump seed
+ */
+declare function getSwapStatePDA(nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
 
 /**
  * On-chain Merkle proof computation
@@ -1838,6 +1863,11 @@ declare function computeProofForLatestDeposit(connection: Connection, merkleTree
  * as it doesn't require a backend prover service.
  */
 
+/**
+ * Default URL for fetching circuit artifacts
+ * These are served from the Cloak web app at https://cloak.ag
+ */
+declare const DEFAULT_CIRCUITS_URL = "https://www.cloak.ag/circuits";
 interface WithdrawRegularInputs {
     root: bigint;
     nullifier: bigint;
@@ -1898,6 +1928,23 @@ declare function generateWithdrawRegularProof(inputs: WithdrawRegularInputs, cir
  * @param circuitsPath - Path or URL to circuits directory. In browser, use URL like '/circuits' or full URL.
  */
 declare function generateWithdrawSwapProof(inputs: WithdrawSwapInputs, circuitsPath: string): Promise<ProofResult>;
+/**
+ * Check if circuits are available at the given path or URL
+ * Supports both local file paths and remote URLs
+ *
+ * Note: For remote URLs, this returns true without checking (snarkjs will handle loading).
+ * For local paths, it checks if the files exist on disk.
+ */
+declare function areCircuitsAvailable(circuitsPath: string): Promise<boolean>;
+/**
+ * Get default circuits path or URL
+ *
+ * Priority:
+ * 1. CIRCUITS_PATH environment variable (if set)
+ * 2. Local file paths (if available)
+ * 3. Default remote URL (https://cloak.ag/circuits)
+ */
+declare function getDefaultCircuitsPath(): Promise<string>;
 /**
  * Expected circuit hashes for verification
  * These are computed from the verification key files to ensure circuits match on-chain vkeys
@@ -2076,4 +2123,4 @@ declare function cleanupStalePendingOperations(maxAgeMs?: number): {
 
 declare const VERSION = "1.0.0";
 
-export { CLOAK_PROGRAM_ID, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, type DepositInstructionParams, type DepositOptions, type DepositResult, type DepositStatus, EXPECTED_CIRCUIT_HASHES, type EncryptedNote, type ErrorCategory, FIXED_FEE_LAMPORTS, type Groth16Proof, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, type Network, type NoteData, type OnchainMerkleProof, type PendingDeposit, type PendingWithdrawal, type ProofResult, RelayService, RootNotFoundError, ShieldPoolErrors, type ShieldPoolPDAs, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, VARIABLE_FEE_RATE, VERSION, type ViewKey, type WalletAdapter, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSubmissionResult, type WithdrawSwapInputs, bigintToBytes32, buildPublicInputsBytes, bytesToHex, calculateFee, calculateRelayFee, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeCommitment, computeMerkleRoot, computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeProofForLatestDeposit, computeProofFromChain, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, deriveSpendKey, deriveViewKey, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptNoteForRecipient, exportKeys, exportNote, exportWalletKeys, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatErrorForLogging, formatSol, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getDistributableAmount, getExplorerUrl, getPendingOperationsSummary, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getViewKey, hasPendingOperations, hexToBigint, hexToBytes, importKeys, importWalletKeys, isDebugEnabled, isRootNotFoundError, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, parseAmount, parseError, parseNote, parseTransactionError, poseidonHash, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToLimbs, randomBytes, readMerkleTreeState, removePendingDeposit, removePendingWithdrawal, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, sdkLogger, sendTransaction, serializeNote, setDebugMode, signTransaction, splitTo2Limbs, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, validateDepositParams, validateNote, validateOutputsSum, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, withTiming };
+export { CLOAK_PROGRAM_ID, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, DEFAULT_CIRCUITS_URL, type DepositInstructionParams, type DepositOptions, type DepositResult, type DepositStatus, EXPECTED_CIRCUIT_HASHES, type EncryptedNote, type ErrorCategory, FIXED_FEE_LAMPORTS, type Groth16Proof, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, type Network, type NoteData, type OnchainMerkleProof, type PendingDeposit, type PendingWithdrawal, type ProofResult, RelayService, RootNotFoundError, ShieldPoolErrors, type ShieldPoolPDAs, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, VARIABLE_FEE_RATE, VERSION, type ViewKey, type WalletAdapter, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSubmissionResult, type WithdrawSwapInputs, areCircuitsAvailable, bigintToBytes32, buildPublicInputsBytes, bytesToHex, calculateFee, calculateRelayFee, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeCommitment, computeMerkleRoot, computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeProofForLatestDeposit, computeProofFromChain, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, deriveSpendKey, deriveViewKey, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptNoteForRecipient, exportKeys, exportNote, exportWalletKeys, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatErrorForLogging, formatSol, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getDefaultCircuitsPath, getDistributableAmount, getExplorerUrl, getNullifierPDA, getPendingOperationsSummary, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, getViewKey, hasPendingOperations, hexToBigint, hexToBytes, importKeys, importWalletKeys, isDebugEnabled, isRootNotFoundError, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, parseAmount, parseError, parseNote, parseTransactionError, poseidonHash, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToLimbs, randomBytes, readMerkleTreeState, removePendingDeposit, removePendingWithdrawal, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, sdkLogger, sendTransaction, serializeNote, setDebugMode, signTransaction, splitTo2Limbs, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, validateDepositParams, validateNote, validateOutputsSum, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, withTiming };