privacycash 1.2.2 → 1.2.3

package/README.md

@@ -2,7 +2,9 @@
 This is the SDK for Privacy Cash. It has been audited by Zigtur (https://x.com/zigtur).
 
 ### Disclaimer
-This SDK powers Privacy Cash's frontend, assuming the single wallet use case. If you use it or published npm library from this repo, please fully test and beware of the inherent software risks or potential bugs.
+This SDK powers Privacy Cash's frontend, assuming the single wallet use case. It is NOT supposed to support hardware wallet.
+
+If you use it or published npm library from this repo, please fully test and beware of the inherent software risks or potential bugs. Our team is not responsible for any losses.
 
 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
@@ -18,6 +20,8 @@ depositSPL(), withdrawSPL(), getPrivateBalanceSpl()
 For backend integration:  
 Check the example project under /example folder. The code should be fairly self-explanatory.  
 
+For SDK referral attribution, pass the database-assigned partner id when withdrawing, for example `privacyCash.withdraw({ lamports: 10000000, referralId: 'partner_id' })`. The same `referralId` option is available on `withdrawUSDC` and `withdrawSPL`. Invalid or inactive ids are rejected before the withdrawal is submitted. The old `referrer` wallet-address option does not enroll a withdrawal in this program. When a referral id is supplied, check `referralRecorded` in the result; a false value means the withdrawal succeeded but the referral entry needs reconciliation using `tx`.
+
 For frontend integration:  
 Check the example project above, but also refer to: https://gist.github.com/SocialfiPanda/c63786b5dd156e59847e9a4afca31a77
 
@@ -31,6 +35,9 @@ Next.js project needs to update the postinstall build scripts:
 
 Use node version 24 or above.
 
+### Warnings
+Privacy Cash SDK requires consistent signature generation, otherwise the deposited tokens might be lost forever since the encrypted UTXO can't be decrypted. For frontend, please make sure deriveEncryptionKeyFromSignature() generates the same result for the same params passed in, and for backend, please make sure deriveEncryptionKeyFromWallet() generates the same result. Most wallets returns the same result, but some non major wallets might generate different result.
+
 ### Tests
 1. To run unit tests:
 ```

package/dist/index.d.ts

@@ -45,32 +45,34 @@ export declare class PrivacyCash {
      *
      * Lamports is the amount of SOL in lamports. e.g. if you want to withdraw 0.01 SOL (10000000 lamports), call withdraw({ lamports: 10000000 })
      */
-    withdraw({ lamports, recipientAddress, referrer }: {
+    withdraw({ lamports, recipientAddress, referralId }: {
         lamports: number;
         recipientAddress?: string;
-        referrer?: string;
+        referralId?: string;
     }): Promise<{
         isPartial: boolean;
         tx: string;
         recipient: string;
         amount_in_lamports: number;
         fee_in_lamports: number;
+        referralRecorded: boolean | undefined;
     }>;
     /**
       * Withdraw USDC from the Privacy Cash.
       *
       * base_units is the amount of USDC in base unit. e.g. if you want to withdraw 1 USDC (1,000,000 base unit), call withdraw({ base_units: 1000000, recipientAddress: 'some_address' })
       */
-    withdrawUSDC({ base_units, recipientAddress, referrer }: {
+    withdrawUSDC({ base_units, recipientAddress, referralId }: {
         base_units: number;
         recipientAddress?: string;
-        referrer?: string;
+        referralId?: string;
     }): Promise<{
         isPartial: boolean;
         tx: string;
         recipient: string;
         base_units: number;
         fee_base_units: number;
+        referralRecorded: boolean | undefined;
     }>;
     /**
      * Returns the amount of lamports current wallet has in Privacy Cash.
@@ -112,17 +114,18 @@ export declare class PrivacyCash {
     /**
       * Withdraw SPL from the Privacy Cash.
       */
-    withdrawSPL({ base_units, mintAddress, recipientAddress, amount, referrer }: {
+    withdrawSPL({ base_units, mintAddress, recipientAddress, amount, referralId }: {
         base_units?: number;
         amount?: number;
         mintAddress: PublicKey | string;
         recipientAddress?: string;
-        referrer?: string;
+        referralId?: string;
     }): Promise<{
         isPartial: boolean;
         tx: string;
         recipient: string;
         base_units: number;
         fee_base_units: number;
+        referralRecorded: boolean | undefined;
     }>;
 }

package/dist/index.js

@@ -123,7 +123,7 @@ export class PrivacyCash {
      *
      * Lamports is the amount of SOL in lamports. e.g. if you want to withdraw 0.01 SOL (10000000 lamports), call withdraw({ lamports: 10000000 })
      */
-    async withdraw({ lamports, recipientAddress, referrer }) {
+    async withdraw({ lamports, recipientAddress, referralId }) {
         this.isRuning = true;
         logger.info('start withdrawing');
         let lightWasm = await WasmFactory.getInstance();
@@ -137,7 +137,7 @@ export class PrivacyCash {
             recipient,
             keyBasePath: path.join(import.meta.dirname, '..', 'circuit2', 'transaction2'),
             storage,
-            referrer
+            referralId
         });
         logger.debug(`Withdraw successful. Recipient ${recipient} received ${res.amount_in_lamports / LAMPORTS_PER_SOL} SOL, with ${res.fee_in_lamports / LAMPORTS_PER_SOL} SOL relayers fees`);
         this.isRuning = false;
@@ -148,7 +148,7 @@ export class PrivacyCash {
       *
       * base_units is the amount of USDC in base unit. e.g. if you want to withdraw 1 USDC (1,000,000 base unit), call withdraw({ base_units: 1000000, recipientAddress: 'some_address' })
       */
-    async withdrawUSDC({ base_units, recipientAddress, referrer }) {
+    async withdrawUSDC({ base_units, recipientAddress, referralId }) {
         this.isRuning = true;
         logger.info('start withdrawing');
         let lightWasm = await WasmFactory.getInstance();
@@ -163,7 +163,7 @@ export class PrivacyCash {
             recipient,
             keyBasePath: path.join(import.meta.dirname, '..', 'circuit2', 'transaction2'),
             storage,
-            referrer
+            referralId
         });
         logger.debug(`Withdraw successful. Recipient ${recipient} received ${base_units} USDC units`);
         this.isRuning = false;
@@ -250,7 +250,7 @@ export class PrivacyCash {
     /**
       * Withdraw SPL from the Privacy Cash.
       */
-    async withdrawSPL({ base_units, mintAddress, recipientAddress, amount, referrer }) {
+    async withdrawSPL({ base_units, mintAddress, recipientAddress, amount, referralId }) {
         this.isRuning = true;
         logger.info('start withdrawing');
         let lightWasm = await WasmFactory.getInstance();
@@ -266,7 +266,7 @@ export class PrivacyCash {
             keyBasePath: path.join(import.meta.dirname, '..', 'circuit2', 'transaction2'),
             storage,
             mintAddress,
-            referrer
+            referralId
         });
         logger.debug(`Withdraw successful. Recipient ${recipient} received ${base_units} USDC units`);
         this.isRuning = false;

package/dist/withdraw.d.ts

@@ -10,13 +10,14 @@ type WithdrawParams = {
     lightWasm: hasher.LightWasm;
     recipient: PublicKey;
     storage: Storage;
-    referrer?: string;
+    referralId?: string;
 };
-export declare function withdraw({ recipient, lightWasm, storage, publicKey, connection, amount_in_lamports, encryptionService, keyBasePath, referrer }: WithdrawParams): Promise<{
+export declare function withdraw({ recipient, lightWasm, storage, publicKey, connection, amount_in_lamports, encryptionService, keyBasePath, referralId }: WithdrawParams): Promise<{
     isPartial: boolean;
     tx: string;
     recipient: string;
     amount_in_lamports: number;
     fee_in_lamports: number;
+    referralRecorded: boolean | undefined;
 }>;
 export {};

package/dist/withdraw.js

@@ -28,14 +28,14 @@ async function submitWithdrawToIndexer(params) {
         const result = await response.json();
         logger.debug('Withdraw request submitted successfully!');
         logger.debug('Response:', result);
-        return result.signature;
+        return result;
     }
     catch (error) {
         logger.debug('Failed to submit withdraw request to indexer:', typeof error, error);
         throw error;
     }
 }
-export async function withdraw({ recipient, lightWasm, storage, publicKey, connection, amount_in_lamports, encryptionService, keyBasePath, referrer }) {
+export async function withdraw({ recipient, lightWasm, storage, publicKey, connection, amount_in_lamports, encryptionService, keyBasePath, referralId }) {
     let fee_in_lamports = Math.floor(amount_in_lamports * (await getConfig('withdraw_fee_rate')) + LAMPORTS_PER_SOL * (await getConfig('withdraw_rent_fee')));
     amount_in_lamports = Math.floor(amount_in_lamports - fee_in_lamports);
     let isPartial = false;
@@ -241,12 +241,12 @@ export async function withdraw({ recipient, lightWasm, storage, publicKey, conne
         encryptedOutput2: encryptedOutput2.toString('base64'),
         fee: fee_in_lamports,
         lookupTableAddress: ALT_ADDRESS.toString(),
-        referralWalletAddress: referrer
+        referralId
     };
     logger.debug('Prepared withdraw parameters for indexer backend');
     // Submit to indexer backend instead of directly to Solana
     logger.info('submitting transaction to relayer...');
-    const signature = await submitWithdrawToIndexer(withdrawParams);
+    const { signature, referralRecorded } = await submitWithdrawToIndexer(withdrawParams);
     // Wait a moment for the transaction to be confirmed
     logger.info('waiting for transaction confirmation...');
     let retryTimes = 0;
@@ -262,7 +262,7 @@ export async function withdraw({ recipient, lightWasm, storage, publicKey, conne
         let resJson = await res.json();
         logger.debug('resJson:', resJson);
         if (resJson.exists) {
-            return { isPartial, tx: signature, recipient: recipient.toString(), amount_in_lamports, fee_in_lamports };
+            return { isPartial, tx: signature, recipient: recipient.toString(), amount_in_lamports, fee_in_lamports, referralRecorded };
         }
         if (retryTimes >= 10) {
             throw new Error('Refresh the page to see latest balance.');

package/dist/withdrawSPL.d.ts

@@ -12,13 +12,14 @@ type WithdrawParams = {
     recipient: PublicKey;
     mintAddress: PublicKey | string;
     storage: Storage;
-    referrer?: string;
+    referralId?: string;
 };
-export declare function withdrawSPL({ recipient, lightWasm, storage, publicKey, connection, base_units, amount, encryptionService, keyBasePath, mintAddress, referrer }: WithdrawParams): Promise<{
+export declare function withdrawSPL({ recipient, lightWasm, storage, publicKey, connection, base_units, amount, encryptionService, keyBasePath, mintAddress, referralId }: WithdrawParams): Promise<{
     isPartial: boolean;
     tx: string;
     recipient: string;
     base_units: number;
     fee_base_units: number;
+    referralRecorded: boolean | undefined;
 }>;
 export {};

package/dist/withdrawSPL.js

@@ -29,14 +29,14 @@ async function submitWithdrawToIndexer(params) {
         const result = await response.json();
         logger.debug('Withdraw request submitted successfully!');
         logger.debug('Response:', result);
-        return result.signature;
+        return result;
     }
     catch (error) {
         logger.debug('Failed to submit withdraw request to indexer:', typeof error, error);
         throw error;
     }
 }
-export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, connection, base_units, amount, encryptionService, keyBasePath, mintAddress, referrer }) {
+export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, connection, base_units, amount, encryptionService, keyBasePath, mintAddress, referralId }) {
     if (typeof mintAddress == 'string') {
         mintAddress = new PublicKey(mintAddress);
     }
@@ -265,12 +265,12 @@ export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, co
         recipientAta: recipient_ata.toString(),
         mintAddress: token.pubkey.toString(),
         feeRecipientTokenAccount: feeRecipientTokenAccount.toString(),
-        referralWalletAddress: referrer
+        referralId
     };
     logger.debug('Prepared withdraw parameters for indexer backend');
     // Submit to indexer backend instead of directly to Solana
     logger.info('submitting transaction to relayer...');
-    const signature = await submitWithdrawToIndexer(withdrawParams);
+    const { signature, referralRecorded } = await submitWithdrawToIndexer(withdrawParams);
     // Wait a moment for the transaction to be confirmed
     logger.info('waiting for transaction confirmation...');
     let retryTimes = 0;
@@ -286,7 +286,7 @@ export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, co
         let resJson = await res.json();
         logger.debug('resJson:', resJson);
         if (resJson.exists) {
-            return { isPartial, tx: signature, recipient: recipient.toString(), base_units, fee_base_units };
+            return { isPartial, tx: signature, recipient: recipient.toString(), base_units, fee_base_units, referralRecorded };
         }
         if (retryTimes >= 10) {
             throw new Error('Refresh the page to see latest balance.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privacycash",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "",
   "main": "dist/index.js",
   "repository": "https://github.com/Privacy-Cash/privacy-cash-sdk",
@@ -48,4 +48,4 @@
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   }
-}
+}

package/src/index.ts

@@ -141,10 +141,10 @@ export class PrivacyCash {
      * 
      * Lamports is the amount of SOL in lamports. e.g. if you want to withdraw 0.01 SOL (10000000 lamports), call withdraw({ lamports: 10000000 })
      */
-    async withdraw({ lamports, recipientAddress, referrer }: {
+    async withdraw({ lamports, recipientAddress, referralId }: {
         lamports: number,
         recipientAddress?: string,
-        referrer?: string
+        referralId?: string
     }) {
         this.isRuning = true
         logger.info('start withdrawing')
@@ -159,7 +159,7 @@ export class PrivacyCash {
             recipient,
             keyBasePath: path.join(import.meta.dirname, '..', 'circuit2', 'transaction2'),
             storage,
-            referrer
+            referralId
         })
         logger.debug(`Withdraw successful. Recipient ${recipient} received ${res.amount_in_lamports / LAMPORTS_PER_SOL} SOL, with ${res.fee_in_lamports / LAMPORTS_PER_SOL} SOL relayers fees`)
         this.isRuning = false
@@ -171,10 +171,10 @@ export class PrivacyCash {
       * 
       * base_units is the amount of USDC in base unit. e.g. if you want to withdraw 1 USDC (1,000,000 base unit), call withdraw({ base_units: 1000000, recipientAddress: 'some_address' })
       */
-    async withdrawUSDC({ base_units, recipientAddress, referrer }: {
+    async withdrawUSDC({ base_units, recipientAddress, referralId }: {
         base_units: number,
         recipientAddress?: string,
-        referrer?: string
+        referralId?: string
     }) {
         this.isRuning = true
         logger.info('start withdrawing')
@@ -190,7 +190,7 @@ export class PrivacyCash {
             recipient,
             keyBasePath: path.join(import.meta.dirname, '..', 'circuit2', 'transaction2'),
             storage,
-            referrer
+            referralId
         })
         logger.debug(`Withdraw successful. Recipient ${recipient} received ${base_units} USDC units`)
         this.isRuning = false
@@ -288,12 +288,12 @@ export class PrivacyCash {
     /**
       * Withdraw SPL from the Privacy Cash.
       */
-    async withdrawSPL({ base_units, mintAddress, recipientAddress, amount, referrer }: {
+    async withdrawSPL({ base_units, mintAddress, recipientAddress, amount, referralId }: {
         base_units?: number,
         amount?: number,
         mintAddress: PublicKey | string,
         recipientAddress?: string,
-        referrer?: string
+        referralId?: string
     }) {
         this.isRuning = true
         logger.info('start withdrawing')
@@ -311,7 +311,7 @@ export class PrivacyCash {
             keyBasePath: path.join(import.meta.dirname, '..', 'circuit2', 'transaction2'),
             storage,
             mintAddress,
-            referrer
+            referralId
         })
         logger.debug(`Withdraw successful. Recipient ${recipient} received ${base_units} USDC units`)
         this.isRuning = false
@@ -353,4 +353,4 @@ function stdWrite(status: string, frame: string) {
     let blue = "\x1b[34m";
     let reset = "\x1b[0m";
     process.stdout.write(`${frame}status: ${blue}${status}${reset}\r`);
-}
+}

package/src/withdraw.ts

@@ -17,7 +17,7 @@ import { logger } from './utils/logger.js';
 
 
 // Function to submit withdraw request to indexer backend
-async function submitWithdrawToIndexer(params: any): Promise<string> {
+async function submitWithdrawToIndexer(params: any): Promise<{ signature: string, referralRecorded?: boolean }> {
     try {
 
         const response = await fetch(`${RELAYER_API_URL}/withdraw`, {
@@ -33,11 +33,11 @@ async function submitWithdrawToIndexer(params: any): Promise<string> {
             throw new Error(errorData.error)
         }
 
-        const result = await response.json() as { signature: string, success: boolean };
+        const result = await response.json() as { signature: string, success: boolean, referralRecorded?: boolean };
         logger.debug('Withdraw request submitted successfully!');
         logger.debug('Response:', result);
 
-        return result.signature;
+        return result;
     } catch (error) {
         logger.debug('Failed to submit withdraw request to indexer:', typeof error, error);
         throw error;
@@ -53,10 +53,10 @@ type WithdrawParams = {
     lightWasm: hasher.LightWasm,
     recipient: PublicKey,
     storage: Storage,
-    referrer?: string,
+    referralId?: string,
 }
 
-export async function withdraw({ recipient, lightWasm, storage, publicKey, connection, amount_in_lamports, encryptionService, keyBasePath, referrer }: WithdrawParams) {
+export async function withdraw({ recipient, lightWasm, storage, publicKey, connection, amount_in_lamports, encryptionService, keyBasePath, referralId }: WithdrawParams) {
     let fee_in_lamports = Math.floor(amount_in_lamports * (await getConfig('withdraw_fee_rate')) + LAMPORTS_PER_SOL * (await getConfig('withdraw_rent_fee')))
     amount_in_lamports = Math.floor(amount_in_lamports - fee_in_lamports)
     let isPartial = false
@@ -297,7 +297,7 @@ export async function withdraw({ recipient, lightWasm, storage, publicKey, conne
         encryptedOutput2: encryptedOutput2.toString('base64'),
         fee: fee_in_lamports,
         lookupTableAddress: ALT_ADDRESS.toString(),
-        referralWalletAddress: referrer
+        referralId
     };
 
 
@@ -305,7 +305,7 @@ export async function withdraw({ recipient, lightWasm, storage, publicKey, conne
 
     // Submit to indexer backend instead of directly to Solana
     logger.info('submitting transaction to relayer...')
-    const signature = await submitWithdrawToIndexer(withdrawParams);
+    const { signature, referralRecorded } = await submitWithdrawToIndexer(withdrawParams);
     // Wait a moment for the transaction to be confirmed
     logger.info('waiting for transaction confirmation...')
     let retryTimes = 0
@@ -321,7 +321,7 @@ export async function withdraw({ recipient, lightWasm, storage, publicKey, conne
         let resJson = await res.json()
         logger.debug('resJson:', resJson)
         if (resJson.exists) {
-            return { isPartial, tx: signature, recipient: recipient.toString(), amount_in_lamports, fee_in_lamports }
+            return { isPartial, tx: signature, recipient: recipient.toString(), amount_in_lamports, fee_in_lamports, referralRecorded }
         }
         if (retryTimes >= 10) {
             throw new Error('Refresh the page to see latest balance.')
@@ -329,4 +329,4 @@ export async function withdraw({ recipient, lightWasm, storage, publicKey, conne
         retryTimes++
     }
 
-}
+}

package/src/withdrawSPL.ts

@@ -18,7 +18,7 @@ import { logger } from './utils/logger.js';
 
 
 // Function to submit withdraw request to indexer backend
-async function submitWithdrawToIndexer(params: any): Promise<string> {
+async function submitWithdrawToIndexer(params: any): Promise<{ signature: string, referralRecorded?: boolean }> {
     try {
         const response = await fetch(`${RELAYER_API_URL}/withdraw/spl`, {
             method: 'POST',
@@ -33,11 +33,11 @@ async function submitWithdrawToIndexer(params: any): Promise<string> {
             throw new Error(errorData.error)
         }
 
-        const result = await response.json() as { signature: string, success: boolean };
+        const result = await response.json() as { signature: string, success: boolean, referralRecorded?: boolean };
         logger.debug('Withdraw request submitted successfully!');
         logger.debug('Response:', result);
 
-        return result.signature;
+        return result;
     } catch (error) {
         logger.debug('Failed to submit withdraw request to indexer:', typeof error, error);
         throw error;
@@ -55,10 +55,10 @@ type WithdrawParams = {
     recipient: PublicKey,
     mintAddress: PublicKey | string,
     storage: Storage,
-    referrer?: string,
+    referralId?: string,
 }
 
-export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, connection, base_units, amount, encryptionService, keyBasePath, mintAddress, referrer }: WithdrawParams) {
+export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, connection, base_units, amount, encryptionService, keyBasePath, mintAddress, referralId }: WithdrawParams) {
     if (typeof mintAddress == 'string') {
         mintAddress = new PublicKey(mintAddress)
     }
@@ -350,14 +350,14 @@ export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, co
         recipientAta: recipient_ata.toString(),
         mintAddress: token.pubkey.toString(),
         feeRecipientTokenAccount: feeRecipientTokenAccount.toString(),
-        referralWalletAddress: referrer
+        referralId
     };
 
     logger.debug('Prepared withdraw parameters for indexer backend');
 
     // Submit to indexer backend instead of directly to Solana
     logger.info('submitting transaction to relayer...')
-    const signature = await submitWithdrawToIndexer(withdrawParams);
+    const { signature, referralRecorded } = await submitWithdrawToIndexer(withdrawParams);
     // Wait a moment for the transaction to be confirmed
     logger.info('waiting for transaction confirmation...')
     let retryTimes = 0
@@ -373,7 +373,7 @@ export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, co
         let resJson = await res.json()
         logger.debug('resJson:', resJson)
         if (resJson.exists) {
-            return { isPartial, tx: signature, recipient: recipient.toString(), base_units, fee_base_units }
+            return { isPartial, tx: signature, recipient: recipient.toString(), base_units, fee_base_units, referralRecorded }
         }
         if (retryTimes >= 10) {
             throw new Error('Refresh the page to see latest balance.')