Frontend Integration

Demo Project

A complete example project demonstrating how to use PrivacyCash SDK:

https://github.com/Privacy-Cash/solana-sdk-demo-interface

Installation

npm install privacycash --save

Requires Node.js 24+. The SDK is written in TypeScript and includes type definitions.

Deriving Encryption Key

Client need to ask user to sign an offchain message, before the user can interact with Privacy Cash.

async function getSignedSignature(signed: Signed) {
    if (signed.signature) {
        return
    }
    const encodedMessage = new TextEncoder().encode(`Privacy Money account sign in`)
    const cacheKey = `zkcash-signature-${signed.publicKey.toBase58()}`

    // ask for sign
    let signature: Uint8Array
    try {
        signature = await signed.provider.signMessage(encodedMessage)
    } catch (err: any) {
        if (err instanceof Error && err.message?.toLowerCase().includes('user rejected')) {
            throw new Error('User rejected the signature request')
        }
        throw new Error('Failed to sign message: ' + err.message)
    }
    
    if (currentSigned.pubKeyStr != signed.publicKey.toString()) {
        throw new Error(`Don't switch account when signing in. Refresh the page and try again.`)
    }

    // If wallet.signMessage returned an object, extract `signature`
    // @ts-ignore
    if (signature.signature) {
        // @ts-ignore
        signature = signature.signature
    }

    if (!(signature instanceof Uint8Array)) {
        throw new Error('signature is not an Uint8Array type')
    }
    signed.signature = signature
}

export type Signed = {
    publicKey: PublicKey,
    signature?: Uint8Array,
    provider: any
}

Once the user signed the message, pass the resulting signature to EncryptionService of the SDK:

export * from "privacycash/utils"

let encryptionService = new EncryptionService();
encryptionService.deriveEncryptionKeyFromSignature(signed.signature);

Get hasher

const { WasmFactory } = await import('@lightprotocol/hasher.rs');
const hasher = await WasmFactory.getInstance();

Common Issues

Next.js project needs to update the postinstall build scripts:

"scripts": {
    "postinstall": "cp node_modules/@lightprotocol/hasher.rs/dist/hasher_wasm_simd_bg.wasm node_modules/@lightprotocol/hasher.rs/dist/browser-fat/es/ && cp node_modules/@lightprotocol/hasher.rs/dist/light_wasm_hasher_bg.wasm node_modules/@lightprotocol/hasher.rs/dist/browser-fat/es/",
},..}

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.