@0xbow/privacy-pools-core-sdk 1.1.1 → 1.2.0

package/README.md

@@ -1,10 +1,9 @@
 # Privacy Pool Core SDK
 
-A TypeScript SDK for interacting with the Privacy Pool protocol. This SDK provides a comprehensive set of tools and utilities for integrating with Privacy Pool, enabling deposits, withdrawals, and other core functionality.
+A TypeScript SDK for interacting with the Privacy Pool protocol. This SDK provides cryptographic utilities, proof generation, account management, and contract interactions for Privacy Pool integration.
 
 ## Installation
 
-
 ```bash
 npm install @0xbow/privacy-pools-core-sdk
 # or
@@ -35,33 +34,113 @@ pnpm add @0xbow/privacy-pools-core-sdk
 
 ## Usage
 
+### Initialization
+
+```typescript
+import { PrivacyPoolSDK, Circuits } from '@0xbow/privacy-pools-core-sdk';
+
+// In Node.js — set browser: false to load artifacts from the filesystem
+const circuits = new Circuits({ browser: false });
+
+// In the browser — the default (browser: true) uses fetch
+// const circuits = new Circuits();
+
+const sdk = new PrivacyPoolSDK(circuits);
+```
+
+### Commitment Proofs
+
+```typescript
+const commitmentProof = await sdk.proveCommitment(value, label, nullifier, secret);
+const isValid = await sdk.verifyCommitment(commitmentProof);
+```
+
+### Withdrawal Proofs
+
+```typescript
+const withdrawalProof = await sdk.proveWithdrawal(commitment, withdrawalInput);
+const isValid = await sdk.verifyWithdrawal(withdrawalProof);
+```
+
+### Key Derivation
+
+The SDK derives deterministic master keys from a BIP-39 mnemonic phrase using `generateMasterKeys`. These keys are used to generate per-deposit and per-withdrawal nullifiers and secrets.
+
+```typescript
+import { generateMasterKeys, generateDepositSecrets, generateWithdrawalSecrets } from '@0xbow/privacy-pools-core-sdk';
+
+const { masterNullifier, masterSecret } = generateMasterKeys(mnemonic);
+
+const depositSecrets = generateDepositSecrets(
+  { masterNullifier, masterSecret },
+  scope,
+  index,
+);
+
+const withdrawalSecrets = generateWithdrawalSecrets(
+  { masterNullifier, masterSecret },
+  label,
+  index,
+);
+```
+
+### Account Recovery
+
+The `AccountService` reconstructs on-chain account state from a mnemonic by scanning deposit, withdrawal, and ragequit events.
+
+```typescript
+import { AccountService, DataService } from '@0xbow/privacy-pools-core-sdk';
+
+const { account, errors } = await AccountService.initializeWithEvents(
+  dataService,
+  { mnemonic },
+  pools,
+);
+```
+
+### Contract Interactions
+
 ```typescript
-import { PrivacyPoolSDK } from '@0xbow/privacy-pools-core-sdk';
-
-// Initialize the SDK
-const sdk = new PrivacyPoolSDK({
-  // Configuration options
-});
-
-// Example: Create a deposit
-const deposit = await sdk.deposit({
-  // Deposit parameters
-});
-
-// Example: Create a withdrawal
-const withdrawal = await sdk.withdraw({
-  // Withdrawal parameters
-});
+const contracts = sdk.createContractInstance(rpcUrl, chain, entrypointAddress, privateKey);
 ```
 
-For detailed usage examples and API documentation, please refer to our [documentation](https://github.com/defi-wonderland/privacy-pool-core/tree/main/docs).
+## Mnemonic Security
+
+The SDK does **not** provide a `generateMnemonic` utility. Use a trusted BIP-39 library (e.g. `@scure/bip39` or `viem/accounts`) to generate mnemonic phrases externally.
+
+- **Never hardcode** mnemonics in source code or configuration files.
+- **Never log or transmit** mnemonics in plaintext.
+- **Store mnemonics** using OS-level secure storage (e.g. OS keychain, encrypted vault) — never in browser localStorage or unencrypted files.
+- **Do not reuse** a single mnemonic across unrelated applications. A compromised mnemonic exposes all derived keys and the funds they control.
+- The mnemonic is the **sole root of all derived keys**. Loss of the mnemonic means permanent loss of access to all associated commitments and funds.
+
+## Circuit Artifact Integrity
+
+The SDK verifies **every** downloaded circuit artifact (wasm, vkey, zkey) against expected SHA-256 digests. Artifacts without a registered hash are rejected at load time.
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `commitment.wasm` | `254d2130607182fd6fd1aee67971526b13cfe178c88e360da96dce92663828d8` |
+| `commitment.vkey` | `7d48b4eb3dedc12fb774348287b587f0c18c3c7254cd60e9cf0f8b3636a570d8` |
+| `commitment.zkey` | `494ae92d64098fda2a5649690ddc5821fcd7449ca5fe8ef99ee7447544d7e1f3` |
+| `withdraw.wasm` | `36cda22791def3d520a55c0fc808369cd5849532a75fab65686e666ed3d55c10` |
+| `withdraw.vkey` | `666bd0983b20c1611543b04f7712e067fbe8cad69f07ada8a310837ff398d21e` |
+| `withdraw.zkey` | `2a893b42174c813566e5c40c715a8b90cd49fc4ecf384e3a6024158c3d6de677` |
+
+You can independently verify these against the committed artifacts:
+
+```bash
+shasum -a 256 packages/circuits/trusted-setup/final-keys/*.{vkey,zkey}
+shasum -a 256 packages/circuits/build/*/*_js/*.wasm
+```
 
 ## Features
 
-- Deposit and withdrawal functionality
-- Zero-knowledge proof generation
-- Commitment management
-- Contract interactions
+- Zero-knowledge proof generation and verification (commitments and withdrawals)
+- Deterministic key derivation from BIP-39 mnemonics
+- Account state recovery from on-chain events
+- Commitment and Merkle proof utilities
+- Contract interaction helpers
 - Type-safe API
 
 ## Contributing

package/dist/esm/{fetchArtifacts.esm-DbVRphob.js → fetchArtifacts.esm-B0qaot8v.js}

@@ -1,4 +1,4 @@
-import { F as FetchArtifact } from './index-DkNRxKxP.js';
+import { F as FetchArtifact } from './index-BjOXETm6.js';
 import 'viem/accounts';
 import 'buffer';
 import 'assert';
@@ -15,4 +15,4 @@ async function fetchVersionedArtifact(artifactUrl) {
 }
 
 export { fetchVersionedArtifact };
-//# sourceMappingURL=fetchArtifacts.esm-DbVRphob.js.map
+//# sourceMappingURL=fetchArtifacts.esm-B0qaot8v.js.map

package/dist/esm/{fetchArtifacts.esm-DbVRphob.js.map → fetchArtifacts.esm-B0qaot8v.js.map}

@@ -1 +1 @@
-{"version":3,"file":"fetchArtifacts.esm-DbVRphob.js","sources":["../../src/circuits/fetchArtifacts.esm.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AAEO,eAAe,sBAAsB,CAC1C,WAAgB,EAAA;AAEhB,IAAA,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC;AACpC,IAAA,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE;AACtB,QAAA,MAAM,IAAI,aAAa,CAAC,WAAW,CAAC;;AAEtC,IAAA,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,WAAW,EAAE;AACpC,IAAA,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC;AAC7B;;;;"}
+{"version":3,"file":"fetchArtifacts.esm-B0qaot8v.js","sources":["../../src/circuits/fetchArtifacts.esm.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AAEO,eAAe,sBAAsB,CAC1C,WAAgB,EAAA;AAEhB,IAAA,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC;AACpC,IAAA,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE;AACtB,QAAA,MAAM,IAAI,aAAa,CAAC,WAAW,CAAC;;AAEtC,IAAA,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,WAAW,EAAE;AACpC,IAAA,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC;AAC7B;;;;"}

package/dist/esm/{fetchArtifacts.node-D-fJGtzV.js → fetchArtifacts.node-PzijuwVc.js}

@@ -1,4 +1,4 @@
-import { F as FetchArtifact } from './index-DkNRxKxP.js';
+import { F as FetchArtifact } from './index-BjOXETm6.js';
 import 'viem/accounts';
 import 'buffer';
 import 'assert';
@@ -28,4 +28,4 @@ async function fetchVersionedArtifact(artifactUrl) {
 }
 
 export { fetchVersionedArtifact };
-//# sourceMappingURL=fetchArtifacts.node-D-fJGtzV.js.map
+//# sourceMappingURL=fetchArtifacts.node-PzijuwVc.js.map

package/dist/esm/{fetchArtifacts.node-D-fJGtzV.js.map → fetchArtifacts.node-PzijuwVc.js.map}

@@ -1 +1 @@
-{"version":3,"file":"fetchArtifacts.node-D-fJGtzV.js","sources":["../../src/circuits/fetchArtifacts.node.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AAEO,eAAe,sBAAsB,CAC1C,WAAgB,EAAA;AAEhB,IAAA,IAAI;QACF,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,IAAI,CAAC,EAAE,OAAO;QACvC,MAAM,WAAW,GAAoB,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;AACnE,YAAA,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAI;gBAC9C,IAAI,GAAG,EAAE;oBACP,MAAM,CAAC,GAAG,CAAC;;qBACN;oBACL,OAAO,CAAC,IAAI,CAAC;;AAEjB,aAAC,CAAC;AACJ,SAAC,CAAC;AACF,QAAA,MAAM,GAAG,GAAG,MAAM,WAAW;AAC7B,QAAA,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC;;IAC1B,OAAO,KAAK,EAAE;AACd,QAAA,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AACpB,QAAA,MAAM,IAAI,aAAa,CAAC,WAAW,CAAC;;AAExC;;;;"}
+{"version":3,"file":"fetchArtifacts.node-PzijuwVc.js","sources":["../../src/circuits/fetchArtifacts.node.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AAEO,eAAe,sBAAsB,CAC1C,WAAgB,EAAA;AAEhB,IAAA,IAAI;QACF,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,IAAI,CAAC,EAAE,OAAO;QACvC,MAAM,WAAW,GAAoB,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;AACnE,YAAA,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAI;gBAC9C,IAAI,GAAG,EAAE;oBACP,MAAM,CAAC,GAAG,CAAC;;qBACN;oBACL,OAAO,CAAC,IAAI,CAAC;;AAEjB,aAAC,CAAC;AACJ,SAAC,CAAC;AACF,QAAA,MAAM,GAAG,GAAG,MAAM,WAAW;AAC7B,QAAA,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC;;IAC1B,OAAO,KAAK,EAAE;AACd,QAAA,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AACpB,QAAA,MAAM,IAAI,aAAa,CAAC,WAAW,CAAC;;AAExC;;;;"}