@chipi-stack/chipi-react 14.8.0 → 14.10.0

package/README.md

@@ -109,3 +109,36 @@ Full docs at [docs.chipipay.com](https://docs.chipipay.com)
 ## License
 
 MIT
+
+
+## Private balances (useShield / useUnshield / usePrivateBalance)
+
+```tsx
+import { useShield, usePrivateBalance, derivePrivacyAccount } from "@chipi-stack/chipi-react";
+
+const keys = await derivePrivacyAccount({
+  anchorSecret,
+  seedDomainTag: wallet.address,
+  classHash: COMPANION_CLASS_HASH,
+});
+const { shieldAsync } = useShield();
+await shieldAsync({
+  config: {
+    apiPublicKey,
+    getBearerToken: () => getToken(),
+    gatewaySubmitUrl: "/api/starknet-gateway", // browsers need this CORS proxy
+  },
+  keys,
+  token: USDC_ADDRESS,
+  amount: 1_000_000n,
+  fundDeposit: (companion, amount) => transferGasless(companion, amount),
+  onStep: setPhase, // prepare | fund | deposit | prove | finish
+});
+const { byToken } = usePrivateBalance({ mode: "ledger", events: recordedEvents });
+```
+
+Client-derived keys (cache the address, never the keys; the DELEGATED
+PROVER sees the pool key per op — privacy holds vs the public, not the
+proving operator: see the docs' trust-model section),
+gasless for the end user (Chipi fronts the STRK per allowlisted API key).
+Capture the StarkWare pool ToS at the first shield. Full guide in the docs.