Shield Module

Lightweight utilities for deposits. Import from @zkprivacy/sdk/shield for a smaller bundle (~150KB).

import { shieldTo, encryptNoteForRecipient, generateDepositAddress } from '@zkprivacy/sdk/shield';

shieldTo

Shield tokens to a ZK address.

await shieldTo(
  config: ShieldConfig,
  params: ShieldParams
): Promise<ShieldResult>

ShieldConfig

Property	Type	Description
rpcUrl	string	Ethereum RPC endpoint
poolAddress	Address	Pool contract address

ShieldParams

Property	Type	Required	Description
recipient	string	Yes	ZK address (zks1...)
amount	string	Yes	Human-readable amount
tokenAddress	Address	No	Token address (omit for ETH)
walletClient	WalletClient	Yes	Viem wallet client

ShieldResult

Property	Type	Description
txHash	Hash	Transaction hash
commitment	bigint	Note commitment

Example

import { shieldTo, DEPLOYMENTS } from '@zkprivacy/sdk/shield';

const result = await shieldTo(
  {
    rpcUrl: DEPLOYMENTS.remote.rpcUrl,
    poolAddress: DEPLOYMENTS.remote.pool,
  },
  {
    recipient: 'zks1...',
    amount: '100',
    tokenAddress: DEPLOYMENTS.remote.tokens.zkUSD,
    walletClient,
  }
);

console.log('TX:', result.txHash);

---

encryptNoteForRecipient

Create encrypted note data for a recipient.

encryptNoteForRecipient(
  recipient: string,    // zks1... address
  amount: bigint,
  tokenId: bigint,
): { encryptedNote: `0x${string}`, commitment: bigint }

Parameters

Parameter	Type	Description
recipient	string	ZK address (zks1...)
amount	bigint	Amount in smallest units
tokenId	bigint	Token ID (0n for ETH)

Returns

Property	Type	Description
encryptedNote	0x${string}	Hex-encoded encrypted note
commitment	bigint	Note commitment for Merkle tree

Example

import { encryptNoteForRecipient } from '@zkprivacy/sdk/shield';
import { parseUnits } from 'viem';

const { encryptedNote, commitment } = encryptNoteForRecipient(
  'zks1...',
  parseUnits('100', 6),  // 100 USDC
  BigInt(tokenAddress),
);

// Use in direct shield call
await walletClient.writeContract({
  address: tokenAddress,
  abi: EMT_ABI,
  functionName: 'shield',
  args: [
    amount,
    `0x${commitment.toString(16).padStart(64, '0')}`,
    encryptedNote,
  ],
});

Important

Always pass tokenId. Omitting it creates invalid commitments that can't be spent.

---

generateDepositAddress

Create a new ZK address for receiving deposits.

generateDepositAddress(): {
  address: string;
  spendingKey: bigint;
}

Returns

Property	Type	Description
address	string	ZK address (zks1...)
spendingKey	bigint	Private key to spend funds

Example

import { generateDepositAddress } from '@zkprivacy/sdk/shield';

const deposit = generateDepositAddress();

console.log('Send funds to:', deposit.address);
console.log('SAVE THIS KEY:', deposit.spendingKey.toString(16));

// Later, use the key to access funds
await client.connect({
  mode: 'standalone',
  spendingKey: deposit.spendingKey,
});

Security

The spending key controls all funds. Store it securely!

---

Address Utilities

decodeAddress

Decode a ZK address into its components.

import { decodeAddress } from '@zkprivacy/sdk';

const { spk, vpk } = decodeAddress('zks1...');

encodeAddress

Encode components into a ZK address.

import { encodeAddress } from '@zkprivacy/sdk';

const address = encodeAddress(spk, vpk);
// Returns: zks1...

---

Bundle Size

The shield module is designed for minimal bundle size:

Module	Size	Dependencies
@zkprivacy/sdk/shield	~150KB	@noble/curves, poseidon
@zkprivacy/sdk	~2MB	+ NoirJS, bb.js WASM

Use the shield module for:

• Deposit pages
• Payment links
• Widgets
• Server-side scripts

Use the full SDK when you need:

• Balance checking
• Transfers
• Unshields