@permissionless-technologies/upp-sdk 0.1.0 → 0.2.0

package/README.md

@@ -2,193 +2,153 @@
 
 Privacy-preserving token operations for any ERC20 token.
 
-## Features
-
-- **Multi-token support**: Shield any ERC20 into a single privacy pool
-- **Large anonymity set**: All token users share one Merkle tree
-- **Compliance-ready**: ASP-based whitelists with ragequit protection
-- **Modern stack**: Built on viem, not ethers.js
-
-## Package Structure
-
-The SDK is published as a single npm package with subpath exports:
-
-```typescript
-// Core crypto and utilities
-import { poseidon, computeSharedSecret } from '@upp/sdk/core'
-
-// Key derivation
-import { deriveKeysFromSignature } from '@upp/sdk/keys'
+**[Documentation](https://permissionless-technologies.com/docs/upp/quickstart)** | **[Learn more](https://permissionless-technologies.com/upp)**
 
-// React hooks (requires React 18+)
-import { UPPAccountProvider, useUPPAccount } from '@upp/sdk/react'
-
-// Indexer for note scanning
-import { makeRpcIndexer } from '@upp/sdk/indexer'
-```
-
-**Why not separate packages?**
-
-We considered splitting into `@upp/core`, `@upp/react`, etc. (like Kohaku), but chose a single package because:
-
-1. **Same developer experience** - Subpath exports work identically to separate packages
-2. **Tree-shaking works** - Modern bundlers only include what you import
-3. **Simpler versioning** - No cross-package dependency management
-4. **Prototype-appropriate** - Less operational overhead
+## Features
 
-The internal architecture maintains clean boundaries, so splitting later is straightforward if needed.
+- **Multi-token support** — Shield any ERC20 into a single privacy pool
+- **Large anonymity set** — All token users share one Merkle tree
+- **Compliance-ready** — Pluggable ASP (Association Set Provider) with ragequit fallback
+- **Pluggable architecture** — Bring your own account adapter, ASP provider, storage backend
+- **SNARK + STARK** — Dual proof system support (BN254 + Circle STARK)
+- **Modern stack** — Built on viem, TypeScript strict mode, ESM-first
 
 ## Installation
 
 ```bash
-npm install @upp/sdk viem
+npm install @permissionless-technologies/upp-sdk viem
 ```
 
-## Quick Start
+## Subpath Exports
 
 ```typescript
-import { createUPPClient } from '@upp/sdk'
-import { createPublicClient, createWalletClient, http } from 'viem'
-import { sepolia } from 'viem/chains'
-
-// Create viem clients
-const publicClient = createPublicClient({
-  chain: sepolia,
-  transport: http(),
-})
+// Everything
+import { ... } from '@permissionless-technologies/upp-sdk'
 
-const walletClient = createWalletClient({
-  chain: sepolia,
-  transport: http(),
-})
+// Core: notes, proofs, stealth addresses, transfers
+import { ... } from '@permissionless-technologies/upp-sdk/core'
 
-// Create UPP client
-const upp = createUPPClient({
-  publicClient,
-  walletClient,
-  poolAddress: '0x...',
-  aspHubAddress: '0x...',
-})
+// Keys: derivation, viewing keys
+import { ... } from '@permissionless-technologies/upp-sdk/keys'
 
-// Shield tokens
-const { commitment, note } = await upp.shield({
-  token: '0xUSDC...',
-  amount: 1000n * 10n ** 6n,
-})
+// React hooks (requires React 18+ and wagmi)
+import { ... } from '@permissionless-technologies/upp-sdk/react'
 
-// Transfer privately
-await upp.transfer({
-  note: myNote,
-  recipient: recipientStealthAddress,
-  amount: 500n * 10n ** 6n,
-})
+// Indexer: note scanning, storage adapters
+import { ... } from '@permissionless-technologies/upp-sdk/indexer'
 
-// Withdraw
-await upp.withdraw({
-  note: myNote,
-  amount: 500n * 10n ** 6n,
-  recipient: '0xMyAddress...',
-  aspId: 1,
-})
+// Utilities: poseidon, babyjubjub, merkle trees
+import { ... } from '@permissionless-technologies/upp-sdk/utils'
 ```
 
-## Local Development
-
-### Prerequisites
-
-- [Foundry](https://book.getfoundry.sh/getting-started/installation) for contract compilation and deployment
-- [Node.js](https://nodejs.org/) 18+
-- Local Ethereum node (Anvil recommended)
-
-### Starting a Local Node
-
-```bash
-# Start Anvil with auto-mining
-anvil
-```
-
-### Deploying Contracts
-
-The SDK includes deployment scripts and automatic address extraction:
-
-```bash
-# 1. Deploy contracts to local Anvil
-forge script src/contracts/script/DeployUPP.s.sol:DeployUPPLocal \
-  --rpc-url http://localhost:8545 \
-  --broadcast \
-  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+## Quick Start
 
-# 2. Extract addresses to SDK deployment JSON
-node scripts/extract-deployment.js 31337
+### React Application
 
-# 3. Rebuild SDK to include new addresses
-npm run build
-```
+```tsx
+import { UPPAccountProvider, useUPPAccount, useShield } from '@permissionless-technologies/upp-sdk/react'
+import { getDeployment } from '@permissionless-technologies/upp-sdk'
 
-After deployment, addresses are written to `src/deployments/31337.json`:
+const deployment = getDeployment(11155111) // Sepolia
 
-```json
-{
-  "UniversalPrivatePool": "0x2279b7a0a67db372996a5fab50d91eaa73d2ebe6",
-  "ASPRegistryHub": "0xe7f1725e7734ce288f8367e1bb143e90bb3f0512",
-  "TestToken": "0x610178da211fef7d417bc0e6fed39f05609ad788",
-  "verifiers": { ... },
-  "deployBlock": 2
+function App() {
+  return (
+    <UPPAccountProvider chainId={11155111} ethAddress={address}>
+      <ShieldForm />
+    </UPPAccountProvider>
+  )
 }
 ```
 
-### Using Deployment Addresses
-
-The SDK provides helpers to load deployment addresses:
+### Standalone (Node.js / Custom Frontend)
 
 ```typescript
-import { getDeployment, getDeploymentOrThrow } from '@upp/sdk'
+import {
+  getDeployment,
+  registerDeployment,
+  NoteStore,
+  DirectAccountAdapter,
+} from '@permissionless-technologies/upp-sdk'
+import { makeRpcIndexer, createAutoAdapter } from '@permissionless-technologies/upp-sdk/indexer'
+
+// Load deployment addresses
+const deployment = getDeployment(11155111)
+
+// Or register your own chain
+registerDeployment(8453, {
+  UniversalPrivatePool: '0x...',
+  ASPRegistryHub: '0x...',
+  verifiers: { TransferVerifier: '0x...', MergeVerifier: '0x...', WithdrawVerifier: '0x...' },
+  chainId: 8453,
+  deployBlock: 12345678,
+})
 
-// Get deployment for chain (returns null if not found)
-const deployment = getDeployment(31337)
+// Note storage (pluggable: IndexedDB, localStorage, memory, custom)
+const storage = createAutoAdapter('my-app')
+const noteStore = new NoteStore(storage)
+await noteStore.load()
+```
 
-// Or throw if not found
-const deployment = getDeploymentOrThrow(31337)
+## Architecture
 
-// Access addresses
-const poolAddress = deployment.UniversalPrivatePool
-const tokenAddress = deployment.TestToken // local dev
-// or
-const tokenAddress = deployment.USSC // production
+```
+@permissionless-technologies/upp-sdk
+├── core/         # Notes, proofs, stealth addresses, transfers
+├── keys/         # Key derivation (signature, direct, custom)
+├── react/        # React hooks (useUPPAccount, useShield, etc.)
+├── indexer/      # Note scanning + pluggable storage
+├── utils/        # Poseidon, BabyJubJub, Merkle trees
+├── contracts/    # ABIs + Solidity interfaces
+└── deployments/  # Per-chain contract addresses
 ```
 
-### TestStableToken (TST)
-
-The local deployment includes a test ERC20 token with an ETH-to-token swap:
+### Pluggable Interfaces
 
-```typescript
-// Mint TST by sending ETH (1 ETH = 3000 TST)
-await walletClient.sendTransaction({
-  to: deployment.TestToken,
-  value: parseEther('1'),
-  data: encodeFunctionData({
-    abi: USSC_ABI,
-    functionName: 'mintWithEth',
-  }),
-})
-```
+| Interface | Purpose | Built-in |
+|-----------|---------|----------|
+| `IAccountAdapter` | Key derivation source | `DirectAccountAdapter`, signature-based |
+| `IASPProvider` | Compliance layer | Optional (ragequit always available) |
+| `StorageAdapter` | Note persistence | IndexedDB, localStorage, memory |
+| `NoteStore` | Note state management | Dedup, balance, status tracking |
 
 ## Contract ABIs
 
-The SDK exports ABIs for all contracts:
-
 ```typescript
 import {
   UNIVERSAL_PRIVATE_POOL_ABI,
   ASP_REGISTRY_HUB_ABI,
-  USSC_ABI,
-} from '@upp/sdk'
+  TEST_STABLE_TOKEN_ABI,
+} from '@permissionless-technologies/upp-sdk'
+```
+
+Solidity interfaces are included for integration:
+
+```
+node_modules/@permissionless-technologies/upp-sdk/src/contracts/interfaces/
+├── IUniversalPrivatePool.sol
+├── IASPRegistry.sol
+└── IVerifiers.sol
 ```
 
-## Documentation
+## Deployments
 
-See [CLAUDE.md](./CLAUDE.md) for detailed API documentation and architecture.
+| Chain | Chain ID | Status |
+|-------|----------|--------|
+| Anvil (local) | 31337 | Built-in |
+| Sepolia | 11155111 | Built-in |
+
+Custom chains: use `registerDeployment()` at app initialization.
+
+## Local Development
+
+```bash
+npm install         # Install dependencies
+npm run build       # Build (ESM + CJS)
+npm run dev         # Watch mode
+npm test            # Run tests (176 passing)
+npm run deploy:local  # Deploy to local Anvil
+```
 
 ## License
 
-MIT
+[AGPL-3.0-or-later](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@permissionless-technologies/upp-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Universal Private Pool SDK - Privacy-preserving token operations for any ERC20",
   "type": "module",
   "main": "./dist/index.cjs",