@chipi-stack/core 0.3.1 → 0.4.1

package/NOTICE-starknet-sdk.md

@@ -0,0 +1,13 @@
+# Bundled third-party software
+
+`@chipi-stack/core`'s build bundles the **StarkWare Starknet Privacy SDK**
+("starknet-sdk", from github.com/starknet-innovation/starknet-privacy),
+licensed under the **Apache License, Version 2.0**
+(http://www.apache.org/licenses/LICENSE-2.0).
+
+Changes from upstream: `ContractDiscoveryProvider` is re-exported from the
+package's main index (upstream exported it only via `starknet-sdk/testing`,
+which drags devnet/Node-only modules into client bundles).
+
+Copyright © StarkWare Industries and contributors. Bundled with attribution
+per Apache-2.0 §4. The full license text accompanies the upstream source.

package/README.md

@@ -98,3 +98,65 @@ Full docs at [docs.chipipay.com](https://docs.chipipay.com)
 ## License
 
 MIT
+
+
+## Private balances (STRK20 privacy pool)
+
+Mainnet-proven shield/unshield engine (Chipi's "Modo privado"). React apps
+should use the hooks in `@chipi-stack/chipi-react` / `@chipi-stack/nextjs`;
+this is the headless layer they wrap.
+
+```ts
+import {
+  ChipiProofProvider,
+  derivePoolKeypair,
+  deriveCompanionKeypair,
+  deriveCompanionAddress,
+  requestGasFunding,
+  waitForFunding,
+  execShield,
+  GAS_FUND_STRK,
+} from "@chipi-stack/core";
+import { RpcProvider } from "starknet";
+
+// Keys derive CLIENT-SIDE from the user's anchor — never persist them.
+// NOTE the trust model: delegated proving sends the pool key to the prover
+// per operation (privacy vs the PUBLIC, not the proving operator) — docs.
+const pool = await derivePoolKeypair({ anchorSecret, seedDomainTag: wallet.address });
+const companion = await deriveCompanionKeypair(anchorSecret);
+const companionAddress = deriveCompanionAddress({
+  publicKey: companion.publicKey,
+  classHash: COMPANION_CLASS_HASH,
+});
+
+const provider = new RpcProvider({ nodeUrl: "https://api.cartridge.gg/x/starknet/mainnet" });
+await requestGasFunding(companionAddress, {
+  baseUrl: "https://api.chipipay.com/v1",
+  apiKey: apiPublicKey,
+  getBearerToken: () => getToken(),
+});
+await waitForFunding(provider, companionAddress, { strk: GAS_FUND_STRK });
+const result = await execShield(
+  {
+    provider,
+    chainId: "0x534e5f4d41494e",
+    companionAddress,
+    companionKey: companion.privateKey,
+    classHash: COMPANION_CLASS_HASH,
+    poolKey: BigInt(pool.privateKey),
+    provingProvider: new ChipiProofProvider({
+      baseUrl: "https://api.chipipay.com/v1",
+      apiKey: apiPublicKey,
+      getBearerToken: () => getToken(),
+      chainId: "0x534e5f4d41494e",
+    }),
+  },
+  USDC_ADDRESS,
+  1_000_000n,
+);
+console.log(result.transactionHash); // receipt + pool event already verified
+```
+
+The bundled note-graph SDK is StarkWare's, Apache-2.0 — see
+`NOTICE-starknet-sdk.md`. Full guide: the docs' "Private Balances" page;
+runnable example + smoke: `examples/private-balance`.