Private Balances (shield / unshield)

​

The five rules

1. Key handling: privacy keys derive client-side from the user’s anchor (passkey encryptKey / PRF) and are never stored server-side. Cache the companion address, never the keys. Note the proving trust model below — it bounds what “private” may honestly mean in your copy.
2. One passkey gesture per shield/unshield — that IS the security model. Set the expectation: “You confirm with your fingerprint or Face ID — the same as when you send money.”
3. Browsers need a gateway proxy (gatewaySubmitUrl): the Starknet sequencer gateway has no CORS. Install the private-balance-card registry item to get the proxy route, or copy it from the example.
4. Capture the StarkWare pool ToS at the user’s first shield.
5. Fees: fixed 4 STRK per op, fronted by Chipi’s gas tank (metered per API key) — your user never holds STRK. Show it in USD via getShieldFee.

​

The trust model, honestly

​

What is the “companion”?

​

Quickstart

import { useShield, usePrivateBalance, derivePrivacyAccount } from "@chipi-stack/nextjs";

const keys = await derivePrivacyAccount({
  anchorSecret,                  // 32 bytes from your passkey rail
  seedDomainTag: wallet.address, // per-wallet domain separation
  classHash: COMPANION_CLASS_HASH,
});

const { shieldAsync } = useShield();
await shieldAsync({
  config: {
    apiPublicKey: process.env.NEXT_PUBLIC_CHIPI_API_KEY!,
    getBearerToken: () => getToken(),          // a FUNCTION: tokens die mid-flow
    gatewaySubmitUrl: "/api/starknet-gateway", // your CORS proxy
  },
  keys,
  token: USDC_ADDRESS,
  amount: 1_000_000n, // base units
  fundDeposit: (companion, amount) => transferGasless(companion, amount),
  onStep: setPhase,   // prepare | fund | deposit | prove | finish — drive a REAL loader
});

const { byToken } = usePrivateBalance({ mode: "ledger", events: recordedEvents });

​

Multiple tokens

• Shielding N tokens costs ONE proof and ONE 4-STRK fee — batch with the core-level execShieldMany (mainnet-proven). The useShield hook is per-token by design; for a multi-token shield call the core engine directly.
• Unshielding is per token (no unshieldMany yet): each withdrawal is its own proof and its own 4-STRK fee, and consecutive withdrawals must wait ~5–6 minutes for the prover’s view to catch up (they share the note channel). Run them sequentially, surface partial results honestly — what came back IS back, the rest stays private and retryable — and never call it a failure. Full pattern with the wait/refuel details on the Core SDK privacy page.