@obelyzk/sdk 1.0.0 → 1.1.0

package/README.md

@@ -1,478 +1,502 @@
-# @bitsage/sdk
+# @obelyzk/sdk
 
-Official TypeScript SDK for the BitSage Network - Decentralized Compute with Privacy.
+Official TypeScript SDK for the **Obelysk Protocol** -- privacy-first DeFi on Starknet.
+
+All cryptography runs client-side. The SDK provides ~150 methods across 10 protocol sub-clients, covering privacy pools, dark pool auctions, stealth payments, confidential transfers, shielded swaps, UTXO vaults, OTC trading, and staking.
 
 ## Installation
 
 ```bash
-npm install @bitsage/sdk
-# or
-yarn add @bitsage/sdk
-# or
-pnpm add @bitsage/sdk
+npm install @obelyzk/sdk starknet
 ```
 
-## Features
+`starknet` (v6+) is a required peer dependency. For React hooks, also ensure `react >= 18`.
+
+## Entry Points
 
-- **Obelysk Privacy Layer** - Client-side ElGamal encryption and Schnorr proofs for private payments
-- **STWO GPU Prover** - GPU-accelerated proof generation for batch operations
-- **Confidential Swaps** - Trade tokens privately with encrypted amounts
-- **Staking & Workers** - Manage stake and worker nodes
-- **React Hooks** - Ready-to-use hooks for React applications
+| Import path | Description |
+|---|---|
+| `@obelyzk/sdk` | Main SDK (distributed compute, STWO prover, ZKML) |
+| `@obelyzk/sdk/obelysk` | Obelysk Protocol client (privacy DeFi -- this document) |
+| `@obelyzk/sdk/privacy` | ElGamal primitives, EC math, Schnorr proofs |
+| `@obelyzk/sdk/react` | React hooks for wallet, privacy, and prover state |
 
 ---
 
-## Quick Start
+## Quick Start (Read-Only)
 
-### Basic Setup
+No wallet or account needed for read-only queries:
 
 ```typescript
-import { BitSageClient } from '@bitsage/sdk';
+import { ObelyskClient } from '@obelyzk/sdk/obelysk';
 
-const client = new BitSageClient({
-  network: 'sepolia', // or 'mainnet'
-  apiKey: 'your-api-key',
+const obelysk = new ObelyskClient({
+  network: 'mainnet',
+  rpcUrl: 'https://your-rpc.com',
 });
 
-// Submit a compute job
-const job = await client.submitJob({
-  job_type: { type: 'ai_inference', model_type: 'llama-7b', batch_size: 1 },
-  input_data: btoa('Hello, BitSage!'),
-  max_cost_sage: 100n,
-  priority: 5,
-});
+// Query DarkPool epoch
+const epoch = await obelysk.darkPool.getEpochInfo();
+console.log('Epoch:', epoch.epoch, 'Phase:', epoch.phase);
 
-console.log('Job ID:', job.job_id);
-```
+// Query privacy pool stats
+const root = await obelysk.privacyPool.getMerkleRoot('eth');
+console.log('ETH pool Merkle root:', root);
 
----
+// Query staking
+const totalStaked = await obelysk.staking.getTotalStaked();
+console.log('Total SAGE staked:', totalStaked);
 
-## Obelysk Privacy Layer
+// Query OTC orderbook depth
+const depth = await obelysk.otc.getOrderbookDepth(0);
+console.log('Bids:', depth.bids.length, 'Asks:', depth.asks.length);
+```
 
-The Obelysk Privacy Layer enables fully private on-chain payments using ElGamal encryption and Schnorr zero-knowledge proofs. **All cryptography runs client-side** - no server ever sees your amounts.
+---
 
-### Private Payments
+## ObelyskClient Configuration
 
 ```typescript
-import { ObelyskPrivacy, ConfidentialSwapClient } from '@bitsage/sdk';
+import { ObelyskClient } from '@obelyzk/sdk/obelysk';
+import { Account, RpcProvider } from 'starknet';
 
-// Initialize privacy module
-const privacy = new ObelyskPrivacy();
-
-// Generate your key pair (store securely!)
-const keyPair = privacy.generateKeyPair();
-console.log('Public Key:', keyPair.publicKey);
+const provider = new RpcProvider({ nodeUrl: 'https://your-rpc.com' });
+const account = new Account(provider, '0xADDRESS', '0xPRIVATE_KEY');
 
-// Encrypt an amount (only you and recipient can see it)
-const amount = 1000n; // 1000 SAGE
-const encrypted = privacy.encrypt(amount, recipientPublicKey);
-console.log('Encrypted:', encrypted.c1, encrypted.c2);
+const obelysk = new ObelyskClient({
+  // Required
+  network: 'mainnet', // 'mainnet' | 'sepolia'
 
-// Create a proof that amount is valid (without revealing it)
-const proof = privacy.createEncryptionProof(amount, keyPair, encrypted);
+  // Recommended
+  rpcUrl: 'https://your-rpc.com', // default public RPCs have rate limits
 
-// Verify proof (anyone can do this)
-const isValid = privacy.verifyEncryptionProof(proof, keyPair.publicKey, encrypted);
-console.log('Proof valid:', isValid); // true
-```
-
-### Confidential Swaps
+  // Required for write operations
+  account, // starknet.js Account
 
-```typescript
-import { ConfidentialSwapClient } from '@bitsage/sdk';
+  // Optional: VM31 relayer (for UTXO vault operations)
+  relayerUrl: 'https://relay.bitsage.network:3080',
+  relayerApiKey: 'your-api-key',
 
-const swapClient = new ConfidentialSwapClient({
-  contractAddress: '0x...',
-  proverUrl: 'https://prover.bitsage.network',
+  // Optional: ElGamal private key (hex). If omitted, generated fresh.
+  privacyPrivateKey: '0x...',
 });
+```
 
-// Create a private order (amounts hidden on-chain)
-const order = await swapClient.createPrivateOrder({
-  giveAsset: 'SAGE',
-  wantAsset: 'USDC',
-  giveAmount: 1000n,
-  wantAmount: 100n,
-});
+All 14 mainnet contract addresses are baked into the SDK. No manual address configuration is needed.
 
-console.log('Order ID:', order.orderId);
-console.log('Encrypted amounts:', order.encryptedGive, order.encryptedWant);
-```
+---
 
-### Privacy Operations Reference
+## Sub-Clients
 
-| Operation | Privacy | Speed | Cost |
-|-----------|---------|-------|------|
-| `encrypt()` | Full | < 1ms | Free |
-| `createEncryptionProof()` | Full | ~50ms | Free |
-| `createRangeProof()` | Full | ~100ms | Free |
-| `verifyProof()` | N/A | < 10ms | Free |
-| On-chain verification | Full | N/A | ~$0.03 |
+The `ObelyskClient` exposes 10 sub-clients, each handling a specific protocol domain.
 
----
+### 1. Privacy Pool (`obelysk.privacyPool`)
 
-## STWO GPU Prover
+Deposit tokens into shielded pools using Pedersen commitments. Withdraw with nullifier + Merkle proof to break the on-chain link between depositor and recipient.
 
-For batch operations and complex computations, use the STWO GPU Prover to generate proofs efficiently.
+```typescript
+// Deposit 0.1 ETH into the privacy pool
+const { txHash, note, commitmentHash } = await obelysk.privacyPool.deposit({
+  token: 'eth',
+  amount: '0.1',
+});
+// IMPORTANT: Save `note` securely -- it is required for withdrawal.
+
+// Withdraw to a different address
+const result = await obelysk.privacyPool.withdraw({
+  note,
+  recipient: '0xRecipient...',
+  merkleProof: ['0x...', '0x...'],
+  leafIndex: 42,
+});
 
-### When to Use STWO GPU
+// Read-only queries
+const root = await obelysk.privacyPool.getMerkleRoot('eth');
+const stats = await obelysk.privacyPool.getPoolStats('eth');
+```
 
-| Scenario | Recommendation | Savings |
-|----------|---------------|---------|
-| Single payment | Client-side Schnorr | - |
-| 100+ payments | STWO GPU batch | 95% |
-| AI/ML inference | STWO GPU | Required |
-| Cross-chain bridge | STWO GPU | 98% |
-| Gaming state | STWO GPU batch | 99% |
+### 2. DarkPool (`obelysk.darkPool`)
 
-### Basic Usage
+Commit-reveal batch auction trading. Orders are committed as hashes during the commit phase, revealed during the reveal phase, and matched during settlement.
 
 ```typescript
-import { createStwoProverClient, PROOF_TYPES, GPU_TIERS } from '@bitsage/sdk';
-
-const prover = createStwoProverClient({
-  baseUrl: 'https://prover.bitsage.network',
-  apiKey: 'your-api-key',
+// Fund your DarkPool balance
+await obelysk.darkPool.deposit({ token: 'sage', amount: '10000' });
+
+// Commit an order (commit phase)
+const { orderData } = await obelysk.darkPool.commitOrder({
+  pair: 'SAGE/STRK',
+  side: 'sell',
+  price: '0.011',
+  amount: '5000',
 });
+// Save `orderData` -- needed for reveal
 
-// Submit a proof generation job
-const job = await prover.submitProofJob({
-  proofType: PROOF_TYPES.BATCH_PAYMENTS,
-  publicInputs: [/* payment data */],
-  priority: 'high',
-  gpuTier: GPU_TIERS.H100,
-});
+// Reveal the order (reveal phase)
+await obelysk.darkPool.revealOrder({ orderData });
+
+// Claim fills after settlement
+await obelysk.darkPool.claimFills({ epoch: orderData.epoch });
+
+// Read-only
+const epoch = await obelysk.darkPool.getEpochInfo();
+```
+
+### 3. Stealth Payments (`obelysk.stealth`)
 
-console.log('Job ID:', job.jobId);
-console.log('Estimated cost:', job.estimatedCostUsdc, 'USDC');
-console.log('Estimated time:', job.estimatedTimeSecs, 'seconds');
+Send tokens to one-time stealth addresses. The sender derives an ephemeral address from the receiver's stealth meta-address. Only the receiver can detect and claim the payment.
 
-// Wait for completion with progress updates
-const result = await prover.waitForProof(job.jobId, {
-  onProgress: (status) => {
-    console.log(`Progress: ${status.progressBps / 100}%`);
-    console.log(`Phase: ${status.currentPhase}`);
-  },
+```typescript
+// Send 1000 SAGE to a stealth address
+const { txHash, announcement } = await obelysk.stealth.send({
+  to: '0xReceiverAddress...',
+  token: 'sage',
+  amount: '1000',
 });
 
-console.log('Proof hash:', result.proofHash);
-console.log('Actual cost:', result.costUsdc, 'USDC');
+// Receiver: scan announcements and claim
+const announcements = await obelysk.stealth.getAnnouncements(fromBlock);
+const claimable = await obelysk.stealth.scanForPayments(announcements, viewKey);
+await obelysk.stealth.claim({ announcementIndex: 5, spendingProof, recipient: '0x...' });
 ```
 
-### Batch Operations (95-99% Cost Savings)
+### 4. Confidential Transfer (`obelysk.confidentialTransfer`)
+
+Peer-to-peer transfers where the amount is encrypted on-chain using ElGamal. Only sender and recipient can see the value.
 
 ```typescript
-// Batch 1000 payments into a single proof
-const payments = [
-  { sender: '0x...', recipient: '0x...', amount: 100n, asset: 'SAGE' },
-  // ... 999 more payments
-];
-
-const result = await prover.proveBatchPayments(payments, {
-  priority: 'high',
-  requireTee: true, // Use TEE for privacy
+// Transfer 500 SAGE with encrypted amount
+const { txHash } = await obelysk.confidentialTransfer.transfer({
+  to: '0xRecipient...',
+  recipientPublicKey: { x: 0x...n, y: 0x...n },
+  amount: '500',
+  token: 'sage',
 });
 
-// Cost: ~$0.25 instead of $30 (99% savings!)
-console.log('Batch proof hash:', result.proofHash);
+// Query encrypted balance
+const encBalance = await obelysk.confidentialTransfer.getEncryptedBalance('0xAddress...');
+
+// Decrypt locally (requires private key)
+const balance = obelysk.privacy.decrypt(encBalance, privateKey);
 ```
 
-### AI/ML Inference Proofs
+### 5. Prover Staking (`obelysk.staking`)
+
+Stake SAGE tokens to participate as a GPU prover in the network. Four tiers: Consumer, Professional, DataCenter, H100.
 
 ```typescript
-// Prove AI inference was computed correctly
-const result = await prover.proveInference(
-  'llama-7b',           // Model ID
-  [/* input tokens */], // Inputs
-  [/* output tokens */], // Outputs
-  { requireTee: true }   // Keep data private
-);
+// Stake 50,000 SAGE as a DataCenter prover
+await obelysk.staking.stake({ amount: '50000', gpuTier: 'DataCenter' });
 
-console.log('Inference proof:', result.proofHash);
+// Query staking info
+const config = await obelysk.staking.getConfig();
+const worker = await obelysk.staking.getWorkerStake('0xWorker...');
+const total = await obelysk.staking.getTotalStaked();
+
+// Unstake (after cooldown)
+await obelysk.staking.unstake();
 ```
 
-### Cross-Chain Bridge Proofs
+### 6. Privacy Router (`obelysk.router`)
+
+Read-only views into the Privacy Router contract -- private account registration, encrypted balances, nullifier tracking, and audit support.
 
 ```typescript
-// Prove a transaction occurred on another chain
-const result = await prover.proveBridge(
-  'ethereum',                    // Source chain
-  '0xabc...def',                 // Transaction hash
-  ['0x...', '0x...', '0x...'],   // Block headers
-  { priority: 'critical' }
-);
+const account = await obelysk.router.getAccount('0xAddress...');
+if (account?.registered) {
+  console.log('Public key:', account.publicKey);
+  console.log('Encrypted balance:', account.encryptedBalance);
+}
 
-console.log('Bridge proof:', result.proofHash);
+const spent = await obelysk.router.isNullifierUsed('0xNullifier...');
 ```
 
-### Recursive Proof Aggregation
+### 7. Shielded Swap (`obelysk.swap`)
+
+Privacy-preserving AMM swaps routed through Ekubo. Swaps consume a privacy pool withdrawal proof and produce a new shielded commitment.
 
 ```typescript
-// Aggregate multiple proofs into one
-const proofHashes = [
-  '0x111...',
-  '0x222...',
-  '0x333...',
-];
-
-const aggregated = await prover.aggregateProofs(proofHashes);
-console.log('Aggregated proof:', aggregated.proofHash);
-// Verify once instead of 3 times!
+// Query swap router state
+const swapCount = await obelysk.swap.getSwapCount();
+const pool = await obelysk.swap.getPool(tokenAddress);
+const fee = await obelysk.swap.getFee();
 ```
 
-### Cost Estimation
+### 8. VM31 UTXO Vault (`obelysk.vm31`)
+
+UTXO-based privacy vault using Poseidon2-M31 hashing. Transactions are submitted to the VM31 relayer, which batches and proves them on-chain.
 
 ```typescript
-// Estimate cost before submitting
-const estimate = await prover.estimateCost({
-  proofType: PROOF_TYPES.BATCH_PAYMENTS,
-  publicInputs: new Array(1000).fill(0n),
-  priority: 'high',
-  requireTee: true,
+// Deposit 0.01 BTC (denomination-safe)
+const result = await obelysk.vm31.deposit({
+  amount: 1_000_000n, // 0.01 BTC in satoshis
+  assetId: 0,         // wBTC
+  recipientPubkey: [/* M31 field elements */],
+  recipientViewingKey: [/* M31 field elements */],
 });
 
-console.log('Estimated cost:', estimate.costUsdc, 'USDC');
-console.log('Breakdown:');
-console.log('  Base:', estimate.breakdown.baseCost);
-console.log('  Priority:', estimate.breakdown.prioritySurcharge);
-console.log('  TEE:', estimate.breakdown.teeSurcharge);
-```
+// Check batch status
+const batch = await obelysk.vm31.getBatchStatus(result.batchId);
 
-### Network Metrics
+// Query on-chain state
+const root = await obelysk.vm31.getMerkleRoot();
+const noteCount = await obelysk.vm31.getNoteCount();
+const relayer = await obelysk.vm31.getRelayerInfo();
+```
 
-```typescript
-// Check network status
-const metrics = await prover.getMetrics();
+### 9. VM31 Bridge (`obelysk.bridge`)
 
-console.log('Available GPUs:');
-for (const gpu of metrics.availableGpus) {
-  console.log(`  ${gpu.tier}: ${gpu.count} (${gpu.teeEnabled} TEE)`);
-}
+Bridge between the VM31 UTXO pool and ElGamal-based ConfidentialTransfer system.
 
-console.log('Queue depth:', metrics.queueDepth);
-console.log('Avg wait time:', metrics.avgWaitTimeSecs, 'seconds');
-console.log('Utilization:', metrics.networkUtilization * 100, '%');
+```typescript
+const config = await obelysk.bridge.getConfig();
+const assetPair = await obelysk.bridge.getAssetPair(0); // wBTC mapping
+const relayer = await obelysk.bridge.getRelayer();
 ```
 
----
-
-## Full Privacy Client
+### 10. OTC Orderbook (`obelysk.otc`)
 
-For advanced privacy operations including steganographic transactions, ring signatures, and threshold decryption.
+On-chain limit and market order book for peer-to-peer token trading.
 
 ```typescript
-import { createPrivacyClient } from '@bitsage/sdk';
-
-const privacy = createPrivacyClient({
-  contractAddress: '0x...',
-  httpUrl: 'https://api.bitsage.network',
+import { OrderSide, OrderType } from '@obelyzk/sdk/obelysk';
+
+// Place a limit order
+const orderId = await obelysk.otc.placeLimitOrder({
+  pairId: 0,
+  side: OrderSide.Buy,
+  price: 11_000_000_000_000_000n, // 0.011 in 18-decimal
+  amount: 5000_000_000_000_000_000_000n,
 });
 
-// Register a private account
-const account = await privacy.registerAccount(keyPair);
-
-// Private transfer
-const tx = await privacy.privateTransfer({
-  recipientPublicKey: recipient.publicKey,
-  amount: 500n,
-  asset: 'SAGE',
+// Place a market order
+await obelysk.otc.placeMarketOrder({
+  pairId: 0,
+  side: OrderSide.Sell,
+  amount: 1000_000_000_000_000_000_000n,
 });
 
-// Check encrypted balance
-const balance = await privacy.getEncryptedBalance(myAddress, 'SAGE');
+// Query orderbook
+const depth = await obelysk.otc.getOrderbookDepth(0);
+const stats = await obelysk.otc.get24hStats(0);
+const order = await obelysk.otc.getOrder(orderId);
+const trades = await obelysk.otc.getRecentTrades(0);
 
-// Reveal balance (client-side decryption)
-const revealed = await privacy.revealBalance(keyPair, 'SAGE');
-console.log('My SAGE balance:', revealed);
+// Cancel
+await obelysk.otc.cancelOrder(orderId);
 ```
 
 ---
 
-## React Hooks
+## ElGamal Privacy Primitives
+
+Available from both `@obelyzk/sdk/privacy` and `@obelyzk/sdk/obelysk`.
 
 ```typescript
-import { useBitSage, usePrivacy, useStwoProver } from '@bitsage/sdk/react';
+import { ObelyskPrivacy } from '@obelyzk/sdk/privacy';
 
-function App() {
-  const { client, isConnected } = useBitSage();
-  const { privacy, keyPair, generateKeyPair } = usePrivacy();
-  const { prover, submitJob, status } = useStwoProver();
+const privacy = new ObelyskPrivacy();
 
-  return (
-    <div>
-      <button onClick={generateKeyPair}>Generate Keys</button>
-      <button onClick={() => submitJob({ ... })}>Submit Proof</button>
-      {status && <p>Progress: {status.progressBps / 100}%</p>}
-    </div>
-  );
-}
+// Generate a key pair
+const keyPair = privacy.generateKeyPair();
+console.log('Public key:', keyPair.publicKey); // ECPoint { x, y }
+
+// Encrypt an amount (only the private key holder can decrypt)
+const ciphertext = privacy.encrypt(1_000_000n, keyPair.publicKey);
+// ciphertext = { c1: ECPoint, c2: ECPoint }
+
+// Decrypt
+const amount = privacy.decrypt(ciphertext, keyPair.privateKey);
+console.log(amount); // 1000000n
+
+// Homomorphic addition (add encrypted values without decrypting)
+const ct1 = privacy.encrypt(100n, keyPair.publicKey);
+const ct2 = privacy.encrypt(200n, keyPair.publicKey);
+const ctSum = privacy.homomorphicAdd(ct1, ct2);
+const sum = privacy.decrypt(ctSum, keyPair.privateKey);
+console.log(sum); // 300n
+
+// Schnorr proof of correct encryption
+const proof = privacy.createEncryptionProof(1_000_000n, keyPair, ciphertext);
+const valid = privacy.verifyEncryptionProof(proof, keyPair.publicKey, ciphertext);
 ```
 
----
-
-## Contract Registry
+### Low-Level Crypto Functions
 
 ```typescript
 import {
-  SEPOLIA_CONTRACTS,
-  MAINNET_CONTRACTS,
-  getContractsForNetwork
-} from '@bitsage/sdk';
-
-// Get contracts for a network
-const contracts = getContractsForNetwork('sepolia');
-
-console.log('SAGE Token:', contracts.sageToken);
-console.log('Confidential Swap:', contracts.confidentialSwap);
-console.log('Privacy Router:', contracts.privacyRouter);
-console.log('STWO Verifier:', contracts.stwoVerifier);
+  elgamalEncrypt,
+  pedersenCommit,
+  createEncryptionProof,
+  createAEHint,
+  commitmentToHash,
+  deriveNullifier,
+  randomScalar,
+  ecAdd,
+  ecMul,
+  mod,
+  modInverse,
+  FIELD_PRIME,
+  CURVE_ORDER,
+  GENERATOR_G,
+  GENERATOR_H,
+} from '@obelyzk/sdk/obelysk';
+
+// Pedersen commitment: C = value * G + blinding * H
+const blinding = randomScalar();
+const commitment = pedersenCommit(1000n, blinding);
+
+// ElGamal encrypt: (r*G, amount*H + r*PK)
+const { c1, c2, randomness } = elgamalEncrypt(500n, publicKey);
+
+// Schnorr proof of knowledge of r
+const proof = createEncryptionProof(randomness, c1);
+
+// AE hint for O(1) decryption
+const { encryptedAmount, mac } = createAEHint(500n, sharedSecret);
+
+// Nullifier derivation (Poseidon hash)
+const nullifier = deriveNullifier(nullifierSecret, commitmentToHash(commitment));
 ```
 
 ---
 
-## Architecture
+## ECIES Encryption
 
+ECIES (X25519 + HKDF-SHA256 + AES-256-GCM) is used to encrypt transaction payloads for the VM31 relayer. Compatible with the Rust relayer (`x25519-dalek` + `aes-gcm` + `hkdf`).
+
+```typescript
+import { eciesEncrypt } from '@obelyzk/sdk/obelysk';
+import type { ECIESEnvelope } from '@obelyzk/sdk/obelysk';
+
+const envelope: ECIESEnvelope = await eciesEncrypt(
+  { action: 'deposit', amount: '1000000', assetId: 0 },
+  relayerPublicKeyHex, // 64-char hex X25519 public key
+);
+
+// POST the envelope to the relayer
+const response = await fetch('https://relay.bitsage.network:3080/submit', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(envelope),
+});
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                              @bitsage/sdk                                   │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│   OBELYSK PRIVACY (Client-Side)         STWO GPU PROVER (Server-Side)      │
-│   ─────────────────────────────         ──────────────────────────────     │
-│   • ElGamal encryption                  • Batch proof generation           │
-│   • Schnorr proofs                      • GPU acceleration (H100/H200)     │
-│   • Range proofs                        • TEE privacy (optional)           │
-│   • Confidential swaps                  • Recursive aggregation            │
-│                                                                             │
-│   import { ObelyskPrivacy }             import { createStwoProverClient }  │
-│                                                                             │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│                              STARKNET L2                                    │
-│                     • Proof verification                                    │
-│                     • Encrypted balances                                    │
-│                     • Atomic swaps                                          │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+
+Requires Web Crypto API (Node 20+ or any modern browser).
 
 ---
 
-## API Reference
-
-### ObelyskPrivacy
-
-| Method | Description |
-|--------|-------------|
-| `generateKeyPair()` | Generate ElGamal key pair |
-| `encrypt(amount, publicKey)` | Encrypt amount |
-| `decrypt(ciphertext, privateKey)` | Decrypt ciphertext |
-| `homomorphicAdd(c1, c2)` | Add encrypted values |
-| `createEncryptionProof()` | Create Schnorr proof |
-| `verifyEncryptionProof()` | Verify proof |
-
-### StwoProverClient
-
-| Method | Description |
-|--------|-------------|
-| `submitProofJob(request)` | Submit proof generation job |
-| `getJobStatus(jobId)` | Get job status |
-| `waitForProof(jobId)` | Wait for completion |
-| `cancelJob(jobId)` | Cancel pending job |
-| `submitBatch(request)` | Submit batch of proofs |
-| `estimateCost(request)` | Estimate proof cost |
-| `getMetrics()` | Get network metrics |
-| `proveBatchPayments()` | Helper for batch payments |
-| `proveInference()` | Helper for AI inference |
-| `proveBridge()` | Helper for bridge proofs |
-| `aggregateProofs()` | Recursive aggregation |
-| `loadZkmlModel(req)` | Load ONNX model on prover server |
-| `submitZkmlProve(req)` | Submit ZKML proving job |
-| `getZkmlProveStatus(jobId)` | Get ZKML job progress |
-| `getZkmlProveResult(jobId)` | Get proof calldata + commitments |
-| `proveZkml(req, opts?)` | Full prove pipeline with progress callback |
-
-### StwoClient (On-Chain Verification)
-
-| Method | Description |
-|--------|-------------|
-| `submitProof(data, hash)` | Submit proof for verification |
-| `verifyProof(hash)` | Verify proof via contract |
-| `submitGpuTeeProof(params)` | Submit GPU-TEE optimistic proof |
-| `registerZkmlModel(id, commitment)` | Register model on verifier contract |
-| `verifyZkmlModel(id, calldata)` | Verify ML model proof on-chain |
-| `isZkmlProofVerified(hash)` | Check if proof is verified |
-| `getZkmlVerificationCount(id)` | Get verification count for model |
-| `getZkmlModelCommitment(id)` | Get registered weight commitment |
-| `proveAndVerifyOnChain(prover, req)` | End-to-end: prove via API + verify on-chain |
+## Denomination Validation
 
----
+Privacy pool and VM31 vault deposits must use standard denominations to prevent exact-amount correlation attacks. The SDK enforces this client-side.
 
-## ZKML Proving
+```typescript
+import {
+  validateDenomination,
+  splitIntoDenominations,
+  getDenominations,
+  ETH_DENOMINATIONS,
+} from '@obelyzk/sdk/obelysk';
+
+// Validate a deposit amount
+validateDenomination(10_000_000_000_000_000n, 'eth'); // 0.01 ETH -- OK
+validateDenomination(12_345_678n, 'eth');              // throws Error
+
+// Auto-split an arbitrary amount into denomination-safe batches
+const { denominations, remainder } = splitIntoDenominations(
+  350_000_000_000_000_000n, // 0.35 ETH
+  'eth',
+);
+// denominations = [0.1 ETH, 0.1 ETH, 0.1 ETH, 0.05 ETH]
+// remainder = 0n
 
-End-to-end ML inference proving and on-chain verification.
+// List valid denominations for an asset
+const denoms = getDenominations('usdc');
+// [1 USDC, 5 USDC, 10 USDC, 50 USDC, 100 USDC, 500 USDC]
+```
 
-### Prove a Model
+Supported tokens: wBTC, SAGE, ETH, STRK, USDC. Unknown assets pass through without restriction.
 
-```typescript
-import { createStwoProverClient } from '@bitsage/sdk';
+---
 
-const prover = createStwoProverClient({
-  baseUrl: 'http://your-gpu-server:8080',
-});
+## Contract Addresses
 
-// Load an ONNX model
-const model = await prover.loadZkmlModel({
-  modelPath: '/path/to/model.onnx',
-  description: 'Qwen3-14B block 0',
-});
-console.log('Model ID:', model.modelId);
-console.log('Weight commitment:', model.weightCommitment);
-
-// Prove with progress tracking
-const result = await prover.proveZkml(
-  { modelId: model.modelId, gpu: true },
-  {
-    onProgress: (status) => {
-      console.log(`${(status.progressBps / 100).toFixed(1)}% — ${status.elapsedSecs.toFixed(1)}s`);
-    },
-    pollIntervalMs: 2000,
-    timeoutMs: 300_000,
-  }
-);
+All mainnet and Sepolia addresses are available programmatically:
 
-console.log('Calldata:', result.calldataLength, 'felts');
-console.log('Gas estimate:', result.estimatedGas);
-console.log('Prove time:', (result.proveTimeMs / 1000).toFixed(1), 's');
+```typescript
+import {
+  getContracts,
+  getRpcUrl,
+  MAINNET_TOKENS,
+  MAINNET_PRIVACY_POOLS,
+  TOKEN_DECIMALS,
+  DARKPOOL_ASSET_IDS,
+  VM31_ASSET_IDS,
+  parseAmount,
+  formatAmount,
+} from '@obelyzk/sdk/obelysk';
+
+const contracts = getContracts('mainnet');
+console.log('SAGE Token:', contracts.sage_token);
+console.log('DarkPool:', contracts.dark_pool);
+console.log('VM31 Pool:', contracts.vm31_pool);
+
+// Token utilities
+const wei = parseAmount('1.5', 'eth');   // 1500000000000000000n
+const str = formatAmount(wei, 'eth');     // "1.5"
 ```
 
-### Verify On-Chain
+### Mainnet Contracts (14 total)
+
+| Contract | Address |
+|---|---|
+| SAGE Token | `0x0098d563...931c799` |
+| ConfidentialTransfer | `0x0673685b...a979d2` |
+| PrivacyRouter | `0x00f3fd87...bfbdfbd` |
+| ProverStaking | `0x07d2ecff...293e3` |
+| DarkPool | `0x0230b582...ea7727` |
+| ShieldedSwap | `0x05a7f8a6...29725b` |
+| StealthRegistry | `0x077ee4c3...fcaea8` |
+| OTC Orderbook | `0x04165f8f...941b19` |
+| SumcheckVerifier | `0x05071a94...d330e8` |
+| VM31Pool | `0x0230eb35...1400d` |
+| VM31Bridge | `0x048f481c...0356c` |
+| PrivacyPool (wBTC) | `0x030fcfd4...d5e5e2` |
+| PrivacyPool (SAGE) | `0x0224977...ac724f` |
+| PrivacyPool (ETH) | `0x06d0b41c...e82b5` |
+| PrivacyPool (STRK) | `0x02c348e8...c9cf1` |
+| PrivacyPool (USDC) | `0x05d36d7f...d4d59b` |
 
-```typescript
-import { createStwoClient } from '@bitsage/sdk';
+---
 
-const verifier = createStwoClient({ /* ... */ });
+## React Hooks
 
-// Set verifier contract (default: deployed v3 on Sepolia)
-verifier.setZkmlVerifier('0x048070fbd531a0192f3d4a37eb019ae3174600cae15e08c737982fae5d929160');
+```typescript
+import { useBitSage, usePrivacy, useStwoProver } from '@obelyzk/sdk/react';
 
-// Register model
-await verifier.registerZkmlModel(model.modelId, model.weightCommitment);
+function App() {
+  const { client, isConnected } = useBitSage();
+  const { privacy, keyPair, generateKeyPair } = usePrivacy();
+  const { prover, submitJob, status } = useStwoProver();
 
-// Check verification status
-const count = await verifier.getZkmlVerificationCount(model.modelId);
-console.log('Verified', count, 'times');
+  return (
+    <div>
+      <p>Connected: {String(isConnected)}</p>
+      <button onClick={generateKeyPair}>Generate Keys</button>
+    </div>
+  );
+}
 ```
 
-### Full Pipeline
+Requires `react >= 18` as a peer dependency (optional -- only needed if you use this entry point).
 
-```typescript
-// Prove on GPU server + verify on Starknet in one call
-const tx = await verifier.proveAndVerifyOnChain(prover, {
-  modelId: model.modelId,
-  gpu: true,
-});
-console.log('Transaction hash:', tx);
-```
+---
+
+## Requirements
+
+- Node.js >= 18
+- `starknet` >= 6.0.0
+- TypeScript >= 5.0 (recommended)
 
 ---